GDBM(3)

📦
version 1.26 · 4 versions
, in alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

GDBM(3) — GDBM User Reference 🫶✨

okay bestie, welcome to the GDBM library manual, part 1! 💅 this is the GNU database manager, and it also includes dbm and ndbm compatibility. let's get into it.

✨ NAME ✨

GDBM — The GNU database manager. Includes dbm and ndbm compatibility. 💖

🦋 SYNOPSIS 🦋

       #include <gdbm.h>

       extern gdbm_error gdbm_errno;
       extern char *gdbm_version;
       extern int gdbm_version[3];
       GDBM_FILE gdbm_open (const char *name, int block_size,
                            int flags, int mode,
                            void (*fatal_func)(const char *));
       GDBM_FILE gdbm_fd_open (int FD, const char *name, int block_size,
                               int flags, int mode,
                               void (*fatal_func)(const char *));
       GDBM_FILE gdbm_open_ext (const char *name, int flags,
                                struct gdbm_open_spec *spec);
       void gdbm_open_spec_init (struct gdbm_open_spec *spec);
       int gdbm_close (GDBM_FILE dbf);
       int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag);
       datum gdbm_fetch (GDBM_FILE dbf, datum key);
       int gdbm_delete (GDBM_FILE dbf, datum key);
       datum gdbm_firstkey (GDBM_FILE dbf);
       datum gdbm_nextkey (GDBM_FILE dbf, datum key);
       int gdbm_recover (GDBM_FILE dbf, gdbm_recovery *rcvr, intflags);
       int gdbm_reorganize (GDBM_FILE dbf);
       int gdbm_sync (GDBM_FILE dbf);
       int gdbm_exists (GDBM_FILE dbf, datum key);
       const char *gdbm_strerror (gdbm_error errno);
       int gdbm_setopt (GDBM_FILE dbf, int option, int value, int size);
       int gdbm_fdesc (GDBM_FILE dbf);
       int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
       int gdbm_bucket_count (GDBM_FILE dbf, size_t *pcount);
       int gdbm_avail_verify (GDBM_FILE dbf);

💅 Crash Tolerance (see below):

       int gdbm_failure_atomic (GDBM_FILE dbf, const char *even, const char
       *odd);
       int gdbm_latest_snapshot (const char *even, const char *odd, const char
       **result);

💖 NOTICE 💖

This manpage is a short description of the GDBM library. For a detailed discussion, including examples and usage recommendations, refer to the GDBM Manual available in Texinfo format. To access it, run:

info gdbm

The documentation is also available online at

https://www.gnu.org/software/gdbm/manual

Should any discrepancies occur between this manpage and the GDBM Manual, the later shall be considered the authoritative source.

🌸 DESCRIPTION 🌸

GNU dbm is a library of routines that manages data files that contain key/data pairs. The access provided is that of storing, retrieval, and deletion by key and a non-sorted traversal of all keys. A process is allowed to use multiple data files at the same time. ✨

✨ Opening a database ✨

A process that opens a gdbm file is designated as a "reader" or a "writer". Only one writer may open a gdbm file and many readers may open the file. Readers and writers can not open the gdbm file at the same time. The procedure for opening a gdbm file is:

GDBM_FILE gdbm_open (const char *name, int block_size,
                     int flags, int mode,
                     void (*fatal_func)(const char *));
  • name — is the name of the file (the complete name, gdbm does not append any characters to this name). 💅
  • block_size — is the size of a single transfer from disk to memory. If the value is less than 512, the file system block size is used instead. The size is adjusted so that the block can hold exact number of directory entries, so that the effective block size can be slightly greater than requested. This adjustment is disabled if the GDBM_BSEXACT flag is used.
  • flags — a bitmask, composed of the access mode and one or more modifier flags. The access mode bit designates the process as a reader or writer and must be one of the following:
    • GDBM_READER — reader 👀
    • GDBM_WRITER — writer ✍️
    • GDBM_WRCREAT — writer - if database does not exist create new one
    • GDBM_NEWDB — writer - create new database regardless if one exists

Additional flags (modifiers) can be combined with these values by bitwise OR. Not all of them are meaningful with all access modes.

Flags that are valid for any value of access mode are:

  • GDBM_CLOEXEC — Set the close-on-exec flag on the database file descriptor.
  • GDBM_NOLOCK — Prevents the library from performing any locking on the database file.
  • GDBM_NOMMAP — Instructs gdbm_open to disable the use of mmap(2).
  • GDBM_PREREAD — When mapping GDBM file to memory, read its contents immediately, instead of when needed (prefault reading). This can be advantageous if you open a read-only database and are going to do a lot of look-ups on it. In this case entire database will be read at once and searches will operate on an in-memory copy. In contrast, GDBM_PREREAD should not be used if you open a database (even in read-only mode) only to retrieve a couple of keys. Finally, never use GDBM_PREREAD when opening a database for updates, especially for inserts: this will degrade performance. This flag has no effect if GDBM_NOMMAP is given, or if the operating system does not support prefault reading. It is known to work on Linux and FreeBSD kernels.
  • GDBM_XVERIFY — Enable additional consistency checks. With this flag, eventual corruptions of the database are discovered when opening it, instead of when a corrupted structure is read during normal operation. However, on large databases, it can slow down the opening process.

The following additional flags are valid when the database is opened for writing (GDBM_WRITER, GDBM_WRCREAT, or GDBM_NEWDB):

  • GDBM_SYNC — Causes all database operations to be synchronized to the disk.
NOTE: this option entails severe performance degradation and does not necessarily ensure that the resulting database state is consistent, therefore we discourage its use. For a discussion of how to ensure database consistency with minimal performance overhead, see CRASH TOLERANCE below.
  • GDBM_FAST — A reverse of GDBM_SYNC: synchronize writes only when needed. This is the default. This flag is provided only for compatibility with previous versions of GDBM.

The following flags can be used together with GDBM_NEWDB. They also take effect when used with GDBM_WRCREAT, if the requested database file doesn't exist:

  • GDBM_BSEXACT — If this flag is set and the requested block_size value cannot be used, gdbm_open will refuse to create the database. In this case it will set the gdbm_errno variable to GDBM_BLOCK_SIZE_ERROR and return NULL. Without this flag, gdbm_open will silently adjust the block_size to a usable value, as described above.
  • GDBM_NUMSYNC — Create new database in extended database format, a format best suited for effective crash recovery. For a detailed discussion, see the CRASH RECOVERY chapter below.
  • mode — is the file mode (see chmod(2) and open(2)). It is used if the file is created.
  • fatal_func — is a function to be called when gdbm encounters a fatal error. This parameter is deprecated and must always be NULL.

The return value is the pointer needed by all other routines to access that gdbm file. If the return is the NULL pointer, gdbm_open was not successful. In this case, the reason of the failure can be found in the gdbm_errno variable. If the following call returns true (non-zero value):

gdbm_check_syserr(gdbm_open)

the system errno variable must be examined in order to obtain more detail about the failure.

GDBM_FILE gdbm_fd_open (int FD, const char *name, int block_size,
                        int flags, int mode,
                        void (*fatal_func)(const char *));

This is an alternative entry point to gdbm_open. FD is a valid file descriptor obtained as a result of a call to open(2) or creat(2). The function opens (or creates) a GDBM database this descriptor refers to. The descriptor is not dup'ed, and will be closed when the returned GDBM_FILE is closed. Use dup (2) if that is not desirable.

In case of error, the function behaves like gdbm_open and does not close FD. This can be altered by the following value passed in flags:

  • GDBM_CLOERROR — Close FD before exiting on error.

The rest of arguments are the same as for gdbm_open.

GDBM_FILE gdbm_open_ext (const char *name, int flags,
                         struct gdbm_open_spec *spec);

This is an extended interface for opening and creating database files. The meaning of name and flags is the same as described above. Third argument, spec, is a pointer to a structure that supplies additional information about how to open the database. It can be NULL, in which case the call is equivalent to

gdbm_open (name, 0, flags, 0600, NULL)

The struct gdbm_open_ext type has at least the following fields:

  • int fd — Unless -1, this is the file descriptor of an already opened database file. The function will then act as improved gdbm_fd_open.
  • int mode — File mode to use if the file needs be created.
  • int block_size — Block size to be used when creating new database. Zero stands for default value. See the description of the block_size argument in gdbm_open, for details.
  • int lock_wait — This field, together with the two fields described below, controls how to handle failed attempts to lock the file. Its possible values are:
    • GDBM_LOCKWAIT_NONE — Return NULL immediately. This is the default.
    • GDBM_LOCKWAIT_RETRY — Sleep for the amount of time defined by the lock_interval field, and retry the attempt. In case of failure, repeat until total time spent exceeds lock_timeout.
  • GDBM_LOCKWAIT_SIGNAL — okay so bestie, this one waits until locking succeeds or the timeout defined by lock_timeout expires, whichever happens first. Signal delivery is used to catch timeout expiration, so this method is not advised for use in multi-threaded programs. 💀
  • struct timespec lock_timeout — the overall timeout for file locking operation. ⏳
  • struct timespec lock_interval — the time interval between two successive locking attempts. It's used if lock_wait is set to GDBM_LOCKWAIT_RETRY. 🔁

A struct gdbm_open_spec variable can be initialized to default values by assigning it the GDBM_OPEN_SPEC_INITIALIZER value, or by using the gdbm_open_spec_init function. The latter is defined as:

void gdbm_open_spec_init (struct gdbm_open_spec *spec);

Calling convention 🫶

All GDBM functions take as their first parameter the database handle (GDBM_FILE), which you get back from gdbm_open, gdbm_fd_open, or gdbm_open_ext. ✨ No cap.

Any value stored in the GDBM database is described by datum, an aggregate type defined as:

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

The dptr field points to the actual data. Its type is char * for historical reasons. Actually it should have been typed void *. Programmers are free to store data of arbitrary complexity, both scalar and aggregate, in this field. 🦋

The dsize field contains the number of bytes stored in dptr. 📏

The datum type is used to describe both keys and content (values) in the database. Values of this type can be passed as arguments or returned from GDBM function calls. 🔑

GDBM functions that return datum indicate failure by setting its dptr field to NULL. 🚫

Functions returning integer value, indicate success by returning 0 and failure by returning a non-zero value (the only exception to this rule is gdbm_exists, for which the return value is reversed). ⚠️

If the returned value indicates failure, the gdbm_errno variable contains an integer value indicating what went wrong. A similar value is associated with the dbf handle and can be accessed using the gdbm_last_errno function. Immediately after return from a function, both values are exactly equal. Subsequent GDBM calls with another dbf as argument may alter the value of the global gdbm_errno, but the value returned by gdbm_last_errno will always indicate the most recent code of an error that occurred for that particular database. Programmers are encouraged to use such per-database error codes. 💅

Sometimes the actual reason of the failure can be clarified by examining the system errno value. To make sure its value is meaningful for a given GDBM error code, use the gdbm_check_syserr function. The function takes error code as argument and returns 1 if the errno is meaningful for that error, or 0 if it is irrelevant. 🔍

Similarly to gdbm_errno, the latest errno value associated with a particular database can be obtained using the gdbm_last_syserr function. 📟

The gdbm_clear_error clears the error indicator (both GDBM and system error codes) associated with a database handle. 🧹

Some critical errors leave the database in a structurally inconsistent state. If that happens, all subsequent GDBM calls accessing that database will fail with the GDBM error code of GDBM_NEED_RECOVERY (a special function gdbm_needs_recovery is also provided, which returns true if the database handle given as its argument is structurally inconsistent). To return such databases to consistent state, use the gdbm_recover function (see below). 🚨

The GDBM_NEED_RECOVERY error cannot be cleared using gdbm_clear_error. ⛔

Error functions 🛠️

This section describes the error handling functions outlined above. 👇

  • gdbm_error gdbm_last_errno (GDBM_FILE dbf) — returns the error code of the most recent failure encountered when operating on dbf. 😭
  • int gdbm_last_syserr (GDBM_FILE dbf) — returns the value of the system errno variable associated with the most recent failure that occurred on dbf. Notice that not all gdbm_error codes have a relevant system error code. Use the following function to determine if a given code has. 🧐
  • int gdbm_check_syserr (gdbm_error err) — returns 1, if system errno value should be checked to get more info on the error described by GDBM code err. ✅
  • void gdbm_clear_error (GDBM_FILE dbf) — clears the error state for the database dbf. This function is called implicitly upon entry to any GDBM function that operates on GDBM_FILE. The GDBM_NEED_RECOVERY error cannot be cleared. 🚫
  • int gdbm_needs_recovery (GDBM_FILE dbf) — return 1 if the database file dbf is in inconsistent state and needs recovery. 🚑
  • const char *gdbm_strerror (gdbm_error err) — returns a textual description of the error code err. 📝
  • const char *gdbm_db_strerror (GDBM_FILE dbf) — returns a textual description of the recent error in database dbf. This description includes the system errno value, if relevant. 📖

Closing the database 🚪

It is important that every database file opened is also closed. This is needed to update the reader/writer count on the file. This is done by:

int gdbm_close (GDBM_FILE dbf);

No cap, close your files bestie. 💅

Database lookups 🔍

  • int gdbm_exists (GDBM_FILE dbf, datum key); — if the key is found within the database, the return value will be true (1). If nothing appropriate is found, false (0) is returned and gdbm_errno set to GDBM_NO_ERROR. On error, returns 0 and sets gdbm_errno. 👀
  • datum gdbm_fetch (GDBM_FILE dbf, datum key); — dbf is the pointer returned by gdbm_open. key is the key data. If the dptr element of the return value is NULL, the gdbm_errno variable should be examined. The value of GDBM_ITEM_NOT_FOUND means no data was found for that key. Other value means an error occurred. Otherwise the return value is a pointer to the found data. The storage space for the dptr element is allocated using malloc(3). GDBM does not automatically free this data. It is the programmer's responsibility to free this storage when it is no longer needed. 🗑️

Iterating over the database 🔄

The following two routines allow for iterating over all items in the database. Such iteration is not key sequential, but it is guaranteed to visit every key in the database exactly once. (The order has to do with the hash values.) 🎲

  • datum gdbm_firstkey (GDBM_FILE dbf); — returns first key in the database. 🥇
  • datum gdbm_nextkey (GDBM_FILE dbf, datum key); — given a key, returns the database key that follows it. End of iteration is marked by returning datum with dptr field set to NULL and setting the gdbm_errno value to GDBM_ITEM_NOT_FOUND. 🏁

After successful return from both functions, dptr points to data allocated by malloc(3). It is the caller responsibility to free the data when no longer needed. 🧹

A typical iteration loop looks like:

datum key, nextkey, content;
key = gdbm_firstkey (dbf);
while (key.dptr)
  {
    content = gdbm_fetch (dbf, key);
    /* Do something with key and/or content */
    nextkey = gdbm_nextkey (dbf, key);
    free (key.dptr);
    key = nextkey;
  }

These functions are intended to visit the database in read-only algorithms. Avoid any database modifications within the iteration loop. File visiting is based on a hash table. The gdbm_delete and, in most cases, gdbm_store, functions rearrange the hash table to make sure that any collisions in the table do not leave some item `un-findable'. Thus, a call to either of these functions changes the order in which the keys are ordered. Therefore, these functions should not be used when iterating over all the keys in the database. For example, the following loop is wrong: it is possible that some keys will not be visited or will be visited twice if it is executed: 🚫

key = gdbm_firstkey (dbf);
while (key.dptr)
  {
    nextkey = gdbm_nextkey (dbf, key);
    if (some condition)
      gdbm_delete ( dbf, key );
    free (key.dptr);
    key = nextkey;
  }

Updating the database 📝

  • int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag); — dbf is the pointer returned by gdbm_open. key is the key data. content is the data to be associated with the key. flag can have one of the following values:
    • GDBM_INSERT — insert only, generate an error if key exists; 🚫
    • GDBM_REPLACE — replace contents if key exists. 🔄

The function returns 0 on success and -1 on failure. If the key already exists in the database and the flag is GDBM_INSERT, the function does not modify the database. It sets gdbm_errno to GDBM_CANNOT_REPLACE and returns 1. 😤

  • int gdbm_delete (GDBM_FILE dbf, datum key); — looks up and deletes the given key from the database dbf. The return value is 0 if there was a successful delete or -1 on error. In the latter case, the gdbm_errno value GDBM_ITEM_NOT_FOUND indicates that the key is not present in the database. Other gdbm_errno values indicate failure. 🗑️

Recovering structural consistency 🚑

If a function leaves the database in structurally inconsistent state, it can be recovered using the gdbm_recover function. 🚑

  • int gdbm_recover (GDBM_FILE dbf, gdbm_recovery * rcvr, int flags) — check the database file DBF and fix eventual inconsistencies. The rcvr argument can be used both to control the recovery and to return additional statistics about the process, as indicated by flags. For a detailed discussion of these arguments and their usage, see the GDBM Manual, chapter Recovering structural consistency. You can pass NULL as rcvr and 0 as flags, if no such control is needed. By default, this function first checks the database for inconsistencies and attempts recovery only if some were found. The special flags bit GDBM_RCVR_FORCE instructs gdbm_recovery to skip this check and to perform database recovery unconditionally. 🔧

Export and import 💾✨

okay so bestie, GDBM database files can be exported (that's "dumped") into what we call flat files, or imported (that's "loaded") back out of them. A flat file has exactly the same data as the original database, but lowkey it can't be used for searches or updates. Its whole purpose is to hold onto the data so you can restore it later when the need arrives. So basically: flat files are for backups and for yeeting databases over the wire. 📡

As of GDBM version 1.21, there are two flat file formats:

  • The ASCII file format encodes all data in Base64 and stores not only the key/data pairs, but also the original database file metadata — like file name, mode and ownership. Files in this format can be sent without additional encapsulation over transmission channels that normally only allow ASCII data, such as, e.g. SMTP. And because of that extra metadata, they let you restore an exact copy of the database, including file ownership and privileges — which is highkey important if the database in question contained some security-related data. 👑 This is the preferred format.
  • The other one is the binary format. It stores only key/data pairs and keeps no information about the database file itself. It cannot be used to copy databases between different architectures. The binary format was introduced in GDBM version 1.9.1 and is retained mainly for backward compatibility. (It's giving legacy, ngl.)

The following functions are what you use to export or import GDBM database files. 🫶

int gdbm_dump (GDBM_FILE dbf, const char *filename,
               int format, int open_flag, int mode)

Dumps the database file dbf to the file filename in the requested format. The allowed values for format are:

  • GDBM_DUMP_FMT_ASCII — to create an ASCII dump file ✨
  • GDBM_DUMP_FMT_BINARY — to create a binary dump

The value of open_flag tells gdbm_dump what to do if filename already exists:

  • If it's GDBM_NEWDB, the function will create a new output file, replacing it if it already exists.
  • If its value is GDBM_WRCREAT, the file will be created if it does not exist. But if it does exist, gdbm_dump will return error. 🚫

The file mode to use when creating the output file is defined by the mode parameter. Its meaning is the same as for open(2).

int gdbm_load (GDBM_FILE *pdbf, const char *filename,
               int flag, int meta_mask, unsigned long *errline)

Loads data from the dump file filename into the database pointed to by pdbf. If pdbf is NULL, the function will try to create a new database. On success, the new GDBM_FILE object will be stored in the memory location pointed to by pdbf. But listen — if the dump file carries no information about the original database file name, the function will set gdbm_errno to GDBM_NO_DBNAME and return -1, indicating failure. 😭

Otherwise, if pdbf points to an already open GDBM_FILE, the function will load data from filename into that database.

The flag parameter controls the function behavior if a key from the dump file already exists in the database. See the gdbm_store function for its possible values. 👀

The meta_mask parameter can be used to disable restoring certain bits of the file's meta-data from the information in the input dump file. It is a binary OR of zero or more of the following:

  • GDBM_META_MASK_MODE — Do not restore file mode.
  • GDBM_META_MASK_OWNER — Do not restore file owner.

Other functions 🛠️💅

int gdbm_reorganize (GDBM_FILE dbf);

If you have had a lot of deletions and would like to shrink the space used by the GDBM file, this routine will reorganize the database. ✨ (It's giving "clean your room" energy but for buckets.)

int gdbm_sync (GDBM_FILE dbf);

Synchronizes the changes in dbf with its disk file. 💾

It will not return until the disk file state is synchronized with the in-memory state of the database. Periodt.

int gdbm_setopt (GDBM_FILE dbf, int option, void *value, int size);

Query or change some parameter of an already opened database. The option argument defines what parameter to set or retrieve.

  • If the set operation is requested, value points to the new value. Its actual data type depends on option.
  • If the get operation is requested, value points to a memory region where to store the return value.

In both cases, size contains the actual size of the memory pointed to by value.

Possible values of option are: 🎀

  • GDBM_SETCACHESIZE, GDBM_CACHESIZE — Set the size of the internal bucket cache. The value should point to a size_t holding the desired cache size, or the constant GDBM_CACHE_AUTO, to select the best cache size automatically.

By default, a newly open database is configured to adapt the cache size to the number of index buckets in the database file. This provides for the best performance. 🔥

Use this option if you wish to limit the memory usage at the expense of performance. If you chose to do so, please bear in mind that cache becomes effective when its size is greater than 2/3 of the number of index bucket counts in the database. The best performance results are achieved when cache size equals the number of buckets.

  • GDBM_GETCACHESIZE — Return the size of the internal bucket cache. The value should point to a size_t variable, where the size will be stored.
  • GDBM_GETFLAGS — Return the flags describing current state of the database. The value should point to an int variable where to store the flags. On success, its value will be similar to the flags used when opening the database, except that it will reflect the current state (which may have been altered by another calls to gdbm_setopt).
  • GDBM_FASTMODE — Enable or disable the fast writes mode, similar to the GDBM_FAST option to gdbm_open.

This option is retained for compatibility with previous versions of GDBM. (Legacy icon behavior tbh.)

  • GDBM_SETSYNCMODE, GDBM_SYNCMODE — Turn on or off immediate disk synchronization after updates. The value should point to an integer: 1 to turn synchronization on, and 0 to turn it off.
NOTE: setting this option entails severe performance degradation and does not necessarily ensure that the resulting database state is consistent, therefore we discourage its use. For a discussion of how to ensure database consistency with minimal performance overhead, see CRASH TOLERANCE below.
  • GDBM_GETSYNCMODE — Return the current synchronization status. The value should point to an int where the status will be stored.
  • GDBM_SETCENTFREE, GDBM_CENTFREE — Enable or disable central free block pool. The default is off, which is how previous versions of GDBM handled free blocks. If set, this option causes all subsequent free blocks to be placed in the global pool, allowing (in theory) more file space to be reused more quickly. The value should point to an integer: TRUE to turn central block pool on, and FALSE to turn it off.

The GDBM_CENTFREE alias is provided for compatibility with earlier versions.

  • GDBM_SETCOALESCEBLKS, GDBM_COALESCEBLKS — Set free block merging to either on or off. The default is off, which is how previous versions of GDBM handled free blocks. If set, this option causes adjacent free blocks to be merged. This can become a CPU expensive process with time, though, especially if used in conjunction with GDBM_CENTFREE. The value should point to an integer: TRUE to turn free block merging on, and FALSE to turn it off.
  • GDBM_GETCOALESCEBLKS — Return the current status of free block merging. The value should point to an int where the status will be stored.
  • GDBM_SETMAXMAPSIZE — Sets maximum size of a memory mapped region. The value should point to a value of type size_t, unsigned long or unsigned. The actual value is rounded to the nearest page boundary (the page size is obtained from sysconf(_SC_PAGESIZE)).
  • GDBM_GETMAXMAPSIZE — Return the maximum size of a memory mapped region. The value should point to a value of type size_t where to return the data.
  • GDBM_SETMMAP — Enable or disable memory mapping mode. The value should point to an integer: TRUE to enable memory mapping or FALSE to disable it.
  • GDBM_GETMMAP — Check whether memory mapping is enabled. The value should point to an integer where to return the status.
  • GDBM_GETDBNAME — Return the name of the database disk file. The value should point to a variable of type char**. A pointer to the newly allocated copy of the file name will be placed there. The caller is responsible for freeing this memory when no longer needed. 🫶 (Don't leak, bestie.)
  • GDBM_GETBLOCKSIZE — Return the block size in bytes. The value should point to int.
int gdbm_fdesc (GDBM_FILE dbf);

Returns the file descriptor of the database dbf. 🎀

CRASH TOLERANCE 💥🦋

By default GNU dbm does not protect the integrity of its databases from corruption or destruction due to failures such as power outages, operating system kernel panics, or application process crashes. Such failures could damage or destroy the underlying database. 😭

Starting with release 1.21 GNU dbm includes a mechanism that, if used correctly, enables post-crash recovery to a consistent state of the underlying database. This mechanism requires OS and filesystem support and must be requested when gdbm is compiled. The crash-tolerance mechanism is a "pure opt-in" feature, in the sense that it has no effects whatsoever except on those applications that explicitly request it. For details, see the chapter Crash Tolerance in the GDBM manual. ✨

🌸 GLOBAL VARIABLES 🌸

okay bestie, these are the global-ish things the library keeps around for you 💖

  • gdbm_error gdbm_errno — this one holds the code of the most recent error that happened. but listen, it's not a C variable in the proper sense, okay? you can read its value, you can assign any value to it, but the moment you try to take its address you get a syntax error. so don't do that 🙈. also it's a per-thread memory location, so each thread gets its own lil copy ✨
  • const char *gdbm_version — a string with the library version number and the build date in it. cute, informative, iconic 💅
  • int const gdbm_version_number[3] — this one's got the library version numbers in a lil trio: major, minor, and patchlevel 🎀

🦋 VERSIONING 🦋

so the version tea is kept in two places. the version of the library itself lives in the gdbm_version_number variable we just talked about. and then, on top of that, the header file gdbm.h defines these macros:

  • GDBM_VERSION_MAJOR — major version number.
  • GDBM_VERSION_MINOR — minor version number.
  • GDBM_VERSION_PATCH — patchlevel number. and heads up, 0 means there's no patchlevel.

you can use these to check whether your header file actually corresponds to the library your program is linked with 👀 (mismatch? not the vibe).

and there's a function for comparing two version numbers:

int gdbm_version_cmp (int const a[3], int const b[3])

it compares two version numbers formatted the same way as gdbm_version_number. it returns a negative number if a is older than b, a positive number if a is newer than b, and 0 if they're equal. no cap, that's the whole thing 🫶

💀 ERROR CODES 💀

okay this is the big list, stay with me, it's giving encyclopedia but every single one matters 🔥

  • GDBM_NO_ERROR — no error occurred. the dream. the fantasy. ✨
  • GDBM_MALLOC_ERROR — memory allocation failed 😭
  • GDBM_BLOCK_SIZE_ERROR — this one gets set by the gdbm_open function when the value of its block_size argument is incorrect and the GDBM_BSEXACT flag is set.
  • GDBM_FILE_OPEN_ERROR — the library couldn't open a disk file. can be set by gdbm_open, gdbm_fd_open, gdbm_dump and gdbm_load.

peek at the system errno variable for the more detailed diagnostics 👀

  • GDBM_FILE_WRITE_ERROR — writing to a disk file failed. can be set by gdbm_open, gdbm_fd_open, gdbm_dump and gdbm_load.

again, check the system errno variable for the detailed tea.

  • GDBM_FILE_SEEK_ERROR — positioning inside a disk file failed. can be set by the gdbm_open function.

and yes, check the system errno variable for a more detailed diagnostics.

  • GDBM_FILE_READ_ERROR — reading from a disk file failed. can be set by gdbm_open, gdbm_dump and gdbm_load.

you already know — inspect the system errno variable for a more detailed diagnostics.

  • GDBM_BAD_MAGIC_NUMBER — the file passed as an argument to the gdbm_open function is not a valid gdbm file: it's got a wrong magic number 🪄❌
  • GDBM_EMPTY_DATABASE — the file passed as an argument to gdbm_open is not a valid gdbm file: it has zero length. this error gets returned unless the flags argument has the GDBM_NEWDB bit set.
  • GDBM_CANT_BE_READER — set by the gdbm_open function if it can't lock the file when called in GDBM_READER mode.
  • GDBM_CANT_BE_WRITER — set by the gdbm_open function if it can't lock the file when called in writer mode.
  • GDBM_READER_CANT_DELETE — set by gdbm_delete, if it tried to operate on a database that's open in read-only mode.
  • GDBM_READER_CANT_STORE — set by gdbm_store if it tried to operate on a database that's open in read-only mode.
  • GDBM_READER_CANT_REORGANIZE — set by gdbm_reorganize if it tried to operate on a database that's open in read-only mode.
  • GDBM_ITEM_NOT_FOUND — the requested item wasn't found. set by gdbm_delete and gdbm_fetch when the requested key value isn't in the database 😔
  • GDBM_REORGANIZE_FAILED — the gdbm_reorganize function can't create a temporary database.
  • GDBM_CANNOT_REPLACE — cannot replace an existing item. set by gdbm_store if the requested key value is found in the database and the flag parameter is not GDBM_REPLACE.
  • GDBM_MALFORMED_DATA — the input data was malformed in some way. when it comes back from gdbm_load, it means the input file wasn't a valid gdbm dump file. when it comes back from gdbm_store, it means either the key or content parameter had its dptr field set to NULL.

also: GDBM_ILLEGAL_DATA is an alias for this error code, kept around for backward compatibility. periodt.

  • GDBM_OPT_ALREADY_SET — the requested option can only be set once, and it was already set. as of version 1.21, this error code is no longer used. in prior versions it could have been returned by the gdbm_setopt function when setting the GDBM_CACHESIZE value.
  • GDBM_OPT_BADVAL — the option argument isn't valid, or the value argument points to an invalid value, in a call to the gdbm_setopt function.

GDBM_OPT_ILLEGAL is an alias for this error code, kept for backward compatibility. modern applications should not use it 🙅‍♀️

  • GDBM_BYTE_SWAPPED — the gdbm_open function is trying to open a database that was created on a machine with a different byte ordering.
  • GDBM_BAD_FILE_OFFSET — the gdbm_open function sets this error code if the file it's trying to open has a wrong magic number.
  • GDBM_BAD_OPEN_FLAGS — set by the gdbm_dump function if it's supplied an invalid flags argument.
  • GDBM_FILE_STAT_ERROR — getting information about a disk file failed. the system errno will give more details about the error.

this error can be set by: gdbm_open, gdbm_reorganize.

  • GDBM_FILE_EOF — end of file was hit where more data was expected to be present. this can happen when fetching data from the database, and it usually means the database is truncated or otherwise corrupted 💀

this error can be set by any GDBM function that does I/O. some of these functions are: gdbm_delete, gdbm_exists, gdbm_fetch, gdbm_export, gdbm_import, gdbm_reorganize, gdbm_firstkey, gdbm_nextkey, gdbm_store.

  • GDBM_NO_DBNAME — the output database name isn't specified. set by gdbm_load if the first argument points to NULL and the input file doesn't specify the database name.
  • GDBM_ERR_FILE_OWNER — set by gdbm_load if it can't restore the database file owner. it's a mild error condition, meaning the data have been restored successfully — only changing the target file owner failed. check the system errno variable for a more detailed diagnostics.
  • GDBM_ERR_FILE_MODE — set by gdbm_load if it can't restore the database file mode. it's a mild error condition, meaning the data have been restored successfully — only changing the target file owner failed. check the system errno variable for a more detailed diagnostics.
  • GDBM_NEED_RECOVERY — the database is in an inconsistent state and needs recovery. call gdbm_recover if you get this one 🚑
  • GDBM_BACKUP_FAILED — the GDBM engine can't create a backup copy of the file.
  • GDBM_DIR_OVERFLOW — the bucket directory would overflow the size limit during an attempt to split a hash bucket. this can pop up while storing a new key.
  • GDBM_BAD_BUCKET — an invalid index bucket was encountered in the database. database recovery is needed.
  • GDBM_BAD_HEADER — set by gdbm_open and gdbm_fd_open if the first block read from the database file doesn't contain a valid GDBM header.
  • GDBM_BAD_AVAIL — the available space stack is invalid. can be set by gdbm_open and gdbm_fd_open if extended database verification was requested (GDBM_XVERIFY). it's also set by the gdbm_avail_verify function.

the database needs recovery.

  • GDBM_BAD_HASH_TABLE — the hash table in a bucket is invalid. can be set by: gdbm_delete, gdbm_exists, gdbm_fetch, gdbm_firstkey, gdbm_nextkey, and gdbm_store.

the database needs recovery.

  • GDBM_BAD_DIR_ENTRY — a bad directory entry was found in the bucket. database recovery is needed.
  • GDBM_FILE_CLOSE_ERROR — the gdbm_close function couldn't close the database file descriptor. the system errno variable contains the corresponding error code.
  • GDBM_FILE_SYNC_ERROR — cached content couldn't be synchronized to disk. examine the errno variable to get more info.

database recovery is needed.

  • GDBM_FILE_TRUNCATE_ERROR — the file cannot be truncated. examine the errno variable to get more info.

this error is set by gdbm_open and gdbm_fd_open when called with the GDBM_NEWDB flag.

  • GDBM_BUCKET_CACHE_CORRUPTED — the bucket cache structure is corrupted. database recovery is needed.
  • GDBM_BAD_HASH_ENTRY — this one gets set during sequential access (@pxref{Sequential}), if the next hash table entry doesn't contain the expected key. that means the bucket is malformed or corrupted, and the database needs recovery.
  • GDBM_ERR_SNAPSHOT_CLONE — set by the gdbm_failure_atomic function if it couldn't clone the database file into a snapshot. check the system errno variable for the underlying cause. and heads up: if errno is EINVAL or ENOSYS, crash tolerance settings will be removed from the database.
  • GDBM_ERR_REALPATH — set by the gdbm_failure_atomic function if the call to the realpath function failed. realpath is used to figure out the actual path names of the snapshot files. examine the system errno variable for details.
  • GDBM_ERR_USAGE — function usage error. that includes invalid argument values, and the like 🙈

🦋 DBM COMPATIBILITY ROUTINES 🦋

Okay bestie, storytime: GDBM ships a whole extra compatibility library called libgdbm_compat, and it's for all the old-school programs out there that still expect the classic UNIX dbm or ndbm interfaces — think stuff like, e.g. Sendmail. The way that this library is optional though? Not every binary distribution has it, so it might just be absent from yours. 🙈

And because a full deep-dive on the compatibility API would be its own whole saga (way beyond the scope of this doc, fr fr), we're only giving you a lil' short reference down here. Want the full tea? Go read the GDBM Manual, chapter Compatibility with standard dbm and ndbm. 💅

🌸 DBM compatibility routines 🌸

In dbm compatibility mode there's a big rule: only one file may be opened at a time. Also everyone using it is assumed to be a writer. And if the database file happens to be read only? It's gonna fail as a writer — but it'll still get opened as a reader, so, slay, it lives. 🫶

Also important: all returned pointers in datum structures point to data that the compatibility library will free. Treat them like static pointers, exactly the way standard UNIX dbm does. Do not go freeing them yourself, I am begging. 😭

The following interfaces are provided:

#include <dbm.h>

int dbminit (const char *name);
int store (datum key, datum content);
datum fetch (datum key);
int delete (datum key);
datum firstkey (void);
datum nextkey (datum key);
int dbmclose (void);

🎀 NDBM Compatibility routines 🎀

This mode is the glow-up: multiple databases can be opened. Each database gets its own lil' handle of type DBM * to identify it. 💖

Same deal as the original NDBM though — all returned pointers in datum structures point to data that will be freed by the compatibility library, so treat them as static pointers. Periodt.

The following interfaces are provided:

#include <ndbm.h>

DBM *dbm_open (const char *name, int flags, int mode);
void dbm_close (DBM *file);
datum dbm_fetch (DBM *file, datum key);
int dbm_store (DBM *file, datum key, datum content, int flags);
int dbm_delete (DBM *file, datum key);
datum dbm_firstkey (DBM *file);
datum dbm_nextkey (DBM *file, datum key);
int dbm_error (DBM *file);
int dbm_clearerr (DBM *file);
int dbm_pagfno (DBM *file);
int dbm_dirfno (DBM *file);
int dbm_rdonly (DBM *file);

✨ LINKING ✨

To get at this library you pass -lgdbm as the last parameter on the compile line, like:

gcc -o prog prog.c -lgdbm

And if you wanna use the dbm or ndbm compatibility routines? You gotta link in the gdbm_compat library too. For example:

gcc -o prog proc.c -lgdbm -lgdbm_compat
Note the spelling difference in the examples, bestie — the first one compiles prog.c, the second compiles proc.c. That's literally what the original says, so I'm keeping it exactly as-is. 👀

💀 BUG REPORTS 💀

Found a bug? Send your bug reports to <bug-gdbm@gnu.org>. Don't be shy, they wanna hear it. 🐛

🌈 SEE ALSO 🌈

👑 AUTHORS 👑

by Philip A. Nelson, Jason Downs and Sergey Poznyakoff; crash tolerance by Terence Kelly. Iconic lineup, no cap. 💜

Copyright © 1990 - 2025 Free Software Foundation, Inc.

GDBM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.

GDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with GDBM. If not, see <http://gnu.org/licenses/gpl.html>

🫶 CONTACTS 🫶

Wanna contact the original author? Here's how:

   e-mail:  phil@cs.wwu.edu
  us-mail:  Philip A. Nelson
Computer Science Department
Western Washington University
Bellingham, WA 98226

Wanna contact the current maintainers? Here's how:

   e-mail:  downsj@downsj.com

and

   e-mail:  gray@gnu.org

Got questions or feedback specifically about crash tolerance? You can reach Terence Kelly at:

   e-mail:  tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }

aaaand that's the whole page, bestie!! 🎉 this little gem is GDBM(3), dated March 6, 2025, straight from the GDBM source — go forth and slay those databases 💖✨🌸

📦 where this page comes from