gdbm_open (name, block_size, read_write, mode, fatal_func) [gdbm]|
int dbminit (name) [dbm]
*dbm_open (name, flags, mode) [ndbm]
char * name
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".
int block_size, read_write, flags, mode
void (*fatal_func) ();
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:
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.
- 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
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]
These functions close files. Duh.
gdbm_store (dbf, key, content, flag) [gdbm]
store (key, content) [dbm]
dbm_store (file, key, content, flags) [ndbm]
Stores a value into a database file with key key and data content. The flag
parameter (or flags under ndbm) may be one of:
datum key, content
int flag, flags;
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.
- 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_fetch (dbf, key) [gdbm]
fetch (key) [dbm]
dbm_fetch (file, key) [ndbm]
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!
gdbm_exists (dbf, key) [gdbm only]
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.
gdbm_delete (dbf, key) [gdbm]
delete (key) [dbm]
dbm_delete (file, key) [ndbm]
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.
gdbm_firstkey (dbf) [gdbm]
firstkey () [dbm]
dbm_firstkey (file) [ndbm]
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.
gdbm_nextkey (dbf, key) [gdbm]
nextkey (key) [dbm]
dbm_nextkey (file) [ndbm]
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.
gdbm_reorganize (dbf) [gdbm only]
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.
gdbm_sync (dbf) [gdbm only]
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.
gdbm_strerror (errno) [gdbm only]
Returns a nice error message for the given error.
gdbm_setopt (dbf, option, value, size) [gdbm only]
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:
Sets the size of the internal bucket cache, by default 100. You can reset it once on any
given file descriptor.
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.
dbm_error (DBM *file) [ndbm only]
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)
dbm_pagfno (DBM *file) [ndbm only]
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.