1TCBDB(3)                         Tokyo Cabinet                        TCBDB(3)
2
3
4

NAME

6       tcbdb - the B+ tree database API
7
8

DESCRIPTION

10       B+ tree database is a file containing a B+ tree and is handled with the
11       B+ tree database API.
12
13       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
17              #include <tcutil.h>
18              #include <tcbdb.h>
19              #include <stdlib.h>
20              #include <time.h>
21              #include <stdbool.h>
22              #include <stdint.h>
23
24       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
30       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
38

API

40       The function `tcbdberrmsg' is used in order to get the  message  string
41       corresponding to an error code.
42
43              const char *tcbdberrmsg(int ecode);
44                     `ecode' specifies the error code.
45                     The return value is the message string of the error code.
46
47       The  function  `tcbdbnew' is used in order to create a B+ tree database
48       object.
49
50              TCBDB *tcbdbnew(void);
51                     The return value is the new B+ tree database object.
52
53       The function `tcbdbdel' is used in order to delete a B+  tree  database
54       object.
55
56              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
62       The  function  `tcbdbecode'  is  used in order to get the last happened
63       error code of a B+ tree database object.
64
65              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
83       The  function  `tcbdbsetmutex' is used in order to set mutual exclusion
84       control of a B+ tree database object for threading.
85
86              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
94       The  function `tcbdbsetcmpfunc' is used in order to set the custom com‐
95       parison function of a B+ tree database object.
96
97              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
123       The  function `tcbdbtune' is used in order to set the tuning parameters
124       of a B+ tree database object.
125
126              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
160       The function `tcbdbsetcache' is used in order to set the caching param‐
161       eters of a B+ tree database object.
162
163              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
177       The  function  `tcbdbsetxmsiz'  is used in order to set the size of the
178       extra mapped memory of a B+ tree database object.
179
180              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
191       The  function  `tcbdbsetdfunit'  is  used in order to set the unit step
192       number of auto defragmentation of a B+ tree database object.
193
194              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
205       The  function  `tcbdbopen' is used in order to open a database file and
206       connect a B+ tree database object.
207
208              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
226       The function `tcbdbclose' is used in order to close a B+ tree  database
227       object.
228
229              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
238       The  function  `tcbdbput'  is used in order to store a record into a B+
239       tree database object.
240
241              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
254       The function `tcbdbput2' is used in order to store a string record into
255       a B+ tree database object.
256
257              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
267       The function `tcbdbputkeep' is used in order to store a new record into
268       a B+ tree database object.
269
270              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
283       The  function  `tcbdbputkeep2'  is  used in order to store a new string
284       record into a B+ tree database object.
285
286              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
297       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
300              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
313       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
316              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
327       The function `tcbdbputdup' is used in order to store a record into a B+
328       tree database object with allowing duplication of keys.
329
330              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
343       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
346              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
357       The function `tcbdbputdup3' is used in order to store records into a B+
358       tree database object with allowing duplication of keys.
359
360              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
374       The  function  `tcbdbout'  is  used in order to remove a record of a B+
375       tree database object.
376
377              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
387       The  function `tcbdbout2' is used in order to remove a string record of
388       a B+ tree database object.
389
390              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
399       The  function  `tcbdbout3'  is  used in order to remove records of a B+
400       tree database object.
401
402              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
412       The  function  `tcbdbget' is used in order to retrieve a record in a B+
413       tree database object.
414
415              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
432       The  function  `tcbdbget2' is used in order to retrieve a string record
433       in a B+ tree database object.
434
435              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
447       The function `tcbdbget3' is used in order to retrieve a record in a  B+
448       tree database object as a volatile buffer.
449
450              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
469       The function `tcbdbget4' is used in order to retrieve records in  a  B+
470       tree database object.
471
472              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
483       The  function `tcbdbvnum' is used in order to get the number of records
484       corresponding a key in a B+ tree database object.
485
486              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
493       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
496              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
502       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
505              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
514       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
517              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
525       The  function  `tcbdbrange'  is  used  in  order  to get keys of ranged
526       records in a B+ tree database object.
527
528              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
554       The function `tcbdbrange2' is used in  order  to  get  string  keys  of
555       ranged records in a B+ tree database object.
556
557              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
577       The  function  `tcbdbfwmkeys'  is used in order to get forward matching
578       keys in a B+ tree database object.
579
580              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
594       The function `tcbdbfwmkeys2' is used in order to get  forward  matching
595       string keys in a B+ tree database object.
596
597              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
609       The function `tcbdbaddint' is used in order to  add  an  integer  to  a
610       record in a B+ tree database object.
611
612              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
625       The function `tcbdbadddouble' is used in order to add a real number  to
626       a record in a B+ tree database object.
627
628              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
641       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
644              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
652       The function `tcbdboptimize' is used in order to optimize the file of a
653       B+ tree database object.
654
655              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
688       The  function `tcbdbvanish' is used in order to remove all records of a
689       B+ tree database object.
690
691              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
697       The function `tcbdbcopy' is used in order to copy the database file  of
698       a B+ tree database object.
699
700              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
713       The function `tcbdbtranbegin' is used in order to begin the transaction
714       of a B+ tree database object.
715
716              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
731       The  function `tcbdbtrancommit' is used in order to commit the transac‐
732       tion of a B+ tree database object.
733
734              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
742       The function `tcbdbtranabort' is used in order to abort the transaction
743       of a B+ tree database object.
744
745              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
754       The function `tcbdbpath' is used in order to get the file path of a  B+
755       tree database object.
756
757              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
763       The  function `tcbdbrnum' is used in order to get the number of records
764       of a B+ tree database object.
765
766              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
771       The  function `tcbdbfsiz' is used in order to get the size of the data‐
772       base file of a B+ tree database object.
773
774              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
779       The function `tcbdbcurnew' is used in order to create a cursor object.
780
781              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
790       The function `tcbdbcurdel' is used in order to delete a cursor object.
791
792              void tcbdbcurdel(BDBCUR *cur);
793                     `cur' specifies the cursor object.
794
795       The  function  `tcbdbcurfirst' is used in order to move a cursor object
796       to the first record.
797
798              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
804       The function `tcbdbcurlast' is used in order to move a cursor object to
805       the last record.
806
807              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
813       The function `tcbdbcurjump' is used in order to move a cursor object to
814       the front of records corresponding a key.
815
816              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
827       The function `tcbdbcurjump2' is used in order to move a  cursor  object
828       to the front of records corresponding a key string.
829
830              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
840       The function `tcbdbcurprev' is used in order to move a cursor object to
841       the previous record.
842
843              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
848       The function `tcbdbcurnext' is used in order to move a cursor object to
849       the next record.
850
851              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
856       The function `tcbdbcurput' is used in order to insert a record around a
857       cursor object.
858
859              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
876       The  function `tcbdbcurput2' is used in order to insert a string record
877       around a cursor object.
878
879              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
894       The function `tcbdbcurout' is used in order to remove the record  where
895       a cursor object is.
896
897              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
905       The function `tcbdbcurkey' is used in order  to  get  the  key  of  the
906       record where the cursor object is.
907
908              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
922       The  function  `tcbdbcurkey2' is used in order to get the key string of
923       the record where the cursor object is.
924
925              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
934       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
937              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
951       The  function  `tcbdbcurval'  is  used in order to get the value of the
952       record where the cursor object is.
953
954              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
968       The function `tcbdbcurval2' is used in order to get the value string of
969       the record where the cursor object is.
970
971              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
980       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
983              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
997       The function `tcbdbcurrec' is used in order to  get  the  key  and  the
998       value of the record where the cursor object is.
999
1000              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
1010

SEE ALSO

1012       tcbtest(1), tcbmttest(1), tcbmgr(1), tokyocabinet(3)
1013
1014
1015
1016Man Page                          2009-09-04                          TCBDB(3)
Impressum