Berkeley DB Programmer's Reference: Programmer Notes

Berkeley DB Programmer's Reference: Programmer Notes

Error returns to applications

Except for the historic dbm, ndbm and hsearch interfaces, Berkeley DB does not use the global variable errno to return error values. The return values for all Berkeley DB functions can be grouped into three categories:

0
A return value of 0 indicates that the operation was successful.

> 0
A return value that is greater than 0 indicates that there was a system error. The errno value returned by the system is returned by the function, e.g., when a Berkeley DB function is unable to allocate memory, the return value from the function will be ENOMEM.

< 0
A return value that is less than 0 indicates a condition that was not a system failure, but was not an unqualified success, either. For example, a routine to retrieve a key/data pair from the database may return DB_NOTFOUND when the key/data pair does not appear in the database, as opposed to the value of 0, which would be returned if the key/data pair were found in the database. All such special values returned by Berkeley DB functions are less than 0 in order to avoid conflict with possible values of errno.

There are two special return values that are somewhat similar in meaning, are returned in similar situations, and therefore might be confused: DB_NOTFOUND and DB_KEYEMPTY.

The DB_NOTFOUND error return indicates that the requested key/data pair did not exist in the database or that start- or end-of-file has been reached.

The DB_KEYEMPTY error return indicates that the requested key/data pair logically exists but was never explicitly created by the application (the recno access method will automatically create key/data pairs under some circumstances, see db_open for more information), or that the requested key/data pair was deleted and is currently in a deleted state.