Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TCFDB(3)			 Tokyo Cabinet			      TCFDB(3)

NAME
       tcfdb - the fixed-length	database API

DESCRIPTION
       Fixed-length database is	a file containing an array of fixed-length el-
       ements and is handled with the fixed-length database API.

       To use the fixed-length database	API,  include  `tcutil.h',  `tcfdb.h',
       and  related  standard  header files.  Usually, write the following de-
       scription near the front	of a source file.

	      #include <tcutil.h>
	      #include <tcfdb.h>
	      #include <stdlib.h>
	      #include <stdbool.h>
	      #include <stdint.h>

       Objects	whose  type  is	 pointer  to  `TCFDB'  are  used   to	handle
       fixed-length databases.	A fixed-length database	object is created with
       the function `tcfdbnew' and is deleted with  the	 function  `tcfdbdel'.
       To avoid	memory leak, it	is important to	delete every object when it is
       no longer in use.

       Before operations to store or retrieve records, it is necessary to open
       a  database  file  and  connect the fixed-length	database object	to it.
       The function `tcfdbopen'	is used	to open	a database file	and the	 func-
       tion  `tcfdbclose'  is  used to close the database file.	 To avoid data
       missing or corruption, it is important to  close	 every	database  file
       when it is no longer in use.  It	is forbidden for multible database ob-
       jects in	a process to open the same database at the same	time.

API
       The function `tcfdberrmsg' is used in order to get the  message	string
       corresponding to	an error code.

	      const char *tcfdberrmsg(int ecode);
		     `ecode' specifies the error code.
		     The return	value is the message string of the error code.

       The function `tcfdbnew' is used in order	to create a fixed-length data-
       base object.

	      TCFDB *tcfdbnew(void);
		     The return	value is the new fixed-length database object.

       The function `tcfdbdel' is used in order	to delete a fixed-length data-
       base object.

	      void tcfdbdel(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     If	 the  database is not closed, it is closed implicitly.
		     Note that the deleted object and its derivatives can  not
		     be	used anymore.

       The function `tcfdbecode' is used in order to get the last happened er-
       ror code	of a fixed-length database object.

	      int tcfdbecode(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     The return	value is the last happened error code.
		     The following error codes are defined:  `TCESUCCESS'  for
		     success,  `TCETHREAD'  for	 threading error, `TCEINVALID'
		     for invalid operation, `TCENOFILE'	for  file  not	found,
		     `TCENOPERM' for no	permission, `TCEMETA' for invalid meta
		     data, `TCERHEAD' for invalid record header, `TCEOPEN' for
		     open  error,  `TCECLOSE'  for close error,	`TCETRUNC' for
		     trunc error, `TCESYNC' for	sync error, `TCESTAT' for stat
		     error,  `TCESEEK'	for seek error,	`TCEREAD' for read er-
		     ror, `TCEWRITE' for write error, `TCEMMAP'	for  mmap  er-
		     ror, `TCELOCK' for	lock error, `TCEUNLINK'	for unlink er-
		     ror, `TCERENAME' for rename error,	`TCEMKDIR'  for	 mkdir
		     error, `TCERMDIR' for rmdir error,	`TCEKEEP' for existing
		     record, `TCENOREC'	for no record found, and `TCEMISC' for
		     miscellaneous error.

       The  function  `tcfdbsetmutex' is used in order to set mutual exclusion
       control of a fixed-length database object for threading.

	      bool tcfdbsetmutex(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object which is
		     not opened.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Note that the mutual exclusion control is needed  if  the
		     object  is	 shared	 by  plural  threads and this function
		     should be called before the database is opened.

       The function `tcfdbtune'	is used	in order to set	the tuning  parameters
       of a fixed-length database object.

	      bool tcfdbtune(TCFDB *fdb, int32_t width,	int64_t	limsiz);
		     `fdb' specifies the fixed-length database object which is
		     not opened.
		     `width' specifies the width of the	value of each  record.
		     If	it is not more than 0, the default value is specified.
		     The default value is 255.
		     `limsiz' specifies	the limit size of the  database	 file.
		     If	it is not more than 0, the default value is specified.
		     The default value is 268435456.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     Note  that	the tuning parameters should be	set before the
		     database is opened.

       The function `tcfdbopen'	is used	in order to open a database  file  and
       connect a fixed-length database object.

	      bool tcfdbopen(TCFDB *fdb, const char *path, int omode);
		     `fdb' specifies the fixed-length database object which is
		     not opened.
		     `path' specifies the path of the database file.
		     `omode' specifies the connection mode: `FDBOWRITER' as  a
		     writer,  `FDBOREADER'  as	a reader.  If the mode is `FD-
		     BOWRITER',	the following may be added by bitwise-or: `FD-
		     BOCREAT',	which  means  it creates a new database	if not
		     exist, `FDBOTRUNC', which means it	creates	a new database
		     regardless	 if one	exists,	`FDBOTSYNC', which means every
		     transaction synchronizes updated contents	with  the  de-
		     vice.  Both of `FDBOREADER' and `FDBOWRITER' can be added
		     to	by bitwise-or: `FDBONOLCK', which means	it  opens  the
		     database file without file	locking, or `FDBOLCKNB', which
		     means locking is performed	without	blocking.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tcfdbclose'  is	used  in order to close	a fixed-length
       database	object.

	      bool tcfdbclose(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     Update  of	 a  database is	assured	to be written when the
		     database is closed.  If a writer  opens  a	 database  but
		     does  not	close  it  appropriately, the database will be
		     broken.

       The function `tcfdbput' is used in order	 to  store  a  record  into  a
       fixed-length database object.

	      bool  tcfdbput(TCFDB  *fdb,  int64_t  id,	 const void *vbuf, int
	      vsiz);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `id'  specifies the ID number.  It	should be more than 0.
		     If	it is `FDBIDMIN', the minimum ID  number  of  existing
		     records  is  specified.  If it is `FDBIDPREV', the	number
		     less by one  than	the  minimum  ID  number  of  existing
		     records  is  specified.  If it is `FDBIDMAX', the maximum
		     ID	number of existing records is  specified.   If	it  is
		     `FDBIDNEXT',  the	number greater by one than the maximum
		     ID	number of existing records is specified.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the  size	of  the	value is greater than the width	tuning
		     parameter of the database,	the size is cut	 down  to  the
		     width.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	a record with the same key exists in the database,  it
		     is	overwritten.

       The function `tcfdbput2'	is used	in order to store a record with	a dec-
       imal key	into a fixed-length database object.

	      bool tcfdbput2(TCFDB *fdb, const void  *kbuf,  int  ksiz,	 const
	      void *vbuf, int vsiz);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum ID number of existing	records	is specified.	If  it
		     is	 "prev",  the  number  less by one than	the minimum ID
		     number of existing	records	is specified.  If it is	"max",
		     the  maximum  ID number of	existing records is specified.
		     If	it is "next", the number greater by one	than the maxi-
		     mum ID number of existing records is specified.
		     `ksiz' specifies the size of the region of	the key.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the size of the value is greater than  the	 width	tuning
		     parameter	of  the	 database, the size is cut down	to the
		     width.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     If	 a record with the same	key exists in the database, it
		     is	overwritten.

       The function `tcfdbput3'	is used	in order to store a string record with
       a decimal key into a fixed-length database object.

	      bool tcfdbput3(TCFDB *fdb, const char *kstr, const void *vstr);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `kstr' specifies the  string  of  the  decimal  key.   It
		     should  be	 more  than 0.	If it is "min",	the minimum ID
		     number of	existing  records  is  specified.   If	it  is
		     "prev", the number	less by	one than the minimum ID	number
		     of	existing records is specified.	If it  is  "max",  the
		     maximum  ID  number of existing records is	specified.  If
		     it	is "next", the number greater by one than the  maximum
		     ID	number of existing records is specified.
		     `vstr' specifies the string of the	value.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	a record with the same key exists in the database,  it
		     is	overwritten.

       The function `tcfdbputkeep' is used in order to store a new record into
       a fixed-length database object.

	      bool tcfdbputkeep(TCFDB *fdb, int64_t id,	const void *vbuf,  int
	      vsiz);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `id' specifies the	ID number.  It should be more than  0.
		     If	 it  is	 `FDBIDMIN', the minimum ID number of existing
		     records is	specified.  If it is `FDBIDPREV',  the	number
		     less  by  one  than  the  minimum	ID  number of existing
		     records is	specified.  If it is `FDBIDMAX',  the  maximum
		     ID	 number	 of  existing  records is specified.  If it is
		     `FDBIDNEXT', the number greater by	one than  the  maximum
		     ID	number of existing records is specified.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the size of the value is greater than  the	 width	tuning
		     parameter	of  the	 database, the size is cut down	to the
		     width.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     If	 a  record  with  the same key exists in the database,
		     this function has no effect.

       The function `tcfdbputkeep2' is used in order to	 store	a  new	record
       with a decimal key into a fixed-length database object.

	      bool tcfdbputkeep2(TCFDB *fdb, const void	*kbuf, int ksiz, const
	      void *vbuf, int vsiz);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum  ID  number of existing records is specified.	 If it
		     is	"prev",	the number less	by one	than  the  minimum  ID
		     number of existing	records	is specified.  If it is	"max",
		     the maximum ID number of existing records	is  specified.
		     If	it is "next", the number greater by one	than the maxi-
		     mum ID number of existing records is specified.
		     `ksiz' specifies the size of the region of	the key.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the  size	of  the	value is greater than the width	tuning
		     parameter of the database,	the size is cut	 down  to  the
		     width.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	a record with the same key  exists  in	the  database,
		     this function has no effect.

       The  function  `tcfdbputkeep3'  is  used	in order to store a new	string
       record with a decimal key into a	fixed-length database object.

	      bool tcfdbputkeep3(TCFDB *fdb,  const  char  *kstr,  const  void
	      *vstr);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `kstr' specifies the  string  of  the  decimal  key.   It
		     should  be	 more  than 0.	If it is "min",	the minimum ID
		     number of	existing  records  is  specified.   If	it  is
		     "prev", the number	less by	one than the minimum ID	number
		     of	existing records is specified.	If it  is  "max",  the
		     maximum  ID  number of existing records is	specified.  If
		     it	is "next", the number greater by one than the  maximum
		     ID	number of existing records is specified.
		     `vstr' specifies the string of the	value.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	a record with the same key  exists  in	the  database,
		     this function has no effect.

       The  function  `tcfdbputcat' is used in order to	concatenate a value at
       the end of the existing record in a fixed-length	database object.

	      bool tcfdbputcat(TCFDB *fdb, int64_t id, const void  *vbuf,  int
	      vsiz);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `id' specifies the	ID number.  It should be more than  0.
		     If	 it  is	 `FDBIDMIN', the minimum ID number of existing
		     records is	specified.  If it is `FDBIDPREV',  the	number
		     less  by  one  than  the  minimum	ID  number of existing
		     records is	specified.  If it is `FDBIDMAX',  the  maximum
		     ID	 number	 of  existing  records is specified.  If it is
		     `FDBIDNEXT', the number greater by	one than  the  maximum
		     ID	number of existing records is specified.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the size of the value is greater than  the	 width	tuning
		     parameter	of  the	 database, the size is cut down	to the
		     width.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     If	there is no corresponding record, a new	record is cre-
		     ated.

       The function `tcfdbputcat2' is used in order  to	 concatenate  a	 value
       with a decimal key in a fixed-length database object.

	      bool  tcfdbputcat2(TCFDB *fdb, const void	*kbuf, int ksiz, const
	      void *vbuf, int vsiz);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum  ID  number of existing records is specified.	 If it
		     is	"prev",	the number less	by one	than  the  minimum  ID
		     number of existing	records	is specified.  If it is	"max",
		     the maximum ID number of existing records	is  specified.
		     If	it is "next", the number greater by one	than the maxi-
		     mum ID number of existing records is specified.
		     `ksiz' specifies the size of the region of	the key.
		     `vbuf' specifies the pointer to the region	of the value.
		     `vsiz' specifies the size of the region of	the value.  If
		     the  size	of  the	value is greater than the width	tuning
		     parameter of the database,	the size is cut	 down  to  the
		     width.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	there is no corresponding record, a new	record is cre-
		     ated.

       The  function  `tcfdbputcat3'  is used in order to concatenate a	string
       value with a decimal key	in a fixed-length database object.

	      bool tcfdbputcat3(TCFDB  *fdb,  const  char  *kstr,  const  void
	      *vstr);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `kstr' specifies the  string  of  the  decimal  key.   It
		     should  be	 more  than 0.	If it is "min",	the minimum ID
		     number of	existing  records  is  specified.   If	it  is
		     "prev", the number	less by	one than the minimum ID	number
		     of	existing records is specified.	If it  is  "max",  the
		     maximum  ID  number of existing records is	specified.  If
		     it	is "next", the number greater by one than the  maximum
		     ID	number of existing records is specified.
		     `vstr' specifies the string of the	value.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     If	there is no corresponding record, a new	record is cre-
		     ated.

       The  function  `tcfdbout'  is  used  in	order  to remove a record of a
       fixed-length database object.

	      bool tcfdbout(TCFDB *fdb,	int64_t	id);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `id'  specifies the ID number.  It	should be more than 0.
		     If	it is `FDBIDMIN', the minimum ID  number  of  existing
		     records  is  specified.  If it is `FDBIDMAX', the maximum
		     ID	number of existing records is specified.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tcfdbout2'  is  used in order to	remove a record	with a
       decimal key of a	fixed-length database object.

	      bool tcfdbout2(TCFDB *fdb, const void *kbuf, int ksiz);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum  ID  number of existing records is specified.	 If it
		     is	"max", the maximum ID number of	 existing  records  is
		     specified.
		     `ksiz' specifies the size of the region of	the key.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcfdbout3'	is used	in order to  remove  a	string	record
       with a decimal key of a fixed-length database object.

	      bool tcfdbout3(TCFDB *fdb, const char *kstr);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     `kstr' specifies the  string  of  the  decimal  key.   It
		     should  be	 more  than 0.	If it is "min",	the minimum ID
		     number of existing	records	is specified.  If it is	"max",
		     the maximum ID number of existing records is specified.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcfdbget' is used in order	to  retrieve  a	 record	 in  a
       fixed-length database object.

	      void *tcfdbget(TCFDB *fdb, int64_t id, int *sp);
		     `fdb' specifies the fixed-length database object.
		     `id'  specifies the ID number.  It	should be more than 0.
		     If	it is `FDBIDMIN', the minimum ID  number  of  existing
		     records  is  specified.  If it is `FDBIDMAX', the maximum
		     ID	number of existing records is specified.
		     `sp' specifies the	pointer	to the variable	into which the
		     size of the region	of the return value is assigned.
		     If	successful, the	return value is	the pointer to the re-
		     gion of the value of the corresponding record.  `NULL' is
		     returned if no record corresponds.
		     Because an	additional zero	code is	appended at the	end of
		     the region	of the return value, the return	value  can  be
		     treated as	a character string.  Because the region	of the
		     return value is allocated	with  the  `malloc'  call,  it
		     should  be	 released  with	 the `free' call when it is no
		     longer in use.

       The function `tcfdbget2'	is used	in order to retrieve a record  with  a
       decimal key in a	fixed-length database object.

	      void  *tcfdbget2(TCFDB  *fdb,  const  void  *kbuf, int ksiz, int
	      *sp);
		     `fdb' specifies the fixed-length database object.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum ID number of existing	records	is specified.	If  it
		     is	 "max",	 the  maximum ID number	of existing records is
		     specified.
		     `ksiz' specifies the size of the region of	the key.
		     `sp' specifies the	pointer	to the variable	into which the
		     size of the region	of the return value is assigned.
		     If	successful, the	return value is	the pointer to the re-
		     gion of the value of the corresponding record.  `NULL' is
		     returned if no record corresponds.
		     Because an	additional zero	code is	appended at the	end of
		     the region	of the return value, the return	value  can  be
		     treated as	a character string.  Because the region	of the
		     return value is allocated	with  the  `malloc'  call,  it
		     should  be	 released  with	 the `free' call when it is no
		     longer in use.

       The function `tcfdbget3'	is used	in order to retrieve a	string	record
       with a decimal key in a fixed-length database object.

	      char *tcfdbget3(TCFDB *fdb, const	char *kstr);
		     `fdb' specifies the fixed-length database object.
		     `kstr'  specifies	the  string  of	 the  decimal key.  It
		     should be more than 0.  If	it is "min",  the  minimum  ID
		     number of existing	records	is specified.  If it is	"max",
		     the maximum ID number of existing records is specified.
		     If	successful, the	return value  is  the  string  of  the
		     value of the corresponding	record.	 `NULL'	is returned if
		     no	record corresponds.
		     Because an	additional zero	code is	appended at the	end of
		     the  region  of the return	value, the return value	can be
		     treated as	a character string.  Because the region	of the
		     return  value  is	allocated  with	 the `malloc' call, it
		     should be released	with the `free'	call  when  it	is  no
		     longer in use.

       The  function  `tcfdbget4'  is  used in order to	retrieve a record in a
       fixed-length database object and	write the value	into a buffer.

	      int tcfdbget4(TCFDB *fdb,	int64_t	id, void *vbuf,	int max);
		     `fdb' specifies the fixed-length database object.
		     `id' specifies the	ID number.  It should be more than  0.
		     If	 it  is	 `FDBIDMIN', the minimum ID number of existing
		     records is	specified.  If it is `FDBIDMAX',  the  maximum
		     ID	number of existing records is specified.
		     `vbuf' specifies the pointer to the buffer	into which the
		     value of the corresponding	record is written.
		     `max' specifies the size of the buffer.
		     If	successful, the	return value is	the size of the	 writ-
		     ten  data,	 else,	it is -1.  -1 is returned if no	record
		     corresponds to the	specified key.
		     Note that an additional zero code is not appended at  the
		     end of the	region of the writing buffer.

       The  function `tcfdbvsiz' is used in order to get the size of the value
       of a record in a	fixed-length database object.

	      int tcfdbvsiz(TCFDB *fdb,	int64_t	id);
		     `fdb' specifies the fixed-length database object.
		     `id' specifies the	ID number.  It should be more than  0.
		     If	 it  is	 `FDBIDMIN', the minimum ID number of existing
		     records is	specified.  If it is `FDBIDMAX',  the  maximum
		     ID	number of existing records is specified.
		     If	 successful, the return	value is the size of the value
		     of	the corresponding record, else,	it is -1.

       The function `tcfdbvsiz2' is used in order to get the size of the value
       with a decimal key in a fixed-length database object.

	      int tcfdbvsiz2(TCFDB *fdb, const void *kbuf, int ksiz);
		     `fdb' specifies the fixed-length database object.
		     `kbuf' specifies the pointer to the region	of the decimal
		     key.  It should be	more than 0.  If it is "min", the min-
		     imum  ID  number of existing records is specified.	 If it
		     is	"max", the maximum ID number of	 existing  records  is
		     specified.
		     `ksiz' specifies the size of the region of	the key.
		     If	 successful, the return	value is the size of the value
		     of	the corresponding record, else,	it is -1.

       The function `tcfdbvsiz3' is used in order  to  get  the	 size  of  the
       string value with a decimal key in a fixed-length database object.

	      int tcfdbvsiz3(TCFDB *fdb, const char *kstr);
		     `fdb' specifies the fixed-length database object.
		     `kstr'  specifies	the  string  of	 the  decimal key.  It
		     should be more than 0.  If	it is "min",  the  minimum  ID
		     number of existing	records	is specified.  If it is	"max",
		     the maximum ID number of existing records is specified.
		     If	successful, the	return value is	the size of the	 value
		     of	the corresponding record, else,	it is -1.

       The  function `tcfdbiterinit' is	used in	order to initialize the	itera-
       tor of a	fixed-length database object.

	      bool tcfdbiterinit(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     The  iterator is used in order to access the key of every
		     record stored in a	database.

       The function `tcfdbiternext' is used in order to	get the	next ID	number
       of the iterator of a fixed-length database object.

	      uint64_t tcfdbiternext(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     If	 successful, the return	value is the next ID number of
		     the iterator, else, it is	0.   0	is  returned  when  no
		     record is to be get out of	the iterator.
		     It	 is  possible  to  access every	record by iteration of
		     calling this function.  It	is allowed to update or	remove
		     records  whose keys are fetched while the iteration.  The
		     order of this traversal access method is ascending	of the
		     ID	number.

       The  function `tcfdbiternext2' is used in order to get the next decimay
       key of the iterator of a	fixed-length database object.

	      void *tcfdbiternext2(TCFDB *fdb, int *sp);
		     `fdb' specifies the fixed-length database object.
		     `sp' specifies the	pointer	to the variable	into which the
		     size of the region	of the return value is assigned.
		     If	successful, the	return value is	the pointer to the re-
		     gion of the next decimal key, else, it is `NULL'.	`NULL'
		     is	returned when no record	is to be get out of the	itera-
		     tor.
		     Because an	additional zero	code is	appended at the	end of
		     the  region  of the return	value, the return value	can be
		     treated as	a character string.  Because the region	of the
		     return  value  is	allocated  with	 the `malloc' call, it
		     should be released	with the `free'	call  when  it	is  no
		     longer  in	use.  It is possible to	access every record by
		     iteration of calling this function.  It is	allowed	to up-
		     date  or  remove records whose keys are fetched while the
		     iteration.	 The order of this traversal access method  is
		     ascending of the ID number.

       The  function `tcfdbiternext3' is used in order to get the next decimay
       key string of the iterator of a fixed-length database object.

	      char *tcfdbiternext3(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     If	successful, the	return value is	the string of the next
		     decimal key, else,	it is `NULL'.  `NULL' is returned when
		     no	record is to be	get out	of the iterator.
		     Because the region	of the return value is allocated  with
		     the  `malloc' call, it should be released with the	`free'
		     call when it is no	longer in use.	It is possible to  ac-
		     cess  every record	by iteration of	calling	this function.
		     It	is allowed to update or	remove records whose keys  are
		     fetched while the iteration.  The order of	this traversal
		     access method is ascending	of the ID number.

       The function `tcfdbrange' is used in order to  get  range  matching  ID
       numbers in a fixed-length database object.

	      uint64_t	*tcfdbrange(TCFDB  *fdb, int64_t lower,	int64_t	upper,
	      int max, int *np);
		     `fdb' specifies the fixed-length database object.
		     `lower' specifies the lower limit of the range.  If it is
		     `FDBIDMIN', the minimum ID	is specified.
		     `upper' specifies the upper limit of the range.  If it is
		     `FDBIDMAX', the maximum ID	is specified.
		     `max' specifies the maximum number	of keys	to be fetched.
		     If	it is negative,	no limit is specified.
		     `np' specifies the	pointer	to the variable	into which the
		     number of elements	of the return value is assigned.
		     If	successful, the	return value is	the pointer to an  ar-
		     ray  of  ID numbers of the	corresponding records.	`NULL'
		     is	returned on failure.  This function does  never	 fail.
		     It	returns	an empty array even if no key corresponds.
		     Because  the region of the	return value is	allocated with
		     the `malloc' call,	it should be released with the	`free'
		     call when it is no	longer in use.

       The function `tcfdbrange2' is used in order to get range	matching deci-
       mal keys	in a fixed-length database object.

	      TCLIST *tcfdbrange2(TCFDB	*fdb,  const  void  *lbuf,  int	 lsiz,
	      const void *ubuf,	int usiz, int max);
		     `fdb' specifies the fixed-length database object.
		     `lbuf'  specifies	the pointer to the region of the lower
		     key.  If it is "min", the minimum ID number  of  existing
		     records is	specified.
		     `lsiz' specifies the size of the region of	the lower key.
		     `ubuf'  specifies	the pointer to the region of the upper
		     key.  If it is "max", the maximum ID number  of  existing
		     records is	specified.
		     `usiz' specifies the size of the region of	the upper key.
		     `max' specifies the maximum number	of keys	to be fetched.
		     If	it is negative,	no limit is specified.
		     The return	value is a list	object	of  the	 corresponding
		     decimal keys.  This function does never fail.  It returns
		     an	empty list even	if no key corresponds.
		     Because the object	of the return value  is	 created  with
		     the  function  `tclistnew', it should be deleted with the
		     function `tclistdel' when it is no	longer in  use.	  Note
		     that  this	function may be	very slow because every	key in
		     the database is scanned.

       The function `tcfdbrange3' is used in order to get range	matching deci-
       mal keys	with strings in	a fixed-length database	object.

	      TCLIST  *tcfdbrange3(TCFDB  *fdb,	 const	char *lstr, const char
	      *ustr, int max);
		     `fdb' specifies the fixed-length database object.
		     `lstr' specifies the string of the	lower key.  If	it  is
		     "min", the	minimum	ID number of existing records is spec-
		     ified.
		     `ustr' specifies the string of the	upper key.  If	it  is
		     "max", the	maximum	ID number of existing records is spec-
		     ified.
		     `max' specifies the maximum number	of keys	to be fetched.
		     If	it is negative,	no limit is specified.
		     The  return  value	 is a list object of the corresponding
		     decimal keys.  This function does never fail.  It returns
		     an	empty list even	if no key corresponds.
		     Because  the  object  of the return value is created with
		     the function `tclistnew', it should be deleted  with  the
		     function  `tclistdel'  when it is no longer in use.  Note
		     that this function	may be very slow because every key  in
		     the database is scanned.

       The  function `tcfdbrange4' is used in order to get keys	with an	inter-
       val notation in a fixed-length database object.

	      TCLIST *tcfdbrange4(TCFDB	*fdb, const void *ibuf,	int isiz,  int
	      max);
		     `fdb' specifies the fixed-length database object.
		     `ibuf'  specifies the pointer to the region of the	inter-
		     val notation.
		     `isiz' specifies the size of the region of	 the  interval
		     notation.
		     `max' specifies the maximum number	of keys	to be fetched.
		     If	it is negative,	no limit is specified.
		     The return	value is a list	object	of  the	 corresponding
		     decimal keys.  This function does never fail.  It returns
		     an	empty list even	if no key corresponds.
		     Because the object	of the return value  is	 created  with
		     the  function  `tclistnew', it should be deleted with the
		     function `tclistdel' when it is no	longer in  use.	  Note
		     that  this	function may be	very slow because every	key in
		     the database is scanned.

       The function `tcfdbrange5' is used in order to get keys with an	inter-
       val notation string in a	fixed-length database object.

	      TCLIST *tcfdbrange5(TCFDB	*fdb, const void *istr,	int max);
		     `fdb' specifies the fixed-length database object.
		     `istr'  specifies the pointer to the region of the	inter-
		     val notation string.
		     `max' specifies the maximum number	of keys	to be fetched.
		     If	it is negative,	no limit is specified.
		     The  return  value	 is a list object of the corresponding
		     decimal keys.  This function does never fail.  It returns
		     an	empty list even	if no key corresponds.
		     Because  the  object  of the return value is created with
		     the function `tclistnew', it should be deleted  with  the
		     function  `tclistdel'  when it is no longer in use.  Note
		     that this function	may be very slow because every key  in
		     the database is scanned.

       The  function  `tcfdbaddint'  is	 used  in order	to add an integer to a
       record in a fixed-length	database object.

	      int tcfdbaddint(TCFDB *fdb, int64_t id, int num);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `id'  specifies the ID number.  It	should be more than 0.
		     If	it is `FDBIDMIN', the minimum ID  number  of  existing
		     records  is  specified.  If it is `FDBIDPREV', the	number
		     less by one  than	the  minimum  ID  number  of  existing
		     records  is  specified.  If it is `FDBIDMAX', the maximum
		     ID	number of existing records is  specified.   If	it  is
		     `FDBIDNEXT',  the	number greater by one than the maximum
		     ID	number of existing records is specified.
		     `num' specifies the additional value.
		     If	successful, the	return value is	the  summation	value,
		     else, it is `INT_MIN'.
		     If	 the corresponding record exists, the value is treated
		     as	an integer and is added	to.  If	no record corresponds,
		     a new record of the additional value is stored.

       The  function `tcfdbadddouble' is used in order to add a	real number to
       a record	in a fixed-length database object.

	      double tcfdbadddouble(TCFDB *fdb,	int64_t	id, double num);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `id'  specifies the ID number.  It	should be more than 0.
		     If	it is `FDBIDMIN', the minimum ID  number  of  existing
		     records  is  specified.  If it is `FDBIDPREV', the	number
		     less by one  than	the  minimum  ID  number  of  existing
		     records  is  specified.  If it is `FDBIDMAX', the maximum
		     ID	number of existing records is  specified.   If	it  is
		     `FDBIDNEXT',  the	number greater by one than the maximum
		     ID	number of existing records is specified.
		     `num' specifies the additional value.
		     If	successful, the	return value is	the  summation	value,
		     else, it is Not-a-Number.
		     If	 the corresponding record exists, the value is treated
		     as	a real number and is added to.	If  no	record	corre-
		     sponds, a new record of the additional value is stored.

       The  function  `tcfdbsync' is used in order to synchronize updated con-
       tents of	a fixed-length database	object with the	file and the device.

	      bool tcfdbsync(TCFDB *fdb);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     This function is useful when another process connects  to
		     the same database file.

       The function `tcfdboptimize' is used in order to	optimize the file of a
       fixed-length database object.

	      bool tcfdboptimize(TCFDB *fdb, int32_t width, int64_t limsiz);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     `width'  specifies	the width of the value of each record.
		     If	it is not more than 0,	the  current  setting  is  not
		     changed.
		     `limsiz'  specifies  the limit size of the	database file.
		     If	it is not more than 0,	the  current  setting  is  not
		     changed.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcfdbvanish' is used in order to remove all records of  a
       fixed-length database object.

	      bool tcfdbvanish(TCFDB *fdb);
		     `fdb'  specifies  the  fixed-length  database object con-
		     nected as a writer.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function `tcfdbcopy' is used in order to copy the database file of
       a fixed-length database object.

	      bool tcfdbcopy(TCFDB *fdb, const char *path);
		     `fdb' specifies the fixed-length database object.
		     `path' specifies the path of the destination file.	 If it
		     begins  with `@', the trailing substring is executed as a
		     command line.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.  False is returned if the executed command returns
		     non-zero code.
		     The database file is assured to be	kept synchronized  and
		     not  modified while the copying or	executing operation is
		     in	progress.  So, this function is	 useful	 to  create  a
		     backup file of the	database file.

       The function `tcfdbtranbegin' is	used in	order to begin the transaction
       of a fixed-length database object.

	      bool tcfdbtranbegin(TCFDB	*fdb);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     The database is locked by the thread while	 the  transac-
		     tion so that only one transaction can be activated	with a
		     database object at	the same time.	Thus, the serializable
		     isolation level is	assumed	if every database operation is
		     performed in the transaction.  All	 updated  regions  are
		     kept  track  of by	write ahead logging while the transac-
		     tion.  If the database is closed during transaction,  the
		     transaction is aborted implicitly.

       The  function `tcfdbtrancommit' is used in order	to commit the transac-
       tion of a fixed-length database object.

	      bool tcfdbtrancommit(TCFDB *fdb);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Update in the transaction is fixed	when it	 is  committed
		     successfully.

       The function `tcfdbtranabort' is	used in	order to abort the transaction
       of a fixed-length database object.

	      bool tcfdbtranabort(TCFDB	*fdb);
		     `fdb' specifies the  fixed-length	database  object  con-
		     nected as a writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Update  in	 the  transaction  is  discarded  when	it  is
		     aborted.	The state of the database is rollbacked	to be-
		     fore transaction.

       The function `tcfdbpath'	is used	in order to get	the  file  path	 of  a
       fixed-length database object.

	      const char *tcfdbpath(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     The  return  value	 is  the  path of the database file or
		     `NULL' if the object does not  connect  to	 any  database
		     file.

       The  function `tcfdbrnum' is used in order to get the number of records
       of a fixed-length database object.

	      uint64_t tcfdbrnum(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     The return	value is the number of records or 0 if the ob-
		     ject does not connect to any database file.

       The  function `tcfdbfsiz' is used in order to get the size of the data-
       base file of a fixed-length database object.

	      uint64_t tcfdbfsiz(TCFDB *fdb);
		     `fdb' specifies the fixed-length database object.
		     The return	value is the size of the database file or 0 if
		     the object	does not connect to any	database file.

SEE ALSO
       tcftest(1), tcfmttest(1), tcfmgr(1), tokyocabinet(3)

Man Page			  2012-08-18			      TCFDB(3)

NAME | DESCRIPTION | API | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tcfdb&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help