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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
|
<?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>Chapter 4. The DBT Handle</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C API Reference" />
<link rel="up" href="index.html" title="Berkeley DB C API Reference" />
<link rel="prev" href="dbcset_priority.html" title="DBcursor->set_priority()" />
<link rel="next" href="DB_MULTIPLE_INIT.html" title="DB_MULTIPLE_INIT" />
</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">Chapter 4.
The DBT Handle
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="DB_MULTIPLE_INIT.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="dbt"></a>Chapter 4.
The DBT Handle
</h2>
</div>
</div>
</div>
<pre class="programlisting">#include <db.h>
typedef struct {
void *data;
u_int32_t size;
u_int32_t ulen;
u_int32_t dlen;
u_int32_t doff;
u_int32_t flags;
} DBT;
</pre>
<p>
Storage and retrieval for the <a class="link" href="db.html" title="Chapter 2. The DB Handle">DB</a> access methods are
based on key/data pairs. Both key and data items are represented by
<span>
the DBT data structure. (The name DBT is a mnemonic for data base thang, and was used
because no one could think of a reasonable name that wasn't already in use somewhere
else.)
</span>
Key and data byte strings may refer to strings of zero length up to strings of essentially
unlimited length. See <a href="../../programmer_reference/am_misc_dbsizes.html" class="olink">Database limits</a> for
more information.
</p>
<p>
All fields of the DBT structure that are not explicitly set should
be initialized to nul bytes before the first time the structure is
used. Do this by declaring the structure external or static, or by
calling the C library routine
<span class="bold"><strong>memset</strong></span>(3).
</p>
<p>
<span>
By default, the <span class="bold"><strong>flags</strong></span> structure element is expected to
be set to 0. In this default case,
</span>
when the application is providing Berkeley DB a key or data item to store into the database,
Berkeley DB expects the <span class="bold"><strong>data</strong></span>
<span>
structure element
</span>
to point to a byte string of <span class="bold"><strong>size</strong></span> bytes. When returning a
key/data item to the application, Berkeley DB will store into the <span class="bold"><strong>data</strong></span>
<span>
structure element
</span>
a pointer to a byte string of <span class="bold"><strong>size</strong></span> bytes,
and the memory to which the pointer refers will be
allocated and managed by Berkeley DB. Note that using the default flags
for returned <code class="classname">DBT</code>s is only compatible with
single threaded usage of Berkeley DB.
</p>
<p>
The elements of the DBT structure are defined as follows:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<span class="bold"><strong>void *data;</strong></span>
</p>
<p>
A pointer to a byte string.
</p>
</li>
<li>
<p>
<span class="bold"><strong>u_int32_t size;</strong></span>
</p>
<p>
The length of <span class="bold"><strong>data</strong></span>, in bytes.
</p>
</li>
<li>
<p>
<span class="bold"><strong>u_int32_t ulen;</strong></span>
</p>
<p>
The size of the user's buffer (to which <span class="bold"><strong>data</strong></span> refers), in bytes. This
location is not written by the Berkeley DB functions.
</p>
<p>
Set the byte size of the user-specified buffer.
</p>
<p>
Note that applications can determine the length of a record by setting
the <code class="literal">ulen</code> field to 0 and checking the return value in the
<span class="bold"><strong>size</strong></span> field. See
the <code class="literal">DB_DBT_USERMEM</code> flag for more information.
</p>
</li>
<li>
<p>
<span class="bold"><strong>u_int32_t dlen;</strong></span>
</p>
<p>
<span>
The
</span>
length of the partial record being read or written by the
application, in bytes. See the <code class="literal">DB_DBT_PARTIAL</code>
flag for more information.
</p>
</li>
<li>
<p>
<span class="bold"><strong>u_int32_t doff;</strong></span>
</p>
<p>
<span>
The
</span>
offset of the partial record being read or written by the application,
in bytes. See the <code class="literal">DB_DBT_PARTIAL</code> flag for more information.
</p>
</li>
<li>
<p>
<span class="bold"><strong>u_int32_t flags;</strong></span>
</p>
<p>
The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 or
by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together
one or more of the following values:
</p>
<span>
<div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_MALLOC"></a>
<code class="literal">DB_DBT_MALLOC</code>
</p><p>
When this flag is set, Berkeley DB will allocate memory
for the returned key or data item (using
<span class="bold"><strong>malloc</strong></span>(3), or
the user-specified malloc function), and return a
pointer to it in the
<span class="bold"><strong>data</strong></span> field of the key or data
<code class="literal">DBT</code>
structure. Because any allocated memory becomes the
responsibility of the calling application, the caller
must determine whether memory was allocated using the
returned value of the
<span class="bold"><strong>data</strong></span> field.
</p><p>
It is an error to specify more than one of
<code class="literal">DB_DBT_MALLOC</code>,
<code class="literal">DB_DBT_REALLOC</code>, and
<code class="literal">DB_DBT_USERMEM</code>.
</p></li><li><p><a id="dbt_DB_DBT_REALLOC"></a>
<code class="literal">DB_DBT_REALLOC</code>
</p><p>
When this flag is set Berkeley DB will allocate memory
for the returned key or data item (using
<span class="bold"><strong>realloc</strong></span>(3), or
the user-specified realloc function), and return a
pointer to it in the
<span class="bold"><strong>data</strong></span> field of the key or data DBT
structure. Because any allocated memory becomes the
responsibility of the calling application, the caller
must determine whether memory was allocated using the
returned value of the
<span class="bold"><strong>data</strong></span> field.
</p><p>
The difference between
<code class="literal">DB_DBT_MALLOC</code> and
<code class="literal">DB_DBT_REALLOC</code>
is that the latter will call
<span class="bold"><strong>realloc</strong></span>(3) instead of
<span class="bold"><strong>malloc</strong></span>(3),
so the allocated memory will be grown as
necessary instead of the application doing repeated
free/malloc calls.
</p><p>
It is an error to specify more than one of
<code class="literal">DB_DBT_MALLOC</code>,
<code class="literal">DB_DBT_REALLOC</code>, and
<code class="literal">DB_DBT_USERMEM</code>.
</p></li><li><p><a id="dbt_DB_DBT_USERMEM"></a>
<code class="literal">DB_DBT_USERMEM</code>
</p><p>
The <span class="emphasis"><em>data</em></span>
field of the key or data structure must refer
to memory that is at least
<span class="emphasis"><em>ulen</em></span>
bytes in length. If the
length of the requested item is less than or equal to
that number of bytes, the item is copied into the memory
to which the
<span class="emphasis"><em>data</em></span>
field refers. Otherwise, the
<span class="emphasis"><em>size</em></span>
field is set to the length needed for the requested
item, and the error
<code class="literal">DB_BUFFER_SMALL</code> is returned.
</p><p>
It is an error to specify more than one of
<code class="literal">DB_DBT_MALLOC</code>,
<code class="literal">DB_DBT_REALLOC</code>, and
<code class="literal">DB_DBT_USERMEM</code>.
</p></li></ul></div>
<div class="itemizedlist"><ul type="circle"><li><p><a id="dbt_DB_DBT_PARTIAL"></a>
<code class="literal">DB_DBT_PARTIAL</code>
</p><p>
Do partial retrieval or storage of an item. If the
calling application is doing a get, the
<span class="bold"><strong>dlen</strong></span> bytes
starting
<span class="bold"><strong>doff</strong></span>
bytes from the beginning of the retrieved
data record are returned as if they comprised the entire
record. If any or all of the specified bytes do not
exist in the record, the get is successful, and any
existing bytes are returned.
</p><p>
For example, if the data portion of a retrieved record
was 100 bytes, and a partial retrieval was done using a
DBT having a
<span class="bold"><strong>dlen</strong></span>
field of 20 and a
<span class="bold"><strong>doff</strong></span>
field of 85,
the get call would succeed, the
<span class="bold"><strong>data</strong></span>
field would refer
to the last 15 bytes of the record, and the
<span class="bold"><strong>size</strong></span>
field would be set to 15.
</p><p>
If the calling application is doing a put, the
<span class="bold"><strong>dlen</strong></span>
bytes starting
<span class="bold"><strong>doff</strong></span>
bytes from the beginning of the
specified key's data record are replaced by the data
specified by the
<span class="bold"><strong>data</strong></span>
and
<span class="bold"><strong>size</strong></span>
structure elements. If
<span class="bold"><strong>dlen</strong></span>
is smaller than
<span class="bold"><strong>size</strong></span>
the record will grow; if
<span class="bold"><strong>dlen</strong></span>
is larger than
<span class="bold"><strong>size</strong></span>
the record will shrink. If the
specified bytes do not exist, the record will be
extended using nul bytes as necessary, and the put call
will succeed.
</p><p>
It is an error to attempt a partial put using the
<a class="xref" href="dbput.html" title="DB->put()">DB->put()</a>
method in a database that supports duplicate
records. Partial puts in databases supporting duplicate
records must be done using a
<a class="xref" href="dbcput.html" title="DBcursor->put()">DBcursor->put()</a>
method.
</p><p>
It is an error to attempt a partial put with differing
<span class="bold"><strong>dlen</strong></span>
and
<span class="bold"><strong>size</strong></span>
values in Queue or Recno databases with
fixed-length records.
</p><p>
For example, if the data portion of a retrieved record
was 100 bytes, and a partial put was done using a DBT
having a
<span class="bold"><strong>dlen</strong></span>
field of 20, a
<span class="bold"><strong>doff</strong></span>
field of 85, and a
<span class="bold"><strong>size</strong></span>
field of 30, the resulting record would be 115
bytes in length, where the last 30 bytes would be those
specified by the put call.
</p><p>
This flag is ignored when used with the
<code class="literal">pkey</code> parameter on
<a class="link" href="dbget.html" title="DB->get()">DB->pget()</a> or
<a class="link" href="dbcget.html" title="DBcursor->get()">DBcursor->pget()</a>.
</p></li><li><p><a id="dbt_DB_DBT_APPMALLOC"></a>
<code class="literal">DB_DBT_APPMALLOC</code>
</p><p>
After an application-supplied callback routine passed to
either
<a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a>
or
<a class="xref" href="dbset_append_recno.html" title="DB->set_append_recno()">DB->set_append_recno()</a>
is executed, the
<span class="bold"><strong>data</strong></span>
field of a DBT may refer to memory allocated with
<span class="bold"><strong>malloc</strong></span>(3)
or
<span class="bold"><strong>realloc</strong></span>(3).
In that case,
the callback sets the
<code class="literal">DB_DBT_APPMALLOC</code>
flag in the DBT
so that Berkeley DB will call
<span class="bold"><strong>free</strong></span>(3)
to deallocate the
memory when it is no longer required.
</p></li><li><p><a id="dbt_DB_DBT_MULTIPLE"></a>
<code class="literal">DB_DBT_MULTIPLE</code>
</p><p>
Set in a secondary key creation callback routine passed
to
<a class="xref" href="dbassociate.html" title="DB->associate()">DB->associate()</a>
to indicate that multiple secondary
keys should be associated with the given primary
key/data pair. If set, the
<span class="bold"><strong>size</strong></span>
field indicates the
number of secondary keys and the
<span class="bold"><strong>data</strong></span>
field refers to an
array of that number of DBT structures.
</p><p>
The <code class="literal">DB_DBT_APPMALLOC</code> flag may be set on any of the DBT
structures to indicate that their
<span class="bold"><strong>data</strong></span>
field needs to be
freed.
</p></li><li><p><a id="dbt_DB_DBT_READONLY"></a>
<code class="literal">DB_DBT_READONLY</code>
</p><p>
When this flag is set Berkeley DB will not write
into the DBT. This may be set on key values in
cases where the key is a static string that cannot
be written and Berkeley DB might try to update it
because the application has set a user defined
comparison function.
</p></li></ul></div>
</span>
</li>
</ul>
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="dbtlist"></a>DBT and Bulk Operations</h2>
</div>
</div>
</div>
<div class="navtable">
<table border="1" width="80%">
<thead>
<tr>
<th>DBT and Bulk Operations</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a class="xref" href="dbsort_multiple.html" title="DB->sort_multiple()">DB->sort_multiple()</a>
</td>
<td>Sort a set of DBTs</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_INIT.html" title="DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a>
</td>
<td>Initialize bulk get retrieval</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_NEXT.html" title="DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>
</td>
<td>Next bulk get retrieval</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_KEY_NEXT.html" title="DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>
</td>
<td>Next bulk get retrieval</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_RECNO_NEXT.html" title="DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a>
</td>
<td>Next bulk get retrieval</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_WRITE_INIT.html" title="DB_MULTIPLE_WRITE_INIT">DB_MULTIPLE_WRITE_INIT</a>
</td>
<td>Initialize a bulk buffer to hold key/data pairs</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_WRITE_NEXT.html" title="DB_MULTIPLE_WRITE_NEXT">DB_MULTIPLE_WRITE_NEXT</a>
</td>
<td>Append a data item to a bulk buffer</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_RESERVE_NEXT.html" title="DB_MULTIPLE_RESERVE_NEXT">DB_MULTIPLE_RESERVE_NEXT</a>
</td>
<td>Reserve space for a data item in a bulk buffer</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_KEY_WRITE_NEXT.html" title="DB_MULTIPLE_KEY_WRITE_NEXT">DB_MULTIPLE_KEY_WRITE_NEXT</a>
</td>
<td>Append a key / data pair to a bulk buffer</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_KEY_RESERVE_NEXT.html" title="DB_MULTIPLE_KEY_RESERVE_NEXT">DB_MULTIPLE_KEY_RESERVE_NEXT</a>
</td>
<td>Reserve space for a key / data pair in a bulk buffer</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_RECNO_WRITE_INIT.html" title="DB_MULTIPLE_RECNO_WRITE_INIT">DB_MULTIPLE_RECNO_WRITE_INIT</a>
</td>
<td>Initialize a bulk buffer to hold recno/data pairs</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_RECNO_WRITE_NEXT.html" title="DB_MULTIPLE_RECNO_WRITE_NEXT">DB_MULTIPLE_RECNO_WRITE_NEXT</a>
</td>
<td>Append a record number / data pair to a bulk buffer</td>
</tr>
<tr>
<td>
<a class="xref" href="DB_MULTIPLE_RECNO_RESERVE_NEXT.html" title="DB_MULTIPLE_RECNO_RESERVE_NEXT">DB_MULTIPLE_RECNO_RESERVE_NEXT</a>
</td>
<td>Reserve space for a record number / data pair in a bulk buffer</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="dbcset_priority.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="DB_MULTIPLE_INIT.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">DBcursor->set_priority() </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> DB_MULTIPLE_INIT</td>
</tr>
</table>
</div>
</body>
</html>
|
