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
|
<! "@(#)get.so 10.12 (Sleepycat) 10/3/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB: DB->get</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>
<h1>DB->get</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
#include <db.h>
<p>
int
DB->get(DB *db,
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
</pre>
</h3>
<h1>Description</h1>
<p>
The DB->get function retrieves key/data pairs from the database. The
address
and length of the data associated with the specified <b>key</b> are
returned in the structure referenced by <b>data</b>.
<p>
In the presence of duplicate key values, DB->get will return the
first data item for the designated key. Duplicates are sorted by insert
order except where this order has been overridden by cursor operations.
<b>Retrieval of duplicates requires the use of cursor operations.</b>
See <a href="../../api_c/Dbc/get.html">DBcursor->c_get</a> for details.
<p>
If the file is being accessed under transaction protection,
the <b>txnid</b> parameter is a transaction ID returned from
<a href="../../api_c/DbTxnMgr/begin.html">txn_begin</a>, otherwise, NULL.
<p>
The <b>flags</b> parameter must be set to 0 or one of the following
values:
<dl compact>
<a name="DB_GET_BOTH">
<p><dt>DB_GET_BOTH<dd>Retrieve the key/data pair only if both the key and data match the
arguments.
<a name="DB_SET_RECNO">
<p><dt>DB_SET_RECNO<dd>Retrieve the specified numbered key/data pair from a database.
Upon return, both the <b>key</b> and <b>data</b> items will have been
filled in, not just the data item as is done for all other uses of the
DB->get function.
<p>
The <b>data</b> field of the specified <b>key</b>
must be a pointer to a <a href="../../api_c/Dbt/dbt.html#db_recno_t">logical record number</a> (i.e.,
a <b>db_recno_t</b>).
This record number determines the record to be retrieved.
<p>
For DB_SET_RECNO to be specified, the underlying database must be of type
btree and it must have been created with the DB_RECNUM flag.
</dl>
<p>
In addition, the following value may be set by logically <b>OR</b>'ing it into the
<b>flags</b> parameter:
<dl compact>
<p><dt>DB_RMW<dd>Acquire write locks instead of read locks when doing the retrieval.
Setting this flag may decrease the likelihood of deadlock during a
read-modify-write cycle by immediately acquiring the write lock during
the read part of the cycle so that another thread of control acquiring
a read lock for the same item, in its own read-modify-write cycle, will
not result in deadlock.
</dl>
<p>
If the database is a recno database and the requested key exists, but was
never explicitly created by the application or was later deleted, the
DB->get function returns DB_KEYEMPTY. Otherwise, if the requested key
is not in the database, the DB->get function returns DB_NOTFOUND.
Otherwise, the DB->get
function returns the value of <b>errno</b> on failure, and 0 on success.
<p>
<h1>Errors</h1>
If a fatal error occurs in Berkeley DB, the DB->get function may fail and return
DB_RUNRECOVERY, at which point all subsequent database calls will also
return DB_RUNRECOVERY.
<p>
The DB->get
function may fail and return <b>errno</b>
for any of the errors specified for the following Berkeley DB and C library
functions:
<a href="../../api_c/Db/cursor.html">DB->cursor</a>,
DBcursor->c_close(3),
<a href="../../api_c/Dbc/get.html">DBcursor->c_get</a>,
fflush(3),
fprintf(3),
vfprintf(3),
and
vsnprintf(3).
<p>
In addition, the DB->get
function may fail and return <b>errno</b>
for the following conditions:
<p>
<dl compact>
<p><dt>EAGAIN<dd>A lock was unavailable.
</dl>
<p>
<dl compact>
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
<p>
The DB_THREAD flag was specified to the <a href="../../api_c/Db/open.html">db_open</a> function and neither the
<a href="../../api_c/Dbt/dbt.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a> or <a href="../../api_c/Dbt/dbt.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> flags were set in the
DBT.
<p>
A record number of 0 was specified.
</dl>
<p>
<h1>See Also</h1>
<a href="../../api_c/DbEnv/appexit.html">db_appexit</a>,
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a>,
<a href="../../api_c/DbEnv/version.html">db_version</a>,
<a href="../../api_c/Db/close.html">DB->close</a>,
<a href="../../api_c/Db/cursor.html">DB->cursor</a>,
<a href="../../api_c/Db/del.html">DB->del</a>,
<a href="../../api_c/Db/fd.html">DB->fd</a>,
DB->get,
<a href="../../api_c/Db/join.html">DB->join</a>,
<a href="../../api_c/Db/open.html">db_open</a>,
<a href="../../api_c/Db/put.html">DB->put</a>,
<a href="../../api_c/Db/stat.html">DB->stat</a>,
<a href="../../api_c/Db/sync.html">DB->sync</a>,
<a href="../../api_c/Dbc/close.html">DBcursor->c_close</a>,
<a href="../../api_c/Dbc/del.html">DBcursor->c_del</a>,
<a href="../../api_c/Dbc/get.html">DBcursor->c_get</a>
and
<a href="../../api_c/Dbc/put.html">DBcursor->c_put</a>.
</tt>
</body>
</html>
|
