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

FreeBSD Manual Pages

  
 
  

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

NAME
       tctdb - the table database API

DESCRIPTION
       Table  database	is  a  file containing records composed	of the primary
       keys and	arbitrary columns and is handled with the table	database API.

       To use the table	database API, include `tcutil.h', `tctdb.h',  and  re-
       lated  standard header files.  Usually, write the following description
       near the	front of a source file.

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

       Objects whose type is pointer to	`TCTDB'	are used to handle table data-
       bases.  A table database	object is created with the function `tctdbnew'
       and is deleted with the function	`tctdbdel'.  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 table database object to	it.  The func-
       tion `tctdbopen'	is used	to open	a database file	and the	function `tct-
       dbclose'	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	objects	 in  a
       process to open the same	database at the	same time.

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

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

       The function `tctdbnew' is used in order	to create a table database ob-
       ject.

	      TCTDB *tctdbnew(void);
		     The return	value is the new table database	object.

       The function `tctdbdel' is used in order	to delete a table database ob-
       ject.

	      void tctdbdel(TCTDB *tdb);
		     `tdb' specifies the table 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 `tctdbecode' is used in order to get the last happened er-
       ror code	of a table database object.

	      int tctdbecode(TCTDB *tdb);
		     `tdb' specifies the table 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 `tctdbsetmutex' is used in order to	set  mutual  exclusion
       control of a table database object for threading.

	      bool tctdbsetmutex(TCTDB *tdb);
		     `tdb'  specifies  the  table 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 `tctdbtune' is used in order to set the tuning parameters
       of a table database object.

	      bool tctdbtune(TCTDB *tdb, int64_t  bnum,	 int8_t	 apow,	int8_t
	      fpow, uint8_t opts);
		     `tdb'  specifies  the  table database object which	is not
		     opened.
		     `bnum' specifies the number of elements of	the bucket ar-
		     ray.   If	it  is	not  more than 0, the default value is
		     specified.	 The default value is 131071.  Suggested  size
		     of	 the  bucket array is about from 0.5 to	4 times	of the
		     number of all records to be stored.
		     `apow' specifies the size of record alignment by power of
		     2.	  If  it  is negative, the default value is specified.
		     The default value is 4 standing for 2^4=16.
		     `fpow' specifies the maximum number of  elements  of  the
		     free  block  pool	by power of 2.	If it is negative, the
		     default value is specified.   The	default	 value	is  10
		     standing for 2^10=1024.
		     `opts' specifies options by bitwise-or: `TDBTLARGE' spec-
		     ifies that	the size of the	database can  be  larger  than
		     2GB by using 64-bit bucket	array, `TDBTDEFLATE' specifies
		     that each record is  compressed  with  Deflate  encoding,
		     `TDBTBZIP'	 specifies that	each record is compressed with
		     BZIP2 encoding, `TDBTTCBS'	specifies that each record  is
		     compressed	with TCBS encoding.
		     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  `tctdbsetcache' is set the caching parameters of a table
       database	object.

	      bool tctdbsetcache(TCTDB *tdb,  int32_t  rcnum,  int32_t	lcnum,
	      int32_t ncnum);
		     `tdb'  specifies  the  table database object which	is not
		     opened.
		     `rcnum' specifies the maximum number  of  records	to  be
		     cached.   If  it  is not more than	0, the record cache is
		     disabled.	It is disabled by default.
		     `lcnum' specifies the maximum number of leaf nodes	to  be
		     cached.   If  it is not more than 0, the default value is
		     specified.	 The default value is 4096.
		     `ncnum' specifies the maximum number of non-leaf nodes to
		     be	 cached.   If it is not	more than 0, the default value
		     is	specified.  The	default	value is 512.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     Note that the caching parameters should be	set before the
		     database is opened.  Leaf nodes and  non-leaf  nodes  are
		     used in column indices.

       The  function  `tctdbsetxmsiz'  is used in order	to set the size	of the
       extra mapped memory of a	table database object.

	      bool tctdbsetxmsiz(TCTDB *tdb, int64_t xmsiz);
		     `tdb' specifies the table database	object	which  is  not
		     opened.
		     `xmsiz'  specifies	 the  size of the extra	mapped memory.
		     If	it is not more than 0, the extra mapped	memory is dis-
		     abled.  The default size is 67108864.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Note that the mapping parameters should be	set before the
		     database is opened.

       The  function  `tctdbsetdfunit'	is  used in order to set the unit step
       number of auto defragmentation of a table database object.

	      bool tctdbsetdfunit(TCTDB	*tdb, int32_t dfunit);
		     `tdb' specifies the table database	object	which  is  not
		     opened.
		     `dfunit'  specifie	 the  unit  step number.  If it	is not
		     more than 0, the auto defragmentation is disabled.	 It is
		     disabled by default.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Note that the defragmentation parameters  should  be  set
		     before the	database is opened.

       The  function  `tctdbopen' is used in order to open a database file and
       connect a table database	object.

	      bool tctdbopen(TCTDB *tdb, const char *path, int omode);
		     `tdb' specifies the table database	object	which  is  not
		     opened.
		     `path' specifies the path of the database file.
		     `omode'  specifies	the connection mode: `TDBOWRITER' as a
		     writer, `TDBOREADER' as a reader.	If the	mode  is  `TD-
		     BOWRITER',	the following may be added by bitwise-or: `TD-
		     BOCREAT', which means it creates a	new  database  if  not
		     exist, `TDBOTRUNC', which means it	creates	a new database
		     regardless	if one exists, `TDBOTSYNC', which means	 every
		     transaction  synchronizes	updated	 contents with the de-
		     vice.  Both of `TDBOREADER' and `TDBOWRITER' can be added
		     to	 by  bitwise-or: `TDBONOLCK', which means it opens the
		     database file without file	locking, or `TDBOLCKNB', which
		     means locking is performed	without	blocking.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tctdbclose' is used in order to close  a  table  database
       object.

	      bool tctdbclose(TCTDB *tdb);
		     `tdb' specifies the table 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 `tctdbput' is used in order	to store a record into a table
       database	object.

	      bool tctdbput(TCTDB *tdb,	const void *pkbuf,  int	 pksiz,	 TCMAP
	      *cols);
		     `tdb'  specifies the table	database object	connected as a
		     writer.
		     `pkbuf' specifies the pointer to the region of  the  pri-
		     mary key.
		     `pksiz'  specifies	 the size of the region	of the primary
		     key.
		     `cols' specifies a	map object containing columns.
		     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 `tctdbput2'	is used	in order to store a string record into
       a table database	object with a zero separated column string.

	      bool  tctdbput2(TCTDB  *tdb, const void *pkbuf, int pksiz, const
	      void *cbuf, int csiz);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkbuf'  specifies	 the pointer to	the region of the pri-
		     mary key.
		     `pksiz' specifies the size	of the region of  the  primary
		     key.
		     `cbuf'  specifies	the  pointer to	the region of the zero
		     separated column string where the name and	the  value  of
		     each column are situated one after	the other.
		     `csiz'  specifies	the  size  of the region of the	column
		     string.
		     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 `tctdbput3'	is used	in order to store a string record into
       a table database	object with a tab separated column string.

	      bool tctdbput3(TCTDB *tdb, const char *pkstr, const char *cstr);
		     `tdb'  specifies the table	database object	connected as a
		     writer.
		     `pkstr' specifies the string of the primary key.
		     `cstr' specifies the string of the	the tab	separated col-
		     umn  string  where	 the name and the value	of each	column
		     are situated one after the	other.
		     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 `tctdbputkeep' is used in order to store a new record into
       a table database	object.

	      bool  tctdbputkeep(TCTDB	*tdb,  const  void  *pkbuf, int	pksiz,
	      TCMAP *cols);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkbuf'  specifies	 the pointer to	the region of the pri-
		     mary key.
		     `pksiz' specifies the size	of the region of  the  primary
		     key.
		     `cols' specifies a	map object containing columns.
		     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  `tctdbputkeep2'  is  used	in order to store a new	string
       record into a table  database  object  with  a  zero  separated	column
       string.

	      bool  tctdbputkeep2(TCTDB	 *tdb,	const  void *pkbuf, int	pksiz,
	      const void *cbuf,	int csiz);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkbuf'  specifies	 the pointer to	the region of the pri-
		     mary key.
		     `pksiz' specifies the size	of the region of  the  primary
		     key.
		     `cbuf'  specifies	the  pointer to	the region of the zero
		     separated column string where the name and	the  value  of
		     each column are situated one after	the other.
		     `csiz'  specifies	the  size  of the region of the	column
		     string.
		     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 `tctdbputkeep3' is used in order to	 store	a  new	string
       record into a table database object with	a tab separated	column string.

	      bool  tctdbputkeep3(TCTDB	 *tdb,	const  char *pkstr, const char
	      *cstr);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkstr' specifies the string of the primary key.
		     `cstr' specifies the string of the	the tab	separated col-
		     umn string	where the name and the value  of  each	column
		     are situated one after the	other.
		     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  `tctdbputcat' is used in order to	concatenate columns of
       the existing record in a	table database object.

	      bool tctdbputcat(TCTDB *tdb, const void *pkbuf, int pksiz, TCMAP
	      *cols);
		     `tdb'  specifies the table	database object	connected as a
		     writer.
		     `pkbuf' specifies the pointer to the region of  the  pri-
		     mary key.
		     `pksiz'  specifies	 the size of the region	of the primary
		     key.
		     `cols' specifies a	map object containing columns.
		     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 `tctdbputcat2' is used in order to concatenate columns  in
       a table database	object with a zero separated column string.

	      bool  tctdbputcat2(TCTDB	*tdb,  const  void  *pkbuf, int	pksiz,
	      const void *cbuf,	int csiz);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkbuf'  specifies	 the pointer to	the region of the pri-
		     mary key.
		     `pksiz' specifies the size	of the region of  the  primary
		     key.
		     `cbuf'  specifies	the  pointer to	the region of the zero
		     separated column string where the name and	the  value  of
		     each column are situated one after	the other.
		     `csiz'  specifies	the  size  of the region of the	column
		     string.
		     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 `tctdbputcat3' is used in order to concatenate columns  in
       a table database	object with with a tab separated column	string.

	      bool  tctdbputcat3(TCTDB	*tdb,  const  char  *pkstr, const char
	      *cstr);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkstr' specifies the string of the primary key.
		     `cstr' specifies the string of the	the tab	separated col-
		     umn string	where the name and the value  of  each	column
		     are situated one after the	other.
		     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 `tctdbout'	is used	in order to remove a record of a table
       database	object.

	      bool tctdbout(TCTDB *tdb,	const void *pkbuf, int pksiz);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `pkbuf'  specifies	 the pointer to	the region of the pri-
		     mary key.
		     `pksiz' specifies the size	of the region of  the  primary
		     key.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tctdbout2'	is used	in order to remove a string record  of
       a table database	object.

	      bool tctdbout2(TCTDB *tdb, const char *pkstr);
		     `tdb'  specifies the table	database object	connected as a
		     writer.
		     `pkstr' specifies the string of the primary key.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function `tctdbget'	is used	in order to retrieve a record in a ta-
       ble database object.

	      TCMAP *tctdbget(TCTDB *tdb, const	void *pkbuf, int pksiz);
		     `tdb' specifies the table database	object.
		     `pkbuf' specifies the pointer to the region of  the  pri-
		     mary key.
		     `pksiz'  specifies	 the size of the region	of the primary
		     key.
		     If	successful, the	return value is	a map  object  of  the
		     columns  of the corresponding record.  `NULL' is returned
		     if	no record corresponds.
		     Because the object	of the return value  is	 created  with
		     the  function  `tcmapnew',	 it should be deleted with the
		     function `tcmapdel' when it is no longer in use.

       The function `tctdbget2'	is used	in order to retrieve a record in a ta-
       ble database object as a	zero separated column string.

	      char  *tctdbget2(TCTDB  *tdb,  const void	*pkbuf,	int pksiz, int
	      *sp);
		     `tdb' specifies the table database	object.
		     `pkbuf' specifies the pointer to the region of  the  pri-
		     mary key.
		     `pksiz'  specifies	 the size of the region	of the primary
		     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 column	string 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 `tctdbget3'	is used	in order to retrieve a	string	record
       in a table database object as a tab separated column string.

	      char *tctdbget3(TCTDB *tdb, const	char *pkstr);
		     `tdb' specifies the table database	object.
		     `pkstr' specifies the string of the primary key.
		     If	successful, the	return value is	the tab	separated col-
		     umn string	of the corresponding record.   `NULL'  is  re-
		     turned if no record 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 `tctdbvsiz' is used in order to get the size of the value
       of a record in a	table database object.

	      int tctdbvsiz(TCTDB *tdb,	const void *pkbuf, int pksiz);
		     `tdb' specifies the table database	object.
		     `kbuf' specifies the pointer to the region	of the primary
		     key.
		     `ksiz'  specifies	the  size of the region	of the primary
		     key.
		     If	successful, the	return value is	the size of the	 value
		     of	the corresponding record, else,	it is -1.

       The function `tctdbvsiz2' is used in order to get the size of the value
       of a string record in a table database object.

	      int tctdbvsiz2(TCTDB *tdb, const char *pkstr);
		     `tdb' specifies the table database	object.
		     `kstr' specifies the string of the	primary	key.
		     If	successful, the	return value is	the size of the	 value
		     of	the corresponding record, else,	it is -1.

       The  function `tctdbiterinit' is	used in	order to initialize the	itera-
       tor of a	table database object.

	      bool tctdbiterinit(TCTDB *tdb);
		     `tdb' specifies the table database	object.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     The  iterator  is used in order to	access the primary key
		     of	every record stored in a database.

       The function `tctdbiternext' is used in order to	get the	 next  primary
       key of the iterator of a	table database object.

	      void *tctdbiternext(TCTDB	*tdb, int *sp);
		     `tdb' specifies the table 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 primary 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.	  However,  it	is not assured if updating the
		     database is occurred while	the iteration.	 Besides,  the
		     order of this traversal access method is arbitrary, so it
		     is	not assured that the order of storing matches the  one
		     of	the traversal access.

       The  function `tctdbiternext2' is used in order to get the next primary
       key string of the iterator of a table database object.

	      char *tctdbiternext2(TCTDB *tdb);
		     `tdb' specifies the table database	object.
		     If	successful, the	return value is	the string of the next
		     primary 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.
		     However, it is not	assured	if updating  the  database  is
		     occurred while the	iteration.  Besides, the order of this
		     traversal access method is	arbitrary, so it  is  not  as-
		     sured  that  the  order of	storing	matches	the one	of the
		     traversal access.

       The function `tctdbiternext3' is	used in	order to get  the  columns  of
       the next	record of the iterator of a table database object.

	      TCMAP *tctdbiternext3(TCTDB *tdb);
		     `tdb' specifies the table database	object.
		     If	 successful,  the  return value	is a map object	of the
		     columns of	the next record, else, it is  `NULL'.	`NULL'
		     is	returned when no record	is to be get out of the	itera-
		     tor.  The primary key is added into the map as  a	column
		     of	an empty string	key.
		     Because  the  object  of the return value is created with
		     the function `tcmapnew', it should	be  deleted  with  the
		     function  `tcmapdel'  when	it is no longer	in use.	 It is
		     possible to access	every record by	iteration  of  calling
		     this  function.   However,	 it is not assured if updating
		     the database is occurred while the	 iteration.   Besides,
		     the  order	 of this traversal access method is arbitrary,
		     so	it is not assured that the order  of  storing  matches
		     the one of	the traversal access.

       The  function  `tctdbfwmkeys'  is used in order to get forward matching
       primary keys in a table database	object.

	      TCLIST *tctdbfwmkeys(TCTDB *tdb, const void *pbuf, int psiz, int
	      max);
		     `tdb' specifies the table database	object.
		     `pbuf' specifies the pointer to the region	of the prefix.
		     `psiz' specifies the size of the region of	the prefix.
		     `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
		     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 `tctdbfwmkeys2' is used in order to	get  forward  matching
       string primary keys in a	table database object.

	      TCLIST *tctdbfwmkeys2(TCTDB *tdb,	const char *pstr, int max);
		     `tdb' specifies the table database	object.
		     `pstr' specifies the string of the	prefix.
		     `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
		     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 `tctdbaddint' is used in order to add an integer to	a col-
       umn of a	record in a table database object.

	      int  tctdbaddint(TCTDB  *tdb,  const void	*pkbuf,	int pksiz, int
	      num);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `kbuf' specifies the pointer to the region	of the primary
		     key.
		     `ksiz' specifies the size of the region  of  the  primary
		     key.
		     `num' specifies the additional value.
		     If	 successful,  the return value is the summation	value,
		     else, it is `INT_MIN'.
		     The additional value is stored as a decimal string	 value
		     of	 a  column  whose name is "_num".  If no record	corre-
		     sponds, a new record with the additional value is stored.

       The function `tctdbadddouble' is	used in	order to add a real number  to
       a column	of a record in a table database	object.

	      double  tctdbadddouble(TCTDB *tdb, const void *pkbuf, int	pksiz,
	      double num);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `kbuf' specifies the pointer to the region	of the primary
		     key.
		     `ksiz' specifies the size of the region  of  the  primary
		     key.
		     `num' specifies the additional value.
		     If	 successful,  the return value is the summation	value,
		     else, it is Not-a-Number.
		     The additional value is stored as a decimal string	 value
		     of	 a  column  whose name is "_num".  If no record	corre-
		     sponds, a new record with the additional value is stored.

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

	      bool tctdbsync(TCTDB *tdb);
		     `tdb'  specifies the table	database object	connected 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 `tctdboptimize' is used in order to	optimize the file of a
       table database object.

	      bool tctdboptimize(TCTDB *tdb, int64_t bnum, int8_t apow,	int8_t
	      fpow, uint8_t opts);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `bnum' specifies the number of elements of	the bucket ar-
		     ray.  If it is not	more than  0,  the  default  value  is
		     specified.	  The default value is two times of the	number
		     of	records.
		     `apow' specifies the size of record alignment by power of
		     2.	  If  it  is  negative,	 the  current  setting	is not
		     changed.
		     `fpow' specifies the maximum number of  elements  of  the
		     free  block  pool	by power of 2.	If it is negative, the
		     current setting is	not changed.
		     `opts' specifies options by bitwise-or: `TDBTLARGE' spec-
		     ifies  that  the  size of the database can	be larger than
		     2GB by using 64-bit bucket	array, `TDBTDEFLATE' specifies
		     that  each	 record	 is  compressed	with Deflate encoding,
		     `TDBTBZIP'	specifies that each record is compressed  with
		     BZIP2  encoding, `TDBTTCBS' specifies that	each record is
		     compressed	with TCBS encoding.  If	it is `UINT8_MAX', the
		     current setting is	not changed.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     This function is useful to	reduce the size	of  the	 data-
		     base file with data fragmentation by successive updating.

       The  function `tctdbvanish' is used in order to remove all records of a
       table database object.

	      bool tctdbvanish(TCTDB *tdb);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tctdbcopy'	is used	in order to copy the database file  of
       a table database	object.

	      bool tctdbcopy(TCTDB *tdb, const char *path);
		     `tdb' specifies the table 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 `tctdbtranbegin' is	used in	order to begin the transaction
       of a table database object.

	      bool tctdbtranbegin(TCTDB	*tdb);
		     `tdb'  specifies the table	database object	connected 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.	Because	 all pages are
		     cached on memory while the	transaction, the amount	of re-
		     ferred records is limited by the memory capacity.	If the
		     database is closed	during transaction, the	transaction is
		     aborted implicitly.

       The  function `tctdbtrancommit' is used in order	to commit the transac-
       tion of a table database	object.

	      bool tctdbtrancommit(TCTDB *tdb);
		     `tdb' specifies the table database	object connected 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 `tctdbtranabort' is	used in	order to abort the transaction
       of a table database object.

	      bool tctdbtranabort(TCTDB	*tdb);
		     `tdb' specifies the table database	object connected 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 `tctdbpath'	is used	in order to get	the file path of a ta-
       ble database object.

	      const char *tctdbpath(TCTDB *tdb);
		     `tdb' specifies the table 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 `tctdbrnum' is used in order to get the number of records
       ccccof a	table database object.

	      uint64_t tctdbrnum(TCTDB *tdb);
		     `tdb' specifies the table 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 `tctdbfsiz' is used in order to get the size of the data-
       base file of a table database object.

	      uint64_t tctdbfsiz(TCTDB *tdb);
		     `tdb' specifies the table database	object.
		     The return	value is the size of the database file or 0 if
		     the object	does not connect to any	database file.

       The  function `tctdbsetindex' is	used in	order to set a column index to
       a table database	object.

	      bool tctdbsetindex(TCTDB *tdb, const char	*name, int type);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     `name' specifies the name of a column.  If	the name of an
		     existing index is specified, the index  is	 rebuilt.   An
		     empty string means	the primary key.
		     `type' specifies the index	type: `TDBITLEXICAL' for lexi-
		     cal string, `TDBITDECIMAL'	for decimal string,  `TDBITTO-
		     KEN'  for	token  inverted	index, `TDBITQGRAM' for	q-gram
		     inverted index.  If it is `TDBITOPT', the index is	 opti-
		     mized.   If  it is	`TDBITVOID', the index is removed.  If
		     `TDBITKEEP' is added by bitwise-or	and the	index  exists,
		     this function merely returns failure.
		     If	 successful,  the  return  value  is true, else, it is
		     false.
		     Note that the setting indices should  be  set  after  the
		     database is opened.

       The  function  `tctdbgenuid'  is	 used in order to generate a unique ID
       number of a table database object.

	      int64_t tctdbgenuid(TCTDB	*tdb);
		     `tdb' specifies the table database	object connected as  a
		     writer.
		     The  return  value	 is  the new unique ID number or -1 on
		     failure.

       The function `tctdbqrynew' is used in order to create a query object.

	      TDBQRY *tctdbqrynew(TCTDB	*tdb);
		     `tdb' specifies the table database	object.
		     The return	value is the new query object.

       The function `tctdbqrydel' is used in order to delete a query object.

	      void tctdbqrydel(TDBQRY *qry);
		     `qry' specifies the query object.

       The function `tctdbqryaddcond' is used in order to add a	narrowing con-
       dition to a query object.

	      void  tctdbqryaddcond(TDBQRY  *qry,  const  char	*name, int op,
	      const char *expr);
		     `qry' specifies the query object.
		     `name' specifies the name of a column.  An	 empty	string
		     means the primary key.
		     `op' specifies an operation type: `TDBQCSTREQ' for	string
		     which is  equal  to  the  expression,  `TDBQCSTRINC'  for
		     string  which is included in the expression, `TDBQCSTRBW'
		     for string	which begins with the expression, `TDBQCSTREW'
		     for  string which ends with the expression, `TDBQCSTRAND'
		     for string	which includes all tokens in  the  expression,
		     `TDBQCSTROR' for string which includes at least one token
		     in	the expression,	`TDBQCSTROREQ'	for  string  which  is
		     equal  to	at  least one token in the expression, `TDBQC-
		     STRRX' for	string which matches  regular  expressions  of
		     the expression, `TDBQCNUMEQ' for number which is equal to
		     the expression, `TDBQCNUMGT' for number which is  greater
		     than  the	expression,  `TDBQCNUMGE'  for number which is
		     greater than or equal to the expression, `TDBQCNUMLT' for
		     number  which  is	less than the expression, `TDBQCNUMLE'
		     for number	which is less than or equal to the expression,
		     `TDBQCNUMBT'  for	number	which is between two tokens of
		     the expression, `TDBQCNUMOREQ' for	number which is	 equal
		     to	at least one token in the expression, `TDBQCFTSPH' for
		     full-text search with the phrase of the expression,  `TD-
		     BQCFTSAND'	 for  full-text	 search	with all tokens	in the
		     expression, `TDBQCFTSOR' for  full-text  search  with  at
		     least  one	 token	in  the	 expression,  `TDBQCFTSEX' for
		     full-text search with the compound	expression.  All oper-
		     ations  can  be  flagged by bitwise-or: `TDBQCNEGATE' for
		     negation, `TDBQCNOIDX' for	using no index.
		     `expr' specifies an operand exression.

       The function `tctdbqrysetorder' is used in order	to set the order of  a
       query object.

	      void tctdbqrysetorder(TDBQRY *qry, const char *name, int type);
		     `qry' specifies the query object.
		     `name'  specifies	the name of a column.  An empty	string
		     means the primary key.
		     `type' specifies the order	type: `TDBQOSTRASC' for	string
		     ascending,	`TDBQOSTRDESC' for string descending, `TDBQON-
		     UMASC' for	number ascending,  `TDBQONUMDESC'  for	number
		     descending.

       The  function `tctdbqrysetlimit'	is used	in order to set	the limit num-
       ber of records of the result of a query object.

	      void tctdbqrysetlimit(TDBQRY *qry, int max, int skip);
		     `qry' specifies the query object.
		     `max' specifies the maximum number	of records of the  re-
		     sult.  If it is negative, no limit	is specified.
		     `skip' specifies the number of skipped records of the re-
		     sult.  If it is not more than 0, no record	is skipped.

       The function `tctdbqrysearch' is	used in	order to execute the search of
       a query object.

	      TCLIST *tctdbqrysearch(TDBQRY *qry);
		     `qry' specifies the query object.
		     The  return value is a list object	of the primary keys of
		     the corresponding	records.   This	 function  does	 never
		     fail.   It	returns	an empty list even if no record	corre-
		     sponds.
		     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.

       The function `tctdbqrysearchout'	is used	in order to remove each	record
       corresponding to	a query	object.

	      bool tctdbqrysearchout(TDBQRY *qry);
		     `qry'  specifies  the  query  object of the database con-
		     nected as a writer.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tctdbqryproc'  is  used in order	to process each	record
       corresponding to	a query	object.

	      bool tctdbqryproc(TDBQRY *qry, TDBQRYPROC	proc, void *op);
		     `qry' specifies the query object  of  the	database  con-
		     nected as a writer.
		     `proc'  specifies	the  pointer  to the iterator function
		     called for	each record.   It  receives  four  parameters.
		     The  first	 parameter is the pointer to the region	of the
		     primary key.  The second parameter	is the size of the re-
		     gion  of  the  primary key.  The third parameter is a map
		     object containing columns.	 The fourth parameter  is  the
		     pointer  to the optional opaque object.  It returns flags
		     of	the post treatment by bitwise-or: `TDBQPPUT' to	modify
		     the  record, `TDBQPOUT' to	remove the record, `TDBQPSTOP'
		     to	stop the iteration.
		     `op' specifies an arbitrary pointer to be given as	a  pa-
		     rameter  of  the iterator function.  If it	is not needed,
		     `NULL' can	be specified.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function `tctdbqryhint' is used in order to	get the	hint string of
       a query object.

	      const char *tctdbqryhint(TDBQRY *qry);
		     `qry' specifies the query object.
		     The return	value is the hint string.

       The function `tctdbmetasearch' is used in  order	 to  retrieve  records
       with multiple query objects and get the set of the result.

	      TCLIST *tctdbmetasearch(TDBQRY **qrys, int num, int type);
		     `qrys' specifies an array of the query objects.
		     `num' specifies the number	of elements of the array.
		     `type'  specifies	a set operation	type: `TDBMSUNION' for
		     the union set, `TDBMSISECT'  for  the  intersection  set,
		     `TDBMSDIFF' for the difference set.
		     The  return value is a list object	of the primary keys of
		     the corresponding	records.   This	 function  does	 never
		     fail.   It	returns	an empty list even if no record	corre-
		     sponds.
		     If	the first query	object has the order setting, the  re-
		     sult array	is sorted by the order.	 Because the object of
		     the return	value is created with  the  function  `tclist-
		     new',  it should be deleted with the function `tclistdel'
		     when it is	no longer in use.

SEE ALSO
       tcttest(1), tctmttest(1), tctmgr(1), tokyocabinet(3)

Man Page			  2012-08-18			      TCTDB(3)

NAME | DESCRIPTION | API | SEE ALSO

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

home | help