Fundamental Specification of Tokyo Cabinet Version 1
Copyright (C) 2006-2007 Mikio Hirabayashi
Last Update: Wed, 24 Oct 2007 01:26:07 +0900
Table of Contents
- Introduction
- Features
- Installation
- The Utility API
- The Hash Database API
- The B+ Tree API
- License
Introduction
Tokyo Cabinet is a library of routines for managing a database. The database is a simple data file containing records, each is a pair of a key and a value. Every key and value is serial bytes with variable length. Both binary data and character string can be used as a key and a value. There is neither concept of data tables nor data types. Records are organized in hash table or B+ tree.
As for database of hash table, each key must be unique within a database, so it is impossible to store two or more records with a key overlaps. The following access methods are provided to the database: storing a record with a key and a value, deleting a record by a key, retrieving a record by a key. Moreover, traversal access to every key are provided, although the order is arbitrary. These access methods are similar to ones of DBM (or its followers: NDBM and GDBM) library defined in the UNIX standard. Tokyo Cabinet is an alternative for DBM because of its higher performance.
As for database of B+ tree, records whose keys are duplicated can be stored. Access methods of storing, deleting, and retrieving are provided as with the database of hash table. Records are stored in order by a comparison function assigned by a user. It is possible to access each record with the cursor in ascending or descending order. According to this mechanism, forward matching search for strings and range search for integers are realized. Moreover, transaction is available in database of B+ tree.
Tokyo Cabinet is written in the C language, and provided as API of C, Perl, Ruby, and Java. Tokyo Cabinet is available on platforms which have API conforming to C99 and POSIX. Tokyo Cabinet is a free software licensed under the GNU Lesser General Public License.
Features
Tokyo Cabinet is the successor of QDBM and improves time and space efficiency. This section describes the features of Tokyo Cabinet.
The Dinosaur Wing of the DBM fork
Tokyo Cabinet is developed as the successor of QDBM on the following purposes. They are achieved and Tokyo Cabinet replaces QDBM.
- improves space efficiency : smaller size of database file.
- improves time efficiency : faster processing speed.
- improves parallelism : higher performance in multi-thread environment.
- improves usability : simplified API.
- improves robustness : database file is not corrupted even under catastrophic situation.
- supports 64-bit architecture : enormous memory space and database file are available.
As with QDBM, the following three restrictions of traditional DBM: a process can handle only one database, the size of a key and a value is bounded, a database file is sparse, are cleared. Moreover, the following three restrictions of QDBM: the size of a database file is limited to 2GB, environments with different byte orders can not share a database file, only one thread can search a database at the same time, are cleared.
Tokyo Cabinet runs very fast. For example, elapsed time to store 1 million records is 1.5 seconds for hash database, and 2.2 seconds for B+ tree database. Moreover, the size of database of Tokyo Cabinet is very small. For example, overhead for a record is 16 bytes for hash database, and 5 bytes for B+ tree database. Furthermore, scalability of Tokyo Cabinet is great. The database size can be up to 8EB (9.22e18 bytes).
Effective Implementation of Hash Database
Tokyo Cabinet uses hash algorithm to retrieve records. If a bucket array has sufficient number of elements, the time complexity of retrieval is `O(1)'. That is, time required for retrieving a record is constant, regardless of the scale of a database. It is also the same about storing and deleting. Collision of hash values is managed by separate chaining. Data structure of the chains is binary search tree. Even if a bucket array has unusually scarce elements, the time complexity of retrieval is `O(log n)'.
Tokyo Cabinet attains improvement in retrieval by loading RAM with the whole of a bucket array. If a bucket array is on RAM, it is possible to access a region of a target record by about one path of file operations. A bucket array saved in a file is not read into RAM with the `read' call but directly mapped to RAM with the `mmap' call. Therefore, preparation time on connecting to a database is very short, and two or more processes can share the same memory map.
If the number of elements of a bucket array is about half of records stored within a database, although it depends on characteristic of the input, the probability of collision of hash values is about 56.7% (36.8% if the same, 21.3% if twice, 11.5% if four times, 6.0% if eight times). In such case, it is possible to retrieve a record by two or less paths of file operations. If it is made into a performance index, in order to handle a database containing one million of records, a bucket array with half a million of elements is needed. The size of each element is 4 bytes. That is, if 2M bytes of RAM is available, a database containing one million records can be handled.
Traditional DBM provides two modes of the storing operations: `insert' and `replace'. In the case a key overlaps an existing record, the insert mode keeps the existing value, while the replace mode transposes it to the specified value. In addition to the two modes, Tokyo Cabinet provides `concatenate' mode. In the mode, the specified value is concatenated at the end of the existing value and stored. This feature is useful when adding a element to a value as an array. Moreover, although DBM has a method to fetch out a value from a database only by reading the whole of a region of a record, Tokyo Cabinet has a method to fetch out a part of a region of a value. When a value is treated as an array, this feature is also useful.
Generally speaking, while succession of updating, fragmentation of available regions occurs, and the size of a database grows rapidly. Tokyo Cabinet deal with this problem by coalescence of dispensable regions and reuse of them, and featuring of optimization of a database. When overwriting a record with a value whose size is greater than the existing one, it is necessary to remove the region to another position of the file. Because the time complexity of the operation depends on the size of the region of a record, extending values successively is inefficient. However, Tokyo Cabinet deal with this problem by alignment. If increment can be put in padding, it is not necessary to remove the region.
Useful Implementation of B+ Tree Database
Although B+ tree database is slower than hash database, it features ordering access to each record. The order can be assigned by users. Records of B+ tree are sorted and arranged in logical pages. Sparse index organized in B tree that is multiway balanced tree are maintained for each page. Thus, the time complexity of retrieval and so on is `O(log n)'. Cursor is provided to access each record in order. The cursor can jump to a position specified by a key and can step forward or backward from the current position. Because each page is arranged as double linked list, the time complexity of stepping cursor is `O(1)'.
B+ tree database is implemented, based on above hash database. Because each page of B+ tree is stored as each record of hash database, B+ tree database inherits efficiency of storage management of hash database. Because the header of each record is smaller and alignment of each page is adjusted according to the page size, in most cases, the size of database file is cut by half compared to one of hash database. Although operation of many pages are required to update B+ tree, QDBM expedites the process by caching pages and reducing file operations. In most cases, because whole of the sparse index is cached on memory, it is possible to retrieve a record by one or less path of file operations.
B+ tree database features transaction mechanism. It is possible to commit a series of operations between the beginning and the end of the transaction in a lump, or to abort the transaction and perform rollback to the state before the transaction. Two isolation levels are supported; serializable and read uncommitted.
Each pages of B+ tree can be stored with compressed. Two compression method; Deflate of ZLIB and Block Sorting, are supported. Because each record in a page has similar patterns, high efficiency of compression is expected due to the Lempel-Ziv or the BWT algorithms. In case handling text data, the size of a database is reduced to about 25%. If the scale of a database is large and disk I/O is the bottleneck, featuring compression makes the processing speed improved to a large extent.
Simple but Various Interfaces
Tokyo Cabinet provides simple API based on the object oriented design. Every operation for database is encapsulated and published as lucid methods as `open' (connect), `close' (disconnect), `put' (insert), `out' (remove), `get' (retrieve), and so on. Because the two of the hash and the B+ tree database APIs are very similar with each other, porting an application from one to the other is easy.
Tokyo Cabinet provides two modes to connect to a database: `reader' and `writer'. A reader can perform retrieving but neither storing nor deleting. A writer can perform all access methods. Exclusion control between processes is performed when connecting to a database by file locking. While a writer is connected to a database, neither readers nor writers can be connected. While a reader is connected to a database, other readers can be connect, but writers can not. According to this mechanism, data consistency is guaranteed with simultaneous connections in multitasking environment.
Functions of API of Tokyo cabinet are reentrant and available in multi-thread environment. Discrete database object can be operated in parallel entirely. For simultaneous operations of the same database object, read-write lock is used for exclusion control. That is, while a writing thread is operating the database, other reading threads and writing threads are blocked. However, while a reading thread is operating the database, reading threads are not blocked.
The utility API is also provided. Such fundamental data structure as list and map are included. And, some useful features; memory pool, string processing, encoding, are also included.
Three kinds of API; the utility API, the hash database API, and the B+ tree database API, are provided for the C language. Command line interfaces are also provided corresponding to each API. They are usuful for prototyping, test, and debugging. Except for C, Tokyo Cabinet provides APIs for Perl, Ruby, and Java. The Perl API has methods calling the hash database API and the B+ tree database API with XS language. The Java API has native methods calling the hash database API and the B+ tree API with Java Native Interface. The Ruby API has methods calling the hash database API and the B+ tree database API as modules of Ruby. APIs for other languages will hopefully be provided by third party.
Installation
This section describes how to install Tokyo Cabinet with the source package. As for a binary package, see its installation manual.
Preparation
Tokyo Cabinet is available on UNIX-like systems. At least, the following environments are supported.
- Linux 2.4 and later (IA32/IA64/AMD64)
gcc
3.1 or later and make
are required to install Tokyo Cabinet with the source package. They are installed by default on Linux, FreeBSD and so on.
As Tokyo Cabinet depends on the following libraries, install them beforehand.
- zlib : for loss-less data compression. 1.2.1 or later is suggested.
Installation
When an archive file of Tokyo Cabinet is extracted, change the current working directory to the generated directory and perform installation.
Run the configuration script.
./configure
Build programs.
make
Perform self-diagnostic test.
make check
Install programs. This operation must be carried out by the root
user.
make install
Result
When a series of work finishes, the following files will be installed.
/usr/local/include/tcutil.h
/usr/local/include/tchdb.h
/usr/local/include/tcbdb.h
/usr/local/lib/libtokyocabinet.a
/usr/local/lib/libtokyocabinet.so.1.11.0
/usr/local/lib/libtokyocabinet.so.1
/usr/local/lib/libtokyocabinet.so
/usr/local/lib/pkgconfig/tokyocabinet.pc
/usr/local/bin/tcucodec
/usr/local/bin/tcutest
/usr/local/bin/tchmgr
/usr/local/bin/tchtest
/usr/local/bin/tchmttest
/usr/local/bin/tcbmgr
/usr/local/bin/tcbtest
/usr/local/bin/tcbmttest
/usr/local/share/tokyocabinet/...
/usr/local/man/man1/...
/usr/local/man/man3/...
Options of Configure
The following options can be specified with `./configure
'.
--enable-debug
: build for debugging. Enable debugging symbols, do not perform optimization, and perform static linking.
--enable-devel
: build for development. Enable debugging symbols, perform optimization, and perform dynamic linking.
--enable-fastest
: build for fastest run.
--enable-swab
: build for swapping byte-orders.
--disable-zlib
: build without ZLIB compression.
--disable-pthread
: build without POSIX thread support.
--disable-shared
: avoid to build shared libraries.
`--prefix
' and other options are also available as with usual UNIX software packages. If you want to install Tokyo Cabinet under `/usr
' not `/usr/local
', specify `--prefix=/usr
'. As well, the library search path does not include `/usr/local/lib
', it is necessary to set the environment variable `LD_LIBRARY_PATH
' to include `/usr/local/lib
' before running applications of Tokyo Cabinet.
How to Use the Library
Tokyo Cabinet provides API of the C language and it is available by programs conforming to the C89 (ANSI C) standard or the C99 standard. As the header files of Tokyo Cabinet are provided as `tcutil.h
', `tchdb.h
', and `tcbdb.h
', applications should include one or more of them accordingly to use the API. As the library is provided as `libtokyocabinet.a
' and `libtokyocabinet.so
' and they depends `libz.so
', `libpthread.so
', `libm.so
', and `libc.so
', linker options `-ltokyocabinet
', `-lz
', `-lpthread
', `-lm
', and `-lc
' are required for build command. A typical build command is the following.
gcc -I/usr/local/include tc_example.c -o tc_example \
-L/usr/local/lib -ltokyocabinet -lz -lm -lc
You can also use Tokyo Cabinet in programs written in C++. Because each header is wrapped in C linkage (`extern "C"
' block), you can simply include them into your C++ programs.
The Utility API
The utility API is a set of routines to handle records on memory easily. Especially, extensible string, array list, and hash map are useful. See `tcutil.h
' for entire specification.
Description
To use the utility API, include `tcutil.h
' and related standard header files. Usually, write the following description near the front of a source file.
#include <tcutil.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
Objects whose type is pointer to `TCXSTR
' are used for extensible string. An extensible string object is created with the function `tcxstrnew
' and is deleted with the function `tcxstrdel
'. Objects whose type is pointer to `TCLIST
' are used for array list. A list object is created with the function `tclistnew
' and is deleted with the function `tclistdel
'. Objects whose type is pointer to `TCMAP
' are used for hash map. A map object is created with the function `tcmapnew
' and is deleted with the function `tcmapdel
'. To avoid memory leak, it is important to delete every object when it is no longer in use.
API of Basic Utilities
The constant `tcversion' is the string containing the version information.
extern const char *tcversion;
The variable `tcfatalfunc' is the pointer to the call back function for handling a fatal error.
extern void (*tcfatalfunc)(const char *);
- The argument specifies the error message. The initial value of this variable is `NULL'.
- If the value is `NULL', the default function is called when a fatal error occurs. A fatal error occurs when memory allocation is failed.
The function `tcmalloc' is used in order to allocate a region on memory.
void *tcmalloc(size_t size);
- `size' specifies the size of the region.
- The return value is the pointer to the allocated region.
- This function handles failure of memory allocation implicitly. 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 `tccalloc' is used in order to allocate a nullified region on memory.
void *tccalloc(size_t nmemb, size_t size);
- `size' specifies the size of the region.
- The return value is the pointer to the allocated nullified region.
- This function handles failure of memory allocation implicitly. Because the region of the return value is allocated with the `calloc' call, it should be released with the `free' call when it is no longer in use.
The function `tcrealloc' is used in order to re-allocate a region on memory.
void *tcrealloc(void *ptr, size_t size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the pointer to the re-allocated region.
- This function handles failure of memory allocation implicitly. Because the region of the return value is allocated with the `realloc' call, it should be released with the `free' call when it is no longer in use.
The function `tcmemdup' is used in order to duplicate a region on memory.
void *tcmemdup(const void *ptr, size_t size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the pointer to the allocated region of the duplicate.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcstrdup' is used in order to duplicate a string on memory.
char *tcstrdup(const void *str);
- `str' specifies the string.
- The return value is the allocated string equivalent to the specified string.
- 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 `tcfree' is used in order to free a region on memory.
void tcfree(void *ptr);
- `ptr' specifies the pointer to the region. If it is `NULL', this function has no effect.
- Although this function is just a wrapper of `free' call, this is useful in applications using another package of the `malloc' series.
API of Extensible String
The function `tcxstrnew' is used in order to create an extensible string object.
TCXSTR *tcxstrnew(void);
- The return value is the new extensible string object.
The function `tcxstrnew2' is used in order to create an extensible string object from a character string.
TCXSTR *tcxstrnew2(const char *str);
- `str' specifies the string of the initial content.
- The return value is the new extensible string object containing the specified string.
The function `tcxstrnew3' is used in order to create an extensible string object with the initial allocation size.
TCXSTR *tcxstrnew3(int asiz);
- `asiz' specifies the initial allocation size.
- The return value is the new extensible string object.
The function `tcxstrdup' is used in order to copy an extensible string object.
TCXSTR *tcxstrdup(const TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- The return value is the new extensible string object equivalent to the specified object.
The function `tcxstrdel' is used in order to delete an extensible string object.
void tcxstrdel(TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- Note that the deleted object and its derivatives can not be used anymore.
The function `tcxstrcat' is used in order to concatenate a region to the end of an extensible string object.
void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);
- `xstr' specifies the extensible string object.
- `ptr' specifies the pointer to the region to be appended.
- `size' specifies the size of the region.
The function `tcxstrcat2' is used in order to concatenate a character string to the end of an extensible string object.
void tcxstrcat2(TCXSTR *xstr, const char *str);
- `xstr' specifies the extensible string object.
- `str' specifies the string to be appended.
The function `tcxstrptr' is used in order to get the pointer of the region of an extensible string object.
const void *tcxstrptr(const TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- The return value is the pointer of the region of the object.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.
The function `tcxstrsize' is used in order to get the size of the region of an extensible string object.
int tcxstrsize(const TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- The return value is the size of the region of the object.
The function `tcxstrclear' is used in order to clear an extensible string object.
void tcxstrclear(TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- The internal buffer of the object is cleared and the size is set zero.
The function `tcxstrtomalloc' is used in order to convert an extensible string object into a usual allocated region.
void *tcxstrtomalloc(TCXSTR *xstr);
- `xstr' specifies the extensible string object.
- The return value is the pointer to the allocated region of the object.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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. Because the region of the original object is deleted, it should not be deleted again.
The function `tcxstrfrommalloc' is used in order to create an extensible string object from an allocated region.
TCXSTR *tcxstrfrommalloc(void *ptr, int size);
- `ptr' specifies the pointer to the region allocated with `malloc' call.
- `size' specifies the size of the region.
- The return value is the new extensible string object wrapping the specified region.
- Note that the specified region is released when the object is deleted.
The function `tcxstrprintf' is used in order to perform formatted output into an extensible string object.
void tcxstrprintf(TCXSTR *xstr, const char *format, ...);
- `xstr' specifies the extensible string object.
- `format' specifies the printf-like format string. The conversion character `%' can be used with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `%'. `@' works as with `s' but escapes meta characters of XML. `?' works as with `s' but escapes meta characters of URL. The other conversion character work as with each original.
- The other arguments are used according to the format string.
The function `tcsprintf' is used in order to allocate a formatted string on memory.
char *tcsprintf(const char *format, ...);
- `format' specifies the printf-like format string. The conversion character `%' can be used with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `%'. `@' works as with `s' but escapes meta characters of XML. `?' works as with `s' but escapes meta characters of URL. The other conversion character work as with each original.
- The other arguments are used according to the format string.
- 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.
API of Array List
The function `tclistnew' is used in order to create a list object.
TCLIST *tclistnew(void);
- The return value is the new list object.
The function `tclistnew2' is used in order to create a list object with expecting the number of elements.
TCLIST *tclistnew2(int anum);
- `anum' specifies the number of elements expected to be stored in the list.
- The return value is the new list object.
The function `tclistdup' is used in order to copy a list object.
TCLIST *tclistdup(const TCLIST *list);
- `list' specifies the list object.
- The return value is the new list object equivalent to the specified object.
The function `tclistdel' is used in order to delete a list object.
void tclistdel(TCLIST *list);
- `list' specifies the list object.
- Note that the deleted object and its derivatives can not be used anymore.
The function `tclistnum' is used in order to get the number of elements of a list object.
int tclistnum(const TCLIST *list);
- `list' specifies the list object.
- The return value is the number of elements of the list.
The function `tclistval' is used in order to get the pointer to the region of an element of a list object.
const void *tclistval(const TCLIST *list, int index, int *sp);
- `list' specifies the list object.
- `index' specifies the index of the element.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the value.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. If `index' is equal to or more than the number of elements, the return value is `NULL'.
The function `tclistval2' is used in order to get the string of an element of a list object.
const char *tclistval2(const TCLIST *list, int index);
- `list' specifies the list object.
- `index' specifies the index of the element.
- The return value is the string of the value.
- If `index' is equal to or more than the number of elements, the return value is `NULL'.
The function `tclistpush' is used in order to add an element at the end of a list object.
void tclistpush(TCLIST *list, const void *ptr, int size);
- `list' specifies the list object.
- `ptr' specifies the pointer to the region of the new element.
- `size' specifies the size of the region.
The function `tclistpush2' is used in order to add a string element at the end of a list object.
void tclistpush2(TCLIST *list, const char *str);
- `list' specifies the list object.
- `str' specifies the string of the new element.
The function `tclistpushmalloc' is used in order to add an allocated element at the end of a list object.
void tclistpushmalloc(TCLIST *list, void *ptr, int size);
- `list' specifies the list object.
- `ptr' specifies the pointer to the region allocated with `malloc' call.
- `size' specifies the size of the region.
- Note that the specified region is released when the object is deleted.
The function `tclistpop' is used in order to remove an element of the end of a list object.
void *tclistpop(TCLIST *list, int *sp);
- `list' specifies the list object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the removed element.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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. If the list is empty, the return value is `NULL'.
The function `tclistpop2' is used in order to remove a string element of the end of a list object.
char *tclistpop2(TCLIST *list);
- `list' specifies the list object.
- The return value is the string of the removed element.
- 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. If the list is empty, the return value is `NULL'.
The function `tclistunshift' is used in order to add an element at the top of a list object.
void tclistunshift(TCLIST *list, const void *ptr, int size);
- `list' specifies the list object.
- `ptr' specifies the pointer to the region of the new element.
- `size' specifies the size of the region.
The function `tclistunshift2' is used in order to add a string element at the top of a list object.
void tclistunshift2(TCLIST *list, const char *str);
- `list' specifies the list object.
- `str' specifies the string of the new element.
The function `tclistshift' is used in order to remove an element of the top of a list object.
void *tclistshift(TCLIST *list, int *sp);
- `list' specifies the list object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the removed element.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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. If the list is empty, the return value is `NULL'.
The function `tclistshift2' is used in order to remove a string element of the top of a list object.
char *tclistshift2(TCLIST *list);
- `list' specifies the list object.
- The return value is the string of the removed element.
- 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. If the list is empty, the return value is `NULL'.
The function `tclistinsert' is used in order to add an element at the specified location of a list object.
void tclistinsert(TCLIST *list, int index, const void *ptr, int size);
- `list' specifies the list object.
- `index' specifies the index of the new element.
- `ptr' specifies the pointer to the region of the new element.
- `size' specifies the size of the region.
- If `index' is equal to or more than the number of elements, this function has no effect.
The function `tclistinsert2' is used in order to add a string element at the specified location of a list object.
void tclistinsert2(TCLIST *list, int index, const char *str);
- `list' specifies the list object.
- `index' specifies the index of the new element.
- `str' specifies the string of the new element.
- If `index' is equal to or more than the number of elements, this function has no effect.
The function `tclistremove' is used in order to remove an element at the specified location of a list object.
void *tclistremove(TCLIST *list, int index, int *sp);
- `list' specifies the list object.
- `index' specifies the index of the element to be removed.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the removed element.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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. If `index' is equal to or more than the number of elements, no element is removed and the return value is `NULL'.
The function `tclistremove2' is used in order to remove a string element at the specified location of a list object.
char *tclistremove2(TCLIST *list, int index);
- `list' specifies the list object.
- `index' specifies the index of the element to be removed.
- The return value is the string of the removed element.
- 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. If `index' is equal to or more than the number of elements, no element is removed and the return value is `NULL'.
The function `tclistover' is used in order to overwrite an element at the specified location of a list object.
void tclistover(TCLIST *list, int index, const void *ptr, int size);
- `list' specifies the list object.
- `index' specifies the index of the element to be overwritten.
- `ptr' specifies the pointer to the region of the new content.
- `size' specifies the size of the new content.
- If `index' is equal to or more than the number of elements, this function has no effect.
The function `tclistover2' is used in order to overwrite a string element at the specified location of a list object.
void tclistover2(TCLIST *list, int index, const char *str);
- `list' specifies the list object.
- `index' specifies the index of the element to be overwritten.
- `str' specifies the string of the new content.
- If `index' is equal to or more than the number of elements, this function has no effect.
The function `tclistsort' is used in order to sort elements of a list object in lexical order.
void tclistsort(TCLIST *list);
- `list' specifies the list object.
The function `tclistsortci' is used in order to sort elements of a list object in case-insensitive lexical order.
void tclistsortci(TCLIST *list);
- `list' specifies the list object.
The function `tclistlsearch' is used in order to search a list object for an element using liner search.
int tclistlsearch(const TCLIST *list, const void *ptr, int size);
- `list' specifies the list object.
- `ptr' specifies the pointer to the region of the key.
- `size' specifies the size of the region.
- The return value is the index of a corresponding element or -1 if there is no corresponding element.
- If two or more elements correspond, the former returns.
The function `tclistbsearch' is used in order to search a list object for an element using binary search.
int tclistbsearch(const TCLIST *list, const void *ptr, int size);
- `list' specifies the list object. It should be sorted in lexical order.
- `ptr' specifies the pointer to the region of the key.
- `size' specifies the size of the region.
- The return value is the index of a corresponding element or -1 if there is no corresponding element.
- If two or more elements correspond, which returns is not defined.
The function `tclistclear' is used in order to clear a list object.
void tclistclear(TCLIST *list);
- `list' specifies the list object.
- All elements are removed.
The function `tclistdump' is used in order to serialize a list object into a byte array.
void *tclistdump(const TCLIST *list, int *sp);
- `list' specifies the list object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the result serial region.
- 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 `tclistload' is used in order to create a list object from a serialized byte array.
TCLIST *tclistload(const void *ptr, int size);
- `ptr' specifies the pointer to the region of serialized byte array.
- `size' specifies the size of the region.
- The return value is a new list object.
- 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.
API of Hash Map
The function `tcmapnew' is used in order to create a map object.
TCMAP *tcmapnew(void);
- The return value is the new map object.
The function `tcmapnew2' is used in order to create a map object with specifying the number of the buckets.
TCMAP *tcmapnew2(int bnum);
- `bnum' specifies the number of the buckets.
- The return value is the new map object.
The function `tcmapdup' is used in order to copy a map object.
TCMAP *tcmapdup(const TCMAP *map);
- `map' specifies the map object.
- The return value is the new map object equivalent to the specified object.
The function `tcmapdel' is used in order to delete a map object.
void tcmapdel(TCMAP *map);
- `map' specifies the list object.
- Note that the deleted object and its derivatives can not be used anymore.
The function `tcmapput' is used in order to store a record into a map object.
void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If a record with the same key exists in the database, it is overwritten.
The function `tcmapput2' is used in order to store a string record into a map object.
void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);
- `map' specifies the map object.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- `over' specifies whether the value of the duplicated record is overwritten or not.
- If a record with the same key exists in the database, it is overwritten.
The function `tcmapputkeep' is used in order to store a new record into a map object.
bool tcmapputkeep(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tcmapputkeep2' is used in order to store a new string record into a map object.
bool tcmapputkeep2(TCMAP *map, const char *kstr, const char *vstr);
- `map' specifies the map object.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tcmapputcat' is used in order to concatenate a value at the end of the value of the existing record in a map object.
void tcmapputcat(TCMAP *map, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If there is no corresponding record, a new record is created.
The function `tcmapputcat2' is used in order to concatenate a string value at the end of the value of the existing record in a map object.
void tcmapputcat2(TCMAP *map, const char *kstr, const char *vstr);
- `map' specifies the map object.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If there is no corresponding record, a new record is created.
The function `tcmapout' is used in order to remove a record of a map object.
bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is true. False is returned when no record corresponds to the specified key.
The function `tcmapout2' is used in order to remove a string record of a map object.
bool tcmapout2(TCMAP *map, const void *kstr);
- `map' specifies the map object.
- `kstr' specifies the string of the key.
- If successful, the return value is true. False is returned when no record corresponds to the specified key.
The function `tcmapget' is used in order to retrieve a record in a map object.
const void *tcmapget(const TCMAP *map, const void *kbuf, int ksiz, int *sp);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the value of the corresponding record. `NULL' is returned when no record corresponds.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.
The function `tcmapget2' is used in order to retrieve a string record in a map object.
const char *tcmapget2(const TCMAP *map, const char *kstr);
- `map' specifies the map object.
- `kstr' specifies the string of the key.
- If successful, the return value is the string of the value of the corresponding record. `NULL' is returned when no record corresponds.
The function `tcmapmove' is used in order to move a record to the edge of a map object.
bool tcmapmove(TCMAP *map, const void *kbuf, int ksiz, bool head);
- `map' specifies the map object.
- `kbuf' specifies the pointer to the region of a key.
- `ksiz' specifies the size of the region of the key.
- `head' specifies the destination which is head if it is true or tail if else.
- If successful, the return value is true. False is returned when no record corresponds to the specified key.
The function `tcmapmove2' is used in order to move a string record to the edge of a map object.
bool tcmapmove2(TCMAP *map, const char *kstr, bool head);
- `map' specifies the map object.
- `kstr' specifies the string of a key.
- `head' specifies the destination which is head if it is true or tail if else.
- If successful, the return value is true. False is returned when no record corresponds to the specified key.
The function `tcmapiterinit' is used in order to initialize the iterator of a map object.
void tcmapiterinit(TCMAP *map);
- `map' specifies the map object.
- The iterator is used in order to access the key of every record stored in the map object.
The function `tcmapiternext' is used in order to get the next key of the iterator of a map object.
const void *tcmapiternext(TCMAP *map, int *sp);
- `map' specifies the map object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the next key, else, it is `NULL'. `NULL' is returned when no record can be fetched from the iterator.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. The order of iteration is assured to be the same as the stored order.
The function `tcmapiternext2' is used in order to get the next key string of the iterator of a map object.
const char *tcmapiternext2(TCMAP *map);
- `map' specifies the map object.
- If successful, the return value is the pointer to the region of the next key, else, it is `NULL'. `NULL' is returned when no record can be fetched from the iterator.
- The order of iteration is assured to be the same as the stored order.
The function `tcmapiterval' is used in order to get the value bound to the key fetched from the iterator of a map object.
const void *tcmapiterval(const void *kbuf, int *sp);
- `kbuf' specifies the pointer to the region of the iteration key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the value of the corresponding record.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.
The function `tcmapiterval2' is used in order to get the value string bound to the key fetched from the iterator of a map object.
const char *tcmapiterval2(const char *kstr);
- `kstr' specifies the string of the iteration key.
- The return value is the pointer to the region of the value of the corresponding record.
The function `tcmaprnum' is used in order to get the number of records stored in a map object.
int tcmaprnum(const TCMAP *map);
- `map' specifies the map object.
- The return value is the number of the records stored in the map object.
The function `tcmapkeys' is used in order to create a list object containing all keys in a map object.
TCLIST *tcmapkeys(const TCMAP *map);
- `map' specifies the map object.
- The return value is the new list object containing all keys in the map object.
- 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 `tcmapvals' is used in order to create a list object containing all values in a map object.
TCLIST *tcmapvals(const TCMAP *map);
- `map' specifies the map object.
- The return value is the new list object containing all values in the map object.
- 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 `tcmapclear' is used in order to clear a list object.
void tcmapclear(TCMAP *map);
- `map' specifies the map object.
- All records are removed.
The function `tcmapdump' is used in order to serialize map list object into a byte array.
void *tcmapdump(const TCMAP *map, int *sp);
- `map' specifies the map object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the result serial region.
- 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 `tcmapload' is used in order to create a map object from a serialized byte array.
TCMAP *tcmapload(const void *ptr, int size);
- `ptr' specifies the pointer to the region of serialized byte array.
- `size' specifies the size of the region.
- The return value is a new map object.
- Because the object of the return value is created with the function `tcmapnew', it should be deleted with the function `tcmapdel' when it is no longer in use.
The function `tcmaploadone' is used in order to extract a map record from a serialized byte array.
void *tcmaploadone(const void *ptr, int size, const void *kbuf, int ksiz, int *sp);
- `ptr' specifies the pointer to the region of serialized byte array.
- `size' specifies the size of the region.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the value of the corresponding record. `NULL' is returned when no record corresponds.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.
API of Memory Pool
The function `tcmpoolnew' is used in order to create a memory pool object.
TCMPOOL *tcmpoolnew(void);
- The return value is the new memory pool object.
The function `tcmpooldel' is used in order to delete a memory pool object.
void tcmpooldel(TCMPOOL *mpool);
- `mpool' specifies the memory pool object.
- Note that the deleted object and its derivatives can not be used anymore.
The function `tcmpoolput' is used in order to relegate an arbitrary object to a memory pool object.
void tcmpoolput(TCMPOOL *mpool, void *ptr, void (*del)(void *));
- `mpool' specifies the memory pool object.
- `ptr' specifies the pointer to the object to be relegated.
- `del' specifies the pointer to the function to delete the object.
- This function assures that the specified object is deleted when the memory pool object is deleted.
The function `tcmpoolputptr' is used in order to relegate an allocated region to a memory pool object.
void tcmpoolputptr(TCMPOOL *mpool, void *ptr);
- `ptr' specifies the pointer to the region to be relegated.
- This function assures that the specified region is released when the memory pool object is deleted.
The function `tcmpoolputxstr' is used in order to relegate an extensible string object to a memory pool object.
void tcmpoolputxstr(TCMPOOL *mpool, TCXSTR *xstr);
- `mpool' specifies the memory pool object.
- `xstr' specifies the extensible string object.
- This function assures that the specified object is deleted when the memory pool object is deleted.
The function `tcmpoolputlist' is used in order to relegate a list object to a memory pool object.
void tcmpoolputlist(TCMPOOL *mpool, TCLIST *list);
- `mpool' specifies the memory pool object.
- `list' specifies the list object.
- This function assures that the specified object is deleted when the memory pool object is deleted.
The function `tcmpoolputmap' is used in order to relegate a map object to a memory pool object.
void tcmpoolputmap(TCMPOOL *mpool, TCMAP *map);
- `mpool' specifies the memory pool object.
- `map' specifies the map object.
- This function assures that the specified object is deleted when the memory pool object is deleted.
The function `tcmpoolmalloc' is used in order to allocate a region relegated to a memory pool object.
void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);
- `mpool' specifies the memory pool object.
- The return value is the pointer to the allocated region under the memory pool.
The function `tcmpoolxstrnew' is used in order to create an extensible string object relegated to a memory pool object.
TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);
- The return value is the new extensible string object under the memory pool.
The function `tcmpoollistnew' is used in order to create a list object relegated to a memory pool object.
TCLIST *tcmpoollistnew(TCMPOOL *mpool);
- The return value is the new list object under the memory pool.
The function `tcmpoolmapnew' is used in order to create a map object relegated to a memory pool object.
TCMAP *tcmpoolmapnew(TCMPOOL *mpool);
- The return value is the new map object under the memory pool.
The function `tcmpoolglobal' is used in order to get the global memory pool object.
TCMPOOL *tcmpoolglobal(void);
- The return value is the global memory pool object.
- The global memory pool object is a singleton and assured to be deleted when the process is terminating normally.
API of Miscellaneous Utilities
The function `tclmax' is used in order to get the larger value of two integers.
long tclmax(long a, long b);
- `a' specifies an integer.
- `b' specifies the other integer.
- The return value is the larger value of the two.
The function `tclmin' is used in order to get the lesser value of two integers.
long tclmin(long a, long b);
- `a' specifies an integer.
- `b' specifies the other integer.
- The return value is the lesser value of the two.
The function `tcstricmp' is used in order to compare two strings with case insensitive evaluation.
int tcstricmp(const char *astr, const char *bstr);
- `astr' specifies a string.
- `bstr' specifies of the other string.
- The return value is positive if the former is big, negative if the latter is big, 0 if both are equivalent.
The function `tcstrfwm' is used in order to check whether a string begins with a key.
bool tcstrfwm(const char *str, const char *key);
- `str' specifies the target string.
- `key' specifies the forward matching key string.
- The return value is true if the target string begins with the key, else, it is false.
The function `tcstrifwm' is used in order to check whether a string begins with a key with case insensitive evaluation.
bool tcstrifwm(const char *str, const char *key);
- `str' specifies the target string.
- `key' specifies the forward matching key string.
- The return value is true if the target string begins with the key, else, it is false.
The function `tcstrbwm' is used in order to check whether a string ends with a key.
bool tcstrbwm(const char *str, const char *key);
- `str' specifies the target string.
- `key' specifies the backward matching key string.
- The return value is true if the target string ends with the key, else, it is false.
The function `tcstribwm' is used in order to check whether a string ends with a key with case insensitive evaluation.
bool tcstribwm(const char *str, const char *key);
- `str' specifies the target string.
- `key' specifies the backward matching key string.
- The return value is true if the target string ends with the key, else, it is false.
The function `tcstrtoupper' is used in order to convert the letters of a string into upper case.
char *tcstrtoupper(char *str);
- `str' specifies the string to be converted.
- The return value is the string itself.
The function `tcstrtolower' is used in order to convert the letters of a string into lower case.
char *tcstrtolower(char *str);
- `str' specifies the string to be converted.
- The return value is the string itself.
The function `tcstrtrim' is used in order to cut space characters at head or tail of a string.
char *tcstrtrim(char *str);
- `str' specifies the string to be converted.
- The return value is the string itself.
The function `tcstrsqzspc' is used in order to squeeze space characters in a string and trim it.
char *tcstrsqzspc(char *str);
- `str' specifies the string to be converted.
- The return value is the string itself.
The function `tcstrsubchr' is used in order to substitute characters in a string.
char *tcstrsubchr(char *str, const char *rstr, const char *sstr);
- `str' specifies the string to be converted.
- `rstr' specifies the string containing characters to be replaced.
- `sstr' specifies the string containing characters to be substituted.
- If the substitute string is shorter then the replacement string, corresponding characters are removed.
The function `tcstrcntutf' is used in order to count the number of characters in a string of UTF-8.
int tcstrcntutf(const char *str);
- `str' specifies the string of UTF-8.
- The return value is the number of characters in the string.
The function `tcstrcututf' is used in order to cut a string of UTF-8 at the specified number of characters.
char *tcstrcututf(char *str, int num);
- `str' specifies the string of UTF-8.
- `num' specifies the number of characters to be kept.
- The return value is the string itself.
The function `tcstrsplit' is used in order to create a list object by splitting a string.
TCLIST *tcstrsplit(const char *str, const char *delim);
- `str' specifies the source string.
- `delim' specifies a string containing delimiting characters.
- The return value is a list object of the split elements.
- If two delimiters are successive, it is assumed that an empty element is between the two. 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 `tctime' is used in order to get the time of day in milliseconds.
double tctime(void);
- The return value is the time of day in milliseconds.
API of Filesystem Utilities
The function `tcreadfile' is used in order to read whole data of a file.
void *tcreadfile(const char *path, int limit, int *sp);
- `path' specifies the path of the file. If it is `NULL', the standard input is specified.
- `limit' specifies the limiting size of reading data. If it is not more than 0, the limitation is not specified.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned. If it is `NULL', it is not used.
- The return value is the pointer to the allocated region of the read data, or `NULL' if the file could not be opened.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call when when is no longer in use.
The function `tcreadfilelines' is used in order to read every line of a file.
TCLIST *tcreadfilelines(const char *path);
- `path' specifies the path of the file. If it is `NULL', the standard input is specified.
- The return value is a list object of every lines if successful, else it is `NULL'.
- Line separators are cut out. 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 `tcwritefile' is used in order to write data into a file.
bool tcwritefile(const char *path, const void *ptr, int size);
- `path' specifies the path of the file. If it is `NULL', the standard output is specified.
- `ptr' specifies the pointer to the data region.
- `size' specifies the size of the region.
- If successful, the return value is true, else, it is false.
The function `tcreaddir' is used in order to read names of files in a directory.
TCLIST *tcreaddir(const char *path);
- `path' specifies the path of the directory.
- The return value is a list object of names if successful, else it is `NULL'.
- Links to the directory itself and to the parent directory are ignored.
- 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 `tcremovelink' is used in order to remove a file or a directory and its sub ones recursively.
bool tcremovelink(const char *path);
- `path' specifies the path of the link.
- If successful, the return value is true, else, it is false. False is returned when the link does not exist or the permission is denied.
The function `tcwrite' is used in order to write data into a file.
bool tcwrite(int fd, const void *buf, size_t size);
- `fd' specifies the file descriptor.
- `buf' specifies the buffer to be written.
- `size' specifies the size of the buffer.
- The return value is true if successful, else, it is false.
The function `tcread' is used in order to read data from a file.
bool tcread(int fd, void *buf, size_t size);
- `fd' specifies the file descriptor.
- `buf' specifies the buffer to store into.
- `size' specifies the size of the buffer.
- The return value is true if successful, else, it is false.
The function `tclock' is used in order to lock a file.
bool tclock(int fd, bool ex, bool nb);
- `fd' specifies the file descriptor.
- `ex' specifies whether an exclusive lock or a shared lock is performed.
- `nb' specifies whether to request with non-blocking.
- The return value is true if successful, else, it is false.
API of Encoding Utilities
The function `tcurlencode' is used in order to encode a serial object with URL encoding.
char *tcurlencode(const char *ptr, int size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the result string.
- Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if when is no longer in use.
The function `tcurldecode' is used in order to decode a string encoded with URL encoding.
char *tcurldecode(const char *str, int *sp);
- `str' specifies the encoded string.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the result.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcurlbreak' is used in order to break up a URL into elements.
TCMAP *tcurlbreak(const char *str);
- `str' specifies the URL string.
- The return value is the map handle whose keys are the name of elements. The key "self" specifies the URL itself. The key "scheme" specifies the scheme. The key "host" specifies the host of the server. The key "port" specifies the port number of the server. The key "authority" specifies the authority information. The key "path" specifies the path of the resource. The key "file" specifies the file name without the directory section. The key "query" specifies the query string. The key "fragment" specifies the fragment string.
- Supported schema are HTTP, HTTPS, FTP, and FILE. Absolute URL and relative URL are supported. Because the object of the return value is created with the function `tcmapnew', it should be deleted with the function `tcmapdel' when it is no longer in use.
The function `tcurlresolve' is used in order to resolve a relative URL with an absolute URL.
char *tcurlresolve(const char *base, const char *target);
- `base' specifies the absolute URL of the base location.
- `target' specifies the URL to be resolved.
- The return value is the resolved URL. If the target URL is relative, a new URL of relative location from the base location is returned. Else, a copy of the target URL is returned.
- 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 `tcbaseencode' is used in order to encode a serial object with Base64 encoding.
char *tcbaseencode(const char *ptr, int size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the result string.
- Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if when is no longer in use.
The function `tcbasedecode' is used in order to decode a string encoded with Base64 encoding.
char *tcbasedecode(const char *str, int *sp);
- `str' specifies the encoded string.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the result.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcquoteencode' is used in order to encode a serial object with Quoted-printable encoding.
char *tcquoteencode(const char *ptr, int size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the result string.
- Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if when is no longer in use.
The function `tcquotedecode' is used in order to decode a string encoded with Quoted-printable encoding.
char *tcquotedecode(const char *str, int *sp);
- `str' specifies the encoded string.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- The return value is the pointer to the region of the result.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcmimeencode' is used in order to encode a string with MIME encoding.
char *tcmimeencode(const char *str, const char *encname, bool base);
- `str' specifies the string.
- `encname' specifies the string of the name of the character encoding.
- `base' specifies whether to use Base64 encoding. If it is false, Quoted-printable is used.
- The return value is the result string.
- 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 `tcmimedecode' is used in order to decode a string encoded with MIME encoding.
char *tcmimedecode(const char *str, char *enp);
- `str' specifies the encoded string.
- `enp' specifies the pointer to the region into which the name of encoding is written. If it is `NULL', it is not used. The size of the buffer should be equal to or more than 32 bytes.
- The return value is the result string.
- 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 `tcpackencode' is used in order to compress a serial object with Packbits encoding.
char *tcpackencode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, 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 `tcpackdecode' is used in order to decompress a serial object compressed with Packbits encoding.
char *tcpackdecode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, else, it is `NULL'.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcbsencode' is used in order to compress a serial object with TCBS encoding.
char *tcbsencode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, 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 `tcbsdecode' is used in order to decompress a serial object compressed with TCBS encoding.
char *tcbsdecode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, else, it is `NULL'.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcdeflate' is used in order to compress a serial object with Deflate encoding.
char *tcdeflate(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, 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 `tcinflate' is used in order to decompress a serial object compressed with Deflate encoding.
char *tcinflate(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, else, it is `NULL'.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcgzipencode' is used in order to compress a serial object with GZIP encoding.
char *tcgzipencode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, 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 `tcgzipdecode' is used in order to decompress a serial object compressed with GZIP encoding.
char *tcgzipdecode(const char *ptr, int size, int *sp);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- `sp' specifies the pointer to a variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the result object, else, it is `NULL'.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcgetcrc' is used in order to get the CRC32 checksum of a serial object.
unsigned int tcgetcrc(const char *ptr, int size);
- `ptr' specifies the pointer to the region.
- `size' specifies the size of the region.
- The return value is the CRC32 checksum of the object.
The function `tcxmlescape' is used in order to escape meta characters in a string with the entity references of XML.
char *tcxmlescape(const char *str);
- `str' specifies the string.
- The return value is the pointer to the escaped string.
- This function escapes only `&', `<', `>', and `"'. 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 `tcxmlunescape' is used in order to unescape entity references in a string of XML.
char *tcxmlunescape(const char *str);
- `str' specifies the string.
- The return value is the unescaped string.
- This function restores only `&', `<', `>', and `"'. 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 `tcxmlbreak' is used in order to split an XML string into tags and text sections.
TCLIST *tcxmlbreak(const char *str);
- `str' specifies the XML string.
- The return value is the list object whose elements are strings of tags or text sections.
- 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. Because this function does not check validation, it can handle also HTML and SGML.
The function `tcxmlattrs' is used in order to get the map of attributes of an XML tag.
TCMAP *tcxmlattrs(const char *str);
- `str' specifies the pointer to the region of a tag string.
- The return value is the map object containing attribute names and their values which are unescaped. You can get the name of the tag with the key of an empty string.
- Because the object of the return value is created with the function `tcmapnew', it should be deleted with the function `tcmapdel' when it is no longer in use.
Example
The following code is an example using extensible string, array list, and hash map.
#include <tcutil.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
int main(int argc, char **argv){
{ /* example to use an extensible string object */
TCXSTR *xstr;
/* create the object */
xstr = tcxstrnew();
/* concatenate strings */
tcxstrcat2(xstr, "hop");
tcxstrcat2(xstr, "step");
tcxstrcat2(xstr, "jump");
/* print the size and the content */
printf("%d:%s\n", tcxstrsize(xstr), (char *)tcxstrptr(xstr));
/* delete the object */
tcxstrdel(xstr);
}
{ /* example to use a list object */
TCLIST *list;
int i;
/* create the object */
list = tclistnew();
/* add strings to the tail */
tclistpush2(list, "hop");
tclistpush2(list, "step");
tclistpush2(list, "jump");
/* print all elements */
for(i = 0; i < tclistnum(list); i++){
printf("%d:%s\n", i, tclistval2(list, i));
}
/* delete the object */
tclistdel(list);
}
{ /* example to use a map object */
TCMAP *map;
const char *key;
/* create the object */
map = tcmapnew();
/* add records */
tcmapput2(map, "foo", "hop");
tcmapput2(map, "bar", "step");
tcmapput2(map, "baz", "jump");
/* print all records */
tcmapiterinit(map);
while((key = tcmapiternext2(map)) != NULL){
printf("%s:%s\n", key, tcmapget2(map, key));
}
/* delete the object */
tcmapdel(map);
}
return 0;
}
CLI
To use the utility API easily, the commands `tcutest
' and `tcucodec
' are provided.
The command `tcutest
' is a utility for facility test and performance test. This command is used in the following format. `rnum' specifies the number of iterations. `anum' specifies the initial number of elements of array. `bnum' specifies the number of buckets.
tcutest xstr rnum
- Perform test of extensible string.
tcutest list rnum [anum]
- Perform test of array list.
tcutest map rnum [bnum]
- Perform test of hash map.
tcutest misc rnum
- Perform test of miscellaneous routines.
tcutest wicked rnum
- Perform updating operations of list and map selected at random.
This command returns 0 on success, another on failure.
The command `tcucodec
' is a tool to use encoding and decoding features. This command is used in the following format. `file' specifies a input file. If it is omitted, the standard input is read.
tcucodec url [-d] [-br] [-rs base] [file]
- Perform URL encoding and its decoding.
tcucodec base [-d] [file]
- Perform Base64 encoding and its decoding.
tcucodec quote [-d] [file]
- Perform quoted-printable encoding and its decoding.
tcucodec mime [-d] [-en name] [-q] [file]
- Perform MIME encoding and its decoding.
tcucodec pack [-d] [-bwt] [file]
- Perform Packbits encoding and its decoding.
tcucodec tcbs [-d] [file]
- Perform TCBS encoding and its decoding.
tcucodec zlib [-d] [-gz] [file]
- Perform ZLIB encoding and its decoding.
tcucodec xml [-d] [-br] [file]
- Process XML. By default, escape meta characters.
tcucodec conf [-v|-i|-l|-p]
- Print some configurations.
Options feature the following.
-d
: perform decoding (unescaping), not encoding (escaping).
-br
: break up URL or XML into elements.
-rs base
: specify the base URL and resolve the relative URL.
-en name
: specify the input encoding, which is UTF-8 by default.
-q
: use quoted-printable encoding, which is Base64 by default.
-bwt
: convert by BWT as preprocessing.
-gz
: use GZIP format.
-v
: show the version number of Tokyo Cabinet.
-i
: show options to include the headers of Tokyo Cabinet.
-l
: show options to link the library of Tokyo Cabinet.
-p
: show the directory path of the commands of Tokyo Cabinet.
This command returns 0 on success, another on failure.
The Hash Database API
Hash database is a file containing a hash table and is handled with the hash database API. See `tchdb.h
' for entire specification.
Description
To use the hash database API, include `tcutil.h
', `tchdb.h
', and related standard header files. Usually, write the following description near the front of a source file.
#include <tcutil.h>
#include <tchdb.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
Objects whose type is pointer to `TCHDB
' are used to handle hash databases. A hash database object is created with the function `tchdbnew
' and is deleted with the function `tchdbdel
'. 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 hash database object to it. The function `tchdbopen
' is used to open a database file and the function `tchdbclose
' 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 `tchdberrmsg' is used in order to get the message string corresponding to an error code.
const char *tchdberrmsg(int ecode);
- `ecode' specifies the error code.
The function `tchdbnew' is used in order to create a hash database object.
TCHDB *tchdbnew(void);
- The return value is the new hash database object.
The function `tchdbdel' is used in order to delete a hash database object.
void tchdbdel(TCHDB *hdb);
- `hdb' specifies the hash 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 `tchdbecode' is used in order to get the last happened error code of a hash database object.
int tchdbecode(TCHDB *hdb);
- `hdb' specifies the hash 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 `tchdbsetmutex' is used in order to set mutual exclusion control of a hash database object for threading.
bool tchdbsetmutex(TCHDB *hdb);
- `hdb' specifies the hash database object which is not opened.
- If successful, the return value is true, else, it is false.
- Note that the mutual exclusion control of the database should be set before the database is opened.
The function `tchdbtune' is used in order to set the tuning parameters of a hash database object.
bool tchdbtune(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
- `hdb' specifies the hash database object which is not opened.
- `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is 16381. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records to be stored.
- `apow' specifies the size of record alignment by power of 2. If it is negative, the default value is specified. The default value is 4 standing for 2^4=16.
- `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the default value is specified. The default value is 10 standing for 2^10=1024.
- `opts' specifies options by bitwise or: `HDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies that each record is compressed with Deflate encoding, `HDBTTCBS' specifies that each record is compressed with TCBS encoding.
- If successful, the return value is true, else, it is false.
- Note that the tuning parameters of the database should be set before the database is opened.
The function `tchdbopen' is used in order to open a database file and connect a hash database object.
bool tchdbopen(TCHDB *hdb, const char *path, int omode);
- `hdb' specifies the hash database object which is not opened.
- `path' specifies the path of the database file.
- `omode' specifies the connection mode: `HDBOWRITER' as a writer, `HDBOREADER' as a reader. If the mode is `HDBOWRITER', the following may be added by bitwise or: `HDBOCREAT', which means it creates a new database if not exist, `HDBOTRUNC', which means it creates a new database regardless if one exists. Both of `HDBOREADER' and `HDBOWRITER' can be added to by bitwise or: `HDBONOLCK', which means it opens the database file without file locking, or `HDBOLCKNB', which means locking is performed without blocking.
- If successful, the return value is true, else, it is false.
The function `tchdbclose' is used in order to close a hash database object.
bool tchdbclose(TCHDB *hdb);
- `hdb' specifies the hash 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 `tchdbput' is used in order to store a record into a hash database object.
bool tchdbput(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `hdb' specifies the hash database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten.
The function `tchdbput2' is used in order to store a string record into a hash database object.
bool tchdbput2(TCHDB *hdb, const char *kstr, const char *vstr);
- `hdb' specifies the hash database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- `over' specifies whether the value of the duplicated record is overwritten or not.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten.
The function `tchdbputkeep' is used in order to store a new record into a hash database object.
bool tchdbputkeep(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `hdb' specifies the hash database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tchdbputkeep2' is used in order to store a new string record into a hash database object.
bool tchdbputkeep2(TCHDB *hdb, const char *kstr, const char *vstr);
- `hdb' specifies the hash database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tchdbputcat' is used in order to concatenate a value at the end of the existing record in a hash database object.
bool tchdbputcat(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `hdb' specifies the hash database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If there is no corresponding record, a new record is created.
The function `tchdbputcat2' is used in order to concatenate a string value at the end of the existing record in a hash database object.
bool tchdbputcat2(TCHDB *hdb, const char *kstr, const char *vstr);
- `hdb' specifies the hash database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If there is no corresponding record, a new record is created.
The function `tchdbputasync' is used in order to store a record into a hash database object in asynchronous fashion.
bool tchdbputasync(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `hdb' specifies the hash database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten. Records passed to this function are accumulated into the inner buffer and wrote into the file at a blast.
The function `tchdbputasync2' is used in order to store a string record into a hash database object in asynchronous fashion.
bool tchdbputasync2(TCHDB *hdb, const char *kstr, const char *vstr);
- `hdb' specifies the hash database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten. Records passed to this function are accumulated into the inner buffer and wrote into the file at a blast.
The function `tchdbout' is used in order to remove a record of a hash database object.
bool tchdbout(TCHDB *hdb, const void *kbuf, int ksiz);
- `hdb' specifies the hash database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is true, else, it is false.
The function `tchdbout2' is used in order to remove a string record of a hash database object.
bool tchdbout2(TCHDB *hdb, const char *kstr);
- `hdb' specifies the hash database object connected as a writer.
- `kstr' specifies the string of the key.
- If successful, the return value is true, else, it is false.
The function `tchdbget' is used in order to retrieve a record in a hash database object.
void *tchdbget(TCHDB *hdb, const void *kbuf, int ksiz, int *sp);
- `hdb' specifies the hash database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the value of the corresponding record. `NULL' is returned if no record corresponds.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tchdbget2' is used in order to retrieve a string record in a hash database object.
char *tchdbget2(TCHDB *hdb, const char *kstr);
- `hdb' specifies the hash database object.
- `kstr' specifies the string of the key.
- If successful, the return value is the string of the value of the corresponding record. `NULL' is returned if no record corresponds. 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 `tchdbget3' is used in order to retrieve a record in a hash database object and write the value into a buffer.
int tchdbget3(TCHDB *hdb, const void *kbuf, int ksiz, void *vbuf, int max);
- `hdb' specifies the hash database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the buffer into which the value of the corresponding record is written.
- `max' specifies the size of the buffer.
- If successful, the return value is the size of the written data, else, it is -1. -1 is returned if no record corresponds to the specified key.
- Note that an additional zero code is not appended at the end of the region of the writing buffer.
The function `tchdbvsiz' is used in order to get the size of the value of a record in a hash database object.
int tchdbvsiz(TCHDB *hdb, const void *kbuf, int ksiz);
- `hdb' specifies the hash database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is the size of the value of the corresponding record, else, it is -1.
The function `tchdbiterinit' is used in order to initialize the iterator of a hash database object.
bool tchdbiterinit(TCHDB *hdb);
- `hdb' specifies the hash database object.
- If successful, the return value is true, else, it is false.
- The iterator is used in order to access the key of every record stored in a database.
The function `tchdbiternext' is used in order to get the next key of the iterator of a hash database object.
void *tchdbiternext(TCHDB *hdb, int *sp);
- `hdb' specifies the hash database object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the next key, else, it is `NULL'. `NULL' is returned when no record is to be get out of the iterator.
- Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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. 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 `tchdbiternext2' is used in order to get the next key string of the iterator of a hash database object.
char *tchdbiternext2(TCHDB *hdb);
- `hdb' specifies the hash database object.
- If successful, the return value is the string of the next key, else, it is `NULL'. `NULL' is returned when no record is to be get out of the iterator.
- 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. It is possible to access every record by iteration of calling this function. 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 `tchdbiternext3' is used in order to get the next extensible objects of the iterator of a hash database object.
bool tchdbiternext3(TCHDB *hdb, TCXSTR *kxstr, TCXSTR *vxstr);
- `hdb' specifies the hash database object.
- `kxstr' specifies the object into which the next key is wrote down.
- `vxstr' specifies the object into which the next value is wrote down.
- If successful, the return value is true, else, it is false. False is returned when no record is to be get out of the iterator.
The function `tchdbsync' is used in order to synchronize updated contents of a hash database object with the file and the device.
bool tchdbsync(TCHDB *hdb);
- `hdb' specifies the hash 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 `tchdboptimize' is used in order to optimize the file of a hash database object.
bool tchdboptimize(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
- `hdb' specifies the hash database object connected as a writer.
- `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is two times of the number of records.
- `apow' specifies the size of record alignment by power of 2. If it is negative, the current setting is not changed.
- `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the current setting is not changed.
- `opts' specifies options by bitwise or: `HDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies that each record is compressed with Deflate encoding, `HDBTTCBS' specifies that each record is compressed with TCBS encoding. If it is `UINT8_MAX', the default setting is not changed.
- 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 `tchdbvanish' is used in order to remove all records of a hash database object.
bool tchdbvanish(TCHDB *hdb);
- `hdb' specifies the hash database object connected as a writer.
- If successful, the return value is true, else, it is false.
The function `tchdbpath' is used in order to get the file path of a hash database object.
const char *tchdbpath(TCHDB *hdb);
- `hdb' specifies the hash 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 `tchdbrnum' is used in order to get the number of records of a hash database object.
uint64_t tchdbrnum(TCHDB *hdb);
- `hdb' specifies the hash database object.
- The return value is the number of records or 0 if the object does not connect to any database file.
The function `tchdbfsiz' is used in order to get the size of the database file of a hash database object.
uint64_t tchdbfsiz(TCHDB *hdb);
- `hdb' specifies the hash database object.
- The return value is the size of the database file or 0 if the object does not connect to any database file.
Example Code
The following code is an example to use a hash database.
#include <tcutil.h>
#include <tchdb.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
int main(int argc, char **argv){
TCHDB *hdb;
int ecode;
char *key, *value;
/* create the object */
hdb = tchdbnew();
/* open the database */
if(!tchdbopen(hdb, "casket.hdb", HDBOWRITER | HDBOCREAT)){
ecode = tchdbecode(hdb);
fprintf(stderr, "open error: %s\n", tchdberrmsg(ecode));
}
/* store records */
if(!tchdbput2(hdb, "foo", "hop") ||
!tchdbput2(hdb, "bar", "step") ||
!tchdbput2(hdb, "baz", "jump")){
ecode = tchdbecode(hdb);
fprintf(stderr, "put error: %s\n", tchdberrmsg(ecode));
}
/* retrieve records */
value = tchdbget2(hdb, "foo");
if(value){
printf("%s\n", value);
free(value);
} else {
ecode = tchdbecode(hdb);
fprintf(stderr, "get error: %s\n", tchdberrmsg(ecode));
}
/* traverse records */
tchdbiterinit(hdb);
while((key = tchdbiternext2(hdb)) != NULL){
value = tchdbget2(hdb, key);
if(value){
printf("%s:%s\n", key, value);
free(value);
}
free(key);
}
/* close the database */
if(!tchdbclose(hdb)){
ecode = tchdbecode(hdb);
fprintf(stderr, "close error: %s\n", tchdberrmsg(ecode));
}
/* delete the object */
tchdbdel(hdb);
return 0;
}
CLI
To use the hash database API easily, the commands `tchtest
', `tchmttest
', and `tchmgr
' are provided.
The command `tchtest
' is a utility for facility test and performance test. This command is used in the following format. `path' specifies the path of a database file. `rnum' specifies the number of iterations. `bnum' specifies the number of buckets. `apow' specifies the power of the alignment. `fpow' specifies the power of the free block pool.
tchtest write [-mt] [-tl] [-td|-tb] [-nl|-nb] [-as] path rnum [bnum [apow [fpow]]]
- Store records with keys of 8 bytes. They change as `00000001', `00000002'...
tchtest read [-mt] [-nl|-nb] [-wb] path
- Retrieve all records of the database above.
tchtest remove [-mt] [-nl|-nb] path
- Remove all records of the database above.
tchtest rcat [-mt] [-tl] [-td|-tb] [-nl|-nb] [-pn num] [-rl] path rnum [bnum [apow [fpow]]]
- Store records with partway duplicated keys using concatenate mode.
tchtest misc [-mt] [-tl] [-td|-tb] [-nl|-nb] path rnum
- Perform miscellaneous test of various operations.
tchtest wicked [-mt] [-tl] [-td|-tb] [-nl|-nb] path rnum
- Perform updating operations selected at random.
Options feature the following.
-mt
: call the function `tchdbsetmutex'.
-tl
: enable the option `HDBTLARGE'.
-td
: enable the option `HDBTDEFLATE'.
-tb
: enable the option `HDBTTCBS'.
-nl
: enable the option `HDBNOLCK'.
-nb
: enable the option `HDBLCKNB'.
-as
: use the function `tchdbputasync' instead of `tchdbput'.
-wb
: use the function `tchdbget3' instead of `tchdbget'.
-pn num
: specify the number of patterns.
-rl
: set the length of values at random.
This command returns 0 on success, another on failure.
The command `tchmttest
' is a utility for facility test under multi-thread situation. This command is used in the following format. `path' specifies the path of a database file. `rnum' specifies the number of iterations. `bnum' specifies the number of buckets. `apow' specifies the power of the alignment. `fpow' specifies the power of the free block pool.
tchmttest write [-tl] [-td|-tb] [-nl|-nb] [-as] path tnum rnum [bnum] [apow] [fpow]
- Store records with keys of 8 bytes. They change as `00000001', `00000002'...
tchmttest read [-nl|-nb] [-wb] path tnum
- Retrieve all records of the database above.
tchmttest remove [-nl|-nb] [-wb] path tnum
- Remove all records of the database above.
tchmttest wicked [-tl] [-td|-tb] [-nl|-nb] [-nc] path tnum rnum
- Perform updating operations selected at random.
Options feature the following.
-tl
: enable the option `HDBTLARGE'.
-td
: enable the option `HDBTDEFLATE'.
-tb
: enable the option `HDBTTCBS'.
-nl
: enable the option `HDBNOLCK'.
-nb
: enable the option `HDBLCKNB'.
-as
: use the function `tchdbputasync' instead of `tchdbput'.
-wb
: use the function `tchdbget3' instead of `tchdbget'.
This command returns 0 on success, another on failure.
The command `tchmgr
' is a utility for test and debugging of the hash database API and its applications. `path' specifies the path of a database file. `bnum' specifies the number of buckets. `apow' specifies the power of the alignment. `fpow' specifies the power of the free block pool. `key' specifies the key of a record. `value' specifies the value of a record.
tchmgr create [-tl] [-td|-tb] path [bnum [apow [fpow]]]
- Create a database file.
tchmgr inform [-nl|-nb] path
- Print miscellaneous information to the standard output.
tchmgr put [-nl|-nb] [-sx] [-dk|-dc] path key value
- Store a record.
tchmgr out [-nl|-nb] [-sx] path key
- Remove a record.
tchmgr get [-nl|-nb] [-sx] [-px] [-nl] path key
- Print the value of a record.
tchmgr list [-nl|-nb] [-pv] path
- Print keys of all records, separated by line feeds.
tchmgr optimize [-tl] [-td|-tb] [-tz] [-nl|-nb] path [bnum [apow [fpow]]]
- Optimize a database file.
tchmgr version
- Print the version information of Tokyo Cabinet.
Options feature the following.
-tl
: enable the option `HDBTLARGE'.
-td
: enable the option `HDBTDEFLATE'.
-tb
: enable the option `HDBTTCBS'.
-nl
: enable the option `HDBNOLCK'.
-nb
: enable the option `HDBLCKNB'.
-sx
: input data is evaluated as a hexadecimal data string.
-dk
: use the function `tchdbputkeep' instead of `tchdbput'.
-dc
: use the function `tchdbputcat' instead of `tchdbput'.
-px
: output data is converted into a hexadecimal data string.
-pz
: do not append line feed at the end of the output.
-pv
: print values of record also.
-tz
: enable the option `UINT8_MAX'.
This command returns 0 on success, another on failure.
The B+ tree database API
B+ tree database is a file containing a B+ tree and is handled with the B+ tree database API. See `tcbdb.h
' for entire specification.
Description
To use the B+ tree database API, include `tcutil.h
', `tchdb.h
', `tcbdb.h
', and related standard header files. Usually, write the following description near the front of a source file.
#include <tcutil.h>
#include <tchdb.h>
#include <tcbdb.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
Objects whose type is pointer to `TCBDB
' are used to handle B+ tree databases. A B+ tree database object is created with the function `tcbdbnew
' and is deleted with the function `tcbdbdel
'. 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 B+ tree database object to it. The function `tcbdbopen
' is used to open a database file and the function `tcbdbclose
' 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 `tcbdberrmsg' is used in order to get the message string corresponding to an error code.
const char *tcbdberrmsg(int ecode);
- `ecode' specifies the error code.
The function `tcbdbnew' is used in order to create a B+ tree database object.
TCBDB *tcbdbnew(void);
- The return value is the new B+ tree database object.
The function `tcbdbdel' is used in order to delete a B+ tree database object.
void tcbdbdel(TCBDB *bdb);
- `bdb' specifies the B+ tree 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 `tcbdbecode' is used in order to get the last happened error code of a B+ tree database object.
int tcbdbecode(TCBDB *bdb);
- `bdb' specifies the B+ tree 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 `tcbdbsetmutex' is used in order to set mutual exclusion control of a B+ tree database object for threading.
bool tcbdbsetmutex(TCBDB *bdb);
- `bdb' specifies the B+ tree database object which is not opened.
- If successful, the return value is true, else, it is false.
- Note that the mutual exclusion control of the database should be set before the database is opened.
The function `tcbdbsetcmpfunc' is used in order to set the custom comparison function of a B+ tree database object.
bool tcbdbsetcmpfunc(TCBDB *bdb, BDBCMP cmp, void *cmpop);
- `bdb' specifies the B+ tree database object which is not opened.
- `cmp' specifies the pointer to the custom comparison function.
- `cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function. If it is not needed, `NULL' can be specified.
- If successful, the return value is true, else, it is false.
- The default comparison function compares keys of two records by lexical order. The functions `tcbdbcmplexical' (dafault), `tcbdbcmpdecimal', `tcbdbcmpint32', and `tcbdbcmpint64' are built-in. Note that the comparison function should be set before the database is opened. Moreover, user-defined comparison functions should be set every time the database is being opened.
The function `tcbdbtune' is used in order to set the tuning parameters of a B+ tree database object.
bool tcbdbtune(TCBDB *bdb, int32_t lmemb, int32_t nmemb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
- `bdb' specifies the B+ tree database object which is not opened.
- `lmemb' specifies the number of members in each leaf page. If it is not more than 0, the default value is specified. The default value is 128.
- `nmemb' specifies the number of members in each non-leaf page. If it is not more than 0, the default value is specified. The default value is 256.
- `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is 16381.
- `apow' specifies the size of record alignment by power of 2. If it is negative, the default value is specified. The default value is 8 standing for 2^8=256.
- `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the default value is specified. The default value is 10 standing for 2^10=1024.
- `opts' specifies options by bitwise or: `BDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each page is compressed with Deflate encoding, `BDBTTCBS' 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 of the database should be set before the database is opened.
The function `tcbdbsetcache' is used in order to set the caching parameters of a B+ tree database object.
bool tcbdbsetcache(TCBDB *bdb, int32_t lcnum, int32_t ncnum);
- `bdb' specifies the B+ tree database object which is not opened.
- `lcnum' specifies the maximum number of leaf nodes to be cached. If it is not more than 0, the default value is specified.
- `ncnum' specifies the maximum number of non-leaf nodes to be cached. If it is not more than 0, the default value is specified.
- If successful, the return value is true, else, it is false.
- Note that the tuning parameters of the database should be set before the database is opened.
The function `tcbdbopen' is used in order to open a database file and connect a B+ tree database object.
bool tcbdbopen(TCBDB *bdb, const char *path, int omode);
- `bdb' specifies the B+ tree database object which is not opened.
- `path' specifies the path of the database file.
- `omode' specifies the connection mode: `BDBOWRITER' as a writer, `BDBOREADER' as a reader. If the mode is `BDBOWRITER', the following may be added by bitwise or: `BDBOCREAT', which means it creates a new database if not exist, `BDBOTRUNC', which means it creates a new database regardless if one exists. Both of `BDBOREADER' and `BDBOWRITER' can be added to by bitwise or: `BDBONOLCK', which means it opens the database file without file locking, or `BDBOLCKNB', which means locking is performed without blocking.
- If successful, the return value is true, else, it is false.
The function `tcbdbclose' is used in order to close a B+ tree database object.
bool tcbdbclose(TCBDB *bdb);
- `bdb' specifies the B+ tree 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 `tcbdbput' is used in order to store a record into a B+ tree database object.
bool tcbdbput(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten.
The function `tcbdbput2' is used in order to store a string record into a B+ tree database object.
bool tcbdbput2(TCBDB *bdb, const char *kstr, const char *vstr);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- `over' specifies whether the value of the duplicated record is overwritten or not.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, it is overwritten.
The function `tcbdbputkeep' is used in order to store a new record into a B+ tree database object.
bool tcbdbputkeep(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tcbdbputkeep2' is used in order to store a new string record into a B+ tree database object.
bool tcbdbputkeep2(TCBDB *bdb, const char *kstr, const char *vstr);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, this function has no effect.
The function `tcbdbputcat' is used in order to concatenate a value at the end of the existing record in a B+ tree database object.
bool tcbdbputcat(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If there is no corresponding record, a new record is created.
The function `tcbdbputcat2' is used in order to concatenate a string value at the end of the existing record in a B+ tree database object.
bool tcbdbputcat2(TCBDB *bdb, const char *kstr, const char *vstr);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If there is no corresponding record, a new record is created.
The function `tcbdbputdup' is used in order to store a record into a B+ tree database object with allowing duplication of keys.
bool tcbdbputdup(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, the new record is placed after the existing one.
The function `tcbdbputdup2' is used in order to store a string record into a B+ tree database object with allowing duplication of keys.
bool tcbdbputdup2(TCBDB *bdb, const char *kstr, const char *vstr);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kstr' specifies the string of the key.
- `vstr' specifies the string of the value.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, the new record is placed after the existing one.
The function `tcbdbputdup3' is used in order to store records into a B+ tree database object with allowing duplication of keys.
bool tcbdbputdup3(TCBDB *bdb, const void *kbuf, int ksiz, const TCLIST *vals);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the common key.
- `ksiz' specifies the size of the region of the common key.
- `vals' specifies a list object containing values.
- If successful, the return value is true, else, it is false.
- If a record with the same key exists in the database, the new records are placed after the existing one.
The function `tcbdbout' is used in order to remove a record of a B+ tree database object.
bool tcbdbout(TCBDB *bdb, const void *kbuf, int ksiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is true, else, it is false.
- If the key of duplicated records is specified, the value of the first record is selected.
The function `tcbdbout2' is used in order to remove a string record of a B+ tree database object.
bool tcbdbout2(TCBDB *bdb, const char *kstr);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kstr' specifies the string of the key.
- If successful, the return value is true, else, it is false.
- If the key of duplicated records is specified, the value of the first record is selected.
The function `tcbdbout3' is used in order to remove records of a B+ tree database object.
bool tcbdbout3(TCBDB *bdb, const void *kbuf, int ksiz);
- `bdb' specifies the B+ tree database object connected as a writer.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is true, else, it is false.
- If the key of duplicated records is specified, all of them are removed.
The function `tcbdbget' is used in order to retrieve a record in a B+ tree database object.
void *tcbdbget(TCBDB *bdb, const void *kbuf, int ksiz, int *sp);
- `bdb' specifies the B+ tree database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the value of the corresponding record. `NULL' is returned if no record corresponds.
- If the key of duplicated records is specified, the value of the first record is selected. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. 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 `tcbdbget2' is used in order to retrieve a string record in a B+ tree database object.
char *tcbdbget2(TCBDB *bdb, const char *kstr);
- `bdb' specifies the B+ tree database object.
- `kstr' specifies the string of the key.
- If successful, the return value is the string of the value of the corresponding record. `NULL' is returned if no record corresponds.
- If the key of duplicated records is specified, the value of the first record is selected. 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 `tcbdbget3' is used in order to retrieve a record in a B+ tree database object as a volatile buffer.
const void *tcbdbget3(TCBDB *bdb, const void *kbuf, int ksiz, int *sp);
- `bdb' specifies the B+ tree database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the value of the corresponding record. `NULL' is returned if no record corresponds.
- If the key of duplicated records is specified, the value of the first record is selected. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is volatile and it may be spoiled by another operation of the database, the data should be copied into another involatile buffer immediately.
The function `tcbdbget4' is used in order to retrieve records in a B+ tree database object.
TCLIST *tcbdbget4(TCBDB *bdb, const void *kbuf, int ksiz);
- `bdb' specifies the B+ tree database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is a list object of the values of the corresponding records. `NULL' is returned if no record corresponds.
- 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 `tcbdbvnum' is used in order to get the number of records corresponding a key in a B+ tree database object.
int tcbdbvnum(TCBDB *bdb, const void *kbuf, int ksiz);
- `bdb' specifies the B+ tree database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is the number of the corresponding records, else, it is 0.
The function `tcbdbvsiz' is used in order to get the size of the value of a record in a B+ tree database object.
int tcbdbvsiz(TCBDB *bdb, const void *kbuf, int ksiz);
- `bdb' specifies the B+ tree database object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is the size of the value of the corresponding record, else, it is -1.
- If the key of duplicated records is specified, the value of the first record is selected.
The function `tcbdbsync' is used in order to synchronize updated contents of a B+ tree database object with the file and the device.
bool tcbdbsync(TCBDB *bdb);
- `bdb' specifies the B+ tree 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 `tcbdboptimize' is used in order to optimize the file of a B+ tree database object.
bool tcbdboptimize(TCBDB *bdb, int32_t lmemb, int32_t nmemb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
- `bdb' specifies the B+ tree database object connected as a writer.
- `lmemb' specifies the number of members in each leaf page. If it is not more than 0, the current setting is not changed.
- `nmemb' specifies the number of members in each non-leaf page. If it is not more than 0, the current setting is not changed.
- `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the current setting is not changed.
- `apow' specifies the size of record alignment by power of 2. If it is negative, the current setting is not changed.
- `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the current setting is not changed.
- `opts' specifies options by bitwise or: `BDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each record is compressed with Deflate encoding, `BDBTTCBS' specifies that each page is compressed with TCBS encoding. If it is `UINT8_MAX', the default setting is not changed.
- 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 `tcbdbvanish' is used in order to remove all records of a B+ tree database object.
bool tcbdbvanish(TCBDB *bdb);
- `bdb' specifies the B+ tree database object connected as a writer.
- If successful, the return value is true, else, it is false.
The function `tcbdbtranbegin' is used in order to begin the transaction of a B+ tree database object.
bool tcbdbtranbegin(TCBDB *bdb);
- `bdb' specifies the B+ tree database object connected as a writer.
- If successful, the return value is true, else, it is false.
- The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. If the database is closed during transaction, the transaction is aborted implicitly.
The function `tcbdbtrancommit' is used in order to commit the transaction of a B+ tree database object.
bool tcbdbtrancommit(TCBDB *bdb);
- `bdb' specifies the B+ tree database object connected as a writer.
- If successful, the return value is true, else, it is false.
- Update in the transaction is fixed when it is committed successfully.
The function `tcbdbtranabort' is used in order to abort the transaction of a B+ tree database object.
bool tcbdbtranabort(TCBDB *bdb);
- `bdb' specifies the B+ tree database object connected as a writer.
- If successful, the return value is true, else, it is false.
- Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.
The function `tcbdbpath' is used in order to get the file path of a B+ tree database object.
const char *tcbdbpath(TCBDB *bdb);
- `bdb' specifies the B+ tree 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 `tcbdbrnum' is used in order to get the number of records of a B+ tree database object.
uint64_t tcbdbrnum(TCBDB *bdb);
- `bdb' specifies the B+ tree database object.
- The return value is the number of records or 0 if the object does not connect to any database file.
The function `tcbdbfsiz' is used in order to get the size of the database file of a B+ tree database object.
uint64_t tcbdbfsiz(TCBDB *bdb);
- `bdb' specifies the B+ tree database object.
- The return value is the size of the database file or 0 if the object does not connect to any database file.
The function `tcbdbcurnew' is used in order to create a cursor object.
BDBCUR *tcbdbcurnew(TCBDB *bdb);
- `bdb' specifies the B+ tree database object.
- The return value is the new cursor object.
- Note that the cursor is available only after initialization with the `tcbdbcurfirst' or the `tcbdbcurjump' functions and so on. Moreover, the position of the cursor will be indefinite when the database is updated after the initialization of the cursor.
The function `tcbdbcurdel' is used in order to delete a cursor object.
void tcbdbcurdel(BDBCUR *cur);
- `cur' specifies the cursor object.
The function `tcbdbcurfirst' is used in order to move a cursor object to the first record.
bool tcbdbcurfirst(BDBCUR *cur);
- `cur' specifies the cursor object.
- If successful, the return value is true, else, it is false. False is returned if there is no record in the database.
The function `tcbdbcurlast' is used in order to move a cursor object to the last record.
bool tcbdbcurlast(BDBCUR *cur);
- `cur' specifies the cursor object.
- If successful, the return value is true, else, it is false. False is returned if there is no record in the database.
The function `tcbdbcurjump' is used in order to move a cursor object to the front of records corresponding a key.
bool tcbdbcurjump(BDBCUR *cur, const void *kbuf, int ksiz);
- `cur' specifies the cursor object.
- `kbuf' specifies the pointer to the region of the key.
- `ksiz' specifies the size of the region of the key.
- If successful, the return value is true, else, it is false. False is returned if there is no record corresponding the condition.
- The cursor is set to the first record corresponding the key or the next substitute if completely matching record does not exist.
The function `tcbdbcurjump2' is used in order to move a cursor object to the front of records corresponding a key string.
bool tcbdbcurjump2(BDBCUR *cur, const char *kstr);
- `cur' specifies the cursor object.
- `kstr' specifies the string of the key.
- If successful, the return value is true, else, it is false. False is returned if there is no record corresponding the condition.
- The cursor is set to the first record corresponding the key or the next substitute if completely matching record does not exist.
The function `tcbdbcurprev' is used in order to move a cursor object to the previous record.
bool tcbdbcurprev(BDBCUR *cur);
- `cur' specifies the cursor object.
- If successful, the return value is true, else, it is false. False is returned if there is no previous record.
The function `tcbdbcurnext' is used in order to move a cursor object to the next record.
bool tcbdbcurnext(BDBCUR *cur);
- `cur' specifies the cursor object.
- If successful, the return value is true, else, it is false. False is returned if there is no next record.
The function `tcbdbcurput' is used in order to insert a record around a cursor object.
bool tcbdbcurput(BDBCUR *cur, const void *vbuf, int vsiz, int cpmode);
- `cur' specifies the cursor object of writer connection.
- `vbuf' specifies the pointer to the region of the value.
- `vsiz' specifies the size of the region of the value.
- `cpmode' specifies detail adjustment: `BDBCPCURRENT', which means that the value of the current record is overwritten, `BDBCPBEFORE', which means that the new record is inserted before the current record, `BDBCPAFTER', which means that the new record is inserted after the current record.
- If successful, the return value is true, else, it is false. False is returned when the cursor is at invalid position.
- After insertion, the cursor is moved to the inserted record.
The function `tcbdbcurput2' is used in order to insert a string record around a cursor object.
bool tcbdbcurput2(BDBCUR *cur, const char *vstr, int cpmode);
- `cur' specifies the cursor object of writer connection.
- `vstr' specifies the string of the value.
- `cpmode' specifies detail adjustment: `BDBCPCURRENT', which means that the value of the current record is overwritten, `BDBCPBEFORE', which means that the new record is inserted before the current record, `BDBCPAFTER', which means that the new record is inserted after the current record.
- If successful, the return value is true, else, it is false. False is returned when the cursor is at invalid position.
- After insertion, the cursor is moved to the inserted record.
The function `tcbdbcurout' is used in order to delete the record where a cursor object is.
bool tcbdbcurout(BDBCUR *cur);
- `cur' specifies the cursor object of writer connection.
- If successful, the return value is true, else, it is false. False is returned when the cursor is at invalid position.
- After deletion, the cursor is moved to the next record if possible.
The function `tcbdbcurkey' is used in order to get the key of the record where the cursor object is.
char *tcbdbcurkey(BDBCUR *cur, int *sp);
- `cur' specifies the cursor object.
- `sp' specifies the pointer to the variable into which the size of the region of the return value is assigned.
- If successful, the return value is the pointer to the region of the key, else, it is `NULL'. `NULL' is returned when the cursor is at invalid position.