NAME
	/precompiled/gdbm - database interface

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

	A gdbm database has essentially the same functionality as a mapping,
	except the syntax is different, and it is located on disk, not in
	memory. Each gdbm database is one file which contains a set of
	key-value pairs. Both keys and values are strings and all keys are
	unique.

============================================================================
NAME
	create - open database

SYNTAX
	int gdbm->create();
	or
	int gdbm->create(string file);
	or
	int gdbm->create(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 syncronizing 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".

NOTA BENE
	The gdbm manual states that it is important that the database is
	closed properly. Unfortunately this will not be the case if Pike
	calls exit() or returns from main(). You should therefore make sure
	you call close or destruct your gdbm objects when exiting your
	program. This will probably be done automatically in the future.

============================================================================
NAME
	close - close database

SYNTAX
	void gdbm->close();

DESCRIPTION
	This closes the database.

============================================================================
NAME
	store - store a value in the database

SYNTAX
	int gdbm->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.

============================================================================
NAME
	fetch - fetch a value from the databse

SYNTAX
	string gdbm->fetch(string key);

DESCRIPTION
	Return the data associated with the key 'key' in the database.
	If there was no such key in the database, zero is returned.

============================================================================
NAME
	delete - delete a value from the database

SYNTAX
	int gdbm->delete(string key);

DESCRIPTION
	Remove a key from the database. Note that no error will be generated
	if the key does not exist.

============================================================================
NAME
	firstkey - get first key in database

SYNTAX
	string gdbm->firstkey();

DESCRIPTION
	Return the first key in the database, this can be any key in the
	database.

============================================================================
NAME
	nextkey - get next key in database

SYNTAX
	string gdbm->nextkey(string key);

DESCRIPTION
	This returns the key in database that follows the key '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");

============================================================================
NAME
	reorganize - reorganize database

SYNTAX
	int gdbm->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.

============================================================================
NAME
	sync - synchronize database

SYNTAX
	void gdbm->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.

============================================================================
