ndbm(3) — Subroutines
NAME
dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_forder, dbm_error, dbm_clearerr − Database subroutines
SYNOPSIS
#include <ndbm.h> typedef struct {
char ∗dptr;
int dsize;
} datum; DBM ∗dbm_open(
char ∗file,
int flags,
int mode ); void dbm_close(
DBM ∗db ); datum dbm_fetch(
DBM ∗db,
datum key ); int dbm_store(
DBM ∗db,
datum key,
datum content,
int flags ); int dbm_delete(
DBM ∗db,
datum key ); datum dbm_firstkey(
DBM ∗db ); datum dbm_nextkey(
DBM ∗db ); long dbm_forder(
DBM ∗db,
datum key ); int dbm_error(
DBM ∗db ); int dbm_clearerr(
DBM ∗db );
PARAMETERS
dbSpecifies the database.
fileSpecifies 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() manual page for further details.
modeSpecifies the read, write, and execute permissions of the file to be created (requested by the O_CREAT flag). 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() manual page for further details.
flagsSpecifies one of the following flags for opening:
DBM_INSERT
Only insert new entries into the database. Do not change an existing entry with the same key.
DBM_REPLACE
Replace an existing entry if it has the same key.
keySpecifies the key.
contentSpecifies a value associated with key.
DESCRIPTION
The dbm_open(), dbm_close(), dbm_fetch(), dbm_store(), dbm_delete(), dbm_firstkey(), dbm_nextkey(), dbm_forder(), 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 .dir as its suffix. The second file contains all data and has .pag 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.
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. A key (and its associated contents) is deleted by the dbm_delete() function. A linear pass through all keys in a database may be made, in an (apparently) random order, by use of the dbm_firstkey() and dbm_nextkey() functions. 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_error() function returns a nonzero value when an error has occurred reading or writing the database. The dbm_clearerr() function resets the error condition on the named database.
The dbm_forder() function returns the block number in the .pag file that the specified key will map to.
RETURN VALUES
Upon successful completion, all functions that return an int return a value of 0 (zero). Otherwise, a negative value is returned. Routines that return a datum indicate errors with a null (0) dptr. If the dbm_store() function is called with a flags value of DBM_INSERT, and finds an existing entry with the same key, it returns 1.
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:
[ENOMEM]Insufficient space to allocate a buffer.
[EPERM]An attempt was made to store or delete a key (and its associated contents) in a database that was opened read-only.
[ENOSPC]An attempt was made to store a key (and its associated contents) whose size exceeds the page block size limit as defined by PBLKSIZE in /usr/include/ndbm.h.