ndbm.3x (2010 09)

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)) databases and 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.
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 not provide the many other useful database functions that are found in more robust database
management systems. Creating and updating databases by use of these functions is relatively slow
because of data copies that occur upon hash collisions. These functions are useful for applications requir-
ing fast lookup of relatively static information that is to be indexed by a single key.
The pointer to data that is returned from these functions are not aligned. This can cause problems if the
block contains data that must be aligned to a specific boundry. If the block contains data that must be
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1