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

NAME

6       tcadb - the abstract database API
7
8

DESCRIPTION

10       Abstract  database  is  a set of interfaces to use on-memory hash data‐
11       base,  on-memory  tree  database,  hash  database,  B+  tree  database,
12       fixed-length database, and table database with the same API.
13
14       To  use  the  abstract database API, include `tcutil.h', `tcadb.h', and
15       related standard header files.  Usually, write the  following  descrip‐
16       tion near the front of a source file.
17
18              #include <tcutil.h>
19              #include <tcadb.h>
20              #include <stdlib.h>
21              #include <stdbool.h>
22              #include <stdint.h>
23
24       Objects  whose  type  is pointer to `TCADB' are used to handle abstract
25       databases.  An abstract database object is created  with  the  function
26       `tcadbnew'  and is deleted with the function `tcadbdel'.  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 con‐
31       nect the abstract database object to the concrete  one.   The  function
32       `tcadbopen' is used to open a concrete database and the function `tcad‐
33       bclose' is used to close the database.  To avoid data missing  or  cor‐
34       ruption, it is important to close every database instance when it is no
35       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 `tcadbnew' is used in order to create an abstract database
41       object.
42
43              TCADB *tcadbnew(void);
44                     The return value is the new abstract database object.
45
46       The function `tcadbdel' is used in order to delete an abstract database
47       object.
48
49              void tcadbdel(TCADB *adb);
50                     `adb' specifies the abstract database object.
51
52       The function `tcadbopen' is used in order to open an abstract database.
53
54              bool tcadbopen(TCADB *adb, const char *name);
55                     `adb' specifies the abstract database object.
56                     `name' specifies the name of the database.  If it is "*",
57                     the database will be an on-memory hash database.   If  it
58                     is  "+", the database will be an on-memory tree database.
59                     If its suffix is ".tch", the  database  will  be  a  hash
60                     database.   If its suffix is ".tcb", the database will be
61                     a B+ tree database.  If its suffix is ".tcf",  the  data‐
62                     base  will  be a fixed-length database.  If its suffix is
63                     ".tct", the database will be a  table  database.   Other‐
64                     wise,  this  function fails.  Tuning parameters can trail
65                     the name, separated by "#".  Each parameter  is  composed
66                     of  the  name and the value, separated by "=".  On-memory
67                     hash database supports "bnum",  "capnum",  and  "capsiz".
68                     On-memory  tree  database supports "capnum" and "capsiz".
69                     Hash database supports "mode",  "bnum",  "apow",  "fpow",
70                     "opts", "rcnum", "xmsiz", and "dfunit".  B+ tree database
71                     supports  "mode",  "lmemb",  "nmemb",   "bnum",   "apow",
72                     "fpow",  "opts", "lcnum", "ncnum", "xmsiz", and "dfunit".
73                     Fixed-length database supports "mode", "width", and "lim‐
74                     siz".   Table  database  supports "mode", "bnum", "apow",
75                     "fpow", "opts", "rcnum", "lcnum", "ncnum", "xmsiz", "dfu‐
76                     nit", and "idx".
77                     If  successful,  the  return  value  is true, else, it is
78                     false.
79                     The tuning parameter "capnum" specifies the capacity num‐
80                     ber  of records.  "capsiz" specifies the capacity size of
81                     using memory.  Records spilled the capacity  are  removed
82                     by  the storing order.  "mode" can contain "w" of writer,
83                     "r" of reader, "c" of creating, "t" of truncating, "e" of
84                     no  locking,  and  "f" of non-blocking lock.  The default
85                     mode is relevant to "wc".  "opts"  can  contains  "l"  of
86                     large option, "d" of Deflate option, "b" of BZIP2 option,
87                     and "t" of TCBS option.  "idx" specifies the column  name
88                     of  an index and its type separated by ":".  For example,
89                     "casket.tch#bnum=1000000#opts=ld" means that the name  of
90                     the  database file is "casket.tch", and the bucket number
91                     is 1000000, and the options are large and Deflate.
92
93       The function `tcadbclose' is used in order to close an  abstract  data‐
94       base object.
95
96              bool tcadbclose(TCADB *adb);
97                     `adb' specifies the abstract database object.
98                     If  successful,  the  return  value  is true, else, it is
99                     false.
100                     Update of a database is assured to be  written  when  the
101                     database  is  closed.   If  a writer opens a database but
102                     does not close it appropriately,  the  database  will  be
103                     broken.
104
105       The  function  `tcadbput'  is  used  in order to store a record into an
106       abstract database object.
107
108              bool tcadbput(TCADB *adb, const void *kbuf, int ksiz, const void
109              *vbuf, int vsiz);
110                     `adb' specifies the abstract database object.
111                     `kbuf' specifies the pointer to the region of the key.
112                     `ksiz' specifies the size of the region of the key.
113                     `vbuf' specifies the pointer to the region of the value.
114                     `vsiz' specifies the size of the region of the value.
115                     If  successful,  the  return  value  is true, else, it is
116                     false.
117                     If a record with the same key exists in the database,  it
118                     is overwritten.
119
120       The function `tcadbput2' is used in order to store a string record into
121       an abstract object.
122
123              bool tcadbput2(TCADB *adb, const char *kstr, const char *vstr);
124                     `adb' specifies the abstract database object.
125                     `kstr' specifies the string of the key.
126                     `vstr' specifies the string of the value.
127                     If successful, the return value  is  true,  else,  it  is
128                     false.
129                     If  a record with the same key exists in the database, it
130                     is overwritten.
131
132       The function `tcadbputkeep' is used in order to store a new record into
133       an abstract database object.
134
135              bool  tcadbputkeep(TCADB *adb, const void *kbuf, int ksiz, const
136              void *vbuf, int vsiz);
137                     `adb' specifies the abstract database object.
138                     `kbuf' specifies the pointer to the region of the key.
139                     `ksiz' specifies the size of the region of the key.
140                     `vbuf' specifies the pointer to the region of the value.
141                     `vsiz' specifies the size of the region of the value.
142                     If successful, the return value  is  true,  else,  it  is
143                     false.
144                     If  a  record  with  the same key exists in the database,
145                     this function has no effect.
146
147       The function `tcadbputkeep2' is used in order to  store  a  new  string
148       record into an abstract database object.
149
150              bool  tcadbputkeep2(TCADB  *adb,  const  char  *kstr, const char
151              *vstr);
152                     `adb' specifies the abstract database object.
153                     `kstr' specifies the string of the key.
154                     `vstr' specifies the string of the value.
155                     If successful, the return value  is  true,  else,  it  is
156                     false.
157                     If  a  record  with  the same key exists in the database,
158                     this function has no effect.
159
160       The function `tcadbputcat' is used in order to concatenate a  value  at
161       the end of the existing record in an abstract database object.
162
163              bool  tcadbputcat(TCADB  *adb, const void *kbuf, int ksiz, const
164              void *vbuf, int vsiz);
165                     `adb' specifies the abstract database object.
166                     `kbuf' specifies the pointer to the region of the key.
167                     `ksiz' specifies the size of the region of the key.
168                     `vbuf' specifies the pointer to the region of the value.
169                     `vsiz' specifies the size of the region of the value.
170                     If successful, the return value  is  true,  else,  it  is
171                     false.
172                     If there is no corresponding record, a new record is cre‐
173                     ated.
174
175       The function `tcadbputcat2' is used in order to  concatenate  a  string
176       value at the end of the existing record in an abstract database object.
177
178              bool  tcadbputcat2(TCADB  *adb,  const  char  *kstr,  const char
179              *vstr);
180                     `adb' specifies the abstract database object.
181                     `kstr' specifies the string of the key.
182                     `vstr' specifies the string of the value.
183                     If successful, the return value  is  true,  else,  it  is
184                     false.
185                     If there is no corresponding record, a new record is cre‐
186                     ated.
187
188       The function `tcadbout' is used in order  to  remove  a  record  of  an
189       abstract database object.
190
191              bool tcadbout(TCADB *adb, const void *kbuf, int ksiz);
192                     `adb' specifies the abstract database object.
193                     `kbuf' specifies the pointer to the region of the key.
194                     `ksiz' specifies the size of the region of the key.
195                     If  successful,  the  return  value  is true, else, it is
196                     false.
197
198       The function `tcadbout2' is used in order to remove a string record  of
199       an abstract database object.
200
201              bool tcadbout2(TCADB *adb, const char *kstr);
202                     `adb' specifies the abstract database object.
203                     `kstr' specifies the string of the key.
204                     If  successful,  the  return  value  is true, else, it is
205                     false.
206
207       The function `tcadbget' is used in order to retrieve  a  record  in  an
208       abstract database object.
209
210              void *tcadbget(TCADB *adb, const void *kbuf, int ksiz, int *sp);
211                     `adb' specifies the abstract database object.
212                     `kbuf' specifies the pointer to the region of the key.
213                     `ksiz' specifies the size of the region of the key.
214                     `sp' specifies the pointer to the variable into which the
215                     size of the region of the return value is assigned.
216                     If successful, the return value is  the  pointer  to  the
217                     region  of the value of the corresponding record.  `NULL'
218                     is returned if no record corresponds.
219                     Because an additional zero code is appended at the end of
220                     the  region  of the return value, the return value can be
221                     treated as a character string.  Because the region of the
222                     return  value  is  allocated  with  the `malloc' call, it
223                     should be released with the `free' call  when  it  is  no
224                     longer in use.
225
226       The  function  `tcadbget2' is used in order to retrieve a string record
227       in an abstract database object.
228
229              char *tcadbget2(TCADB *adb, const char *kstr);
230                     `adb' specifies the abstract database object.
231                     `kstr' specifies the string of the key.
232                     If successful, the return value  is  the  string  of  the
233                     value of the corresponding record.  `NULL' is returned if
234                     no record corresponds.
235                     Because the region of the return value is allocated  with
236                     the  `malloc' call, it should be released with the `free'
237                     call when it is no longer in use.
238
239       The function `tcadbvsiz' is used in order to get the size of the  value
240       of a record in an abstract database object.
241
242              int tcadbvsiz(TCADB *adb, const void *kbuf, int ksiz);
243                     `adb' specifies the abstract database object.
244                     `kbuf' specifies the pointer to the region of the key.
245                     `ksiz' specifies the size of the region of the key.
246                     If  successful, the return value is the size of the value
247                     of the corresponding record, else, it is -1.
248
249       The function `tcadbvsiz2' is used in order to get the size of the value
250       of a string record in an abstract database object.
251
252              int tcadbvsiz2(TCADB *adb, const char *kstr);
253                     `adb' specifies the abstract database object.
254                     `kstr' specifies the string of the key.
255                     If  successful, the return value is the size of the value
256                     of the corresponding record, else, it is -1.
257
258       The function `tcadbiterinit' is used in order to initialize the  itera‐
259       tor of an abstract database object.
260
261              bool tcadbiterinit(TCADB *adb);
262                     `adb' specifies the abstract database object.
263                     If  successful,  the  return  value  is true, else, it is
264                     false.
265                     The iterator is used in order to access the key of  every
266                     record stored in a database.
267
268       The  function  `tcadbiternext'  is used in order to get the next key of
269       the iterator of an abstract database object.
270
271              void *tcadbiternext(TCADB *adb, int *sp);
272                     `adb' specifies the abstract database object.
273                     `sp' specifies the pointer to the variable into which the
274                     size of the region of the return value is assigned.
275                     If  successful,  the  return  value is the pointer to the
276                     region of the next key, else, it is  `NULL'.   `NULL'  is
277                     returned when no record is to be get out of the iterator.
278                     Because an additional zero code is appended at the end of
279                     the region of the return value, the return value  can  be
280                     treated as a character string.  Because the region of the
281                     return value is allocated  with  the  `malloc'  call,  it
282                     should  be  released  with  the `free' call when it is no
283                     longer in use.  It is possible to access every record  by
284                     iteration  of  calling  this  function.  It is allowed to
285                     update or remove records whose keys are fetched while the
286                     iteration.   However,  it  is not assured if updating the
287                     database is occurred while the iteration.   Besides,  the
288                     order of this traversal access method is arbitrary, so it
289                     is not assured that the order of storing matches the  one
290                     of the traversal access.
291
292       The  function  `tcadbiternext2'  is  used  in order to get the next key
293       string of the iterator of an abstract database object.
294
295              char *tcadbiternext2(TCADB *adb);
296                     `adb' specifies the abstract database object.
297                     If successful, the return value is the string of the next
298                     key,  else,  it  is  `NULL'.   `NULL' is returned when no
299                     record is to be get out of the iterator.
300                     Because the region of the return value is allocated  with
301                     the  `malloc' call, it should be released with the `free'
302                     call when it is no longer in  use.   It  is  possible  to
303                     access  every  record  by iteration of calling this func‐
304                     tion.  However, it is not assured if updating  the  data‐
305                     base is occurred while the iteration.  Besides, the order
306                     of this traversal access method is arbitrary,  so  it  is
307                     not  assured that the order of storing matches the one of
308                     the traversal access.
309
310       The function `tcadbfwmkeys' is used in order to  get  forward  matching
311       keys in an abstract database object.
312
313              TCLIST *tcadbfwmkeys(TCADB *adb, const void *pbuf, int psiz, int
314              max);
315                     `adb' specifies the abstract database object.
316                     `pbuf' specifies the pointer to the region of the prefix.
317                     `psiz' specifies the size of the region of the prefix.
318                     `max' specifies the maximum number of keys to be fetched.
319                     If it is negative, no limit is specified.
320                     The  return  value  is a list object of the corresponding
321                     keys.  This function does  never  fail.   It  returns  an
322                     empty list even if no key corresponds.
323                     Because  the  object  of the return value is created with
324                     the function `tclistnew', it should be deleted  with  the
325                     function  `tclistdel'  when it is no longer in use.  Note
326                     that this function may be very slow because every key  in
327                     the database is scanned.
328
329       The  function  `tcadbfwmkeys2' is used in order to get forward matching
330       string keys in an abstract database object.
331
332              TCLIST *tcadbfwmkeys2(TCADB *adb, const char *pstr, int max);
333                     `adb' specifies the abstract database object.
334                     `pstr' specifies the string of the prefix.
335                     `max' specifies the maximum number of keys to be fetched.
336                     If it is negative, no limit is specified.
337                     The  return  value  is a list object of the corresponding
338                     keys.  This function does  never  fail.   It  returns  an
339                     empty list even if no key corresponds.
340                     Because  the  object  of the return value is created with
341                     the function `tclistnew', it should be deleted  with  the
342                     function  `tclistdel'  when it is no longer in use.  Note
343                     that this function may be very slow because every key  in
344                     the database is scanned.
345
346       The  function  `tcadbaddint'  is  used  in order to add an integer to a
347       record in an abstract database object.
348
349              int tcadbaddint(TCADB *adb, const  void  *kbuf,  int  ksiz,  int
350              num);
351                     `adb' specifies the abstract database object.
352                     `kbuf' specifies the pointer to the region of the key.
353                     `ksiz' specifies the size of the region of the key.
354                     `num' specifies the additional value.
355                     If  successful,  the return value is the summation value,
356                     else, it is `INT_MIN'.
357                     If the corresponding record exists, the value is  treated
358                     as an integer and is added to.  If no record corresponds,
359                     a new record of the additional value is stored.
360
361       The function `tcadbadddouble' is used in order to add a real number  to
362       a record in an abstract database object.
363
364              double  tcadbadddouble(TCADB  *adb,  const void *kbuf, int ksiz,
365              double num);
366                     `adb' specifies the abstract database object.
367                     `kbuf' specifies the pointer to the region of the key.
368                     `ksiz' specifies the size of the region of the key.
369                     `num' specifies the additional value.
370                     If successful, the return value is the  summation  value,
371                     else, it is Not-a-Number.
372                     If  the corresponding record exists, the value is treated
373                     as a real number and is added to.  If  no  record  corre‐
374                     sponds, a new record of the additional value is stored.
375
376       The  function  `tcadbsync' is used in order to synchronize updated con‐
377       tents of an abstract database object with the file and the device.
378
379              bool tcadbsync(TCADB *adb);
380                     `adb' specifies the abstract database object.
381                     If successful, the return value  is  true,  else,  it  is
382                     false.
383
384       The  function  `tcadboptimize' is used in order to optimize the storage
385       of an abstract database object.
386
387              bool tcadboptimize(TCADB *adb, const char *params);
388                     `adb' specifies the abstract database object.
389                     `params' specifies the string of the  tuning  parameters,
390                     which works as with the tuning of parameters the function
391                     `tcadbopen'.  If it is `NULL', it is not used.
392                     If successful, the return value  is  true,  else,  it  is
393                     false.
394                     This  function  is useful to reduce the size of the data‐
395                     base storage with data fragmentation by successive updat‐
396                     ing.
397
398       The function `tcadbvanish' is used in order to remove all records of an
399       abstract database object.
400
401              bool tcadbvanish(TCADB *adb);
402                     `adb' specifies the abstract database object.
403                     If successful, the return value  is  true,  else,  it  is
404                     false.
405
406       The  function `tcadbcopy' is used in order to copy the database file of
407       an abstract database object.
408
409              bool tcadbcopy(TCADB *adb, const char *path);
410                     `adb' specifies the abstract database object.
411                     `path' specifies the path of the destination file.  If it
412                     begins  with `@', the trailing substring is executed as a
413                     command line.
414                     If successful, the return value  is  true,  else,  it  is
415                     false.  False is returned if the executed command returns
416                     non-zero code.
417                     The database file is assured to be kept synchronized  and
418                     not  modified while the copying or executing operation is
419                     in progress.  So, this function is  useful  to  create  a
420                     backup file of the database file.
421
422       The function `tcadbtranbegin' is used in order to begin the transaction
423       of an abstract database object.
424
425              bool tcadbtranbegin(TCADB *adb);
426                     `adb' specifies the abstract database object.
427                     If successful, the return value  is  true,  else,  it  is
428                     false.
429                     The  database  is locked by the thread while the transac‐
430                     tion so that only one transaction can be activated with a
431                     database object at the same time.  Thus, the serializable
432                     isolation level is assumed if every database operation is
433                     performed  in  the  transaction.  All updated regions are
434                     kept track of by write ahead logging while  the  transac‐
435                     tion.   If the database is closed during transaction, the
436                     transaction is aborted implicitly.
437
438       The function `tcadbtrancommit' is used in order to commit the  transac‐
439       tion of an abstract database object.
440
441              bool tcadbtrancommit(TCADB *adb);
442                     `adb' specifies the abstract database object.
443                     If  successful,  the  return  value  is true, else, it is
444                     false.
445                     Update in the transaction is fixed when it  is  committed
446                     successfully.
447
448       The function `tcadbtranabort' is used in order to abort the transaction
449       of an abstract database object.
450
451              bool tcadbtranabort(TCADB *adb);
452                     `adb' specifies the abstract database object.
453                     If successful, the return value  is  true,  else,  it  is
454                     false.
455                     Update  in  the  transaction  is  discarded  when  it  is
456                     aborted.  The state of  the  database  is  rollbacked  to
457                     before transaction.
458
459       The  function  `tcadbpath'  is used in order to get the file path of an
460       abstract database object.
461
462              const char *tcadbpath(TCADB *adb);
463                     `adb' specifies the abstract database object.
464                     The return value is the path  of  the  database  file  or
465                     `NULL'  if  the  object does not connect to any database.
466                     "*" stands for on-memory hash database.  "+"  stands  for
467                     on-memory tree database.
468
469       The  function `tcadbrnum' is used in order to get the number of records
470       of an abstract database object.
471
472              uint64_t tcadbrnum(TCADB *adb);
473                     `adb' specifies the abstract database object.
474                     The return value is the number of records  or  0  if  the
475                     object does not connect to any database instance.
476
477       The  function `tcadbsize' is used in order to get the size of the data‐
478       base of an abstract database object.
479
480              uint64_t tcadbsize(TCADB *adb);
481                     `adb' specifies the abstract database object.
482                     The return value is the size of the database or 0 if  the
483                     object does not connect to any database instance.
484
485       The  function `tcadbmisc' is used in order to call a versatile function
486       for miscellaneous operations of an abstract database object.
487
488              TCLIST *tcadbmisc(TCADB *adb, const  char  *name,  const  TCLIST
489              *args);
490                     `adb' specifies the abstract database object.
491                     `name' specifies the name of the function.  All databases
492                     support "put", "out", "get",  "putlist",  "outlist",  and
493                     "getlist".   "put"  is  to store a record.  It receives a
494                     key and a value, and returns an empty list.  "out" is  to
495                     remove a record.  It receives a key, and returns an empty
496                     list.  "get" is to retrieve a record.  It receives a key,
497                     and  returns a list of the values.  "putlist" is to store
498                     records.  It receives  keys  and  values  one  after  the
499                     other, and returns an empty list.  "outlist" is to remove
500                     records.  It receives keys, and returns  an  empty  list.
501                     "getlist"  is to retrieve records.  It receives keys, and
502                     returns keys and  values  of  corresponding  records  one
503                     after the other.
504                     `args' specifies a list object containing arguments.
505                     If  successful,  the return value is a list object of the
506                     result.  `NULL' is returned on failure.
507                     Because the object of the return value  is  created  with
508                     the  function  `tclistnew', it should be deleted with the
509                     function `tclistdel' when it is no longer in use.
510
511

SEE ALSO

513       tcatest(1), tcamgr(1), tokyocabinet(3)
514
515
516
517Man Page                          2009-09-04                          TCADB(3)
Impressum