ndbm(3)ndbm(3)NAME
ndbm, dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch,
dbm_firstkey, dbm_forder, dbm_nextkey, dbm_open, dbm_setpblksiz,
dbm_store - Database subroutines
SYNOPSIS
#include <ndbm.h>
typedef struct {
void *dptr
size_t dsize
} datum;
int dbm_clearerr(
DBM *db ); void dbm_close(
DBM *db ); int dbm_delete(
DBM *db,
datum key ); int dbm_error(
DBM *db ); datum dbm_fetch(
DBM *db,
datum key ); datum dbm_firstkey(
DBM *db ); long dbm_forder(
DBM *db,
datum key ); datum dbm_nextkey(
DBM *db ); DBM *dbm_open(
const char *file,
int flags,
mode_t mode ); int dbm_setpblksiz(
DBM *db,
int size ); int dbm_store(
DBM *db,
datum key,
datum content,
int store_mode );
The following declarations do not conform to current standards and are
supported only for backward compatibility: typedef struct{
char *dptr
int dsize
} datum;
DBM *dbm_open(
char *file,
int flags,
int mode );
STANDARDS
Interfaces documented by this reference page conform to industry stan‐
dards as follows:
dbm_clearerr(), dbm_close(), dbm_delete(), dbm_error(), dbm_fetch(),
dbm_firstkey(), dbm_nextkey(), dbm_open(), dbm_store(): XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies a value associated with key. Points to a database structure
that has been returned from a call to the dbm_open() function. Speci‐
fies the file to be opened. If the file parameter refers to a symbolic
link, the dbm_open() function opens the file pointed to by the symbolic
link. See the open(2) reference page for further details. Specifies
the type of access, special open processing, the type of update, and
the initial state of the open file. The parameter value is constructed
by logically ORing special processing options described in the fcntl.h
header file. See the open(2) reference page for further details. A
datum that has been initialized by the application program to the value
of the key that identifies the record that the program is handling.
Specifies the read, write, and execute permissions of the file to be
created (requested by the O_CREAT option). If the file already exists,
this parameter is ignored. This parameter is constructed by logically
ORing values described in the sys/mode.h header file. See the open(2)
reference page for further details. The new page file block size set
by dbm_setpblksiz(). This function forces values to a minimum setting
of 1024 bytes and a maximum setting of 32,768 bytes. It also rounds
values up to a multiple of 1024. Specifies one of the following
options to dbm_store(): Only insert new entries into the database. Do
not change an existing entry with the same key. Replace an existing
entry if it has the same key.
DESCRIPTION
The dbm_open(), dbm_close(), dbm_fetch(), dbm_store(), dbm_delete(),
dbm_firstkey(), dbm_nextkey(), dbm_forder(), dbm_setpblksiz(),
dbm_error(), and dbm_clearerr() functions maintain key/content pairs in
a database. The functions handle very large databases (a billion
blocks) and access a keyed item in one or two file system accesses.
Arbitrary binary data, as well as normal ASCII strings, are allowed.
The database is stored in two files. One file is a directory containing
a bit map and has as its suffix. The second file contains all data and
has as its suffix.
Before a database can be accessed, it must be opened by the dbm_open()
function. The dbm_open() function opens (and if necessary, creates) the
file.dir and file.pag files, depending on the flags parameter. The
flags parameter has the same meaning as the oflags parameter of open()
except that a database opened for write-only access opens the files for
read and write access.
Once open, the data stored under a key is accessed by the dbm_fetch()
function and data is placed under a key by the dbm_store() function.
The store_mode parameter controls whether dbm_store() replaces any pre‐
existing record whose key matches the key specified by the key parame‐
ter.
The dbm_delete() function deletes a record and its key from the data‐
base.
The dbm_firstkey() and dbm_nextkey() functions can be used to make a
linear pass through all keys in a database, in an (apparently) random
order. The dbm_firstkey() function returns the first key in the data‐
base. The dbm_nextkey() function returns the next key in the database.
The order of keys presented by the dbm_firstkey() and dbm_nextkey()
functions depends on a hashing function.
The following code traverses the database:
for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
The dbm_setpblksiz() function sets the page file block size, which is
1024 bytes by default. This function should only be called immediately
after a call to dbm_open() and prior to calls to other ndbm functions.
For an existing database, dbm_open() automatically sets the page file
block size to the size set at the time of its creation.
The dbm_error() function returns the error condition of the database.
The dbm_clearerr() function clears the error condition of the database.
[Tru64 UNIX] The dbm_forder() function returns the block number in the
file to which the specified key maps.
NOTES
[Tru64 UNIX] When compiled in the X/Open UNIX environment, calls to
the dbm_delete(), dbm_fetch(), dbm_firstkey(), dbm_forder(), dbm_nex‐
tkey(), and dbm_store() functions are internally renamed by prepending
_E to the function name. When you are debugging a module that includes
any of these functions and for which _XOPEN_SOURCE_EXTENDED has been
defined, use _Ename to refer to the name() call. For example, use
_Edbm_delete to refer to the dbm_delete() call. See standards(5) for
further information.
When using key structures containing gaps, make sure that the whole
structure, including gaps, is initialized to a known value; otherwise,
the keys may not match.
RETURN VALUES
Upon successful completion, all functions that return an int return a
value of 0 (zero). Otherwise, a negative value is returned.
Functions that return a datum indicate errors with a null (0) dptr.
The dbm_store() function returns 1 if it is called with a flags value
of DBM_INSERT and the function finds an existing entry with the same
key.
ERRORS
If any of the following conditions occurs, the dbm_open(),
dbm_delete(), and dbm_store() functions set errno to the value that
corresponds to the condition: [Tru64 UNIX] Insufficient space to allo‐
cate a buffer. [Tru64 UNIX] An attempt was made to store or delete a
key (and its associated contents) in a database that was opened read-
only. [Tru64 UNIX] An attempt was made to store a key whose size
exceeds the page block size limit as defined by PBLKSIZ in
/usr/include/ndbm.h or a key whose size plus the size of its associated
contents exceeds the page block size limit set by dbm_setpblksiz().
SEE ALSO
Functions: dbm(3), open(2)
Standards: standards(5)ndbm(3)