ndbm(3)

NAME

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error,

dbm_fetch,
dbm_firstkey, dbm_nextkey, dbm_open, dbm_pagfno, dbm_store

database
access methods

SYNOPSIS

#include <ndbm.h>
int
dbm_clearerr(DBM *db);
void
dbm_close(DBM *db);
int
dbm_delete(DBM *db, datum key);
int
dbm_dirfno(DBM *db);
int
dbm_error(DBM *db);
datum
dbm_fetch(DBM *db, datum key);
datum
dbm_firstkey(DBM *db);
datum
dbm_nextkey(DBM *db);
DBM *
dbm_open(const char *file, int flags, int mode);
int
dbm_pagfno(DBM *db);
int
dbm_store(DBM   *db,   datum   key,   datum   content,   int
store_mode);

DESCRIPTION

These functions provide a ndbm-compatible interface to the

database
access methods described in db(3). Each unique record in

the database is
a key/content pair, the components of which may be any arbi

trary binary
data. The key and the content data are described by the

datum data
structure:

typedef struct {

char *dptr;
int dsize;

} datum

The dbm_open() function is used to open a database in the

file named by
file, suffixed with DBM_SUFFIX (`.db'). If necessary, the

file is cre
ated with mode mode. Access to this file depends on the

flags parameter
(see open(2)). Read-only access may be indicated by speci

fying
DBM_RDONLY.

Once the database is open, dbm_fetch() is used to retrieve

the data con
tent associated with the key key. Similarly, dbm_store() is

used to
store the content data with the key key. When storing, the

store_mode
parameter must be one of:

DBM_INSERT Only insert new keys into the database.

Existing

key/content pairs are untouched.

DBM_REPLACE Replace any existing entry with the same

key. Any

previously stored records with the same

key are lost.

The dbm_delete() function removes the key key and its asso

ciated content
from the database.

The functions dbm_firstkey() and dbm_nextkey() are used to

iterate over
all of the records in the database. Each record will be

reached exactly
once, but in no particular order. The dbm_firstkey() func

tion returns
the first record of the database, and thereafter

dbm_nextkey() returns
the following records. The following code traverses the en

tire database:

for (key = dbm_firstkey(db); key.dptr != NULL; key =

dbm_nextkey(db))

The behaviour of dbm_nextkey() is undefined if the database

is modified
after a call to dbm_firstkey().

The dbm_error() function returns the last error condition of

the
database, or 0 if no error had occurred or had been cleared.

The
dbm_clearerr() function clears the error condition of the

database.

The dbm_dirfno() function is used to find the file descrip

tor associated
with the directory file of an open database. Since a direc

tory bitmap
file is not used in this implementation, this function re

turns the file
descriptor of the database file opened with dbm_open().

The dbm_pagfno() function is used to find the file descrip

tor associated
with the page file of an open database. Since a page file

is not used in
this implementation, this function is implemented as a macro

that always
returns the (undefined) value DBM_PAGFNO_NOT_AVAILABLE.

The database is closed with the dbm_close() function.

Thereafter, the db
handle is invalid.

Implementation notes

The underlying database is a hash(3) database with a bucket

size of 4096,
a filling factor of 40, default hashing function and cache

size, and uses
the host's native byte order.

RETURN VALUES

Upon successful completion, all functions that return int

return a value
of 0, otherwise a negative value is returned.

Routines that return a datum indicate errors by setting the

dptr field to
NULL.

The dbm_open() function returns NULL on error, and sets

errno appropri
ately. On success, it returns a handle to the database that

should be
used as the db argument in the other functions.

The dbm_store() function returns 1 when it is called with a

flags value
of DBM_INSERT and a record with the specified key already

exists.

ERRORS

If an error occurs, the error can be retrieved with

dbm_error() and cor
responds to those errors described in db(3).

SEE ALSO

open(2), db(3), hash(3)

BSD May 13, 1998

BSD