Topic: gdbm -- Functions and data types

up to gdbm index ]
The gdbm library provides three modes, gdbm, dbm, and ndbm, the last two of which are provided for reverse compatibility. All three use the same data structures, but they have different file formats. This API description lists the functions together where they are equivalent in the three modes.

DATA STRUCTURES

GDBM_FILE and DBM
Structures used to identify an open file for gdbm and ndbm modes. GDBM_FILE is passed as is, not as a pointer like stdio's FILE *, but DBM is used exactly like that: DBM *. The dbm mode has no corresponding structure, because only one file may be open at a time in dbm mode.

datum
The datum is a simple structure:

typedef struct {
   char *dptr;
   int  dsize;
} datum;
It's used to pass keys and data back and forth from all functions in gdbm. Note that this means you're not dependent on the null terminator, but for ease of use, many programs still include the null terminator in keys and data. If your program must interact with others, be sure you understand whether the others are including those terminators or not.


gdbm_error
This is an enumerated type, with the following possible values (along with the error messages that
gdbm_strerr returns.) As you can see, the stock error messages don't tell you a lot more than you already know, but fortunately all the error returns are pretty obvious after reading the description of the function that returns them.
0 GDBM_NO_ERROR No error
1GDBM_MALLOC_ERRORMalloc error
2GDBM_BLOCK_SIZE_ERRORBlock size error
3GDBM_FILE_OPEN_ERRORFile open error
4GDBM_FILE_WRITE_ERRORFile write error
5GDBM_FILE_SEEK_ERRORFile seek error
6GDBM_FILE_READ_ERRORFile read error
7GDBM_BAD_MAGIC_NUMBERBad magic number
8GDBM_EMPTY_DATABASEEmpty database
9GDBM_CANT_BE_READERCan't be reader
10GDBM_CANT_BE_WRITERCan't be writer
11GDBM_READER_CANT_DELETEReader can't delete
12GDBM_READER_CANT_STOREReader can't store
13GDBM_READER_CANT_REORGANIZEReader can't reorganize
14GDBM_UNKNOWN_UPDATEUnknown update
15GDBM_ITEM_NOT_FOUNDItem not found
16GDBM_REORGANIZE_FAILEDReorganize failed
17GDBM_CANNOT_REPLACECannot replace
18GDBM_ILLEGAL_DATAIllegal data
19GDBM_OPT_ALREADY_SETOption already set
20GDBM_OPT_ILLEGALIllegal option


EXTERN VARIABLES

extern gdbm_error gdbm_errno
Contains the error number of the last error encountered.

extern char *gdbm_version
Points to a version string suitable for framing.


FUNCTIONS
open ] [ close ] [ store ] [ fetch ] [ key existence ] [ delete ] [ first key ] [ next key ]
GDBM_FILE gdbm_open (name, block_size, read_write, mode, fatal_func) [gdbm]
int dbminit (name) [dbm]
DBM *dbm_open (name, flags, mode) [ndbm]
char * name
int block_size, read_write, flags, mode
void (*fatal_func) ();
Each function opens the database file named by name. In gdbm mode, the file is named normally; in dbm and ndbm modes each database consists of two files with extensions .dir and .pag, so name refers to the common name without extensions. So a database named "aliases" resides in the files "aliases.dir" and "aliases.pag", and name is specified as "aliases".

The blocksize is meaningful only when creating a new gdbm database; it is the retrieval block size to be used for the file. If a number less than 256 is given, the system stat page size will be used, but if you are storing large chunks of data in your file, you may want to consider bumping blocksize up.

The read_write parameter may take the following values:

  • GDBM_READER to open the file as a reader
  • GDBM_WRITER to open the file as a writer
  • GDBM_WRCREAT to open as a writer and create the file if it doesn't exist
  • GDBM_NEWDB to open as a writer and overwrite any existing file
There may be only one writer at a time, but an arbitrary number of readers. If a file is open for writing, attempts to open it for reading will fail. For any of the writer variations above, you can also bitwise-OR a flag GDBM_FAST into the flags; this causes gdbm to avoid writing data to the file until told to do so by gdbm_sync. You can also get this behavior after opening by using gdbm_setopt.

I haven't found documentation for the flags parameter for ndbm.

The mode parameter specifies the mode of a newly created database file; it takes the same form as for Unix chmod, so for instance 0666 is read-write access for everybody.

Finally, fatal_func can be used to assign an error handler; the function should take a single string. If you specify 0 for this function, gdbm uses a default handler.


void gdbm_close (dbf) [gdbm]
int dbmclose () [dbm]
void dbm_close (file) [ndbm]
GDBM_FILE dbf
DBM *file
These functions close files. Duh.


int gdbm_store (dbf, key, content, flag) [gdbm]
int store (key, content) [dbm]
int dbm_store (file, key, content, flags) [ndbm]
GDBM_FILE dbf
DBM *file
datum key, content
int flag, flags;
Stores a value into a database file with key key and data content. The flag parameter (or flags under ndbm) may be one of:
  • GDBM_INSERT to insert a new record
  • GDBM_REPLACE to insert the record but to replace the record if the key is already found.
Gdbm will never create a duplicate key; if GDBM_INSERT is specified, then a return code of 1 will result in the event of a pre-existing key but no new record will be added. If successful, the function returns 0. If a reader attempts to call this function, a return code of -1 results.


datum gdbm_fetch (dbf, key) [gdbm]
datum fetch (key) [dbm]
datum dbm_fetch (file, key) [ndbm]
GDBM_FILE dbf
DBM *file
datum key
Retrieves the contents of key key into the return value. If key isn't found in the database, then the dptr of the return datum will be NULL. The dptr points to a data buffer which is allocated with malloc so you have to free it when you're done with it. If you don't like that kind of discipline, well then, switch to Java, bucko!


int gdbm_exists (dbf, key) [gdbm only]
GDBM_FILE dbf
datum key
Checks for the existence of a key key without the memory allocation required by a fetch. If the key exists, the return value will be true, otherwise it's 0.


int gdbm_delete (dbf, key) [gdbm]
int delete (key) [dbm]
int dbm_delete (file, key) [ndbm]
GDBM_FILE dbf
DBM *file
datum key
Deletes a key. The file will not shrink unless you perform a gdbm_reorganize, but will be reused, if possible, by the next store operation. If the key wasn't present or if the file is opened as a reader, then the return code will be -1.


datum gdbm_firstkey (dbf) [gdbm]
datum firstkey () [dbm]
datum dbm_firstkey (file) [ndbm]
GDBM_FILE dbf
DBM *file
Use this along with the nextkey functions for iterating through all the keys of a database. If you've opened the database in writer mode, though, be careful. If you make any changes while iterating, you're not guaranteed to visit all the keys!

A NULL value for the dptr of the return value means there are no keys in the file.


datum gdbm_nextkey (dbf, key) [gdbm]
datum nextkey (key) [dbm]
datum dbm_nextkey (file) [ndbm]
GDBM_FILE dbf
DBM *file
datum key
Once you've started an iteration with firstkey, you can supply that key to this function to get the next key in the iteration. If you've given the last key in the file, the dptr element of the return value will be NULL, just like firstkey.


int gdbm_reorganize (dbf) [gdbm only]
GDBM_FILE dbf
Use this to shrink your database file if you've done a lot of deletions. This is the only way to get a file to shrink. Ever.


void gdbm_sync (dbf) [gdbm only]
GDBM_FILE dbf
Forces a write to the database if you've used the GDBM_FAST flag with gdbm_open or you've set fast mode using gdbm_setopt. Until a sync is done, gdbm will work from its memory cache wherever possible.


char * gdbm_strerror (errno) [gdbm only]
gdbm_error errno;
Returns a nice error message for the given error.


int gdbm_setopt (dbf, option, value, size) [gdbm only]
GDBM_FILE dbf
int option
int *value
int size
This can be used to set options, of which only two have been defined so far. The value must be in a buffer pointed to by value and the size of the value given in size. The valid options are:
  • GDBM_CACHESIZE
    Sets the size of the internal bucket cache, by default 100. You can reset it once on any given file descriptor.
  • GDBM_FASTMODE
    This allows you to toggle fast mode, regardless of how you originally opened the database. If fast mode is on (a value of TRUE), then gdbm will avoid writing data out to the file unless explicitly told to do so by a call to gdbm_sync.


int dbm_error (DBM *file) [ndbm only]
int dbm_clearerr (DBM *file) [ndbm only]

Included in GDBM only for compilation compatibility. These are defined as macros in the GNU version of ndbm.h because gdbm doesn't really support this functionality:

#define dbm_error(file)  (0)
#define dbm_clearerror(file)


int dbm_pagfno (DBM *file) [ndbm only]
int dbm_dirfno (DBM *file) [ndbm only]

Again, included in gdbm only for compilation compatibility. They return the file numbers for the directory and page files (.dir and .pag) respectively under real ndbm and I frankly don't know what they do under gdbm.






Copyright © 1996-2007 Vivtek. All Rights Reserved. Read the disclaimer.
Read our privacy statement, too, if you are concerned.