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, KCENOREPOS,   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...
enum	{ KCMSET, KCMADD, KCMREPLACE, KCMAPPEND }
	Merge modes. More...
Functions
void *	kcmalloc (size_t size)
	Allocate a region on memory.
void	kcfree (void *ptr)
	Release a region allocated in the library.
double	kctime (void)
	Get the time of day in seconds.
int64_t	kcatoi (const char *str)
	Convert a string to an integer.
int64_t	kcatoix (const char *str)
	Convert a string with a metric prefix to an integer.
double	kcatof (const char *str)
	Convert a string to a real number.
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.
double	kcnan ()
	Get the quiet Not-a-Number value.
double	kcinf ()
	Get the positive infinity value.
int32_t	kcchknan (double num)
	Check a number is a Not-a-Number value.
int32_t	kcchkinf (double num)
	Check a number is an infinity value.
const char *	kcecodename (int32_t code)
	Get the readable string of an error code.
KCDB *	kcdbnew (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	kcdbreplace (KCDB *db, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
	Replace the value of 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	kcdbcopy (KCDB *db, const char *dest)
	Create a copy of the database file.
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.
int64_t	kcdbmatchprefix (KCDB *db, const char *prefix, char **strary, int64_t max)
	Get keys matching a prefix string.
int64_t	kcdbmatchregex (KCDB *db, const char *regex, char **strary, int64_t max)
	Get keys matching a regular expression string.
int32_t	kcdbmerge (KCDB *db, KCDB **srcary, size_t srcnum, uint32_t mode)
	Merge records from other databases.
KCCUR *	kcdbcursor (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.
int32_t	kccursetvalue (KCCUR *cur, const char *vbuf, size_t vsiz, int32_t step)
	Set the value of the current record.
int32_t	kccurremove (KCCUR *cur)
	Remove 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	kccurjump (KCCUR *cur)
	Jump the cursor to the first record for forward scan.
int32_t	kccurjumpkey (KCCUR *cur, const char *kbuf, size_t ksiz)
	Jump the cursor to a record for forward scan.
int32_t	kccurjumpback (KCCUR *cur)
	Jump the cursor to the last record for backward scan.
int32_t	kccurjumpbackkey (KCCUR *cur, const char *kbuf, size_t ksiz)
	Jump the cursor to a record for backward scan.
int32_t	kccurstep (KCCUR *cur)
	Step the cursor to the next record.
int32_t	kccurstepback (KCCUR *cur)
	Step the cursor to the previous record.
KCDB *	kccurdb (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
KCENOREPOS	no repository
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

anonymous enum

Merge modes.

Enumerator:

KCMSET	overwrite the existing value
KCMADD	keep the existing value
KCMREPLACE	modify the existing record only
KCMAPPEND	append the new value

---

Function Documentation

void* 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

(

void *

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.

int64_t kcatoi

(

const char *

str

)

Convert a string to an integer.

Parameters:

str

specifies the string.

Returns:

the integer. If the string does not contain numeric expression, 0 is returned.

int64_t kcatoix

(

const char *

str

)

Convert a string with a metric prefix to an integer.

Parameters:

str

the string, which can be trailed by a binary metric prefix. "K", "M", "G", "T", "P", and "E" are supported. They are case-insensitive.

Returns:

the integer. If the string does not contain numeric expression, 0 is returned. If the integer overflows the domain, INT64_MAX or INT64_MIN is returned according to the sign.

double kcatof

(

const char *

str

)

Convert a string to a real number.

Parameters:

str

specifies the string.

Returns:

the real number. If the string does not contain numeric expression, 0.0 is returned.

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.

double kcnan

(

)

Get the quiet Not-a-Number value.

Returns:

the quiet Not-a-Number value.

double kcinf

(

)

Get the positive infinity value.

Returns:

the positive infinity value.

int32_t kcchknan

(

double

num

)

Check a number is a Not-a-Number value.

Returns:

true for the number is a Not-a-Number value, or false if not.

int32_t kcchkinf

(

double

num

)

Check a number is an infinity value.

Returns:

true for the number is an infinity value, or false if not.

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 hash database. If it is "%", the database will be a cache tree 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. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory 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", "kct", "kcd", and "kcf". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The cache hash database supports "opts", "bnum", "zcomp", "capcount", "capsize", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory 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 "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcount" is for "cap_count". "capsize" is for "cap_size". "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". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the kcdbclose method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

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 kcdbreplace	(	KCDB *	db,
		const char *	kbuf,
		size_t	ksiz,
		const char *	vbuf,
		size_t	vsiz
	)

Replace 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, no new record is created and false is returned. If the corresponding record exists, the value is modified.

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 kcdbcopy	(	KCDB *	db,
		const char *	dest
	)

Create a copy of the database file.

Parameters:

	db	a database object.
	dest	the path of the destination file.

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.

int64_t kcdbmatchprefix	(	KCDB *	db,
		const char *	prefix,
		char **	strary,
		int64_t	max
	)

Get keys matching a prefix string.

Parameters:

	db	a database object.
	prefix	the prefix string.
	strary	an array to contain the result. Its size must be sufficient.
	max	the maximum number to retrieve.

Returns:

the number of retrieved keys or -1 on failure.

Note:

The region of each element of the result should be released with the kcfree function when it is no longer in use.

int64_t kcdbmatchregex	(	KCDB *	db,
		const char *	regex,
		char **	strary,
		int64_t	max
	)

Get keys matching a regular expression string.

Parameters:

	db	a database object.
	regex	the regular expression string.
	strary	an array to contain the result. Its size must be sufficient.
	max	the maximum number to retrieve.

Returns:

the number of retrieved keys or -1 on failure.

Note:

The region of each element of the result should be released with the kcfree function when it is no longer in use.

int32_t kcdbmerge	(	KCDB *	db,
		KCDB **	srcary,
		size_t	srcnum,
		uint32_t	mode
	)

Merge records from other databases.

Parameters:

	db	a database object.
	srcary	an array of the source detabase objects.
	srcnum	the number of the elements of the source array.
	mode	the merge mode. KCMSET to overwrite the existing value, KCMADD to keep the existing value, KCMREPLACE to modify the existing record only, KCMAPPEND to append the new value.

Returns:

true on success, or false on failure.

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.

int32_t kccursetvalue	(	KCCUR *	cur,
		const char *	vbuf,
		size_t	vsiz,
		int32_t	step
	)

Set the value of the current record.

Parameters:

	cur	a cursor object.
	vbuf	the pointer to the value region.
	vsiz	the size of the value region.
	step	true to move the cursor to the next record, or false for no move.

Returns:

true on success, or false on failure.

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.

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 kccurjump

(

KCCUR *

cur

)

Jump the cursor to the first record for forward scan.

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 for forward scan.

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 kccurjumpback

(

KCCUR *

cur

)

Jump the cursor to the last record for backward scan.

Parameters:

cur

a cursor object.

Returns:

true on success, or false on failure.

Note:

This method is dedicated to tree databases. Some database types, especially hash databases, may provide a dummy implementation.

int32_t kccurjumpbackkey	(	KCCUR *	cur,
		const char *	kbuf,
		size_t	ksiz
	)

Jump the cursor to a record for backward scan.

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.

Note:

This method is dedicated to tree databases. Some database types, especially hash databases, will provide a dummy implementation.

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.

int32_t kccurstepback

(

KCCUR *

cur

)

Step the cursor to the previous record.

Parameters:

cur

a cursor object.

Returns:

true on success, or false on failure.

Note:

This method is dedicated to tree databases. Some database types, especially hash databases, may provide a dummy implementation.

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.