6 Inserting and replacing records in the database

gdbm interface: int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag)

The function gdbm_store inserts or replaces records in the database.

The parameters are:

dbf

The pointer returned by gdbm_open.

key

The search key.

content

The data to be associated with the key.

flag

Defines the action to take when the key is already in the database. The value GDBM_REPLACE asks that the old data be replaced by the new content. The value GDBM_INSERT asks that an error be returned and no action taken if the key already exists.

This function can return the following values:

0

Success. The value of content is keyed by key in the database.

-1

An error occurred which prevented the item from being stored in the database. Examine the gdbm_errno variable to determine the actual cause of the error.

+1

The item was not stored because the argument flag was GDBM_INSERT and the key was already in the database. The gdbm_errno variable is set to GDBM_CANNOT_REPLACE.

If the function returns -1, gdbm_errno can have the following values:

GDBM_READER_CANT_STORE

Database was open in read-only mode, i.e. with the GDBM_READER flag. See Open.

GDBM_MALFORMED_DATA

Either key or content had their dptr field set to NULL.

It is OK to have a zero-length key or content, i.e. a datum with dsize set to 0, but the dptr field must always be a non-NULL value.

GDBM_BAD_HASH_TABLE

Database hash table is malformed. This usually means that some error in the application or the library caused memory overrun. The database is marked as needing recovery. All further calls on this database will return with gdbm_error set to GDBM_NEED_RECOVERY. See Recovery, for a discussion of database recovery process.

GDBM_BAD_DIR_ENTRY

Database directory entry is corrupted. The database is marked as needing recovery. See Recovery.

GDBM_BAD_BUCKET

Database bucket is corrupted. The database is marked as needing recovery. See Recovery.

GDBM_BAD_AVAIL

Database available storage index is corrupted. The database is marked as needing recovery. See Recovery.

GDBM_FILE_SEEK_ERROR

A seek error occurred on the underlying disk file. Examine the system errno variable for more detail.

If you store data for a key that is already in the data base, GDBM replaces the old data with the new data if called with GDBM_REPLACE. You do not get two data items for the same key and you do not get an error from gdbm_store.

The size of datum in GDBM is restricted only by the maximum value for an object of type int (type of the dsize member of datum).