1TCFDB(3) Tokyo Cabinet TCFDB(3)
2
6 tcfdb - the fixed-length database API
7
10 Fixed-length database is a file containing an array of fixed-length
11 elements and is handled with the fixed-length database API.
12 To use the fixed-length database API, include `tcutil.h', `tcfdb.h',
14 and related standard header files. Usually, write the following
15 description near the front of a source file.
16 #include <tcutil.h>
18 #include <tcfdb.h>
19 #include <stdlib.h>
20 #include <stdbool.h>
21 #include <stdint.h>
22 Objects whose type is pointer to `TCFDB' are used to handle
24 fixed-length databases. A fixed-length database object is created with
25 the function `tcfdbnew' and is deleted with the function `tcfdbdel'.
26 To avoid memory leak, it is important to delete every object when it is
27 no longer in use.
28 Before operations to store or retrieve records, it is necessary to open
30 a database file and connect the fixed-length database object to it.
31 The function `tcfdbopen' is used to open a database file and the func‐
32 tion `tcfdbclose' is used to close the database file. To avoid data
33 missing or corruption, it is important to close every database file
34 when it is no longer in use. It is forbidden for multible database
35 objects in a process to open the same database at the same time.
36
39 The function `tcfdberrmsg' is used in order to get the message string
40 corresponding to an error code.
41 const char *tcfdberrmsg(int ecode);
43 `ecode' specifies the error code.
44 The return value is the message string of the error code.
45 The function `tcfdbnew' is used in order to create a fixed-length data‐
47 base object.
48 TCFDB *tcfdbnew(void);
50 The return value is the new fixed-length database object.
51 The function `tcfdbdel' is used in order to delete a fixed-length data‐
53 base object.
54 void tcfdbdel(TCFDB *fdb);
56 `fdb' specifies the fixed-length 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 The function `tcfdbecode' is used in order to get the last happened
62 error code of a fixed-length database object.
63 int tcfdbecode(TCFDB *fdb);
65 `fdb' specifies the fixed-length 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 The function `tcfdbsetmutex' is used in order to set mutual exclusion
83 control of a fixed-length database object for threading.
84 bool tcfdbsetmutex(TCFDB *fdb);
86 `fdb' specifies the fixed-length database object which is
87 not opened.
88 If successful, the return value is true, else, it is
89 false.
90 Note that the mutual exclusion control is needed if the
91 object is shared by plural threads and this function
92 should be called before the database is opened.
93 The function `tcfdbtune' is used in order to set the tuning parameters
95 of a fixed-length database object.
96 bool tcfdbtune(TCFDB *fdb, int32_t width, int64_t limsiz);
98 `fdb' specifies the fixed-length database object which is
99 not opened.
100 `width' specifies the width of the value of each record.
101 If it is not more than 0, the default value is specified.
102 The default value is 255.
103 `limsiz' specifies the limit size of the database file.
104 If it is not more than 0, the default value is specified.
105 The default value is 268435456.
106 If successful, the return value is true, else, it is
107 false.
108 Note that the tuning parameters should be set before the
109 database is opened.
110 The function `tcfdbopen' is used in order to open a database file and
112 connect a fixed-length database object.
113 bool tcfdbopen(TCFDB *fdb, const char *path, int omode);
115 `fdb' specifies the fixed-length database object which is
116 not opened.
117 `path' specifies the path of the database file.
118 `omode' specifies the connection mode: `FDBOWRITER' as a
119 writer, `FDBOREADER' as a reader. If the mode is
120 `FDBOWRITER', the following may be added by bitwise-or:
121 `FDBOCREAT', which means it creates a new database if not
122 exist, `FDBOTRUNC', which means it creates a new database
123 regardless if one exists, `FDBOTSYNC', which means every
124 transaction synchronizes updated contents with the
125 device. Both of `FDBOREADER' and `FDBOWRITER' can be
126 added to by bitwise-or: `FDBONOLCK', which means it opens
127 the database file without file locking, or `FDBOLCKNB',
128 which means locking is performed without blocking.
129 If successful, the return value is true, else, it is
130 false.
131 The function `tcfdbclose' is used in order to close a fixed-length
133 database object.
134 bool tcfdbclose(TCFDB *fdb);
136 `fdb' specifies the fixed-length database object.
137 If successful, the return value is true, else, it is
138 false.
139 Update of a database is assured to be written when the
140 database is closed. If a writer opens a database but
141 does not close it appropriately, the database will be
142 broken.
143 The function `tcfdbput' is used in order to store a record into a
145 fixed-length database object.
146 bool tcfdbput(TCFDB *fdb, int64_t id, const void *vbuf, int
148 vsiz);
149 `fdb' specifies the fixed-length database object con‐
150 nected as a writer.
151 `id' specifies the ID number. It should be more than 0.
152 If it is `FDBIDMIN', the minimum ID number of existing
153 records is specified. If it is `FDBIDPREV', the number
154 less by one than the minimum ID number of existing
155 records is specified. If it is `FDBIDMAX', the maximum
156 ID number of existing records is specified. If it is
157 `FDBIDNEXT', the number greater by one than the maximum
158 ID number of existing records is specified.
159 `vbuf' specifies the pointer to the region of the value.
160 `vsiz' specifies the size of the region of the value. If
161 the size of the value is greater than the width tuning
162 parameter of the database, the size is cut down to the
163 width.
164 If successful, the return value is true, else, it is
165 false.
166 If a record with the same key exists in the database, it
167 is overwritten.
168 The function `tcfdbput2' is used in order to store a record with a dec‐
170 imal key into a fixed-length database object.
171 bool tcfdbput2(TCFDB *fdb, const void *kbuf, int ksiz, const
173 void *vbuf, int vsiz);
174 `fdb' specifies the fixed-length database object con‐
175 nected as a writer.
176 `kbuf' specifies the pointer to the region of the decimal
177 key. It should be more than 0. If it is "min", the min‐
178 imum ID number of existing records is specified. If it
179 is "prev", the number less by one than the minimum ID
180 number of existing records is specified. If it is "max",
181 the maximum ID number of existing records is specified.
182 If it is "next", the number greater by one than the maxi‐
183 mum ID number of existing records is specified.
184 `ksiz' specifies the size of the region of the key.
185 `vbuf' specifies the pointer to the region of the value.
186 `vsiz' specifies the size of the region of the value. If
187 the size of the value is greater than the width tuning
188 parameter of the database, the size is cut down to the
189 width.
190 If successful, the return value is true, else, it is
191 false.
192 If a record with the same key exists in the database, it
193 is overwritten.
194 The function `tcfdbput3' is used in order to store a string record with
196 a decimal key into a fixed-length database object.
197 bool tcfdbput3(TCFDB *fdb, const char *kstr, const void *vstr);
199 `fdb' specifies the fixed-length database object con‐
200 nected as a writer.
201 `kstr' specifies the string of the decimal key. It
202 should be more than 0. If it is "min", the minimum ID
203 number of existing records is specified. If it is
204 "prev", the number less by one than the minimum ID number
205 of existing records is specified. If it is "max", the
206 maximum ID number of existing records is specified. If
207 it is "next", the number greater by one than the maximum
208 ID number of existing records is specified.
209 `vstr' specifies the string 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 The function `tcfdbputkeep' is used in order to store a new record into
216 a fixed-length database object.
217 bool tcfdbputkeep(TCFDB *fdb, int64_t id, const void *vbuf, int
219 vsiz);
220 `fdb' specifies the fixed-length database object con‐
221 nected as a writer.
222 `id' specifies the ID number. It should be more than 0.
223 If it is `FDBIDMIN', the minimum ID number of existing
224 records is specified. If it is `FDBIDPREV', the number
225 less by one than the minimum ID number of existing
226 records is specified. If it is `FDBIDMAX', the maximum
227 ID number of existing records is specified. If it is
228 `FDBIDNEXT', the number greater by one than the maximum
229 ID number of existing records is specified.
230 `vbuf' specifies the pointer to the region of the value.
231 `vsiz' specifies the size of the region of the value. If
232 the size of the value is greater than the width tuning
233 parameter of the database, the size is cut down to the
234 width.
235 If successful, the return value is true, else, it is
236 false.
237 If a record with the same key exists in the database,
238 this function has no effect.
239 The function `tcfdbputkeep2' is used in order to store a new record
241 with a decimal key into a fixed-length database object.
242 bool tcfdbputkeep2(TCFDB *fdb, const void *kbuf, int ksiz, const
244 void *vbuf, int vsiz);
245 `fdb' specifies the fixed-length database object con‐
246 nected as a writer.
247 `kbuf' specifies the pointer to the region of the decimal
248 key. It should be more than 0. If it is "min", the min‐
249 imum ID number of existing records is specified. If it
250 is "prev", the number less by one than the minimum ID
251 number of existing records is specified. If it is "max",
252 the maximum ID number of existing records is specified.
253 If it is "next", the number greater by one than the maxi‐
254 mum ID number of existing records is specified.
255 `ksiz' specifies the size of the region of the key.
256 `vbuf' specifies the pointer to the region of the value.
257 `vsiz' specifies the size of the region of the value. If
258 the size of the value is greater than the width tuning
259 parameter of the database, the size is cut down to the
260 width.
261 If successful, the return value is true, else, it is
262 false.
263 If a record with the same key exists in the database,
264 this function has no effect.
265 The function `tcfdbputkeep3' is used in order to store a new string
267 record with a decimal key into a fixed-length database object.
268 bool tcfdbputkeep3(TCFDB *fdb, const char *kstr, const void
270 *vstr);
271 `fdb' specifies the fixed-length database object con‐
272 nected as a writer.
273 `kstr' specifies the string of the decimal key. It
274 should be more than 0. If it is "min", the minimum ID
275 number of existing records is specified. If it is
276 "prev", the number less by one than the minimum ID number
277 of existing records is specified. If it is "max", the
278 maximum ID number of existing records is specified. If
279 it is "next", the number greater by one than the maximum
280 ID number of existing records is specified.
281 `vstr' specifies the string of the value.
282 If successful, the return value is true, else, it is
283 false.
284 If a record with the same key exists in the database,
285 this function has no effect.
286 The function `tcfdbputcat' is used in order to concatenate a value at
288 the end of the existing record in a fixed-length database object.
289 bool tcfdbputcat(TCFDB *fdb, int64_t id, const void *vbuf, int
291 vsiz);
292 `fdb' specifies the fixed-length database object con‐
293 nected as a writer.
294 `id' specifies the ID number. It should be more than 0.
295 If it is `FDBIDMIN', the minimum ID number of existing
296 records is specified. If it is `FDBIDPREV', the number
297 less by one than the minimum ID number of existing
298 records is specified. If it is `FDBIDMAX', the maximum
299 ID number of existing records is specified. If it is
300 `FDBIDNEXT', the number greater by one than the maximum
301 ID number of existing records is specified.
302 `vbuf' specifies the pointer to the region of the value.
303 `vsiz' specifies the size of the region of the value. If
304 the size of the value is greater than the width tuning
305 parameter of the database, the size is cut down to the
306 width.
307 If successful, the return value is true, else, it is
308 false.
309 If there is no corresponding record, a new record is cre‐
310 ated.
311 The function `tcfdbputcat2' is used in order to concatenate a value
313 with a decimal key in a fixed-length database object.
314 bool tcfdbputcat2(TCFDB *fdb, const void *kbuf, int ksiz, const
316 void *vbuf, int vsiz);
317 `fdb' specifies the fixed-length database object con‐
318 nected as a writer.
319 `kbuf' specifies the pointer to the region of the decimal
320 key. It should be more than 0. If it is "min", the min‐
321 imum ID number of existing records is specified. If it
322 is "prev", the number less by one than the minimum ID
323 number of existing records is specified. If it is "max",
324 the maximum ID number of existing records is specified.
325 If it is "next", the number greater by one than the maxi‐
326 mum ID number of existing records is specified.
327 `ksiz' specifies the size of the region of the key.
328 `vbuf' specifies the pointer to the region of the value.
329 `vsiz' specifies the size of the region of the value. If
330 the size of the value is greater than the width tuning
331 parameter of the database, the size is cut down to the
332 width.
333 If successful, the return value is true, else, it is
334 false.
335 If there is no corresponding record, a new record is cre‐
336 ated.
337 The function `tcfdbputcat3' is used in order to concatenate a string
339 value with a decimal key in a fixed-length database object.
340 bool tcfdbputcat3(TCFDB *fdb, const char *kstr, const void
342 *vstr);
343 `fdb' specifies the fixed-length database object con‐
344 nected as a writer.
345 `kstr' specifies the string of the decimal key. It
346 should be more than 0. If it is "min", the minimum ID
347 number of existing records is specified. If it is
348 "prev", the number less by one than the minimum ID number
349 of existing records is specified. If it is "max", the
350 maximum ID number of existing records is specified. If
351 it is "next", the number greater by one than the maximum
352 ID number of existing records is specified.
353 `vstr' specifies the string of the value.
354 If successful, the return value is true, else, it is
355 false.
356 If there is no corresponding record, a new record is cre‐
357 ated.
358 The function `tcfdbout' is used in order to remove a record of a
360 fixed-length database object.
361 bool tcfdbout(TCFDB *fdb, int64_t id);
363 `fdb' specifies the fixed-length database object con‐
364 nected as a writer.
365 `id' specifies the ID number. It should be more than 0.
366 If it is `FDBIDMIN', the minimum ID number of existing
367 records is specified. If it is `FDBIDMAX', the maximum
368 ID number of existing records is specified.
369 If successful, the return value is true, else, it is
370 false.
371 The function `tcfdbout2' is used in order to remove a record with a
373 decimal key of a fixed-length database object.
374 bool tcfdbout2(TCFDB *fdb, const void *kbuf, int ksiz);
376 `fdb' specifies the fixed-length database object con‐
377 nected as a writer.
378 `kbuf' specifies the pointer to the region of the decimal
379 key. It should be more than 0. If it is "min", the min‐
380 imum ID number of existing records is specified. If it
381 is "max", the maximum ID number of existing records is
382 specified.
383 `ksiz' specifies the size of the region of the key.
384 If successful, the return value is true, else, it is
385 false.
386 The function `tcfdbout3' is used in order to remove a string record
388 with a decimal key of a fixed-length database object.
389 bool tcfdbout3(TCFDB *fdb, const char *kstr);
391 `fdb' specifies the fixed-length database object con‐
392 nected as a writer.
393 `kstr' specifies the string of the decimal key. It
394 should be more than 0. If it is "min", the minimum ID
395 number of existing records is specified. If it is "max",
396 the maximum ID number of existing records is specified.
397 If successful, the return value is true, else, it is
398 false.
399 The function `tcfdbget' is used in order to retrieve a record in a
401 fixed-length database object.
402 void *tcfdbget(TCFDB *fdb, int64_t id, int *sp);
404 `fdb' specifies the fixed-length database object.
405 `id' specifies the ID number. It should be more than 0.
406 If it is `FDBIDMIN', the minimum ID number of existing
407 records is specified. If it is `FDBIDMAX', the maximum
408 ID number of existing records is specified.
409 `sp' specifies the pointer to the variable into which the
410 size of the region of the return value is assigned.
411 If successful, the return value is the pointer to the
412 region of the value of the corresponding record. `NULL'
413 is returned if no record corresponds.
414 Because an additional zero code is appended at the end of
415 the region of the return value, the return value can be
416 treated as a character string. Because the region of the
417 return value is allocated with the `malloc' call, it
418 should be released with the `free' call when it is no
419 longer in use.
420 The function `tcfdbget2' is used in order to retrieve a record with a
422 decimal key in a fixed-length database object.
423 void *tcfdbget2(TCFDB *fdb, const void *kbuf, int ksiz, int
425 *sp);
426 `fdb' specifies the fixed-length database object.
427 `kbuf' specifies the pointer to the region of the decimal
428 key. It should be more than 0. If it is "min", the min‐
429 imum ID number of existing records is specified. If it
430 is "max", the maximum ID number of existing records is
431 specified.
432 `ksiz' specifies the size of the region of the key.
433 `sp' specifies the pointer to the variable into which the
434 size of the region of the return value is assigned.
435 If successful, the return value is the pointer to the
436 region of the value of the corresponding record. `NULL'
437 is returned if no record corresponds.
438 Because an additional zero code is appended at the end of
439 the region of the return value, the return value can be
440 treated as a character string. Because the region of the
441 return value is allocated with the `malloc' call, it
442 should be released with the `free' call when it is no
443 longer in use.
444 The function `tcfdbget3' is used in order to retrieve a string record
446 with a decimal key in a fixed-length database object.
447 char *tcfdbget3(TCFDB *fdb, const char *kstr);
449 `fdb' specifies the fixed-length database object.
450 `kstr' specifies the string of the decimal key. It
451 should be more than 0. If it is "min", the minimum ID
452 number of existing records is specified. If it is "max",
453 the maximum ID number of existing records is specified.
454 If successful, the return value is the string of the
455 value of the corresponding record. `NULL' is returned if
456 no record corresponds.
457 Because an additional zero code is appended at the end of
458 the region of the return value, the return value can be
459 treated as a character string. Because the region of the
460 return value is allocated with the `malloc' call, it
461 should be released with the `free' call when it is no
462 longer in use.
463 The function `tcfdbget4' is used in order to retrieve a record in a
465 fixed-length database object and write the value into a buffer.
466 int tcfdbget4(TCFDB *fdb, int64_t id, void *vbuf, int max);
468 `fdb' specifies the fixed-length database object.
469 `id' specifies the ID number. It should be more than 0.
470 If it is `FDBIDMIN', the minimum ID number of existing
471 records is specified. If it is `FDBIDMAX', the maximum
472 ID number of existing records is specified.
473 `vbuf' specifies the pointer to the buffer into which the
474 value of the corresponding record is written.
475 `max' specifies the size of the buffer.
476 If successful, the return value is the size of the writ‐
477 ten data, else, it is -1. -1 is returned if no record
478 corresponds to the specified key.
479 Note that an additional zero code is not appended at the
480 end of the region of the writing buffer.
481 The function `tcfdbvsiz' is used in order to get the size of the value
483 of a record in a fixed-length database object.
484 int tcfdbvsiz(TCFDB *fdb, int64_t id);
486 `fdb' specifies the fixed-length database object.
487 `id' specifies the ID number. It should be more than 0.
488 If it is `FDBIDMIN', the minimum ID number of existing
489 records is specified. If it is `FDBIDMAX', the maximum
490 ID number of existing records is specified.
491 If successful, the return value is the size of the value
492 of the corresponding record, else, it is -1.
493 The function `tcfdbvsiz2' is used in order to get the size of the value
495 with a decimal key in a fixed-length database object.
496 int tcfdbvsiz2(TCFDB *fdb, const void *kbuf, int ksiz);
498 `fdb' specifies the fixed-length database object.
499 `kbuf' specifies the pointer to the region of the decimal
500 key. It should be more than 0. If it is "min", the min‐
501 imum ID number of existing records is specified. If it
502 is "max", the maximum ID number of existing records is
503 specified.
504 `ksiz' specifies the size of the region of the key.
505 If successful, the return value is the size of the value
506 of the corresponding record, else, it is -1.
507 The function `tcfdbvsiz3' is used in order to get the size of the
509 string value with a decimal key in a fixed-length database object.
510 int tcfdbvsiz3(TCFDB *fdb, const char *kstr);
512 `fdb' specifies the fixed-length database object.
513 `kstr' specifies the string of the decimal key. It
514 should be more than 0. If it is "min", the minimum ID
515 number of existing records is specified. If it is "max",
516 the maximum ID number of existing records is specified.
517 If successful, the return value is the size of the value
518 of the corresponding record, else, it is -1.
519 The function `tcfdbiterinit' is used in order to initialize the itera‐
521 tor of a fixed-length database object.
522 bool tcfdbiterinit(TCFDB *fdb);
524 `fdb' specifies the fixed-length database object.
525 If successful, the return value is true, else, it is
526 false.
527 The iterator is used in order to access the key of every
528 record stored in a database.
529 The function `tcfdbiternext' is used in order to get the next ID number
531 of the iterator of a fixed-length database object.
532 uint64_t tcfdbiternext(TCFDB *fdb);
534 `fdb' specifies the fixed-length database object.
535 If successful, the return value is the next ID number of
536 the iterator, else, it is 0. 0 is returned when no
537 record is to be get out of the iterator.
538 It is possible to access every record by iteration of
539 calling this function. It is allowed to update or remove
540 records whose keys are fetched while the iteration. The
541 order of this traversal access method is ascending of the
542 ID number.
543 The function `tcfdbiternext2' is used in order to get the next decimay
545 key of the iterator of a fixed-length database object.
546 void *tcfdbiternext2(TCFDB *fdb, int *sp);
548 `fdb' specifies the fixed-length database object.
549 `sp' specifies the pointer to the variable into which the
550 size of the region of the return value is assigned.
551 If successful, the return value is the pointer to the
552 region of the next decimal key, else, it is `NULL'.
553 `NULL' is returned when no record is to be get out of the
554 iterator.
555 Because an additional zero code is appended at the end of
556 the region of the return value, the return value can be
557 treated as a character string. Because the region of the
558 return value is allocated with the `malloc' call, it
559 should be released with the `free' call when it is no
560 longer in use. It is possible to access every record by
561 iteration of calling this function. It is allowed to
562 update or remove records whose keys are fetched while the
563 iteration. The order of this traversal access method is
564 ascending of the ID number.
565 The function `tcfdbiternext3' is used in order to get the next decimay
567 key string of the iterator of a fixed-length database object.
568 char *tcfdbiternext3(TCFDB *fdb);
570 `fdb' specifies the fixed-length database object.
571 If successful, the return value is the string of the next
572 decimal key, else, it is `NULL'. `NULL' is returned when
573 no record is to be get out of the iterator.
574 Because the region of the return value is allocated with
575 the `malloc' call, it should be released with the `free'
576 call when it is no longer in use. It is possible to
577 access every record by iteration of calling this func‐
578 tion. It is allowed to update or remove records whose
579 keys are fetched while the iteration. The order of this
580 traversal access method is ascending of the ID number.
581 The function `tcfdbrange' is used in order to get range matching ID
583 numbers in a fixed-length database object.
584 uint64_t *tcfdbrange(TCFDB *fdb, int64_t lower, int64_t upper,
586 int max, int *np);
587 `fdb' specifies the fixed-length database object.
588 `lower' specifies the lower limit of the range. If it is
589 `FDBIDMIN', the minimum ID is specified.
590 `upper' specifies the upper limit of the range. If it is
591 `FDBIDMAX', the maximum ID is specified.
592 `max' specifies the maximum number of keys to be fetched.
593 If it is negative, no limit is specified.
594 `np' specifies the pointer to the variable into which the
595 number of elements of the return value is assigned.
596 If successful, the return value is the pointer to an
597 array of ID numbers of the corresponding records. `NULL'
598 is returned on failure. This function does never fail.
599 It returns an empty array even if no key corresponds.
600 Because the region of the return value is allocated with
601 the `malloc' call, it should be released with the `free'
602 call when it is no longer in use.
603 The function `tcfdbrange2' is used in order to get range matching deci‐
605 mal keys in a fixed-length database object.
606 TCLIST *tcfdbrange2(TCFDB *fdb, const void *lbuf, int lsiz,
608 const void *ubuf, int usiz, int max);
609 `fdb' specifies the fixed-length database object.
610 `lbuf' specifies the pointer to the region of the lower
611 key. If it is "min", the minimum ID number of existing
612 records is specified.
613 `lsiz' specifies the size of the region of the lower key.
614 `ubuf' specifies the pointer to the region of the upper
615 key. If it is "max", the maximum ID number of existing
616 records is specified.
617 `usiz' specifies the size of the region of the upper key.
618 `max' specifies the maximum number of keys to be fetched.
619 If it is negative, no limit is specified.
620 The return value is a list object of the corresponding
621 decimal keys. This function does never fail. It returns
622 an empty list even if no key corresponds.
623 Because the object of the return value is created with
624 the function `tclistnew', it should be deleted with the
625 function `tclistdel' when it is no longer in use. Note
626 that this function may be very slow because every key in
627 the database is scanned.
628 The function `tcfdbrange3' is used in order to get range matching deci‐
630 mal keys with strings in a fixed-length database object.
631 TCLIST *tcfdbrange3(TCFDB *fdb, const char *lstr, const char
633 *ustr, int max);
634 `fdb' specifies the fixed-length database object.
635 `lstr' specifies the string of the lower key. If it is
636 "min", the minimum ID number of existing records is spec‐
637 ified.
638 `ustr' specifies the string of the upper key. If it is
639 "max", the maximum ID number of existing records is spec‐
640 ified.
641 `max' specifies the maximum number of keys to be fetched.
642 If it is negative, no limit is specified.
643 The return value is a list object of the corresponding
644 decimal keys. This function does never fail. It returns
645 an empty list even if no key corresponds.
646 Because the object of the return value is created with
647 the function `tclistnew', it should be deleted with the
648 function `tclistdel' when it is no longer in use. Note
649 that this function may be very slow because every key in
650 the database is scanned.
651 The function `tcfdbrange4' is used in order to get keys with an inter‐
653 val notation in a fixed-length database object.
654 TCLIST *tcfdbrange4(TCFDB *fdb, const void *ibuf, int isiz, int
656 max);
657 `fdb' specifies the fixed-length database object.
658 `ibuf' specifies the pointer to the region of the inter‐
659 val notation.
660 `isiz' specifies the size of the region of the interval
661 notation.
662 `max' specifies the maximum number of keys to be fetched.
663 If it is negative, no limit is specified.
664 The return value is a list object of the corresponding
665 decimal keys. This function does never fail. It returns
666 an empty list even if no key corresponds.
667 Because the object of the return value is created with
668 the function `tclistnew', it should be deleted with the
669 function `tclistdel' when it is no longer in use. Note
670 that this function may be very slow because every key in
671 the database is scanned.
672 The function `tcfdbrange5' is used in order to get keys with an inter‐
674 val notation string in a fixed-length database object.
675 TCLIST *tcfdbrange5(TCFDB *fdb, const void *istr, int max);
677 `fdb' specifies the fixed-length database object.
678 `istr' specifies the pointer to the region of the inter‐
679 val notation string.
680 `max' specifies the maximum number of keys to be fetched.
681 If it is negative, no limit is specified.
682 The return value is a list object of the corresponding
683 decimal keys. This function does never fail. It returns
684 an empty list even if no key corresponds.
685 Because the object of the return value is created with
686 the function `tclistnew', it should be deleted with the
687 function `tclistdel' when it is no longer in use. Note
688 that this function may be very slow because every key in
689 the database is scanned.
690 The function `tcfdbaddint' is used in order to add an integer to a
692 record in a fixed-length database object.
693 int tcfdbaddint(TCFDB *fdb, int64_t id, int num);
695 `fdb' specifies the fixed-length database object con‐
696 nected as a writer.
697 `id' specifies the ID number. It should be more than 0.
698 If it is `FDBIDMIN', the minimum ID number of existing
699 records is specified. If it is `FDBIDPREV', the number
700 less by one than the minimum ID number of existing
701 records is specified. If it is `FDBIDMAX', the maximum
702 ID number of existing records is specified. If it is
703 `FDBIDNEXT', the number greater by one than the maximum
704 ID number of existing records is specified.
705 `num' specifies the additional value.
706 If successful, the return value is the summation value,
707 else, it is `INT_MIN'.
708 If the corresponding record exists, the value is treated
709 as an integer and is added to. If no record corresponds,
710 a new record of the additional value is stored.
711 The function `tcfdbadddouble' is used in order to add a real number to
713 a record in a fixed-length database object.
714 double tcfdbadddouble(TCFDB *fdb, int64_t id, double num);
716 `fdb' specifies the fixed-length database object con‐
717 nected as a writer.
718 `id' specifies the ID number. It should be more than 0.
719 If it is `FDBIDMIN', the minimum ID number of existing
720 records is specified. If it is `FDBIDPREV', the number
721 less by one than the minimum ID number of existing
722 records is specified. If it is `FDBIDMAX', the maximum
723 ID number of existing records is specified. If it is
724 `FDBIDNEXT', the number greater by one than the maximum
725 ID number of existing records is specified.
726 `num' specifies the additional value.
727 If successful, the return value is the summation value,
728 else, it is Not-a-Number.
729 If the corresponding record exists, the value is treated
730 as a real number and is added to. If no record corre‐
731 sponds, a new record of the additional value is stored.
732 The function `tcfdbsync' is used in order to synchronize updated con‐
734 tents of a fixed-length database object with the file and the device.
735 bool tcfdbsync(TCFDB *fdb);
737 `fdb' specifies the fixed-length database object con‐
738 nected as a writer.
739 If successful, the return value is true, else, it is
740 false.
741 This function is useful when another process connects to
742 the same database file.
743 The function `tcfdboptimize' is used in order to optimize the file of a
745 fixed-length database object.
746 bool tcfdboptimize(TCFDB *fdb, int32_t width, int64_t limsiz);
748 `fdb' specifies the fixed-length database object con‐
749 nected as a writer.
750 `width' specifies the width of the value of each record.
751 If it is not more than 0, the current setting is not
752 changed.
753 `limsiz' specifies the limit size of the database file.
754 If it is not more than 0, the current setting is not
755 changed.
756 If successful, the return value is true, else, it is
757 false.
758 The function `tcfdbvanish' is used in order to remove all records of a
760 fixed-length database object.
761 bool tcfdbvanish(TCFDB *fdb);
763 `fdb' specifies the fixed-length database object con‐
764 nected as a writer.
765 If successful, the return value is true, else, it is
766 false.
767 The function `tcfdbcopy' is used in order to copy the database file of
769 a fixed-length database object.
770 bool tcfdbcopy(TCFDB *fdb, const char *path);
772 `fdb' specifies the fixed-length database object.
773 `path' specifies the path of the destination file. If it
774 begins with `@', the trailing substring is executed as a
775 command line.
776 If successful, the return value is true, else, it is
777 false. False is returned if the executed command returns
778 non-zero code.
779 The database file is assured to be kept synchronized and
780 not modified while the copying or executing operation is
781 in progress. So, this function is useful to create a
782 backup file of the database file.
783 The function `tcfdbtranbegin' is used in order to begin the transaction
785 of a fixed-length database object.
786 bool tcfdbtranbegin(TCFDB *fdb);
788 `fdb' specifies the fixed-length database object con‐
789 nected as a writer.
790 If successful, the return value is true, else, it is
791 false.
792 The database is locked by the thread while the transac‐
793 tion so that only one transaction can be activated with a
794 database object at the same time. Thus, the serializable
795 isolation level is assumed if every database operation is
796 performed in the transaction. All updated regions are
797 kept track of by write ahead logging while the transac‐
798 tion. If the database is closed during transaction, the
799 transaction is aborted implicitly.
800 The function `tcfdbtrancommit' is used in order to commit the transac‐
802 tion of a fixed-length database object.
803 bool tcfdbtrancommit(TCFDB *fdb);
805 `fdb' specifies the fixed-length database object con‐
806 nected as a writer.
807 If successful, the return value is true, else, it is
808 false.
809 Update in the transaction is fixed when it is committed
810 successfully.
811 The function `tcfdbtranabort' is used in order to abort the transaction
813 of a fixed-length database object.
814 bool tcfdbtranabort(TCFDB *fdb);
816 `fdb' specifies the fixed-length database object con‐
817 nected as a writer.
818 If successful, the return value is true, else, it is
819 false.
820 Update in the transaction is discarded when it is
821 aborted. The state of the database is rollbacked to
822 before transaction.
823 The function `tcfdbpath' is used in order to get the file path of a
825 fixed-length database object.
826 const char *tcfdbpath(TCFDB *fdb);
828 `fdb' specifies the fixed-length database object.
829 The return value is the path of the database file or
830 `NULL' if the object does not connect to any database
831 file.
832 The function `tcfdbrnum' is used in order to get the number of records
834 of a fixed-length database object.
835 uint64_t tcfdbrnum(TCFDB *fdb);
837 `fdb' specifies the fixed-length database object.
838 The return value is the number of records or 0 if the
839 object does not connect to any database file.
840 The function `tcfdbfsiz' is used in order to get the size of the data‐
842 base file of a fixed-length database object.
843 uint64_t tcfdbfsiz(TCFDB *fdb);
845 `fdb' specifies the fixed-length database object.
846 The return value is the size of the database file or 0 if
847 the object does not connect to any database file.
848
851 tcftest(1), tcfmttest(1), tcfmgr(1), tokyocabinet(3)
852Man Page 2012-08-18 TCFDB(3)