tcfdb.h

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

   transaction, the transaction is aborted implicitly. */
bool tcfdbtranbegin(TCFDB *fdb);


/* Commit the transaction of a fixed-length database object.
   `fdb' specifies the fixed-length 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. */
bool tcfdbtrancommit(TCFDB *fdb);


/* Abort the transaction of a fixed-length database object.
   `fdb' specifies the fixed-length 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. */
bool tcfdbtranabort(TCFDB *fdb);


/* Get the file path of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the path of the database file or `NULL' if the object does not connect to
   any database file. */
const char *tcfdbpath(TCFDB *fdb);


/* Get the number of records of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the number of records or 0 if the object does not connect to any database
   file. */
uint64_t tcfdbrnum(TCFDB *fdb);


/* Get the size of the database file of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the size of the database file or 0 if the object does not connect to any
   database file. */
uint64_t tcfdbfsiz(TCFDB *fdb);



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


/* Set the error code of a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbsetecode(TCFDB *fdb, int ecode, const char *filename, int line, const char *func);


/* Set the file descriptor for debugging output.
   `fdb' specifies the fixed-length database object.
   `fd' specifies the file descriptor for debugging output. */
void tcfdbsetdbgfd(TCFDB *fdb, int fd);


/* Get the file descriptor for debugging output.
   `fdb' specifies the fixed-length database object.
   The return value is the file descriptor for debugging output. */
int tcfdbdbgfd(TCFDB *fdb);


/* Check whether mutual exclusion control is set to a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   If mutual exclusion control is set, it is true, else it is false. */
bool tcfdbhasmutex(TCFDB *fdb);


/* Synchronize updating contents on memory of a fixed-length database object.
   `fdb' specifies the fixed-length database object connected as a writer.
   `phys' specifies whether to synchronize physically.
   If successful, the return value is true, else, it is false. */
bool tcfdbmemsync(TCFDB *fdb, bool phys);


/* Get the minimum ID number of records of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the minimum ID number of records or 0 if the object does not connect to
   any database file. */
uint64_t tcfdbmin(TCFDB *fdb);


/* Get the maximum ID number of records of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the maximum ID number of records or 0 if the object does not connect to
   any database file. */
uint64_t tcfdbmax(TCFDB *fdb);


/* Get the width of the value of each record of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the width of the value of each record or 0 if the object does not connect
   to any database file. */
uint32_t tcfdbwidth(TCFDB *fdb);


/* Get the limit file size of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the limit file size or 0 if the object does not connect to any database
   file. */
uint64_t tcfdblimsiz(TCFDB *fdb);


/* Get the limit ID number of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the limit ID number or 0 if the object does not connect to any database
   file. */
uint64_t tcfdblimid(TCFDB *fdb);


/* Get the inode number of the database file of a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbinode(TCFDB *fdb);


/* Get the modification time of the database file of a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbmtime(TCFDB *fdb);


/* Get the connection mode of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the connection mode. */
int tcfdbomode(TCFDB *fdb);


/* Get the database type of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the database type. */
uint8_t tcfdbtype(TCFDB *fdb);


/* Get the additional flags of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the additional flags. */
uint8_t tcfdbflags(TCFDB *fdb);


/* Get the pointer to the opaque field of a fixed-length database object.
   `fdb' specifies the fixed-length database object.
   The return value is the pointer to the opaque field whose size is 128 bytes. */
char *tcfdbopaque(TCFDB *fdb);


/* Store a record into a fixed-length database object with a duplication handler.
   `fdb' specifies the fixed-length database object connected as a writer.
   `id' specifies the ID number.  It should be more than 0.  If it is `FDBIDMIN', the minimum ID
   number of existing records is specified.  If it is `FDBIDPREV', the number less by one than
   the minimum ID number of existing records is specified.  If it is `FDBIDMAX', the maximum ID
   number of existing records is specified.  If it is `FDBIDNEXT', the number greater by one than
   the maximum ID number of existing records is specified.
   `vbuf' specifies the pointer to the region of the value.  `NULL' means that record addition is
   ommited if there is no corresponding record.
   `vsiz' specifies the size of the region of the value.  If the size of the value is greater
   than the width tuning parameter of the database, the size is cut down to the width.
   `proc' specifies the pointer to the callback function to process duplication.  It receives
   four parameters.  The first parameter is the pointer to the region of the value.  The second
   parameter is the size of the region of the value.  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'.  It is released by the caller.  If it is `NULL', the record is
   not modified.  If it is `(void *)-1', the record is removed.
   `op' specifies an arbitrary pointer to be given as a parameter of the callback function.  If
   it is not needed, `NULL' can be specified.
   If successful, the return value is true, else, it is false. */
bool tcfdbputproc(TCFDB *fdb, int64_t id, const void *vbuf, int vsiz, TCPDPROC proc, void *op);


/* Process each record atomically of a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbforeach(TCFDB *fdb, TCITER iter, void *op);


/* Generate the ID number from arbitrary binary data.
   `kbuf' specifies the pointer to the region of the key.
   `ksiz' specifies the size of the region of the key.
   The return value is the ID number. */
int64_t tcfdbkeytoid(const char *kbuf, int ksiz);



__TCFDB_CLINKAGEEND
#endif                                   /* duplication check */


/* END OF FILE */