April 30, 2004 DBM_CLEARERR 3

### NAME

dbm_clearerr, dbm_close, dbm_delete, dbm_dirfno, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store, ndbm - database functions

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```int` dbm_clearerr(```DBM *db`)
```void` dbm_close(```DBM *db`)
```int` dbm_delete(```DBM *db``, datum key`)
```int` dbm_dirfno(```DBM *db`)
```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

The ndbm facility provides access to hash database files.

Two data types are fundamental to the ndbm facility. ```DBM` serves as a handle to a database. It is an opaque type.

The other data type is ```datum`, which is a structure type which includes the following members:

  `

      void *  dptr
      size_t  dsize

  `

A ```datum` is thus given by ```dptr` pointing at an object of ```dsize` bytes in length.

The dbm_open(``) function opens a database. The ```file` argument is the pathname which the actual database file pathname is based on. This implementation uses a single file with the suffix ```.db` appended to ```file`. The ```open_flags` argument has the same meaning as the ```flags` argument to open(2) except that when opening a database for write-only access the file is opened for read/write access, and the ```O_APPEND` flag must not be specified. The ```file_mode` argument has the same meaning as the ```mode` argument to open(2).

For the following functions, the ```db` argument is a handle previously returned by a call to dbm_open(``).

The dbm_close(``) function closes a database.

The dbm_fetch(``) function retrieves a record from the database. The ```key` argument is a ```datum` that identifies the record to be fetched.

The dbm_store(``) function stores a record into the database. The ```key` argument is a ```datum` that identifies the record to be stored. The ```content` argument is a ```datum` that specifies the value of the record to be stored. The ```store_mode` argument specifies the behavior of dbm_store(``) if a record matching ```key` is already present in the database, ```db`. ```store_mode` must be one of the following:

```DBM_INSERT`
  If a record matching ```key` is already present, it is left unchanged.

```DBM_REPLACE`
  If a record matching ```key` is already present, its value is replaced by ```content`.

If no record matching ```key` is present, a new record is inserted regardless of ```store_mode`.

The dbm_delete(``) function deletes a record from the database. The ```key` argument is a ```datum` that identifies the record to be deleted.

The dbm_firstkey(``) function returns the first key in the database.

The dbm_nextkey(``) function returns the next key in the database. In order to be meaningful, it must be preceded by a call to dbm_firstkey(``).

The dbm_error(``) function returns the error indicator of the database.

The dbm_clearerr(``) function clears the error indicator of the database.

The dbm_dirfno(``) function returns the file descriptor of the underlying database file.

### IMPLEMENTATION NOTES

The ndbm facility is implemented on top of the hash(3) access method of the db(3) database facility.

### RETURN VALUES

The dbm_open(``) function returns a pointer to a ```DBM` when successful; otherwise a null pointer is returned.

The dbm_close(``) function returns no value.

The dbm_fetch(``) function returns a content ```datum`; if no record matching ```key` was found or if an error occured, its ```dptr` member is a null pointer.

The dbm_store(``) function returns 0 when then record was successfully inserted; it returns 1 when called with ```store_mode` being ```DBM_INSERT` and a record matching ```key` is already present; otherwise a negative value is returned.

The dbm_delete(``) function returns 0 when the record was successfully deleted; otherwise a negative value is returned.

The dbm_firstkey(``) and dbm_nextkey(``) functions return a key ```datum`. When the end of the database is reached or if an error occured, its ```dptr` member is a null pointer.

The dbm_error(``) function returns 0 if the error indicator is clear; if the error indicator is set a non-zero value is returned.

The dbm_clearerr(``) function always returns 0.

The dbm_dirfno(``) function returns the file descriptor of the underlying database file.

### ERRORS

No errors are defined.

### SEE ALSO

open(2), db(3), hash(3)

### STANDARDS

The dbm_clearerr(``), dbm_close(``), dbm_delete(``), dbm_error(``), dbm_fetch(``), dbm_firstkey(``), dbm_nextkey(``), dbm_open(``), and dbm_store(``) functions conform to X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'') . The dbm_dirfno(``) function is an extension.