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 specification.

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 databases. A remote database object is created with the function `tcwdbnew' 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 function `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 object.

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

The function `tcwdbdel' is used in order to delete a word database object.

    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 error 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 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 `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' specifies 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 parameters 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 number 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 object.

    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 `WDBOWRITER', the following may be added by bitwise-or: `WDBOCREAT', 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 `WDBOWRITER' can be added to by bitwise-or: `WDBONOLCK', which means it opens the database file without file locking, 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 object.

    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 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 `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 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 `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 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 `tcwdbsync' is used in order to synchronize updated contents 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 database 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 object does not connect to any database file.

The function `tcwdbfsiz' is used in order to get the size of the database 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)