NDBM(3) OpenBSD Programmer's Manual NDBM(3)
NAME
ndbm - 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 ac-
cess methods described in db(3). Each unique record in the database is a
key/content pair, the components of which may be any arbitrary binary da-
ta. The key and the content data are described by the datum data struc-
ture:
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 created
with mode mode. Access to this file depends on the flags parameter (see
open(2)). Read-only access may be indicated by specifying DBM_READONLY.
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 pre-
viously stored records with the same key are lost.
The dbm_delete() function removes the key key and its associated 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() function returns
the first record of the database, and thereafter dbm_nextkey() returns
the following records. The following code traverses the entire 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 descriptor associated
with the directory file of an open database. Since a directory bitmap
file is not used in this implementation, this function returns the file
descriptor of the datbase file opened with dbm_open().
The dbm_pagfno() function is used to find the file descriptor 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
OpenBSD 2.6 May 13, 1998 2
www.fiveanddime.net
|