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
#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 );
Interfaces documented by this reference page conform to
industry standards 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.
Specifies a value associated with key. Points to a
database structure that has been returned from a call to
the dbm_open() function. Specifies 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.
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 preexisting record whose
key matches the key specified by the key parameter.
The dbm_delete() function deletes a record and its key
from the database.
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 database. 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.
[Tru64 UNIX] When compiled in the X/Open UNIX environment,
calls to the dbm_delete(), dbm_fetch(),
dbm_firstkey(), dbm_forder(), dbm_nextkey(), 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.
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.
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 allocate 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().
Functions: dbm(3), open(2)
Standards: standards(5)
ndbm(3)
[ Back ] |
