tctdb.h

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

   record is skipped. */
void tctdbqrysetlimit(TDBQRY *qry, int max, int skip);


/* Execute the search of a query object.
   `qry' specifies the query object.
   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.
   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. */
TCLIST *tctdbqrysearch(TDBQRY *qry);


/* Remove each record corresponding to a query object.
   `qry' specifies the query object of the database connected as a writer.
   If successful, the return value is true, else, it is false. */
bool tctdbqrysearchout(TDBQRY *qry);


/* Process each record corresponding to a query object.
   `qry' specifies the query object of the database connected as a writer.
   `proc' 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.
   `op' specifies an arbitrary pointer to be given as a parameter of the iterator function.  If
   it is not needed, `NULL' can be specified.
   If successful, the return value is true, else, it is false. */
bool tctdbqryproc(TDBQRY *qry, TDBQRYPROC proc, void *op);


/* Get the hint of a query object.
   `qry' specifies the query object.
   The return value is the hint string.
   This function should be called after the query execution by `tctdbqrysearch' and so on.  The
   region of the return value is overwritten when this function is called again. */
const char *tctdbqryhint(TDBQRY *qry);



/*************************************************************************************************
 * features for experts
 *************************************************************************************************/


/* Set the error code of a table database object.
   `tdb' specifies the table database object.
   `ecode' specifies the error code.
   `file' specifies the file name of the code.
   `line' specifies the line number of the code.
   `func' specifies the function name of the code. */
void tctdbsetecode(TCTDB *tdb, int ecode, const char *filename, int line, const char *func);


/* Set the file descriptor for debugging output.
   `tdb' specifies the table database object.
   `fd' specifies the file descriptor for debugging output. */
void tctdbsetdbgfd(TCTDB *tdb, int fd);


/* Get the file descriptor for debugging output.
   `tdb' specifies the table database object.
   The return value is the file descriptor for debugging output. */
int tctdbdbgfd(TCTDB *tdb);


/* Check whether mutual exclusion control is set to a table database object.
   `tdb' specifies the table database object.
   If mutual exclusion control is set, it is true, else it is false. */
bool tctdbhasmutex(TCTDB *tdb);


/* Synchronize updating contents on memory of a table database object.
   `tdb' specifies the table database object connected as a writer.
   `phys' specifies whether to synchronize physically.
   If successful, the return value is true, else, it is false. */
bool tctdbmemsync(TCTDB *tdb, bool phys);


/* Get the number of elements of the bucket array of a table database object.
   `tdb' specifies the table database object.
   The return value is the number of elements of the bucket array or 0 if the object does not
   connect to any database file. */
uint64_t tctdbbnum(TCTDB *tdb);


/* Get the record alignment of a table database object.
   `tdb' specifies the table database object.
   The return value is the record alignment or 0 if the object does not connect to any database
   file. */
uint32_t tctdbalign(TCTDB *tdb);


/* Get the maximum number of the free block pool of a table database object.
   `tdb' specifies the table database object.
   The return value is the maximum number of the free block pool or 0 if the object does not
   connect to any database file. */
uint32_t tctdbfbpmax(TCTDB *tdb);


/* Get the inode number of the database file of a table database object.
   `tdb' specifies the table database object.
   The return value is the inode number of the database file or 0 if the object does not connect
   to any database file. */
uint64_t tctdbinode(TCTDB *tdb);


/* Get the modification time of the database file of a table database object.
   `tdb' specifies the table database object.
   The return value is the inode number of the database file or 0 if the object does not connect
   to any database file. */
time_t tctdbmtime(TCTDB *tdb);


/* Get the additional flags of a table database object.
   `tdb' specifies the table database object.
   The return value is the additional flags. */
uint8_t tctdbflags(TCTDB *tdb);


/* Get the options of a table database object.
   `tdb' specifies the table database object.
   The return value is the options. */
uint8_t tctdbopts(TCTDB *tdb);


/* Get the pointer to the opaque field of a table database object.
   `tdb' specifies the table database object.
   The return value is the pointer to the opaque field whose size is 128 bytes. */
char *tctdbopaque(TCTDB *tdb);


/* Get the number of used elements of the bucket array of a table database object.
   `tdb' specifies the table database object.
   The return value is the number of used elements of the bucket array or 0 if the object does not
   connect to any database file. */
uint64_t tctdbbnumused(TCTDB *tdb);


/* Get the number of column indices of a table database object.
   `tdb' specifies the table database object.
   The return value is the number of column indices or 0 if the object does not connect to any
   database file. */
int tctdbinum(TCTDB *tdb);


/* Get the seed of unique ID unumbers of a table database object.
   `tdb' specifies the table database object.
   The return value is the seed of unique ID numbers or -1 on failure. */
int64_t tctdbuidseed(TCTDB *tdb);


/* Set the seed of unique ID unumbers of a table database object.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false. */
bool tctdbsetuidseed(TCTDB *tdb, int64_t seed);


/* Set the custom codec functions of a table database object.
   `tdb' specifies the table database object.
   `enc' specifies the pointer to the custom encoding function.  It receives four parameters.
   The first parameter is the pointer to the region.  The second parameter is the size of the
   region.  The third parameter is the pointer to the variable into which the size of the region
   of the return value is assigned.  The fourth parameter is the pointer to the optional opaque
   object.  It returns the pointer to the result object allocated with `malloc' call if
   successful, else, it returns `NULL'.
   `encop' specifies an arbitrary pointer to be given as a parameter of the encoding function.
   If it is not needed, `NULL' can be specified.
   `dec' specifies the pointer to the custom decoding function.
   `decop' specifies an arbitrary pointer to be given as a parameter of the decoding function.
   If it is not needed, `NULL' can be specified.
   If successful, the return value is true, else, it is false.
   Note that the custom codec functions should be set before the database is opened and should be
   set every time the database is being opened. */
bool tctdbsetcodecfunc(TCTDB *tdb, TCCODEC enc, void *encop, TCCODEC dec, void *decop);


/* Process each record atomically of a table database object.
   `tdb' specifies the table database object.
   `iter' specifies the pointer to the iterator function called for each record.  It receives
   five parameters.  The first parameter is the pointer to the region of the key.  The second
   parameter is the size of the region of the key.  The third parameter is the pointer to the
   region of the value.  The fourth parameter is the size of the region of the value.  The fifth
   parameter is the pointer to the optional opaque object.  It returns true to continue iteration
   or false to stop iteration.
   `op' specifies an arbitrary pointer to be given as a parameter of the iterator function.  If
   it is not needed, `NULL' can be specified.
   If successful, the return value is true, else, it is false. */
bool tctdbforeach(TCTDB *tdb, TCITER iter, void *op);


/* Convert a string into the index type number.
   `str' specifies a string.
   The return value is the index type number or -1 on failure. */
int tctdbstrtoindextype(const char *str);


/* Get the count of corresponding records of a query object.
   `qry' specifies the query object.
   The return value is the count of corresponding records. */
int tctdbqrycount(TDBQRY *qry);


/* Convert a string into the query operation number.
   `str' specifies a string.
   The return value is the query operation number or -1 on failure. */
int tctdbqrystrtocondop(const char *str);


/* Convert a string into the query order type number.
   `str' specifies a string.
   The return value is the query order type or -1 on failure. */
int tctdbqrystrtoordertype(const char *str);



__TCTDB_CLINKAGEEND
#endif                                   /* duplication check */


/* END OF FILE */