/I<Berkeley DB Reference Guide: Programmer Notes[P6

Berkeley DB Reference Guide: Programmer Notes



3

Error returns to applications



µExcept for the historic dbm, ndbm and hsearchHinterfaces, Berkeley DB does not use the global variable errno toreturn error values.IThe return values for all Berkeley DB functions can be grouped into three categories:

L

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

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

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


HWhile possible error returns are specified by each individual function'sHmanual page, there are a few error returns that deserve special mention:

EAGAIN

IWhen multiple processes or threads of control are modifying the database,Ithere is normally the potential for deadlock. In Berkeley DB, deadlock isNsignified by an error return from the Berkeley DB function of the errnoLvalue EAGAIN. Whenever a Berkeley DB function returns EAGAIN, the enclosingtransaction should be aborted.

NAny Berkeley DB function that attempts to acquire locks can potentially returnGEAGAIN. Practically speaking, the safest way to deal with applicationsMthat can deadlock is to handle a potential EAGAIN return from any Berkeley DBAccess Method call.$

DB_NOTFOUND and DB_KEYEMPTY



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

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

GThe DB_KEYEMPTY error return indicates that the requested key/data pairIlogically exists but was never explicitly created by the application (theGrecno access method will automatically create key/data pairs under somecircumstances, see.db_openfor more information),Mor that the requested key/data pair was deleted and is currently in a deletedstate.

DB_RUNRECOVERY



LThere exists a class of errors that Berkeley DB considers fatal to an entireIBerkeley DB environment. An example of this type of error is a log writeHfailure due to the disk being out of free space. The only way to recoverGfrom these failures is for the application to exit, run recovery of theUBerkeley DB environment, and re-enter Berkeley DB. (It is not strictly necessary thatEthe application exit, although that is the only way to recover systemDresources, e.g., file descriptors and memory, currently allocated by Berkeley DB.)

7When this type of error is encountered, the error value=DB_RUNRECOVERY is returned. This error can be returned by anyFBerkeley DB interface. If a fatal error occurs, DB_RUNRECOVERY will beOreturned from all subsequent Berkeley DB calls made by any threads or processes!participating in the environment.

IOptionally, applications may also specify a fatal-error callback function@by setting the db_paniccall field of the DB_ENV structure beforeiinitializing the environment with db_appinit. This callbackEfunction will be called with two arguments: a reference to the DB_ENVEstructure associated with the environment, and the errno value=associated with the underlying error that caused the problem.

IApplications can handle such fatal errors in one of two ways: by checkingCfor DB_RUNRECOVERY as part of their normal Berkeley DB error returnJchecking, similarly to EAGAIN or any other error, or, in applications thatJhave no cleanup processing of their own, by simply exiting the application%when the callback function is called.

QAMÿÿ