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
|
<! "@(#)errorret.so 10.13 (Sleepycat) 11/9/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB Reference Guide: Programmer Notes</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btr
ee,hash,hashing,transaction,transactions,locking,logging,access method,access me
thods,java,C,C++">
</head>
<h3>Berkeley DB Reference Guide: Programmer Notes</h3>
<p>
<h1 align=center>Error returns to applications</h1>
<p>
Except for the historic <a href="../../api_c/historic/dbm.html">dbm</a>, <a href="../../api_c/historic/dbm.html">ndbm</a> and <a href="../../api_c/historic/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 can be grouped into three
categories:
<dl compact>
<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,
e.g., 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 such special values returned by Berkeley DB functions are less than 0 in
order to avoid conflict with possible values of
<b>errno</b>.
</dl>
<p>
While possible error returns are specified by each individual function's
manual page, there are a few error returns that deserve special mention:
<h1>EAGAIN</h1>
When multiple processes or 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 <b>errno</b>
value EAGAIN. Whenever a Berkeley DB function returns EAGAIN, the enclosing
transaction should be aborted.
<p>
Any Berkeley DB function that attempts to acquire locks can potentially return
EAGAIN. Practically speaking, the safest way to deal with applications
that can deadlock is to handle a potential EAGAIN return from any Berkeley DB
Access Method call.
<h1>DB_NOTFOUND and DB_KEYEMPTY</h1>
<p>
There are two special return values that are somewhat similar in meaning,
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- or end-of-file has been reached.
<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 access method 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 is currently in a deleted
state.
<h1>DB_RUNRECOVERY</h1>
<p>
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 log write
failure due to the disk being out of free space. The only way to recover
from these failures is for the application to exit, run recovery of the
Berkeley DB environment, and re-enter Berkeley DB. (It is not strictly necessary that
the application exit, although that is the only way to recover system
resources, e.g., file descriptors and memory, currently allocated by
Berkeley DB.)
<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. If a fatal error occurs, DB_RUNRECOVERY will be
returned from all subsequent Berkeley DB calls made by any threads or processes
participating in the environment.
<p>
Optionally, applications may also specify a fatal-error callback function
by setting the db_paniccall field of the DB_ENV structure before
initializing the environment with <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>. This callback
function will be called with two arguments: a reference to the DB_ENV
structure associated with the environment, and the <b>errno</b> value
associated with the underlying error that caused the problem.
<p>
Applications can handle such fatal errors in one of two ways: by checking
for DB_RUNRECOVERY as part of their normal Berkeley DB error return
checking, similarly to EAGAIN or any other error, or, in applications that
have no cleanup processing of their own, by simply exiting the application
when the callback function is called.
<p>
<a href="../../ref/program/appsignals.html"><img src="../../images/prev.gif"></a>
<a href="../../ref/toc.html"><img src="../../images/toc.gif"></a>
<a href="../../ref/program/thread.html"><img src="../../images/next.gif"></a>
</tt>
</body>
</html>
|
