1TCTDB(3) Tokyo Cabinet TCTDB(3)
2
6 tctdb - the table database API
7
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 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 #include <tcutil.h>
18 #include <tctdb.h>
19 #include <stdlib.h>
20 #include <stdbool.h>
21 #include <stdint.h>
22 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 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
38 The function `tctdberrmsg' is used in order to get the message string
39 corresponding to an error code.
40 const char *tctdberrmsg(int ecode);
42 `ecode' specifies the error code.
43 The return value is the message string of the error code.
44 The function `tctdbnew' is used in order to create a table database
46 object.
47 TCTDB *tctdbnew(void);
49 The return value is the new table database object.
50 The function `tctdbdel' is used in order to delete a table database
52 object.
53 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 The function `tctdbecode' is used in order to get the last happened
61 error code of a table database object.
62 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 The function `tctdbsetmutex' is used in order to set mutual exclusion
82 control of a table database object for threading.
83 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 The function `tctdbtune' is used in order to set the tuning parameters
94 of a table database object.
95 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 The function `tctdbsetcache' is set the caching parameters of a table
125 database object.
126 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 The function `tctdbsetxmsiz' is used in order to set the size of the
147 extra mapped memory of a table database object.
148 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 The function `tctdbsetdfunit' is used in order to set the unit step
161 number of auto defragmentation of a table database object.
162 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 The function `tctdbopen' is used in order to open a database file and
175 connect a table database object.
176 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 The function `tctdbclose' is used in order to close a table database
196 object.
197 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 The function `tctdbput' is used in order to store a record into a table
208 database object.
209 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 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 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 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 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 The function `tctdbputkeep' is used in order to store a new record into
261 a table database object.
262 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 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 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 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 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 The function `tctdbputcat' is used in order to concatenate columns of
316 the existing record in a table database object.
317 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 The function `tctdbputcat2' is used in order to concatenate columns in
333 a table database object with a zero separated column string.
334 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 The function `tctdbputcat3' is used in order to concatenate columns in
354 a table database object with with a tab separated column string.
355 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 The function `tctdbout' is used in order to remove a record of a table
370 database object.
371 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 The function `tctdbout2' is used in order to remove a string record of
383 a table database object.
384 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 The function `tctdbget' is used in order to retrieve a record in a ta‐
393 ble database object.
394 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 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 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 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 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 The function `tctdbvsiz' is used in order to get the size of the value
444 of a record in a table database object.
445 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 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 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 The function `tctdbiterinit' is used in order to initialize the itera‐
465 tor of a table database object.
466 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 The function `tctdbiternext' is used in order to get the next primary
475 key of the iterator of a table database object.
476 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 The function `tctdbiternext2' is used in order to get the next primary
500 key string of the iterator of a table database object.
501 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 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 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 The function `tctdbfwmkeys' is used in order to get forward matching
538 primary keys in a table database object.
539 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 The function `tctdbfwmkeys2' is used in order to get forward matching
557 string primary keys in a table database object.
558 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 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 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 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 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 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 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 The function `tctdboptimize' is used in order to optimize the file of a
621 table database object.
622 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 The function `tctdbvanish' is used in order to remove all records of a
651 table database object.
652 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 The function `tctdbcopy' is used in order to copy the database file of
660 a table database object.
661 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 The function `tctdbtranbegin' is used in order to begin the transaction
676 of a table database object.
677 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 The function `tctdbtrancommit' is used in order to commit the transac‐
694 tion of a table database object.
695 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 The function `tctdbtranabort' is used in order to abort the transaction
705 of a table database object.
706 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 The function `tctdbpath' is used in order to get the file path of a ta‐
717 ble database object.
718 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 The function `tctdbrnum' is used in order to get the number of records
726 ccccof a table database object.
727 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 The function `tctdbfsiz' is used in order to get the size of the data‐
734 base file of a table database object.
735 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 The function `tctdbsetindex' is used in order to set a column index to
742 a table database object.
743 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 The function `tctdbgenuid' is used in order to generate a unique ID
763 number of a table database object.
764 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 The function `tctdbqrynew' is used in order to create a query object.
772 TDBQRY *tctdbqrynew(TCTDB *tdb);
774 `tdb' specifies the table database object.
775 The return value is the new query object.
776 The function `tctdbqrydel' is used in order to delete a query object.
778 void tctdbqrydel(TDBQRY *qry);
780 `qry' specifies the query object.
781 The function `tctdbqryaddcond' is used in order to add a narrowing con‐
783 dition to a query object.
784 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 The function `tctdbqrysetorder' is used in order to set the order of a
819 query object.
820 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 The function `tctdbqrysetlimit' is used in order to set the limit num‐
831 ber of records of the result of a query object.
832 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 The function `tctdbqrysearch' is used in order to execute the search of
841 a query object.
842 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 The function `tctdbqrysearchout' is used in order to remove each record
854 corresponding to a query object.
855 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 The function `tctdbqryproc' is used in order to process each record
863 corresponding to a query object.
864 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 The function `tctdbqryhint' is used in order to get the hint string of
885 a query object.
886 const char *tctdbqryhint(TDBQRY *qry);
888 `qry' specifies the query object.
889 The return value is the hint string.
890 The function `tctdbmetasearch' is used in order to retrieve records
892 with multiple query objects and get the set of the result.
893 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
912 tcttest(1), tctmttest(1), tctmgr(1), tokyocabinet(3)
913Man Page 2012-08-18 TCTDB(3)