 |
Index for
Section 3 |
|
 |
Alphabetical
listing for N |
|
 |
Bottom of
page |
|
ndbm(3)
NAME
dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey,
dbm_forder, dbm_nextkey, dbm_open, dbm_setpblksiz, dbm_store - Database
subroutines
SYNOPSIS
#include <ndbm.h>
typedef struct {
void *dptr;
size_t dsize;
} datum;
int dbm_clearerr(
DBM *db);
void dbm_close(
DBM *db);
int dbm_delete(
DBM *db,
datum key);
int dbm_error(
DBM *db);
datum dbm_fetch(
DBM *db,
datum key);
datum dbm_firstkey(
DBM *db);
long dbm_forder(
DBM *db,
datum key);
datum dbm_nextkey(
DBM *db);
DBM *dbm_open(
const char *file,
int flags,
mode_t mode);
int dbm_setpblksiz(
DBM *db,
int size);
int dbm_store(
DBM *db,
datum key,
datum content,
int store_mode );
The following declarations do not conform to current standards and are
supported only for backward compatibility:
typedef struct {
char *dptr;
int dsize;
} datum;
DBM *dbm_open(
char *file,
int flags,
int mode );
STANDARDS
Interfaces documented by this reference page conform to industry standards
as follows:
dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey,
dbm_nextkey, dbm_open, dbm_store: XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
content Specifies a value associated with key.
db Points to a database structure that has been returned from a call
to the dbm_open() function.
file Specifies 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(2) reference page for
further details.
flags Specifies the type of access, special open processing, the type
of update, and the initial state of the open file. The parameter
value is constructed by logically ORing special processing flags
described in the fcntl.h header file. See the open(2) reference
page for further details.
key A datum that has been initialized by the application program to
the value of the key that identifies the record that the program
is handling.
mode Specifies 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(2) reference page for further details.
size The new page file block size set by dbm_setpblksiz(). This
function forces values to a minimum setting of 1024 bytes and a
maximum setting of 32,768 bytes. It also rounds values up to a
multiple of 1024.
store_mode
Specifies one of the following flags to dbm_store():
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.
DESCRIPTION
The dbm_open(), dbm_close(), dbm_fetch(), dbm_store(), dbm_delete(),
dbm_firstkey(), dbm_nextkey(), dbm_forder(), dbm_setpblksiz(), 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. The flags
parameter has the same meaning as the oflag parameter of open() except that
a database opened for write-only access opens the files for read and write
access.
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. The
store_mode parameter controls whether dbm_store() replaces any preexisting
record whose key matches the key specified by the key parameter.
The dbm_delete() function deletes a record and its key from the database.
The dbm_firstkey() and dbm_nextkey() functions can be used to make a linear
pass through all keys in a database, in an (apparently) random order. 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_setpblksiz() function sets the page file block size, which is 1024
bytes by default. This function should only be called immediately after a
call to dbm_open() and prior to calls to other ndbm functions. For an
existing database, dbm_open() automatically sets the page file block size
to the size set at the time of its creation.
The dbm_error() function returns the error condition of the database.
The dbm_clearerr() function clears the error condition of the database.
[Tru64 UNIX] The dbm_forder() function returns the block number in the
.pag file to which the specified key maps.
NOTES
[Tru64 UNIX] When compiled in the X/Open UNIX environment, calls to the
dbm_delete(), dbm_fetch(), dbm_firstkey(), dbm_forder(), dbm_nextkey(), and
dbm_store() functions are internally renamed by prepending _E to the
function name. When you are debugging a module that includes any of these
functions and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ename
to refer to the name() call. For example, use _Edbm_delete to refer to the
dbm_delete call. See standards(5) for further information.
When using key structures containing gaps, make sure that the whole
structure, including gaps, is initialized to a known value; otherwise, the
keys may not match.
RETURN VALUES
Upon successful completion, all functions that return an int return a value
of 0 (zero). Otherwise, a negative value is returned.
Functions that return a datum indicate errors with a null (0) dptr.
The dbm_store() function returns 1 if it is called with a flags value of
DBM_INSERT and the function finds an existing entry with the same key.
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] [Tru64 UNIX] Insufficient space to allocate a buffer.
[EPERM] [Tru64 UNIX] An attempt was made to store or delete a key (and
its associated contents) in a database that was opened read-only.
[ENOSPC] [Tru64 UNIX] An attempt was made to store a key whose size
exceeds the page block size limit as defined by PBLKSIZ in
/usr/include/ndbm.h or a key whose size plus the size of its
associated contents exceeds the page block size limit set by
dbm_setpblksiz().
RELATED INFORMATION
Functions: dbm(3), open(2)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for N |
|
 |
Top of
page |
|