---
name: "dbm"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/dbm"
---

# dbm(3)

database access functions

## NAME

**dbm\_clearerr**, **dbm\_close**, **dbm\_delete**, **dbm\_dirfno**, **dbm\_error**, **dbm\_fetch**, **dbm\_firstkey**, **dbm\_nextkey**, **dbm\_open**, **dbm\_store** – database access functions

## SYNOPSIS

**#include \<ndbm.h\>**

*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

Database access functions. These functions are implemented using [dbopen(3)](/dbopen/3.md) with a [hash(3)](/hash/3.md) database.

*datum* is declared in ⟨ndbm.h⟩:

```
typedef struct {
	char *dptr;
	int dsize;
} datum;
```

The **dbm\_open**(*file*, *open\_flags*, *file\_mode*) function opens or creates a database file. The *file* argument is the basename of the file containing the database; the actual database has a *.db* suffix. I.e., if *file* is "/home/me/mystuff" then the actual database is in the file */home/me/mystuff.db*. The *open\_flags* and *file\_mode* arguments are passed to [open(2)](/open/2.md). (O\_RDWR \| O\_CREAT) is a typical value for *open\_flags*; 0660 is a typical value for *file\_mode*. O\_WRONLY is not allowed in *open\_flags*. The pointer returned by **dbm\_open**() identifies the database and is the *db* argument to the other functions. The **dbm\_open**() function returns NULL and sets *errno* if there were any errors.

The **dbm\_close**(*db*) function closes the database.

The **dbm\_store**(*db*, *key*, *content*, *store\_mode*) function inserts or replaces an entry in the database. The *store\_mode* argument is either DBM\_INSERT or DBM\_REPLACE. If *store\_mode* is DBM\_INSERT and the database already contains an entry for *key*, that entry is not replaced. Otherwise the entry is replaced or inserted. The **dbm\_store**() function normally returns zero but returns 1 if the entry could not be inserted (because *store\_mode* is DBM\_INSERT, and an entry with *key* already exists) or returns -1 and sets *errno* if there were any errors.

The **dbm\_fetch**(*db*, *key*) function returns NULL or the *content* corresponding to *key*.

The **dbm\_delete**(*db*, *key*) function deletes the entry for *key*. The **dbm\_delete**() function normally returns zero but returns 1 if there was no entry with *key* in the database or returns -1 and sets *errno* if there were any errors.

The **dbm\_firstkey**(*db*) function returns the first key in the database. The **dbm\_nextkey**(*db*) function returns subsequent keys. The **db\_firstkey**() function must be called before **dbm\_nextkey**(). The order in which keys are returned is unspecified and may appear random. The **dbm\_nextkey**() function returns NULL after all keys have been returned.

The **dbm\_error**(*db*) function returns the *errno* value of the most recent error. The **dbm\_clearerr**(*db*) function resets this value to 0 and returns 0.

The **dbm\_dirfno**(*db*) function returns the file descriptor to the database.

## LEGACY SYNOPSIS

**#include \<fcntl.h\>** **#include \<ndbm.h\>**

The include file ⟨ndbm.h⟩ is necessary for all functions.

*DBM* *\**\
 **dbm\_open**(*const char \*file*, *int open\_flags*, *int file\_mode*);

*file\_mode* has type *int*.

## SEE ALSO

[open(2)](/open/2.md), [dbopen(3)](/dbopen/3.md), [hash(3)](/hash/3.md), [compat(5)](/compat/5.md)

## STANDARDS

These functions (except **dbm\_dirfno**()) are included in the Version 2 of the Single UNIX Specification (“SUSv2”).