~ubuntu-branches/ubuntu/edgy/rpm/edgy

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

interfaces, Berkeley DB does not use the global variable <b>errno</b> to

return error values. The return values for all Berkeley DB functions are

grouped into the following three categories:

<p><dt>0<dd>A return value of 0 indicates that the operation was successful.

<p><dt>> 0<dd>A return value that is greater than 0 indicates that there was a system

error. The <b>errno</b> 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.

<p><dt>< 0<dd>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 <b>errno</b>. 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.

</dl>

<p>Although possible error returns are specified by each individual function's

manual page, there are a few error returns that deserve general mention:

<h3><a name="DB_NOTFOUND">DB_NOTFOUND</a> and <a name="DB_KEYEMPTY">DB_KEYEMPTY</a></h3>

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

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

<p>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 <a href="../../api_c/db_open.html">DB->open</a>

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.

<h3><a name="DB_KEYEXIST">DB_KEYEXIST</a></h3>

<p>The DB_KEYEXIST error return indicates the <a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a>

option was specified to the <a href="../../api_c/db_put.html">DB->put</a> function and the key already exists

in the database.

<h3><a name="DB_INCOMPLETE">DB_INCOMPLETE</a></h3>

<p>When a database cannot be flushed to disk by <a href="../../api_c/db_close.html">DB->close</a> or

<a href="../../api_c/db_sync.html">DB->sync</a>, or by the underlying Memory Pool subsystem methods,

<a href="../../api_c/memp_fsync.html">memp_fsync</a> and <a href="../../api_c/memp_sync.html">memp_sync</a>, DB_INCOMPLETE may be

returned to the application.

<p>In the case of <a href="../../api_c/db_close.html">DB->close</a> and <a href="../../api_c/db_sync.html">DB->sync</a>, the only reason

for a return of DB_INCOMPLETE is if another thread of control

was writing pages in the underlying database file at the same time as

the <a href="../../api_c/db_close.html">DB->close</a> or <a href="../../api_c/db_sync.html">DB->sync</a> call was made. For this

reason, a return of DB_INCOMPLETE can normally be ignored; or,

in cases where it is a possible return value, <a href="../../api_c/db_sync.html">DB->sync</a> should

probably never have been called, or the <a href="../../api_c/db_close.html#DB_NOSYNC">DB_NOSYNC</a> option should

have been specified to <a href="../../api_c/db_close.html">DB->close</a>.

<p>In the case of <a href="../../api_c/memp_fsync.html">memp_fsync</a> or <a href="../../api_c/memp_sync.html">memp_sync</a> (or other Berkeley DB

interfaces that call those functions, <a href="../../api_c/txn_checkpoint.html">txn_checkpoint</a> for

example), a return of DB_INCOMPLETE indicates that the database

environment is under heavy load and the checkpoint was unable to

complete because there were pages that could not be written at this

time. This is not a fatal error, and the call should be retried.

<h3><a name="DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a></h3>

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

<p>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 handle a

DB_LOCK_DEADLOCK return from any Berkeley DB access method call.

<h3><a name="DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a></h3>

<p>When multiple threads of control are modifying the database, there is

normally the potential for deadlock. In order to avoid deadlock,

applications may specify -- on a per-transaction basis -- that if a lock

100

is unavailable, the Berkeley DB operation should return immediately instead

101

of waiting on the lock. The error return in this case will be

102

DB_LOCK_NOTGRANTED. Whenever a Berkeley DB function returns

103

DB_LOCK_NOTGRANTED, the enclosing transaction should be

104

aborted.

105

<h3><a name="DB_RUNRECOVERY">DB_RUNRECOVERY</a></h3>

106

<p>There exists a class of errors that Berkeley DB considers fatal to an entire

107

Berkeley DB environment. An example of this type of error is a corrupted

108

database or a log write failure because the disk is out of free space.

109

The only way to recover from these failures is to have all threads of

110

control exit the Berkeley DB environment, run recovery of the environment, and

111

re-enter Berkeley DB. (It is not strictly necessary that the processes exit,

112

although that is the only way to recover system resources, such as file

113

descriptors and memory, allocated by Berkeley DB.)

114

<p>When this type of error is encountered, the error value

115

DB_RUNRECOVERY is returned. This error can be returned by any

116

Berkeley DB interface. Once DB_RUNRECOVERY is returned by any

117

interface, it will be returned from all subsequent Berkeley DB calls made by

118

any threads of control participating in the environment.

119

<p>Optionally, applications may also specify a fatal-error callback function

120

using the <a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a> function. This callback function will be

121

called with two arguments: a reference to the DB_ENV structure

122

associated with the environment and the <b>errno</b> value

123

associated with the underlying error that caused the problem.

124

<p>Applications can handle such fatal errors in one of two ways: by checking

125

for DB_RUNRECOVERY as part of their normal Berkeley DB error return

126

checking, similarly to DB_LOCK_DEADLOCK or any other error, or

127

by simply exiting the application when the callback function is called

128

in applications that have no cleanup processing of their own.

129

130

</td></tr></table>

131

<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>

132

</body>

133

</html>

Older »