GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
TCQDB(3) Tokyo Dystopia TCQDB(3)

tcqdb - the q-gram database API

Q-gram database is a file containing index of text. The key of each record is a positive number. The value of each record is an arbitrary text data whose encoding is UTF-8. Note that q-gram database is pure index and does not contain entity of records. See `tcqdb.h' for entire specification.

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


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

Objects whose type is pointer to `TCQDB' are used to handle q-gram databases. A remote database object is created with the function `tcqdbnew' and is deleted with the function `tcqdbdel'. 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 q-gram database object to it. The function `tcqdbopen' is used to open a database file and the function `tcqdbclose' 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.

The constant `tdversion' is the string containing the version information.


extern const char *tdversion;

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


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

The function `tcqdbnew' is used in order to create a q-gram database object.


TCQDB *tcqdbnew(void);
The return value is the new q-gram database object.

The function `tcqdbdel' is used in order to delete a q-gram database object.


void tcqdbdel(TCQDB *qdb);
`qdb' specifies the q-gram 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 `tcqdbecode' is used in order to get the last happened error code of a q-gram database object.


int tcqdbecode(TCQDB *qdb);
`qdb' specifies the q-gram 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 `tcqdbtune' is used in order to set the tuning parameters of a q-gram database object.


bool tcqdbtune(TCQDB *qdb, int64_t etnum, uint8_t opts);
`qdb' specifies the q-gram 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: `QDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `QDBTDEFLATE' specifies that each page is compressed with Deflate encoding, `QDBTBZIP' specifies that each page is compressed with BZIP2 encoding, `QDBTTCBS' 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 `tcqdbsetcache' is used in order to set the caching parameters of a q-gram database object.


bool tcqdbsetcache(TCQDB *qdb, int64_t icsiz, int32_t lcnum);
`qdb' specifies the q-gram 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 `tcqdbsetfwmmax' is used in order to set the maximum number of forward matching expansion of a q-gram database object.


bool tcqdbsetfwmmax(TCQDB *qdb, uint32_t fwmmax);
`qdb' specifies the q-gram 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 `tcqdbopen' is used in order to open a q-gram database object.


bool tcqdbopen(TCQDB *qdb, const char *path, int omode);
`qdb' specifies the q-gram database object.
`path' specifies the path of the database file.
`omode' specifies the connection mode: `QDBOWRITER' as a writer, `QDBOREADER' as a reader. If the mode is `QDBOWRITER', the following may be added by bitwise-or: `QDBOCREAT', which means it creates a new database if not exist, `QDBOTRUNC', which means it creates a new database regardless if one exists. Both of `QDBOREADER' and `QDBOWRITER' can be added to by bitwise-or: `QDBONOLCK', which means it opens the database file without file locking, or `QDBOLCKNB', which means locking is performed without blocking.
If successful, the return value is true, else, it is false.

The function `tcqdbclose' is used in order to close a q-gram database object.


bool tcqdbclose(TCQDB *qdb);
`qdb' specifies the q-gram 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 `tcqdbput' is used in order to store a record into a q-gram database object.


bool tcqdbput(TCQDB *qdb, int64_t id, const char *text);
`qdb' specifies the q-gram 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.
If successful, the return value is true, else, it is false.

The function `tcqdbout' is used in order to remove a record of a q-gram database object.


bool tcqdbout(TCQDB *qdb, int64_t id, const char *text);
`qdb' specifies the q-gram 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.
If successful, the return value is true, else, it is false.

The function `tcqdbsearch' is used in order to search a q-gram database.


uint64_t *tcqdbsearch(TCQDB *qdb, const char *word, int smode, int *np);
`qdb' specifies the q-gram database object.
`word' specifies the string of the word to be matched to.
`smode' specifies the matching mode: `QDBSSUBSTR' as substring matching, `QDBSPREFIX' as prefix matching, `QDBSSUFFIX' as suffix matching, or `QDBSFULL' 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 `tcqdbsync' is used in order to synchronize updated contents of a q-gram database object with the file and the device.


bool tcqdbsync(TCQDB *qdb);
`qdb' specifies the q-gram 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 `tcqdboptimize' is used in order to optimize the file of a q-gram database object.


bool tcqdboptimize(TCQDB *qdb);
`qdb' specifies the q-gram 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 file with data fragmentation by successive updating.

The function `tcqdbvanish' is used in order to remove all records of a q-gram database object.


bool tcqdbvanish(TCQDB *qdb);
`qdb' specifies the q-gram database object connected as a writer.
If successful, the return value is true, else, it is false.

The function `tcqdbcopy' is used in order to copy the database file of a q-gram database object.


bool tcqdbcopy(TCQDB *qdb, const char *path);
`qdb' specifies the q-gram 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 `tcqdbpath' is used in order to get the file path of a q-gram database object.


const char *tcqdbpath(TCQDB *qdb);
`qdb' specifies the q-gram 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 `tcqdbtnum' is used in order to get the number of tokens of a q-gram database object.


uint64_t tcqdbtnum(TCQDB *qdb);
`qdb' specifies the q-gram database object.
The return value is the number of tokens or 0 if the object does not connect to any database file.

The function `tcqdbfsiz' is used in order to get the size of the database file of a q-gram database object.


uint64_t tcqdbfsiz(TCQDB *qdb);
`qdb' specifies the q-gram database object.
The return value is the size of the database file or 0 if the object does not connect to any database file.

tcqtest(1), tcqmgr(1), dystopia(3)
2010-08-05 Man Page
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.