MirOS Manual: dbm_clearerr(3), dbm_close(3), dbm_delete(3), dbm_dirfno(3), dbm_error(3), dbm_fetch(3), dbm_firstkey(3), dbm_nextkey(3), dbm_open(3), dbm_pagfno(3), dbm_rdonly(3), dbm_store(3), ndbm(3)

NDBM(3)                    BSD Programmer's Manual                     NDBM(3)

NAME

     dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch,
     dbm_firstkey, dbm_nextkey, dbm_open, dbm_pagfno, dbm_rdonly, 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, mode_t mode);

     int
     dbm_pagfno(DBM *db);

     int
     dbm_rdonly(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
     data. The key and the content data are described by the datum data struc-
     ture:

           typedef struct {
                   void *dptr;
                   size_t 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_RDONLY. The
     dbm_rdonly() function may be used to determine if a database is opened
     for read-only access.

     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 data-
     base, 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 database 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
     corresponds to those errors described in db(3).

SEE ALSO

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

MirOS BSD #10-current            May 13, 1998                                1

Generated on 2014-04-02 20:57:59 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.