mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
239 lines
12 KiB
HTML
239 lines
12 KiB
HTML
<?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>
|