HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/nan.3m
________________________________________________________________
___ ___
n
ndbm(3X) ndbm(3X)
NAME
dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error,
dbm_clearerr - database subroutines
SYNOPSIS
#include <ndbm.h>
DBM *dbm_open(const char *file, int flags, mode_t 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);
int dbm_error(DBM *db);
int dbm_clearerr(DBM *db);
DESCRIPTION
These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block =
1024 bytes)) databasesand can access a keyed item in one or two file system accesses.
key and content parameters are described by the datum type. A datum specifies a string of dsize bytes
pointed to by dptr. 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 of keys 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 dbm_open. This will open and/or create the files
file.dir and file.pag depending on the flags parameter (see open(2)).
Once open, the data stored under a key is accessed by
dbm_fetch and data is placed under a key by
dbm_store. The flags field can be either DBM_INSERT or DBM_REPLACE . DBM_INSERT can only
insert new entries into the database, and cannot change an existing entry having the same key.
DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is
deleted by dbm_delete . A linear pass through all keys in a database can be made in (apparently) ran-
dom order by use of dbm_firstkey and dbm_nextkey. dbm_firstkey returns the first key in
the database. dbm_nextkey returns the next key in the database, The following code can be used to
traverse the database:
for (key = dbm_firstkey(db); key.dptr != NULL; key =
dbm_nextkey(db))
dbm_error
returns non-zero when an error has occurred reading or writing the database.
dbm_clearerr resets the error condition on the named database.
DIAGNOSTICS
All functions that return an int indicate errors with negative values and success with zero. Functions
that return a datum indicate errors with a null dptr.Ifdbm_store is called with a flags value of
DBM_INSERT and finds an existing entry with the same key, a value of 1 is returned. If a call to
dbm_store results in an internal block overflow, a value of −2 is returned.
APPLICATION USAGE
The interfaces
dbm_open(), dbm_close() , dbm_fetch() , dbm_store() , dbm_delete() ,
dbm_firstkey(), dbm_nextkey(), dbm_error() and dbm_clearerr are thread-safe. These
interfaces are not async-cancel-safe. A cancellation point may occur when a thread is executing
dbm_open(), dbm_close() , dbm_fetch() , dbm_store() , dbm_delete() ,
dbm_firstkey(), dbm_nextkey() or dbm_error() .
WARNINGS
The ndbm functions provided in this library should not be confused in any way with those of a general-
purpose database management system. These functions do not provide for multiple search keys per entry,
they do not protect against multi-user access (in other words they do not lock records or files), and they do
HP-UX Release 11i: December 2000 − 1 − Section 3−−539
___
___