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

NAME

6       tcfdb - the fixed-length database API
7
8

DESCRIPTION

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
13       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
17              #include <tcutil.h>
18              #include <tcfdb.h>
19              #include <stdlib.h>
20              #include <stdbool.h>
21              #include <stdint.h>
22
23       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
29       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
37

API

39       The function `tcfdberrmsg' is used in order to get the  message  string
40       corresponding to an error code.
41
42              const char *tcfdberrmsg(int ecode);
43                     `ecode' specifies the error code.
44                     The return value is the message string of the error code.
45
46       The function `tcfdbnew' is used in order to create a fixed-length data‐
47       base object.
48
49              TCFDB *tcfdbnew(void);
50                     The return value is the new fixed-length database object.
51
52       The function `tcfdbdel' is used in order to delete a fixed-length data‐
53       base object.
54
55              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
61       The  function  `tcfdbecode'  is  used in order to get the last happened
62       error code of a fixed-length database object.
63
64              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
82       The  function  `tcfdbsetmutex' is used in order to set mutual exclusion
83       control of a fixed-length database object for threading.
84
85              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
94       The function `tcfdbtune' is used in order to set the tuning  parameters
95       of a fixed-length database object.
96
97              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
111       The function `tcfdbopen' is used in order to open a database  file  and
112       connect a fixed-length database object.
113
114              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
132       The  function  `tcfdbclose'  is  used  in order to close a fixed-length
133       database object.
134
135              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
144       The function `tcfdbput' is used in order  to  store  a  record  into  a
145       fixed-length database object.
146
147              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
169       The function `tcfdbput2' is used in order to store a record with a dec‐
170       imal key into a fixed-length database object.
171
172              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
195       The function `tcfdbput3' is used in order to store a string record with
196       a decimal key into a fixed-length database object.
197
198              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
215       The function `tcfdbputkeep' is used in order to store a new record into
216       a fixed-length database object.
217
218              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
240       The function `tcfdbputkeep2' is used in order to  store  a  new  record
241       with a decimal key into a fixed-length database object.
242
243              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
266       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
269              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
287       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
290              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
312       The function `tcfdbputcat2' is used in order  to  concatenate  a  value
313       with a decimal key in a fixed-length database object.
314
315              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
338       The  function  `tcfdbputcat3'  is used in order to concatenate a string
339       value with a decimal key in a fixed-length database object.
340
341              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
359       The  function  `tcfdbout'  is  used  in  order  to remove a record of a
360       fixed-length database object.
361
362              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
372       The  function  `tcfdbout2'  is  used in order to remove a record with a
373       decimal key of a fixed-length database object.
374
375              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
387       The function `tcfdbout3' is used in order to  remove  a  string  record
388       with a decimal key of a fixed-length database object.
389
390              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
400       The function `tcfdbget' is used in order to  retrieve  a  record  in  a
401       fixed-length database object.
402
403              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
421       The function `tcfdbget2' is used in order to retrieve a record  with  a
422       decimal key in a fixed-length database object.
423
424              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
445       The function `tcfdbget3' is used in order to retrieve a  string  record
446       with a decimal key in a fixed-length database object.
447
448              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
464       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
467              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
482       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
485              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
494       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
497              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
508       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
511              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
520       The  function `tcfdbiterinit' is used in order to initialize the itera‐
521       tor of a fixed-length database object.
522
523              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
530       The function `tcfdbiternext' is used in order to get the next ID number
531       of the iterator of a fixed-length database object.
532
533              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
544       The  function `tcfdbiternext2' is used in order to get the next decimay
545       key of the iterator of a fixed-length database object.
546
547              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
566       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
569              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
582       The function `tcfdbrange' is used in order to  get  range  matching  ID
583       numbers in a fixed-length database object.
584
585              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
604       The function `tcfdbrange2' is used in order to get range matching deci‐
605       mal keys in a fixed-length database object.
606
607              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
629       The function `tcfdbrange3' is used in order to get range matching deci‐
630       mal keys with strings in a fixed-length database object.
631
632              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
652       The  function `tcfdbrange4' is used in order to get keys with an inter‐
653       val notation in a fixed-length database object.
654
655              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
673       The function `tcfdbrange5' is used in order to get keys with an  inter‐
674       val notation string in a fixed-length database object.
675
676              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
691       The  function  `tcfdbaddint'  is  used  in order to add an integer to a
692       record in a fixed-length database object.
693
694              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
712       The  function `tcfdbadddouble' is used in order to add a real number to
713       a record in a fixed-length database object.
714
715              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
733       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
736              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
744       The function `tcfdboptimize' is used in order to optimize the file of a
745       fixed-length database object.
746
747              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
759       The function `tcfdbvanish' is used in order to remove all records of  a
760       fixed-length database object.
761
762              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
768       The  function `tcfdbcopy' is used in order to copy the database file of
769       a fixed-length database object.
770
771              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
784       The function `tcfdbtranbegin' is used in order to begin the transaction
785       of a fixed-length database object.
786
787              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
801       The  function `tcfdbtrancommit' is used in order to commit the transac‐
802       tion of a fixed-length database object.
803
804              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
812       The function `tcfdbtranabort' is used in order to abort the transaction
813       of a fixed-length database object.
814
815              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
824       The function `tcfdbpath' is used in order to get the  file  path  of  a
825       fixed-length database object.
826
827              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
833       The  function `tcfdbrnum' is used in order to get the number of records
834       of a fixed-length database object.
835
836              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
841       The  function `tcfdbfsiz' is used in order to get the size of the data‐
842       base file of a fixed-length database object.
843
844              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
849

SEE ALSO

851       tcftest(1), tcfmttest(1), tcfmgr(1), tokyocabinet(3)
852
853
854
855Man Page                          2010-08-05                          TCFDB(3)
Impressum