1<!--$Id: errorret.so,v 10.50 2007/09/26 15:11:31 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Error returns to applications</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></b></td> 14<td align=right><a href="../program/appsignals.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/environ.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Error returns to applications</b></p> 17<p>Except for the historic <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a>, and <a href="../../api_c/hsearch.html">hsearch</a> 18interfaces, Berkeley DB does not use the global variable <b>errno</b> to 19return error values. The return values for all Berkeley DB functions are 20grouped into the following three categories:</p> 21<br> 22<b>0</b><ul compact><li>A return value of 0 indicates that the operation was successful.</ul> 23<b>> 0</b><ul compact><li>A return value that is greater than 0 indicates that there was a system 24error. The <b>errno</b> value returned by the system is returned by 25the function; for example, when a Berkeley DB function is unable to allocate 26memory, the return value from the function will be ENOMEM.</ul> 27<b>< 0</b><ul compact><li>A return value that is less than 0 indicates a condition that was not 28a system failure, but was not an unqualified success, either. For 29example, a routine to retrieve a key/data pair from the database may 30return DB_NOTFOUND when the key/data pair does not appear in 31the database; as opposed to the value of 0, which would be returned if 32the key/data pair were found in the database. 33<p><a name="3"><!--meow--></a> 34All values returned by Berkeley DB functions are less than 0 in order to avoid 35conflict with possible values of <b>errno</b>. Specifically, Berkeley DB 36reserves all values from -30,800 to -30,999 to itself as possible error 37values. There are a few Berkeley DB interfaces where it is possible for an 38application function to be called by a Berkeley DB function and subsequently 39fail with an application-specific return. Such failure returns will be 40passed back to the function that originally called a Berkeley DB interface. 41To avoid ambiguity about the cause of the error, error values separate 42from the Berkeley DB error name space should be used.</p></ul> 43<br> 44<p>Although possible error returns are specified by each individual function's 45manual page, there are a few error returns that deserve general mention:</p> 46<b><a name="DB_NOTFOUND">DB_NOTFOUND</a> and <a name="DB_KEYEMPTY">DB_KEYEMPTY</a></b> 47<p>There are two special return values that are similar in meaning and that 48are returned in similar situations, and therefore might be confused: 49DB_NOTFOUND and DB_KEYEMPTY.</p> 50<p>The DB_NOTFOUND error return indicates that the requested key/data 51pair did not exist in the database or that start-of- or end-of-file has 52been reached by a cursor.</p> 53<p>The DB_KEYEMPTY error return indicates that the requested 54key/data pair logically exists but was never explicitly created by the 55application (the Recno and Queue access methods will automatically 56create key/data pairs under some circumstances; see <a href="../../api_c/db_open.html">DB->open</a> 57for more information), or that the requested key/data pair was deleted 58and never re-created. In addition, the Queue access method will return 59DB_KEYEMPTY for records that were created as part of a 60transaction that was later aborted and never re-created.</p> 61<b><a name="DB_KEYEXIST">DB_KEYEXIST</a></b> 62<p>The DB_KEYEXIST error return indicates the <a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a> 63option was specified when inserting a key/data pair into the database and 64the key already exists in the database, or the <a href="../../api_c/db_put.html#DB_NODUPDATA">DB_NODUPDATA</a> 65option was specified and the key/data pair already exists in the data.</p> 66<a name="4"><!--meow--></a> 67<b><a name="DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a></b> 68<p>When multiple threads of control are modifying the database, there is 69normally the potential for deadlock. In Berkeley DB, deadlock is signified by 70an error return from the Berkeley DB function of the value 71DB_LOCK_DEADLOCK. Whenever a Berkeley DB function returns 72DB_LOCK_DEADLOCK, the enclosing transaction should be aborted.</p> 73<p>Any Berkeley DB function that attempts to acquire locks can potentially return 74DB_LOCK_DEADLOCK. Practically speaking, the safest way to deal 75with applications that can deadlock is to anticipate a 76DB_LOCK_DEADLOCK return from any <a href="../../api_c/db_class.html">DB</a> or <a href="../../api_c/dbc_class.html">DBC</a> 77handle method call, or any <a href="../../api_c/env_class.html">DB_ENV</a> handle method call that 78references a database, including the database's backing physical file.</p> 79<b><a name="DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a></b> 80<p>If a lock is requested from the <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> or <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> methods 81with the <a href="../../api_c/lock_vec.html#DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a> flag specified, the method will return 82DB_LOCK_NOTGRANTED if the lock is not immediately available.</p> 83<p>If the <a href="../../api_c/env_set_flags.html#DB_TIME_NOTGRANTED">DB_TIME_NOTGRANTED</a> flag is specified to the 84<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> method, database calls timing out based on lock or 85transaction timeout values will return DB_LOCK_NOTGRANTED 86instead of DB_LOCK_DEADLOCK.</p> 87<b><a name="DB_RUNRECOVERY">DB_RUNRECOVERY</a></b> 88<p>There exists a class of errors that Berkeley DB considers fatal to an entire 89Berkeley DB environment. An example of this type of error is a corrupted 90database page. The only way to recover from these failures is to have 91all threads of control exit the Berkeley DB environment, run recovery of the 92environment, and re-enter Berkeley DB. (It is not strictly necessary that the 93processes exit, although that is the only way to recover system 94resources, such as file descriptors and memory, allocated by Berkeley DB.)</p> 95<p>When this type of error is encountered, the error value 96DB_RUNRECOVERY is returned. This error can be returned by any 97Berkeley DB interface. Once DB_RUNRECOVERY is returned by any 98interface, it will be returned from all subsequent Berkeley DB calls made by 99any threads of control participating in the environment.</p> 100<p>Applications can handle such fatal errors in one of two ways: first, by 101checking for DB_RUNRECOVERY as part of their normal Berkeley DB error 102return checking, similarly to DB_LOCK_DEADLOCK or any other 103error. Alternatively, applications can specify a fatal-error callback 104function using the <a href="../../api_c/env_event_notify.html">DB_ENV->set_event_notify</a> method. Applications with 105no cleanup processing of their own should simply exit from the callback 106function.</p> 107<b><a name="DB_SECONDARY_BAD">DB_SECONDARY_BAD</a></b> 108<p>A secondary index has been corrupted. This is likely the result of an 109application operating on related databases without first associating 110them.</p> 111<table width="100%"><tr><td><br></td><td align=right><a href="../program/appsignals.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/environ.html"><img src="../../images/next.gif" alt="Next"></a> 112</td></tr></table> 113<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 114</body> 115</html> 116