File: gdbm.info,  Node: Store,  Next: Fetch,  Prev: Count,  Up: Top

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.  *Note 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'.  *Note Recovery::, for a
          discussion of database recovery process.

     'GDBM_BAD_DIR_ENTRY'
          Database directory entry is corrupted.  The database is marked
          as needing recovery.  *Note Recovery::.

     'GDBM_BAD_BUCKET'
          Database bucket is corrupted.  The database is marked as
          needing recovery.  *Note Recovery::.

     'GDBM_BAD_AVAIL'
          Database available storage index is corrupted.  The database
          is marked as needing recovery.  *Note 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').