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

FreeBSD Manual Pages

  
 
  

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

NAME
       laputa -	the simple API

DESCRIPTION
       Tagged  database	is a directory containing a hash database file and its
       tagging files.  The key of each record is a positive number.  The value
       of  each	record is an arbitrary text data whose encoding	is UTF-8.  See
       `laputa.h' for entire specification.

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

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

       Objects whose type is pointer to	`TCJDB'	 are  used  to	handle	tagged
       databases.   A  remote  database	 object	 is  created with the function
       `tcjdbnew' and is deleted with the function `tcjdbdel'.	To avoid  mem-
       ory  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 directory and	connect	the tagged database object to it.  The
       function	`tcjdbopen' is used to open a database directory and the func-
       tion  `tcjdbclose'  is  used to close the database directory.  To avoid
       data missing or corruption, it is important to close every database di-
       rectory when it is no longer in use.

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

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

       The function `tcjdbnew' is used in order	to create  a  tagged  database
       object.

	      TCJDB *tcjdbnew(void);
		     The return	value is the new tagged	database object.

       The  function  `tcjdbdel'  is used in order to delete a tagged database
       object.

	      void tcjdbdel(TCJDB *jdb);
		     `jdb' specifies the tagged	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 `tcjdbecode' is used in order to get the last happened er-
       ror code	of a tagged database object.

	      int tcjdbecode(TCJDB *jdb);
		     `jdb' specifies the tagged	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 `tcjdbtune'	is used	in order to set	the tuning  parameters
       of a tagged database object.

	      bool tcjdbtune(TCJDB *jdb, int64_t ernum,	int64_t	etnum, int64_t
	      iusiz, uint8_t opts);
		     `jdb' specifies the tagged	database object	which  is  not
		     opened.
		     `ernum'  specifies	 the  expected number of records to be
		     stored.  If it is not more	than 0,	the default  value  is
		     specified.	 The default value is 1000000.
		     `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.
		     `iusiz'  specifies	 the unit size of each index file.  If
		     it	is not more than 0, the	default	 value	is  specified.
		     The default value is 536870912.
		     `opts' specifies options by bitwise-or: `JDBTLARGE' spec-
		     ifies that	the size of the	database can  be  larger  than
		     2GB by using 64-bit bucket	array, `JDBTDEFLATE' specifies
		     that each	page  is  compressed  with  Deflate  encoding,
		     `JDBTBZIP'	 specifies  that  each page is compressed with
		     BZIP2 encoding, `JDBTTCBS'	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 `tcjdbsetcache' is used in order to	set the	caching	param-
       eters of	a tagged database object.

	      bool tcjdbsetcache(TCJDB *jdb, int64_t icsiz, int32_t lcnum);
		     `jdb' specifies the tagged	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 `tcjdbsetfwmmax' is	used in	order to set the maximum  num-
       ber of forward matching expansion of a tagged database object.

	      bool tcjdbsetfwmmax(TCJDB	*jdb, uint32_t fwmmax);
		     `jdb' specifies the tagged	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 `tcjdbopen'	is used	in order to open a tagged database ob-
       ject.

	      bool tcjdbopen(TCJDB *jdb, const char *path, int omode);
		     `jdb' specifies the tagged	database object.
		     `path' specifies the path of the database directory.
		     `omode'  specifies	the connection mode: `JDBOWRITER' as a
		     writer, `JDBOREADER' as a reader.	If the	mode  is  `JD-
		     BOWRITER',	the following may be added by bitwise-or: `JD-
		     BOCREAT', which means it creates a	new  database  if  not
		     exist, `JDBOTRUNC', which means it	creates	a new database
		     regardless	if one exists.	Both of	`JDBOREADER' and  `JD-
		     BOWRITER'	can  be	 added	to by bitwise-or: `JDBONOLCK',
		     which means it opens the database directory without  file
		     locking, or `JDBOLCKNB', which means locking is performed
		     without blocking.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tcjdbclose' is used in order to close a tagged database
       object.

	      bool tcjdbclose(TCJDB *jdb);
		     `jdb' specifies the tagged	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 `tcjdbput' is used in order	 to  store  a  record  into  a
       tagged database object.

	      bool tcjdbput(TCJDB *jdb,	int64_t	id, const TCLIST *words);
		     `jdb' specifies the tagged	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 `tcjdbput2'	is used	in order to store a record with	a text
       string into a tagged database object.

	      bool tcjdbput2(TCJDB *jdb, int64_t id, const char	 *text,	 const
	      char *delims);
		     `jdb' specifies the tagged	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 `tcjdbout' is used in order	to remove a record of a	tagged
       database	object.

	      bool tcjdbout(TCJDB *jdb,	int64_t	id);
		     `jdb' specifies the tagged	database object	connected as a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.

       The  function  `tcjdbget'  is  used  in order to	retrieve a record of a
       tagged database object.

	      TCLIST *tcjdbget(TCJDB *jdb, int64_t id);
		     `jdb' specifies the tagged	database object	connected as a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     If	successful, the	return value is	the string of the cor-
		     responding	record,	else, it is `NULL'.
		     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  `tcjdbget2'  is  used in order to	retrieve a record as a
       string of a tagged database object.

	      char *tcjdbget2(TCJDB *jdb, int64_t id);
		     `jdb' specifies the tagged	database object	connected as a
		     writer.
		     `id' specifies the	ID number of the record.  It should be
		     positive.
		     If	successful, the	return value is	the string of the cor-
		     responding	record,	else, it is `NULL'.  Each word is sep-
		     arated by a tab character.
		     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 `tcjdbsearch' is used in order to search  a	 tagged	 data-
       base.

	      uint64_t	*tcjdbsearch(TCJDB  *jdb, const	char *word, int	smode,
	      int *np);
		     `jdb' specifies the tagged	database object.
		     `word' specifies the string of the	word to	be matched to.
		     `smode' specifies the matching mode: `JDBSSUBSTR' as sub-
		     string  matching,	`JDBSPREFIX' as	prefix matching, `JDB-
		     SSUFFIX' as suffix	matching, `JDBSFULL' as	full matching.
		     `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  `tcjdbsearch2' is	used in	order to search	a tagged data-
       base with a compound expression.

	      uint64_t *tcjdbsearch2(TCJDB *jdb, const char *expr, int *np);
		     `jdb' specifies the tagged	database object.
		     `expr' specifies the string of the	compound expression.
		     `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 `tcjdbiterinit' is	used in	order to initialize the	itera-
       tor of a	tagged database	object.

	      bool tcjdbiterinit(TCJDB *jdb);
		     `jdb' specifies the tagged	database object.
		     If	successful, the	return value  is  true,	 else,	it  is
		     false.
		     The  iterator is used in order to access the ID number of
		     every record stored in a database.

       The function `tcjdbiternext' is used in order to	get the	next ID	number
       of the iterator of a tagged database object.

	      uint64_t tcjdbiternext(TCJDB *jdb);
		     `jdb' specifies the tagged	database object.
		     If	 successful,  the return value is the ID number	of the
		     next record, 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.  How-
		     ever, it is not assured if	updating the database  is  oc-
		     curred  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 `tcjdbsync'	is used	in order to synchronize	 updated  con-
       tents of	a tagged database object with the files	and the	device.

	      bool tcjdbsync(TCJDB *jdb);
		     `jdb' specifies the tagged	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 directory.

       The function `tcjdboptimize' is used in order to	optimize the files  of
       a tagged	database object.

	      bool tcjdboptimize(TCJDB *jdb);
		     `jdb' specifies the tagged	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 files	with data fragmentation	by  successive	updat-
		     ing.

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

	      bool tcjdbvanish(TCJDB *jdb);
		     `jdb' specifies the tagged	database object	connected as a
		     writer.
		     If	 successful,  the  return  value  is true, else, it is
		     false.

       The function `tcjdbcopy'	is used	in order to copy the  database	direc-
       tory of a tagged	database object.

	      bool tcjdbcopy(TCJDB *jdb, const char *path);
		     `jdb' specifies the tagged	database object.
		     `path'  specifies	the path of the	destination directory.
		     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 directory 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 directory of the database directory.

       The function `tcjdbpath'	is used	in order to get	the directory path  of
       a tagged	database object.

	      const char *tcjdbpath(TCJDB *jdb);
		     `jdb' specifies the tagged	database object.
		     The return	value is the path of the database directory or
		     `NULL' if the object does not connect to any database di-
		     rectory.

       The  function `tcjdbrnum' is used in order to get the number of records
       of a tagged database object.

	      uint64_t tcjdbrnum(TCJDB *jdb);
		     `jdb' specifies the tagged	database object.
		     The return	value is the number of records or 0 if the ob-
		     ject does not connect to any database directory.

       The  function `tcjdbfsiz' is used in order to get the total size	of the
       database	files of a tagged database object.

	      uint64_t tcjdbfsiz(TCJDB *jdb);
		     `jdb' specifies the tagged	database object.
		     The return	value is the size of the database files	 or  0
		     if	the object does	not connect to any database directory.

COMPOUND EXPRESSION OF SEARCH
       The  function  `tcidbsearch2'  searches with a compound expression.  In
       the compound expression,	tokens are separated  by  one  or  more	 white
       space  characters.   If	one  token is specified, records including the
       specified pattern are searched for.  Upper or lower case	is not distin-
       guished.	  Accent  marks	 and diacritical marks are ignored.  If	two or
       more tokens are specified, records including all	of  the	 patterns  are
       searched	 for.	The compound expression	includes the following sub ex-
       pressions.

	      A	B : searches for records including the two words.
	      A	&& B : searches	for records including the two words.
	      A	|| B : searches	for records including the one or both  of  the
	      two words.
	      "A  B..."	: searches for records including the phrase word which
	      can include space	characters.
	      [[A*]] : searches	for records including words beginning with the
	      token.
	      [[*A]]  :	 searches  for records including words ending with the
	      token.
	      [[*A*]] :	searches for records including words including the to-
	      ken.

       Note that the priority of "||" is higher	than the one of	"&&".

SEE ALSO
       laputest(1), lapumgr(1),	tcwdb(3), dystopia(3)

Man Page			  2010-08-05			     LAPUTA(3)

NAME | DESCRIPTION | API | COMPOUND EXPRESSION OF SEARCH | SEE ALSO

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

home | help