1TCADB(3) Tokyo Cabinet TCADB(3)
2
6 tcadb - the abstract database API
7
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 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 #include <tcutil.h>
19 #include <tcadb.h>
20 #include <stdlib.h>
21 #include <stdbool.h>
22 #include <stdint.h>
23 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 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
40 The function `tcadbnew' is used in order to create an abstract database
41 object.
42 TCADB *tcadbnew(void);
44 The return value is the new abstract database object.
45 The function `tcadbdel' is used in order to delete an abstract database
47 object.
48 void tcadbdel(TCADB *adb);
50 `adb' specifies the abstract database object.
51 The function `tcadbopen' is used in order to open an abstract database.
53 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 The function `tcadbclose' is used in order to close an abstract data‐
94 base object.
95 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 The function `tcadbput' is used in order to store a record into an
106 abstract database object.
107 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 The function `tcadbput2' is used in order to store a string record into
121 an abstract object.
122 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 The function `tcadbputkeep' is used in order to store a new record into
133 an abstract database object.
134 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 The function `tcadbputkeep2' is used in order to store a new string
148 record into an abstract database object.
149 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 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 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 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 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 The function `tcadbout' is used in order to remove a record of an
189 abstract database object.
190 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 The function `tcadbout2' is used in order to remove a string record of
199 an abstract database object.
200 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 The function `tcadbget' is used in order to retrieve a record in an
208 abstract database object.
209 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 The function `tcadbget2' is used in order to retrieve a string record
227 in an abstract database object.
228 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 The function `tcadbvsiz' is used in order to get the size of the value
240 of a record in an abstract database object.
241 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 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 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 The function `tcadbiterinit' is used in order to initialize the itera‐
259 tor of an abstract database object.
260 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 The function `tcadbiternext' is used in order to get the next key of
269 the iterator of an abstract database object.
270 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 The function `tcadbiternext2' is used in order to get the next key
293 string of the iterator of an abstract database object.
294 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 The function `tcadbfwmkeys' is used in order to get forward matching
311 keys in an abstract database object.
312 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 The function `tcadbfwmkeys2' is used in order to get forward matching
330 string keys in an abstract database object.
331 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 The function `tcadbaddint' is used in order to add an integer to a
347 record in an abstract database object.
348 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 The function `tcadbadddouble' is used in order to add a real number to
362 a record in an abstract database object.
363 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 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 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 The function `tcadboptimize' is used in order to optimize the storage
385 of an abstract database object.
386 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 The function `tcadbvanish' is used in order to remove all records of an
399 abstract database object.
400 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 The function `tcadbcopy' is used in order to copy the database file of
407 an abstract database object.
408 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 The function `tcadbtranbegin' is used in order to begin the transaction
423 of an abstract database object.
424 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 The function `tcadbtrancommit' is used in order to commit the transac‐
439 tion of an abstract database object.
440 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 The function `tcadbtranabort' is used in order to abort the transaction
449 of an abstract database object.
450 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 The function `tcadbpath' is used in order to get the file path of an
460 abstract database object.
461 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 The function `tcadbrnum' is used in order to get the number of records
470 of an abstract database object.
471 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 The function `tcadbsize' is used in order to get the size of the data‐
478 base of an abstract database object.
479 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 The function `tcadbmisc' is used in order to call a versatile function
486 for miscellaneous operations of an abstract database object.
487 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",
493 "getlist", and "getpart". "put" is to store a record.
494 It receives a key and a value, and returns an empty list.
495 "out" is to remove a record. It receives a key, and
496 returns an empty list. "get" is to retrieve a record.
497 It receives a key, and returns a list of the values.
498 "putlist" is to store records. It receives keys and val‐
499 ues one after the other, and returns an empty list.
500 "outlist" is to remove records. It receives keys, and
501 returns an empty list. "getlist" is to retrieve records.
502 It receives keys, and returns keys and values of corre‐
503 sponding records one after the other. "getpart" is to
504 retrieve the partial value of a record. It receives a
505 key, the offset of the region, and the length of the
506 region.
507 `args' specifies a list object containing arguments.
508 If successful, the return value is a list object of the
509 result. `NULL' is returned on failure.
510 Because the object of the return value is created with
511 the function `tclistnew', it should be deleted with the
512 function `tclistdel' when it is no longer in use.
513
516 tcatest(1), tcamttest(1), tcamgr(1), tokyocabinet(3)
517Man Page 2012-08-18 TCADB(3)