Kyoto Cabinet: kclangc.h File Reference

Kyoto Cabinet

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

Classes | Defines | Typedefs | Enumerations | Functions | Variables
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
struct | KCDB
| C wrapper of polymorphic database. More...
struct | KCCUR
| C wrapper of polymorphic cursor. More...
struct | KCSTR
| Binary string of byte array. More...
struct | KCREC
| Key-Value record. More...
struct | KCIDX
| C wrapper of index database. More...
struct | KCMAP
| C wrapper of memory-saving string hash map. More...
struct | KCMAPITER
| C wrapper of iterator of memory-saving string hash map. More...
struct | KCMAPSORT
| C wrapper of sorter of memory-saving string hash map. More...
struct | KCLIST
| C wrapper of memory-saving string hash map. More...
## Defines
#define | __STDC_LIMIT_MACROS 1
| enable limit macros for C++
## 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.
size_t | kclevdist (const void *abuf, size_t asiz, const void *bbuf, size_t bsiz, int32_t utf)
| Calculate the levenshtein distance of two regions.
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 polymorphic 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 | kcdbacceptbulk (KCDB *db, const KCSTR *keys, size_t knum, KCVISITFULL fullproc, KCVISITEMPTY emptyproc, void *opq, int32_t writable)
| Accept a visitor to multiple records at once.
int32_t | kcdbiterate (KCDB *db, KCVISITFULL fullproc, void *opq, int32_t writable)
| Iterate to accept a visitor for each record.
int32_t | kcdbscanpara (KCDB *db, KCVISITFULL fullproc, void *opq, size_t thnum)
| Scan each record in parallel.
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, int64_t orig)
| Add a number to the numeric value of a record.
double | kcdbincrdouble (KCDB *db, const char *kbuf, size_t ksiz, double num, double orig)
| Add a number to the numeric value of a record.
int32_t | kcdbcas (KCDB *db, const char *kbuf, size_t ksiz, const char *ovbuf, size_t ovsiz, const char *nvbuf, size_t nvsiz)
| 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 | kcdbcheck (KCDB *db, const char *kbuf, size_t ksiz)
| Check the existence 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.
char * | kcdbseize (KCDB *db, const char *kbuf, size_t ksiz, size_t *sp)
| Retrieve the value of a record and remove it atomically.
int64_t | kcdbsetbulk (KCDB *db, const KCREC *recs, size_t rnum, int32_t atomic)
| Store records at once.
int64_t | kcdbremovebulk (KCDB *db, const KCSTR *keys, size_t knum, int32_t atomic)
| Remove records at once.
int64_t | kcdbgetbulk (KCDB *db, const KCSTR *keys, size_t knum, KCREC *recs, int32_t atomic)
| Retrieve records at once.
int32_t | kcdbsync (KCDB *db, int32_t hard, KCFILEPROC proc, void *opq)
| Synchronize updated contents with the file and the device.
int32_t | kcdboccupy (KCDB *db, int32_t writable, KCFILEPROC proc, void *opq)
| Occupy database by locking and do something meanwhile.
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 | kcdbclear (KCDB *db)
| Remove all records.
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, size_t max)
| Get keys matching a prefix string.
int64_t | kcdbmatchregex (KCDB *db, const char *regex, char **strary, size_t max)
| Get keys matching a regular expression string.
int64_t | kcdbmatchsimilar (KCDB *db, const char *origin, uint32_t range, int32_t utf, char **strary, size_t max)
| Get keys similar to a string in terms of the levenshtein distance.
int32_t | kcdbmerge (KCDB *db, KCDB **srcary, size_t srcnum, uint32_t mode)
| Merge records from other databases.
KCCUR * | kcdbcursor (KCDB *db)
| Create a polymorphic 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.
char * | kccurseize (KCCUR *cur, size_t *ksp, const char **vbp, size_t *vsp)
| Get a pair of the key and the value of the current record and remove it atomically.
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.
KCIDX * | kcidxnew (void)
| Create an index database object.
void | kcidxdel (KCIDX *idx)
| Destroy a database object.
int32_t | kcidxopen (KCIDX *idx, const char *path, uint32_t mode)
| Open a database file.
int32_t | kcidxclose (KCIDX *idx)
| Close the database file.
int32_t | kcidxecode (KCIDX *idx)
| Get the code of the last happened error.
const char * | kcidxemsg (KCIDX *idx)
| Get the supplement message of the last happened error.
int32_t | kcidxset (KCIDX *idx, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Set the value of a record.
int32_t | kcidxadd (KCIDX *idx, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Add a record.
int32_t | kcidxreplace (KCIDX *idx, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Replace the value of a record.
int32_t | kcidxappend (KCIDX *idx, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Append the value of a record.
int32_t | kcidxremove (KCIDX *idx, const char *kbuf, size_t ksiz)
| Remove a record.
char * | kcidxget (KCIDX *idx, const char *kbuf, size_t ksiz, size_t *sp)
| Retrieve the value of a record.
int32_t | kcidxsync (KCIDX *idx, int32_t hard, KCFILEPROC proc, void *opq)
| Synchronize updated contents with the file and the device.
int32_t | kcidxclear (KCIDX *idx)
| Remove all records.
int64_t | kcidxcount (KCIDX *idx)
| Get the number of records.
int64_t | kcidxsize (KCIDX *idx)
| Get the size of the database file.
char * | kcidxpath (KCIDX *idx)
| Get the path of the database file.
char * | kcidxstatus (KCIDX *idx)
| Get the miscellaneous status information.
KCDB * | kcidxrevealinnerdb (KCIDX *idx)
| Reveal the inner database object.
KCMAP * | kcmapnew (size_t bnum)
| Create a string hash map object.
void | kcmapdel (KCMAP *map)
| Destroy a map object.
void | kcmapset (KCMAP *map, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Set the value of a record.
int32_t | kcmapadd (KCMAP *map, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Add a record.
int32_t | kcmapreplace (KCMAP *map, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Replace the value of a record.
void | kcmapappend (KCMAP *map, const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Append the value of a record.
int32_t | kcmapremove (KCMAP *map, const char *kbuf, size_t ksiz)
| Remove a record.
const char * | kcmapget (KCMAP *map, const char *kbuf, size_t ksiz, size_t *sp)
| Retrieve the value of a record.
void | kcmapclear (KCMAP *map)
| Remove all records.
size_t | kcmapcount (KCMAP *map)
| Get the number of records.
KCMAPITER * | kcmapiterator (KCMAP *map)
| Create a string hash map iterator object.
void | kcmapiterdel (KCMAPITER *iter)
| Destroy an iterator object.
const char * | kcmapitergetkey (KCMAPITER *iter, size_t *sp)
| Get the key of the current record.
const char * | kcmapitergetvalue (KCMAPITER *iter, size_t *sp)
| Get the value of the current record.
const char * | kcmapiterget (KCMAPITER *iter, size_t *ksp, const char **vbp, size_t *vsp)
| Get a pair of the key and the value of the current record.
void | kcmapiterstep (KCMAPITER *iter)
| Step the cursor to the next record.
KCMAPSORT * | kcmapsorter (KCMAP *map)
| Create a string hash map sorter object.
void | kcmapsortdel (KCMAPSORT *sort)
| Destroy an sorter object.
const char * | kcmapsortgetkey (KCMAPSORT *sort, size_t *sp)
| Get the key of the current record.
const char * | kcmapsortgetvalue (KCMAPSORT *sort, size_t *sp)
| Get the value of the current record.
const char * | kcmapsortget (KCMAPSORT *sort, size_t *ksp, const char **vbp, size_t *vsp)
| Get a pair of the key and the value of the current record.
void | kcmapsortstep (KCMAPSORT *sort)
| Step the cursor to the next record.
KCLIST * | kclistnew ()
| Create a string array list object.
void | kclistdel (KCLIST *list)
| Destroy a list object.
void | kclistpush (KCLIST *list, const char *buf, size_t size)
| Insert a record at the bottom of the list.
int32_t | kclistpop (KCLIST *list)
| Remove a record at the bottom of the list.
void | kclistunshift (KCLIST *list, const char *buf, size_t size)
| Insert a record at the top of the list.
int32_t | kclistshift (KCLIST *list)
| Remove a record at the top of the list.
void | kclistinsert (KCLIST *list, const char *buf, size_t size, size_t idx)
| Insert a record at the position of the given index of the list.
void | kclistremove (KCLIST *list, size_t idx)
| Remove a record at the position of the given index of the list.
const char * | kclistget (KCLIST *list, size_t idx, size_t *sp)
| Retrieve a record at the position of the given index of the list.
void | kclistclear (KCLIST *list)
| Remove all records.
size_t | kclistcount (KCLIST *list)
| Get the number of records.
## 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.

## Define Documentation

#define __STDC_LIMIT_MACROS 1

enable limit macros for C++

## 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.

size_t kclevdist | ( | const void * | abuf,
|  | size_t | asiz,
|  | const void * | bbuf,
|  | size_t | bsiz,
|  | int32_t | utf
| ) |  |

Calculate the levenshtein distance of two regions.

Parameters:

  abuf | the pointer to the region of one buffer.
  asiz | the size of the region of one buffer.
  bbuf | the pointer to the region of the other buffer.
  bsiz | the size of the region of the other buffer.
  utf | flag to treat keys as UTF-8 strings.

Returns:
  the levenshtein distance of two regions.

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 polymorphic 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 stash 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. If its suffix is ".kcx", the database will be a plain text 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", kcf", and "kcx". 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 stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", 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. The plain text database does not support any other tuning parameter.
  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. To avoid deadlock, any explicit database operation must not be performed in this function.

int32_t kcdbacceptbulk | ( | KCDB * | db,
|  | const KCSTR * | keys,
|  | size_t | knum,
|  | KCVISITFULL | fullproc,
|  | KCVISITEMPTY | emptyproc,
|  | void * | opq,
|  | int32_t | writable
| ) |  |

Accept a visitor to multiple records at once.

Parameters:

  db | a database object.
  keys | specifies an array of binary strings of the keys.
  knum | specifies the number of the keys.
  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 operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

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. To avoid deadlock, any explicit database operation must not be performed in this function.

int32_t kcdbscanpara | ( | KCDB * | db,
|  | KCVISITFULL | fullproc,
|  | void * | opq,
|  | size_t | thnum
| ) |  |

Scan each record in parallel.

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.
  thnum | the number of worker threads.

Returns:
  true on success, or false on failure.

Note:
  This function is for reading records and not for updating ones. The return value of the visitor is just ignored. To avoid deadlock, any explicit database operation must not be performed in this function.

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,
|  | int64_t | orig
| ) |  |

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.
  orig | the origin number if no record corresponds to the key. If it is INT64_MIN and no record corresponds, this function fails. If it is INT64_MAX, the value is set as the additional number regardless of the current value.

Returns:
  the result value, or INT64_MIN on failure.

Note:
  The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this function fails.

double kcdbincrdouble | ( | KCDB * | db,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | double | num,
|  | double | orig
| ) |  |

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.
  orig | the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this function fails. If it is positive infinity, the value is set as the additional number regardless of the current value.

Returns:
  the result value, or Not-a-number on failure.

Note:
  The value is serialized as an 16-byte binary fixed-point number in big-endian order, not a decimal string. If existing value is not 16-byte, this function fails.

int32_t kcdbcas | ( | KCDB * | db,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | ovbuf,
|  | size_t | ovsiz,
|  | const char * | nvbuf,
|  | size_t | nvsiz
| ) |  |

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

Check the existence of a record.

Parameters:

  db | a database object.
  kbuf | the pointer to the key region.
  ksiz | the size of the key region.

Returns:
  the size of the value, or -1 on failure.

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.

char* kcdbseize | ( | KCDB * | db,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp
| ) |  |

Retrieve the value of a record and remove it atomically.

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.

int64_t kcdbsetbulk | ( | KCDB * | db,
|  | const KCREC * | recs,
|  | size_t | rnum,
|  | int32_t | atomic
| ) |  |

Store records at once.

Parameters:

  db | a database object.
  recs | the records to store.
  rnum | specifies the number of the records.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of stored records, or -1 on failure.

int64_t kcdbremovebulk | ( | KCDB * | db,
|  | const KCSTR * | keys,
|  | size_t | knum,
|  | int32_t | atomic
| ) |  |

Remove records at once.

Parameters:

  db | a database object.
  keys | the keys of the records to remove.
  knum | specifies the number of the keys.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of removed records, or -1 on failure.

int64_t kcdbgetbulk | ( | KCDB * | db,
|  | const KCSTR * | keys,
|  | size_t | knum,
|  | KCREC * | recs,
|  | int32_t | atomic
| ) |  |

Retrieve records at once.

Parameters:

  db | a database object.
  keys | the keys of the records to retrieve.
  knum | specifies the number of the keys.
  recs | an array to contain the result. Its size must be sufficient.
  atomic | true to perform all operations atomically, or false for non-atomic operations.

Returns:
  the number of retrieved records, or -1 on failure.

Note:
  The regions of the key and the value of each element of the result should be released with the kcfree function when it is no longer in use.

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.

Note:
  The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

int32_t kcdboccupy | ( | KCDB * | db,
|  | int32_t | writable,
|  | KCFILEPROC | proc,
|  | void * | opq
| ) |  |

Occupy database by locking and do something meanwhile.

Parameters:

  db | a database object.
  writable | true to use writer lock, or false to use reader lock.
  proc | a processor object. If it is NULL, no processing is performed.
  opq | an opaque pointer to be given to the call back function.

Returns:
  true on success, or false on failure.

Note:
  The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

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 kcdbclear | ( | KCDB * | db | ) |

Remove all records.

Parameters:

  db | a database object.

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,
|  | size_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,
|  | size_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.

int64_t kcdbmatchsimilar | ( | KCDB * | db,
|  | const char * | origin,
|  | uint32_t | range,
|  | int32_t | utf,
|  | char ** | strary,
|  | size_t | max
| ) |  |

Get keys similar to a string in terms of the levenshtein distance.

Parameters:

  db | a database object.
  origin | the origin string.
  range | the maximum distance of keys to adopt.
  utf | flag to treat keys as UTF-8 strings.
  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 polymorphic 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.

Note:
  The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

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.

char* kccurseize | ( | KCCUR * | cur,
|  | size_t * | ksp,
|  | const char ** | vbp,
|  | size_t * | vsp
| ) |  |

Get a pair of the key and the value of the current record and remove it atomically.

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.

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. The cursor is moved to the next record implicitly.

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.

KCIDX* kcidxnew | ( | void |  | ) |

Create an index database object.

Returns:
  the created database object.

Note:
  The object of the return value should be released with the kcidxdel function when it is no longer in use.

void kcidxdel | ( | KCIDX * | idx | ) |

Destroy a database object.

Parameters:

  idx | the database object.

int32_t kcidxopen | ( | KCIDX * | idx,
|  | const char * | path,
|  | uint32_t | mode
| ) |  |

Open a database file.

Parameters:

  idx | a database object.
  path | the path of a database file. The same as with the polymorphic database.
  mode | the connection mode. The same as with the polymorphic database.

Returns:
  true on success, or false on failure.

int32_t kcidxclose | ( | KCIDX * | idx | ) |

Close the database file.

Parameters:

  idx | a database object.

Returns:
  true on success, or false on failure.

int32_t kcidxecode | ( | KCIDX * | idx | ) |

Get the code of the last happened error.

Parameters:

  idx | a database object.

Returns:
  the code of the last happened error.

const char* kcidxemsg | ( | KCIDX * | idx | ) |

Get the supplement message of the last happened error.

Parameters:

  idx | a database object.

Returns:
  the supplement message of the last happened error.

int32_t kcidxset | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Set the value of a record.

Parameters:

  idx | 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 kcidxadd | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Add a record.

Parameters:

  idx | 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 kcidxreplace | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Replace the value of a record.

Parameters:

  idx | 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 kcidxappend | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Append the value of a record.

Parameters:

  idx | 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.

int32_t kcidxremove | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz
| ) |  |

Remove a record.

Parameters:

  idx | 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* kcidxget | ( | KCIDX * | idx,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp
| ) |  |

Retrieve the value of a record.

Parameters:

  idx | 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 kcidxsync | ( | KCIDX * | idx,
|  | int32_t | hard,
|  | KCFILEPROC | proc,
|  | void * | opq
| ) |  |

Synchronize updated contents with the file and the device.

Parameters:

  idx | 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.

Note:
  The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

int32_t kcidxclear | ( | KCIDX * | idx | ) |

Remove all records.

Parameters:

  idx | a database object.

Returns:
  true on success, or false on failure.

int64_t kcidxcount | ( | KCIDX * | idx | ) |

Get the number of records.

Parameters:

  idx | a database object.

Returns:
  the number of records, or -1 on failure.

int64_t kcidxsize | ( | KCIDX * | idx | ) |

Get the size of the database file.

Parameters:

  idx | a database object.

Returns:
  the size of the database file in bytes, or -1 on failure.

char* kcidxpath | ( | KCIDX * | idx | ) |

Get the path of the database file.

Parameters:

  idx | 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* kcidxstatus | ( | KCIDX * | idx | ) |

Get the miscellaneous status information.

Parameters:

  idx | 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.

KCDB* kcidxrevealinnerdb | ( | KCIDX * | idx | ) |

Reveal the inner database object.

Returns:
  the inner database object, or NULL on failure.

KCMAP* kcmapnew | ( | size_t | bnum | ) |

Create a string hash map object.

Parameters:

  bnum | the number of buckets of the hash table. If it is not more than 0, the default setting 31 is specified.

Returns:
  the created map object.

Note:
  The object of the return value should be released with the kcmapdel function when it is no longer in use.

void kcmapdel | ( | KCMAP * | map | ) |

Destroy a map object.

Parameters:

  map | the map object.

void kcmapset | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Set the value of a record.

Parameters:

  map | the map 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.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

int32_t kcmapadd | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Add a record.

Parameters:

  map | the map 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 kcmapreplace | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Replace the value of a record.

Parameters:

  map | the map 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.

void kcmapappend | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Append the value of a record.

Parameters:

  map | the map 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.

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.

int32_t kcmapremove | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz
| ) |  |

Remove a record.

Parameters:

  map | the map 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.

const char* kcmapget | ( | KCMAP * | map,
|  | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp
| ) |  |

Retrieve the value of a record.

Parameters:

  map | the map 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.

void kcmapclear | ( | KCMAP * | map | ) |

Remove all records.

Parameters:

  map | the map object.

size_t kcmapcount | ( | KCMAP * | map | ) |

Get the number of records.

Parameters:

  map | the map object.

Returns:
  the number of records.

KCMAPITER* kcmapiterator | ( | KCMAP * | map | ) |

Create a string hash map iterator object.

Parameters:

  map | a map object.

Returns:
  the return value is the created iterator object.

Note:
  The object of the return value should be released with the kcmapiterdel function when it is no longer in use.
  This object will not be invalidated even when the map object is updated once. However, phantom records may be retrieved if they are removed after creation of each iterator.

void kcmapiterdel | ( | KCMAPITER * | iter | ) |

Destroy an iterator object.

Parameters:

  iter | the iterator object.

const char* kcmapitergetkey | ( | KCMAPITER * | iter,
|  | size_t * | sp
| ) |  |

Get the key of the current record.

Parameters:

  iter | the iterator object.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.

Returns:
  the pointer to the key region of the current record, or NULL on failure.

const char* kcmapitergetvalue | ( | KCMAPITER * | iter,
|  | size_t * | sp
| ) |  |

Get the value of the current record.

Parameters:

  iter | the iterator object.
  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 current record, or NULL on failure.

const char* kcmapiterget | ( | KCMAPITER * | iter,
|  | size_t * | ksp,
|  | const char ** | vbp,
|  | size_t * | vsp
| ) |  |

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

Parameters:

  iter | the iterator 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.

Returns:
  the pointer to the key region, or NULL on failure.

void kcmapiterstep | ( | KCMAPITER * | iter | ) |

Step the cursor to the next record.

Parameters:

  iter | the iterator object.

KCMAPSORT* kcmapsorter | ( | KCMAP * | map | ) |

Create a string hash map sorter object.

Parameters:

  map | a map object.

Returns:
  the return value is the created sorter object.

Note:
  The object of the return value should be released with the kcmapsortdel function when it is no longer in use.
  This object will not be invalidated even when the map object is updated once. However, phantom records may be retrieved if they are removed after creation of each sorter.

void kcmapsortdel | ( | KCMAPSORT * | sort | ) |

Destroy an sorter object.

Parameters:

  sort | the sorter object.

const char* kcmapsortgetkey | ( | KCMAPSORT * | sort,
|  | size_t * | sp
| ) |  |

Get the key of the current record.

Parameters:

  sort | the sorter object.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.

Returns:
  the pointer to the key region of the current record, or NULL on failure.

const char* kcmapsortgetvalue | ( | KCMAPSORT * | sort,
|  | size_t * | sp
| ) |  |

Get the value of the current record.

Parameters:

  sort | the sorter object.
  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 current record, or NULL on failure.

const char* kcmapsortget | ( | KCMAPSORT * | sort,
|  | size_t * | ksp,
|  | const char ** | vbp,
|  | size_t * | vsp
| ) |  |

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

Parameters:

  sort | the sorter 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.

Returns:
  the pointer to the key region, or NULL on failure.

void kcmapsortstep | ( | KCMAPSORT * | sort | ) |

Step the cursor to the next record.

Parameters:

  sort | the sorter object.

KCLIST* kclistnew | ( |  | ) |

Create a string array list object.

Returns:
  the created list object.

Note:
  The object of the return value should be released with the kclistdel function when it is no longer in use.

void kclistdel | ( | KCLIST * | list | ) |

Destroy a list object.

Parameters:

  list | the list object.

void kclistpush | ( | KCLIST * | list,
|  | const char * | buf,
|  | size_t | size
| ) |  |

Insert a record at the bottom of the list.

Parameters:

  list | the list object.
  buf | the pointer to the record region.
  size | the size of the record region.

int32_t kclistpop | ( | KCLIST * | list | ) |

Remove a record at the bottom of the list.

Parameters:

  list | the list object.

Returns:
  true if the operation success, or false if there is no record in the list.

void kclistunshift | ( | KCLIST * | list,
|  | const char * | buf,
|  | size_t | size
| ) |  |

Insert a record at the top of the list.

Parameters:

  list | the list object.
  buf | the pointer to the record region.
  size | the size of the record region.

int32_t kclistshift | ( | KCLIST * | list | ) |

Remove a record at the top of the list.

Parameters:

  list | the list object.

Returns:
  true if the operation success, or false if there is no record in the list.

void kclistinsert | ( | KCLIST * | list,
|  | const char * | buf,
|  | size_t | size,
|  | size_t | idx
| ) |  |

Insert a record at the position of the given index of the list.

Parameters:

  list | the list object.
  buf | the pointer to the record region.
  size | the size of the record region.
  idx | the index of the position. It must be equal to or less than the number of records.

void kclistremove | ( | KCLIST * | list,
|  | size_t | idx
| ) |  |

Remove a record at the position of the given index of the list.

Parameters:

  list | the list object.
  idx | the index of the position. It must be less than the number of records.

const char* kclistget | ( | KCLIST * | list,
|  | size_t | idx,
|  | size_t * | sp
| ) |  |

Retrieve a record at the position of the given index of the list.

Parameters:

  list | the list object.
  idx | the index of the position. It must be less than the number of records.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.

Returns:
  the pointer to the region of the retrieved record.

void kclistclear | ( | KCLIST * | list | ) |

Remove all records.

Parameters:

  list | the list object.

size_t kclistcount | ( | KCLIST * | list | ) |

Get the number of records.

Parameters:

  list | the list object.

Returns:
  the number of records.

## 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.