Pike Manual

14.5 Gdbm

Gdbm is short for GNU Data Base Manager. It provides a simple data base similar to a file system. The functionality is similar to a mapping, but the data is located on disk, not in memory. Each gdbm database is one file which contains a key-pair values, both keys and values have to be strings. All keys are always unique, just as with a mapping.

This is the an interface to the gdbm library. This module might or might not be available in your Pike depending on whether the gdbm library was available on your system when Pike was compiled.

METHOD

Gdbm.gdbm.create - open database

SYNTAX

int create(); int create(string file); int create(string file, string mode); object(Gdbm) Gdbm(); object(Gdbm) Gdbm(string file); object(Gdbm) Gdbm(string file, string mode);

DESCRIPTION

Without arguments, this function does nothing. With one argument it opens the given file as a gdbm database, if this fails for some reason, an error will be generated. If a second argument is present, it specifies how to open the database using one or more of the follow flags in a string:

r open database for reading

w open database for writing

c create database if it does not exist

t overwrite existing database

f fast mode

The fast mode prevents the database from synchronizing each change in the database immediately. This is dangerous because the database can be left in an unusable state if Pike is terminated abnormally.

The default mode is "rwc".

METHOD: Gdbm.gdbm.close - close database
SYNTAX: void close();
DESCRIPTION: This closes the database.

METHOD: Gdbm.gdbm.store - store a value in the database
SYNTAX: int store(string key, string data);
DESCRIPTION: Associate the contents of data with the key key. If the key key already exists in the database the data for that key will be replaced. If it does not exist it will be added. An error will be generated if the database was not open for writing.

METHOD: Gdbm.gdbm.fetch - fetch a value from the database
SYNTAX: string fetch(string key);
DESCRIPTION: Returns the data associated with the key key in the database. If there was no such key in the database, zero is returned.

METHOD: Gdbm.gdbm.delete - delete a value from the database
SYNTAX: int delete(string key);
DESCRIPTION: Remove a key from the database. Note that no error will be generated if the key does not exist.

METHOD: Gdbm.gdbm.firstkey - get first key in database
SYNTAX: string firstkey();
DESCRIPTION: Returns the first key in the database, this can be any key in the database.

METHOD

Gdbm.gdbm.nextkey - get next key in database

SYNTAX

string nextkey(string key);

DESCRIPTION

This returns the key in database that follows the key key. This is of course used to iterate over all keys in the database.

EXAMPLE

/* Write the contents of the database */ for(key=gdbm->firstkey(); k; k=gdbm->nextkey(k)) write(k+":"+gdbm->fetch(k)+"\n");

METHOD: Gdbm.gdbm.reorganize - reorganize database
SYNTAX: int reorganize();
DESCRIPTION: Deletions and insertions into the database can cause fragmentation which will make the database bigger. This routine reorganizes the contents to get rid of fragmentation. Note however that this function can take a LOT of time to run.

METHOD: Gdbm.gdbm.sync - synchronize database
SYNTAX: void sync();
DESCRIPTION: When opening the database with the 'f' flag writings to the database can be cached in memory for a long time. Calling sync will write all such caches to disk and not return until everything is stored on the disk.

Previous section

To contents

Next section

r	open database for reading
w	open database for writing
c	create database if it does not exist
t	overwrite existing database
f	fast mode