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 (see open in open(2) man page), 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 (see 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. See 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.