# dbm_clearerr

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch,
           dbm_firstkey, dbm_nextkey, dbm_open, dbm_store — database
           functions
    


## SYNOPSIS



           #include <ndbm.h>
    
           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_);
           datum dbm_nextkey(DBM *_db_);
           DBM *dbm_open(const char *_file_ , int _open_flags_ , mode_t _file_mode_);
           int dbm_store(DBM *_db_ , datum _key_ , datum _content_ , int _store_mode_);
    


## DESCRIPTION



           These functions create, access, and modify a database.
    
           A **datum** consists of at least two members, _dptr_ and _dsize_.  The
           _dptr_ member points to an object that is _dsize_ bytes in length.
           Arbitrary binary data, as well as character strings, may be stored
           in the object pointed to by _dptr_.
    
           A database shall be stored in one or two files. When one file is
           used, the name of the database file shall be formed by appending
           the suffix **.db** to the _file_ argument given to _dbm_open_().  When two
           files are used, the names of the database files shall be formed by
           appending the suffixes **.dir** and **.pag** respectively to the _file_
           argument.
    
           The _dbm_open_() function shall open a database. The _file_ argument
           to the function is the pathname of the database. The _open_flags_
           argument has the same meaning as the _flags_ argument of _open_()
           except that a database opened for write-only access opens the
           files for read and write access and the behavior of the O_APPEND
           flag is unspecified. The _file_mode_ argument has the same meaning
           as the third argument of _open_().
    
           The _dbm_open_() function need not accept pathnames longer than
           {PATH_MAX}-4 bytes (including the terminating null), or pathnames
           with a last component longer than {NAME_MAX}-4 bytes (excluding
           the terminating null).
    
           The _dbm_close_() function shall close a database. The application
           shall ensure that argument _db_ is a pointer to a **dbm** structure that
           has been returned from a call to _dbm_open_().
    
           These database functions shall support an internal block size
           large enough to support key/content pairs of at least 1023 bytes.
    
           The _dbm_fetch_() function shall read a record from a database. The
           argument _db_ is a pointer to a database structure that has been
           returned from a call to _dbm_open_().  The argument _key_ is a **datum**
           that has been initialized by the application to the value of the
           key that matches the key of the record the program is fetching.
    
           The _dbm_store_() function shall write a record to a database. The
           argument _db_ is a pointer to a database structure that has been
           returned from a call to _dbm_open_().  The argument _key_ is a **datum**
           that has been initialized by the application to the value of the
           key that identifies (for subsequent reading, writing, or deleting)
           the record the application is writing. The argument _content_ is a
           **datum** that has been initialized by the application to the value of
           the record the program is writing. The argument _store_mode_
           controls whether _dbm_store_() replaces any pre-existing record that
           has the same key that is specified by the _key_ argument. The
           application shall set _store_mode_ to either DBM_INSERT or
           DBM_REPLACE. If the database contains a record that matches the
           _key_ argument and _store_mode_ is DBM_REPLACE, the existing record
           shall be replaced with the new record. If the database contains a
           record that matches the _key_ argument and _store_mode_ is DBM_INSERT,
           the existing record shall be left unchanged and the new record
           ignored. If the database does not contain a record that matches
           the _key_ argument and _store_mode_ is either DBM_INSERT or
           DBM_REPLACE, the new record shall be inserted in the database.
    
           If the sum of a key/content pair exceeds the internal block size,
           the result is unspecified. Moreover, the application shall ensure
           that all key/content pairs that hash together fit on a single
           block. The _dbm_store_() function shall return an error in the event
           that a disk block fills with inseparable data.
    
           The _dbm_delete_() function shall delete a record and its key from
           the database. The argument _db_ is a pointer to a database structure
           that has been returned from a call to _dbm_open_().  The argument
           _key_ is a **datum** that has been initialized by the application to the
           value of the key that identifies the record the program is
           deleting.
    
           The _dbm_firstkey_() function shall return the first key in the
           database. The argument _db_ is a pointer to a database structure
           that has been returned from a call to _dbm_open_().
    
           The _dbm_nextkey_() function shall return the next key in the
           database. The argument _db_ is a pointer to a database structure
           that has been returned from a call to _dbm_open_().  The application
           shall ensure that the _dbm_firstkey_() function is called before
           calling _dbm_nextkey_().  Subsequent calls to _dbm_nextkey_() return
           the next key until all of the keys in the database have been
           returned.
    
           The _dbm_error_() function shall return the error condition of the
           database. The argument _db_ is a pointer to a database structure
           that has been returned from a call to _dbm_open_().
    
           The _dbm_clearerr_() function shall clear the error condition of the
           database. The argument _db_ is a pointer to a database structure
           that has been returned from a call to _dbm_open_().
    
           The _dptr_ pointers returned by these functions may point into
           static storage that may be changed by subsequent calls.
    
           These functions need not be thread-safe.
    


## RETURN VALUE



           The _dbm_store_() and _dbm_delete_() functions shall return 0 when
           they succeed and a negative value when they fail.
    
           The _dbm_store_() function shall return 1 if it is called with a
           _flags_ value of DBM_INSERT and the function finds an existing
           record with the same key.
    
           The _dbm_error_() function shall return 0 if the error condition is
           not set and return a non-zero value if the error condition is set.
    
           The return value of _dbm_clearerr_() is unspecified.
    
           The _dbm_firstkey_() and _dbm_nextkey_() functions shall return a key
           **datum**.  When the end of the database is reached, the _dptr_ member
           of the key is a null pointer. If an error is detected, the _dptr_
           member of the key shall be a null pointer and the error condition
           of the database shall be set.
    
           The _dbm_fetch_() function shall return a content **datum**.  If no
           record in the database matches the key or if an error condition
           has been detected in the database, the _dptr_ member of the content
           shall be a null pointer.
    
           The _dbm_open_() function shall return a pointer to a database
           structure. If an error is detected during the operation,
           _dbm_open_() shall return a (**DBM ***)0.
    


## ERRORS



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The following code can be used to traverse the database:
    
               for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
    
           The _dbm__ * 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 requiring fast lookup of
           relatively static information that is to be indexed by a single
           key.
    
           Note that a strictly conforming application is extremely limited
           by these functions: since there is no way to determine that the
           keys in use do not all hash to the same value (although that would
           be rare), a strictly conforming application cannot be guaranteed
           that it can store more than one block's worth of data in the
           database. As long as a key collision does not occur, additional
           data may be stored, but because there is no way to determine
           whether an error is due to a key collision or some other error
           condition (_dbm_error_() being effectively a Boolean), once an error
           is detected, the application is effectively limited to guessing
           what the error might be if it wishes to continue using these
           functions.
    
           The _dbm_delete_() function need not physically reclaim file space,
           although it does make it available for reuse by the database.
    
           After calling _dbm_store_() or _dbm_delete_() during a pass through
           the keys by _dbm_firstkey_() and _dbm_nextkey_(), the application
           should reset the database by calling _dbm_firstkey_() before again
           calling _dbm_nextkey_().  The contents of these files are
           unspecified and may not be portable.
    
           Applications should take care that database pathname arguments
           specified to _dbm_open_() are not prefixes of unrelated files. This
           might be done, for example, by placing databases in a separate
           directory.
    
           Since some implementations use three characters for a suffix and
           others use four characters for a suffix, applications should
           ensure that the maximum portable pathname length passed to
           _dbm_open_() is no greater than {PATH_MAX}-4 bytes, with the last
           component of the pathname no greater than {NAME_MAX}-4 bytes.
    


## RATIONALE



           Previously the standard required the database to be stored in two
           files, one file being a directory containing a bitmap of keys and
           having **.dir** as its suffix. The second file containing all data and
           having **.pag** as its suffix. This has been changed not to specify
           the use of the files and to allow newer implementations of the
           Berkeley DB interface using a single file that have evolved while
           remaining compatible with the application programming interface.
           The standard developers considered removing the specific suffixes
           altogether but decided to retain them so as not to pollute the
           application file name space more than necessary and to allow for
           portable backups of the database.
    


## FUTURE DIRECTIONS



           None.
    


* * *