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

FreeBSD Manual Pages

  
 
  

home | help
TCWDB(3)			Tokyo Dystopia			      TCWDB(3)

NAME
       tcwdb - the word	database API

DESCRIPTION
       Word  database  is  a  file  containing index of	text.  The key of each
       record is a positive number.  The value of each record  is  a  list  of
       words  whose  encoding is UTF-8.	 Note that word	database is pure index
       and does	not contain entity of records.	See `tcwdb.h' for entire spec-
       ification.

       To  use	the  word database API,	include	`tcwdb.h' and related standard
       header files.  Usually, write the following description near the	 front
       of a source file.

	      #include <tcwdb.h>
	      #include <stdlib.h>
	      #include <stdbool.h>
	      #include <stdint.h>

       Objects	whose type is pointer to `TCWDB' are used to handle word data-
       bases.  A remote	database object	is created with	the  function  `tcwdb-
       new'  and  is  deleted  with  the function `tcwdbdel'.  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 word database object to it.  The	 func-
       tion  `tcwdbopen'  is  used  to	open  a	database file and the function
       `tcwdbclose' 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.

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

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

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

	      TCWDB *tcwdbnew(void);
		     The return	value is the new word database object.

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

	      void tcwdbdel(TCWDB *wdb);
		     `wdb' specifies the word 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 `tcwdbecode' is used in order to get the last happened er-
       ror code	of a word database object.

	      int tcwdbecode(TCWDB *wdb);
		     `wdb' specifies the word database object.
		     The return	value is the last happened error code.
		     The following error code  is  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 `tcwdbtune' is used in order to set the tuning parameters
       of a word database object.

	      bool tcwdbtune(TCWDB *wdb, int64_t etnum,	uint8_t	opts);
		     `wdb' specifies the word database	object	which  is  not
		     opened.
		     `etnum'  specifies	 the  expected	number of tokens to be
		     stored.  If it is not more	than 0,	the default  value  is
		     specified.	 The default value is 1000000.
		     `opts' specifies options by bitwise-or: `WDBTLARGE' spec-
		     ifies that	the size of the	database can  be  larger  than
		     2GB by using 64-bit bucket	array, `WDBTDEFLATE' specifies
		     that each	page  is  compressed  with  Deflate  encoding,
		     `WDBTBZIP'	 specifies  that  each page is compressed with
		     BZIP2 encoding, `WDBTTCBS'	specifies that	each  page  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 `tcwdbsetcache' is used in order to	set the	caching	param-
       eters of	a word database	object.

	      bool tcwdbsetcache(TCWDB *wdb, int64_t icsiz, int32_t lcnum);
		     `wdb' specifies the word database	object	which  is  not
		     opened.
		     `icsiz'  specifies	 the capacity size of the token	cache.
		     If	it is not more than 0, the default value is specified.
		     The default value is 134217728.
		     `lcnum' specifies the maximum number of cached leaf nodes
		     of	B+ tree.  If it	is not more than 0, the	default	 value
		     is	specified.  The	default	value is 64 for	writer or 1024
		     for reader.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     Note that the caching parameters should be	set before the
		     database is opened.

       The function `tcwdbsetfwmmax' is	used in	order to set the maximum  num-
       ber of forward matching expansion of a word database object.

	      bool tcwdbsetfwmmax(TCWDB	*wdb, uint32_t fwmmax);
		     `wdb' specifies the word database object.
		     `fwmmax' specifies	the maximum number of forward matching
		     expansion.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     Note  that	 the  matching parameters should be set	before
		     the database is opened.

       The function `tcwdbopen'	is used	in order to open a word	 database  ob-
       ject.

	      bool tcwdbopen(TCWDB *wdb, const char *path, int omode);
		     `wdb' specifies the word database object.
		     `path' specifies the path of the database file.
		     `omode'  specifies	the connection mode: `WDBOWRITER' as a
		     writer, `WDBOREADER' as a reader.	If the	mode  is  `WD-
		     BOWRITER',	the following may be added by bitwise-or: `WD-
		     BOCREAT', which means it creates a	new  database  if  not
		     exist, `WDBOTRUNC', which means it	creates	a new database
		     regardless	if one exists.	Both of	`WDBOREADER' and  `WD-
		     BOWRITER'	can  be	 added	to by bitwise-or: `WDBONOLCK',
		     which means it opens the database file without file lock-
		     ing,  or  `WDBOLCKNB',  which  means locking is performed
		     without blocking.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The function `tcwdbclose' is used in order to close a word database ob-
       ject.

	      bool tcwdbclose(TCWDB *wdb);
		     `wdb' specifies the word 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 `tcwdbput' is used in order	to store a record into a  word
       database	object.

	      bool tcwdbput(TCWDB *wdb,	int64_t	id, const TCLIST *words);
		     `wdb'  specifies  the word	database object	connected as a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     `words' specifies a list object contains the words	of the
		     record, whose encoding should be UTF-8.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The function `tcwdbput2'	is used	in order to store a record with	a text
       string into a word database object.

	      bool tcwdbput2(TCWDB *wdb, int64_t id, const char	 *text,	 const
	      char *delims);
		     `wdb'  specifies  the word	database object	connected as a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     `text' specifies the string of the	record,	whose encoding
		     should be UTF-8.
		     `delims' specifies	a string containing delimiting charac-
		     ters  of the text.	 If it is `NULL', space	characters are
		     specified.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tcwdbout' is used in order to remove a record of	a word
       database	object.

	      bool tcwdbout(TCWDB *wdb,	int64_t	id, const TCLIST *words);
		     `wdb' specifies the word database object connected	 as  a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     `words' specifies a list object contains the words	of the
		     record, which should be same as the stored	ones.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcwdbout2'	is used	in order to remove  a  record  with  a
       text string of a	word database object.

	      bool  tcwdbout2(TCWDB  *wdb, int64_t id, const char *text, const
	      char *delims);
		     `wdb' specifies the word database object connected	 as  a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     `text' specifies the string of the	record,	 which	should
		     be	same as	the stored one.
		     `delims' specifies	a string containing delimiting charac-
		     ters of the text.	If it is `NULL', space characters  are
		     specified.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcwdbsearch' is used in order to search a word database.

	      uint64_t *tcwdbsearch(TCWDB *wdb,	const char *word, int *np);
		     `wdb' specifies the word database object.
		     `word' specifies the string of the	word to	be matched to.
		     `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.
		     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  `tcwdbsync' is used in order to synchronize updated con-
       tents of	a word database	object with the	file and the device.

	      bool tcwdbsync(TCWDB *wdb);
		     `wdb' specifies the word 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 the
		     same database file.

       The function `tcwdboptimize' is used in order to	optimize the file of a
       word database object.

	      bool tcwdboptimize(TCWDB *wdb);
		     `wdb' specifies the word database object connected	 as  a
		     writer.
		     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 `tcwdbvanish' is used in order to remove all records of a
       word database object.

	      bool tcwdbvanish(TCWDB *wdb);
		     `wdb' specifies the word database object connected	 as  a
		     writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

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

	      bool tcwdbcopy(TCWDB *wdb, const char *path);
		     `wdb' specifies the word 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 `tcwdbpath'	is used	in order to get	the  file  path	 of  a
       word database object.

	      const char *tcwdbpath(TCWDB *wdb);
		     `wdb' specifies the word 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  `tcwdbtnum' is used in order to get the number of	tokens
       of a word database object.

	      uint64_t tcwdbtnum(TCWDB *wdb);
		     `wdb' specifies the word database object.
		     The return	value is the number of tokens or 0 if the  ob-
		     ject does not connect to any database file.

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

	      uint64_t tcwdbfsiz(TCWDB *wdb);
		     `wdb' specifies the word 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
       tcwtest(1), tcwmgr(1), laputa(3)

Man Page			  2010-08-05			      TCWDB(3)

NAME | DESCRIPTION | API | SEE ALSO

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

home | help