dbm_nextkey() — Get next key in database

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <ndbm.h>

datum dbm_nextkey(DBM * db);

General description

The dbm_nextkey() function returns the next key in the database. The argument db is a handle to a database previously obtained by dbm_open(). Since the keys are arbitrary binary data, the order of key return by dbm_firstkey() and dbm_nextkey() does not reflect any lexical ordering. In addition, the return order does not reflect record insertion ordering. All keys can be retrieved from the database by executing a loop such as: 
for (key = dbm_firstkey(db); key.dptr !=NULL; key = dbm_nextkey(db))
That is, establish positioning to the beginning by use of the dbm_firstkey() function, then loop doing dbm_nextkey() function calls until a NULL dptr is returned in datum.

The returned dptr is valid only until the next dbm_ operation by this thread.

Special behavior for z/OS® UNIX Services: In a multithreaded environment, the dbm_nextkey() function returns a pointer to data that is thread-specific. In addition, each thread maintains its own positioning information for dbm_nextkey() operations. However, other threads making modifications to the database, for example using dbm_store() or dbm_delete() can cause unpredictable results for threads executing dbm_nextkey(), including keys retrieved multiple times or not at all. The application must reset positioning to the beginning using dbm_firstkey() if another thread has done a modification to the database.

Returned value

If successful, dbm_nextkey() returns the datum containing a pointer to the key dptr, and the key length dsize.

If unsuccessful, dbm_nextkey() returns a NULL pointer in dptr and returns the error value in errno. Also, the database error indicator may be set.

Related information

Parent topic: Library functions