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.