Sindbad~EG File Manager
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Error returns to applications</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="up" href="program.html" title="Chapter 16. Programmer Notes" />
<link rel="prev" href="program.html" title="Chapter 16. Programmer Notes" />
<link rel="next" href="program_i18n.html" title="Globalization Support" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 18.1.40</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Error returns to
applications</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="program.html">Prev</a> </td>
<th width="60%" align="center">Chapter 16. Programmer Notes </th>
<td width="20%" align="right"> <a accesskey="n" href="program_i18n.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="program_errorret"></a>Error returns to
applications</h2>
</div>
</div>
</div>
<p>
Except for the historic <a href="../api_reference/C/dbm.html" class="olink">dbm</a>, <a href="../api_reference/C/dbm.html" class="olink">ndbm</a> and <a href="../api_reference/C/hsearch.html" class="olink">hsearch</a>
interfaces, Berkeley DB does not use the global variable
<code class="literal">errno</code> to return error values. The
return values for all Berkeley DB functions are grouped into
the following three categories:
</p>
<div class="variablelist">
<dl>
<dt>
<span class="term">0</span>
</dt>
<dd>A return value of 0 indicates that the operation
was successful.</dd>
<dt>
<span class="term">> 0</span>
</dt>
<dd>
A return value that is greater than 0 indicates
that there was a system error. The <span class="bold"><strong>errno</strong></span> 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.
</dd>
<dt>
<span class="term">< 0</span>
</dt>
<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.
<p>
All values returned by
Berkeley DB functions are less than 0 in order to
avoid conflict with possible values of <span class="bold"><strong>errno</strong></span>. 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.
</p></dd>
</dl>
</div>
<p>
Although possible error returns are specified by each
individual function's manual page, there are a few error
returns that deserve general mention:
</p>
<p>
<span class="bold"><strong>DB_NOTFOUND and DB_KEYEMPTY</strong></span>
</p>
<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>
<p><a id="program_errorret.DB_NOTFOUND"></a>
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>
<p><a id="program_errorret.DB_KEYEMPTY"></a>
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_reference/C/dbopen.html" class="olink">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.
</p>
<p>
<span class="bold"><strong>DB_KEYEXIST</strong></span>
</p>
<p><a id="program_errorret.DB_KEYEXIST"></a>
The DB_KEYEXIST error
return indicates the <a href="../api_reference/C/dbput.html#put_DB_NOOVERWRITE" class="olink">DB_NOOVERWRITE</a> option was specified
when inserting a key/data pair into the database and the key
already exists in the database, or the <a href="../api_reference/C/dbput.html#put_DB_NODUPDATA" class="olink">DB_NODUPDATA</a> option
was specified and the key/data pair already exists in the
data.
</p>
<p>
<span class="bold"><strong>DB_LOCK_DEADLOCK</strong></span>
</p>
<p><a id="program_errorret.DB_LOCK_DEADLOCK"></a>
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>
<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
anticipate a DB_LOCK_DEADLOCK return from any <a href="../api_reference/C/db.html" class="olink">DB</a> or <a href="../api_reference/C/dbc.html" class="olink">DBC</a>
handle method call, or any <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle method call that
references a database, including the database's backing
physical file.
</p>
<p>
<span class="bold"><strong>DB_LOCK_NOTGRANTED</strong></span>
</p>
<p><a id="program_errorret.DB_LOCK_NOTGRANTED"></a>
If a lock is
requested from the <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> or <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> methods with the
<a href="../api_reference/C/lockvec.html#vec_DB_LOCK_NOWAIT" class="olink">DB_LOCK_NOWAIT</a> flag specified, the method will return
DB_LOCK_NOTGRANTED if the lock is not immediately available.
</p>
<p>
If the <a href="../api_reference/C/envset_flags.html#envset_flags_DB_TIME_NOTGRANTED" class="olink">DB_TIME_NOTGRANTED</a> flag is specified to the
<a href="../api_reference/C/envset_flags.html" class="olink">DB_ENV->set_flags()</a> method, database calls timing out based on lock
or transaction timeout values will return DB_LOCK_NOTGRANTED
instead of DB_LOCK_DEADLOCK.
</p>
<p>
<span class="bold"><strong>DB_RUNRECOVERY</strong></span>
</p>
<p><a id="program_errorret.DB_RUNRECOVERY"></a>
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.)
</p>
<p>
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.
</p>
<p>
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 <a href="../api_reference/C/envevent_notify.html" class="olink">DB_ENV->set_event_notify()</a> method. Applications with no cleanup
processing of their own should simply exit from the callback
function.
</p>
<p>
<span class="bold"><strong>DB_SECONDARY_BAD</strong></span>
</p>
<p><a id="program_error_ret.DB_SECONDARY_BAD"></a>
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.
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="program.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="program.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="program_i18n.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 16. Programmer Notes </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Globalization Support</td>
</tr>
</table>
</div>
</body>
</html>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists