1TCBDB(3) Tokyo Cabinet TCBDB(3)
2
6 tcbdb - the B+ tree database API
7
10 B+ tree database is a file containing a B+ tree and is handled with the
11 B+ tree database API.
12 To use the B+ tree database API, include `tcutil.h', `tcbdb.h', and
14 related standard header files. Usually, write the following descrip‐
15 tion near the front of a source file.
16 #include <tcutil.h>
18 #include <tcbdb.h>
19 #include <stdlib.h>
20 #include <time.h>
21 #include <stdbool.h>
22 #include <stdint.h>
23 Objects whose type is pointer to `TCBDB' are used to handle B+ tree
25 databases. A B+ tree database object is created with the function
26 `tcbdbnew' and is deleted with the function `tcbdbdel'. To avoid mem‐
27 ory leak, it is important to delete every object when it is no longer
28 in use.
29 Before operations to store or retrieve records, it is necessary to open
31 a database file and connect the B+ tree database object to it. The
32 function `tcbdbopen' is used to open a database file and the function
33 `tcbdbclose' is used to close the database file. To avoid data missing
34 or corruption, it is important to close every database file when it is
35 no longer in use. It is forbidden for multible database objects in a
36 process to open the same database at the same time.
37
40 The function `tcbdberrmsg' is used in order to get the message string
41 corresponding to an error code.
42 const char *tcbdberrmsg(int ecode);
44 `ecode' specifies the error code.
45 The return value is the message string of the error code.
46 The function `tcbdbnew' is used in order to create a B+ tree database
48 object.
49 TCBDB *tcbdbnew(void);
51 The return value is the new B+ tree database object.
52 The function `tcbdbdel' is used in order to delete a B+ tree database
54 object.
55 void tcbdbdel(TCBDB *bdb);
57 `bdb' specifies the B+ tree database object.
58 If the database is not closed, it is closed implicitly.
59 Note that the deleted object and its derivatives can not
60 be used anymore.
61 The function `tcbdbecode' is used in order to get the last happened
63 error code of a B+ tree database object.
64 int tcbdbecode(TCBDB *bdb);
66 `bdb' specifies the B+ tree database object.
67 The return value is the last happened error code.
68 The following error codes are defined: `TCESUCCESS' for
69 success, `TCETHREAD' for threading error, `TCEINVALID'
70 for invalid operation, `TCENOFILE' for file not found,
71 `TCENOPERM' for no permission, `TCEMETA' for invalid meta
72 data, `TCERHEAD' for invalid record header, `TCEOPEN' for
73 open error, `TCECLOSE' for close error, `TCETRUNC' for
74 trunc error, `TCESYNC' for sync error, `TCESTAT' for stat
75 error, `TCESEEK' for seek error, `TCEREAD' for read
76 error, `TCEWRITE' for write error, `TCEMMAP' for mmap
77 error, `TCELOCK' for lock error, `TCEUNLINK' for unlink
78 error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir
79 error, `TCERMDIR' for rmdir error, `TCEKEEP' for existing
80 record, `TCENOREC' for no record found, and `TCEMISC' for
81 miscellaneous error.
82 The function `tcbdbsetmutex' is used in order to set mutual exclusion
84 control of a B+ tree database object for threading.
85 bool tcbdbsetmutex(TCBDB *bdb);
87 `bdb' specifies the B+ tree database object which is not
88 opened.
89 If successful, the return value is true, else, it is
90 false.
91 Note that the mutual exclusion control of the database
92 should be set before the database is opened.
93 The function `tcbdbsetcmpfunc' is used in order to set the custom com‐
95 parison function of a B+ tree database object.
96 bool tcbdbsetcmpfunc(TCBDB *bdb, TCCMP cmp, void *cmpop);
98 `bdb' specifies the B+ tree database object which is not
99 opened.
100 `cmp' specifies the pointer to the custom comparison
101 function. It receives five parameters. The first param‐
102 eter is the pointer to the region of one key. The second
103 parameter is the size of the region of one key. The
104 third parameter is the pointer to the region of the other
105 key. The fourth parameter is the size of the region of
106 the other key. The fifth parameter is the pointer to the
107 optional opaque object. It returns positive if the for‐
108 mer is big, negative if the latter is big, 0 if both are
109 equivalent.
110 `cmpop' specifies an arbitrary pointer to be given as a
111 parameter of the comparison function. If it is not
112 needed, `NULL' can be specified.
113 If successful, the return value is true, else, it is
114 false.
115 The default comparison function compares keys of two
116 records by lexical order. The functions `tccmplexical'
117 (dafault), `tccmpdecimal', `tccmpint32', and `tccmpint64'
118 are built-in. Note that the comparison function should
119 be set before the database is opened. Moreover,
120 user-defined comparison functions should be set every
121 time the database is being opened.
122 The function `tcbdbtune' is used in order to set the tuning parameters
124 of a B+ tree database object.
125 bool tcbdbtune(TCBDB *bdb, int32_t lmemb, int32_t nmemb, int64_t
127 bnum, int8_t apow, int8_t fpow, uint8_t opts);
128 `bdb' specifies the B+ tree database object which is not
129 opened.
130 `lmemb' specifies the number of members in each leaf
131 page. If it is not more than 0, the default value is
132 specified. The default value is 128.
133 `nmemb' specifies the number of members in each non-leaf
134 page. If it is not more than 0, the default value is
135 specified. The default value is 256.
136 `bnum' specifies the number of elements of the bucket
137 array. If it is not more than 0, the default value is
138 specified. The default value is 16381. Suggested size
139 of the bucket array is about from 1 to 4 times of the
140 number of all pages to be stored.
141 `apow' specifies the size of record alignment by power of
142 2. If it is negative, the default value is specified.
143 The default value is 8 standing for 2^8=256.
144 `fpow' specifies the maximum number of elements of the
145 free block pool by power of 2. If it is negative, the
146 default value is specified. The default value is 10
147 standing for 2^10=1024.
148 `opts' specifies options by bitwise-or: `BDBTLARGE' spec‐
149 ifies that the size of the database can be larger than
150 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies
151 that each page is compressed with Deflate encoding,
152 `BDBTBZIP' specifies that each page is compressed with
153 BZIP2 encoding, `BDBTTCBS' specifies that each page is
154 compressed with TCBS encoding.
155 If successful, the return value is true, else, it is
156 false.
157 Note that the tuning parameters should be set before the
158 database is opened.
159 The function `tcbdbsetcache' is used in order to set the caching param‐
161 eters of a B+ tree database object.
162 bool tcbdbsetcache(TCBDB *bdb, int32_t lcnum, int32_t ncnum);
164 `bdb' specifies the B+ tree database object which is not
165 opened.
166 `lcnum' specifies the maximum number of leaf nodes to be
167 cached. If it is not more than 0, the default value is
168 specified. The default value is 1024.
169 `ncnum' specifies the maximum number of non-leaf nodes to
170 be cached. If it is not more than 0, the default value
171 is specified. The default value is 512.
172 If successful, the return value is true, else, it is
173 false.
174 Note that the caching parameters should be set before the
175 database is opened.
176 The function `tcbdbsetxmsiz' is used in order to set the size of the
178 extra mapped memory of a B+ tree database object.
179 bool tcbdbsetxmsiz(TCBDB *bdb, int64_t xmsiz);
181 `bdb' specifies the B+ tree database object which is not
182 opened.
183 `xmsiz' specifies the size of the extra mapped memory.
184 If it is not more than 0, the extra mapped memory is dis‐
185 abled. It is disabled by default.
186 If successful, the return value is true, else, it is
187 false.
188 Note that the mapping parameters should be set before the
189 database is opened.
190 The function `tcbdbsetdfunit' is used in order to set the unit step
192 number of auto defragmentation of a B+ tree database object.
193 bool tcbdbsetdfunit(TCBDB *bdb, int32_t dfunit);
195 `bdb' specifies the B+ tree database object which is not
196 opened.
197 `dfunit' specifie the unit step number. If it is not
198 more than 0, the auto defragmentation is disabled. It is
199 disabled by default.
200 If successful, the return value is true, else, it is
201 false.
202 Note that the defragmentation parameter should be set
203 before the database is opened.
204 The function `tcbdbopen' is used in order to open a database file and
206 connect a B+ tree database object.
207 bool tcbdbopen(TCBDB *bdb, const char *path, int omode);
209 `bdb' specifies the B+ tree database object which is not
210 opened.
211 `path' specifies the path of the database file.
212 `omode' specifies the connection mode: `BDBOWRITER' as a
213 writer, `BDBOREADER' as a reader. If the mode is
214 `BDBOWRITER', the following may be added by bitwise-or:
215 `BDBOCREAT', which means it creates a new database if not
216 exist, `BDBOTRUNC', which means it creates a new database
217 regardless if one exists, `BDBOTSYNC', which means every
218 transaction synchronizes updated contents with the
219 device. Both of `BDBOREADER' and `BDBOWRITER' can be
220 added to by bitwise-or: `BDBONOLCK', which means it opens
221 the database file without file locking, or `BDBOLCKNB',
222 which means locking is performed without blocking.
223 If successful, the return value is true, else, it is
224 false.
225 The function `tcbdbclose' is used in order to close a B+ tree database
227 object.
228 bool tcbdbclose(TCBDB *bdb);
230 `bdb' specifies the B+ tree database object.
231 If successful, the return value is true, else, it is
232 false.
233 Update of a database is assured to be written when the
234 database is closed. If a writer opens a database but
235 does not close it appropriately, the database will be
236 broken.
237 The function `tcbdbput' is used in order to store a record into a B+
239 tree database object.
240 bool tcbdbput(TCBDB *bdb, const void *kbuf, int ksiz, const void
242 *vbuf, int vsiz);
243 `bdb' specifies the B+ tree database object connected as
244 a writer.
245 `kbuf' specifies the pointer to the region of the key.
246 `ksiz' specifies the size of the region of the key.
247 `vbuf' specifies the pointer to the region of the value.
248 `vsiz' specifies the size of the region of the value.
249 If successful, the return value is true, else, it is
250 false.
251 If a record with the same key exists in the database, it
252 is overwritten.
253 The function `tcbdbput2' is used in order to store a string record into
255 a B+ tree database object.
256 bool tcbdbput2(TCBDB *bdb, const char *kstr, const char *vstr);
258 `bdb' specifies the B+ tree database object connected as
259 a writer.
260 `kstr' specifies the string of the key.
261 `vstr' specifies the string of the value.
262 If successful, the return value is true, else, it is
263 false.
264 If a record with the same key exists in the database, it
265 is overwritten.
266 The function `tcbdbputkeep' is used in order to store a new record into
268 a B+ tree database object.
269 bool tcbdbputkeep(TCBDB *bdb, const void *kbuf, int ksiz, const
271 void *vbuf, int vsiz);
272 `bdb' specifies the B+ tree database object connected as
273 a writer.
274 `kbuf' specifies the pointer to the region of the key.
275 `ksiz' specifies the size of the region of the key.
276 `vbuf' specifies the pointer to the region of the value.
277 `vsiz' specifies the size of the region of the value.
278 If successful, the return value is true, else, it is
279 false.
280 If a record with the same key exists in the database,
281 this function has no effect.
282 The function `tcbdbputkeep2' is used in order to store a new string
284 record into a B+ tree database object.
285 bool tcbdbputkeep2(TCBDB *bdb, const char *kstr, const char
287 *vstr);
288 `bdb' specifies the B+ tree database object connected as
289 a writer.
290 `kstr' specifies the string of the key.
291 `vstr' specifies the string of the value.
292 If successful, the return value is true, else, it is
293 false.
294 If a record with the same key exists in the database,
295 this function has no effect.
296 The function `tcbdbputcat' is used in order to concatenate a value at
298 the end of the existing record in a B+ tree database object.
299 bool tcbdbputcat(TCBDB *bdb, const void *kbuf, int ksiz, const
301 void *vbuf, int vsiz);
302 `bdb' specifies the B+ tree database object connected as
303 a writer.
304 `kbuf' specifies the pointer to the region of the key.
305 `ksiz' specifies the size of the region of the key.
306 `vbuf' specifies the pointer to the region of the value.
307 `vsiz' specifies the size of the region of the value.
308 If successful, the return value is true, else, it is
309 false.
310 If there is no corresponding record, a new record is cre‐
311 ated.
312 The function `tcbdbputcat2' is used in order to concatenate a string
314 value at the end of the existing record in a B+ tree database object.
315 bool tcbdbputcat2(TCBDB *bdb, const char *kstr, const char
317 *vstr);
318 `bdb' specifies the B+ tree database object connected as
319 a writer.
320 `kstr' specifies the string of the key.
321 `vstr' specifies the string of the value.
322 If successful, the return value is true, else, it is
323 false.
324 If there is no corresponding record, a new record is cre‐
325 ated.
326 The function `tcbdbputdup' is used in order to store a record into a B+
328 tree database object with allowing duplication of keys.
329 bool tcbdbputdup(TCBDB *bdb, const void *kbuf, int ksiz, const
331 void *vbuf, int vsiz);
332 `bdb' specifies the B+ tree database object connected as
333 a writer.
334 `kbuf' specifies the pointer to the region of the key.
335 `ksiz' specifies the size of the region of the key.
336 `vbuf' specifies the pointer to the region of the value.
337 `vsiz' specifies the size of the region of the value.
338 If successful, the return value is true, else, it is
339 false.
340 If a record with the same key exists in the database, the
341 new record is placed after the existing one.
342 The function `tcbdbputdup2' is used in order to store a string record
344 into a B+ tree database object with allowing duplication of keys.
345 bool tcbdbputdup2(TCBDB *bdb, const char *kstr, const char
347 *vstr);
348 `bdb' specifies the B+ tree database object connected as
349 a writer.
350 `kstr' specifies the string of the key.
351 `vstr' specifies the string of the value.
352 If successful, the return value is true, else, it is
353 false.
354 If a record with the same key exists in the database, the
355 new record is placed after the existing one.
356 The function `tcbdbputdup3' is used in order to store records into a B+
358 tree database object with allowing duplication of keys.
359 bool tcbdbputdup3(TCBDB *bdb, const void *kbuf, int ksiz, const
361 TCLIST *vals);
362 `bdb' specifies the B+ tree database object connected as
363 a writer.
364 `kbuf' specifies the pointer to the region of the common
365 key.
366 `ksiz' specifies the size of the region of the common
367 key.
368 `vals' specifies a list object containing values.
369 If successful, the return value is true, else, it is
370 false.
371 If a record with the same key exists in the database, the
372 new records are placed after the existing one.
373 The function `tcbdbout' is used in order to remove a record of a B+
375 tree database object.
376 bool tcbdbout(TCBDB *bdb, const void *kbuf, int ksiz);
378 `bdb' specifies the B+ tree database object connected as
379 a writer.
380 `kbuf' specifies the pointer to the region of the key.
381 `ksiz' specifies the size of the region of the key.
382 If successful, the return value is true, else, it is
383 false.
384 If the key of duplicated records is specified, the first
385 one is selected.
386 The function `tcbdbout2' is used in order to remove a string record of
388 a B+ tree database object.
389 bool tcbdbout2(TCBDB *bdb, const char *kstr);
391 `bdb' specifies the B+ tree database object connected as
392 a writer.
393 `kstr' specifies the string of the key.
394 If successful, the return value is true, else, it is
395 false.
396 If the key of duplicated records is specified, the first
397 one is selected.
398 The function `tcbdbout3' is used in order to remove records of a B+
400 tree database object.
401 bool tcbdbout3(TCBDB *bdb, const void *kbuf, int ksiz);
403 `bdb' specifies the B+ tree database object connected as
404 a writer.
405 `kbuf' specifies the pointer to the region of the key.
406 `ksiz' specifies the size of the region of the key.
407 If successful, the return value is true, else, it is
408 false.
409 If the key of duplicated records is specified, all of
410 them are removed.
411 The function `tcbdbget' is used in order to retrieve a record in a B+
413 tree database object.
414 void *tcbdbget(TCBDB *bdb, const void *kbuf, int ksiz, int *sp);
416 `bdb' specifies the B+ tree database object.
417 `kbuf' specifies the pointer to the region of the key.
418 `ksiz' specifies the size of the region of the key.
419 `sp' specifies the pointer to the variable into which the
420 size of the region of the return value is assigned.
421 If successful, the return value is the pointer to the
422 region of the value of the corresponding record. `NULL'
423 is returned if no record corresponds.
424 If the key of duplicated records is specified, the first
425 one is selected. Because an additional zero code is
426 appended at the end of the region of the return value,
427 the return value can be treated as a character string.
428 Because the region of the return value is allocated with
429 the `malloc' call, it should be released with the `free'
430 call when it is no longer in use.
431 The function `tcbdbget2' is used in order to retrieve a string record
433 in a B+ tree database object.
434 char *tcbdbget2(TCBDB *bdb, const char *kstr);
436 `bdb' specifies the B+ tree database object.
437 `kstr' specifies the string of the key.
438 If successful, the return value is the string of the
439 value of the corresponding record. `NULL' is returned if
440 no record corresponds.
441 If the key of duplicated records is specified, the first
442 one is selected. Because the region of the return value
443 is allocated with the `malloc' call, it should be
444 released with the `free' call when it is no longer in
445 use.
446 The function `tcbdbget3' is used in order to retrieve a record in a B+
448 tree database object as a volatile buffer.
449 const void *tcbdbget3(TCBDB *bdb, const void *kbuf, int ksiz,
451 int *sp);
452 `bdb' specifies the B+ tree database object.
453 `kbuf' specifies the pointer to the region of the key.
454 `ksiz' specifies the size of the region of the key.
455 `sp' specifies the pointer to the variable into which the
456 size of the region of the return value is assigned.
457 If successful, the return value is the pointer to the
458 region of the value of the corresponding record. `NULL'
459 is returned if no record corresponds.
460 If the key of duplicated records is specified, the first
461 one is selected. Because an additional zero code is
462 appended at the end of the region of the return value,
463 the return value can be treated as a character string.
464 Because the region of the return value is volatile and it
465 may be spoiled by another operation of the database, the
466 data should be copied into another involatile buffer
467 immediately.
468 The function `tcbdbget4' is used in order to retrieve records in a B+
470 tree database object.
471 TCLIST *tcbdbget4(TCBDB *bdb, const void *kbuf, int ksiz);
473 `bdb' specifies the B+ tree database object.
474 `kbuf' specifies the pointer to the region of the key.
475 `ksiz' specifies the size of the region of the key.
476 If successful, the return value is a list object of the
477 values of the corresponding records. `NULL' is returned
478 if no record corresponds.
479 Because the object of the return value is created with
480 the function `tclistnew', it should be deleted with the
481 function `tclistdel' when it is no longer in use.
482 The function `tcbdbvnum' is used in order to get the number of records
484 corresponding a key in a B+ tree database object.
485 int tcbdbvnum(TCBDB *bdb, const void *kbuf, int ksiz);
487 `bdb' specifies the B+ tree database object.
488 `kbuf' specifies the pointer to the region of the key.
489 `ksiz' specifies the size of the region of the key.
490 If successful, the return value is the number of the cor‐
491 responding records, else, it is 0.
492 The function `tcbdbvnum2' is used in order to get the number of records
494 corresponding a string key in a B+ tree database object.
495 int tcbdbvnum2(TCBDB *bdb, const char *kstr);
497 `bdb' specifies the B+ tree database object.
498 `kstr' specifies the string of the key.
499 If successful, the return value is the number of the cor‐
500 responding records, else, it is 0.
501 The function `tcbdbvsiz' is used in order to get the size of the value
503 of a record in a B+ tree database object.
504 int tcbdbvsiz(TCBDB *bdb, const void *kbuf, int ksiz);
506 `bdb' specifies the B+ tree database object.
507 `kbuf' specifies the pointer to the region of the key.
508 `ksiz' specifies the size of the region of the key.
509 If successful, the return value is the size of the value
510 of the corresponding record, else, it is -1.
511 If the key of duplicated records is specified, the first
512 one is selected.
513 The function `tcbdbvsiz2' is used in order to get the size of the value
515 of a string record in a B+ tree database object.
516 int tcbdbvsiz2(TCBDB *bdb, const char *kstr);
518 `bdb' specifies the B+ tree database object.
519 `kstr' specifies the string of the key.
520 If successful, the return value is the size of the value
521 of the corresponding record, else, it is -1.
522 If the key of duplicated records is specified, the first
523 one is selected.
524 The function `tcbdbrange' is used in order to get keys of ranged
526 records in a B+ tree database object.
527 TCLIST *tcbdbrange(TCBDB *bdb, const void *bkbuf, int bksiz,
529 bool binc, const void *ekbuf, int eksiz, bool einc, int max);
530 `bdb' specifies the B+ tree database object.
531 `bkbuf' specifies the pointer to the region of the key of
532 the beginning border. If it is `NULL', the first record
533 is specified.
534 `bksiz' specifies the size of the region of the beginning
535 key.
536 `binc' specifies whether the beginning border is inclu‐
537 sive or not.
538 `ekbuf' specifies the pointer to the region of the key of
539 the ending border. If it is `NULL', the last record is
540 specified.
541 `eksiz' specifies the size of the region of the ending
542 key.
543 `einc' specifies whether the ending border is inclusive
544 or not.
545 `max' specifies the maximum number of keys to be fetched.
546 If it is negative, no limit is specified.
547 The return value is a list object of the keys of the cor‐
548 responding records. This function does never fail. It
549 returns an empty list even if no record corresponds.
550 Because the object of the return value is created with
551 the function `tclistnew', it should be deleted with the
552 function `tclistdel' when it is no longer in use.
553 The function `tcbdbrange2' is used in order to get string keys of
555 ranged records in a B+ tree database object.
556 TCLIST *tcbdbrange2(TCBDB *bdb, const char *bkstr, bool binc,
558 const char *ekstr, bool einc, int max);
559 `bdb' specifies the B+ tree database object.
560 `bkstr' specifies the string of the key of the beginning
561 border. If it is `NULL', the first record is specified.
562 `binc' specifies whether the beginning border is inclu‐
563 sive or not.
564 `ekstr' specifies the string of the key of the ending
565 border. If it is `NULL', the last record is specified.
566 `einc' specifies whether the ending border is inclusive
567 or not.
568 `max' specifies the maximum number of keys to be fetched.
569 If it is negative, no limit is specified.
570 The return value is a list object of the keys of the cor‐
571 responding records. This function does never fail. It
572 returns an empty list even if no record corresponds.
573 Because the object of the return value is created with
574 the function `tclistnew', it should be deleted with the
575 function `tclistdel' when it is no longer in use.
576 The function `tcbdbfwmkeys' is used in order to get forward matching
578 keys in a B+ tree database object.
579 TCLIST *tcbdbfwmkeys(TCBDB *bdb, const void *pbuf, int psiz, int
581 max);
582 `bdb' specifies the B+ tree database object.
583 `pbuf' specifies the pointer to the region of the prefix.
584 `psiz' specifies the size of the region of the prefix.
585 `max' specifies the maximum number of keys to be fetched.
586 If it is negative, no limit is specified.
587 The return value is a list object of the corresponding
588 keys. This function does never fail. It returns an
589 empty list even if no key corresponds.
590 Because the object of the return value is created with
591 the function `tclistnew', it should be deleted with the
592 function `tclistdel' when it is no longer in use.
593 The function `tcbdbfwmkeys2' is used in order to get forward matching
595 string keys in a B+ tree database object.
596 TCLIST *tcbdbfwmkeys2(TCBDB *bdb, const char *pstr, int max);
598 `bdb' specifies the B+ tree database object.
599 `pstr' specifies the string of the prefix.
600 `max' specifies the maximum number of keys to be fetched.
601 If it is negative, no limit is specified.
602 The return value is a list object of the corresponding
603 keys. This function does never fail. It returns an
604 empty list even if no key corresponds.
605 Because the object of the return value is created with
606 the function `tclistnew', it should be deleted with the
607 function `tclistdel' when it is no longer in use.
608 The function `tcbdbaddint' is used in order to add an integer to a
610 record in a B+ tree database object.
611 int tcbdbaddint(TCBDB *bdb, const void *kbuf, int ksiz, int
613 num);
614 `bdb' specifies the B+ tree database object connected as
615 a writer.
616 `kbuf' specifies the pointer to the region of the key.
617 `ksiz' specifies the size of the region of the key.
618 `num' specifies the additional value.
619 If successful, the return value is the summation value,
620 else, it is `INT_MIN'.
621 If the corresponding record exists, the value is treated
622 as an integer and is added to. If no record corresponds,
623 a new record of the additional value is stored.
624 The function `tcbdbadddouble' is used in order to add a real number to
626 a record in a B+ tree database object.
627 double tcbdbadddouble(TCBDB *bdb, const void *kbuf, int ksiz,
629 double num);
630 `bdb' specifies the B+ tree database object connected as
631 a writer.
632 `kbuf' specifies the pointer to the region of the key.
633 `ksiz' specifies the size of the region of the key.
634 `num' specifies the additional value.
635 If successful, the return value is the summation value,
636 else, it is Not-a-Number.
637 If the corresponding record exists, the value is treated
638 as a real number and is added to. If no record corre‐
639 sponds, a new record of the additional value is stored.
640 The function `tcbdbsync' is used in order to synchronize updated con‐
642 tents of a B+ tree database object with the file and the device.
643 bool tcbdbsync(TCBDB *bdb);
645 `bdb' specifies the B+ tree database object connected as
646 a writer.
647 If successful, the return value is true, else, it is
648 false.
649 This function is useful when another process connects to
650 the same database file.
651 The function `tcbdboptimize' is used in order to optimize the file of a
653 B+ tree database object.
654 bool tcbdboptimize(TCBDB *bdb, int32_t lmemb, int32_t nmemb,
656 int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
657 `bdb' specifies the B+ tree database object connected as
658 a writer.
659 `lmemb' specifies the number of members in each leaf
660 page. If it is not more than 0, the current setting is
661 not changed.
662 `nmemb' specifies the number of members in each non-leaf
663 page. If it is not more than 0, the current setting is
664 not changed.
665 `bnum' specifies the number of elements of the bucket
666 array. If it is not more than 0, the default value is
667 specified. The default value is two times of the number
668 of pages.
669 `apow' specifies the size of record alignment by power of
670 2. If it is negative, the current setting is not
671 changed.
672 `fpow' specifies the maximum number of elements of the
673 free block pool by power of 2. If it is negative, the
674 current setting is not changed.
675 `opts' specifies options by bitwise-or: `BDBTLARGE' spec‐
676 ifies that the size of the database can be larger than
677 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies
678 that each record is compressed with Deflate encoding,
679 `BDBTBZIP' specifies that each page is compressed with
680 BZIP2 encoding, `BDBTTCBS' specifies that each page is
681 compressed with TCBS encoding. If it is `UINT8_MAX', the
682 current setting is not changed.
683 If successful, the return value is true, else, it is
684 false.
685 This function is useful to reduce the size of the data‐
686 base file with data fragmentation by successive updating.
687 The function `tcbdbvanish' is used in order to remove all records of a
689 B+ tree database object.
690 bool tcbdbvanish(TCBDB *bdb);
692 `bdb' specifies the B+ tree database object connected as
693 a writer.
694 If successful, the return value is true, else, it is
695 false.
696 The function `tcbdbcopy' is used in order to copy the database file of
698 a B+ tree database object.
699 bool tcbdbcopy(TCBDB *bdb, const char *path);
701 `bdb' specifies the B+ tree database object.
702 `path' specifies the path of the destination file. If it
703 begins with `@', the trailing substring is executed as a
704 command line.
705 If successful, the return value is true, else, it is
706 false. False is returned if the executed command returns
707 non-zero code.
708 The database file is assured to be kept synchronized and
709 not modified while the copying or executing operation is
710 in progress. So, this function is useful to create a
711 backup file of the database file.
712 The function `tcbdbtranbegin' is used in order to begin the transaction
714 of a B+ tree database object.
715 bool tcbdbtranbegin(TCBDB *bdb);
717 `bdb' specifies the B+ tree database object connected as
718 a writer.
719 If successful, the return value is true, else, it is
720 false.
721 The database is locked by the thread while the transac‐
722 tion so that only one transaction can be activated with a
723 database object at the same time. Thus, the serializable
724 isolation level is assumed if every database operation is
725 performed in the transaction. Because all pages are
726 cached on memory while the transaction, the amount of
727 referred records is limited by the memory capacity. If
728 the database is closed during transaction, the transac‐
729 tion is aborted implicitly.
730 The function `tcbdbtrancommit' is used in order to commit the transac‐
732 tion of a B+ tree database object.
733 bool tcbdbtrancommit(TCBDB *bdb);
735 `bdb' specifies the B+ tree database object connected as
736 a writer.
737 If successful, the return value is true, else, it is
738 false.
739 Update in the transaction is fixed when it is committed
740 successfully.
741 The function `tcbdbtranabort' is used in order to abort the transaction
743 of a B+ tree database object.
744 bool tcbdbtranabort(TCBDB *bdb);
746 `bdb' specifies the B+ tree database object connected as
747 a writer.
748 If successful, the return value is true, else, it is
749 false.
750 Update in the transaction is discarded when it is
751 aborted. The state of the database is rollbacked to
752 before transaction.
753 The function `tcbdbpath' is used in order to get the file path of a B+
755 tree database object.
756 const char *tcbdbpath(TCBDB *bdb);
758 `bdb' specifies the B+ tree database object.
759 The return value is the path of the database file or
760 `NULL' if the object does not connect to any database
761 file.
762 The function `tcbdbrnum' is used in order to get the number of records
764 of a B+ tree database object.
765 uint64_t tcbdbrnum(TCBDB *bdb);
767 `bdb' specifies the B+ tree database object.
768 The return value is the number of records or 0 if the
769 object does not connect to any database file.
770 The function `tcbdbfsiz' is used in order to get the size of the data‐
772 base file of a B+ tree database object.
773 uint64_t tcbdbfsiz(TCBDB *bdb);
775 `bdb' specifies the B+ tree database object.
776 The return value is the size of the database file or 0 if
777 the object does not connect to any database file.
778 The function `tcbdbcurnew' is used in order to create a cursor object.
780 BDBCUR *tcbdbcurnew(TCBDB *bdb);
782 `bdb' specifies the B+ tree database object.
783 The return value is the new cursor object.
784 Note that the cursor is available only after initializa‐
785 tion with the `tcbdbcurfirst' or the `tcbdbcurjump' func‐
786 tions and so on. Moreover, the position of the cursor
787 will be indefinite when the database is updated after the
788 initialization of the cursor.
789 The function `tcbdbcurdel' is used in order to delete a cursor object.
791 void tcbdbcurdel(BDBCUR *cur);
793 `cur' specifies the cursor object.
794 The function `tcbdbcurfirst' is used in order to move a cursor object
796 to the first record.
797 bool tcbdbcurfirst(BDBCUR *cur);
799 `cur' specifies the cursor object.
800 If successful, the return value is true, else, it is
801 false. False is returned if there is no record in the
802 database.
803 The function `tcbdbcurlast' is used in order to move a cursor object to
805 the last record.
806 bool tcbdbcurlast(BDBCUR *cur);
808 `cur' specifies the cursor object.
809 If successful, the return value is true, else, it is
810 false. False is returned if there is no record in the
811 database.
812 The function `tcbdbcurjump' is used in order to move a cursor object to
814 the front of records corresponding a key.
815 bool tcbdbcurjump(BDBCUR *cur, const void *kbuf, int ksiz);
817 `cur' specifies the cursor object.
818 `kbuf' specifies the pointer to the region of the key.
819 `ksiz' specifies the size of the region of the key.
820 If successful, the return value is true, else, it is
821 false. False is returned if there is no record corre‐
822 sponding the condition.
823 The cursor is set to the first record corresponding the
824 key or the next substitute if completely matching record
825 does not exist.
826 The function `tcbdbcurjump2' is used in order to move a cursor object
828 to the front of records corresponding a key string.
829 bool tcbdbcurjump2(BDBCUR *cur, const char *kstr);
831 `cur' specifies the cursor object.
832 `kstr' specifies the string of the key.
833 If successful, the return value is true, else, it is
834 false. False is returned if there is no record corre‐
835 sponding the condition.
836 The cursor is set to the first record corresponding the
837 key or the next substitute if completely matching record
838 does not exist.
839 The function `tcbdbcurprev' is used in order to move a cursor object to
841 the previous record.
842 bool tcbdbcurprev(BDBCUR *cur);
844 `cur' specifies the cursor object.
845 If successful, the return value is true, else, it is
846 false. False is returned if there is no previous record.
847 The function `tcbdbcurnext' is used in order to move a cursor object to
849 the next record.
850 bool tcbdbcurnext(BDBCUR *cur);
852 `cur' specifies the cursor object.
853 If successful, the return value is true, else, it is
854 false. False is returned if there is no next record.
855 The function `tcbdbcurput' is used in order to insert a record around a
857 cursor object.
858 bool tcbdbcurput(BDBCUR *cur, const void *vbuf, int vsiz, int
860 cpmode);
861 `cur' specifies the cursor object of writer connection.
862 `vbuf' specifies the pointer to the region of the value.
863 `vsiz' specifies the size of the region of the value.
864 `cpmode' specifies detail adjustment: `BDBCPCURRENT',
865 which means that the value of the current record is over‐
866 written, `BDBCPBEFORE', which means that the new record
867 is inserted before the current record, `BDBCPAFTER',
868 which means that the new record is inserted after the
869 current record.
870 If successful, the return value is true, else, it is
871 false. False is returned when the cursor is at invalid
872 position.
873 After insertion, the cursor is moved to the inserted
874 record.
875 The function `tcbdbcurput2' is used in order to insert a string record
877 around a cursor object.
878 bool tcbdbcurput2(BDBCUR *cur, const char *vstr, int cpmode);
880 `cur' specifies the cursor object of writer connection.
881 `vstr' specifies the string of the value.
882 `cpmode' specifies detail adjustment: `BDBCPCURRENT',
883 which means that the value of the current record is over‐
884 written, `BDBCPBEFORE', which means that the new record
885 is inserted before the current record, `BDBCPAFTER',
886 which means that the new record is inserted after the
887 current record.
888 If successful, the return value is true, else, it is
889 false. False is returned when the cursor is at invalid
890 position.
891 After insertion, the cursor is moved to the inserted
892 record.
893 The function `tcbdbcurout' is used in order to remove the record where
895 a cursor object is.
896 bool tcbdbcurout(BDBCUR *cur);
898 `cur' specifies the cursor object of writer connection.
899 If successful, the return value is true, else, it is
900 false. False is returned when the cursor is at invalid
901 position.
902 After deletion, the cursor is moved to the next record if
903 possible.
904 The function `tcbdbcurkey' is used in order to get the key of the
906 record where the cursor object is.
907 char *tcbdbcurkey(BDBCUR *cur, int *sp);
909 `cur' specifies the cursor object.
910 `sp' specifies the pointer to the variable into which the
911 size of the region of the return value is assigned.
912 If successful, the return value is the pointer to the
913 region of the key, else, it is `NULL'. `NULL' is
914 returned when the cursor is at invalid position.
915 Because an additional zero code is appended at the end of
916 the region of the return value, the return value can be
917 treated as a character string. Because the region of the
918 return value is allocated with the `malloc' call, it
919 should be released with the `free' call when it is no
920 longer in use.
921 The function `tcbdbcurkey2' is used in order to get the key string of
923 the record where the cursor object is.
924 char *tcbdbcurkey2(BDBCUR *cur);
926 `cur' specifies the cursor object.
927 If successful, the return value is the string of the key,
928 else, it is `NULL'. `NULL' is returned when the cursor
929 is at invalid position.
930 Because the region of the return value is allocated with
931 the `malloc' call, it should be released with the `free'
932 call when it is no longer in use.
933 The function `tcbdbcurkey3' is used in order to get the key of the
935 record where the cursor object is, as a volatile buffer.
936 const char *tcbdbcurkey3(BDBCUR *cur, int *sp);
938 `cur' specifies the cursor object.
939 `sp' specifies the pointer to the variable into which the
940 size of the region of the return value is assigned.
941 If successful, the return value is the pointer to the
942 region of the key, else, it is `NULL'. `NULL' is
943 returned when the cursor is at invalid position.
944 Because an additional zero code is appended at the end of
945 the region of the return value, the return value can be
946 treated as a character string. Because the region of the
947 return value is volatile and it may be spoiled by another
948 operation of the database, the data should be copied into
949 another involatile buffer immediately.
950 The function `tcbdbcurval' is used in order to get the value of the
952 record where the cursor object is.
953 char *tcbdbcurval(BDBCUR *cur, int *sp);
955 `cur' specifies the cursor object.
956 `sp' specifies the pointer to the variable into which the
957 size of the region of the return value is assigned.
958 If successful, the return value is the pointer to the
959 region of the value, else, it is `NULL'. `NULL' is
960 returned when the cursor is at invalid position.
961 Because an additional zero code is appended at the end of
962 the region of the return value, the return value can be
963 treated as a character string. Because the region of the
964 return value is allocated with the `malloc' call, it
965 should be released with the `free' call when it is no
966 longer in use.
967 The function `tcbdbcurval2' is used in order to get the value string of
969 the record where the cursor object is.
970 char *tcbdbcurval2(BDBCUR *cur);
972 `cur' specifies the cursor object.
973 If successful, the return value is the string of the
974 value, else, it is `NULL'. `NULL' is returned when the
975 cursor is at invalid position.
976 Because the region of the return value is allocated with
977 the `malloc' call, it should be released with the `free'
978 call when it is no longer in use.
979 The function `tcbdbcurval3' is used in order to get the value of the
981 record where the cursor object is, as a volatile buffer.
982 const char *tcbdbcurval3(BDBCUR *cur, int *sp);
984 `cur' specifies the cursor object.
985 `sp' specifies the pointer to the variable into which the
986 size of the region of the return value is assigned.
987 If successful, the return value is the pointer to the
988 region of the value, else, it is `NULL'. `NULL' is
989 returned when the cursor is at invalid position.
990 Because an additional zero code is appended at the end of
991 the region of the return value, the return value can be
992 treated as a character string. Because the region of the
993 return value is volatile and it may be spoiled by another
994 operation of the database, the data should be copied into
995 another involatile buffer immediately.
996 The function `tcbdbcurrec' is used in order to get the key and the
998 value of the record where the cursor object is.
999 bool tcbdbcurrec(BDBCUR *cur, TCXSTR *kxstr, TCXSTR *vxstr);
1001 `cur' specifies the cursor object.
1002 `kxstr' specifies the object into which the key is wrote
1003 down.
1004 `vxstr' specifies the object into which the value is
1005 wrote down.
1006 If successful, the return value is true, else, it is
1007 false. False is returned when the cursor is at invalid
1008 position.
1009
1012 tcbtest(1), tcbmttest(1), tcbmgr(1), tokyocabinet(3)
1013Man Page 2010-08-05 TCBDB(3)