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

NAME

6       tchdb - the hash database API
7
8

DESCRIPTION

10       Hash database is a file containing a hash table and is handled with the
11       hash database API.
12
13       To use the  hash  database  API,  include  `tcutil.h',  `tchdb.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 <tchdb.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 `TCHDB' are used to handle hash  data‐
25       bases.   A hash database object is created with the function `tchdbnew'
26       and is deleted with the function `tchdbdel'.  To avoid memory leak,  it
27       is important to delete every object when it is no longer in use.
28
29       Before operations to store or retrieve records, it is necessary to open
30       a database file and connect the hash database object to it.  The  func‐
31       tion  `tchdbopen'  is  used  to  open  a database file and the function
32       `tchdbclose' is used to close the database file.  To avoid data missing
33       or  corruption, it is important to close every database file when it is
34       no longer in use.  It is forbidden for multible database objects  in  a
35       process to open the same database at the same time.
36
37

API

39       The  function  `tchdberrmsg' is used in order to get the message string
40       corresponding to an error code.
41
42              const char *tchdberrmsg(int ecode);
43                     `ecode' specifies the error code.
44                     The return value is the message string of the error code.
45
46       The function `tchdbnew' is used in order  to  create  a  hash  database
47       object.
48
49              TCHDB *tchdbnew(void);
50                     The return value is the new hash database object.
51
52       The  function  `tchdbdel'  is  used  in order to delete a hash database
53       object.
54
55              void tchdbdel(TCHDB *hdb);
56                     `hdb' specifies the hash database object.
57                     If the database is not closed, it is  closed  implicitly.
58                     Note  that the deleted object and its derivatives can not
59                     be used anymore.
60
61       The function `tchdbecode' is used in order to  get  the  last  happened
62       error code of a hash database object.
63
64              int tchdbecode(TCHDB *hdb);
65                     `hdb' specifies the hash database object.
66                     The return value is the last happened error code.
67                     The  following  error codes are defined: `TCESUCCESS' for
68                     success, `TCETHREAD' for  threading  error,  `TCEINVALID'
69                     for  invalid  operation,  `TCENOFILE' for file not found,
70                     `TCENOPERM' for no permission, `TCEMETA' for invalid meta
71                     data, `TCERHEAD' for invalid record header, `TCEOPEN' for
72                     open error, `TCECLOSE' for close  error,  `TCETRUNC'  for
73                     trunc error, `TCESYNC' for sync error, `TCESTAT' for stat
74                     error, `TCESEEK'  for  seek  error,  `TCEREAD'  for  read
75                     error,  `TCEWRITE'  for  write  error, `TCEMMAP' for mmap
76                     error, `TCELOCK' for lock error, `TCEUNLINK'  for  unlink
77                     error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir
78                     error, `TCERMDIR' for rmdir error, `TCEKEEP' for existing
79                     record, `TCENOREC' for no record found, and `TCEMISC' for
80                     miscellaneous error.
81
82       The function `tchdbsetmutex' is used in order to set  mutual  exclusion
83       control of a hash database object for threading.
84
85              bool tchdbsetmutex(TCHDB *hdb);
86                     `hdb'  specifies  the  hash  database object which is not
87                     opened.
88                     If successful, the return value  is  true,  else,  it  is
89                     false.
90                     Note  that  the  mutual exclusion control of the database
91                     should be set before the database is opened.
92
93       The function `tchdbtune' is used in order to set the tuning  parameters
94       of a hash database object.
95
96              bool  tchdbtune(TCHDB  *hdb,  int64_t  bnum, int8_t apow, int8_t
97              fpow, uint8_t opts);
98                     `hdb' specifies the hash 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 16381.  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: `HDBTLARGE' spec‐
113                     ifies  that  the  size of the database can be larger than
114                     2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies
115                     that  each  record  is  compressed with Deflate encoding,
116                     `HDBTBZIP' specifies that each record is compressed  with
117                     BZIP2  encoding, `HDBTTCBS' 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 `tchdbsetcache' is used in order to set the caching param‐
125       eters of a hash database object.
126
127              bool tchdbsetcache(TCHDB *hdb, int32_t rcnum);
128                     `hdb'  specifies  the  hash  database object which is not
129                     opened.
130                     `rcnum' specifies the maximum number  of  records  to  be
131                     cached.   If  it  is not more than 0, the record cache is
132                     disabled.  It is disabled by default.
133                     If successful, the return value  is  true,  else,  it  is
134                     false.
135                     Note that the caching parameters should be set before the
136                     database is opened.
137
138       The function `tchdbsetxmsiz' is used in order to set the  size  of  the
139       extra mapped memory of a hash database object.
140
141              bool tchdbsetxmsiz(TCHDB *hdb, int64_t xmsiz);
142                     `hdb'  specifies  the  hash  database object which is not
143                     opened.
144                     `xmsiz' specifies the size of the  extra  mapped  memory.
145                     If it is not more than 0, the extra mapped memory is dis‐
146                     abled.  The default size is 67108864.
147                     If successful, the return value  is  true,  else,  it  is
148                     false.
149                     Note that the mapping parameters should be set before the
150                     database is opened.
151
152       The function `tchdbsetdfunit' is used in order to  set  the  unit  step
153       number of auto defragmentation of a hash database object.
154
155              bool tchdbsetdfunit(TCHDB *hdb, int32_t dfunit);
156                     `hdb'  specifies  the  hash  database object which is not
157                     opened.
158                     `dfunit' specifie the unit step number.   If  it  is  not
159                     more than 0, the auto defragmentation is disabled.  It is
160                     disabled by default.
161                     If successful, the return value  is  true,  else,  it  is
162                     false.
163                     Note  that  the  defragmentation parameters should be set
164                     before the database is opened.
165
166       The function `tchdbopen' is used in order to open a database  file  and
167       connect a hash database object.
168
169              bool tchdbopen(TCHDB *hdb, const char *path, int omode);
170                     `hdb'  specifies  the  hash  database object which is not
171                     opened.
172                     `path' specifies the path of the database file.
173                     `omode' specifies the connection mode: `HDBOWRITER' as  a
174                     writer,  `HDBOREADER'  as  a  reader.   If  the  mode  is
175                     `HDBOWRITER', the following may be added  by  bitwise-or:
176                     `HDBOCREAT', which means it creates a new database if not
177                     exist, `HDBOTRUNC', which means it creates a new database
178                     regardless  if one exists, `HDBOTSYNC', which means every
179                     transaction  synchronizes  updated  contents   with   the
180                     device.   Both  of  `HDBOREADER'  and `HDBOWRITER' can be
181                     added to by bitwise-or: `HDBONOLCK', which means it opens
182                     the  database  file without file locking, or `HDBOLCKNB',
183                     which means locking is performed without blocking.
184                     If successful, the return value  is  true,  else,  it  is
185                     false.
186
187       The  function  `tchdbclose'  is  used in order to close a hash database
188       object.
189
190              bool tchdbclose(TCHDB *hdb);
191                     `hdb' specifies the hash database object.
192                     If successful, the return value  is  true,  else,  it  is
193                     false.
194                     Update  of  a  database is assured to be written when the
195                     database is closed.  If a writer  opens  a  database  but
196                     does  not  close  it  appropriately, the database will be
197                     broken.
198
199       The function `tchdbput' is used in order to store a record into a  hash
200       database object.
201
202              bool tchdbput(TCHDB *hdb, const void *kbuf, int ksiz, const void
203              *vbuf, int vsiz);
204                     `hdb' specifies the hash database object connected  as  a
205                     writer.
206                     `kbuf' specifies the pointer to the region of the key.
207                     `ksiz' specifies the size of the region of the key.
208                     `vbuf' specifies the pointer to the region of the value.
209                     `vsiz' specifies the size of the region of the value.
210                     If  successful,  the  return  value  is true, else, it is
211                     false.
212                     If a record with the same key exists in the database,  it
213                     is overwritten.
214
215       The function `tchdbput2' is used in order to store a string record into
216       a hash database object.
217
218              bool tchdbput2(TCHDB *hdb, const char *kstr, const char *vstr);
219                     `hdb' specifies the hash database object connected  as  a
220                     writer.
221                     `kstr' specifies the string of the key.
222                     `vstr' specifies the string of the value.
223                     If  successful,  the  return  value  is true, else, it is
224                     false.
225                     If a record with the same key exists in the database,  it
226                     is overwritten.
227
228       The function `tchdbputkeep' is used in order to store a new record into
229       a hash database object.
230
231              bool tchdbputkeep(TCHDB *hdb, const void *kbuf, int ksiz,  const
232              void *vbuf, int vsiz);
233                     `hdb'  specifies  the hash database object connected as a
234                     writer.
235                     `kbuf' specifies the pointer to the region of the key.
236                     `ksiz' specifies the size of the region of the key.
237                     `vbuf' specifies the pointer to the region of the value.
238                     `vsiz' specifies the size of the region of the value.
239                     If successful, the return value  is  true,  else,  it  is
240                     false.
241                     If  a  record  with  the same key exists in the database,
242                     this function has no effect.
243
244       The function `tchdbputkeep2' is used in order to  store  a  new  string
245       record into a hash database object.
246
247              bool  tchdbputkeep2(TCHDB  *hdb,  const  char  *kstr, const char
248              *vstr);
249                     `hdb' specifies the hash database object connected  as  a
250                     writer.
251                     `kstr' specifies the string of the key.
252                     `vstr' specifies the string of the value.
253                     If  successful,  the  return  value  is true, else, it is
254                     false.
255                     If a record with the same key  exists  in  the  database,
256                     this function has no effect.
257
258       The  function  `tchdbputcat' is used in order to concatenate a value at
259       the end of the existing record in a hash database object.
260
261              bool tchdbputcat(TCHDB *hdb, const void *kbuf, int  ksiz,  const
262              void *vbuf, int vsiz);
263                     `hdb'  specifies  the hash database object connected as a
264                     writer.
265                     `kbuf' specifies the pointer to the region of the key.
266                     `ksiz' specifies the size of the region of the key.
267                     `vbuf' specifies the pointer to the region of the value.
268                     `vsiz' specifies the size of the region of the value.
269                     If successful, the return value  is  true,  else,  it  is
270                     false.
271                     If there is no corresponding record, a new record is cre‐
272                     ated.
273
274       The function `tchdbputcat2' is used in order to  concatenate  a  string
275       value at the end of the existing record in a hash database object.
276
277              bool  tchdbputcat2(TCHDB  *hdb,  const  char  *kstr,  const char
278              *vstr);
279                     `hdb' specifies the hash database object connected  as  a
280                     writer.
281                     `kstr' specifies the string of the key.
282                     `vstr' specifies the string of the value.
283                     If  successful,  the  return  value  is true, else, it is
284                     false.
285                     If there is no corresponding record, a new record is cre‐
286                     ated.
287
288       The  function `tchdbputasync' is used in order to store a record into a
289       hash database object in asynchronous fashion.
290
291              bool tchdbputasync(TCHDB *hdb, const void *kbuf, int ksiz, const
292              void *vbuf, int vsiz);
293                     `hdb'  specifies  the hash database object connected as a
294                     writer.
295                     `kbuf' specifies the pointer to the region of the key.
296                     `ksiz' specifies the size of the region of the key.
297                     `vbuf' specifies the pointer to the region of the value.
298                     `vsiz' specifies the size of the region of the value.
299                     If successful, the return value  is  true,  else,  it  is
300                     false.
301                     If  a record with the same key exists in the database, it
302                     is overwritten.  Records  passed  to  this  function  are
303                     accumulated into the inner buffer and wrote into the file
304                     at a blast.
305
306       The function `tchdbputasync2' is used in order to store a string record
307       into a hash database object in asynchronous fashion.
308
309              bool  tchdbputasync2(TCHDB  *hdb,  const  char *kstr, const char
310              *vstr);
311                     `hdb' specifies the hash database object connected  as  a
312                     writer.
313                     `kstr' specifies the string of the key.
314                     `vstr' specifies the string of the value.
315                     If  successful,  the  return  value  is true, else, it is
316                     false.
317                     If a record with the same key exists in the database,  it
318                     is  overwritten.   Records  passed  to  this function are
319                     accumulated into the inner buffer and wrote into the file
320                     at a blast.
321
322       The  function  `tchdbout' is used in order to remove a record of a hash
323       database object.
324
325              bool tchdbout(TCHDB *hdb, const void *kbuf, int ksiz);
326                     `hdb' specifies the hash database object connected  as  a
327                     writer.
328                     `kbuf' specifies the pointer to the region of the key.
329                     `ksiz' specifies the size of the region of the key.
330                     If  successful,  the  return  value  is true, else, it is
331                     false.
332
333       The function `tchdbout2' is used in order to remove a string record  of
334       a hash database object.
335
336              bool tchdbout2(TCHDB *hdb, const char *kstr);
337                     `hdb'  specifies  the hash database object connected as a
338                     writer.
339                     `kstr' specifies the string of the key.
340                     If successful, the return value  is  true,  else,  it  is
341                     false.
342
343       The function `tchdbget' is used in order to retrieve a record in a hash
344       database object.
345
346              void *tchdbget(TCHDB *hdb, const void *kbuf, int ksiz, int *sp);
347                     `hdb' specifies the hash database object.
348                     `kbuf' specifies the pointer to the region of the key.
349                     `ksiz' specifies the size of the region of the key.
350                     `sp' specifies the pointer to the variable into which the
351                     size of the region of the return value is assigned.
352                     If  successful,  the  return  value is the pointer to the
353                     region of the value of the corresponding record.   `NULL'
354                     is returned if no record corresponds.
355                     Because an additional zero code is appended at the end of
356                     the region of the return value, the return value  can  be
357                     treated as a character string.  Because the region of the
358                     return value is allocated  with  the  `malloc'  call,  it
359                     should  be  released  with  the `free' call when it is no
360                     longer in use.
361
362       The function `tchdbget2' is used in order to retrieve a  string  record
363       in a hash database object.
364
365              char *tchdbget2(TCHDB *hdb, const char *kstr);
366                     `hdb' specifies the hash database object.
367                     `kstr' specifies the string of the key.
368                     If  successful,  the  return  value  is the string of the
369                     value of the corresponding record.  `NULL' is returned if
370                     no record corresponds.
371                     Because  the region of the return value is allocated with
372                     the `malloc' call, it should be released with the  `free'
373                     call when it is no longer in use.
374
375       The  function  `tchdbget3'  is  used in order to retrieve a record in a
376       hash database object and write the value into a buffer.
377
378              int tchdbget3(TCHDB *hdb,  const  void  *kbuf,  int  ksiz,  void
379              *vbuf, int max);
380                     `hdb' specifies the hash database object.
381                     `kbuf' specifies the pointer to the region of the key.
382                     `ksiz' specifies the size of the region of the key.
383                     `vbuf' specifies the pointer to the buffer into which the
384                     value of the corresponding record is written.
385                     `max' specifies the size of the buffer.
386                     If successful, the return value is the size of the  writ‐
387                     ten  data,  else,  it is -1.  -1 is returned if no record
388                     corresponds to the specified key.
389                     Note that an additional zero code is not appended at  the
390                     end of the region of the writing buffer.
391
392       The  function `tchdbvsiz' is used in order to get the size of the value
393       of a record in a hash database object.
394
395              int tchdbvsiz(TCHDB *hdb, const void *kbuf, int ksiz);
396                     `hdb' specifies the hash database object.
397                     `kbuf' specifies the pointer to the region of the key.
398                     `ksiz' specifies the size of the region of the key.
399                     If successful, the return value is the size of the  value
400                     of the corresponding record, else, it is -1.
401
402       The function `tchdbvsiz2' is used in order to get the size of the value
403       of a string record in a hash database object.
404
405              int tchdbvsiz2(TCHDB *hdb, const char *kstr);
406                     `hdb' specifies the hash database object.
407                     `kstr' specifies the string of the key.
408                     If successful, the return value is the size of the  value
409                     of the corresponding record, else, it is -1.
410
411       The  function `tchdbiterinit' is used in order to initialize the itera‐
412       tor of a hash database object.
413
414              bool tchdbiterinit(TCHDB *hdb);
415                     `hdb' specifies the hash database object.
416                     If successful, the return value  is  true,  else,  it  is
417                     false.
418                     The  iterator is used in order to access the key of every
419                     record stored in a database.
420
421       The function `tchdbiternext' is used in order to get the  next  key  of
422       the iterator of a hash database object.
423
424              void *tchdbiternext(TCHDB *hdb, int *sp);
425                     `hdb' specifies the hash database object.
426                     `sp' specifies the pointer to the variable into which the
427                     size of the region of the return value is assigned.
428                     If successful, the return value is  the  pointer  to  the
429                     region  of  the  next key, else, it is `NULL'.  `NULL' is
430                     returned when no record is to be get out of the iterator.
431                     Because an additional zero code is appended at the end of
432                     the  region  of the return value, the return value can be
433                     treated as a character string.  Because the region of the
434                     return  value  is  allocated  with  the `malloc' call, it
435                     should be released with the `free' call  when  it  is  no
436                     longer  in use.  It is possible to access every record by
437                     iteration of calling this function.   It  is  allowed  to
438                     update or remove records whose keys are fetched while the
439                     iteration.  However, it is not assured  if  updating  the
440                     database  is  occurred while the iteration.  Besides, the
441                     order of this traversal access method is arbitrary, so it
442                     is  not assured that the order of storing matches the one
443                     of the traversal access.
444
445       The function `tchdbiternext2' is used in order  to  get  the  next  key
446       string of the iterator of a hash database object.
447
448              char *tchdbiternext2(TCHDB *hdb);
449                     `hdb' specifies the hash database object.
450                     If successful, the return value is the string of the next
451                     key, else, it is `NULL'.   `NULL'  is  returned  when  no
452                     record is to be get out of the iterator.
453                     Because  the region of the return value is allocated with
454                     the `malloc' call, it should be released with the  `free'
455                     call  when  it  is  no  longer in use.  It is possible to
456                     access every record by iteration of  calling  this  func‐
457                     tion.   However,  it is not assured if updating the data‐
458                     base is occurred while the iteration.  Besides, the order
459                     of  this  traversal  access method is arbitrary, so it is
460                     not assured that the order of storing matches the one  of
461                     the traversal access.
462
463       The function `tchdbiternext3' is used in order to get the next extensi‐
464       ble objects of the iterator of a hash database object.
465
466              bool tchdbiternext3(TCHDB *hdb, TCXSTR *kxstr, TCXSTR *vxstr);
467                     `hdb' specifies the hash database object.
468                     `kxstr' specifies the object into which the next  key  is
469                     wrote down.
470                     `vxstr' specifies the object into which the next value is
471                     wrote down.
472                     If successful, the return value  is  true,  else,  it  is
473                     false.  False is returned when no record is to be get out
474                     of the iterator.
475
476       The function `tchdbfwmkeys' is used in order to  get  forward  matching
477       keys in a hash database object.
478
479              TCLIST *tchdbfwmkeys(TCHDB *hdb, const void *pbuf, int psiz, int
480              max);
481                     `hdb' specifies the hash database object.
482                     `pbuf' specifies the pointer to the region of the prefix.
483                     `psiz' specifies the size of the region of the prefix.
484                     `max' specifies the maximum number of keys to be fetched.
485                     If it is negative, no limit is specified.
486                     The  return  value  is a list object of the corresponding
487                     keys.  This function does  never  fail.   It  returns  an
488                     empty list even if no key corresponds.
489                     Because  the  object  of the return value is created with
490                     the function `tclistnew', it should be deleted  with  the
491                     function  `tclistdel'  when it is no longer in use.  Note
492                     that this function may be very slow because every key  in
493                     the database is scanned.
494
495       The  function  `tchdbfwmkeys2' is used in order to get forward matching
496       string keys in a hash database object.
497
498              TCLIST *tchdbfwmkeys2(TCHDB *hdb, const char *pstr, int max);
499                     `hdb' specifies the hash database object.
500                     `pstr' specifies the string of the prefix.
501                     `max' specifies the maximum number of keys to be fetched.
502                     If it is negative, no limit is specified.
503                     The  return  value  is a list object of the corresponding
504                     keys.  This function does  never  fail.   It  returns  an
505                     empty list even if no key corresponds.
506                     Because  the  object  of the return value is created with
507                     the function `tclistnew', it should be deleted  with  the
508                     function  `tclistdel'  when it is no longer in use.  Note
509                     that this function may be very slow because every key  in
510                     the database is scanned.
511
512       The  function  `tchdbaddint'  is  used  in order to add an integer to a
513       record in a hash database object.
514
515              int tchdbaddint(TCHDB *hdb, const  void  *kbuf,  int  ksiz,  int
516              num);
517                     `hdb'  specifies  the hash database object connected as a
518                     writer.
519                     `kbuf' specifies the pointer to the region of the key.
520                     `ksiz' specifies the size of the region of the key.
521                     `num' specifies the additional value.
522                     If successful, the return value is the  summation  value,
523                     else, it is `INT_MIN'.
524                     If  the corresponding record exists, the value is treated
525                     as an integer and is added to.  If no record corresponds,
526                     a new record of the additional value is stored.
527
528       The  function  `tchdbdbadddouble' is used in order to add a real number
529       to a record in a hash database object.
530
531              double tchdbadddouble(TCHDB *hdb, const void  *kbuf,  int  ksiz,
532              double num);
533                     `hdb'  specifies  the hash database object connected as a
534                     writer.
535                     `kbuf' specifies the pointer to the region of the key.
536                     `ksiz' specifies the size of the region of the key.
537                     `num' specifies the additional value.
538                     If successful, the return value is the  summation  value,
539                     else, it is Not-a-Number.
540                     If  the corresponding record exists, the value is treated
541                     as a real number and is added to.  If  no  record  corre‐
542                     sponds, a new record of the additional value is stored.
543
544       The  function  `tchdbsync' is used in order to synchronize updated con‐
545       tents of a hash database object with the file and the device.
546
547              bool tchdbsync(TCHDB *hdb);
548                     `hdb' specifies the hash database object connected  as  a
549                     writer.
550                     If  successful,  the  return  value  is true, else, it is
551                     false.
552                     This function is useful when another process connects  to
553                     the same database file.
554
555       The function `tchdboptimize' is used in order to optimize the file of a
556       hash database object.
557
558              bool tchdboptimize(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t
559              fpow, uint8_t opts);
560                     `hdb'  specifies  the hash database object connected as a
561                     writer.
562                     `bnum' specifies the number of  elements  of  the  bucket
563                     array.   If  it  is not more than 0, the default value is
564                     specified.  The default value is two times of the  number
565                     of records.
566                     `apow' specifies the size of record alignment by power of
567                     2.  If  it  is  negative,  the  current  setting  is  not
568                     changed.
569                     `fpow'  specifies  the  maximum number of elements of the
570                     free block pool by power of 2.  If it  is  negative,  the
571                     current setting is not changed.
572                     `opts' specifies options by bitwise-or: `HDBTLARGE' spec‐
573                     ifies that the size of the database can  be  larger  than
574                     2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies
575                     that each record is  compressed  with  Deflate  encoding,
576                     `HDBTBZIP'  specifies that each record is compressed with
577                     BZIP2 encoding, `HDBTTCBS' specifies that each record  is
578                     compressed with TCBS encoding.  If it is `UINT8_MAX', the
579                     current setting is not changed.
580                     If successful, the return value  is  true,  else,  it  is
581                     false.
582                     This  function  is useful to reduce the size of the data‐
583                     base file with data fragmentation by successive updating.
584
585       The function `tchdbvanish' is used in order to remove all records of  a
586       hash database object.
587
588              bool tchdbvanish(TCHDB *hdb);
589                     `hdb'  specifies  the hash database object connected as a
590                     writer.
591                     If successful, the return value  is  true,  else,  it  is
592                     false.
593
594       The  function `tchdbcopy' is used in order to copy the database file of
595       a hash database object.
596
597              bool tchdbcopy(TCHDB *hdb, const char *path);
598                     `hdb' specifies the hash database object.
599                     `path' specifies the path of the destination file.  If it
600                     begins  with `@', the trailing substring is executed as a
601                     command line.
602                     If successful, the return value  is  true,  else,  it  is
603                     false.  False is returned if the executed command returns
604                     non-zero code.
605                     The database file is assured to be kept synchronized  and
606                     not  modified while the copying or executing operation is
607                     in progress.  So, this function is  useful  to  create  a
608                     backup file of the database file.
609
610       The function `tchdbtranbegin' is used in order to begin the transaction
611       of a hash database object.
612
613              bool tchdbtranbegin(TCHDB *hdb);
614                     `hdb' specifies the hash database object connected  as  a
615                     writer.
616                     If  successful,  the  return  value  is true, else, it is
617                     false.
618                     The database is locked by the thread while  the  transac‐
619                     tion so that only one transaction can be activated with a
620                     database object at the same time.  Thus, the serializable
621                     isolation level is assumed if every database operation is
622                     performed in the transaction.  All  updated  regions  are
623                     kept  track  of by write ahead logging while the transac‐
624                     tion.  If the database is closed during transaction,  the
625                     transaction is aborted implicitly.
626
627       The  function `tchdbtrancommit' is used in order to commit the transac‐
628       tion of a hash database object.
629
630              bool tchdbtrancommit(TCHDB *hdb);
631                     `hdb' specifies the hash database object connected  as  a
632                     writer.
633                     If  successful,  the  return  value  is true, else, it is
634                     false.
635                     Update in the transaction is fixed when it  is  committed
636                     successfully.
637
638       The function `tchdbtranabort' is used in order to abort the transaction
639       of a hash database object.
640
641              bool tchdbtranabort(TCHDB *hdb);
642                     `hdb' specifies the hash database object connected  as  a
643                     writer.
644                     If  successful,  the  return  value  is true, else, it is
645                     false.
646                     Update  in  the  transaction  is  discarded  when  it  is
647                     aborted.   The  state  of  the  database is rollbacked to
648                     before transaction.
649
650       The function `tchdbpath' is used in order to get the  file  path  of  a
651       hash database object.
652
653              const char *tchdbpath(TCHDB *hdb);
654                     `hdb' specifies the hash database object.
655                     The  return  value  is  the  path of the database file or
656                     `NULL' if the object does not  connect  to  any  database
657                     file.
658
659       The  function `tchdbrnum' is used in order to get the number of records
660       of a hash database object.
661
662              uint64_t tchdbrnum(TCHDB *hdb);
663                     `hdb' specifies the hash database object.
664                     The return value is the number of records  or  0  if  the
665                     object does not connect to any database file.
666
667       The  function `tchdbfsiz' is used in order to get the size of the data‐
668       base file of a hash database object.
669
670              uint64_t tchdbfsiz(TCHDB *hdb);
671                     `hdb' specifies the hash database object.
672                     The return value is the size of the database file or 0 if
673                     the object does not connect to any database file.
674
675

SEE ALSO

677       tchtest(1), tchmttest(1), tchmgr(1), tokyocabinet(3)
678
679
680
681Man Page                          2010-08-05                          TCHDB(3)
Impressum