NAME
	Dbm.dbm - database interface

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

	A dbm database has essentially the same functionality as a mapping,
	except the syntax is different, and it is located on disk, not in
	memory. Each dbm 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 dbm->create();
	or
	int dbm->create(string file);
	or
	int dbm->create(string file, string mode);

DESCRIPTION
	Without arguments, this function does nothing. With one argument it
	opens the given file as a dbm 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 dbm 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 dbm objects when exiting your
	program. This will probably be done automatically in the future.

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

SYNTAX
	void dbm->close();

DESCRIPTION
	This closes the database.

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

SYNTAX
	int dbm->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 dbm->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 dbm->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 dbm->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 dbm->nextkey();

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=dbm->firstkey(); k; k=dbm->nextkey())
	  write(k+":"+dbm->fetch(k)+"\n");

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