tctdb.3

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

`\fInum\fR' specifies the additional value.
.RE
.RS
If successful, the return value is the summation value, else, it is Not\-a\-Number.
.RE
.RS
The additional value is stored as a decimal string value of a column whose name is "_num".  If no record corresponds, a new record with the additional value is stored.
.RE
.RE
.PP
The function `tctdbsync' is used in order to synchronize updated contents of a table database object with the file and the device.
.PP
.RS
.br
\fBbool tctdbsync(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
This function is useful when another process connects to the same database file.
.RE
.RE
.PP
The function `tctdboptimize' is used in order to optimize the file of a table database object.
.PP
.RS
.br
\fBbool tctdboptimize(TCTDB *\fItdb\fB, int64_t \fIbnum\fB, int8_t \fIapow\fB, int8_t \fIfpow\fB, uint8_t \fIopts\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
`\fIbnum\fR' 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.
.RE
.RS
`\fIapow\fR' specifies the size of record alignment by power of 2.  If it is negative, the current setting is not changed.
.RE
.RS
`\fIfpow\fR' 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.
.RE
.RS
`\fIopts\fR' specifies options by bitwise-or: `TDBTLARGE' specifies that the size of the database can be larger than 2GB by using 64\-bit bucket array, `TDBTDEFLATE' specifies that each record is compressed with Deflate encoding, `TDBTBZIP' specifies that each record is compressed with BZIP2 encoding, `TDBTTCBS' specifies that each record is compressed with TCBS encoding.  If it is `UINT8_MAX', the current setting is not changed.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
This function is useful to reduce the size of the database file with data fragmentation by successive updating.
.RE
.RE
.PP
The function `tctdbvanish' is used in order to remove all records of a table database object.
.PP
.RS
.br
\fBbool tctdbvanish(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RE
.PP
The function `tctdbcopy' is used in order to copy the database file of a table database object.
.PP
.RS
.br
\fBbool tctdbcopy(TCTDB *\fItdb\fB, const char *\fIpath\fB);\fR
.RS
`\fItdb\fR' specifies the table database object.
.RE
.RS
`\fIpath\fR' specifies the path of the destination file.  If it begins with `@', the trailing substring is executed as a command line.
.RE
.RS
If successful, the return value is true, else, it is false.  False is returned if the executed command returns non\-zero code.
.RE
.RS
The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress.  So, this function is useful to create a backup file of the database file.
.RE
.RE
.PP
The function `tctdbtranbegin' is used in order to begin the transaction of a table database object.
.PP
.RS
.br
\fBbool tctdbtranbegin(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
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.  Because all pages are cached on memory while the transaction, the amount of referred records is limited by the memory capacity.  If the database is closed during transaction, the transaction is aborted implicitly.
.RE
.RE
.PP
The function `tctdbtrancommit' is used in order to commit the transaction of a table database object.
.PP
.RS
.br
\fBbool tctdbtrancommit(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
Update in the transaction is fixed when it is committed successfully.
.RE
.RE
.PP
The function `tctdbtranabort' is used in order to abort the transaction of a table database object.
.PP
.RS
.br
\fBbool tctdbtranabort(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
Update in the transaction is discarded when it is aborted.  The state of the database is rollbacked to before transaction.
.RE
.RE
.PP
The function `tctdbpath' is used in order to get the file path of a table database object.
.PP
.RS
.br
\fBconst char *tctdbpath(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object.
.RE
.RS
The return value is the path of the database file or `NULL' if the object does not connect to any database file.
.RE
.RE
.PP
The function `tctdbrnum' is used in order to get the number of records ccccof a table database object.
.PP
.RS
.br
\fBuint64_t tctdbrnum(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object.
.RE
.RS
The return value is the number of records or 0 if the object does not connect to any database file.
.RE
.RE
.PP
The function `tctdbfsiz' is used in order to get the size of the database file of a table database object.
.PP
.RS
.br
\fBuint64_t tctdbfsiz(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object.
.RE
.RS
The return value is the size of the database file or 0 if the object does not connect to any database file.
.RE
.RE
.PP
The function `tctdbsetindex' is used in order to set a column index to a table database object.
.PP
.RS
.br
\fBbool tctdbsetindex(TCTDB *\fItdb\fB, const char *\fIname\fB, int \fItype\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
`\fIname\fR' specifies the name of a column.  If the name of an existing index is specified, the index is rebuilt.  An empty string means the primary key.
.RE
.RS
`\fItype\fR' specifies the index type: `TDBITLEXICAL' for lexical string, `TDBITDECIMAL' for decimal string.  If it is `TDBITOPT', the index is optimized.  If it is `TDBITVOID', the index is removed.  If `TDBITKEEP' is added by bitwise\-or and the index exists, this function merely returns failure.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RS
Note that the setting indices should be set after the database is opened.
.RE
.RE
.PP
The function `tctdbgenuid' is used in order to generate a unique ID number of a table database object.
.PP
.RS
.br
\fBint64_t tctdbgenuid(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object connected as a writer.
.RE
.RS
The return value is the new unique ID number or \-1 on failure.
.RE
.RE
.PP
The function `tctdbqrynew' is used in order to create a query object.
.PP
.RS
.br
\fBTDBQRY *tctdbqrynew(TCTDB *\fItdb\fB);\fR
.RS
`\fItdb\fR' specifies the table database object.
.RE
.RS
The return value is the new query object.
.RE
.RE
.PP
The function `tctdbqrydel' is used in order to delete a query object.
.PP
.RS
.br
\fBvoid tctdbqrydel(TDBQRY *\fIqry\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RE
.PP
The function `tctdbqryaddcond' is used in order to add a narrowing condition to a query object.
.PP
.RS
.br
\fBvoid tctdbqryaddcond(TDBQRY *\fIqry\fB, const char *\fIname\fB, int \fIop\fB, const char *\fIexpr\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RS
`\fIname\fR' specifies the name of a column.  An empty string means the primary key.
.RE
.RS
`\fIop\fR' specifies an operation type: `TDBQCSTREQ' for string which is equal to the expression, `TDBQCSTRINC' for string which is included in the expression, `TDBQCSTRBW' for string which begins with the expression, `TDBQCSTREW' for string which ends with the expression, `TDBQCSTRAND' for string which includes all tokens in the expression, `TDBQCSTROR' for string which includes at least one token in the expression, `TDBQCSTROREQ' for string which is equal to at least one token in the expression, `TDBQCSTRRX' for string which matches regular expressions of the expression, `TDBQCNUMEQ' for number which is equal to the expression, `TDBQCNUMGT' for number which is greater than the expression, `TDBQCNUMGE' for number which is greater than or equal to the expression, `TDBQCNUMLT' for number which is less than the expression, `TDBQCNUMLE' for number which is less than or equal to the expression, `TDBQCNUMBT' for number which is between two tokens of the expression, `TDBQCNUMOREQ' for number which is equal to at least one token in the expression.  All operations can be flagged by bitwise-or: `TDBQCNEGATE' for negation, `TDBQCNOIDX' for using no index.
.RE
.RS
`\fIexpr\fR' specifies an operand exression.
.RE
.RE
.PP
The function `tctdbqrysetorder' is used in order to set the order of a query object.
.PP
.RS
.br
\fBvoid tctdbqrysetorder(TDBQRY *\fIqry\fB, const char *\fIname\fB, int \fItype\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RS
`\fIname\fR' specifies the name of a column.  An empty string means the primary key.
.RE
.RS
`\fItype\fR' specifies the order type: `TDBQOSTRASC' for string ascending, `TDBQOSTRDESC' for string descending, `TDBQONUMASC' for number ascending, `TDBQONUMDESC' for number descending.
.RE
.RE
.PP
The function `tctdbqrysetlimit' is used in order to set the limit number of records of the result of a query object.
.PP
.RS
.br
\fBvoid tctdbqrysetlimit(TDBQRY *\fIqry\fB, int \fImax\fB, int \fIskip\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RS
`\fImax\fR' specifies the maximum number of records of the result.  If it is negative, no limit is specified.
.RE
.RS
`\fIskip\fR' specifies the number of skipped records of the result.  If it is not more than 0, no record is skipped.
.RE
.RE
.PP
The function `tctdbqrysearch' is used in order to execute the search of a query object.
.PP
.RS
.br
\fBTCLIST *tctdbqrysearch(TDBQRY *\fIqry\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RS
The return value is a list object of the primary keys of the corresponding records.  This function does never fail and return an empty list even if no record corresponds.
.RE
.RS
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.
.RE
.RE
.PP
The function `tctdbqrysearchout' is used in order to remove each record corresponding to a query object.
.PP
.RS
.br
\fBbool tctdbqrysearchout(TDBQRY *\fIqry\fB);\fR
.RS
`\fIqry\fR' specifies the query object of the database connected as a writer.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RE
.PP
The function `tctdbqryproc' is used in order to process each record corresponding to a query object.
.PP
.RS
.br
\fBbool tctdbqryproc(TDBQRY *\fIqry\fB, TDBQRYPROC \fIproc\fB, void *\fIop\fB);\fR
.RS
`\fIqry\fR' specifies the query object of the database connected as a writer.
.RE
.RS
`\fIproc\fR' specifies the pointer to the iterator function called for each record.  It receives four parameters.  The first parameter is the pointer to the region of the primary key.  The second parameter is the size of the region of the primary key.  The third parameter is a map object containing columns.  The fourth parameter is the pointer to the optional opaque object.  It returns flags of the post treatment by bitwise-or: `TDBQPPUT' to modify the record, `TDBQPOUT' to remove the record, `TDBQPSTOP' to stop the iteration.
.RE
.RS
`\fIop\fR' specifies an arbitrary pointer to be given as a parameter of the iterator function.  If it is not needed, `NULL' can be specified.
.RE
.RS
If successful, the return value is true, else, it is false.
.RE
.RE
.PP
The function `tctdbqryhint' is used in order to get the hint of a query object.
.PP
.RS
.br
\fBconst char *tctdbqryhint(TDBQRY *\fIqry\fB);\fR
.RS
`\fIqry\fR' specifies the query object.
.RE
.RS
The return value is the hint string.
.RE
.RE

.SH SEE ALSO
.PP
.BR tcttest (1),
.BR tctmttest (1),
.BR tctmgr (1),
.BR tokyocabinet (3)