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.
|
