FreeBSD Manual Pages
DYSTOPIA(3) Tokyo Dystopia DYSTOPIA(3) NAME dystopia - the core API DESCRIPTION Indexed database is a directory containing a hash database file and its index 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 `dystopia.h' for entire specification. To use the core API, include `dystopia.h' and related standard header files. Usually, write the following description near the front of a source file. #include <dystopia.h> #include <stdlib.h> #include <stdbool.h> #include <stdint.h> Objects whose type is pointer to `TCIDB' are used to handle indexed databases. A remote database object is created with the function `tcidbnew' and is deleted with the function `tcidbdel'. 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 indexed database object to it. The function `tcidbopen' is used to open a database directory and the function `tcidbclose' is used to close the database directory. To avoid data missing or corruption, it is important to close every data- base directory when it is no longer in use. API The function `tcidberrmsg' is used in order to get the message string corresponding to an error code. const char *tcidberrmsg(int ecode); `ecode' specifies the error code. The return value is the message string of the error code. The function `tcidbnew' is used in order to create an indexed database object. TCIDB *tcidbnew(void); The return value is the new indexed database object. The function `tcidbdel' is used in order to delete an indexed database object. void tcidbdel(TCIDB *idb); `idb' specifies the indexed 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 `tcidbecode' is used in order to get the last happened er- ror code of an indexed database object. int tcidbecode(TCIDB *idb); `idb' specifies the indexed 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 `tcidbtune' is used in order to set the tuning parameters of an indexed database object. bool tcidbtune(TCIDB *idb, int64_t ernum, int64_t etnum, int64_t iusiz, uint8_t opts); `idb' specifies the indexed 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: `IDBTLARGE' spec- ifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `IDBTDEFLATE' specifies that each page is compressed with Deflate encoding, `IDBTBZIP' specifies that each page is compressed with BZIP2 encoding, `IDBTTCBS' 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 `tcidbsetcache' is used in order to set the caching para- meters of an indexed database object. bool tcidbsetcache(TCIDB *idb, int64_t icsiz, int32_t lcnum); `idb' specifies the indexed 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 `tcidbsetfwmmax' is used in order to set the maximum num- ber of forward matching expansion of an indexed database object. bool tcidbsetfwmmax(TCIDB *idb, uint32_t fwmmax); `idb' specifies the indexed 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 `tcidbopen' is used in order to open an indexed database object. bool tcidbopen(TCIDB *idb, const char *path, int omode); `idb' specifies the indexed database object. `path' specifies the path of the database directory. `omode' specifies the connection mode: `IDBOWRITER' as a writer, `IDBOREADER' as a reader. If the mode is `ID- BOWRITER', the following may be added by bitwise or: `ID- BOCREAT', which means it creates a new database if not exist, `IDBOTRUNC', which means it creates a new database regardless if one exists. Both of `IDBOREADER' and `ID- BOWRITER' can be added to by bitwise or: `IDBONOLCK', which means it opens the database directory without file locking, or `IDBOLCKNB', which means locking is performed without blocking. If successful, the return value is true, else, it is false. The function `tcidbclose' is used in order to close an indexed database object. bool tcidbclose(TCIDB *idb); `idb' specifies the indexed 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 `tcidbput' is used in order to store a record into an in- dexed database object. bool tcidbput(TCIDB *idb, int64_t id, const char *text); `idb' specifies the indexed 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 `tcidbout' is used in order to remove a record of an in- dexed database object. bool tcidbout(TCIDB *idb, int64_t id); `idb' specifies the indexed 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 `tcidbget' is used in order to retrieve a record of an in- dexed database object. char *tcidbget(TCIDB *idb, int64_t id); `idb' specifies the indexed 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 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 `tcidbsearch' is used in order to search an indexed data- base. uint64_t *tcidbsearch(TCIDB *idb, const char *word, int smode, int *np); `idb' specifies the indexed database object. `word' specifies the string of the word to be matched to. `smode' specifies the matching mode: `IDBSSUBSTR' as sub- string matching, `IDBSPREFIX' as prefix matching, `IDB- SSUFFIX' as suffix matching, `IDBSFULL' as full matching, `IDBSTOKEN' as token matching, `IDBSTOKPRE' as token pre- fix matching, or `IDBSTOKSUF' as token suffix 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 `tcidbsearch2' is used in order to search an indexed data- base with a compound expression. uint64_t *tcidbsearch2(TCIDB *idb, const char *expr, int *np); `idb' specifies the indexed 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 `tcidbiterinit' is used in order to initialize the itera- tor of an indexed database object. bool tcidbiterinit(TCIDB *idb); `idb' specifies the indexed 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 `tcidbiternext' is used in order to get the next ID number of the iterator of an indexed database object. uint64_t tcidbiternext(TCIDB *idb); `idb' specifies the indexed 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 `tcidbsync' is used in order to synchronize updated con- tents of an indexed database object with the files and the device. bool tcidbsync(TCIDB *idb); `idb' specifies the indexed 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 `tcidboptimize' is used in order to optimize the files of an indexed database object. bool tcidboptimize(TCIDB *idb); `idb' specifies the indexed 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 `tcidbvanish' is used in order to remove all records of an indexed database object. bool tcidbvanish(TCIDB *idb); `idb' specifies the indexed database object connected as a writer. If successful, the return value is true, else, it is false. The function `tcidbcopy' is used in order to copy the database direc- tory of an indexed database object. bool tcidbcopy(TCIDB *idb, const char *path); `idb' specifies the indexed 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 `tcidbpath' is used in order to get the directory path of an indexed database object. const char *tcidbpath(TCIDB *idb); `idb' specifies the indexed 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 `tcidbrnum' is used in order to get the number of records of an indexed database object. uint64_t tcidbrnum(TCIDB *idb); `idb' specifies the indexed 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 `tcidbfsiz' is used in order to get the total size of the database files of an indexed database object. uint64_t tcidbfsiz(TCIDB *idb); `idb' specifies the indexed 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 tokens. A && B : searches for records including the two tokens. A || B : searches for records including the one or both of the two tokens. "A B..." : searches for records including the phrase. [[A]] : searches for records including words exactly matching the token. [[A*]] : searches for records including words beginning with the token. [[*A]] : searches for records including words ending with the token. [[[[A : searches for records beginning with the token. A]]]] : searches for records ending with the token. Note that the priority of "||" is higher than the one of "&&". SEE ALSO dysttest(1), dystmgr(1), tcqdb(3), laputa(3) Man Page 2010-08-05 DYSTOPIA(3)
NAME | DESCRIPTION | API | COMPOUND EXPRESSION OF SEARCH | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dystopia&sektion=3&manpath=FreeBSD+Ports+15.0>