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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
<! "@(#)get.so 10.18 (Sleepycat) 12/10/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB: DBcursor->c_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>DBcursor->c_get</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
#include <db.h>
<p>
int
DBcursor->c_get(DBC *cursor,
DBT *key, DBT *data, u_int32_t flags);
</pre>
</h3>
<h1>Description</h1>
<p>
The DBcursor->c_get function retrieves key/data pairs from the database. The
address
and length of the key are returned in the object referenced by <b>key</b>
(except for the case of the DB_SET flag where the <b>key</b> object is
unchanged), and the
address
and length of the data are returned in the object referenced by <b>data</b>.
<p>
Modifications to the database during a sequential scan will be reflected
in the scan, i.e. records inserted behind a cursor will not be returned
while records inserted in front of a cursor will be returned.
<p>
In Recno databases, missing entries (i.e., entries that were never explicitly
created or that were created and then deleted), will be skipped during a
sequential scan.
<p>
If multiple threads or processes insert items into the same database file
without using locking, the results are undefined.
For more detail,
see <a href="../../ref/txn/stability.html">cursor stability</a>.
<p>
The <b>flags</b> parameter must be set to one of the following values:
<dl compact>
<a name="DB_FIRST">
<p><dt>DB_FIRST<dd>The cursor is set to reference the first key/data pair of the database,
and that pair is returned.
In the presence of duplicate key values,
the first data item in the set of duplicates is returned.
<p>
If the database is a Recno database, DBcursor->c_get using the
DB_FIRST flag will skip any keys that exist but were never
explicitly created by the application or were created and later deleted.
<p>
If the database is empty, DBcursor->c_get will return DB_NOTFOUND.
<a name="DB_LAST">
<p><dt>DB_LAST<dd>The cursor is set to reference the last key/data pair of the database,
and that pair is returned.
In the presence of duplicate key values,
the last data item in the set of duplicates is returned.
<p>
If the database is a Recno database, DBcursor->c_get using the
DB_LAST flag will skip any keys that exist but were never
explicitly created by the application or were created and later deleted.
<p>
If the database is empty, DBcursor->c_get will return DB_NOTFOUND.
<a name="DB_NEXT">
<p><dt>DB_NEXT<dd>If the cursor is not yet initialized, DB_NEXT is identical to DB_FIRST.
<p>
Otherwise, move the cursor to the next key/data pair of the database,
and that pair is returned.
In the presence of duplicate key values, the value of the key may not change.
<p>
If the database is a Recno database, DBcursor->c_get using the
DB_NEXT flag will skip any keys that exist but were never
explicitly created by the application or were created and later deleted.
<p>
If the cursor is already on the last record in the database, DBcursor->c_get
will return DB_NOTFOUND.
<a name="DB_NEXT_DUP">
<p><dt>DB_NEXT_DUP<dd>If the next key/data pair of the database is a duplicate record for the
current key/data pair, move the cursor to the next key/data pair of the
database, and that pair is returned.
Otherwise, DBcursor->c_get will return DB_NOTFOUND.
<p>
If the cursor is not yet initialized, the DBcursor->c_get
function will return EINVAL.
<a name="DB_PREV">
<p><dt>DB_PREV<dd>If the cursor is not yet initialized, DB_PREV is identical to DB_LAST.
<p>
Otherwise, move the cursor to the previous key/data pair of the database,
and that pair is returned.
In the presence of duplicate key values, the value of the key may not change.
<p>
If the database is a Recno database, DBcursor->c_get using the
DB_PREV flag will skip any keys that exist but were never
explicitly created by the application or were created and later deleted.
<p>
If the cursor is already on the first record in the database, DBcursor->c_get
will return DB_NOTFOUND.
<a name="DB_CURRENT">
<p><dt>DB_CURRENT<dd>Return the key/data pair currently referenced by the cursor.
<p>
If the cursor key/data pair was deleted, DBcursor->c_get will return
DB_KEYEMPTY.
<p>
If the cursor is not yet initialized, the DBcursor->c_get
function will return EINVAL.
<a name="DB_SET">
<p><dt>DB_SET<dd>Move the cursor to the specified key/data pair of the database,
and return the datum associated with the given key.
<p>
In the presence of duplicate key values, DBcursor->c_get will return the
first data item for the given key.
<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,
DBcursor->c_get will return DB_KEYEMPTY.
<p>
If no matching keys are found, DBcursor->c_get will return DB_NOTFOUND.
<a name="DB_SET_RANGE">
<p><dt>DB_SET_RANGE<dd>The DB_SET_RANGE flag is identical to the DB_SET flag, except that the
key is returned as well as the data item, and, in the case of the btree
access method, the returned key/data pair is the smallest key greater than
or equal to the specified key (as determined by the comparison
function), permitting partial key matches and range searches.
<a name="DB_GET_BOTH">
<p><dt>DB_GET_BOTH<dd>The DB_GET_BOTH flag is identical to the DB_SET flag, except that both the
key and the data arguments must be matched by the key and data item in the
database.
<a name="DB_SET_RECNO">
<p><dt>DB_SET_RECNO<dd>Move the cursor to the specific numbered record of the database,
and return the associated key/data pair.
The <b>data</b> field of the specified <b>key</b>
must be a pointer to a memory location from which a <a href="../../api_c/Dbt/dbt.html#db_recno_t">db_recno_t</a>
may be read, as described in DBT.
This memory location will be read to determine 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 <a href="../../api_c/DbInfo/info.html#DB_RECNUM">DB_RECNUM</a> flag.
<a name="DB_GET_RECNO">
<p><dt>DB_GET_RECNO<dd>Return the record number associated with the cursor.
The record number will be returned in <b>data</b> as described in
DBT.
The <b>key</b> parameter is ignored.
<p>
For DB_GET_RECNO to be specified, the underlying database must be of
type btree and it must have been created with the <a href="../../api_c/DbInfo/info.html#DB_RECNUM">DB_RECNUM</a> 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>
Otherwise, the DBcursor->c_get
function returns the value of <b>errno</b> on failure, and 0 on success.
<p>
If DBcursor->c_get fails for any reason, the state of the cursor will be
unchanged.
<p>
<h1>Errors</h1>
If a fatal error occurs in Berkeley DB, the DBcursor->c_get function may fail and return
DB_RUNRECOVERY, at which point all subsequent database calls will also
return DB_RUNRECOVERY.
<p>
The DBcursor->c_get
function may fail and return <b>errno</b>
for any of the errors specified for the following Berkeley DB and C library
functions:
__account_page(3),
abort(3),
dbenv->db_paniccall(3),
dbp->dup_compare(3),
fflush(3),
fprintf(3),
free(3),
func(3),
hcp->dbc->dbp->h_hash(3),
<a href="../../api_c/DbLockTab/get.html">lock_get</a>,
<a href="../../api_c/DbLock/put.html">lock_put</a>,
<a href="../../api_c/DbLockTab/vec.html">lock_vec</a>,
<a href="../../api_c/DbLog/put.html">log_put</a>,
malloc(3),
memcmp(3),
memcpy(3),
memmove(3),
<a href="../../api_c/DbMpoolFile/get.html">memp_fget</a>,
<a href="../../api_c/DbMpoolFile/put.html">memp_fput</a>,
<a href="../../api_c/DbMpoolFile/set.html">memp_fset</a>,
memset(3),
realloc(3),
strerror(3),
vfprintf(3),
and
vsnprintf(3).
<p>
In addition, the DBcursor->c_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 specified cursor was not currently initialized.
<p>
The <a href="../../api_c/DbEnv/appinit.html#DB_THREAD">DB_THREAD</a> flag was specified to <a href="../../api_c/Db/open.html">db_open</a> 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.
</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>,
<a href="../../api_c/Db/get.html">DB->get</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>,
DBcursor->c_get
and
<a href="../../api_c/Dbc/put.html">DBcursor->c_put</a>.
</tt>
</body>
</html>
|
