(gdbm.info.gz) Sequential

Info Catalog

(gdbm.info.gz) Delete

(gdbm.info.gz) Top

(gdbm.info.gz) Reorganization

 
 9 Sequential access to records.
 *******************************
 
 The next two functions allow for accessing all items in the database.
 This access is not `key' sequential, but it is guaranteed to visit every
 `key' in the database once.  The order has to do with the hash values.
 `gdbm_firstkey' starts the visit of all keys in the database.
 `gdbm_nextkey' finds and reads the next entry in the hash structure for
 `dbf'.
 
  -- gdbm interface: datum gdbm_firstkey (GDBM_FILE DBF)
      Initiate sequential access to the database DBF.  The returned
      value is the first key accessed in the database.  If the `dptr'
      field in the returned datum is `NULL', the database contains no
      data.
 
      Otherwise, `dptr' points to a memory block obtained from `malloc',
      which holds the key value.  The caller is responsible for freeing
      this memory block when no longer needed.
 
  -- gdbm interface: datum gdbm_nextkey (GDBM_FILE DBF, datum PREV)
      This function continues the iteration over the keys in DBF,
      initiated by `gdbm_firstkey'.  The parameter PREV holds the value
      returned from a previous call to `gdbm_nextkey' or `gdbm_firstkey'.
 
      The function returns next key from the database.  If the `dptr'
      field in the returned datum is `NULL', all keys in the database
      has been visited.
 
      Otherwise, `dptr' points to a memory block obtained from `malloc',
      which holds the key value.  The caller is responsible for freeing
      this memory block when no longer needed.
 
    These functions were intended to visit the database in read-only
 algorithms, for instance, to validate the database or similar
 operations.  The usual algorithm for sequential access is:
 
         key = gdbm_firstkey (dbf);
         while (key.dptr)
           {
              datum nextkey;
 
              /* do something with the key */
              ...
 
              /* Obtain the next key */
              nextkey = gdbm_nextkey (dbf, key);
              /* Reclaim the memory used by the key */
              free (key.dptr);
              /* Use nextkey in the next iteration. */
              key = nextkey;
           }
 
    Care should be taken when the `gdbm_delete' function is used in such
 a loop.  File visiting is based on a "hash table".  The `gdbm_delete'
 function re-arranges the hash table to make sure that any collisions in
 the table do not leave some item "un-findable".  The original key order
 is _not_ guaranteed to remain unchanged in all instances.  So it is
 possible that some key will not be visited if a loop like the following
 is executed:
 
         key = gdbm_firstkey (dbf);
         while (key.dptr)
           {
              datum nextkey;
              if (some condition)
                {
                   gdbm_delete (dbf, key);
                }
               nextkey = gdbm_nextkey (dbf, key);
               free (key.dptr);
               key = nextkey;
            }
 

Info Catalog

(gdbm.info.gz) Delete

(gdbm.info.gz) Top

(gdbm.info.gz) Reorganization