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

23.2 DBM interface functions
============================

The functions below are provided for compatibility with the old UNIX
'DBM' interface.  Only one database at a time can be manipulated using
them.

 -- dbm: int dbminit (char *FILE)
     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'.  If any of them does not exist, the
     function fails.  It never attempts to create the files.

     The database is opened in the read-write mode, if its disk
     permissions permit.

     The application must ensure that the functions described below in
     this section are called only after a successful call to 'dbminit'.

 -- dbm: int dbmclose (void)
     Closes the database opened by an earlier call to 'dbminit'.

 -- dbm: datum fetch (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.

 -- dbm: int store (datum KEY, datum CONTENT)
     Stores the key/value pair in the database.  If a record with the
     matching key already exists, its content will be replaced with the
     new one.

     Returns '0' on success and '-1' on error.

 -- dbm: int delete (datum KEY)
     Deletes a record with the matching key.

     If the function succeeds, '0' is returned.  Otherwise, if no
     matching record is found or if an error occurs, '-1' is returned.

 -- dbm: datum firstkey (void)
     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.

 -- dbm: datum nextkey (datum KEY)
     Continues the iteration started by a call to '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.