|
NAMElaputa - the simple APIDESCRIPTIONTagged 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 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 directory and connect the tagged database object to it. The function `tcjdbopen' is used to open a database directory and the function `tcjdbclose' is used to close the database directory. To avoid data missing or corruption, it is important to close every database directory when it is no longer in use. APIThe 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 error 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 error, `TCEWRITE' for write error, `TCEMMAP' for mmap error, `TCELOCK'
for lock error, `TCEUNLINK' for unlink error, `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' specifies 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 parameters 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 number 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 object. 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
`JDBOWRITER', the following may be added by bitwise-or: `JDBOCREAT', 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
`JDBOWRITER' 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
characters 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
corresponding 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
corresponding record, else, it is `NULL'. Each word is separated 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 database. 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 substring matching, `JDBSPREFIX' as prefix matching, `JDBSSUFFIX' 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
array 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 database 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
array 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 iterator 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. 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 `tcjdbsync' is used in order to synchronize updated contents 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
database files with data fragmentation by successive updating.
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 directory 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 directory.
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
object 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 SEARCHThe 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 distinguished. 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 expressions.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 token. Note that the priority of "||" is higher than the one of "&&". SEE ALSOlaputest(1), lapumgr(1), tcwdb(3), dystopia(3)
Visit the GSP FreeBSD Man Page Interface. |