dbm Functions

These functions allow you to store records stored in a dbm-style database. This type of database (supported by the Berkeley db, gdbm, and some system libraries, as well as a built-in flatfile library) stores key/value pairs (as opposed to the full-blown records supported by relational databases).

dbm Functions

dbmopen

Name

dbmopen — opens a dbm database

Description

int dbmopen(string filename, int flags);

The first argument is the full-path filename of the dbm file to be opened and the second is the file open mode which is one of "r", "n" or "w" for read-only, new (implies read-write) and read-write respectively.

Returns an identifer to be passed to the other dbm functions on success, or false on failure.

If ndbm support is used, ndbm will actually create filename.dir and filename.pag files. gdbm only uses one file, as does the internal flat-file support, and Berkeley db creates a filename.db file. Note that PHP does its own file locking in addition to any file locking that may be done by the dbm library itself. PHP does not delete the .lck files it creates. It uses these files simply as fixed inodes on which to do the file locking. For more information on dbm files, see your Unix man pages, or obtain GNU's gdbm from ftp://prep.ai.mit.edu/pub/gnu.

dbmclose

Name

dbmclose — closes a dbm database

Description

bool dbmclose(int dbm_identifier);

Unlocks and closes the specified database.

dbmexists

Name

dbmexists — tells if a value exists for a key in a dbm database

Description

bool dbmexists(int dbm_identifier, string key);

Returns true if there is a value associated with the key.

dbmfetch

Name

dbmfetch — fetches a value for a key from a dbm database

Description

string dbmfetch(int dbm_identifier, string key);

Returns the value associated with key.

dbminsert

Name

dbminsert — inserts a value for a key in a dbm database

Description

int dbminsert(int dbm_identifier, string key, string value);

Adds the value to the database with the specified key.

Returns -1 if the database was opened read-only, 0 if the insert was successful, and 1 if the specified key already exists. (To replace the value, use dbmreplace.)

dbmreplace

Name

dbmreplace — replaces the value for a key in a dbm database

Description

bool dbmreplace(int dbm_identifier, string key, string value);

Replaces the value for the specified key in the database.

This will also add the key to the database if it didn't already exist.

dbmdelete

Name

dbmdelete — deletes the value for a key from a dbm database

Description

bool dbmdelete(int dbm_identifier, string key);

Deletes the value for key in the database.

Returns false if the key didn't exist in the database.

dbmfirstkey

Name

dbmfirstkey — retrieves the first key from a dbm database

Description

string dbmfirstkey(int dbm_identifier);

Returns the first key in the database. Note that no particular order is guaranteed since the database may be built using a hash-table, which doesn't guarantee any ordering.

dbmnextkey

Name

dbmnextkey — retrieves the next key from a dbm database

Description

string dbmnextkey(int dbm_identifier, string key);

Returns the next key after key. By calling dbmfirstkey followed by successive calls to dbmnextkey

it is possible to visit every key/value pair in the dbm database. For example:

Example 1. Visiting every key/value pair in a dbm database.

$key = dbmfirstkey($dbm_id); while ($key) {

echo "$key = " . dbmfetch($dbm_id, $key) . "\n";

$key = dbmnextkey($dbm_id, $key);

}

dblist

Name

dblist — describes the dbm-compatible library being used

Description

string dblist(void);