1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<?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 15. Programmer Notes" />
<link rel="prev" href="program.html" title="Chapter 15. Programmer Notes" />
<link rel="next" href="program_environ.html" title="Environment variables" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 11.2.5.3</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 15.
Programmer Notes
</th>
<td width="20%" align="right"> <a accesskey="n" href="program_environ.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_environ.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 15.
Programmer Notes
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Environment variables</td>
</tr>
</table>
</div>
</body>
</html>
|
