spex-en.html

Tokyo Cabinet的Tokyo Cabinet 是一个DBM的实现。这里的数据库由一系列key-value对的记录构成。key和value都可以是任意长度的字节序列,既可以是二进制也可以是字符

/usr/local/bin/tcucodec
/usr/local/bin/tchtest
/usr/local/bin/tchmttest
/usr/local/bin/tchmgr
/usr/local/bin/tcbmgr
/usr/local/bin/tcbtest
/usr/local/bin/tcbmttest
/usr/local/bin/tcftest
/usr/local/bin/tcfmttest
/usr/local/bin/tcfmgr
/usr/local/bin/tcttest
/usr/local/bin/tctmttest
/usr/local/bin/tctmgr
/usr/local/bin/tcamgr
/usr/local/bin/tcatest
/usr/local/libexec/tcawmgr.cgi
/usr/local/share/tokyocabinet/...
/usr/local/man/man1/...
/usr/local/man/man3/...
</pre>

<h3 id="installation_option">Options of Configure</h3>

<p>The following options can be specified with `<code>./configure</code>'.</p>

<ul class="options">
<li><code>--enable-debug</code> : build for debugging.  Enable debugging symbols, do not perform optimization, and perform static linking.</li>
<li><code>--enable-devel</code> : build for development.  Enable debugging symbols, perform optimization, and perform dynamic linking.</li>
<li><code>--enable-profile</code> : build for profiling.  Enable profiling symbols, perform optimization, and perform dynamic linking.</li>
<li><code>--enable-static</code> : build by static linking.</li>
<li><code>--enable-fastest</code> : build for fastest run.</li>
<li><code>--enable-off64</code> : build with 64-bit file offset on 32-bit system.</li>
<li><code>--enable-swab</code> : build for swapping byte-orders.</li>
<li><code>--enable-uyield</code> : build for detecting race conditions.</li>
<li><code>--disable-zlib</code> : build without ZLIB compression.</li>
<li><code>--disable-bzip</code> : build without BZIP2 compression.</li>
<li><code>--disable-pthread</code> : build without POSIX thread support.</li>
<li><code>--disable-shared</code> :  avoid to build shared libraries.</li>
</ul>

<p>`<code>--prefix</code>' and other options are also available as with usual UNIX software packages.  If you want to install Tokyo Cabinet under `<code>/usr</code>' not `<code>/usr/local</code>', specify `<code>--prefix=/usr</code>'.  As well, the library search path does not include `<code>/usr/local/lib</code>', it is necessary to set the environment variable `<code>LD_LIBRARY_PATH</code>' to include `<code>/usr/local/lib</code>' before running applications of Tokyo Cabinet.</p>

<h3 id="installation_library">How to Use the Library</h3>

<p>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 `<code>tcutil.h</code>', `<code>tchdb.h</code>', `<code>tcbdb.h</code>', and `<code>tcadb.h</code>', applications should include one or more of them accordingly to use the API.  As the library is provided as `<code>libtokyocabinet.a</code>' and `<code>libtokyocabinet.so</code>' and they depends `<code>libz.so</code>', `<code>librt.so</code>', `<code>libpthread.so</code>', `<code>libm.so</code>', and `<code>libc.so</code>', linker options `<code>-ltokyocabinet</code>', `<code>-lz</code>', `<code>-lbz2</code>', `<code>-lrt</code>', `<code>-lpthread</code>', `<code>-lm</code>', and `<code>-lc</code>' are required for build command.  A typical build command is the following.</p>

<pre>gcc -I/usr/local/include tc_example.c -o tc_example \
  -L/usr/local/lib -ltokyocabinet -lz -lbz2 -lrt -lpthread -lm -lc
</pre>

<p>You can also use Tokyo Cabinet in programs written in C++.  Because each header is wrapped in C linkage (`<code>extern "C"</code>' block), you can simply include them into your C++ programs.</p>

<hr />

<h2 id="tcutilapi">The Utility API</h2>

<p>The utility API is a set of routines to handle records on memory easily.  Especially, extensible string, array list, hash map, and ordered tree are useful.  See `<code>tcutil.h</code>' for the entire specification.</p>

<h3 id="tcutilapi_description">Description</h3>

<p>To use the utility API, include `<code>tcutil.h</code>' and related standard header files.  Usually, write the following description near the front of a source file.</p>

<dl>
<dt><code>#include &lt;tcutil.h&gt;</code></dt>
<dt><code>#include &lt;stdlib.h&gt;</code></dt>
<dt><code>#include &lt;stdbool.h&gt;</code></dt>
<dt><code>#include &lt;stdint.h&gt;</code></dt>
</dl>

<p>Objects whose type is pointer to `<code>TCXSTR</code>' are used for extensible string.  An extensible string object is created with the function `<code>tcxstrnew</code>' and is deleted with the function `<code>tcxstrdel</code>'.  Objects whose type is pointer to `<code>TCLIST</code>' are used for array list.  A list object is created with the function `<code>tclistnew</code>' and is deleted with the function `<code>tclistdel</code>'.  Objects whose type is pointer to `<code>TCMAP</code>' are used for hash map.  A map object is created with the function `<code>tcmapnew</code>' and is deleted with the function `<code>tcmapdel</code>'.  Objects whose type is pointer to `<code>TCTREE</code>' are used for ordered tree.  A tree object is created with the function `<code>tctreenew</code>' and is deleted with the function `<code>tctreedel</code>'.  To avoid memory leak, it is important to delete every object when it is no longer in use.</p>

<h3 id="tcutilapi_basicapi">API of Basic Utilities</h3>

<p>The constant `tcversion' is the string containing the version information.</p>

<dl class="api">
<dt><code>extern const char *tcversion;</code></dt>
</dl>

<p>The variable `tcfatalfunc' is the pointer to the call back function for handling a fatal error.</p>

<dl class="api">
<dt><code>extern void (*tcfatalfunc)(const char *);</code></dt>
<dd>The argument specifies the error message.</dd>
<dd>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.</dd>
</dl>

<p>The function `tcmalloc' is used in order to allocate a region on memory.</p>

<dl class="api">
<dt><code>void *tcmalloc(size_t <var>size</var>);</code></dt>
<dd>`<var>size</var>' specifies the size of the region.</dd>
<dd>The return value is the pointer to the allocated region.</dd>
<dd>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.</dd>
</dl>

<p>The function `tccalloc' is used in order to allocate a nullified region on memory.</p>

<dl class="api">
<dt><code>void *tccalloc(size_t <var>nmemb</var>, size_t <var>size</var>);</code></dt>
<dd>`<var>nmemb</var>' specifies the number of elements.</dd>
<dd>`<var>size</var>' specifies the size of each element.</dd>
<dd>The return value is the pointer to the allocated nullified region.</dd>
<dd>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.</dd>
</dl>

<p>The function `tcrealloc' is used in order to re-allocate a region on memory.</p>

<dl class="api">
<dt><code>void *tcrealloc(void *<var>ptr</var>, size_t <var>size</var>);</code></dt>
<dd>`<var>ptr</var>' specifies the pointer to the region.</dd>
<dd>`<var>size</var>' specifies the size of the region.</dd>
<dd>The return value is the pointer to the re-allocated region.</dd>
<dd>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.</dd>
</dl>

<p>The function `tcmemdup' is used in order to duplicate a region on memory.</p>

<dl class="api">
<dt><code>void *tcmemdup(const void *<var>ptr</var>, size_t <var>size</var>);</code></dt>
<dd>`<var>ptr</var>' specifies the pointer to the region.</dd>
<dd>`<var>size</var>' specifies the size of the region.</dd>
<dd>The return value is the pointer to the allocated region of the duplicate.</dd>
<dd>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.</dd>
</dl>

<p>The function `tcstrdup' is used in order to duplicate a string on memory.</p>

<dl class="api">
<dt><code>char *tcstrdup(const void *<var>str</var>);</code></dt>
<dd>`<var>str</var>' specifies the string.</dd>
<dd>The return value is the allocated string equivalent to the specified string.</dd>
<dd>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.</dd>
</dl>

<p>The function `tcfree' is used in order to free a region on memory.</p>

<dl class="api">
<dt><code>void tcfree(void *<var>ptr</var>);</code></dt>
<dd>`<var>ptr</var>' specifies the pointer to the region.  If it is `NULL', this function has no effect.</dd>
<dd>Although this function is just a wrapper of `free' call, this is useful in applications using another package of the `malloc' series.</dd>
</dl>

<h3 id="tcutilapi_xstrapi">API of Extensible String</h3>

<p>The function `tcxstrnew' is used in order to create an extensible string object.</p>

<dl class="api">
<dt><code>TCXSTR *tcxstrnew(void);</code></dt>
<dd>The return value is the new extensible string object.</dd>
</dl>

<p>The function `tcxstrnew2' is used in order to create an extensible string object from a character string.</p>

<dl class="api">
<dt><code>TCXSTR *tcxstrnew2(const char *<var>str</var>);</code></dt>
<dd>`<var>str</var>' specifies the string of the initial content.</dd>
<dd>The return value is the new extensible string object containing the specified string.</dd>
</dl>

<p>The function `tcxstrnew3' is used in order to create an extensible string object with the initial allocation size.</p>

<dl class="api">
<dt><code>TCXSTR *tcxstrnew3(int <var>asiz</var>);</code></dt>
<dd>`<var>asiz</var>' specifies the initial allocation size.</dd>
<dd>The return value is the new extensible string object.</dd>
</dl>

<p>The function `tcxstrdup' is used in order to copy an extensible string object.</p>

<dl class="api">
<dt><code>TCXSTR *tcxstrdup(const TCXSTR *<var>xstr</var>);</code></dt>
<dd>`<var>xstr</var>' specifies the extensible string object.</dd>
<dd>The return value is the new extensible string object equivalent to the specified object.</dd>
</dl>

<p>The function `tcxstrdel' is used in order to delete an extensible string object.</p>

<dl class="api">
<dt><code>void tcxstrdel(TCXSTR *<var>xstr</var>);</code></dt>
<dd>`<var>xstr</var>' specifies the extensible string object.</dd>
<dd>Note that the deleted object and its derivatives can not be used anymore.</dd>
</dl>

<p>The function `tcxstrcat' is used in order to concatenate a region to the end of an extensible string object.</p>

<dl class="api">
<dt><code>void tcxstrcat(TCXSTR *<var>xstr</var>, const void *<var>ptr</var>, int <var>size</var>);</code></dt>
<dd>`<var>xstr</var>' specifies the extensible string object.</dd>
<dd>`<var>ptr</var>' specifies the pointer to the region to be appended.</dd>
<dd>`<var>size</var>' specifies the size of the region.</dd>
</dl>

<p>The function `tcxstrcat2' is used in order to concatenate a character string to the end of an extensible string object.</p>

<dl class="api">
<dt><code>void tcxstrcat2(TCXSTR *<var>xstr</var>, const char *<var>str</var>);</code></dt>
<dd>`<var>xstr</var>' specifies the extensible string object.</dd>
<dd>`<var>str</var>' specifies the string to be appended.</dd>
</dl>

<p>The function `tcxstrptr' is used in order to get the pointer of the region of an extensible string object.</p>

<dl class="api">
<dt><code>const void *tcxstrptr(const TCXSTR *<var>xstr</var>);</code></dt>