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

NAME

6       tctdb - the table database API
7
8

DESCRIPTION

10       Table  database  is  a  file containing records composed of the primary
11       keys and arbitrary columns and is handled with the table database API.
12
13       To use the table  database  API,  include  `tcutil.h',  `tctdb.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 <tctdb.h>
19              #include <stdlib.h>
20              #include <stdbool.h>
21              #include <stdint.h>
22
23       Objects whose type is pointer to `TCTDB' are used to handle table data‐
24       bases.  A table database object is created with the function `tctdbnew'
25       and is deleted with the function `tctdbdel'.  To avoid memory leak,  it
26       is important to delete every object when it is no longer in use.
27
28       Before operations to store or retrieve records, it is necessary to open
29       a database file and connect the table database object to it.  The func‐
30       tion `tctdbopen' is used to open a database file and the function `tct‐
31       dbclose' is used to close the database file.  To avoid data missing  or
32       corruption,  it is important to close every database file when it is no
33       longer in use.  It is forbidden for  multible  database  objects  in  a
34       process to open the same database at the same time.
35
36

API

38       The  function  `tctdberrmsg' is used in order to get the message string
39       corresponding to an error code.
40
41              const char *tctdberrmsg(int ecode);
42                     `ecode' specifies the error code.
43                     The return value is the message string of the error code.
44
45       The function `tctdbnew' is used in order to  create  a  table  database
46       object.
47
48              TCTDB *tctdbnew(void);
49                     The return value is the new table database object.
50
51       The  function  `tctdbdel'  is  used in order to delete a table database
52       object.
53
54              void tctdbdel(TCTDB *tdb);
55                     `tdb' specifies the table database object.
56                     If the database is not closed, it is  closed  implicitly.
57                     Note  that the deleted object and its derivatives can not
58                     be used anymore.
59
60       The function `tctdbecode' is used in order to  get  the  last  happened
61       error code of a table database object.
62
63              int tctdbecode(TCTDB *tdb);
64                     `tdb' specifies the table database object.
65                     The return value is the last happened error code.
66                     The  following  error codes are defined: `TCESUCCESS' for
67                     success, `TCETHREAD' for  threading  error,  `TCEINVALID'
68                     for  invalid  operation,  `TCENOFILE' for file not found,
69                     `TCENOPERM' for no permission, `TCEMETA' for invalid meta
70                     data, `TCERHEAD' for invalid record header, `TCEOPEN' for
71                     open error, `TCECLOSE' for close  error,  `TCETRUNC'  for
72                     trunc error, `TCESYNC' for sync error, `TCESTAT' for stat
73                     error, `TCESEEK'  for  seek  error,  `TCEREAD'  for  read
74                     error,  `TCEWRITE'  for  write  error, `TCEMMAP' for mmap
75                     error, `TCELOCK' for lock error, `TCEUNLINK'  for  unlink
76                     error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir
77                     error, `TCERMDIR' for rmdir error, `TCEKEEP' for existing
78                     record, `TCENOREC' for no record found, and `TCEMISC' for
79                     miscellaneous error.
80
81       The function `tctdbsetmutex' is used in order to set  mutual  exclusion
82       control of a table database object for threading.
83
84              bool tctdbsetmutex(TCTDB *tdb);
85                     `tdb'  specifies  the  table database object which is not
86                     opened.
87                     If successful, the return value  is  true,  else,  it  is
88                     false.
89                     Note  that  the mutual exclusion control is needed if the
90                     object is shared by  plural  threads  and  this  function
91                     should be called before the database is opened.
92
93       The  function `tctdbtune' is used in order to set the tuning parameters
94       of a table database object.
95
96              bool tctdbtune(TCTDB *tdb, int64_t  bnum,  int8_t  apow,  int8_t
97              fpow, uint8_t opts);
98                     `tdb'  specifies  the  table database object which is not
99                     opened.
100                     `bnum' specifies the number of  elements  of  the  bucket
101                     array.   If  it  is not more than 0, the default value is
102                     specified.  The default value is 131071.  Suggested  size
103                     of  the  bucket array is about from 0.5 to 4 times of the
104                     number of all records to be stored.
105                     `apow' specifies the size of record alignment by power of
106                     2.   If  it  is negative, the default value is specified.
107                     The default value is 4 standing for 2^4=16.
108                     `fpow' specifies the maximum number of  elements  of  the
109                     free  block  pool  by power of 2.  If it is negative, the
110                     default value is specified.   The  default  value  is  10
111                     standing for 2^10=1024.
112                     `opts' specifies options by bitwise-or: `TDBTLARGE' spec‐
113                     ifies that the size of the database can  be  larger  than
114                     2GB by using 64-bit bucket array, `TDBTDEFLATE' specifies
115                     that each record is  compressed  with  Deflate  encoding,
116                     `TDBTBZIP'  specifies that each record is compressed with
117                     BZIP2 encoding, `TDBTTCBS' specifies that each record  is
118                     compressed with TCBS encoding.
119                     If  successful,  the  return  value  is true, else, it is
120                     false.
121                     Note that the tuning parameters should be set before  the
122                     database is opened.
123
124       The  function  `tctdbsetcache' is set the caching parameters of a table
125       database object.
126
127              bool tctdbsetcache(TCTDB *tdb,  int32_t  rcnum,  int32_t  lcnum,
128              int32_t ncnum);
129                     `tdb'  specifies  the  table database object which is not
130                     opened.
131                     `rcnum' specifies the maximum number  of  records  to  be
132                     cached.   If  it  is not more than 0, the record cache is
133                     disabled.  It is disabled by default.
134                     `lcnum' specifies the maximum number of leaf nodes to  be
135                     cached.   If  it is not more than 0, the default value is
136                     specified.  The default value is 4096.
137                     `ncnum' specifies the maximum number of non-leaf nodes to
138                     be  cached.   If it is not more than 0, the default value
139                     is specified.  The default value is 512.
140                     If successful, the return value  is  true,  else,  it  is
141                     false.
142                     Note that the caching parameters should be set before the
143                     database is opened.  Leaf nodes and  non-leaf  nodes  are
144                     used in column indices.
145
146       The  function  `tctdbsetxmsiz'  is used in order to set the size of the
147       extra mapped memory of a table database object.
148
149              bool tctdbsetxmsiz(TCTDB *tdb, int64_t xmsiz);
150                     `tdb' specifies the table database object  which  is  not
151                     opened.
152                     `xmsiz'  specifies  the  size of the extra mapped memory.
153                     If it is not more than 0, the extra mapped memory is dis‐
154                     abled.  The default size is 67108864.
155                     If  successful,  the  return  value  is true, else, it is
156                     false.
157                     Note that the mapping parameters should be set before the
158                     database is opened.
159
160       The  function  `tctdbsetdfunit'  is  used in order to set the unit step
161       number of auto defragmentation of a table database object.
162
163              bool tctdbsetdfunit(TCTDB *tdb, int32_t dfunit);
164                     `tdb' specifies the table database object  which  is  not
165                     opened.
166                     `dfunit'  specifie  the  unit  step number.  If it is not
167                     more than 0, the auto defragmentation is disabled.  It is
168                     disabled by default.
169                     If  successful,  the  return  value  is true, else, it is
170                     false.
171                     Note that the defragmentation parameters  should  be  set
172                     before the database is opened.
173
174       The  function  `tctdbopen' is used in order to open a database file and
175       connect a table database object.
176
177              bool tctdbopen(TCTDB *tdb, const char *path, int omode);
178                     `tdb' specifies the table database object  which  is  not
179                     opened.
180                     `path' specifies the path of the database file.
181                     `omode'  specifies the connection mode: `TDBOWRITER' as a
182                     writer,  `TDBOREADER'  as  a  reader.   If  the  mode  is
183                     `TDBOWRITER',  the  following may be added by bitwise-or:
184                     `TDBOCREAT', which means it creates a new database if not
185                     exist, `TDBOTRUNC', which means it creates a new database
186                     regardless if one exists, `TDBOTSYNC', which means  every
187                     transaction   synchronizes   updated  contents  with  the
188                     device.  Both of `TDBOREADER'  and  `TDBOWRITER'  can  be
189                     added to by bitwise-or: `TDBONOLCK', which means it opens
190                     the database file without file locking,  or  `TDBOLCKNB',
191                     which means locking is performed without blocking.
192                     If  successful,  the  return  value  is true, else, it is
193                     false.
194
195       The function `tctdbclose' is used in order to close  a  table  database
196       object.
197
198              bool tctdbclose(TCTDB *tdb);
199                     `tdb' specifies the table database object.
200                     If  successful,  the  return  value  is true, else, it is
201                     false.
202                     Update of a database is assured to be  written  when  the
203                     database  is  closed.   If  a writer opens a database but
204                     does not close it appropriately,  the  database  will  be
205                     broken.
206
207       The function `tctdbput' is used in order to store a record into a table
208       database object.
209
210              bool tctdbput(TCTDB *tdb, const void *pkbuf,  int  pksiz,  TCMAP
211              *cols);
212                     `tdb'  specifies the table database object connected as a
213                     writer.
214                     `pkbuf' specifies the pointer to the region of  the  pri‐
215                     mary key.
216                     `pksiz'  specifies  the size of the region of the primary
217                     key.
218                     `cols' specifies a map object containing columns.
219                     If successful, the return value  is  true,  else,  it  is
220                     false.
221                     If  a record with the same key exists in the database, it
222                     is overwritten.
223
224       The function `tctdbput2' is used in order to store a string record into
225       a table database object with a zero separated column string.
226
227              bool  tctdbput2(TCTDB  *tdb, const void *pkbuf, int pksiz, const
228              void *cbuf, int csiz);
229                     `tdb' specifies the table database object connected as  a
230                     writer.
231                     `pkbuf'  specifies  the pointer to the region of the pri‐
232                     mary key.
233                     `pksiz' specifies the size of the region of  the  primary
234                     key.
235                     `cbuf'  specifies  the  pointer to the region of the zero
236                     separated column string where the name and the  value  of
237                     each column are situated one after the other.
238                     `csiz'  specifies  the  size  of the region of the column
239                     string.
240                     If successful, the return value  is  true,  else,  it  is
241                     false.
242                     If  a record with the same key exists in the database, it
243                     is overwritten.
244
245       The function `tctdbput3' is used in order to store a string record into
246       a table database object with a tab separated column string.
247
248              bool tctdbput3(TCTDB *tdb, const char *pkstr, const char *cstr);
249                     `tdb'  specifies the table database object connected as a
250                     writer.
251                     `pkstr' specifies the string of the primary key.
252                     `cstr' specifies the string of the the tab separated col‐
253                     umn  string  where  the name and the value of each column
254                     are situated one after the other.
255                     If successful, the return value  is  true,  else,  it  is
256                     false.
257                     If  a record with the same key exists in the database, it
258                     is overwritten.
259
260       The function `tctdbputkeep' is used in order to store a new record into
261       a table database object.
262
263              bool  tctdbputkeep(TCTDB  *tdb,  const  void  *pkbuf, int pksiz,
264              TCMAP *cols);
265                     `tdb' specifies the table database object connected as  a
266                     writer.
267                     `pkbuf'  specifies  the pointer to the region of the pri‐
268                     mary key.
269                     `pksiz' specifies the size of the region of  the  primary
270                     key.
271                     `cols' specifies a map object containing columns.
272                     If  successful,  the  return  value  is true, else, it is
273                     false.
274                     If a record with the same key  exists  in  the  database,
275                     this function has no effect.
276
277       The  function  `tctdbputkeep2'  is  used in order to store a new string
278       record into a table  database  object  with  a  zero  separated  column
279       string.
280
281              bool  tctdbputkeep2(TCTDB  *tdb,  const  void *pkbuf, int pksiz,
282              const void *cbuf, int csiz);
283                     `tdb' specifies the table database object connected as  a
284                     writer.
285                     `pkbuf'  specifies  the pointer to the region of the pri‐
286                     mary key.
287                     `pksiz' specifies the size of the region of  the  primary
288                     key.
289                     `cbuf'  specifies  the  pointer to the region of the zero
290                     separated column string where the name and the  value  of
291                     each column are situated one after the other.
292                     `csiz'  specifies  the  size  of the region of the column
293                     string.
294                     If successful, the return value  is  true,  else,  it  is
295                     false.
296                     If  a  record  with  the same key exists in the database,
297                     this function has no effect.
298
299       The function `tctdbputkeep3' is used in order to  store  a  new  string
300       record into a table database object with a tab separated column string.
301
302              bool  tctdbputkeep3(TCTDB  *tdb,  const  char *pkstr, const char
303              *cstr);
304                     `tdb' specifies the table database object connected as  a
305                     writer.
306                     `pkstr' specifies the string of the primary key.
307                     `cstr' specifies the string of the the tab separated col‐
308                     umn string where the name and the value  of  each  column
309                     are situated one after the other.
310                     If  successful,  the  return  value  is true, else, it is
311                     false.
312                     If a record with the same key  exists  in  the  database,
313                     this function has no effect.
314
315       The  function  `tctdbputcat' is used in order to concatenate columns of
316       the existing record in a table database object.
317
318              bool tctdbputcat(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP
319              *cols);
320                     `tdb'  specifies the table database object connected as a
321                     writer.
322                     `pkbuf' specifies the pointer to the region of  the  pri‐
323                     mary key.
324                     `pksiz'  specifies  the size of the region of the primary
325                     key.
326                     `cols' specifies a map object containing columns.
327                     If successful, the return value  is  true,  else,  it  is
328                     false.
329                     If there is no corresponding record, a new record is cre‐
330                     ated.
331
332       The function `tctdbputcat2' is used in order to concatenate columns  in
333       a table database object with a zero separated column string.
334
335              bool  tctdbputcat2(TCTDB  *tdb,  const  void  *pkbuf, int pksiz,
336              const void *cbuf, int csiz);
337                     `tdb' specifies the table database object connected as  a
338                     writer.
339                     `pkbuf'  specifies  the pointer to the region of the pri‐
340                     mary key.
341                     `pksiz' specifies the size of the region of  the  primary
342                     key.
343                     `cbuf'  specifies  the  pointer to the region of the zero
344                     separated column string where the name and the  value  of
345                     each column are situated one after the other.
346                     `csiz'  specifies  the  size  of the region of the column
347                     string.
348                     If successful, the return value  is  true,  else,  it  is
349                     false.
350                     If there is no corresponding record, a new record is cre‐
351                     ated.
352
353       The function `tctdbputcat3' is used in order to concatenate columns  in
354       a table database object with with a tab separated column string.
355
356              bool  tctdbputcat3(TCTDB  *tdb,  const  char  *pkstr, const char
357              *cstr);
358                     `tdb' specifies the table database object connected as  a
359                     writer.
360                     `pkstr' specifies the string of the primary key.
361                     `cstr' specifies the string of the the tab separated col‐
362                     umn string where the name and the value  of  each  column
363                     are situated one after the other.
364                     If  successful,  the  return  value  is true, else, it is
365                     false.
366                     If there is no corresponding record, a new record is cre‐
367                     ated.
368
369       The  function `tctdbout' is used in order to remove a record of a table
370       database object.
371
372              bool tctdbout(TCTDB *tdb, const void *pkbuf, int pksiz);
373                     `tdb' specifies the table database object connected as  a
374                     writer.
375                     `pkbuf'  specifies  the pointer to the region of the pri‐
376                     mary key.
377                     `pksiz' specifies the size of the region of  the  primary
378                     key.
379                     If  successful,  the  return  value  is true, else, it is
380                     false.
381
382       The function `tctdbout2' is used in order to remove a string record  of
383       a table database object.
384
385              bool tctdbout2(TCTDB *tdb, const char *pkstr);
386                     `tdb'  specifies the table database object connected as a
387                     writer.
388                     `pkstr' specifies the string of the primary key.
389                     If successful, the return value  is  true,  else,  it  is
390                     false.
391
392       The  function `tctdbget' is used in order to retrieve a record in a ta‐
393       ble database object.
394
395              TCMAP *tctdbget(TCTDB *tdb, const void *pkbuf, int pksiz);
396                     `tdb' specifies the table database object.
397                     `pkbuf' specifies the pointer to the region of  the  pri‐
398                     mary key.
399                     `pksiz'  specifies  the size of the region of the primary
400                     key.
401                     If successful, the return value is a map  object  of  the
402                     columns  of the corresponding record.  `NULL' is returned
403                     if no record corresponds.
404                     Because the object of the return value  is  created  with
405                     the  function  `tcmapnew',  it should be deleted with the
406                     function `tcmapdel' when it is no longer in use.
407
408       The function `tctdbget2' is used in order to retrieve a record in a ta‐
409       ble database object as a zero separated column string.
410
411              char  *tctdbget2(TCTDB  *tdb,  const void *pkbuf, int pksiz, int
412              *sp);
413                     `tdb' specifies the table database object.
414                     `pkbuf' specifies the pointer to the region of  the  pri‐
415                     mary key.
416                     `pksiz'  specifies  the size of the region of the primary
417                     key.
418                     `sp' specifies the pointer to the variable into which the
419                     size of the region of the return value is assigned.
420                     If  successful,  the  return  value is the pointer to the
421                     region of the column string of the corresponding  record.
422                     `NULL' is returned if no record corresponds.
423                     Because an additional zero code is appended at the end of
424                     the region of the return value, the return value  can  be
425                     treated as a character string.  Because the region of the
426                     return value is allocated  with  the  `malloc'  call,  it
427                     should  be  released  with  the `free' call when it is no
428                     longer in use.
429
430       The function `tctdbget3' is used in order to retrieve a  string  record
431       in a table database object as a tab separated column string.
432
433              char *tctdbget3(TCTDB *tdb, const char *pkstr);
434                     `tdb' specifies the table database object.
435                     `pkstr' specifies the string of the primary key.
436                     If successful, the return value is the tab separated col‐
437                     umn  string  of  the  corresponding  record.   `NULL'  is
438                     returned if no record corresponds.
439                     Because  the region of the return value is allocated with
440                     the `malloc' call, it should be released with the  `free'
441                     call when it is no longer in use.
442
443       The  function `tctdbvsiz' is used in order to get the size of the value
444       of a record in a table database object.
445
446              int tctdbvsiz(TCTDB *tdb, const void *pkbuf, int pksiz);
447                     `tdb' specifies the table database object.
448                     `kbuf' specifies the pointer to the region of the primary
449                     key.
450                     `ksiz'  specifies  the  size of the region of the primary
451                     key.
452                     If successful, the return value is the size of the  value
453                     of the corresponding record, else, it is -1.
454
455       The function `tctdbvsiz2' is used in order to get the size of the value
456       of a string record in a table database object.
457
458              int tctdbvsiz2(TCTDB *tdb, const char *pkstr);
459                     `tdb' specifies the table database object.
460                     `kstr' specifies the string of the primary key.
461                     If successful, the return value is the size of the  value
462                     of the corresponding record, else, it is -1.
463
464       The  function `tctdbiterinit' is used in order to initialize the itera‐
465       tor of a table database object.
466
467              bool tctdbiterinit(TCTDB *tdb);
468                     `tdb' specifies the table database object.
469                     If successful, the return value  is  true,  else,  it  is
470                     false.
471                     The  iterator  is used in order to access the primary key
472                     of every record stored in a database.
473
474       The function `tctdbiternext' is used in order to get the  next  primary
475       key of the iterator of a table database object.
476
477              void *tctdbiternext(TCTDB *tdb, int *sp);
478                     `tdb' specifies the table database object.
479                     `sp' specifies the pointer to the variable into which the
480                     size of the region of the return value is assigned.
481                     If successful, the return value is  the  pointer  to  the
482                     region  of  the  next  primary  key,  else, it is `NULL'.
483                     `NULL' is returned when no record is to be get out of the
484                     iterator.
485                     Because an additional zero code is appended at the end of
486                     the region of the return value, the return value  can  be
487                     treated as a character string.  Because the region of the
488                     return value is allocated  with  the  `malloc'  call,  it
489                     should  be  released  with  the `free' call when it is no
490                     longer in use.  It is possible to access every record  by
491                     iteration  of  calling  this  function.  It is allowed to
492                     update or remove records whose keys are fetched while the
493                     iteration.   However,  it  is not assured if updating the
494                     database is occurred while the iteration.   Besides,  the
495                     order of this traversal access method is arbitrary, so it
496                     is not assured that the order of storing matches the  one
497                     of the traversal access.
498
499       The  function `tctdbiternext2' is used in order to get the next primary
500       key string of the iterator of a table database object.
501
502              char *tctdbiternext2(TCTDB *tdb);
503                     `tdb' specifies the table database object.
504                     If successful, the return value is the string of the next
505                     primary key, else, it is `NULL'.  `NULL' is returned when
506                     no record is to be get out of the iterator.
507                     Because the region of the return value is allocated  with
508                     the  `malloc' call, it should be released with the `free'
509                     call when it is no longer in  use.   It  is  possible  to
510                     access  every  record  by iteration of calling this func‐
511                     tion.  However, it is not assured if updating  the  data‐
512                     base is occurred while the iteration.  Besides, the order
513                     of this traversal access method is arbitrary,  so  it  is
514                     not  assured that the order of storing matches the one of
515                     the traversal access.
516
517       The function `tctdbiternext3' is used in order to get  the  columns  of
518       the next record of the iterator of a table database object.
519
520              TCMAP *tctdbiternext3(TCTDB *tdb);
521                     `tdb' specifies the table database object.
522                     If  successful,  the  return value is a map object of the
523                     columns of the next record, else, it is  `NULL'.   `NULL'
524                     is returned when no record is to be get out of the itera‐
525                     tor.  The primary key is added into the map as  a  column
526                     of an empty string key.
527                     Because  the  object  of the return value is created with
528                     the function `tcmapnew', it should be  deleted  with  the
529                     function  `tcmapdel'  when it is no longer in use.  It is
530                     possible to access every record by iteration  of  calling
531                     this  function.   However,  it is not assured if updating
532                     the database is occurred while the  iteration.   Besides,
533                     the  order  of this traversal access method is arbitrary,
534                     so it is not assured that the order  of  storing  matches
535                     the one of the traversal access.
536
537       The  function  `tctdbfwmkeys'  is used in order to get forward matching
538       primary keys in a table database object.
539
540              TCLIST *tctdbfwmkeys(TCTDB *tdb, const void *pbuf, int psiz, int
541              max);
542                     `tdb' specifies the table database object.
543                     `pbuf' specifies the pointer to the region of the prefix.
544                     `psiz' specifies the size of the region of the prefix.
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  corresponding
548                     keys.   This  function  does  never  fail.  It returns an
549                     empty list even if no key 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.   Note
553                     that  this function may be very slow because every key in
554                     the database is scanned.
555
556       The function `tctdbfwmkeys2' is used in order to get  forward  matching
557       string primary keys in a table database object.
558
559              TCLIST *tctdbfwmkeys2(TCTDB *tdb, const char *pstr, int max);
560                     `tdb' specifies the table database object.
561                     `pstr' specifies the string of the prefix.
562                     `max' specifies the maximum number of keys to be fetched.
563                     If it is negative, no limit is specified.
564                     The return value is a list object  of  the  corresponding
565                     keys.   This  function  does  never  fail.  It returns an
566                     empty list even if no key corresponds.
567                     Because the object of the return value  is  created  with
568                     the  function  `tclistnew', it should be deleted with the
569                     function `tclistdel' when it is no longer in  use.   Note
570                     that  this function may be very slow because every key in
571                     the database is scanned.
572
573       The function `tctdbaddint' is used in order to add an integer to a col‐
574       umn of a record in a table database object.
575
576              int  tctdbaddint(TCTDB  *tdb,  const void *pkbuf, int pksiz, int
577              num);
578                     `tdb' specifies the table database object connected as  a
579                     writer.
580                     `kbuf' specifies the pointer to the region of the primary
581                     key.
582                     `ksiz' specifies the size of the region  of  the  primary
583                     key.
584                     `num' specifies the additional value.
585                     If  successful,  the return value is the summation value,
586                     else, it is `INT_MIN'.
587                     The additional value is stored as a decimal string  value
588                     of  a  column  whose name is "_num".  If no record corre‐
589                     sponds, a new record with the additional value is stored.
590
591       The function `tctdbadddouble' is used in order to add a real number  to
592       a column of a record in a table database object.
593
594              double  tctdbadddouble(TCTDB *tdb, const void *pkbuf, int pksiz,
595              double num);
596                     `tdb' specifies the table database object connected as  a
597                     writer.
598                     `kbuf' specifies the pointer to the region of the primary
599                     key.
600                     `ksiz' specifies the size of the region  of  the  primary
601                     key.
602                     `num' specifies the additional value.
603                     If  successful,  the return value is the summation value,
604                     else, it is Not-a-Number.
605                     The additional value is stored as a decimal string  value
606                     of  a  column  whose name is "_num".  If no record corre‐
607                     sponds, a new record with the additional value is stored.
608
609       The function `tctdbsync' is used in order to synchronize  updated  con‐
610       tents of a table database object with the file and the device.
611
612              bool tctdbsync(TCTDB *tdb);
613                     `tdb'  specifies the table database object connected as a
614                     writer.
615                     If successful, the return value  is  true,  else,  it  is
616                     false.
617                     This  function is useful when another process connects to
618                     the same database file.
619
620       The function `tctdboptimize' is used in order to optimize the file of a
621       table database object.
622
623              bool tctdboptimize(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t
624              fpow, uint8_t opts);
625                     `tdb' specifies the table database object connected as  a
626                     writer.
627                     `bnum'  specifies  the  number  of elements of the bucket
628                     array.  If it is not more than 0, the  default  value  is
629                     specified.   The default value is two times of the number
630                     of records.
631                     `apow' specifies the size of record alignment by power of
632                     2.   If  it  is  negative,  the  current  setting  is not
633                     changed.
634                     `fpow' specifies the maximum number of  elements  of  the
635                     free  block  pool  by power of 2.  If it is negative, the
636                     current setting is not changed.
637                     `opts' specifies options by bitwise-or: `TDBTLARGE' spec‐
638                     ifies  that  the  size of the database can be larger than
639                     2GB by using 64-bit bucket array, `TDBTDEFLATE' specifies
640                     that  each  record  is  compressed with Deflate encoding,
641                     `TDBTBZIP' specifies that each record is compressed  with
642                     BZIP2  encoding, `TDBTTCBS' specifies that each record is
643                     compressed with TCBS encoding.  If it is `UINT8_MAX', the
644                     current setting is not changed.
645                     If  successful,  the  return  value  is true, else, it is
646                     false.
647                     This function is useful to reduce the size of  the  data‐
648                     base file with data fragmentation by successive updating.
649
650       The  function `tctdbvanish' is used in order to remove all records of a
651       table database object.
652
653              bool tctdbvanish(TCTDB *tdb);
654                     `tdb' specifies the table database object connected as  a
655                     writer.
656                     If  successful,  the  return  value  is true, else, it is
657                     false.
658
659       The function `tctdbcopy' is used in order to copy the database file  of
660       a table database object.
661
662              bool tctdbcopy(TCTDB *tdb, const char *path);
663                     `tdb' specifies the table database object.
664                     `path' specifies the path of the destination file.  If it
665                     begins with `@', the trailing substring is executed as  a
666                     command line.
667                     If  successful,  the  return  value  is true, else, it is
668                     false.  False is returned if the executed command returns
669                     non-zero code.
670                     The  database file is assured to be kept synchronized and
671                     not modified while the copying or executing operation  is
672                     in  progress.   So,  this  function is useful to create a
673                     backup file of the database file.
674
675       The function `tctdbtranbegin' is used in order to begin the transaction
676       of a table database object.
677
678              bool tctdbtranbegin(TCTDB *tdb);
679                     `tdb'  specifies the table database object connected as a
680                     writer.
681                     If successful, the return value  is  true,  else,  it  is
682                     false.
683                     The  database  is locked by the thread while the transac‐
684                     tion so that only one transaction can be activated with a
685                     database object at the same time.  Thus, the serializable
686                     isolation level is assumed if every database operation is
687                     performed  in  the  transaction.   Because  all pages are
688                     cached on memory while the  transaction,  the  amount  of
689                     referred  records  is limited by the memory capacity.  If
690                     the database is closed during transaction,  the  transac‐
691                     tion is aborted implicitly.
692
693       The  function `tctdbtrancommit' is used in order to commit the transac‐
694       tion of a table database object.
695
696              bool tctdbtrancommit(TCTDB *tdb);
697                     `tdb' specifies the table database object connected as  a
698                     writer.
699                     If  successful,  the  return  value  is true, else, it is
700                     false.
701                     Update in the transaction is fixed when it  is  committed
702                     successfully.
703
704       The function `tctdbtranabort' is used in order to abort the transaction
705       of a table database object.
706
707              bool tctdbtranabort(TCTDB *tdb);
708                     `tdb' specifies the table database object connected as  a
709                     writer.
710                     If  successful,  the  return  value  is true, else, it is
711                     false.
712                     Update  in  the  transaction  is  discarded  when  it  is
713                     aborted.   The  state  of  the  database is rollbacked to
714                     before transaction.
715
716       The function `tctdbpath' is used in order to get the file path of a ta‐
717       ble database object.
718
719              const char *tctdbpath(TCTDB *tdb);
720                     `tdb' specifies the table database object.
721                     The  return  value  is  the  path of the database file or
722                     `NULL' if the object does not  connect  to  any  database
723                     file.
724
725       The  function `tctdbrnum' is used in order to get the number of records
726       ccccof a table database object.
727
728              uint64_t tctdbrnum(TCTDB *tdb);
729                     `tdb' specifies the table database object.
730                     The return value is the number of records  or  0  if  the
731                     object does not connect to any database file.
732
733       The  function `tctdbfsiz' is used in order to get the size of the data‐
734       base file of a table database object.
735
736              uint64_t tctdbfsiz(TCTDB *tdb);
737                     `tdb' specifies the table database object.
738                     The return value is the size of the database file or 0 if
739                     the object does not connect to any database file.
740
741       The  function `tctdbsetindex' is used in order to set a column index to
742       a table database object.
743
744              bool tctdbsetindex(TCTDB *tdb, const char *name, int type);
745                     `tdb' specifies the table database object connected as  a
746                     writer.
747                     `name' specifies the name of a column.  If the name of an
748                     existing index is specified, the index  is  rebuilt.   An
749                     empty string means the primary key.
750                     `type' specifies the index type: `TDBITLEXICAL' for lexi‐
751                     cal string, `TDBITDECIMAL' for decimal string,  `TDBITTO‐
752                     KEN'  for  token  inverted index, `TDBITQGRAM' for q-gram
753                     inverted index.  If it is `TDBITOPT', the index is  opti‐
754                     mized.   If  it is `TDBITVOID', the index is removed.  If
755                     `TDBITKEEP' is added by bitwise-or and the index  exists,
756                     this function merely returns failure.
757                     If  successful,  the  return  value  is true, else, it is
758                     false.
759                     Note that the setting indices should  be  set  after  the
760                     database is opened.
761
762       The  function  `tctdbgenuid'  is  used in order to generate a unique ID
763       number of a table database object.
764
765              int64_t tctdbgenuid(TCTDB *tdb);
766                     `tdb' specifies the table database object connected as  a
767                     writer.
768                     The  return  value  is  the new unique ID number or -1 on
769                     failure.
770
771       The function `tctdbqrynew' is used in order to create a query object.
772
773              TDBQRY *tctdbqrynew(TCTDB *tdb);
774                     `tdb' specifies the table database object.
775                     The return value is the new query object.
776
777       The function `tctdbqrydel' is used in order to delete a query object.
778
779              void tctdbqrydel(TDBQRY *qry);
780                     `qry' specifies the query object.
781
782       The function `tctdbqryaddcond' is used in order to add a narrowing con‐
783       dition to a query object.
784
785              void  tctdbqryaddcond(TDBQRY  *qry,  const  char  *name, int op,
786              const char *expr);
787                     `qry' specifies the query object.
788                     `name' specifies the name of a column.  An  empty  string
789                     means the primary key.
790                     `op' specifies an operation type: `TDBQCSTREQ' for string
791                     which is  equal  to  the  expression,  `TDBQCSTRINC'  for
792                     string  which is included in the expression, `TDBQCSTRBW'
793                     for string which begins with the expression, `TDBQCSTREW'
794                     for  string which ends with the expression, `TDBQCSTRAND'
795                     for string which includes all tokens in  the  expression,
796                     `TDBQCSTROR' for string which includes at least one token
797                     in the expression, `TDBQCSTROREQ'  for  string  which  is
798                     equal  to  at  least one token in the expression, `TDBQC‐
799                     STRRX' for string which matches  regular  expressions  of
800                     the expression, `TDBQCNUMEQ' for number which is equal to
801                     the expression, `TDBQCNUMGT' for number which is  greater
802                     than  the  expression,  `TDBQCNUMGE'  for number which is
803                     greater than or equal to the expression, `TDBQCNUMLT' for
804                     number  which  is  less than the expression, `TDBQCNUMLE'
805                     for number which is less than or equal to the expression,
806                     `TDBQCNUMBT'  for  number  which is between two tokens of
807                     the expression, `TDBQCNUMOREQ' for number which is  equal
808                     to at least one token in the expression, `TDBQCFTSPH' for
809                     full-text search  with  the  phrase  of  the  expression,
810                     `TDBQCFTSAND' for full-text search with all tokens in the
811                     expression, `TDBQCFTSOR' for  full-text  search  with  at
812                     least  one  token  in  the  expression,  `TDBQCFTSEX' for
813                     full-text search with the compound expression.  All oper‐
814                     ations  can  be  flagged by bitwise-or: `TDBQCNEGATE' for
815                     negation, `TDBQCNOIDX' for using no index.
816                     `expr' specifies an operand exression.
817
818       The function `tctdbqrysetorder' is used in order to set the order of  a
819       query object.
820
821              void tctdbqrysetorder(TDBQRY *qry, const char *name, int type);
822                     `qry' specifies the query object.
823                     `name'  specifies  the name of a column.  An empty string
824                     means the primary key.
825                     `type' specifies the order type: `TDBQOSTRASC' for string
826                     ascending, `TDBQOSTRDESC' for string descending, `TDBQON‐
827                     UMASC' for number ascending,  `TDBQONUMDESC'  for  number
828                     descending.
829
830       The  function `tctdbqrysetlimit' is used in order to set the limit num‐
831       ber of records of the result of a query object.
832
833              void tctdbqrysetlimit(TDBQRY *qry, int max, int skip);
834                     `qry' specifies the query object.
835                     `max' specifies the maximum  number  of  records  of  the
836                     result.  If it is negative, no limit is specified.
837                     `skip'  specifies  the  number  of skipped records of the
838                     result.  If it is not more than 0, no record is skipped.
839
840       The function `tctdbqrysearch' is used in order to execute the search of
841       a query object.
842
843              TCLIST *tctdbqrysearch(TDBQRY *qry);
844                     `qry' specifies the query object.
845                     The  return value is a list object of the primary keys of
846                     the corresponding  records.   This  function  does  never
847                     fail.   It returns an empty list even if no record corre‐
848                     sponds.
849                     Because the object of the return value  is  created  with
850                     the  function  `tclistnew', it should be deleted with the
851                     function `tclistdel' when it is no longer in use.
852
853       The function `tctdbqrysearchout' is used in order to remove each record
854       corresponding to a query object.
855
856              bool tctdbqrysearchout(TDBQRY *qry);
857                     `qry'  specifies  the  query  object of the database con‐
858                     nected as a writer.
859                     If successful, the return value  is  true,  else,  it  is
860                     false.
861
862       The  function  `tctdbqryproc'  is  used in order to process each record
863       corresponding to a query object.
864
865              bool tctdbqryproc(TDBQRY *qry, TDBQRYPROC proc, void *op);
866                     `qry' specifies the query object  of  the  database  con‐
867                     nected as a writer.
868                     `proc'  specifies  the  pointer  to the iterator function
869                     called for each record.   It  receives  four  parameters.
870                     The  first  parameter is the pointer to the region of the
871                     primary key.  The second parameter is  the  size  of  the
872                     region  of the primary key.  The third parameter is a map
873                     object containing columns.  The fourth parameter  is  the
874                     pointer  to the optional opaque object.  It returns flags
875                     of the post treatment by bitwise-or: `TDBQPPUT' to modify
876                     the  record, `TDBQPOUT' to remove the record, `TDBQPSTOP'
877                     to stop the iteration.
878                     `op' specifies an arbitrary pointer  to  be  given  as  a
879                     parameter of the iterator function.  If it is not needed,
880                     `NULL' can be specified.
881                     If successful, the return value  is  true,  else,  it  is
882                     false.
883
884       The  function `tctdbqryhint' is used in order to get the hint string of
885       a query object.
886
887              const char *tctdbqryhint(TDBQRY *qry);
888                     `qry' specifies the query object.
889                     The return value is the hint string.
890
891       The function `tctdbmetasearch' is used in  order  to  retrieve  records
892       with multiple query objects and get the set of the result.
893
894              TCLIST *tctdbmetasearch(TDBQRY **qrys, int num, int type);
895                     `qrys' specifies an array of the query objects.
896                     `num' specifies the number of elements of the array.
897                     `type'  specifies  a set operation type: `TDBMSUNION' for
898                     the union set, `TDBMSISECT'  for  the  intersection  set,
899                     `TDBMSDIFF' for the difference set.
900                     The  return value is a list object of the primary keys of
901                     the corresponding  records.   This  function  does  never
902                     fail.   It returns an empty list even if no record corre‐
903                     sponds.
904                     If the first query object  has  the  order  setting,  the
905                     result  array is sorted by the order.  Because the object
906                     of the return value is created with the function `tclist‐
907                     new',  it should be deleted with the function `tclistdel'
908                     when it is no longer in use.
909
910

SEE ALSO

912       tcttest(1), tctmttest(1), tctmgr(1), tokyocabinet(3)
913
914
915
916Man Page                          2009-09-04                          TCTDB(3)
Impressum