Library Version 11.2.5.3

Library Version 12.1.6.1

- + - - + +

Error returns to applications			Error returns to + applications
Prev	Chapter 15. - Programmer Notes -	Next	Chapter 15. Programmer Notes	Next

@@ -34,148 +33,187 @@

Error returns to applications

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 are - grouped into the following three categories: -

+ 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 are grouped into + the following three categories: +

0: A return value of 0 indicates that the operation was successful.; 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; for example, when a Berkeley DB function is unable to allocate -memory, the return value from the function will be ENOMEM.; + 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; for example, 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 values returned by Berkeley DB functions are less than 0 in order to avoid -conflict with possible values of errno. Specifically, Berkeley DB -reserves all values from -30,800 to -30,999 to itself as possible error -values. There are a few Berkeley DB interfaces where it is possible for an -application function to be called by a Berkeley DB function and subsequently -fail with an application-specific return. Such failure returns will be -passed back to the function that originally called a Berkeley DB interface. -To avoid ambiguity about the cause of the error, error values separate -from the Berkeley DB error name space should be used.; + 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 values returned by + Berkeley DB functions are less than 0 in order to + avoid conflict with possible values of errno. Specifically, + Berkeley DB reserves all values from -30,800 to + -30,999 to itself as possible error values. There + are a few Berkeley DB interfaces where it is + possible for an application function to be called + by a Berkeley DB function and subsequently fail + with an application-specific return. Such failure + returns will be passed back to the function that + originally called a Berkeley DB interface. To + avoid ambiguity about the cause of the error, + error values separate from the Berkeley DB error + name space should be used. +

+ Although possible error returns are specified by each + individual function's manual page, there are a few error + returns that deserve general mention: +

- Although possible error returns are specified by each individual - function's manual page, there are a few error returns that deserve - general mention: -

+ DB_NOTFOUND and DB_KEYEMPTY +

- DB_NOTFOUND and DB_KEYEMPTY -

There are two special return values that are similar in meaning and that -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-of- or end-of-file has -been reached by a cursor.

The DB_KEYEMPTY error return indicates that the requested -key/data pair logically exists but was never explicitly created by the -application (the Recno and Queue access methods 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 never re-created. In addition, the Queue access method will return -DB_KEYEMPTY for records that were created as part of a -transaction that was later aborted and never re-created.

+ There are two special return values that are similar in + meaning and that 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-of- or end-of-file has + been reached by a cursor. +

+ The DB_KEYEMPTY error + return indicates that the requested key/data pair logically + exists but was never explicitly created by the application + (the Recno and Queue access methods 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 never re-created. In addition, the Queue access method + will return DB_KEYEMPTY for records that were created as part + of a transaction that was later aborted and never + re-created. +

- DB_KEYEXIST -

- The DB_KEYEXIST error return indicates the DB_NOOVERWRITE option was specified - when inserting a key/data pair into the database and the key already - exists in the database, or the DB_NODUPDATA option was specified and the - key/data pair already exists in the data. -

+ DB_KEYEXIST +

+ The DB_KEYEXIST error + return indicates the DB_NOOVERWRITE option was specified + when inserting a key/data pair into the database and the key + already exists in the database, or the DB_NODUPDATA option + was specified and the key/data pair already exists in the + data. +

- DB_LOCK_DEADLOCK -

+ DB_LOCK_DEADLOCK +

- When multiple threads of control are modifying the database, there is - normally the potential for deadlock. In Berkeley DB, deadlock is - signified by an error return from the Berkeley DB function of the value - DB_LOCK_DEADLOCK. Whenever a Berkeley DB function returns - DB_LOCK_DEADLOCK, the enclosing transaction should be aborted. -

- Any Berkeley DB function that attempts to acquire locks can potentially - return DB_LOCK_DEADLOCK. Practically speaking, the safest way to deal - with applications that can deadlock is to anticipate a DB_LOCK_DEADLOCK - return from any DB or DBC handle method call, or any DB_ENV - handle method call that references a database, including the database's - backing physical file. -

+ When multiple + threads of control are modifying the database, there is + normally the potential for deadlock. In Berkeley DB, deadlock + is signified by an error return from the Berkeley DB function + of the value DB_LOCK_DEADLOCK. Whenever a Berkeley DB function + returns DB_LOCK_DEADLOCK, the enclosing transaction should be + aborted. +

+ Any Berkeley DB function that attempts to acquire locks can + potentially return DB_LOCK_DEADLOCK. Practically speaking, the + safest way to deal with applications that can deadlock is to + anticipate a DB_LOCK_DEADLOCK return from any DB or DBC + handle method call, or any DB_ENV handle method call that + references a database, including the database's backing + physical file. +

- DB_LOCK_NOTGRANTED -

+ DB_LOCK_NOTGRANTED +

- If a lock is requested from the DB_ENV->lock_get() or DB_ENV->lock_vec() methods with the - DB_LOCK_NOWAIT flag specified, the method will return DB_LOCK_NOTGRANTED if the lock - is not immediately available. -

- If the DB_TIME_NOTGRANTED flag is specified to the DB_ENV->set_flags() method, - database calls timing out based on lock or transaction timeout values - will return DB_LOCK_NOTGRANTED instead of DB_LOCK_DEADLOCK. -

+ If a lock is + requested from the DB_ENV->lock_get() or DB_ENV->lock_vec() methods with the + DB_LOCK_NOWAIT flag specified, the method will return + DB_LOCK_NOTGRANTED if the lock is not immediately available. +

+ If the DB_TIME_NOTGRANTED flag is specified to the + DB_ENV->set_flags() method, database calls timing out based on lock + or transaction timeout values will return DB_LOCK_NOTGRANTED + instead of DB_LOCK_DEADLOCK. +

- DB_RUNRECOVERY -

+ DB_RUNRECOVERY +

- There exists a class of errors that Berkeley DB considers fatal to an - entire Berkeley DB environment. An example of this type of error is a - corrupted database page. The only way to recover from these failures - is to have all threads of control exit the Berkeley DB environment, run - recovery of the environment, and re-enter Berkeley DB. (It is not - strictly necessary that the processes exit, although that is the only - way to recover system resources, such as file descriptors and memory, - allocated by Berkeley DB.) -

- When this type of error is encountered, the error value DB_RUNRECOVERY - is returned. This error can be returned by any Berkeley DB interface. - Once DB_RUNRECOVERY is returned by any interface, it will be returned - from all subsequent Berkeley DB calls made by any threads of control - participating in the environment. -

- Applications can handle such fatal errors in one of two ways: first, by - checking for DB_RUNRECOVERY as part of their normal Berkeley DB error - return checking, similarly to DB_LOCK_DEADLOCK or any other error. - Alternatively, applications can specify a fatal-error callback function - using the DB_ENV->set_event_notify() method. Applications with no cleanup - processing of their own should simply exit from the callback function. -

+ There exists a class + of errors that Berkeley DB considers fatal to an entire + Berkeley DB environment. An example of this type of error is a + corrupted database page. The only way to recover from these + failures is to have all threads of control exit the Berkeley + DB environment, run recovery of the environment, and re-enter + Berkeley DB. (It is not strictly necessary that the processes + exit, although that is the only way to recover system + resources, such as file descriptors and memory, allocated by + Berkeley DB.) +

+ When this type of error is encountered, the error value + DB_RUNRECOVERY is returned. This error can be returned by any + Berkeley DB interface. Once DB_RUNRECOVERY is returned by any + interface, it will be returned from all subsequent Berkeley DB + calls made by any threads of control participating in the + environment. +

+ Applications can handle such fatal errors in one of two + ways: first, by checking for DB_RUNRECOVERY as part of their + normal Berkeley DB error return checking, similarly to + DB_LOCK_DEADLOCK or any other error. Alternatively, + applications can specify a fatal-error callback function using + the DB_ENV->set_event_notify() method. Applications with no cleanup + processing of their own should simply exit from the callback + function. +

- DB_SECONDARY_BAD -

+ DB_SECONDARY_BAD +

- The DB_SECONDARY_BAD error is returned if a secondary index has been - corrupted. This may be the result of an application operating on - related databases without first associating them. -

+ The + DB_SECONDARY_BAD error is returned if a secondary index has + been corrupted. This may be the result of an application + operating on related databases without first associating them. +