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.