kclangc.h File Reference

C language binding. More...

#include <assert.h>
#include <ctype.h>
#include <errno.h>
#include <float.h>
#include <limits.h>
#include <locale.h>
#include <math.h>
#include <setjmp.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <string.h>
#include <time.h>
#include <stdint.h>

Classes

union  KCDB
 C wrapper of polymorphic database. More...
union  KCCUR
 C wrapper of polymorphic cursor. More...

Typedefs

typedef const char *(* KCVISITFULL )(const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, size_t *sp, void *opq)
 Call back function to visit a full record.
typedef const char *(* KCVISITEMPTY )(const char *kbuf, size_t ksiz, size_t *sp, void *opq)
 Call back function to visit an empty record.
typedef int32_t(* KCFILEPROC )(const char *path, int64_t count, int64_t size, void *opq)
 Call back function to process the database file.

Enumerations

enum  {
  KCESUCCESS, KCENOIMPL, KCEINVALID, KCENOFILE,
  KCENOPERM, KCEBROKEN, KCEDUPREC, KCENOREC,
  KCELOGIC, KCESYSTEM, KCEMISC = 15
}
 

Error codes.

More...
enum  {
  KCOREADER = 1 << 0, KCOWRITER = 1 << 1, KCOCREATE = 1 << 2, KCOTRUNCATE = 1 << 3,
  KCOAUTOTRAN = 1 << 4, KCOAUTOSYNC = 1 << 5, KCONOLOCK = 1 << 6, KCOTRYLOCK = 1 << 7,
  KCONOREPAIR = 1 << 8
}
 

Open modes.

More...

Functions

char * kcmalloc (size_t size)
 Allocate a region on memory.
void kcfree (char *ptr)
 Release a region allocated in the library.
double kctime (void)
 Get the time of day in seconds.
uint64_t kchashmurmur (const void *buf, size_t size)
 Get the hash value by MurMur hashing.
uint64_t kchashfnv (const void *buf, size_t size)
 Get the hash value by FNV hashing.
const char * kcecodename (int32_t code)
 Get the readable string of an error code.
KCDBkcdbnew (void)
 Create a database object.
void kcdbdel (KCDB *db)
 Destroy a database object.
int32_t kcdbopen (KCDB *db, const char *path, uint32_t mode)
 Open a database file.
int32_t kcdbclose (KCDB *db)
 Close the database file.
int32_t kcdbecode (KCDB *db)
 Get the code of the last happened error.
const char * kcdbemsg (KCDB *db)
 Get the supplement message of the last happened error.
int32_t kcdbaccept (KCDB *db, const char *kbuf, size_t ksiz, KCVISITFULL fullproc, KCVISITEMPTY emptyproc, void *opq, int32_t writable)
 Accept a visitor to a record.
int32_t kcdbiterate (KCDB *db, KCVISITFULL fullproc, void *opq, int32_t writable)
 Iterate to accept a visitor for each record.
int32_t kcdbset (KCDB *db, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Set the value of a record.
int32_t kcdbadd (KCDB *db, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Add a record.
int32_t kcdbappend (KCDB *db, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
 Append the value of a record.
int64_t kcdbincrint (KCDB *db, const char *kbuf, size_t ksiz, int64_t num)
 Add a number to the numeric value of a record.
double kcdbincrdouble (KCDB *db, const char *kbuf, size_t ksiz, double num)
 Add a number to the numeric value of a record.
int32_t kcdbcas (KCDB *db, const char *kbuf, size_t ksiz, const char *nvbuf, size_t nvsiz, const char *ovbuf, size_t ovsiz)
 Perform compare-and-swap.
int32_t kcdbremove (KCDB *db, const char *kbuf, size_t ksiz)
 Remove a record.
char * kcdbget (KCDB *db, const char *kbuf, size_t ksiz, size_t *sp)
 Retrieve the value of a record.
int32_t kcdbgetbuf (KCDB *db, const char *kbuf, size_t ksiz, char *vbuf, size_t max)
 Retrieve the value of a record.
int32_t kcdbclear (KCDB *db)
 Remove all records.
int32_t kcdbsync (KCDB *db, int32_t hard, KCFILEPROC proc, void *opq)
 Synchronize updated contents with the file and the device.
int32_t kcdbbegintran (KCDB *db, int32_t hard)
 Begin transaction.
int32_t kcdbbegintrantry (KCDB *db, int32_t hard)
 Try to begin transaction.
int32_t kcdbendtran (KCDB *db, int32_t commit)
 End transaction.
int32_t kcdbdumpsnap (KCDB *db, const char *dest)
 Dump records into a file.
int32_t kcdbloadsnap (KCDB *db, const char *src)
 Load records from a file.
int64_t kcdbcount (KCDB *db)
 Get the number of records.
int64_t kcdbsize (KCDB *db)
 Get the size of the database file.
char * kcdbpath (KCDB *db)
 Get the path of the database file.
char * kcdbstatus (KCDB *db)
 Get the miscellaneous status information.
KCCURkcdbcursor (KCDB *db)
 Create a cursor object.
void kccurdel (KCCUR *cur)
 Destroy a cursor object.
int32_t kccuraccept (KCCUR *cur, KCVISITFULL fullproc, void *opq, int32_t writable, int32_t step)
 Accept a visitor to the current record.
char * kccurgetkey (KCCUR *cur, size_t *sp, int32_t step)
 Get the key of the current record.
char * kccurgetvalue (KCCUR *cur, size_t *sp, int32_t step)
 Get the value of the current record.
char * kccurget (KCCUR *cur, size_t *ksp, const char **vbp, size_t *vsp, int32_t step)
 Get a pair of the key and the value of the current record.
int32_t kccurremove (KCCUR *cur)
 Remove the current record.
int32_t kccurjump (KCCUR *cur)
 Jump the cursor to the first record.
int32_t kccurjumpkey (KCCUR *cur, const char *kbuf, size_t ksiz)
 Jump the cursor to a record.
int32_t kccurstep (KCCUR *cur)
 Step the cursor to the next record.
KCDBkccurdb (KCCUR *cur)
 Get the database object.
int32_t kccurecode (KCCUR *cur)
 Get the code of the last happened error.
const char * kccuremsg (KCCUR *cur)
 Get the supplement message of the last happened error.

Variables

const char *const KCVERSION
 The package version.
const char *const KCVISNOP
 Special pointer for no operation by the visiting function.
const char *const KCVISREMOVE
 Special pointer to remove the record by the visiting function.

Detailed Description

C language binding.


Typedef Documentation

typedef const char*(* KCVISITFULL)(const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz, size_t *sp, void *opq)

Call back function to visit a full record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
sp the pointer to the variable into which the size of the region of the return value is assigned.
opq an opaque pointer.
Returns:
If it is the pointer to a region, the value is replaced by the content. If it is KCVISNOP, nothing is modified. If it is KCVISREMOVE, the record is removed.
typedef const char*(* KCVISITEMPTY)(const char *kbuf, size_t ksiz, size_t *sp, void *opq)

Call back function to visit an empty record.

Parameters:
kbuf the pointer to the key region.
ksiz the size of the key region.
sp the pointer to the variable into which the size of the region of the return value is assigned.
opq an opaque pointer.
Returns:
If it is the pointer to a region, the value is replaced by the content. If it is KCVISNOP or KCVISREMOVE, nothing is modified.
typedef int32_t(* KCFILEPROC)(const char *path, int64_t count, int64_t size, void *opq)

Call back function to process the database file.

Parameters:
path the path of the database file.
count the number of records.
size the size of the available region.
opq an opaque pointer.
Returns:
true on success, or false on failure.

Enumeration Type Documentation

anonymous enum

Error codes.

Enumerator:
KCESUCCESS 

success

KCENOIMPL 

not implemented

KCEINVALID 

invalid operation

KCENOFILE 

file not found

KCENOPERM 

no permission

KCEBROKEN 

broken file

KCEDUPREC 

record duplication

KCENOREC 

no record

KCELOGIC 

logical inconsistency

KCESYSTEM 

system error

KCEMISC 

miscellaneous error

anonymous enum

Open modes.

Enumerator:
KCOREADER 

open as a reader

KCOWRITER 

open as a writer

KCOCREATE 

writer creating

KCOTRUNCATE 

writer truncating

KCOAUTOTRAN 

auto transaction

KCOAUTOSYNC 

auto synchronization

KCONOLOCK 

open without locking

KCOTRYLOCK 

lock without blocking

KCONOREPAIR 

open without auto repair


Function Documentation

char* kcmalloc ( size_t  size  ) 

Allocate a region on memory.

Parameters:
size the size of the region.
Returns:
the pointer to the allocated region. The region of the return value should be released with the kcfree function when it is no longer in use.
void kcfree ( char *  ptr  ) 

Release a region allocated in the library.

Parameters:
ptr the pointer to the region.
double kctime ( void   ) 

Get the time of day in seconds.

Returns:
the time of day in seconds. The accuracy is in microseconds.
uint64_t kchashmurmur ( const void *  buf,
size_t  size 
)

Get the hash value by MurMur hashing.

Parameters:
buf the source buffer.
size the size of the source buffer.
Returns:
the hash value.
uint64_t kchashfnv ( const void *  buf,
size_t  size 
)

Get the hash value by FNV hashing.

Parameters:
buf the source buffer.
size the size of the source buffer.
Returns:
the hash value.
const char* kcecodename ( int32_t  code  ) 

Get the readable string of an error code.

Parameters:
code the error code.
Returns:
the readable string of the error code.
KCDB* kcdbnew ( void   ) 

Create a database object.

Returns:
the created database object.
Note:
The object of the return value should be released with the kcdbdel function when it is no longer in use.
void kcdbdel ( KCDB db  ) 

Destroy a database object.

Parameters:
db the database object.
int32_t kcdbopen ( KCDB db,
const char *  path,
uint32_t  mode 
)

Open a database file.

Parameters:
db a database object.
path the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is "*", the database will be a cache database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", "*", "kch", and "kct". The prototype hash hash database and the prototype tree database do not support any other tuning parameter. The cache database supports "bnum", "capcount", and "capsize". The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "erstrm", and "ervbs". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition.
mode the connection mode. KCOWRITER as a writer, KCOREADER as a reader. The following may be added to the writer mode by bitwise-or: KCOCREATE, which means it creates a new database if the file does not exist, KCOTRUNCATE, which means it creates a new database regardless if the file exists, KCOAUTOTRAN, which means each updating operation is performed in implicit transaction, KCOAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: KCONOLOCK, which means it opens the database file without file locking, KCOTRYLOCK, which means locking is performed without blocking, KCONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.
Returns:
true on success, or false on failure.
Note:
The tuning parameter "bnum" corresponds to the original "tune_bucket" method. "capcount" is for "cap_count". "capsize" is for "cap_size". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the copmress option. "msiz" is for "tune_map". "dfunit" is for "tune_defrag". "erstrm" and "ervbs" are for "tune_error_reporter" and the formar value can be "stdout" or "stderr" and the latter value can be "true" or "false". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator or "dec" for the decimal comparator. "pccap" is for "tune_page_cache". Every opened database must be closed by the kcdbclose function when it is no longer in use.
int32_t kcdbclose ( KCDB db  ) 

Close the database file.

Parameters:
db a database object.
Returns:
true on success, or false on failure.
int32_t kcdbecode ( KCDB db  ) 

Get the code of the last happened error.

Parameters:
db a database object.
Returns:
the code of the last happened error.
const char* kcdbemsg ( KCDB db  ) 

Get the supplement message of the last happened error.

Parameters:
db a database object.
Returns:
the supplement message of the last happened error.
int32_t kcdbaccept ( KCDB db,
const char *  kbuf,
size_t  ksiz,
KCVISITFULL  fullproc,
KCVISITEMPTY  emptyproc,
void *  opq,
int32_t  writable 
)

Accept a visitor to a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
fullproc a call back function to visit a record.
emptyproc a call back function to visit an empty record space.
opq an opaque pointer to be given to the call back functions.
writable true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.
Note:
the operation for each record is performed atomically and other threads accessing the same record are blocked.
int32_t kcdbiterate ( KCDB db,
KCVISITFULL  fullproc,
void *  opq,
int32_t  writable 
)

Iterate to accept a visitor for each record.

Parameters:
db a database object.
fullproc a call back function to visit a record.
opq an opaque pointer to be given to the call back function.
writable true for writable operation, or false for read-only operation.
Returns:
true on success, or false on failure.
Note:
the whole iteration is performed atomically and other threads are blocked.
int32_t kcdbset ( KCDB db,
const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
)

Set the value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.
int32_t kcdbadd ( KCDB db,
const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
)

Add a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.
int32_t kcdbappend ( KCDB db,
const char *  kbuf,
size_t  ksiz,
const char *  vbuf,
size_t  vsiz 
)

Append the value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the value region.
vsiz the size of the value region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.
int64_t kcdbincrint ( KCDB db,
const char *  kbuf,
size_t  ksiz,
int64_t  num 
)

Add a number to the numeric value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
num the additional number.
Returns:
the result value, or INT64_MIN on failure.
double kcdbincrdouble ( KCDB db,
const char *  kbuf,
size_t  ksiz,
double  num 
)

Add a number to the numeric value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
num the additional number.
Returns:
the result value, or Not-a-number on failure.
int32_t kcdbcas ( KCDB db,
const char *  kbuf,
size_t  ksiz,
const char *  nvbuf,
size_t  nvsiz,
const char *  ovbuf,
size_t  ovsiz 
)

Perform compare-and-swap.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
ovbuf the pointer to the old value region. NULL means that no record corresponds.
ovsiz the size of the old value region.
nvbuf the pointer to the new value region. NULL means that the record is removed.
nvsiz the size of new old value region.
Returns:
true on success, or false on failure.
int32_t kcdbremove ( KCDB db,
const char *  kbuf,
size_t  ksiz 
)

Remove a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, false is returned.
char* kcdbget ( KCDB db,
const char *  kbuf,
size_t  ksiz,
size_t *  sp 
)

Retrieve the value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
sp the pointer to the variable into which the size of the region of the return value is assigned.
Returns:
the pointer to the value region of the corresponding record, or NULL on failure.
Note:
If no record corresponds to the key, NULL is returned. 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 C-style string. The region of the return value should be released with the kcfree function when it is no longer in use.
int32_t kcdbgetbuf ( KCDB db,
const char *  kbuf,
size_t  ksiz,
char *  vbuf,
size_t  max 
)

Retrieve the value of a record.

Parameters:
db a database object.
kbuf the pointer to the key region.
ksiz the size of the key region.
vbuf the pointer to the buffer into which the value of the corresponding record is written.
max the size of the buffer.
Returns:
the size of the value, or -1 on failure.
int32_t kcdbclear ( KCDB db  ) 

Remove all records.

Parameters:
db a database object.
Returns:
true on success, or false on failure.
int32_t kcdbsync ( KCDB db,
int32_t  hard,
KCFILEPROC  proc,
void *  opq 
)

Synchronize updated contents with the file and the device.

Parameters:
db a database object.
hard true for physical synchronization with the device, or false for logical synchronization with the file system.
proc a postprocessor call back function. If it is NULL, no postprocessing is performed.
opq an opaque pointer to be given to the call back function.
Returns:
true on success, or false on failure.
int32_t kcdbbegintran ( KCDB db,
int32_t  hard 
)

Begin transaction.

Parameters:
db a database object.
hard true for physical synchronization with the device, or false for logical synchronization with the file system.
Returns:
true on success, or false on failure.
int32_t kcdbbegintrantry ( KCDB db,
int32_t  hard 
)

Try to begin transaction.

Parameters:
db a database object.
hard true for physical synchronization with the device, or false for logical synchronization with the file system.
Returns:
true on success, or false on failure.
int32_t kcdbendtran ( KCDB db,
int32_t  commit 
)

End transaction.

Parameters:
db a database object.
commit true to commit the transaction, or false to abort the transaction.
Returns:
true on success, or false on failure.
int32_t kcdbdumpsnap ( KCDB db,
const char *  dest 
)

Dump records into a file.

Parameters:
db a database object.
dest the path of the destination file.
Returns:
true on success, or false on failure.
int32_t kcdbloadsnap ( KCDB db,
const char *  src 
)

Load records from a file.

Parameters:
db a database object.
src the path of the source file.
Returns:
true on success, or false on failure.
int64_t kcdbcount ( KCDB db  ) 

Get the number of records.

Parameters:
db a database object.
Returns:
the number of records, or -1 on failure.
int64_t kcdbsize ( KCDB db  ) 

Get the size of the database file.

Parameters:
db a database object.
Returns:
the size of the database file in bytes, or -1 on failure.
char* kcdbpath ( KCDB db  ) 

Get the path of the database file.

Parameters:
db a database object.
Returns:
the path of the database file, or an empty string on failure.
Note:
The region of the return value should be released with the kcfree function when it is no longer in use.
char* kcdbstatus ( KCDB db  ) 

Get the miscellaneous status information.

Parameters:
db a database object.
Returns:
the result string of tab saparated values, or NULL on failure. Each line consists of the attribute name and its value separated by a tab character.
Note:
The region of the return value should be released with the kcfree function when it is no longer in use.
KCCUR* kcdbcursor ( KCDB db  ) 

Create a cursor object.

Parameters:
db a database object.
Returns:
the return value is the created cursor object.
Note:
The object of the return value should be released with the kccurdel function when it is no longer in use.
void kccurdel ( KCCUR cur  ) 

Destroy a cursor object.

Parameters:
cur the cursor object.
int32_t kccuraccept ( KCCUR cur,
KCVISITFULL  fullproc,
void *  opq,
int32_t  writable,
int32_t  step 
)

Accept a visitor to the current record.

Parameters:
cur a cursor object.
fullproc a call back function to visit a record.
opq an opaque pointer to be given to the call back functions.
writable true for writable operation, or false for read-only operation.
step true to move the cursor to the next record, or false for no move.
Returns:
true on success, or false on failure.
char* kccurgetkey ( KCCUR cur,
size_t *  sp,
int32_t  step 
)

Get the key of the current record.

Parameters:
cur a cursor object.
sp the pointer to the variable into which the size of the region of the return value is assigned.
step true to move the cursor to the next record, or false for no move.
Returns:
the pointer to the key region of the current record, or NULL on failure.
Note:
If the cursor is invalidated, NULL is returned. 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 C-style string. The region of the return value should be released with the kcfree function when it is no longer in use.
char* kccurgetvalue ( KCCUR cur,
size_t *  sp,
int32_t  step 
)

Get the value of the current record.

Parameters:
cur a cursor object.
sp the pointer to the variable into which the size of the region of the return value is assigned.
step true to move the cursor to the next record, or false for no move.
Returns:
the pointer to the value region of the current record, or NULL on failure.
Note:
If the cursor is invalidated, NULL is returned. 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 C-style string. The region of the return value should be released with the kcfree function when it is no longer in use.
char* kccurget ( KCCUR cur,
size_t *  ksp,
const char **  vbp,
size_t *  vsp,
int32_t  step 
)

Get a pair of the key and the value of the current record.

Parameters:
cur a cursor object.
ksp the pointer to the variable into which the size of the region of the return value is assigned.
vbp the pointer to the variable into which the pointer to the value region is assigned.
vsp the pointer to the variable into which the size of the value region is assigned.
step true to move the cursor to the next record, or false for no move.
Returns:
the pointer to the pair of the key region, or NULL on failure.
Note:
If the cursor is invalidated, NULL is returned. Because an additional zero code is appended at the end of each region of the key and the value, each region can be treated as a C-style string. The region of the return value should be released with the kcfree function when it is no longer in use.
int32_t kccurremove ( KCCUR cur  ) 

Remove the current record.

Parameters:
cur a cursor object.
Returns:
true on success, or false on failure.
Note:
If no record corresponds to the key, false is returned. The cursor is moved to the next record implicitly.
int32_t kccurjump ( KCCUR cur  ) 

Jump the cursor to the first record.

Parameters:
cur a cursor object.
Returns:
true on success, or false on failure.
int32_t kccurjumpkey ( KCCUR cur,
const char *  kbuf,
size_t  ksiz 
)

Jump the cursor to a record.

Parameters:
cur a cursor object.
kbuf the pointer to the key region.
ksiz the size of the key region.
Returns:
true on success, or false on failure.
int32_t kccurstep ( KCCUR cur  ) 

Step the cursor to the next record.

Parameters:
cur a cursor object.
Returns:
true on success, or false on failure.
KCDB* kccurdb ( KCCUR cur  ) 

Get the database object.

Parameters:
cur a cursor object.
Returns:
the database object.
int32_t kccurecode ( KCCUR cur  ) 

Get the code of the last happened error.

Parameters:
cur a cursor object.
Returns:
the code of the last happened error.
const char* kccuremsg ( KCCUR cur  ) 

Get the supplement message of the last happened error.

Parameters:
cur a cursor object.
Returns:
the supplement message of the last happened error.

Variable Documentation

const char* const KCVERSION

The package version.

const char* const KCVISNOP

Special pointer for no operation by the visiting function.

const char* const KCVISREMOVE

Special pointer to remove the record by the visiting function.

Generated on Tue May 4 10:08:02 2010 for Kyoto Cabinet by  doxygen 1.6.3