gnu dbm · gnu dbm (gdbm) is a library of database functions that use extensible hashing and works...

GNU dbm

A Database Manager

by Philip A. Nelson, Jason Downs and Sergey Poznyakoff

Manual by Pierre Gaumond, Philip A. Nelson, Jason Downsand Sergey Poznyakoff

Edition 1.19

for GNU dbm, Version 1.19

Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor Boston, MA02110-1301, USACopyright c© 1989-1999, 2007-2020 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this document under the terms ofthe GNU Free Documentation License, Version 1.3 or any later version published by theFree Software Foundation; with no Invariant Sections, no Front-Cover, and no Back-Covertexts. A copy of the license is included in the section entitled “GNU Free DocumentationLicense.”

i

Short Contents

1 Copying Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Introduction to GNU dbm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Opening the database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Closing the database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Number of Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

6 Inserting and replacing records in the database. . . . . . . . . . . . . . 9

7 Searching for records in the database. . . . . . . . . . . . . . . . . . . . . 10

8 Removing records from the database. . . . . . . . . . . . . . . . . . . . . 11

9 Sequential access to records. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

10 Database reorganization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

11 Database Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

12 Export and Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

13 Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

14 Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

15 Setting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

16 File Locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

17 Useful global variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

18 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

19 Compatibility with standard dbm and ndbm. . . . . . . . . . . . . . . . 33

20 Examine and modify a GDBM database. . . . . . . . . . . . . . . . . . 37

21 The gdbm_dump utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

22 The gdbm_load utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

23 Exit codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

24 Problems and bugs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

25 Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

A GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

ii

Table of Contents

1 Copying Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Introduction to GNU dbm. . . . . . . . . . . . . . . . . . . . . . . 2

3 Opening the database.. . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Closing the database. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Number of Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

6 Inserting and replacing records in thedatabase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

7 Searching for records in the database. . . . . . . . 10

8 Removing records from the database. . . . . . . . 11

9 Sequential access to records. . . . . . . . . . . . . . . . . . 12

10 Database reorganization. . . . . . . . . . . . . . . . . . . . . 14

11 Database Synchronization . . . . . . . . . . . . . . . . . . . 15

12 Export and Import . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

13 Error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

14 Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

15 Setting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

16 File Locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

17 Useful global variables. . . . . . . . . . . . . . . . . . . . . . . 28

18 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

iii

19 Compatibility with standard dbm and ndbm.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

19.1 NDBM interface functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3319.2 DBM interface functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

20 Examine and modify a GDBM database. . . 3720.1 gdbmtool invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3720.2 gdbmtool interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

20.2.1 Shell Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3920.2.2 Gdbmtool Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4220.2.3 Data Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4520.2.4 Startup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

21 The gdbm_dump utility . . . . . . . . . . . . . . . . . . . . . . . . . 49

22 The gdbm_load utility . . . . . . . . . . . . . . . . . . . . . . . . . 50

23 Exit codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

24 Problems and bugs. . . . . . . . . . . . . . . . . . . . . . . . . . . 52

25 Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . 53

Appendix A GNU Free Documentation License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 1: Copying Conditions. 1

1 Copying Conditions.

This library is free; this means that everyone is free to use it and free to redistribute iton a free basis. GNU dbm (gdbm) is not in the public domain; it is copyrighted and thereare restrictions on its distribution, but these restrictions are designed to permit everythingthat a good cooperating citizen would want to do. What is not allowed is to try to preventothers from further sharing any version of gdbm that they might get from you.

Specifically, we want to make sure that you have the right to give away copies gdbm, thatyou receive source code or else can get it if you want it, that you can change these functionsor use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone elseof these rights. For example, if you distribute copies gdbm, you must give the recipients allthe rights that you have. You must make sure that they, too, receive or can get the sourcecode. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that thereis no warranty for anything in the gdbm distribution. If these functions are modified bysomeone else and passed on, we want their recipients to know that what they have is notwhat we distributed, so that any problems introduced by others will not reflect on ourreputation.

Gdbm is currently distributed under the terms of the GNU General Public License, Version3. (NOT under the GNU General Library Public License.) A copy the GNU General PublicLicense is included with the distribution of gdbm.

Chapter 2: Introduction to GNU dbm. 2

2 Introduction to GNU dbm.

GNU dbm (gdbm) is a library of database functions that use extensible hashing and workssimilar to the standard UNIX dbm functions. These routines are provided to a programmerneeding to create and manipulate a hashed database. (gdbm is NOT a complete databasepackage for an end user.)

The basic use of gdbm is to store key/data pairs in a data file. Each key must be uniqueand each key is paired with only one data item. The keys can not be directly accessed insorted order. The basic unit of data in gdbm is the structure:

typedef struct{

char *dptr;int dsize;

} datum;

This structure allows for arbitrary sized keys and data items.The key/data pairs are stored in a gdbm disk file, called a gdbm database. An application

must open a gdbm database to be able manipulate the keys and data contained in thedatabase. gdbm allows an application to have multiple databases open at the same time.When an application opens a gdbm database, it is designated as a reader or a writer. Agdbm database can be opened by at most one writer at a time. However, many readers mayopen the database simultaneously. Readers and writers can not open the gdbm database atthe same time.

To use the gdbm functions, the programmer must first include the header file gdbm.h.This file defines, among others, the GDBM_FILE data type, an opaque pointer to the struc-

ture that represents the opened gdbm database. To access the database, the programmermust first open it using the gdbm_open function. The function takes several arguments, thename of the database file being one of them, and returns a GDBM_FILE object on success.This object is then passed to other functions in order to manipulate the database. Whenthe database is no longer needed, the programmer closes it using the gdbm_close call.

These and other functions are discussed in detail in chapters that follow. Here we showan example illustrating the use of gdbm to look up a key in the database.

#include <stdio.h>#include <string.h>#include <gdbm.h>

intmain (int argc, char **argv){GDBM_FILE gdbf; /* Database file object pointer */datum key, content; /* Key and content data */int status = 0; /* Exit status of the program: 0 - OK, 1 - key

not found, 2 - error. */

/** Validate arguments.


*/if (argc != 3){fprintf (stderr, "usage: %s DBFILE KEY\n", argv[0]);return 2;

}

/** Open the database. The GDBM_READER flag indicates that we only intend* to read from it.*/gdbf = gdbm_open (argv[1], 0, GDBM_READER, 0, NULL);if (gdbf == NULL){fprintf (stderr, "can’t open database: %s\n",

gdbm_strerror (gdbm_errno));}

/** Prepare the lookup key. Notice, that the terminating \0 character* is not counted in the dsize computation.*/key.dptr = argv[2];key.dsize = strlen (argv[2]);

/** Look up the key in the database.*/content = gdbm_fetch (gdbf, key);

/** Analyze the return.*/if (content.dptr != NULL){/** The key is found. Print the content on the stdout and* indicate success.*/fwrite (content.dptr, content.dsize, 1, stdout);putchar (’\n’);status = 0;

}else if (gdbm_errno == GDBM_ITEM_NOT_FOUND){/** There is no such key in the database.


*/fprintf (stderr, "no such key\n");status = 1;

}else{/** An error occurred.*/fprintf (stderr, "%s\n", gdbm_db_strerror (gdbf));status = 2;

}

/** Close the database and return.*/gdbm_close (gdbf);return status;

}

To compile this example, runcc -oexample example.c -lgdbm

To run it, you will need an example database. The easiest way to create it is by using thegdbtool program, which is part of the gdbm package (see Chapter 20 [gdbmtool], page 37):

$ gdbmtool test.gdbm store foo bar

This creates database file test.gdbm and stores a single record in it. The record’s key is‘foo’, and the value is ‘bar’. Now you can run the example program to see how it works:

$ ./example test.gdbm foobar$ ./example test.gdbm bazno such key

Chapter 3: Opening the database. 5

3 Opening the database.

[gdbm interface]GDBM_FILE gdbm_open (const char *name, int block_size, intflags, int mode, void (*fatal func)(const char *))

Initializes gdbm system. If the file has a size of zero bytes, a file initialization procedureis performed, setting up the initial structure in the file.

The arguments are:

name The name of the file (the complete name, gdbm does not append anycharacters to this name).

block size It is used during initialization to determine the size of various constructs.It is the size of a single transfer from disk to memory. This parameteris ignored if the file has been previously initialized. If the value is lessthan 512, the file system block size is used instead. The size is adjustedso that the block can hold exact number of directory entries, so thatthe effective block size can be slightly greater than requested. However,if the ‘GDBM_BSEXACT’ flag is set and the size needs to be adjusted, thefunction will return with error status, setting the ‘gdbm_errno’ variableto ‘GDBM_BLOCK_SIZE_ERROR’.

flags If flags is set to ‘GDBM_READER’, the user wants to just read the databaseand any call to gdbm_store or gdbm_delete will fail. Many readers canaccess the database at the same time. If flags is set to ‘GDBM_WRITER’,the user wants both read and write access to the database and requiresexclusive access. If flags is set to ‘GDBM_WRCREAT’, the user wants bothread and write access to the database and wants it created if it doesnot already exist. If flags is set to ‘GDBM_NEWDB’, the user want a newdatabase created, regardless of whether one existed, and wants read andwrite access to the new database.The following may also be logically or’d into the database flags:‘GDBM_SYNC’, which causes all database operations to be synchronizedto the disk, ‘GDBM_NOLOCK’, which prevents the library from performingany locking on the database file, and ‘GDBM_NOMMAP’, which disables thememory mapping mechanism. The option ‘GDBM_FAST’ is now obsolete,since gdbm defaults to no-sync mode.If this flag is set and the requested block size cannot be used withoutadjustment, gdbm_open will refuse to create the databases. In this caseit will set the ‘gdbm_errno’ variable to ‘GDBM_BLOCK_SIZE_ERROR’ andreturn ‘NULL’.If the host ‘open’ call (see Section “open” in open(2) man page) supportsthe ‘O_CLOEXEC’ flag, the ‘GDBM_CLOEXEC’ can be or’d into the flags, toenable the close-on-exec flag for the database file descriptor.

mode File mode (see Section “change permissions of a file” in chmod(2) manpage, and see Section “open a file” in open(2) man page), which is usedif the file is created).

Chapter 3: Opening the database. 6

fatal func A function for gdbm to call if it detects a fatal error. The only parameterof this function is a string. If the value of ‘NULL’ is provided, gdbm willuse a default function.

The return value, is the pointer needed by all other functions to access that gdbm file.If the return is the ‘NULL’ pointer, gdbm_open was not successful. The errors can befound in gdbm_errno variable (see Chapter 17 [Variables], page 28). Available errorcodes are discussed in Chapter 18 [Error codes], page 30.In all of the following calls, the parameter dbf refers to the pointer returned fromgdbm_open.

[gdbm interface]GDBM_FILE gdbm_fd_open (int fd, const char *name, intblock_size, int flags, int mode, void (*fatal func)(const char *))

Alternative function for opening a GDBM database. The fd argument is the filedescriptor of the database file obtained by a call to open(2), creat(2) or simi-lar functions. The descriptor is not dup’ed, and will be closed when the returnedGDBM FILE is closed. Use dup(2) if that is not desirable.

[gdbm interface]int gdbm_copy_meta (GDBM FILE dst, GDBM FILE src)Copy file ownership and mode from src to dst.

Chapter 4: Closing the database. 7

4 Closing the database.

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

[gdbm interface]int gdbm_close (GDBM FILE dbf)This function closes the gdbm file and frees all memory associated with it. The pa-rameter is:

dbf The pointer returned by gdbm_open.

Gdbm_close returns 0 on success. On error, it sets gdbm_errno and system errnovariables to the codes describing the error and returns -1.

Chapter 5: Number of Records 8

5 Number of Records

[gdbm interface]int gdbm_count (GDBM FILE dbf, gdbm count t *pcount)Counts number of records in the database dbf. On success, stores it in the memorylocation pointed to by pcount and returns 0. On error, sets gdbm_errno (if relevant,also errno) and returns -1.

Chapter 6: Inserting and replacing records in the database. 9

6 Inserting and replacing records in the database.

[gdbm interface]int gdbm_store (GDBM FILE dbf, datum key, datum content,int flag)

The function gdbm_store inserts or replaces records in the database.The parameters are:


key The search key.

content The data to be associated with the key.

flag Defines the action to take when the key is already in the database. Thevalue ‘GDBM_REPLACE’ (defined in gdbm.h) asks that the old data be re-placed by the new content. The value ‘GDBM_INSERT’ asks that an errorbe returned and no action taken if the key already exists.

This function can return the following values:

0 Success. The value of content is keyed by key in the database.

-1 The item was not stored in the database because the caller was not anofficial writer or either key or content have a ‘NULL’ ‘dptr’ field.Both key and content must have the ‘dptr’ field be a non-‘NULL’ value.Since a ‘NULL’ ‘dptr’ field is used by other functions to indicate an error,it cannot be valid data.

+1 The item was not stored because the argument flag was ‘GDBM_INSERT’and the key was already in the database.

If you store data for a key that is already in the data base, gdbm replaces the old datawith the new data if called with ‘GDBM_REPLACE’. You do not get two data items for thesame key and you do not get an error from gdbm_store.

The size of datum in gdbm is restricted only by the maximum value for an object of typeint (type of the dsize member of datum).

Chapter 7: Searching for records in the database. 10

7 Searching for records in the database.

[gdbm interface]datum gdbm_fetch (GDBM FILE dbf, datum key)Looks up a given key and returns the information associated with it. The ‘dptr’ fieldin the structure that is returned points to a memory block allocated by malloc. It isthe caller’s responsibility to free it when no longer needed.If the ‘dptr’ is ‘NULL’, inspect the value of the gdbm_errno variable (see Chapter 17[Variables], page 28). If it is ‘GDBM_ITEM_NOT_FOUND’, no data was found. Any othervalue means an error occurred. Use gdbm_strerror function to convert gdbm_errnoto a human-readable string.The parameters are:


key The search key.

An example of using this function:content = gdbm_fetch (dbf, key);if (content.dptr == NULL){fprintf(stderr, "key not found\n");

}else{/* do something with content.dptr */

}

You may also search for a particular key without retrieving it:

[gdbm interface]int gdbm_exists (GDBM FILE dbf, datum key)Checks whether the key exists in the database dbf.If key is found, returns ‘true’ (‘1’). If it is not found, returns ‘false’ (‘0’) and setsgdbm_errno to ‘GDBM_NO_ERROR’ (‘0’).On error, returns ‘0’ and sets gdbm_errno to a non-‘0’ error code.The parameters are:


key The search key.

Chapter 8: Removing records from the database. 11

8 Removing records from the database.

To remove some data from the database, use the gdbm_delete function.

[gdbm interface]int gdbm_delete (GDBM FILE dbf, datum key)Deletes the data associated with the given key, if it exists in the database dbf.The parameters are:


datum keyThe search key.

The function returns ‘-1’ if the item is not present or the requester is a reader. Thereturn of ‘0’ marks a successful delete.

Chapter 9: Sequential access to records. 12

9 Sequential access to records.

The next two functions allow for accessing all items in the database. This access is notkey sequential, but it is guaranteed to visit every key in the database once. The order hasto do with the hash values. gdbm_firstkey starts the visit of all keys in the database.gdbm_nextkey finds and reads the next entry in the hash structure for dbf.

[gdbm interface]datum gdbm_firstkey (GDBM FILE dbf)Initiate sequential access to the database dbf. The returned value is the first keyaccessed in the database. If the ‘dptr’ field in the returned datum is ‘NULL’, inspectthe gdbm_errno variable (see Chapter 17 [Variables], page 28). The value of GDBM_ITEM_NOT_FOUND means that the database contains no data. Other value means anerror occurred.

On success, ‘dptr’ points to a memory block obtained from malloc, which holds thekey value. The caller is responsible for freeing this memory block when no longerneeded.

[gdbm interface]datum gdbm_nextkey (GDBM FILE dbf, datum prev)This function continues iteration over the keys in dbf, initiated by gdbm_firstkey.The parameter prev holds the value returned from a previous call to gdbm_nextkeyor gdbm_firstkey.

The function returns next key from the database. If the ‘dptr’ field in the returneddatum is ‘NULL’ inspect the gdbm_errno variable (see Chapter 17 [Variables], page 28).The value of GDBM_ITEM_NOT_FOUND means that all keys in the database has beenvisited. Any other value means an error occurred.

Otherwise, ‘dptr’ points to a memory block obtained from malloc, which holds thekey value. The caller is responsible for freeing this memory block when no longerneeded.

These functions are intended to visit the database in read-only algorithms, for instance,to validate the database or similar operations. The usual algorithm for sequential access is:

key = gdbm_firstkey (dbf);while (key.dptr){

datum nextkey;

/* do something with the key */...

/* Obtain the next key */nextkey = gdbm_nextkey (dbf, key);/* Reclaim the memory used by the key */free (key.dptr);/* Use nextkey in the next iteration. */key = nextkey;

}

Chapter 9: Sequential access to records. 13

Don’t use gdbm_delete or gdbm_store in such a loop. File visiting is based on a hashtable. The gdbm_delete function re-arranges the hash table to make sure that any collisionsin the table do not leave some item un-findable. The original key order is not guaranteedto remain unchanged in all instances. So it is possible that some key will not be visited ifa loop like the following is executed:

key = gdbm_firstkey (dbf);while (key.dptr){

datum nextkey;if (some condition){

gdbm_delete (dbf, key);}nextkey = gdbm_nextkey (dbf, key);free (key.dptr);key = nextkey;

}

Chapter 10: Database reorganization. 14

10 Database reorganization.

The following function should be used very seldom.

[gdbm interface]int gdbm_reorganize (GDBM FILE dbf)Reorganizes the database.The parameter is:


If you have had a lot of deletions and would like to shrink the space used by the gdbmfile, this function will reorganize the database. This results, in particular, in shortening thelength of a gdbm file by removing the space occupied by deleted records.

This reorganization requires creating a new file and inserting all the elements in theold file dbf into the new file. The new file is then renamed to the same name as the oldfile and dbf is updated to contain all the correct information about the new file. If anerror is detected, the return value is negative. The value zero is returned after a successfulreorganization.

Chapter 11: Database Synchronization 15

11 Database Synchronization

Unless your database was opened with the ‘GDBM_SYNC’ flag, gdbm does not wait for writesto be flushed to the disk before continuing. This allows for faster writing of databases at therisk of having a corrupted database if the application terminates in an abnormal fashion.The following function allows the programmer to make sure the disk version of the databasehas been completely updated with all changes to the current time.

[gdbm interface]int gdbm_sync (GDBM FILE dbf)Synchronizes the changes in dbf with its disk file. The parameter is a pointer returnedby gdbm_open.This function would usually be called after a complete set of changes have beenmade to the database and before some long waiting time. The gdbm_close functionautomatically calls the equivalent of gdbm_sync so no call is needed if the databaseis to be closed immediately after the set of changes have been made.Gdbm_sync returns 0 on success. On error, it sets gdbm_errno and system errnovariables to the codes describing the error and returns -1.

Chapter 12: Export and Import 16

12 Export and Import

Gdbm databases can be converted into so-called flat format files. Such files cannot be usedfor searching, their sole purpose is to keep the data from the database for restoring it whenthe need arrives. There are two flat file formats, which differ in the way they representthe data and in the amount of meta-information stored. Both formats can be used, forexample, to migrate between the different versions of gdbm databases. Generally speaking,flat files are safe to send over the network, and can be used to recreate the database onanother machine. The recreated database is guaranteed to be a byte-to-byte equivalent ofthe database from which the flat file was created. This does not necessarily mean, however,that this file can be used in the same way as the original one. For example, if the originaldatabase contained non-ASCII data (e.g. C structures, integers etc.), the recreated databasecan be of any use only if the target machine has the same integer size and byte ordering asthe source one and if its C compiler uses the same packing conventions as the one whichgenerated C which populated the original database. In general, such binary databases arenot portable between machines, unless you follow some stringent rules on what data iswritten to them and how it is interpreted.

The GDBM version 1.19 supports two flat file formats. The binary flat file format wasfirst implemented in GDBM version 1.9.1. This format stores only key/data pairs, it doesnot keep information about the database file itself. As its name implies, files in this formatare binary files.

The ascii flat file format encodes all data in Base64 and stores not only key/data pairs,but also the original database file metadata, such as file name, mode and ownership. Filesin this format can be sent without additional encapsulation over transmission channels thatnormally allow only ASCII data, such as, e.g. SMTP. Due to additional metadata they allowfor restoring an exact copy of the database, including file ownership and privileges, whichis especially important if the database in question contained some security-related data.

We call a process of creating a flat file from a database exporting or dumping thisdatabase. The reverse process, creating the database from a flat file is called importing orloading the database.

[gdbm interface]int gdbm_dump (GDBM FILE dbf, const char *filename, intformat, int open_flags, int mode)

Dumps the database file to the named file in requested format. Arguments are:

dbf A pointer to the source database, returned by a prior call to gdbm_open.

filename Name of the dump file.

format Output file format. Allowed values are: ‘GDBM_DUMP_FMT_BINARY’ to cre-ate a binary dump and ‘GDBM_DUMP_FMT_ASCII’ to create an ASCII dumpfile.

open flags How to create the output file. If flag is ‘GDBM_WRCREAT’ the file will becreated if it does not exist. If it does exist, the gdbm_dump will fail.If flag is ‘GDBM_NEWDB’, the function will create a new output file, replacingit if it already exists.

mode The permissions to use when creating the output file. See Section “opena file” in open(2) man page, for a detailed discussion.


[gdbm interface]int gdbm_load (GDBM FILE *pdbf, const char *filename, intflag, int meta_mask, unsigned long *errline)

Loads data from the dump file filename into the database pointed to by pdbf. Thelatter can point to ‘NULL’, in which case the function will try to create a new database.If it succeeds, the function will return, in the memory location pointed to by pdbf, apointer to the newly created database. If the dump file carries no information aboutthe original database file name, the function will set gdbm_errno to ‘GDBM_NO_DBNAME’and return ‘-1’, indicating failure.

The flag has the same meaning as the flag argument to the gdbm_store function (seeChapter 6 [Store], page 9).

The meta mask argument can be used to disable restoring certain bits of file’s meta-data from the information in the input dump file. It is a binary OR of zero or moreof the following:

GDBM META MASK MODEDo not restore file mode.

GDBM META MASK OWNERDo not restore file owner.

The function returns 0 upon successful completion or -1 on fatal errors and 1 on mild(non-fatal) errors.

If a fatal error occurs, gdbm_errno will be set to one of the following values:

GDBM FILE OPEN ERRORInput file (filename) cannot be opened. The errno variable can be usedto get more detail about the failure.

GDBM MALLOC ERRORNot enough memory to load data.

GDBM FILE READ ERRORReading from filename failed. The errno variable can be used to getmore detail about the failure.

GDBM ILLEGAL DATAInput contained some illegal data.

GDBM ITEM NOT FOUNDThis error can occur only when the input file is in ASCII format. It indi-cates that the data part of the record about to be read lacked length spec-ification. Application developers are advised to treat this error equallyas ‘GDBM_ILLEGAL_DATA’.

Mild errors mean that the function was able to successfully load and restore the data,but was unable to change database file metadata afterward. The table below listspossible values for gdbm_errno in this case. To get more detail, inspect the systemerrno variable.

GDBM ERR FILE OWNERThe function was unable to restore database file owner.


GDBM ERR FILE MODEThe function was unable to restore database file mode (permission bits).

If an error occurs while loading data from an input file in ASCII format, the numberof line in which the error occurred will be stored in the location pointed to by theerrline parameter, unless it is ‘NULL’.If the line information is not available or applicable, errline will be set to ‘0’.

[gdbm interface]int gdbm_dump_to_file (GDBM FILE dbf, FILE *fp, intformat)

This is an alternative entry point to gdbm_dump (which see). Arguments are:

dbf A pointer to the source database, returned by a call to gdbm_open.

fp File to write the data to.

format Format of the dump file. See the format argument to the gdbm_dumpfunction.

[gdbm interface]int gdbm_load_from_file (GDBM FILE *pdbf, FILE *fp, intreplace, int meta_mask, unsigned long *line)

This is an alternative entry point to gdbm_dump. It writes the output to fp whichmust be a file open for writing. The rest of arguments is the same as for gdbm_load(excepting of course flag, which is not needed in this case).

[gdbm interface]int gdbm_export (GDBM FILE dbf, const char *exportfile,int flag, int mode)

This function is retained for compatibility with GDBM 1.10 and earlier. It dumpsthe database to a file in binary dump format and is entirely equivalent to

gdbm_dump(dbf, exportfile, GDBM_DUMP_FMT_BINARY, flag, mode)

[gdbm interface]int gdbm_export_to_file (GDBM FILE dbf, FILE *fp)This is an alternative entry point to gdbm_export. This function writes to file fp abinary dump of the database dbf.

[gdbm interface]int gdbm_import (GDBM FILE dbf, const char *importfile,int flag)

This function is retained for compatibility with GDBM 1.10 and earlier. It loads thefile importfile, which must be a binary flat file, into the database dbf and is equivalentto the following construct:

dbf = gdbm_open (importfile, 0,flag == GDBM_REPLACE ?GDBM_WRCREAT : GDBM_NEWDB,

0600, NULL);gdbm_load (&dbf, exportfile, 0, flag, NULL)

[gdbm interface]int gdbm_import_from_file (GDBM FILE dbf, FILE *fp, intflag)

An alternative entry point to gdbm_import. Reads the binary dump from the file fpand stores the key/value pairs to dbf. See Chapter 6 [Store], page 9, for a descriptionof flag.This function is equivalent to:


dbf = gdbm_open (importfile, 0,flag == GDBM_REPLACE ?GDBM_WRCREAT : GDBM_NEWDB,

0600, NULL);gdbm_load_from_file (dbf, fp, flag, 0, NULL);

Chapter 13: Error handling. 20

13 Error handling.

The global variable gdbm_errno (see Chapter 17 [Variables], page 28) keeps the error codeof the most recent error encountered by GDBM functions.

To convert this code to human-readable string, use the following function:

[gdbm interface]const char * gdbm_strerror (gdbm error errno)Converts errno (which is an integer value) into a human-readable descriptive text.Returns a pointer to a static string. The caller must not alter or free the returnedpointer.

Detailed information about the most recent error that occurred while operating on aGDBM file is stored in the GDBM_FILE object itself. To retrieve it, the following functionsare provided:

[gdbm interface]gdbm_error gdbm_last_errno (GDBM FILE dbf)Returns the code of the most recent error encountered when operating on dbf.

[gdbm interface]int gdbm_last_syserr (GDBM FILE dbf)Returns the value of the system errno variable associated with the most recent error.

Notice, that not all GDBM errors have an associated system error code. The followingare the ones that have:

• GDBM FILE OPEN ERROR• GDBM FILE WRITE ERROR• GDBM FILE SEEK ERROR• GDBM FILE READ ERROR• GDBM FILE STAT ERROR• GDBM BACKUP FAILED

For other errors, gdbm_last_syserr will return 0.

[gdbm interface]int gdbm_check_syserr (gdbm errno err)Returns 1, if system errno value should be checked to get more info on the errordescribed by GDBM code err.

To get a human-readable description of the recent error for a particular database file,use the gdbm_db_strerror function:

[gdbm interface]const char * gdbm_db_strerror (GDBM FILE dbf)Returns textual description of the most recent error encountered when operating onthe database dbf. The resulting string is often more informative than what would bereturned by ‘gdbm_strerror(gdbm_last_errno(dbf))’. In particular, if there is asystem error associated with the recent failure, it will be described as well.

[gdbm interface]void gdbm_clear_error (GDBM FILE dbf)Clears the error state for the database dbf. Normally, this function is called upon theentry to any GDBM function.

Chapter 13: Error handling. 21

Certain errors (such as write error when saving stored key) can leave database file ininconsistent state. When such a critical error occurs, the database file is marked as needingrecovery. Subsequent calls to any GDBM functions for that database file (except gdbm_recover), will return immediately with GDBM error value GDBM_NEED_RECOVERY. Addi-tionally, the following function can be used to check the state of the database file:

[gdbm interface]int gdbm_needs_recovery (GDBM FILE dbf)Returns 1 if the database file dbf is in inconsistent state and needs recovery.

The only way to bring the database back to operational state is to call the gdbm_recoverfunction (see Chapter 14 [Recovery], page 22).

Chapter 14: Recovery 22

14 Recovery

Certain errors (such as write error when saving stored key) can leave database file in in-consistent state. When such a critical error occurs, the database file is marked as needingrecovery. Subsequent calls to any GDBM functions for that database file (except gdbm_recover), will return immediately with GDBM error value GDBM_NEED_RECOVERY.

To escape from this state and bring the database back to operational state, use thefollowing function:

[gdbm interface]int gdbm_recover (GDBM FILE dbf, gdbm recovery *rcvr, intflags)

Check the database file dbf and fix eventual errors. The rcvr argument points toa structure that has input members, providing additional information to alter thebehavior of gdbm_recover, and output members, which are used to return additionalstatistics about the recovery process (rcvr can be NULL if no such information isneeded).Each input member has a corresponding flag bit, which must be set in flags, in orderto instruct the function to use it.The gdbm_recover type is defined as:

typedef struct gdbm_recovery_s{/* Input members.

These are initialized before call to gdbm_recover.The flags argument specifies which of them are initialized. */

void (*errfun) (void *data, char const *fmt, ...);void *data;size_t max_failed_keys;size_t max_failed_buckets;size_t max_failures;

/* Output members.The gdbm_recover function fills these before returning. */

size_t recovered_keys;size_t recovered_buckets;size_t failed_keys;size_t failed_buckets;char *backup_name;

} gdbm_recovery;

The input members modify the behavior of gdbm_recover:

[input member of gdbm_recovery]void (*errfun) (void *data, char const*fmt, ...)

If the GDBM_RCVR_ERRFUN flag bit is set, errfun points to a function that willbe called upon each recoverable or non-fatal error that occurred during therecovery. The data field of gdbm_recovery will be passed to it as its firstargument. The fmt argument is a printf-like (see Section “format output” in

Chapter 14: Recovery 23

printf(2) man page), format string. The rest of arguments supply parametersfor that format.

[input member of gdbm_recovery]void * dataSupplies first argument for the errfun invocations.

[input member of gdbm_recovery]size_t max_failed_keysIf GDBM_RCVR_MAX_FAILED_KEYS is set, this member sets the limit on the num-ber of keys that cannot be retrieved. If the number of failed keys becomes equalto max_failed_keys, recovery is aborted and error is returned.

[input member of gdbm_recovery]size_t max_failed_bucketsIf GDBM_RCVR_MAX_FAILED_BUCKETS is set, this member sets the limit on thenumber of buckets that cannot be retrieved or that contain bogus information.If the number of failed buckets becomes equal to max_failed_buckets, recoveryis aborted and error is returned.

[output member of gdbm_recovery]size_t max_failuresIf GDBM_RCVR_MAX_FAILURES is set, this member sets the limit of failures thatare tolerated during recovery. If the number of errors becomes equal to max_failures, recovery is aborted and error is returned.

The following members are filled on output, upon successful return from the function:

[output member of gdbm_recovery]size_t recovered_keysNumber of recovered keys.

[output member of gdbm_recovery]size_t recovered_bucketsNumber of recovered buckets.

[output member of gdbm_recovery]size_t failed_keysNumber of key/data pairs that cannot be retrieved.

[output member of gdbm_recovery]size_t failed_bucketsNumber of buckets that cannot be retrieved.

[output member of gdbm_recovery]char * backup_nameName of the file keeping the copy of the original database, in the state priorto recovery. It is filled if the GDBM RCVR BACKUP flag is set. The stringis allocated using the malloc call. The caller is responsible for freeing thatmemory when no longer needed.

By default, gdbm_recovery first checks the database for inconsistencies and attemptsrecovery only if some were found. The special flag bit GDBM_RCVR_FORCE instructs gdbm_recovery to omit this check and to perform database recovery unconditionally.

Chapter 15: Setting options 24

15 Setting options

Gdbm supports the ability to set certain options on an already open database.

[gdbm interface]int gdbm_setopt (GDBM FILE dbf, int option, void *value,int size)

Sets an option on the database or returns the value of an option.The parameters are:


option The option to be set or retrieved.

value A pointer to the value to which option will be set or where to place theoption value (depending on the option).

size The length of the data pointed to by value.

The return value will be ‘-1’ upon failure, or ‘0’ upon success. The global variablegdbm_errno will be set upon failure.

The valid options are:

GDBM SETCACHESIZEGDBM CACHESIZE

Set the size of the internal bucket cache. This option may only be set once oneach GDBM FILE descriptor, and is set automatically to 100 upon the firstaccess to the database. The value should point to a size_t holding the desiredcache size.The ‘GDBM_CACHESIZE’ option is provided for compatibility with earlier versions.For instance, to set a database to use a cache of 10, after opening it withgdbm_open, but prior to accessing it in any way, the following code could beused:

int value = 10;ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &value, sizeof (int));

GDBM GETCACHESIZEReturn the size of the internal bucket cache. The value should point to a size_tvariable, where the size will be stored.

GDBM GETFLAGSReturn the flags describing the state of the database. The value should pointto an int variable where to store the flags. On success, its value will be similarto the flags used when opening the database (see Chapter 3 [Open], page 5),except that it will reflect the current state (which may have been altered byanother calls to gdbm_setopt).

GDBM FASTMODEEnable or disable the fast writes mode, i.e. writes without subsequent synchro-nization. The value should point to an integer: ‘TRUE’ to enable fast mode, and‘FALSE’ to disable it.This option is retained for compatibility with previous versions of gdbm. Itseffect is the reverse of GDBM_SETSYNCMODE (see below).


GDBM SETSYNCMODEGDBM SYNCMODE

Turn on or off file system synchronization operations. This setting defaults tooff. The value should point to an integer: ‘TRUE’ to turn synchronization on,and ‘FALSE’ to turn it off.Note, that this option is a reverse of GDBM_FASTMODE, i.e. calling GDBM_SETSYNCMODE with ‘TRUE’ has the same effect as calling GDBM_FASTMODE with‘FALSE’.The ‘GDBM_SYNCMODE’ option is provided for compatibility with earlier versions.

GDBM GETSYNCMODEReturn the current synchronization status. The value should point to an intwhere the status will be stored.

GDBM SETCENTFREEGDBM CENTFREE

NOTICE: This feature is still under study.Set central free block pool to either on or off. The default is off, which ishow previous versions of gdbm handled free blocks. If set, this option causesall 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’ option is provided for compatibility with earlier versions.

GDBM SETCOALESCEBLKSGDBM COALESCEBLKS

NOTICE: This feature is still under study.Set free block merging to either on or off. The default is off, which is howprevious versions of gdbm handled free blocks. If set, this option causes adjacentfree blocks to be merged. This can become a CPU expensive process with time,though, especially if used in conjunction with GDBM CENTFREE. The valueshould point to an integer: ‘TRUE’ to turn free block merging on, and ‘FALSE’to turn it off.

GDBM GETCOALESCEBLKSReturn the current status of free block merging. The value should point to anint where the status will be stored.

GDBM SETMAXMAPSIZESets maximum size of a memory mapped region. The value should point to avalue of type size_t, unsigned long or unsigned. The actual value is roundedto the nearest page boundary (the page size is obtained from sysconf(_SC_PAGESIZE)).

GDBM GETMAXMAPSIZEReturn the maximum size of a memory mapped region. The value should pointto a value of type size_t where to return the data.

GDBM SETMMAPEnable or disable memory mapping mode. The value should point to an integer:‘TRUE’ to enable memory mapping or ‘FALSE’ to disable it.


GDBM GETMMAPCheck whether memory mapping is enabled. The value should point to aninteger where to return the status.

GDBM GETDBNAMEReturn the name of the database disk file. The value should point to a variableof type char**. A pointer to the newly allocated copy of the file name will beplaced there. The caller is responsible for freeing this memory when no longerneeded. For example:

char *name;

if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name))){

fprintf (stderr, "gdbm_setopt failed: %s\n",gdbm_strerror (gdbm_errno));

}else{printf ("database name: %s\n", name);free (name);

}

GDBM GETBLOCKSIZEReturn the block size in bytes. The value should point to int.

Chapter 16: File Locking. 27

16 File Locking.

With locking disabled (if gdbm_open was called with ‘GDBM_NOLOCK’), the user may wantto perform their own file locking on the database file in order to prevent multiple writersoperating on the same file simultaneously.

In order to support this, the gdbm_fdesc routine is provided.

[gdbm interface]int gdbm_fdesc (GDBM FILE dbf)Returns the file descriptor of the database dbf. This value can be used as an argumentto flock, lockf or similar calls.

Chapter 17: Useful global variables. 28

17 Useful global variables.

The following global variables and constants are available:

[Variable]gdbm_error gdbm_errnoThis variable contains error code from the last failed gdbm call. See Chapter 18 [Errorcodes], page 30, for a list of available error codes and their descriptions.Use gdbm_strerror (see Chapter 13 [Errors], page 20) to convert it to a descriptivetext.

[Variable]const char * gdbm_errlist[]This variable is an array of error descriptions, which is used by gdbm_strerror toconvert error codes to human-readable text (see Chapter 13 [Errors], page 20). Youcan access it directly, if you wish so. It contains _GDBM_MAX_ERRNO + 1 elements andcan be directly indexed by the error code to obtain a corresponding descriptive text.

[Variable]int const gdbm_syserr[]Array of boolean values indicating, for each GDBM error code, whether the value oferrno(3) variable is meaningful for this error code. See [gdbm check syserr], page 20.

[Constant]_GDBM_MIN_ERRNOThe minimum error code used by gdbm.

[Constant]_GDBM_MAX_ERRNOThe maximum error code used by gdbm.

[Variable]const char * gdbm_versionA string containing the version information.

[Variable]int const gdbm_version_number[3]This variable contains the gdbm version numbers:

Index Meaning0 Major number1 Minor number2 Patchlevel numberAdditionally, the following constants are defined in the gdbm.h file:

GDBM VERSION MAJORMajor number.

GDBM VERSION MINORMinor number.

GDBM VERSION PATCHPatchlevel number.

These can be used to verify whether the header file matches the library.

To compare two split-out version numbers, use the following function:

Chapter 17: Useful global variables. 29

[gdbm interface]int gdbm_version_cmp (int const a[3], int const b[3])Compare two version numbers. Return ‘-1’ if a is less than b, ‘1’ if a is greater thanb and ‘0’ if they are equal.Comparison is done from left to right, so that:

a = { 1, 8, 3 };b = { 1, 8, 3 };gdbm_version_cmp (a, b) ⇒ 0

a = { 1, 8, 3 };b = { 1, 8, 2 };gdbm_version_cmp (a, b) ⇒ 1

a = { 1, 8, 3 };b = { 1, 9. 0 };gdbm_version_cmp (a, b) ⇒ -1

Chapter 18: Error codes 30

18 Error codes

This chapter summarizes error codes which can be set by the functions in gdbm library.

GDBM NO ERRORNo error occurred.

GDBM MALLOC ERRORMemory allocation failed. Not enough memory.

GDBM BLOCK SIZE ERRORThis error is set by the gdbm_open function (see Chapter 3 [Open], page 5), ifthe value of its block size argument is incorrect and the ‘GDBM_BSEXACT’ flag isset.

GDBM FILE OPEN ERRORThe library was not able to open a disk file. This can be set by gdbm_open(see Chapter 3 [Open], page 5), gdbm_export and gdbm_import functions (seeChapter 12 [Flat files], page 16).Inspect the value of the system errno variable to get more detailed diagnostics.

GDBM FILE WRITE ERRORWriting to a disk file failed. This can be set by gdbm_open (see Chapter 3[Open], page 5), gdbm_export and gdbm_import functions.Inspect the value of the system errno variable to get more detailed diagnostics.

GDBM FILE SEEK ERRORPositioning in a disk file failed. This can be set by gdbm_open (see Chapter 3[Open], page 5) function.Inspect the value of the system errno variable to get a more detailed diagnos-tics.

GDBM FILE READ ERRORReading from a disk file failed. This can be set by gdbm_open (see Chapter 3[Open], page 5), gdbm_export and gdbm_import functions.Inspect the value of the system errno variable to get a more detailed diagnos-tics.

GDBM BAD MAGIC NUMBERThe file given as argument to gdbm_open function is not a valid gdbm file: ithas a wrong magic number.

GDBM EMPTY DATABASEThe file given as argument to gdbm_open function is not a valid gdbm file: ithas zero length.

GDBM CANT BE READERThis error code is set by the gdbm_open function if it is not able to lock filewhen called in ‘GDBM_READER’ mode (see Chapter 3 [Open], page 5).

GDBM CANT BE WRITERThis error code is set by the gdbm_open function if it is not able to lock filewhen called in writer mode (see Chapter 3 [Open], page 5).


GDBM READER CANT DELETESet by the gdbm_delete (see Chapter 8 [Delete], page 11) if it attempted tooperate on a database that is open in read-only mode (see Chapter 3 [Open],page 5).

GDBM READER CANT STORESet by the gdbm_store (see Chapter 6 [Store], page 9) if it attempted to operateon a database that is open in read-only mode (see Chapter 3 [Open], page 5).

GDBM READER CANT REORGANIZESet by the gdbm_reorganize (see Chapter 10 [Reorganization], page 14) ifit attempted to operate on a database that is open in read-only mode (seeChapter 3 [Open], page 5).

GDBM ITEM NOT FOUNDRequested item was not found. This error is set by gdbm_delete (see Chapter 8[Delete], page 11) and gdbm_fetch (see Chapter 7 [Fetch], page 10) when therequested key value is not found in the database.

GDBM REORGANIZE FAILEDThe gdbm_reorganize function is not able to create a temporary database. SeeChapter 10 [Reorganization], page 14.

GDBM CANNOT REPLACECannot replace existing item. This error is set by the gdbm_store if therequested key value is found in the database and the flag parameter is not‘GDBM_REPLACE’. See Chapter 6 [Store], page 9, for a detailed discussion.

GDBM ILLEGAL DATAEither key or content parameter was wrong in a call to to gdbm_store (seeChapter 6 [Store], page 9).

GDBM OPT ALREADY SETRequested option can be set only once and was already set. This error isreturned by the gdbm_setopt function. See Chapter 15 [Options], page 24.

GDBM OPT ILLEGALThe option argument is not valid or the value argument points to an invalidvalue in a call to gdbm_setopt function. See Chapter 15 [Options], page 24.

GDBM BYTE SWAPPEDThe gdbm_open function (see Chapter 3 [Open], page 5) attempts to open adatabase which is created on a machine with different byte ordering.

GDBM BAD FILE OFFSETThe gdbm_open function (see Chapter 3 [Open], page 5) sets this error code ifthe file it tries to open has a wrong magic number.

GDBM BAD OPEN FLAGSSet by the gdbm_export function if supplied an invalid flags argument. SeeChapter 12 [Flat files], page 16.

GDBM FILE STAT ERRORGetting information about a disk file failed. The system errno will give moredetails about the error.


This error can be set by the following functions: gdbm_open, gdbm_reorganize.

GDBM FILE EOFEnd of file was encountered where more data was expected to be present. Thiserror can occur when fetching data from the database and usually means thatthe database is truncated or otherwise corrupted.This error can be set by any GDBM function that does I/O. Some of thesefunctions are: gdbm_delete, gdbm_exists, gdbm_fetch, gdbm_export, gdbm_import, gdbm_reorganize, gdbm_firstkey, gdbm_nextkey, gdbm_store.

GDBM NO DBNAMEOutput database name is not specified. This error code is set by gdbm_load(see [gdbm load], page 17) if the first argument points to ‘NULL’ and the inputfile does not specify the database name.

GDBM ERR FILE OWNERThis error code is set by gdbm_load if it is unable to restore database fileowner. It is a mild error condition, meaning that the data have been restoredsuccessfully, only changing the target file owner failed. Inspect the systemerrno variable to get a more detailed diagnostics.

GDBM ERR FILE MODEThis error code is set by gdbm_load if it is unable to restore database filemode. It is a mild error condition, meaning that the data have been restoredsuccessfully, only changing the target file owner failed. Inspect the systemerrno variable to get a more detailed diagnostics.

GDBM NEED RECOVERYDatabase is in inconsistent state and needs recovery. Call gdbm_recover if youget this error. See Chapter 14 [Recovery], page 22, for a detailed description ofrecovery functions.

GDBM BACKUP FAILEDThe GDBM engine is unable to create backup copy of the file.

GDBM DIR OVERFLOWBucket directory would overflow the size limit during an attempt to split hashbucket. This error can occur while storing a new key.

Chapter 19: Compatibility with standard dbm and ndbm. 33

19 Compatibility with standard dbm and ndbm.

Gdbm includes a compatibility layer, which provides traditional ‘ndbm’ and older ‘dbm’ func-tions. The layer is compiled and installed if the --enable-libgdbm-compat option is usedwhen configuring the package.

The compatibility layer consists of two header files: ndbm.h and dbm.h and the libgdbm_compat library.

Older programs using ndbm or dbm interfaces can use libgdbm_compat without anychanges. To link a program with the compatibility library, add the following two options tothe cc invocation: -lgdbm -lgdbm_compat. The -L option may also be required, dependingon where gdbm is installed, e.g.:

cc ... -lgdbm -lgdbm_compat

Databases created and manipulated by the compatibility interfaces consist of two dif-ferent files: file.dir and file.pag. This is required by the POSIX specification andcorresponds to the traditional usage. Note, however, that despite the similarity of the nam-ing convention, actual data stored in these files has not the same format as in the databasescreated by other dbm or ndbm libraries. In other words, you cannot access a standard UNIXdbm file with GNU dbm!

GNU dbm files are not sparse. You can copy them with the usual cp command and theywill not expand in the copying process.

19.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 beopened. The function opens two files: file.pag and file.dir. The flags and modearguments have the same meaning as the second and third arguments of open (seeSection “open a file” 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_APPENDflag is unspecified.The function returns a pointer to the DBM structure describing the database. Thispointer 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 willbe stored in gdbm_errno (see Chapter 17 [Variables], page 28).

[ndbm]void dbm_close (DBM *dbf)Closes the database. The dbf argument must be a pointer returned by an earlier callto dbm_open.

[ndbm]datum dbm_fetch (DBM *dbf, datum key)Reads a record from the database with the matching key. The key argument suppliesthe 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 managedby 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 DBMstructure returned from a call to dbm_open. The key and content provide the valuesfor 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 ofthe following two values:

DBM_REPLACEReplace existing record with the new one.

DBM_INSERTThe existing record is left unchanged, and the function returns ‘1’.

If no matching record exists in the database, new record will be inserted no matterwhat 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 memorymanaged 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 data-base. If the iteration covered all keys in the database, the dptr member of thereturned datum is ‘NULL’. Otherwise, the dptr member of the returned datum pointsto the memory managed by the compatibility library. The application should neverfree 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 theiteration is not guaranteed to cover all the keys. See Chapter 9 [Sequential], page 12,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 whilemanipulating 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 bedifferent 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.

19.2 DBM interface functions.

The functions below are provided for compatibility with the old UNIX ‘DBM’ interface. Onlyone 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 beopened. The function opens two files: file.pag and file.dir. If any of them doesnot 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 arecalled 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 suppliesthe 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 managedby 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 alreadyexists, 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 orif 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 memorymanaged 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 thedatabase. If the iteration covered all keys in the database, the dptr member of thereturned datum is ‘NULL’. Otherwise, the dptr member of the returned datum pointsto the memory managed by the compatibility library. The application should neverfree it.

Chapter 20: Examine and modify a GDBM database. 37

20 Examine and modify a GDBM database.

The gdbmtool utility allows you to view and modify an existing GDBM database or tocreate a new one.

When invoked without arguments, it tries to open a database file called junk.gdbm,located in the current working directory. You can change this default by supplying thename of the database as argument to the program, e.g.:

$ gdbmtool file.db

The database will be opened in read-write mode, unless the -r (--read-only) option isspecified, in which case it will be opened only for reading.

If the database does not exist, gdbmtool will create it. There is a special option -n(--newdb), which instructs the utility to create a new database. If it is used and if thedatabase already exists, it will be deleted, so use it sparingly.

20.1 gdbmtool invocation

When started without additional arguments, gdbmtool operates on the default databasejunk.gdbm. Otherwise, the first argument supplies the name of the database to operateupon. If neither any additional arguments nor the -f (--file) option are given, gdbmtoolopens starts interactive shell and receives commands directly from the human operator.

If more than one arguments are given, all arguments past the database name are parsedas gdbmtool commands (see Section 20.2 [shell], page 38, for a description of availablecommands) and executed in turn. All commands, except the last one, should be terminatedwith semicolons. Semicolon after the last command is optional. Note, that semicolonsshould be escaped in order to prevent them from being interpreted by the shell.

Finally, if the -f (--file) option is supplied, its argument specifies the name of the diskfile with gdbmtool script. The program will open that file and read commands from it.

The following table summarizes all gdbmtool command line options:

-b size

--block-size=sizeSet block size.

-c size

--cache-size=sizeSet cache size.

-f file

--file file

Read commands from file, instead of the standard input.

-h--help Print a concise help summary.

-N--norc Don’t read startup files (see Section 20.2.4 [startup files], page 47).

-n--newdb Create the database.


-l--no-lock

Disable file locking.

-m--no-mmap

Disable memory mapping.

-q--quiet Don’t print the usual welcome banner at startup. This is the same as setting

the variable ‘quiet’ in the startup file. See [quiet], page 40.

-r--read-only

Open the database in read-only mode.

-s--synchronize

Synchronize to the disk after each write.

-V--version

Print program version and licensing information and exit.

--usage Print a terse invocation syntax summary along with a list of available commandline options.

20.2 gdbmtool interactive mode

After successful startup, gdbmtool starts a loop, in which it reads commands from thestandard input, executes them and prints results on the standard output. If the standardinput is attached to a console, gdbmtool runs in interactive mode, which is indicated by itsprompt:

gdbmtool> _

The utility finishes when it reads the ‘quit’ command (see below) or detects end-of-fileon its standard input, whichever occurs first.

A gdbmtool command consists of a command verb, optionally followed by arguments,separated by any amount of white space and terminated with a newline or semicolon. Acommand verb can be entered either in full or in an abbreviated form, as long as thatabbreviation does not match any other verb. For example, ‘co’ can be used instead of‘count’ and ‘ca’ instead of ‘cache’.

Any sequence of non-whitespace characters appearing after the command verb formsan argument. If the argument contains whitespace or unprintable characters it must beenclosed in double quotes. Within double quotes the usual escape sequences are understood,as shown in the table below:


Sequence Replaced with\a Audible bell character (ASCII 7)\b Backspace character (ASCII 8)\f Form-feed character (ASCII 12)\n Newline character (ASCII 10)\r Carriage return character (ASCII 13)\t Horizontal tabulation character (ASCII 9)\v Vertical tabulation character (ASCII 11)\\ Single slash\" Double quote

Table 20.1: Backslash escapes

In addition, a backslash immediately followed by the end-of-line character effectivelyremoves that character, allowing to split long arguments over several input lines.

Command parameters may be optional or mandatory. If the number of actual argumentsis less than the number of mandatory parameters, gdbmtool will prompt you to supplymissing arguments. For example, the ‘store’ command takes two mandatory parameters,so if you invoked it with no arguments, you would be prompted twice to supply the necessarydata, as shown in example below:

gdbmtool> store

key? three

data? 3

However, such prompting is possible only in interactive mode. In non-interactive mode(e.g. when running a script), all arguments must be supplied with each command, otherwisegdbmtool will report an error and exit immediately.

If the package is compiled with GNU Readline, the input line can be edited (see Section“Command Line Editing” in GNU Readline Library).

20.2.1 Shell Variables

A number of gdbmtool parameters is kept in its internal variables. To examine or modifyvariables, use the set command (see [set], page 41).

[gdbmtool variable]bool confirmWhether to ask for confirmation before certain destructive operations, such as trun-cating the existing database.Default is ‘true’.

[gdbmtool variable]string ps1Primary prompt string. Its value can contain conversion specifiers, consisting of the‘%’ character followed by another character. These specifiers are expanded in theresulting prompt as follows:

Sequence Expansion%f name of the current database file%p program invocation name


%P package name (‘GDBM’)%v program version% single space character%% %The default value is ‘%p>%_’, i.e. the program name, followed by a “greater than”sign, followed by a single space.

[gdbmtool variable]string ps2Secondary prompt. See ‘ps1’ for a description of its value. This prompt is displayedbefore reading the second and subsequent lines of a multi-line command.The default value is ‘%_>%_’.

[gdbmtool variable]string delim1A string used to delimit fields of a structured datum on output (see Section 20.2.3[definitions], page 45).Default is ‘,’ (a comma). This variable cannot be unset.

[gdbmtool variable]string delim2A string used to delimit array items when printing a structured datum (seeSection 20.2.3 [definitions], page 45).Default is ‘,’ (a comma). This variable cannot be unset.

[gdbmtool variable]string pagerThe name and command line of the pager program to pipe output to. This programis used in interactive mode when the estimated number of output lines is greater thenthe number of lines on your screen.The default value is inherited from the environment variable PAGER. Unsetting thisvariable disables paging.

[gdbmtool variable]bool quietWhether to display a welcome banner at startup. To affect gdbmtool, this variableshould be set in a startup script file (see Section 20.2.4 [startup files], page 47). See[-q option], page 38.

The following variables control how the database is opened:

[gdbmtool variable]numeric blocksizeSets the block size. See Chapter 3 [Open], page 5. Unset by default.

[gdbmtool variable]numeric cachesizeSets the cache size. See Chapter 15 [Options], page 24. By default this variable isnot set.

[gdbmtool variable]string openOpen mode. The following values are allowed:

newdb Truncate the database if it exists or create a new one. Open it in read-write mode.Technically, this sets the ‘GDBM_NEWDB’ flag in call to ‘gdbm_open’. SeeChapter 3 [Open], page 5.


wrcreatrw Open the database in read-write mode. Create it if it does not exist. This

is the default.Technically speaking, it sets the ‘GDBM_WRCREAT’ flag in call to gdbm_open.See Chapter 3 [Open], page 5.

readerreadonly Open the database in read-only mode. Signal an error if it does not exist.

This sets the ‘GDBM_READER’ flag (see Chapter 3 [Open], page 5).

Attempting to set any other value or to unset this variable results in error.

[gdbmtool variable]number filemodeFile mode (in octal) for creating new database files and database dumps.

[gdbmtool variable]bool lockLock the database. This is the default.Setting this variable to false or unsetting it results in passing ‘GDBM_NOLOCK’ flag togdbm_open (see Chapter 3 [Open], page 5).

[gdbmtool variable]bool mmapUse memory mapping. This is the default.Setting this variable to false or unsetting it results in passing ‘GDBM_NOMMAP’ flag togdbm_open (see Chapter 3 [Open], page 5).

[gdbmtool variable]bool syncFlush all database writes on disk immediately. Default is false. See Chapter 3 [Open],page 5.

[gdbmtool variable]bool coalesceEnables the coalesce mode, i.e. merging of the freed blocks of GDBM files withentries in available block lists. This provides for effective memory management at thecost of slight increase in execution time when calling gdbm_delete. See Chapter 15[Options], page 24.This variable affects the open command and should be set before invoking it.

[gdbmtool variable]bool centfreeSet to ‘true’, enables the use of central free block pool in newly opened databases.See Chapter 15 [Options], page 24.This variable affects the open command and should be set before invoking it.

The following commands are used to list or modify the variables:

[command verb]set [assignments]When used without arguments, lists all variables and their values. Unset variablesare shown after a comment sign (‘#’). For string and numeric variables, values areshown after an equals sign. For boolean variables, only the variable name is displayedif the variable is ‘true’. If it is ‘false’, its name is prefixed with ‘no’.For example:


ps1="%p>%_"ps2="%_>%_"delim1=","delim2=","confirm# cachesize is unset# blocksize is unsetopen="wrcreat"lockmmapnosyncpager="less"# quiet is unset

If used with arguments, the set command alters the specified variables. In this case,arguments are variable assignments in the form ‘name=value’. For boolean variables,the value is interpreted as follows: if it is numeric, ‘0’ stands for ‘false’, any non-zerovalue stands for ‘true’. Otherwise, the values ‘on’, ‘true’, and ‘yes’ denote ‘true’,and ‘off’, ‘false’, ‘no’ stand for ‘false’. Alternatively, only the name of a booleanvariable can be supplied to set it to ‘true’, and its name prefixed with ‘no’ can beused to set it to false. For example, the following command sets the ‘delim2’ variableto ‘;’ and the ‘confirm’ variable to ‘false’:

set delim2=";" noconfirm

[command verb]unset variablesUnsets the listed variables. The effect of unsetting depends on the variable. Unlessexplicitly described in the discussion of the variables above, unsetting a boolean vari-able is equivalent to setting it to ‘false’. Unsetting a string variable is equivalent toassigning it an empty string.

20.2.2 Gdbmtool Commands

[command verb]availPrint the avail list.

[command verb]bucket numPrint the bucket number num and set it as the current one.

[command verb]cachePrint the bucket cache.

[command verb]closeClose the currently open database.

[command verb]countPrint the number of entries in the database.

[command verb]currentPrint the current bucket.


[command verb]debug [[+-]token...]If GDBM is configured with additional debugging, this statement queries or sets GDBMinternal debugging level. This is intended for debugging and testing purposes andrequires good knowledge of GDBM internals. The use of this command is not recom-mended.

[command verb]delete keyDelete record with the given key

[command verb]dirPrint hash directory.

[command verb]export file-name [truncate] [binary|ascii]Export the database to the flat file file-name. See Chapter 12 [Flat files], page 16, for adescription of the flat file format and its purposes. This command will not overwritean existing file, unless the ‘truncate’ parameter is also given. Another optionalargument determines the type of the dump (see Chapter 12 [Flat files], page 16). Bydefault, ASCII dump is created.

The global variable filemode specifies the permissions to use for the created outputfile.

[command verb]fetch keyFetch and display the record with the given key.

[command verb]firstFetch and display the first record in the database. Subsequent records can be fetchedusing the next command (see below). See Chapter 9 [Sequential], page 12, for moreinformation on sequential access.

[command verb]hash keyCompute and display the hash value for the given key.

[command verb]headerPrint file header.

[command verb]help[command verb]?

Print a concise command summary, showing each command verb with its parametersand a short description of what it does. Optional arguments are enclosed in squarebrackets.

[command verb]import file-name [replace] [nometa]Import data from a flat dump file file-name (see Chapter 12 [Flat files], page 16).If the word ‘replace’ is given as an argument, any records with the same keys asthe already existing ones will replace them. The word ‘nometa’ turns off restoringmeta-information from the dump file.

[command verb]history[command verb]history count


[command verb]history n countShows the command history list with line numbers. When used without arguments,shows entire history. When used with one argument, displays count last commandsfrom the history. With two arguments, displays count commands starting from nthcommand. Command numbering starts with 1.This command is available only if GDBM was compiled with GNU Readline. Thehistory is saved in file .gdbmtool_history in the user’s home directory. If this fileexists upon startup, it is read to populate the history. Thus, command history ispreserved between gdbmtool invocations.

[command verb]listList the contents of the database.

[command verb]next [key]Sequential access: fetch and display the next record. If the key is given, the recordfollowing the one with this key will be fetched.Issuing several next commands in row is rather common. A shortcut is providedto facilitate such use: if the last entered command was next, hitting the Enter keyrepeats it without arguments.See also first, above.See Chapter 9 [Sequential], page 12, for more information on sequential access.

[command verb]open filenameOpen the database file filename. If successful, any previously open database is closed.Otherwise, if the operation fails, the currently opened database remains unchanged.This command takes additional information from the following variables:

‘open’ The database access mode. See [The open variable], page 40, for a list ofits values.

‘lock’ Whether or not to lock the database. Default is ‘on’.

‘mmap’ Use the memory mapping. Default is ‘on’.

‘sync’ Synchronize after each write. Default is ‘off’.

‘filemode’Specifies the permissions to use in case a new file is created.

See [open parameters], page 40, for a detailed description of these variables.

[command verb]quitClose the database and quit the utility.

[command verb]recover [options]Run database recovery. The following options are understood:

backup Create a backup copy of the original database.

max-failed-buckets=nAbort recovery process if n buckets could not be recovered.


max-failed-keys=nAbort recovery process if n keys could not be recovered.

max-failures=nAbort recovery process after n failures. A failure in this context is eithera key or a bucket that failed to be recovered.

summary Print the recovery statistics at the end of the run. The statistics includesnumber of successfully recovered, failed and duplicate keys and the num-ber of recovered and failed buckets.

verbose Verbosely list each error encountered.

[command verb]reorganizeReorganize the database (see Chapter 10 [Reorganization], page 14).

[command verb]source filenameRead gdbmtool commands from the file filename.

[command verb]statusPrint current program status. The following example shows the information displayed:

Database file: junk.gdbmDatabase is opendefine key stringdefine content string

The two ‘define’ strings show the defined formats for key and content data. SeeSection 20.2.3 [definitions], page 45, for a detailed discussion of their meaning.

[command verb]store key dataStore the data with key in the database. If key already exists, its data will be replaced.

[command verb]versionPrint the version of gdbm.

20.2.3 Data Definitions

GDBM databases are able to keep data of any type, both in the key and in the contentpart of a record. Quite often these data are structured, i.e. they consist of several fields ofvarious types. Gdbmtool provides a mechanism for handling such kind of records.

The define command defines a record structure. The general syntax is:define what definition

where what is ‘key’ to defining the structure of key data and ‘content’ to define thestructure of the content records.

The definition can be of two distinct formats. In the simplest case it is a single datatype. For example,

define content int

defines content records consisting of a single integer field. Supported data types are:

char Single byte (signed).

short Signed short integer.


ushort Unsigned short integer.

int Signed integer.

unsigneduint Unsigned integer.

long Signed long integer.

ulong Unsigned long integer.

llong Signed long long integer.

ullong Unsigned long long integer.

float A floating point number.

double Double-precision floating point number.

string Array of bytes.

stringz Null-terminated string, trailing null being part of the string.

All numeric data types (integer as well as floating point) have the same respective widthsas in C language on the host where the database file resides.

The ‘string’ and ‘stringz’ are special. Both define a string of bytes, similar to ‘charx[]’ in C. The former defines an array of bytes, the latter - a null-terminated string. Thismakes a difference, in particular, when the string is the only part of datum. Consider thefollowing two definitions:1. define key string

2. define key stringz

Now, suppose we want to store the string "ab" in the key. Using the definition (1), thedptr member of GDBM datum will contain two bytes: ‘a’, and ‘b’. Consequently, the dsizemember will have the value 2. Using the definition (2), the dptr member will contain threebytes: ‘a’, ‘b’, and ASCII 0. The dsize member will have the value 3.

The definition (1) is the default for both key and content.The second form of the define statement is similar to the C struct statement and

allows for defining structural data. In this form, the definition part is a comma-separatedlist of data types and variables enclosed in curly braces. In contrast to the rest of gdbmcommands, this command is inherently multiline and is terminated with the closing curlybrace. For example:

define content {int status,pad 8,char id[3],string name

}

This defines a structure consisting of three members: an integer status, an array of 3bytes id, and an array of bytes name. Notice the pad statement: it allows to introducepadding between structure members. Another useful statement is offset: it specifies thatthe member following it begins at the given offset in the structure. Assuming the size ofint is 8 bytes, the above definition can also be written as


define content {int status,offset 16,char id[3],string name

}

NOTE : The ‘string’ type can reasonably be used only if it is the last or the onlymember of the data structure. That’s because it provides no information about the numberof elements in the array, so it is interpreted to contain all bytes up to the end of the datum.

When displaying the structured data, gdbmtool precedes each value with the correspond-ing field name and delimits parts of the structure with the string defined in the ‘delim1’variable (see Section 20.2.1 [variables], page 39). Array elements are delimited using thestring from ‘delim2’. For example:

gdbmtool> fetch foostatus=2,id={ a, u, x },name="quux"

To supply a structured datum as an argument to a gdbmtool command, use the samenotation, e.g.:

gdbmtool> store newkey { status=2, id={a,u,x}, name="quux" }

The order in which the fields are listed is not significant. The above command can aswell be written as:

gdbmtool> store newkey { id={a,u,x}, status=2, name="quux" }

You are not required to supply all defined fields. Any number of them can be omitted,provided that at least one remains. The omitted fields are filled with 0:

gdbmtool> store newkey { name="bar" }gdbmtool> fetch newkeystatus=0,id={ ,, },name=bar

Yet another way to supply structured data to a command is by listing the value for eachfield in the order they are defined, without field names:

gdbmtool> store newkey { 2, {a,u,x}, "quux" }

20.2.4 Startup Files

Upon startup gdbmtool looks for a file named ‘.gdbmtoolrc’ first in the current workingdirectory and, if not found, in the home directory of the user who started the command.

If found, this file is read and interpreted as a list of gdbmtool commands. This allowsyou to customize the program behavior.

Following is an example startup file which disables the welcome banner, sets commandline prompt to contain the name of the database file in parentheses and defines the structureof the database content records:


set quietset ps1="(%f) "define key stringzdefine content {

int time,pad 4,int status

}

Chapter 21: The gdbm_dump utility 49

21 The gdbm_dump utility

The gdbm_dump utility creates a flat file dump of a GDBM database (see Chapter 12 [Flatfiles], page 16). It takes one mandatory argument: the name of the source database file.The second argument, if given, specifies the name of the output file. If not given, gdbm_dumpwill produce the dump on the standard output.

For example, the following invocation creates a dump of the database file.db in thefile file.dump:

$ gdbm_dump file.db file.dump

By default the utility creates dumps in ASCII format (see Chapter 12 [Flat files],page 16). Another format can be requested using the --format (-H) option.

The gdbm_dump utility understands the following command line options:

-H fmt

--format=fmtSelect output format. Valid values for fmt are: ‘binary’ or ‘0’ to select binarydump format, and ‘ascii’ or ‘1’ to select ASCII format.


-V--version



Chapter 22: The gdbm_load utility 50

22 The gdbm_load utility

The gdbm_load utility restores a GDBM database from a flat file. The utility requires atleast one argument: the name of the input flat file. If it is ‘-’, the standard input will beread. The format of the input file is detected automatically.

By default the utility attempts to restore the database under its original name, as storedin the input file. It will fail to do so if the input is in binary format. In that case, the nameof the database must be given as the second argument.

In general, if two arguments are given, the second one is treated as the name of thedatabase to create, overriding the file name specified in the flat file.

The utility understands the following command line arguments:

-b num

--block-size=numSets block size. See Chapter 3 [Open], page 5.

-c num

--cache-size=numSets cache size. See Chapter 15 [Options], page 24.

-M--mmap Use memory mapping.

-m mode

--mode=modeSets the file mode. The argument is the desired file mode in octal.

-n--no-meta

Do not restore file meta-data (ownership and mode) from the flat file.

-r--replace

Replace existing keys.

-u user[:group]--user=user[:group]

Set file owner. The user can be either a valid user name or UID. Similarly,the group is either a valid group name or GID. If group is not given, the maingroup of user is used.User and group parts can be separated by a dot, instead of the colon.


-V--version



Chapter 23: Exit codes 51

23 Exit codes

All GDBM utilities return uniform exit codes. These are summarized in the table below:

Code Meaning0 Successful termination.1 A fatal error occurred.2 Program was unable to restore file ownership or mode.3 Command line usage error.

Chapter 24: Problems and bugs. 52

24 Problems and bugs.

If you have problems with GNU dbm or think you’ve found a bug, please report it. Beforereporting a bug, make sure you’ve actually found a real bug. Carefully reread the documen-tation and see if it really says you can do what you’re trying to do. If it’s not clear whetheryou should be able to do something or not, report that too; it’s a bug in the documentation!

Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possibleinput file that reproduces the problem. Then send us the input file and the exact resultsgdbm gave you. Also say what you expected to occur; this will help us decide whether theproblem was really in the documentation.

Once you’ve got a precise problem, send e-mail to [email protected] include the version number of GNU dbm you are using. You can get this informa-

tion by printing the variable gdbm_version (see Chapter 17 [Variables], page 28).Non-bug suggestions are always welcome as well. If you have questions about things

that are unclear in the documentation or are just obscure features, please report them too.You may contact the authors and maintainers by e-mail: [email protected],

[email protected], [email protected] or [email protected].

mailto:[email protected]





Chapter 25: Additional resources 53

25 Additional resources

For the latest updates and pointers to additional resources, visit http://www.gnu.org/software/gdbm.

In particular, a copy of gdbm documentation in various formats is available online athttp://www.gnu.org/software/gdbm/manual.html.

Latest versions of gdbm can be downloaded from anonymous FTP: ftp://ftp.gnu.org/gnu/gdbm, or via HTTP from http://ftp.gnu.org/gnu/gdbm, or via HTTPS fromhttps://ftp.gnu.org/gnu/gdbm, or from any GNU mirror worldwide. See http://www.gnu.org/order/ftp.html, for a list of mirrors.

To track gdbm development, visit http://puszcza.gnu.org.ua/projects/gdbm.

http://www.gnu.org/software/gdbm

http://www.gnu.org/software/gdbm

http://www.gnu.org/software/gdbm/manual.html

ftp://ftp.gnu.org/gnu/gdbm

ftp://ftp.gnu.org/gnu/gdbm

http://ftp.gnu.org/gnu/gdbm

https://ftp.gnu.org/gnu/gdbm

http://www.gnu.org/order/ftp.html

http://www.gnu.org/order/ftp.html

http://puszcza.gnu.org.ua/projects/gdbm

Appendix A: GNU Free Documentation License 54

Appendix A GNU Free Documentation License

Version 1.3, 3 November 2008

Copyright c© 2000-2002, 2007-2008, 2011, 2017-2020 FreeSoftware Foundation, Inc.http://fsf.org/

Everyone is permitted to copy and distribute verbatim copiesof this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional anduseful document free in the sense of freedom: to assure everyone the effective freedomto copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a wayto get credit for their work, while not being considered responsible for modificationsmade by others.

This License is a kind of “copyleft”, which means that derivative works of the documentmust themselves be free in the same sense. It complements the GNU General PublicLicense, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, becausefree software needs free documentation: a free program should come with manualsproviding the same freedoms that the software does. But this License is not limited tosoftware manuals; it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this License principally forworks whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains anotice placed by the copyright holder saying it can be distributed under the termsof this License. Such a notice grants a world-wide, royalty-free license, unlimited induration, to use that work under the conditions stated herein. The “Document”,below, refers to any such manual or work. Any member of the public is a licensee, andis addressed as “you”. You accept the license if you copy, modify or distribute the workin a way requiring permission under copyright law.

A “Modified Version” of the Document means any work containing the Document ora portion of it, either copied verbatim, or with modifications and/or translated intoanother language.

A “Secondary Section” is a named appendix or a front-matter section of the Documentthat deals exclusively with the relationship of the publishers or authors of the Documentto the Document’s overall subject (or to related matters) and contains nothing thatcould fall directly within that overall subject. (Thus, if the Document is in part atextbook of mathematics, a Secondary Section may not explain any mathematics.) Therelationship could be a matter of historical connection with the subject or with relatedmatters, or of legal, commercial, philosophical, ethical or political position regardingthem.

http://fsf.org/


The “Invariant Sections” are certain Secondary Sections whose titles are designated, asbeing those of Invariant Sections, in the notice that says that the Document is releasedunder this License. If a section does not fit the above definition of Secondary then it isnot allowed to be designated as Invariant. The Document may contain zero InvariantSections. If the Document does not identify any Invariant Sections then there are none.

The “Cover Texts” are certain short passages of text that are listed, as Front-CoverTexts or Back-Cover Texts, in the notice that says that the Document is released underthis License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text maybe at most 25 words.

A “Transparent” copy of the Document means a machine-readable copy, representedin a format whose specification is available to the general public, that is suitable forrevising the document straightforwardly with generic text editors or (for images com-posed of pixels) generic paint programs or (for drawings) some widely available drawingeditor, and that is suitable for input to text formatters or for automatic translation toa variety of formats suitable for input to text formatters. A copy made in an otherwiseTransparent file format whose markup, or absence of markup, has been arranged tothwart or discourage subsequent modification by readers is not Transparent. An imageformat is not Transparent if used for any substantial amount of text. A copy that isnot “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain ascii withoutmarkup, Texinfo input format, LaTEX input format, SGML or XML using a publiclyavailable DTD, and standard-conforming simple HTML, PostScript or PDF designedfor human modification. Examples of transparent image formats include PNG, XCFand JPG. Opaque formats include proprietary formats that can be read and editedonly by proprietary word processors, SGML or XML for which the DTD and/orprocessing tools are not generally available, and the machine-generated HTML,PostScript or PDF produced by some word processors for output purposes only.

The “Title Page” means, for a printed book, the title page itself, plus such followingpages as are needed to hold, legibly, the material this License requires to appear in thetitle page. For works in formats which do not have any title page as such, “Title Page”means the text near the most prominent appearance of the work’s title, preceding thebeginning of the body of the text.

The “publisher” means any person or entity that distributes copies of the Documentto the public.

A section “Entitled XYZ” means a named subunit of the Document whose title eitheris precisely XYZ or contains XYZ in parentheses following text that translates XYZ inanother language. (Here XYZ stands for a specific section name mentioned below, suchas “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preservethe Title” of such a section when you modify the Document means that it remains asection “Entitled XYZ” according to this definition.

The Document may include Warranty Disclaimers next to the notice which states thatthis License applies to the Document. These Warranty Disclaimers are considered tobe included by reference in this License, but only as regards disclaiming warranties:any other implication that these Warranty Disclaimers may have is void and has noeffect on the meaning of this License.


2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially ornoncommercially, provided that this License, the copyright notices, and the licensenotice saying this License applies to the Document are reproduced in all copies, andthat you add no other conditions whatsoever to those of this License. You may not usetechnical measures to obstruct or control the reading or further copying of the copiesyou make or distribute. However, you may accept compensation in exchange for copies.If you distribute a large enough number of copies you must also follow the conditionsin section 3.

You may also lend copies, under the same conditions stated above, and you may publiclydisplay copies.

3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) ofthe Document, numbering more than 100, and the Document’s license notice requiresCover Texts, you must enclose the copies in covers that carry, clearly and legibly, allthese Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts onthe back cover. Both covers must also clearly and legibly identify you as the publisherof these copies. The front cover must present the full title with all words of the titleequally prominent and visible. You may add other material on the covers in addition.Copying with changes limited to the covers, as long as they preserve the title of theDocument and satisfy these conditions, can be treated as verbatim copying in otherrespects.

If the required texts for either cover are too voluminous to fit legibly, you should putthe first ones listed (as many as fit reasonably) on the actual cover, and continue therest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100,you must either include a machine-readable Transparent copy along with each Opaquecopy, or state in or with each Opaque copy a computer-network location from whichthe general network-using public has access to download using public-standard networkprotocols a complete Transparent copy of the Document, free of added material. Ifyou use the latter option, you must take reasonably prudent steps, when you begindistribution of Opaque copies in quantity, to ensure that this Transparent copy willremain thus accessible at the stated location until at least one year after the last timeyou distribute an Opaque copy (directly or through your agents or retailers) of thatedition to the public.

It is requested, but not required, that you contact the authors of the Document wellbefore redistributing any large number of copies, to give them a chance to provide youwith an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditionsof sections 2 and 3 above, provided that you release the Modified Version under preciselythis License, with the Modified Version filling the role of the Document, thus licensingdistribution and modification of the Modified Version to whoever possesses a copy ofit. In addition, you must do these things in the Modified Version:


A. Use in the Title Page (and on the covers, if any) a title distinct from that of theDocument, and from those of previous versions (which should, if there were any,be listed in the History section of the Document). You may use the same title asa previous version if the original publisher of that version gives permission.

B. List on the Title Page, as authors, one or more persons or entities responsible forauthorship of the modifications in the Modified Version, together with at least fiveof the principal authors of the Document (all of its principal authors, if it has fewerthan five), unless they release you from this requirement.

C. State on the Title page the name of the publisher of the Modified Version, as thepublisher.

D. Preserve all the copyright notices of the Document.E. Add an appropriate copyright notice for your modifications adjacent to the other

copyright notices.F. Include, immediately after the copyright notices, a license notice giving the public

permission to use the Modified Version under the terms of this License, in the formshown in the Addendum below.

G. Preserve in that license notice the full lists of Invariant Sections and required CoverTexts given in the Document’s license notice.

H. Include an unaltered copy of this License.I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item

stating at least the title, year, new authors, and publisher of the Modified Versionas given on the Title Page. If there is no section Entitled “History” in the Docu-ment, create one stating the title, year, authors, and publisher of the Documentas given on its Title Page, then add an item describing the Modified Version asstated in the previous sentence.

J. Preserve the network location, if any, given in the Document for public access toa Transparent copy of the Document, and likewise the network locations given inthe Document for previous versions it was based on. These may be placed in the“History” section. You may omit a network location for a work that was publishedat least four years before the Document itself, or if the original publisher of theversion it refers to gives permission.

K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Titleof the section, and preserve in the section all the substance and tone of each of thecontributor acknowledgements and/or dedications given therein.

L. Preserve all the Invariant Sections of the Document, unaltered in their text andin their titles. Section numbers or the equivalent are not considered part of thesection titles.

M. Delete any section Entitled “Endorsements”. Such a section may not be includedin the Modified Version.

N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict intitle with any Invariant Section.

O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualifyas Secondary Sections and contain no material copied from the Document, you may at


your option designate some or all of these sections as invariant. To do this, add theirtitles to the list of Invariant Sections in the Modified Version’s license notice. Thesetitles must be distinct from any other section titles.You may add a section Entitled “Endorsements”, provided it contains nothing butendorsements of your Modified Version by various parties—for example, statements ofpeer review or that the text has been approved by an organization as the authoritativedefinition of a standard.You may add a passage of up to five words as a Front-Cover Text, and a passage of upto 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the ModifiedVersion. Only one passage of Front-Cover Text and one of Back-Cover Text may beadded by (or through arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you or by arrangementmade by the same entity you are acting on behalf of, you may not add another; butyou may replace the old one, on explicit permission from the previous publisher thatadded the old one.The author(s) and publisher(s) of the Document do not by this License give permissionto use their names for publicity for or to assert or imply endorsement of any ModifiedVersion.

5. COMBINING DOCUMENTSYou may combine the Document with other documents released under this License,under the terms defined in section 4 above for modified versions, provided that youinclude in the combination all of the Invariant Sections of all of the original documents,unmodified, and list them all as Invariant Sections of your combined work in its licensenotice, and that you preserve all their Warranty Disclaimers.The combined work need only contain one copy of this License, and multiple identicalInvariant Sections may be replaced with a single copy. If there are multiple InvariantSections with the same name but different contents, make the title of each such sectionunique by adding at the end of it, in parentheses, the name of the original author orpublisher of that section if known, or else a unique number. Make the same adjustmentto the section titles in the list of Invariant Sections in the license notice of the combinedwork.In the combination, you must combine any sections Entitled “History” in the vari-ous original documents, forming one section Entitled “History”; likewise combine anysections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. Youmust delete all sections Entitled “Endorsements.”

6. COLLECTIONS OF DOCUMENTSYou may make a collection consisting of the Document and other documents releasedunder this License, and replace the individual copies of this License in the variousdocuments with a single copy that is included in the collection, provided that youfollow the rules of this License for verbatim copying of each of the documents in allother respects.You may extract a single document from such a collection, and distribute it individu-ally under this License, provided you insert a copy of this License into the extracteddocument, and follow this License in all other respects regarding verbatim copying ofthat document.


7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independentdocuments or works, in or on a volume of a storage or distribution medium, is calledan “aggregate” if the copyright resulting from the compilation is not used to limit thelegal rights of the compilation’s users beyond what the individual works permit. Whenthe Document is included in an aggregate, this License does not apply to the otherworks in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document,then if the Document is less than one half of the entire aggregate, the Document’s CoverTexts may be placed on covers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form. Otherwise theymust appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translationsof the Document under the terms of section 4. Replacing Invariant Sections withtranslations requires special permission from their copyright holders, but you mayinclude translations of some or all Invariant Sections in addition to the original versionsof these Invariant Sections. You may include a translation of this License, and all thelicense notices in the Document, and any Warranty Disclaimers, provided that youalso include the original English version of this License and the original versions ofthose notices and disclaimers. In case of a disagreement between the translation andthe original version of this License or a notice or disclaimer, the original version willprevail.

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “His-tory”, the requirement (section 4) to Preserve its Title (section 1) will typically requirechanging the actual title.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expresslyprovided under this License. Any attempt otherwise to copy, modify, sublicense, ordistribute it is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particularcopyright holder is reinstated (a) provisionally, unless and until the copyright holderexplicitly and finally terminates your license, and (b) permanently, if the copyrightholder fails to notify you of the violation by some reasonable means prior to 60 daysafter the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently ifthe copyright holder notifies you of the violation by some reasonable means, this is thefirst time you have received notice of violation of this License (for any work) from thatcopyright holder, and you cure the violation prior to 30 days after your receipt of thenotice.

Termination of your rights under this section does not terminate the licenses of partieswho have received copies or rights from you under this License. If your rights havebeen terminated and not permanently reinstated, receipt of a copy of some or all of thesame material does not give you any rights to use it.


10. FUTURE REVISIONS OF THIS LICENSEThe Free Software Foundation may publish new, revised versions of the GNU FreeDocumentation License from time to time. Such new versions will be similar in spiritto the present version, but may differ in detail to address new problems or concerns.See http://www.gnu.org/copyleft/.Each version of the License is given a distinguishing version number. If the Documentspecifies that a particular numbered version of this License “or any later version”applies to it, you have the option of following the terms and conditions either of thatspecified version or of any later version that has been published (not as a draft) bythe Free Software Foundation. If the Document does not specify a version number ofthis License, you may choose any version ever published (not as a draft) by the FreeSoftware Foundation. If the Document specifies that a proxy can decide which futureversions of this License can be used, that proxy’s public statement of acceptance of aversion permanently authorizes you to choose that version for the Document.

11. RELICENSING“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World WideWeb server that publishes copyrightable works and also provides prominent facilitiesfor anybody to edit those works. A public wiki that anybody can edit is an example ofsuch a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in thesite means any set of copyrightable works thus published on the MMC site.“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license pub-lished by Creative Commons Corporation, a not-for-profit corporation with a principalplace of business in San Francisco, California, as well as future copyleft versions of thatlicense published by that same organization.“Incorporate” means to publish or republish a Document, in whole or in part, as partof another Document.An MMC is “eligible for relicensing” if it is licensed under this License, and if all worksthat were first published under this License somewhere other than this MMC, andsubsequently incorporated in whole or in part into the MMC, (1) had no cover textsor invariant sections, and (2) were thus incorporated prior to November 1, 2008.The operator of an MMC Site may republish an MMC contained in the site underCC-BY-SA on the same site at any time before August 1, 2009, provided the MMC iseligible for relicensing.

http://www.gnu.org/copyleft/


ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in thedocument and put the following copyright and license notices just after the title page:

Copyright (C) year your name.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3

or any later version published by the Free Software Foundation;

with no Invariant Sections, no Front-Cover Texts, and no Back-Cover

Texts. A copy of the license is included in the section entitled ‘‘GNU

Free Documentation License’’.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the“with. . .Texts.” line with this:

with the Invariant Sections being list their titles, with

the Front-Cover Texts being list, and with the Back-Cover Texts

being list.

If you have Invariant Sections without Cover Texts, or some other combination of thethree, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasingthese examples in parallel under your choice of free software license, such as the GNUGeneral Public License, to permit their use in free software.

Index 62

Index

((*errfun) of gdbm_recovery . . . . . . . . . . . . . . . . . . 22

---newdb, gdbmtool option . . . . . . . . . . . . . . . . . . . . . 37--read-only, gdbmtool option . . . . . . . . . . . . . . . . . 37-n, gdbmtool option . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-r, gdbmtool option . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

.

.gdbmtoolrc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

?? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

_GDBM_MAX_ERRNO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28_GDBM_MIN_ERRNO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Aavail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Bbackup_name of gdbm_recovery . . . . . . . . . . . . . . . . 23blocksize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40bucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Ccache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42cachesize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40centfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42close-on-exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5closing database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7coalesce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41command line options, gdbmtool . . . . . . . . . . . . . . . 37compatibility layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33confirm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42creating a database, gdbmtool . . . . . . . . . . . . . . . . . 37current . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Ddata of gdbm_recovery . . . . . . . . . . . . . . . . . . . . . . . . 23database options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24database reorganization . . . . . . . . . . . . . . . . . . . . . . . . 14

database synchronization . . . . . . . . . . . . . . . . . . . . . . 15database, closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7database, opening or creating . . . . . . . . . . . . . . . . . . . 5datum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2dbm.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33dbm_clearerr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbm_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33dbm_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbm_dirfno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35dbm_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbm_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33dbm_firstkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbm_nextkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbm_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33dbm_pagfno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35dbm_rdonly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35dbm_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34DBM functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35DBM_INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34DBM_REPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34dbmclose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35dbminit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43default database, gdbmtool . . . . . . . . . . . . . . . . . . . . 37delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35, 43deleting records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11deletion in iteration loops . . . . . . . . . . . . . . . . . . . . . . 12delim1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40delim2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43‘dir’ file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Eerror code, most recent . . . . . . . . . . . . . . . . . . . . . . . . 20error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30error strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20exit code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 43

Ffailed_buckets of gdbm_recovery . . . . . . . . . . . . . 23failed_keys of gdbm_recovery . . . . . . . . . . . . . . . . 23fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35, 43fetching records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10filemode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41first . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43firstkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Flat file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Ggdbm.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2gdbm_check_syserr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Index 63

gdbm_clear_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gdbm_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7gdbm_copy_meta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6gdbm_count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8gdbm_db_strerror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gdbm_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11gdbm_delete and sequential access . . . . . . . . . . . . . 12gdbm_dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 49gdbm_dump_to_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_errlist[] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28gdbm errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20, 28gdbm_exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10gdbm_export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_export_to_file . . . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_fd_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6gdbm_fdesc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27gdbm_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10gdbm_firstkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12gdbm_import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_import_from_file . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_last_errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gdbm_last_syserr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gdbm_load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17, 50gdbm_load_from_file . . . . . . . . . . . . . . . . . . . . . . . . . 18gdbm_needs_recovery . . . . . . . . . . . . . . . . . . . . . . . . . 21gdbm_nextkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12gdbm_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5gdbm_recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22gdbm_reorganize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14gdbm_setopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24gdbm_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9gdbm_strerror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gdbm_sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15gdbm_syserr[] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28gdbm_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28gdbm_version_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29gdbm_version_number[3] . . . . . . . . . . . . . . . . . . . . . . 28GDBM_BACKUP_FAILED . . . . . . . . . . . . . . . . . . . . . . . . . . 32GDBM_BAD_FILE_OFFSET . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_BAD_MAGIC_NUMBER . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_BAD_OPEN_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_BLOCK_SIZE_ERROR . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_BSEXACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 30GDBM_BYTE_SWAPPED . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_CACHESIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_CANNOT_REPLACE . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_CANT_BE_READER . . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_CANT_BE_WRITER . . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_CENTFREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_CLOEXEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GDBM_COALESCEBLKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_DIR_OVERFLOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32GDBM_EMPTY_DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_ERR_FILE_MODE . . . . . . . . . . . . . . . . . . . . . . . 17, 32GDBM_ERR_FILE_OWNER . . . . . . . . . . . . . . . . . . . . . . 17, 32GDBM_FASTMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2GDBM_FILE_EOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

GDBM_FILE_OPEN_ERROR . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_FILE_READ_ERROR . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_FILE_SEEK_ERROR . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_FILE_STAT_ERROR . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_FILE_WRITE_ERROR . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_GETBLOCKSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26GDBM_GETCACHESIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_GETCOALESCEBLKS . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_GETDBNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26GDBM_GETFLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_GETMAXMAPSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_GETMMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_GETSYNCMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_ILLEGAL_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9GDBM_ITEM_NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_MALLOC_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_NEED_RECOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . 32GDBM_NEWDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GDBM_NO_DBNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32GDBM_NO_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30GDBM_NOLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 27GDBM_NOMMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GDBM_OPT_ALREADY_SET . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_OPT_ILLEGAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31GDBM_RCVR_BACKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23GDBM_RCVR_ERRFUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22GDBM_RCVR_FORCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23GDBM_RCVR_MAX_FAILED_BUCKETS . . . . . . . . . . . . . . . 23GDBM_RCVR_MAX_FAILED_KEYS . . . . . . . . . . . . . . . . . . 23GDBM_RCVR_MAX_FAILURES . . . . . . . . . . . . . . . . . . . . . . 23GDBM_READER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GDBM_READER_CANT_DELETE . . . . . . . . . . . . . . . . . . . . . 30GDBM_READER_CANT_REORGANIZE . . . . . . . . . . . . . . . . 31GDBM_READER_CANT_STORE . . . . . . . . . . . . . . . . . . . . . . 31GDBM_REORGANIZE_FAILED . . . . . . . . . . . . . . . . . . . . . . 31GDBM_REPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9GDBM_SETCACHESIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_SETCENTFREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_SETCOALESCEBLKS . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_SETMAXMAPSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_SETMMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25GDBM_SETSYNCMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_SYNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 15GDBM_SYNCMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24GDBM_VERSION_MAJOR . . . . . . . . . . . . . . . . . . . . . . . . . . 28GDBM_VERSION_MINOR . . . . . . . . . . . . . . . . . . . . . . . . . . 28GDBM_VERSION_PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . 28GDBM_WRCREAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GDBM_WRITER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5gdbmtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37global error state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20GNU Readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Hhash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Index 64

help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Iimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 43init file, gdbmtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47interactive mode, gdbmtool . . . . . . . . . . . . . . . . . . . . 38iterating over records . . . . . . . . . . . . . . . . . . . . . . . . . . 12iteration and gdbm_delete . . . . . . . . . . . . . . . . . . . . . 12iteration loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12iteration loop, using ‘NDBM’ . . . . . . . . . . . . . . . . . . . . . 34

Jjunk.gdbm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Llibgdbm_compat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27looking up records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Mmax_failed_buckets of gdbm_recovery . . . . . . . . 23max_failed_keys of gdbm_recovery . . . . . . . . . . . . 23max_failures of gdbm_recovery . . . . . . . . . . . . . . . 23mmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41most recent error code . . . . . . . . . . . . . . . . . . . . . . . . . 20

Nndbm.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33NDBM functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44nextkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36number of records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Oopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40, 44opening the database . . . . . . . . . . . . . . . . . . . . . . . . . . . 5options, database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

P‘pag’ file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33pager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40ps1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39ps2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Qquiet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Rread-only mode, gdbmtool . . . . . . . . . . . . . . . . . . . . . 37readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39record, deleting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11record, fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10records, iterating over . . . . . . . . . . . . . . . . . . . . . . . . . 12records, storing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9records, testing existence . . . . . . . . . . . . . . . . . . . . . . 10recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44recovered_buckets of gdbm_recovery . . . . . . . . . 23recovered_keys of gdbm_recovery . . . . . . . . . . . . . 23reorganization, database . . . . . . . . . . . . . . . . . . . . . . . 14reorganize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Ssequential access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12sequential access, using ‘NDBM’ . . . . . . . . . . . . . . . . . . 34set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45startup file, gdbmtool . . . . . . . . . . . . . . . . . . . . . . . . . . 47status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35, 45storing records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41synchronization, database . . . . . . . . . . . . . . . . . . . . . . 15

Uunset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Vvariables, gdbmtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45version number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28