File: gdbm.info,  Node: ndbm,  Next: dbm,  Up: Compatibility

23.1 NDBM interface functions
=============================

The functions below implement the POSIX 'ndbm' interface:

 -- ndbm: DBM * dbm_open (char *FILE, int FLAGS, int MODE)
     Opens a database.  The FILE argument is the full name of the
     database file to be opened.  The function opens two files:
     'FILE.pag' and 'FILE.dir'.  The FLAGS and MODE arguments have the
     same meaning as the second and third arguments of 'open' (*note
     (open(2))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 function returns a pointer to the 'DBM' structure describing
     the database.  This pointer is used to refer to this database in
     all operations described below.

     Any error detected will cause a return value of 'NULL' and an
     appropriate value will be stored in 'gdbm_errno' (*note
     Variables::).

 -- ndbm: void dbm_close (DBM *DBF)
     Closes the database.  The DBF argument must be a pointer returned
     by an earlier call to 'dbm_open'.

 -- ndbm: datum dbm_fetch (DBM *DBF, datum KEY)
     Reads a record from the database with the matching key.  The KEY
     argument supplies the key that is being looked for.

     If no matching record is found, the 'dptr' member of the returned
     datum is 'NULL'.  Otherwise, the 'dptr' member of the returned
     datum points to the memory managed by the compatibility library.
     The application should never free it.

 -- ndbm: int dbm_store (DBM *DBF, datum KEY, datum CONTENT, int MODE)
     Writes a key/value pair to the database.  The argument DBF is a
     pointer to the 'DBM' structure returned from a call to 'dbm_open'.
     The KEY and CONTENT provide the values for the record key and
     content.  The MODE argument controls the behavior of 'dbm_store' in
     case a matching record already exists in the database.  It can have
     one of the following two values:

     'DBM_REPLACE'
          Replace existing record with the new one.

     'DBM_INSERT'
          The existing record is left unchanged, and the function
          returns '1'.

     If no matching record exists in the database, new record will be
     inserted no matter what the value of the MODE is.

 -- ndbm: int dbm_delete (DBM *DBF, datum KEY)
     Deletes the record with the matching key from the database.  If the
     function succeeds, '0' is returned.  Otherwise, if no matching
     record is found or if an error occurs, '-1' is returned.

 -- ndbm: datum dbm_firstkey (DBM *DBF)
     Initializes iteration over the keys from the database and returns
     the first key.  Note, that the word 'first' does not imply any
     specific ordering of the keys.

     If there are no records in the database, the 'dptr' member of the
     returned datum is 'NULL'.  Otherwise, the 'dptr' member of the
     returned datum points to the memory managed by the compatibility
     library.  The application should never free it.

 -- ndbm: datum dbm_nextkey (DBM *DBF)
     Continues the iteration started by 'dbm_firstkey'.  Returns the
     next key in the database.  If the iteration covered all keys in the
     database, the 'dptr' member of the returned datum is 'NULL'.
     Otherwise, the 'dptr' member of the returned datum points to the
     memory managed by the compatibility library.  The application
     should never free it.

     The usual way of iterating over all the records in the database is:

          for (key = dbm_firstkey (dbf); key.ptr; key = dbm_nextkey (dbf))
            {
              /* do something with the key */
            }

     The loop above should not try to delete any records from the
     database, otherwise the iteration is not guaranteed to cover all
     the keys.  *Note Sequential::, for a detailed discussion of this.

 -- ndbm: int dbm_error (DBM *DBF)
     Returns the error condition of the database: '0' if no errors
     occurred so far while manipulating the database, and a non-zero
     value otherwise.

 -- ndbm: void dbm_clearerr (DBM *DBF)
     Clears the error condition of the database.

 -- ndbm: int dbm_dirfno (DBM *DBF)
     Returns the file descriptor of the 'dir' file of the database.  It
     is guaranteed to be different from the descriptor returned by the
     'dbm_pagfno' function (see below).

     The application can lock this descriptor to serialize accesses to
     the database.

 -- ndbm: int dbm_pagfno (DBM *DBF)
     Returns the file descriptor of the 'pag' file of the database.  See
     also 'dbm_dirfno'.

 -- ndbm: int dbm_rdonly (DBM *DBF)
     Returns '1' if the database DBF is open in a read-only mode and '0'
     otherwise.