GNU Info

(gdbm.info)Sequential

---

Next: Reorganization Prev: Delete Up: Top

---

Enter node , (file) or (file)node

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'.

     key = gdbm_firstkey(dbf);
     
     nextkey = gdbm_nextkey(dbf, key);

   The parameters are:

GDBM_FILE dbf
     The pointer returned by `gdbm_open'.

datum `key'

datum nextkey
     The `key' data.

   The return values are both datum. If `key'.dptr or nextkey.dptr is
NULL, there is no first `key' or next `key'. Again notice that dptr
points to data allocated by malloc and `gdbm' will not free it for you.

   These functions were intended to visit the database in read-only
algorithms, for instance, to validate the database or similar
operations.

   File `visiting' is based on a `hash table'. `gdbm_delete'
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. 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 ) {
           nextkey = gdbm_nextkey ( dbf, key );
           if ( some condition ) {
              gdbm_delete ( dbf, key );
              free ( key.dptr );
           }
           key = nextkey;
        }