Provided by: libqdbm-dev_1.8.78-6build3_amd64 bug

NAME

       Cabin - the utility API of QDBM

SYNOPSIS

       #include <cabin.h>
       #include <stdlib.h>

       extern void (*cbfatalfunc)(const char *message);

       void *cbmalloc(size_t size);

       void *cbrealloc(void *ptr, size_t size);

       char *cbmemdup(const char *ptr, int size);

       void cbfree(void *ptr);

       void cbglobalgc(void *ptr, void (*func)(void *));

       void cbggcsweep(void);

       int cbvmemavail(size_t size);

       void cbisort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));

       void cbssort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));

       void cbhsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));

       void cbqsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));

       int cbstricmp(const char *astr, const char *bstr);

       int cbstrfwmatch(const char *str, const char *key);

       int cbstrfwimatch(const char *str, const char *key);

       int cbstrbwmatch(const char *str, const char *key);

       int cbstrbwimatch(const char *str, const char *key);

       char *cbstrstrkmp(const char *haystack, const char *needle);

       char *cbstrstrbm(const char *haystack, const char *needle);

       char *cbstrtoupper(char *str);

       char *cbstrtolower(char *str);

       char *cbstrtrim(char *str);

       char *cbstrsqzspc(char *str);

       int cbstrcountutf(const char *str);

       char *cbstrcututf(char *str, int num);

       CBDATUM *cbdatumopen(const char *ptr, int size);

       CBDATUM *cbdatumdup(const CBDATUM *datum);

       void cbdatumclose(CBDATUM *datum);

       void cbdatumcat(CBDATUM *datum, const char *ptr, int size);

       const char *cbdatumptr(const CBDATUM *datum);

       int cbdatumsize(const CBDATUM *datum);

       void cbdatumsetsize(CBDATUM *datum, int size);

       void cbdatumprintf(CBDATUM *datum, const char *format, ...);

       char *cbdatumtomalloc(CBDATUM *datum, int *sp);

       CBLIST *cblistopen(void);

       CBLIST *cblistdup(const CBLIST *list);

       void cblistclose(CBLIST *list);

       int cblistnum(const CBLIST *list);

       const char *cblistval(const CBLIST *list, int index, int *sp);

       void cblistpush(CBLIST *list, const char *ptr, int size);

       char *cblistpop(CBLIST *list, int *sp);

       void cblistunshift(CBLIST *list, const char *ptr, int size);

       char *cblistshift(CBLIST *list, int *sp);

       void cblistinsert(CBLIST *list, int index, const char *ptr, int size);

       char *cblistremove(CBLIST *list, int index, int *sp);

       void cblistover(CBLIST *list, int index, const char *ptr, int size);

       void cblistsort(CBLIST *list);

       int cblistlsearch(const CBLIST *list, const char *ptr, int size);

       int cblistbsearch(const CBLIST *list, const char *ptr, int size);

       char *cblistdump(const CBLIST *list, int *sp);

       CBLIST *cblistload(const char *ptr, int size);

       CBMAP *cbmapopen(void);

       CBMAP *cbmapdup(CBMAP *map);

       void cbmapclose(CBMAP *map);

       int  cbmapput(CBMAP  *map,  const  char  *kbuf,  int ksiz, const char *vbuf, int vsiz, int
       over);

       void cbmapputcat(CBMAP *map, const char *kbuf, int ksiz, const char *vbuf, int vsiz);

       int cbmapout(CBMAP *map, const char *kbuf, int ksiz);

       const char *cbmapget(const CBMAP *map, const char *kbuf, int ksiz, int *sp);

       int cbmapmove(CBMAP *map, const char *kbuf, int ksiz, int head);

       void cbmapiterinit(CBMAP *map);

       const char *cbmapiternext(CBMAP *map, int *sp);

       const char *cbmapiterval(const char *kbuf, int *sp);

       int cbmaprnum(const CBMAP *map);

       CBLIST *cbmapkeys(CBMAP *map);

       CBLIST *cbmapvals(CBMAP *map);

       char *cbmapdump(const CBMAP *map, int *sp);

       CBMAP *cbmapload(const char *ptr, int size);

       char *cbmaploadone(const char *ptr, int size, const char *kbuf, int ksiz, int *sp);

       CBHEAP *cbheapopen(int size, int max, int(*compar)(const void *, const void *));

       CBHEAP *cbheapdup(CBHEAP *heap);

       void cbheapclose(CBHEAP *heap);

       int cbheapnum(CBHEAP *heap);

       int cbheapinsert(CBHEAP *heap, const void *ptr);

       void *cbheapval(CBHEAP *heap, int index);

       void *cbheaptomalloc(CBHEAP *heap, int *np);

       char *cbsprintf(const char *format, ...);

       char *cbreplace(const char *str, CBMAP *pairs);

       CBLIST *cbsplit(const char *ptr, int size, const char *delim);

       char *cbreadfile(const char *name, int *sp);

       int cbwritefile(const char *name, const char *ptr, int size);

       CBLIST *cbreadlines(const char *name);

       CBLIST *cbdirlist(const char *name);

       int cbfilestat(const char *name, int *isdirp, int *sizep, time_t *mtimep);

       int cbremove(const char *name);

       CBMAP *cburlbreak(const char *str);

       char *cburlresolve(const char *base, const char *target);

       char *cburlencode(const char *ptr, int size);

       char *cburldecode(const char *str, int *sp);

       char *cbbaseencode(const char *ptr, int size);

       char *cbbasedecode(const char *str, int *sp);

       char *cbquoteencode(const char *ptr, int size);

       char *cbquotedecode(const char *str, int *sp);

       char *cbmimebreak(const char *ptr, int size, CBMAP *attrs, int *sp);

       CBLIST *cbmimeparts(const char *ptr, int size, const char *boundary);

       char *cbmimeencode(const char *str, const char *encname, int base);

       char *cbmimedecode(const char *str, char *enp);

       CBLIST *cbcsvrows(const char *str);

       CBLIST *cbcsvcells(const char *str);

       char *cbcsvescape(const char *str);

       char *cbcsvunescape(const char *str);

       CBLIST *cbxmlbreak(const char *str, int cr);

       CBMAP *cbxmlattrs(const char *str);

       char *cbxmlescape(const char *str);

       char *cbxmlunescape(const char *str);

       char *cbdeflate(const char *ptr, int size, int *sp);

       char *cbinflate(const char *ptr, int size, int *sp);

       char *cbgzencode(const char *ptr, int size, int *sp);

       char *cbgzdecode(const char *ptr, int size, int *sp);

       unsigned int cbgetcrc(const char *ptr, int size);

       char *cblzoencode(const char *ptr, int size, int *sp);

       char *cblzodecode(const char *ptr, int size, int *sp);

       char *cbbzencode(const char *ptr, int size, int *sp);

       char *cbbzdecode(const char *ptr, int size, int *sp);

       char *cbiconv(const char *ptr, int size, const char *icode, const char  *ocode,  int  *sp,
       int *mp);

       const char *cbencname(const char *ptr, int size);

       int cbjetlag(void);

       void cbcalendar(time_t t, int jl, int *yearp, int *monp, int *dayp, int *hourp, int *minp,
       int *secp);

       int cbdayofweek(int year, int mon, int day);

       char *cbdatestrwww(time_t t, int jl);

       char *cbdatestrhttp(time_t t, int jl);

       time_t cbstrmktime(const char *str);

       void cbproctime(double *usrp, double *sysp);

       void cbstdiobin(void);

DESCRIPTION

       Cabin is the utility API which provides memory allocating  functions,  sorting  functions,
       extensible  datum, array list, hash map, heap array, and so on for handling records easily
       on memory.  This API features also parsing MIME, CSV, and XML, and features various  types
       of encoding and decoding.

       In  order  to  use Cabin, you should include `cabin.h' and `stdlib.h' in the source files.
       Usually, the following description will be near the beginning of a source file.

              #include <cabin.h>
              #include <stdlib.h>

       A pointer to `CBDATUM' is used as a handle of an extensible  datum.   A  datum  handle  is
       opened  with  the  function  `cbdatumopen'  and  closed with `cbdatumclose'.  A pointer to
       `CBLIST' is used as a handle of an array list.  A list handle is opened with the  function
       `cblistopen' and closed with `cblistclose'.  A pointer to `CBMAP' is used as a handle of a
       hash map.  A  map  handle  is  opened  with  the  function  `cbmapopen'  and  closed  with
       `cbmapclose'.   A  pointer to `CBHEAP' is used as a handle of a heap array.  A heap handle
       is opened with the function `cbheapopen' and closed with `cbheapclose'.   You  should  not
       refer directly to any member of each handles.

       The  external  variable  `cbfatalfunc' is the pointer to call back function for handling a
       fatal error.

       extern void (*cbfatalfunc)(const char *message);
              The argument specifies the error message.  The initial value of  this  variable  is
              `NULL'.   If the value is `NULL', the default function is called when a fatal error
              occurs.  A fatal error occurs when memory allocation is failed.

       The function `cbmalloc' is used in order to allocate a region on memory.

       void *cbmalloc(size_t size);
              `size' specifies the size of the region.  The return value is the  pointer  to  the
              allocated  region.   Because  the  region of the return value is allocated with the
              `malloc' call, it should be released with the `free' call if it  is  no  longer  in
              use.

       The function `cbrealloc' is used in order to re-allocate a region on memory.

       void *cbrealloc(void *ptr, size_t size);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              The return value is the pointer to the re-allocated region.  Because the region  of
              the  return  value  is allocated with the `malloc' call, it should be released with
              the `free' call if it is no longer in use.

       The function `cbmemdup' is used in order to duplicate a region on memory.

       char *cbmemdup(const char *ptr, int size);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it  is  negative, the size is assigned with `strlen(ptr)'.  The return value is
              the pointer to the allocated region of the duplicate.  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 character string.  Because  the  region  of  the  return  value  is
              allocated  with the `malloc' call, it should be released with the `free' call if it
              is no longer in use.

       The function `cbfree' is used in order to free a region on memory.

       void cbfree(void *ptr);
              `ptr' specifies the pointer to a region.  If it is `NULL',  this  function  has  no
              effect.  Although this function is just a wrapper of `free' call, this is useful in
              applications using another package of the `malloc' series.

       The function `cbglobalgc' is used in order to register the pointer or handle of an  object
       to the global garbage collector.

       void cbglobalgc(void *ptr, void (*func)(void *));
              `ptr'  specifies  the pointer or handle of an object.  `func' specifies the pointer
              to a function to release resources of the object.  Its argument is the  pointer  or
              handle of the object to release.  This function assures that resources of an object
              are released when the process exits normally by returning from the `main'  function
              or calling the `exit' function.

       The  function  `cbggcsweep'  is  used  in  order  to exercise the global garbage collector
       explicitly.

       void cbggcsweep(void);
              Note that you should not use objects registered to the global garbage collector any
              longer  after  calling  this  function.   Because  the  global garbage collector is
              initialized and you can register new objects into it.

       The function `cbvmemavail' is used in order to check availability  of  allocation  of  the
       virtual memory.

       int cbvmemavail(size_t size);
              `size'  specifies  the  size  of region to be allocated newly.  The return value is
              true if allocation should be success, or false if not.

       The function `cbisort' is used in order to sort an array using insert sort.

       void cbisort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));
              `base' specifies the pointer to an array.  `nmemb' specifies the number of elements
              of  the  array.  `size' specifies the size of each element.  `compar' specifies the
              pointer to comparing function.  The two arguments specify the pointers of elements.
              The  comparing  function  should returns positive if the former is big, negative if
              the latter is big, 0 if both are  equal.   Insert  sort  is  useful  only  if  most
              elements have been sorted already.

       The function `cbssort' is used in order to sort an array using shell sort.

       void cbssort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));
              `base' specifies the pointer to an array.  `nmemb' specifies the number of elements
              of the array.  `size' specifies the size of each element.  `compar'  specifies  the
              pointer to comparing function.  The two arguments specify the pointers of elements.
              The comparing function should returns positive if the former is  big,  negative  if
              the  latter  is big, 0 if both are equal.  If most elements have been sorted, shell
              sort may be faster than heap sort or quick sort.

       The function `cbhsort' is used in order to sort an array using heap sort.

       void cbhsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));
              `base' specifies the pointer to an array.  `nmemb' specifies the number of elements
              of  the  array.   `size' specifies the size of each element. `compar' specifies the
              pointer to comparing function.  The two arguments specify the pointers of elements.
              The  comparing  function  should returns positive if the former is big, negative if
              the latter is big, 0 if both are equal.  Although heap sort is robust against  bias
              of input, quick sort is faster in most cases.

       The function `cbqsort' is used in order to sort an array using quick sort.

       void cbqsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *));
              `base' specifies the pointer to an array.  `nmemb' specifies the number of elements
              of the array.  `size' specifies the size of each element.  `compar'  specifies  the
              pointer to comparing function.  The two arguments specify the pointers of elements.
              The comparing function should returns positive if the former is  big,  negative  if
              the  latter  is  big, 0 if both are equal.  Being sensitive to bias of input, quick
              sort is the fastest sorting algorithm.

       The function `cbstricmp' is used in order to compare two  strings  with  case  insensitive
       evaluation.

       int cbstricmp(const char *astr, const char *bstr);
              `astr'  specifies  the  pointer of one string.  `astr' specifies the pointer of the
              other string.  The return value is positive if the former is big, negative  if  the
              latter  is big, 0 if both are equivalent.  Upper cases and lower cases of alphabets
              in ASCII code are not distinguished.

       The function `cbstrfwmatch' is used in order to check whether a string begins with a key.

       int cbstrfwmatch(const char *str, const char *key);
              `str' specifies the pointer of a target string.  `key' specifies the pointer  of  a
              forward  matching key string.  The return value is true if the target string begins
              with the key, else, it is false.

       The function `cbstrfwimatch' is used in order to check whether a string begins with a key,
       with case insensitive evaluation.

       int cbstrfwimatch(const char *str, const char *key);
              `str'  specifies  the pointer of a target string.  `key' specifies the pointer of a
              forward matching key string.  The return value is true if the target string  begins
              with the key, else, it is false.  Upper cases and lower cases of alphabets in ASCII
              code are not distinguished.

       The function `cbstrbwmatch' is used in order to check whether a string ends with a key.

       int cbstrbwmatch(const char *str, const char *key);
              `str' specifies the pointer of a target string.  `key' specifies the pointer  of  a
              backward  matching  key string.  The return value is true if the target string ends
              with the key, else, it is false.

       The function `cbstrbwimatch' is used in order to check whether a string ends with  a  key,
       with case insensitive evaluation.

       int cbstrbwimatch(const char *str, const char *key);
              `str'  specifies  the pointer of a target string.  `key' specifies the pointer of a
              backward matching key string.  The return value is true if the target  string  ends
              with the key, else, it is false.  Upper cases and lower cases of alphabets in ASCII
              code are not distinguished.

       The function `cbstrstrkmp' is used in order to locate a substring in a  string  using  KMP
       method.

       char *cbstrstrkmp(const char *haystack, const char *needle);
              `haystack'  specifies  the  pointer  of  a  target  string.  `needle' specifies the
              pointer of a substring to be found.   The  return  value  is  the  pointer  to  the
              beginning of the substring or `NULL' if the substring is not found.  In most cases,
              `strstr' as a built-in function of the compiler is faster than this function.

       The function `cbstrstrkmp' is used in order to locate a substring in  a  string  using  BM
       method.

       char *cbstrstrbm(const char *haystack, const char *needle);
              `haystack'  specifies  the  pointer  of  a  target  string.  `needle' specifies the
              pointer of a substring to be found.   The  return  value  is  the  pointer  to  the
              beginning of the substring or `NULL' if the substring is not found.  In most cases,
              `strstr' as a built-in function of the compiler is faster than this function.

       The function `cbstrtoupper' is used in order to convert the letters of a string  to  upper
       case.

       char *cbstrtoupper(char *str);
              `str'  specifies  the  pointer  of  a  string  to convert.  The return value is the
              pointer to the string.

       The function `cbstrtolower' is used in order to convert the letters of a string  to  lower
       case.

       char *cbstrtolower(char *str);
              `str'  specifies  the  pointer  of  a  string  to convert.  The return value is the
              pointer to the string.

       The function `cbstrtrim' is used in order to cut space characters at head  or  tail  of  a
       string.

       char *cbstrtrim(char *str);
              `str'  specifies  the  pointer  of  a  string  to convert.  The return value is the
              pointer to the string.

       The function `cbstrsqzspc' is used in order to squeeze space characters in  a  string  and
       trim it.

       char *cbstrsqzspc(char *str);
              `str'  specifies  the  pointer  of  a  string  to convert.  The return value is the
              pointer to the string.

       The function `cbstrcountutf' is used in order to count  the  number  of  characters  in  a
       string of UTF-8.

       int cbstrcountutf(const char *str);
              `str'  specifies  the pointer of a string of UTF-8.  The return value is the number
              of characters in the string.

       The function `cbstrcututf' is used in order to cut a string  of  UTF-8  at  the  specified
       number of characters.

       char *cbstrcututf(char *str, int num);
              `str'  specifies  the  pointer of a string of UTF-8.  `num' specifies the number of
              characters to be kept.  The return value is the pointer to the string.

       The function `cbdatumopen' is used in order to get a datum handle.

       CBDATUM *cbdatumopen(const char *ptr, int size);
              `ptr' specifies the pointer to the region of the initial content.  If it is `NULL',
              an  empty  datum  is  created.   `size' specifies the size of the region.  If it is
              negative, the size is assigned with `strlen(ptr)'.  The return  value  is  a  datum
              handle.

       The function `cbdatumdup' is used in order to copy a datum.

       CBDATUM *cbdatumdup(const CBDATUM *datum);
              `datum' specifies a datum handle.  The return value is a new datum handle.

       The function `cbdatumclose' is used in order to free a datum handle.

       void cbdatumclose(CBDATUM *datum);
              `datum'  specifies  a  datum  handle.   Because  the  region  of a closed handle is
              released, it becomes impossible to use the handle.

       The function `cbdatumcat' is used in order to concatenate a datum and a region.

       void cbdatumcat(CBDATUM *datum, const char *ptr, int size);
              `datum' specifies a datum handle.  `ptr' specifies the pointer to the region to  be
              appended.  `size' specifies the size of the region.  If it is negative, the size is
              assigned with `strlen(ptr)'.

       The function `cbdatumptr' is used in order to get the pointer of the region of a datum.

       const char *cbdatumptr(const CBDATUM *datum);
              `datum' specifies a datum handle.  The return value is the pointer of the region of
              a  datum.   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 character string.

       The function `cbdatumsize' is used in order to get the size of the region of a datum.

       int cbdatumsize(const CBDATUM *datum);
              `datum' specifies a datum handle.  The return value is the size of the region of  a
              datum.

       The  function  `cbdatumsetsize'  is  used  in  order to change the size of the region of a
       datum.

       void cbdatumsetsize(CBDATUM *datum, int size);
              `datum' specifies a datum handle.  `size' specifies the new size of the region.  If
              the  new size is bigger than the one of old, the surplus region is filled with zero
              codes.

       The function `cbdatumprintf' is used in order to perform formatted output into a datum.

       void cbdatumprintf(CBDATUM *datum, const char *format, ...);
              `format' specifies a printf-like format string.  The conversion character  `%'  can
              be  used  with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E',
              `f', `g', `G', `@', `?', `:',  `%'.   `@'  works  as  with  `s'  but  escapes  meta
              characters  of XML.  `?' works as with `s' but escapes meta characters of URL.  `:'
              works as with `s' but performs  MIME  encoding  as  UTF-8.   The  other  conversion
              character work as with each original.

       The function `cbdatumtomalloc' is used in order to convert a datum to an allocated region.

       char *cbdatumtomalloc(CBDATUM *datum, int *sp);
              `datum'  specifies  a  datum  handle.   `sp' specifies the pointer to a variable to
              which the size of the region of the return value is assigned.  If it is `NULL',  it
              is  not used.  The return value is the pointer to the region of the datum.  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 character string.  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free' call if it is no longer in use.  Because the region of the original datum is
              released, it should not be released again.

       The function `cblistopen' is used in order to get a list handle.

       CBLIST *cblistopen(void);
              The return value is a list handle.

       The function `cblistdup' is used in order to copy a list.

       CBLIST *cblistdup(const CBLIST *list);
              `list' specifies a list handle.  The return value is a new list handle.

       The function `cblistclose' is used in order to close a list handle.

       void cblistclose(CBLIST *list);
              `list' specifies a list handle.  Because the region of a closed handle is released,
              it becomes impossible to use the handle.

       The function `cblistnum' is used in order to get the number of elements of a list.

       int cblistnum(const CBLIST *list);
              `list'  specifies a list handle.  The return value is the number of elements of the
              list.

       The function `cblistval' is used in order to get the pointer to the region of  an  element
       of a list.

       const char *cblistval(const CBLIST *list, int index, int *sp);
              `list'  specifies  a list handle.  `index' specifies the index of an element.  `sp'
              specifies the pointer to a variable to which the size of the region of  the  return
              value  is  assigned.   If  it  is  `NULL', it is not used.  The return value is the
              pointer to the region of the element.  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
              character string.  If `index' is equal to or more than the number of elements,  the
              return value is `NULL'.

       The function `cblistpush' is used in order to add an element at the end of a list.

       void cblistpush(CBLIST *list, const char *ptr, int size);
              `list'  specifies  a  list handle.  `ptr' specifies the pointer to the region of an
              element.  `size' specifies the size of the region.  If it is negative, the size  is
              assigned with `strlen(ptr)'.

       The function `cblistpop' is used in order to remove an element of the end of a list.

       char *cblistpop(CBLIST *list, int *sp);
              `list'  specifies a list handle.  `sp' specifies the pointer to a variable to which
              the size of the region of the return value is assigned.  If it is `NULL', it is not
              used.   The  return  value  is  the pointer to the region of the value.  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 character string.  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free'  call  if it is no longer in use.  If the list is empty, the return value is
              `NULL'.

       The function `cblistunshift' is used in order to add an element at the top of a list.

       void cblistunshift(CBLIST *list, const char *ptr, int size);
              `list' specifies a list handle.  `ptr' specifies the pointer to the  region  of  an
              element.   `size' specifies the size of the region.  If it is negative, the size is
              assigned with `strlen(ptr)'.

       The function `cblistshift' is used in order to remove an element of the top of a list.

       char *cblistshift(CBLIST *list, int *sp);
              `list' specifies a list handle.  `sp' specifies the pointer to a variable to  which
              the size of the region of the return value is assigned.  If it is `NULL', it is not
              used.  The return value is the pointer to the region  of  the  value.   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 character  string.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.  If the list is empty, the return  value  is
              `NULL'.

       The  function  `cblistinsert' is used in order to add an element at the specified location
       of a list.

       void cblistinsert(CBLIST *list, int index, const char *ptr, int size);
              `list' specifies a list handle.  `index' specifies the index of an element.   `ptr'
              specifies  the  pointer to the region of the element.  `size' specifies the size of
              the region.  If it is negative, the size is assigned with `strlen(ptr)'.

       The function `cblistremove' is used in  order  to  remove  an  element  at  the  specified
       location of a list.

       char *cblistremove(CBLIST *list, int index, int *sp);
              `list'  specifies  a list handle.  `index' specifies the index of an element.  `sp'
              specifies the pointer to a variable to which the size of the region of  the  return
              value  is  assigned.   If  it  is  `NULL', it is not used.  The return value is the
              pointer to the region of the value.  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
              character string.  Because the region of the return value  is  allocated  with  the
              `malloc'  call,  it  should  be released with the `free' call if it is no longer in
              use.  If `index' is equal to or more than the number of  elements,  no  element  is
              removed and the return value is `NULL'.

       The  function  `cblistover'  is  used  in  order  to overwrite an element at the specified
       location of a list.

       void cblistover(CBLIST *list, int index, const char *ptr, int size);
              `list' specifies a list handle.  `index' specifies the index of an element.   `ptr'
              specifies  the pointer to the region of the new content.  `size' specifies the size
              of the new content.  If it is negative, the size is  assigned  with  `strlen(ptr)'.
              If  `index'  is  equal to or more than the number of elements, this function has no
              effect.

       The function `cblistsort' is used in order to sort elements of a list in lexical order.

       void cblistsort(CBLIST *list);
              `list' specifies a list handle.  Quick sort is used for sorting.

       The function `cblistlsearch' is used in order to search a list for an element using  liner
       search.

       int cblistlsearch(const CBLIST *list, const char *ptr, int size);
              `list'  specifies  a  list  handle.  `ptr' specifies the pointer to the region of a
              key.  `size' specifies the size of the region.  If it  is  negative,  the  size  is
              assigned  with  `strlen(ptr)'.   The  return  value is the index of a corresponding
              element or -1 if there is no  corresponding  element.   If  two  or  more  elements
              corresponds, the former returns.

       The function `cblistbsearch' is used in order to search a list for an element using binary
       search.

       int cblistbsearch(const CBLIST *list, const char *ptr, int size);
              `list' specifies a list handle.  It should  be  sorted  in  lexical  order.   `ptr'
              specifies  the  pointer  to  the region of a key.  `size' specifies the size of the
              region.  If it is negative, the size is assigned with  `strlen(ptr)'.   The  return
              value  is  the  index of a corresponding element or -1 if there is no corresponding
              element.  If two or more elements corresponds, which returns is not defined.

       The function `cblistdump' is used in order to serialize a list into a byte array.

       char *cblistdump(const CBLIST *list, int *sp);
              `list' specifies a list handle.  `sp' specifies the pointer to a variable to  which
              the  size  of  the region of the return value is assigned.  The return value is the
              pointer to the region of the result serial  region.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.

       The function `cblistload' is used in order to redintegrate a serialized list.

       CBLIST *cblistload(const char *ptr, int size);
              `ptr' specifies the pointer to a byte array.  `size'  specifies  the  size  of  the
              region.  The return value is a new list handle.

       The function `cbmapopen' is used in order to get a map handle.

       CBMAP *cbmapopen(void);
              The return value is a map handle.

       The function `cbmapdup' is used in order to copy a map.

       CBMAP *cbmapdup(CBMAP *map);
              `map'  specifies a map handle.  The return value is a new map handle.  The iterator
              of the source map is initialized.

       The function `cbmapclose' is used in order to close a map handle.

       void cbmapclose(CBMAP *map);
              `map' specifies a map handle.  Because the region of a closed handle  is  released,
              it becomes impossible to use the handle.

       The function `cbmapput' is used in order to store a record into a map.

       int  cbmapput(CBMAP  *map,  const  char  *kbuf,  int ksiz, const char *vbuf, int vsiz, int
       over);
              `map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.
              `ksiz' specifies the size of the region of the key.  If it is negative, the size is
              assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer  to  the  region  of  a
              value.   `vsiz'  specifies the size of the region of the value.  If it is negative,
              the size is assigned with `strlen(vbuf)'.  `over' specifies whether  the  value  of
              the  duplicated  record  is  overwritten or not.  If `over' is false and the key is
              duplicated, the return value is false, else, it is true.

       The function `cbmapputcat' is used in order to concatenate a value at the end of the value
       of the existing record.

       void cbmapputcat(CBMAP *map, const char *kbuf, int ksiz, const char *vbuf, int vsiz);
              `map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.
              `ksiz' specifies the size of the region of the key.  If it is negative, the size is
              assigned  with  `strlen(kbuf)'.   `vbuf'  specifies  the pointer to the region of a
              value.  `vsiz' specifies the size of the region of the value.  If it  is  negative,
              the  size  is assigned with `strlen(vbuf)'.  If there is no corresponding record, a
              new record is created.

       The function `cbmapout' is used in order to delete a record in a map.

       int cbmapout(CBMAP *map, const char *kbuf, int ksiz);
              `map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.
              `ksiz' specifies the size of the region of the key.  If it is negative, the size is
              assigned with `strlen(kbuf)'.  If successful, the return value is true.   False  is
              returned when no record corresponds to the specified key.

       The function `cbmapget' is used in order to retrieve a record in a map.

       const char *cbmapget(const CBMAP *map, const char *kbuf, int ksiz, int *sp);
              `map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.
              `ksiz' specifies the size of the region of the key.  If it is negative, the size is
              assigned  with  `strlen(kbuf)'.   `sp' specifies the pointer to a variable to which
              the size of the region of the return value is assigned.  If it is `NULL', it is not
              used.  If successful, the return value is the pointer to the region of the value of
              the corresponding record.  `NULL' is returned when no record corresponds.   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 character string.

       The function `cbmapmove' is used in order to move a record to the edge of a map.

       int cbmapmove(CBMAP *map, const char *kbuf, int ksiz, int head);
              `map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.
              `ksiz' specifies the size of the region of the key.  If it is negative, the size is
              assigned with `strlen(kbuf)'.  `head' specifies the destination which is head if it
              is  true  or  tail  if  else.   If  successful, the return value is true.  False is
              returned when no record corresponds to the specified key.

       The function `cbmapiterinit' is used in order to initialize the iterator of a map.

       void cbmapiterinit(CBMAP *map);
              `map' specifies a map handle.  The iterator is used in order to access the  key  of
              every record stored in a map.

       The  function  `cbmapiternext'  is  used in order to get the next key of the iterator of a
       map.

       const char *cbmapiternext(CBMAP *map, int *sp);
              `map' specifies a map handle.  `sp' specifies the pointer to a  variable  to  which
              the size of the region of the return value is assigned.  If it is `NULL', it is not
              used.  If successful, the return value is the pointer to the  region  of  the  next
              key, else, it is `NULL'.  `NULL' is returned when no record is to be get out of the
              iterator.  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 character string.  The order
              of iteration is assured to be the same of the one of storing.

       The function `cbmapiterval' is used in order to get the value binded to  the  key  fetched
       from the iterator of a map.

       const char *cbmapiterval(const char *kbuf, int *sp);
              `kbuf'  specifies the pointer to the region of a iteration key.  `sp' specifies the
              pointer to a variable to which the size of  the  region  of  the  return  value  is
              assigned.  If it is `NULL', it is not used.  The return value is the pointer to the
              region of the value of the corresponding record.  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 character string.

       The function `cbmaprnum' is used in order to get the number of the  records  stored  in  a
       map.

       int cbmaprnum(const CBMAP *map);
              `map' specifies a map handle.  The return value is the number of the records stored
              in the map.

       The function `cbmapkeys' is used in order to get the list handle contains all  keys  in  a
       map.

       CBLIST *cbmapkeys(CBMAP *map);
              `map'  specifies  a  map  handle.  The return value is the list handle contains all
              keys in the map.  Because the handle  of  the  return  value  is  opened  with  the
              function `cblistopen', it should be closed with the function `cblistclose' if it is
              no longer in use.

       The function `cbmapvals' is used in order to get the list handle contains all values in  a
       map.

       CBLIST *cbmapvals(CBMAP *map);
              `map'  specifies  a  map  handle.  The return value is the list handle contains all
              values in the map.  Because the handle of the  return  value  is  opened  with  the
              function `cblistopen', it should be closed with the function `cblistclose' if it is
              no longer in use.

       The function `cbmapdump' is used in order to serialize a map into a byte array.

       char *cbmapdump(const CBMAP *map, int *sp);
              `map' specifies a map handle.  `sp' specifies the pointer to a  variable  to  which
              the  size  of  the region of the return value is assigned.  The return value is the
              pointer to the region of the result serial  region.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.

       The function `cbmapload' is used in order to redintegrate a serialized map.

       CBMAP *cbmapload(const char *ptr, int size);
              `ptr' specifies the pointer to a byte array.  `size'  specifies  the  size  of  the
              region.  The return value is a new map handle.

       The function `cbmaploadone' is used in order to extract a record from a serialized map.

       char *cbmaploadone(const char *ptr, int size, const char *kbuf, int ksiz, int *sp);
              `ptr'  specifies  the  pointer  to  a byte array.  `size' specifies the size of the
              region.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the
              size  of  the  region  of  the  key.   If it is negative, the size is assigned with
              `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of  the
              region  of  the  return  value  is  assigned.  If it is `NULL', it is not used.  If
              successful, the return value is the pointer to the  region  of  the  value  of  the
              corresponding  record.   `NULL' is returned when no record corresponds.  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 character string.

       The function `cbheapopen' is used in order to get a heap handle.

       CBHEAP *cbheapopen(int size, int max, int(*compar)(const void *, const void *));
              `size'  specifies  the  size of each record.  `max' specifies the maximum number of
              records in the heap.  `compar' specifies the pointer to  comparing  function.   The
              two  arguments  specify  the  pointers  of  records.  The comparing function should
              returns positive if the former is big, negative if the latter is big, 0 if both are
              equal.  The return value is a heap handle.

       The function `cbheapdup' is used in order to copy a heap.

       CBHEAP *cbheapdup(CBHEAP *heap);
              `heap' specifies a heap handle.  The return value is a new heap handle.

       The function `cbheapclose' is used in order to close a heap handle.

       void cbheapclose(CBHEAP *heap);
              `heap' specifies a heap handle.  Because the region of a closed handle is released,
              it becomes impossible to use the handle.

       The function `cbheapnum' is used in order to get the number of the  records  stored  in  a
       heap.

       int cbheapnum(CBHEAP *heap);
              `heap'  specifies  a  heap  handle.   The return value is the number of the records
              stored in the heap.

       The function `cbheapinsert' is used in order to insert a record into a heap.

       int cbheapinsert(CBHEAP *heap, const void *ptr);
              `heap' specifies a heap handle.  `ptr' specifies the pointer to  the  region  of  a
              record.   The  return value is true if the record is added, else false.  If the new
              record is bigger than the biggest existing regord, the new record is not added.  If
              the  new  record is added and the number of records exceeds the maximum number, the
              biggest existing record is removed.

       The function `cbheapval' is used in order to get the pointer to the region of a record  in
       a heap.

       void *cbheapval(CBHEAP *heap, int index);
              `heap'  specifies  a  heap  handle.   `index' specifies the index of a record.  The
              return value is the pointer to the region of the record.  If `index' is equal to or
              more than the number of records, the return value is `NULL'.  Note that records are
              organized by the nagative order the comparing function.

       The function `cbheaptomalloc' is used in order to convert a heap to an allocated region.

       void *cbheaptomalloc(CBHEAP *heap, int *np);
              `heap' specifies a heap handle.  `np' specifies the pointer to a variable to  which
              the  number of records of the return value is assigned.  If it is `NULL', it is not
              used.  The return value is the pointer to the region  of  the  heap.   Records  are
              sorted.   Because  the  region  of  the return value is allocated with the `malloc'
              call, it should be released with the `free'  call  if  it  is  no  longer  in  use.
              Because  the  region  of  the  original heap is released, it should not be released
              again.

       The function `cbsprintf' is used in order to allocate a formatted string on memory.

       char *cbsprintf(const char *format, ...);
              `format' specifies a printf-like format string.  The conversion character  `%'  can
              be  used  with such flag characters as `d', `o', `u', `x', `X', `e', `E', `f', `g',
              `G', `c', `s', and `%'.  Specifiers of the field length and the  precision  can  be
              put  between  the  conversion  characters  and the flag characters.  The specifiers
              consist of decimal characters, `.', `+', `-', and the space character.   The  other
              arguments are used according to the format string.  The return value is the pointer
              to the allocated region of the result string.  Because the  region  of  the  return
              value  is  allocated  with the `malloc' call, it should be released with the `free'
              call if it is no longer in use.

       The function `cbreplace' is used in order to replace some patterns in a string.

       char *cbreplace(const char *str, CBMAP *pairs);
              `str' specifies the pointer to a source string.  `pairs' specifies the handle of  a
              map  composed  of  pairs  of replacement.  The key of each pair specifies a pattern
              before replacement and its value specifies  the  pattern  after  replacement.   The
              return  value is the pointer to the allocated region of the result string.  Because
              the region of the return value is allocated with the `malloc' call,  it  should  be
              released with the `free' call if it is no longer in use.

       The function `cbsplit' is used in order to make a list by splitting a serial datum.

       CBLIST *cbsplit(const char *ptr, int size, const char *delim);
              `ptr'  specifies the pointer to the region of the source content.  `size' specifies
              the  size  of  the  region.   If  it  is  negative,  the  size  is  assigned   with
              `strlen(ptr)'.  `delim' specifies a string containing delimiting characters.  If it
              is `NULL', zero code is used as a delimiter.  The return value is  a  list  handle.
              If  two  delimiters  are successive, it is assumed that an empty element is between
              the two.  Because the handle of the  return  value  is  opened  with  the  function
              `cblistopen', it should be closed with the function `cblistclose'.

       The function `cbreadfile' is used in order to read whole data of a file.

       char *cbreadfile(const char *name, int *sp);
              `name'  specifies  the  name  of  a  file.   If it is `NULL', the standard input is
              specified.  `sp' specifies the pointer to a variable  to  which  the  size  of  the
              region  of  the  return  value  is assigned.  If it is `NULL', it is not used.  The
              return value is the pointer to the allocated region of the read data.   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 character  string.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.

       The function `cbwritefile' is used in order to write a serial datum into a file.

       int cbwritefile(const char *name, const char *ptr, int size);
              `name specifies the name of a file.  If  it  is  `NULL',  the  standard  output  is
              specified.   `ptr'  specifies  the  pointer  to  the  region of the source content.
              `size' specifies the size of the region.  If it is negative, the size  is  assigned
              with  `strlen(ptr)'.   If  successful, the return value is true, else, it is false.
              If the file exists, it is overwritten.  Else, a new file is created.

       The function `cbreadlines' is used in order to read every line of a file.

       CBLIST *cbreadlines(const char *name);
              `name' specifies the name of a file.  If  it  is  `NULL',  the  standard  input  is
              specified.   The  return value is a list handle of the lines if successful, else it
              is NULL.  Line separators are cut out.  Because the handle of the return  value  is
              opened  with  the  function  `cblistopen',  it  should  be closed with the function
              `cblistclose' if it is no longer in use.

       The function `cbdirlist' is used in order to read names of files in a directory.

       CBLIST *cbdirlist(const char *name);
              `name' specifies the name of a directory.  The return value is  a  list  handle  of
              names  if  successful,  else it is NULL.  Because the handle of the return value is
              opened with the function `cblistopen',  it  should  be  closed  with  the  function
              `cblistclose' if it is no longer in use.

       The function `cbfilestat' is used in order to get the status of a file or a directory.

       int cbfilestat(const char *name, int *isdirp, int *sizep, time_t *mtimep);
              `name'  specifies  the name of a file or a directory.  `dirp' specifies the pointer
              to a variable to which whether the file is a  directory  is  assigned.   If  it  is
              `NULL',  it  is not used.  `sizep' specifies the pointer to a variable to which the
              size of the file is assigned.  If it is `NULL', it is not used.  `mtimep' specifies
              the  pointer to a variable to which the last modified time of the file is assigned.
              If it is `NULL', it is not used.  If successful, the return value  is  true,  else,
              false.  False is returned when the file does not exist or the permission is denied.

       The  function `cbremove' is used in order to remove a file or a directory and its sub ones
       recursively.

       int cbremove(const char *name);
              `name' specifies the name of a file or a  directory.   If  successful,  the  return
              value  is true, else, false.  False is returned when the file does not exist or the
              permission is denied.

       The function `cburlbreak' is used in order to break up a URL into elements.

       CBMAP *cburlbreak(const char *str);
              `str' specifies the pointer to a string of URL.  The return value is a map  handle.
              Each  key  of  the map is the name of an element.  The key "self" specifies the URL
              itself.  The key "scheme" specifies the scheme.  The key "host" specifies the  host
              of  the  server.   The key "port" specifies the port number of the server.  The key
              "authority" specifies the authority information.  The key "path" specifies the path
              of  the  resource.   The  key  "file" specifies the file name without the directory
              section.  The key "query" specifies the query string.  The key "fragment" specifies
              the  fragment  string.   Supported schema are HTTP, HTTPS, FTP, and FILE.  Absolute
              URL and relative URL are supported.  Because the handle  of  the  return  value  is
              opened  with  the  function  `cbmapopen',  it  should  be  closed with the function
              `cbmapclose' if it is no longer in use.

       The runction `cburlresolve' is used in order  to  resolve  a  relative  URL  with  another
       absolute URL.

       char *cburlresolve(const char *base, const char *target);
              `base'  specifies  an absolute URL of a base location.  `target' specifies a URL to
              be resolved.  The return value is a resolved URL.  If the target URL is relative, a
              new  URL  of relative location from the base location is returned.  Else, a copy of
              the target URL is returned.  Because the region of the return  value  is  allocated
              with  the  `malloc'  call,  it  should be released with the `free' call if it is no
              longer in use.

       The function `cburlencode' is used in order to encode a serial object with URL encoding.

       char *cburlencode(const char *ptr, int size);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it  is  negative, the size is assigned with `strlen(ptr)'.  The return value is
              the pointer to the result string.  Because  the  region  of  the  return  value  is
              allocated  with the `malloc' call, it should be released with the `free' call if it
              is no longer in use.

       The function `cburldecode' is used in order to decode a string encoded with URL encoding.

       char *cburldecode(const char *str, int *sp);
              `str' specifies the pointer to a source string.  `sp' specifies the  pointer  to  a
              variable to which the size of the region of the return value is assigned.  If it is
              `NULL', it is not used.  The return value is the  pointer  to  the  region  of  the
              result.   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 character  string.   Because
              the  region  of  the return value is allocated with the `malloc' call, it should be
              released with the `free' call if it is no longer in use.

       The function `cbbaseencode' is used in  order  to  encode  a  serial  object  with  Base64
       encoding.

       char *cbbaseencode(const char *ptr, int size);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              If it is negative, the size is assigned with `strlen(ptr)'.  The  return  value  is
              the  pointer  to  the  result  string.   Because  the region of the return value is
              allocated with the `malloc' call, it should be released with the `free' call if  it
              is no longer in use.

       The  function  `cbbasedecode'  is  used  in  order  to decode a string encoded with Base64
       encoding.

       char *cbbasedecode(const char *str, int *sp);
              `str' specifies the pointer to a source string.  `sp' specifies the  pointer  to  a
              variable to which the size of the region of the return value is assigned.  If it is
              `NULL', it is not used.  The return value is the  pointer  to  the  region  of  the
              result.   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 character  string.   Because
              the  region  of  the return value is allocated with the `malloc' call, it should be
              released with the `free' call if it is no longer in use.

       The  function  `cbquoteencode'  is  used  in  order  to  encode  a  serial   object   with
       quoted-printable encoding.

       char *cbquoteencode(const char *ptr, int size);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              If it is negative, the size is assigned with `strlen(ptr)'.  The  return  value  is
              the  pointer  to  the  result  string.   Because  the region of the return value is
              allocated with the `malloc' call, it should be released with the `free' call if  it
              is no longer in use.

       The   function  `cbquotedecode'  is  used  in  order  to  decode  a  string  encoded  with
       quoted-printable encoding.

       char *cbquotedecode(const char *str, int *sp);
              `str' specifies the pointer to a source string.  `sp' specifies the  pointer  to  a
              variable to which the size of the region of the return value is assigned.  If it is
              `NULL', it is not used.  The return value is the  pointer  to  the  region  of  the
              result.   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 character  string.   Because
              the  region  of  the return value is allocated with the `malloc' call, it should be
              released with the `free' call if it is no longer in use.

       The function `cbmimebreak' is used in order to split a string of MIME into headers and the
       body.

       char *cbmimebreak(const char *ptr, int size, CBMAP *attrs, int *sp);
              `ptr'  specifies the pointer to the region of MIME data.  `size' specifies the size
              of the region.  If it  is  negative,  the  size  is  assigned  with  `strlen(ptr)'.
              `attrs'  specifies  a  map  handle to store attributes.  If it is `NULL', it is not
              used.  Each key of the map is an attribute name uncapitalized.  `sp' specifies  the
              pointer  to  a  variable  to  which  the  size of the region of the return value is
              assigned.  If it is `NULL', it is not used.  The return value is the pointer of the
              body  data.   If  the content type is defined, the attribute map has the key "TYPE"
              specifying the type.  If the character  encoding  is  defined,  the  key  "CHARSET"
              specifies  the  encoding name.  If the boundary string of multipart is defined, the
              key "BOUNDARY" specifies the string.  If the content disposition  is  defined,  the
              key  "DISPOSITION"  specifies  the direction.  If the file name is defined, the key
              "FILENAME" specifies the name.  If the attribute name is defined,  the  key  "NAME"
              specifies  the  name.  Because the region of the return value is allocated with the
              `malloc' call, it should be released with the `free' call if it  is  no  longer  in
              use.

       The  function  `cbmimeparts'  is  used  in  order to split multipart data of MIME into its
       parts.

       CBLIST *cbmimeparts(const char *ptr, int size, const char *boundary);
              `ptr' specifies the pointer to the  region  of  multipart  data  of  MIME.   `size'
              specifies  the  size  of  the region.  If it is negative, the size is assigned with
              `strlen(ptr)'.  `boundary' specifies the pointer to  the  region  of  the  boundary
              string.  The return value is a list handle.  Each element of the list is the string
              of a part.  Because the handle of the return value  is  opened  with  the  function
              `cblistopen',  it  should  be  closed  with  the function `cblistclose' if it is no
              longer in use.

       The function `cbmimeencode' is used in order to encode a string with MIME encoding.

       char *cbmimeencode(const char *str, const char *encname, int base);
              `str' specifies the pointer to a string.  `encname' specifies a string of the  name
              of  the  character encoding.  The return value is the pointer to the result string.
              `base' specifies whether to use Base64 encoding.  If it is false,  quoted-printable
              is  used.   Because  the  region of the return value is allocated with the `malloc'
              call, it should be released with the `free' call if it is no longer in use.

       The function `cbmimedecode' is used  in  order  to  decode  a  string  encoded  with  MIME
       encoding.

       char *cbmimedecode(const char *str, char *enp);
              `str' specifies the pointer to an encoded string.  `enp' specifies the pointer to a
              region into which the name of encoding is written.  If it  is  `NULL',  it  is  not
              used.  The size of the buffer should be equal to or more than 32 bytes.  The return
              value is the pointer to the result string.  Because the region of the return  value
              is  allocated with the `malloc' call, it should be released with the `free' call if
              it is no longer in use.

       The function `cbcsvrows' is used in order to split a string of CSV into rows.

       CBLIST *cbcsvrows(const char *str);
              `str' specifies the pointer to the region of an CSV string.  The return value is  a
              list handle.  Each element of the list is a string of a row.  Because the handle of
              the return value is opened with the function `cblistopen', it should be closed with
              the  function  `cblistclose'  if it is no longer in use.  The character encoding of
              the input string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS.  Being
              compatible  with  MS-Excel, these functions for CSV can handle cells including such
              meta characters as comma, between double quotation marks.

       The function `cbcsvcells' is used in order to split the string of a row of CSV into cells.

       CBLIST *cbcsvcells(const char *str);
              `str' specifies the pointer to the region of a row of CSV.  The return value  is  a
              list  handle.   Each  element  of the list is the unescaped string of a cell of the
              row.  Because  the  handle  of  the  return  value  is  opened  with  the  function
              `cblistopen',  it  should  be  closed  with  the function `cblistclose' if it is no
              longer in use.

       The function `cbcsvescape' is used in order to escape a string with the meta characters of
       CSV.

       char *cbcsvescape(const char *str);
              `str'  specifies  the  pointer  to the region of a string.  The return value is the
              pointer to the escaped string sanitized of meta characters.  Because the region  of
              the  return  value  is allocated with the `malloc' call, it should be released with
              the `free' call if it is no longer in use.

       The function `cbcsvunescape' is used in order to unescape a string with the  escaped  meta
       characters of CSV.

       char *cbcsvunescape(const char *str);
              `str'  specifies  the  pointer to the region of a string with meta characters.  The
              return value is the pointer to the unescaped string.  Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.

       The function `cbxmlbreak' is used in order to split a string of XML  into  tags  and  text
       sections.

       CBLIST *cbxmlbreak(const char *str, int cr);
              `str' specifies the pointer to the region of an XML string.  `cr' specifies whether
              to remove comments.  The return value is a list handle.  Each element of  the  list
              is  the  string of a tag or a text section.  Because the handle of the return value
              is opened with the function `cblistopen', it should be  closed  with  the  function
              `cblistclose'  if  it  is  no  longer  in use.  The character encoding of the input
              string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS.   Because  these
              functions for XML are not XML parser with validation check, it can handle also HTML
              and SGML.

       The function `cbxmlattrs' is used in order to get the map of attributes of an XML tag.

       CBMAP *cbxmlattrs(const char *str);
              `str' specifies the pointer to the region of a tag string.  The return value  is  a
              map  handle.   Each  key  of  the  map  is the name of an attribute.  Each value is
              unescaped.  You can get the name of the tag  with  the  key  of  an  empty  string.
              Because  the handle of the return value is opened with the function `cbmapopen', it
              should be closed with the function `cbmapclose' if it is no longer in use.

       The function `cbxmlescape' is used in order to escape a string with the meta characters of
       XML.

       char *cbxmlescape(const char *str);
              `str'  specifies  the  pointer  to the region of a string.  The return value is the
              pointer to the escaped string sanitized of meta characters.  This function converts
              only  `&',  `<', `>', and `"'.  Because the region of the return value is allocated
              with the `malloc' call, it should be released with the `free'  call  if  it  is  no
              longer in use.

       The  function  `cbxmlunescape'  is  used  in  order  to  unescape a string with the entity
       references of XML.

       char *cbxmlunescape(const char *str);
              `str' specifies the pointer to the region of a string.  The  return  value  is  the
              pointer  to  the  unescaped  string.   This function restores only `&amp;', `&lt;',
              `&gt;', and `&quot;'.  Because the region of the return value is allocated with the
              `malloc'  call,  it  should  be released with the `free' call if it is no longer in
              use.

       The function `cbdeflate' is used in order to compress a serial object with ZLIB.

       char *cbdeflate(const char *ptr, int size, int *sp);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it  is  negative,  the size is assigned with `strlen(ptr)'.  `sp' specifies the
              pointer to a variable to which the size of  the  region  of  the  return  value  is
              assigned.   If  successful,  the  return value is the pointer to the result object,
              else, it is `NULL'.  Because the region of the return value is allocated  with  the
              `malloc'  call,  it  should  be released with the `free' call if it is no longer in
              use.  This function is available only if QDBM was built with ZLIB enabled.

       The function `cbinflate' is used in order to decompress a serial  object  compressed  with
       ZLIB.

       char *cbinflate(const char *ptr, int size, int *sp);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              `sp' specifies the pointer to a variable to which the size of  the  region  of  the
              return  value  is  assigned.   If it is `NULL', it is not used.  If successful, the
              return value is the pointer to the result object, else, it is `NULL'.   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 character  string.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.  This function is available only if QDBM was
              built with ZLIB enabled.

       The function `cbgzencode' is used in order to compress a serial object with GZIP.

       char *cbgzencode(const char *ptr, int size, int *sp);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              If it is negative, the size is assigned with  `strlen(ptr)'.   `sp'  specifies  the
              pointer  to  a  variable  to  which  the  size of the region of the return value is
              assigned.  If successful, the return value is the pointer  to  the  result  object,
              else,  it  is `NULL'.  Because the region of the return value is allocated with the
              `malloc' call, it should be released with the `free' call if it  is  no  longer  in
              use.  This function is available only if QDBM was built with ZLIB enabled.

       The  function  `cbgzdecode' is used in order to decompress a serial object compressed with
       GZIP.

       char *cbgzdecode(const char *ptr, int size, int *sp);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              `sp'  specifies  the  pointer  to a variable to which the size of the region of the
              return value is assigned.  If it is `NULL', it is not  used.   If  successful,  the
              return  value  is the pointer to the result object, else, it is `NULL'.  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 character string.  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free' call if it is no longer in use.  This function is available only if QDBM was
              built with ZLIB enabled.

       The function `cbgetcrc' is used in order to get the CRC32 checksum of a serial object.

       unsigned int cbgetcrc(const char *ptr, int size);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it  is  negative, the size is assigned with `strlen(ptr)'.  The return value is
              the CRC32 checksum of the object.  This function is  available  only  if  QDBM  was
              built with ZLIB enabled.

       The function `cblzoencode' is used in order to compress a serial object with LZO.

       char *cblzoencode(const char *ptr, int size, int *sp);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              If it is negative, the size is assigned with  `strlen(ptr)'.   `sp'  specifies  the
              pointer  to  a  variable  to  which  the  size of the region of the return value is
              assigned.  If successful, the return value is the pointer  to  the  result  object,
              else,  it  is `NULL'.  Because the region of the return value is allocated with the
              `malloc' call, it should be released with the `free' call if it  is  no  longer  in
              use.  This function is available only if QDBM was built with LZO enabled.

       The  function `cblzodecode' is used in order to decompress a serial object compressed with
       LZO.

       char *cblzodecode(const char *ptr, int size, int *sp);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              `sp'  specifies  the  pointer  to a variable to which the size of the region of the
              return value is assigned.  If it is `NULL', it is not  used.   If  successful,  the
              return  value  is the pointer to the result object, else, it is `NULL'.  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 character string.  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free' call if it is no longer in use.  This function is available only if QDBM was
              built with LZO enabled.

       The function `cbbzencode' is used in order to compress a serial object with BZIP2.

       char *cbbzencode(const char *ptr, int size, int *sp);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it  is  negative,  the size is assigned with `strlen(ptr)'.  `sp' specifies the
              pointer to a variable to which the size of  the  region  of  the  return  value  is
              assigned.   If  successful,  the  return value is the pointer to the result object,
              else, it is `NULL'.  Because the region of the return value is allocated  with  the
              `malloc'  call,  it  should  be released with the `free' call if it is no longer in
              use.  This function is available only if QDBM was built with BZIP2 enabled.

       The function `cbbzdecode' is used in order to decompress a serial object  compressed  with
       BZIP2.

       char *cbbzdecode(const char *ptr, int size, int *sp);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              `sp' specifies the pointer to a variable to which the size of  the  region  of  the
              return  value  is  assigned.   If it is `NULL', it is not used.  If successful, the
              return value is the pointer to the result object, else, it is `NULL'.   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 character  string.   Because  the  region  of  the
              return  value  is  allocated with the `malloc' call, it should be released with the
              `free' call if it is no longer in use.  This function is available only if QDBM was
              built with BZIP2 enabled.

       The function `cbiconv' is used in order to convert the character encoding of a string.

       char  *cbiconv(const  char  *ptr, int size, const char *icode, const char *ocode, int *sp,
       int *mp);
              `ptr' specifies the pointer to a region.  `size' specifies the size of the  region.
              If  it is negative, the size is assigned with `strlen(ptr)'.  `icode' specifies the
              name of encoding of the input string.  `ocode' specifies the name  of  encoding  of
              the  output  string.  `sp' specifies the pointer to a variable to which the size of
              the region of the return value is assigned.  If it is `NULL', it is not used.  `mp'
              specifies  the  pointer  to a variable to which the number of missing characters by
              failure of conversion  is  assigned.   If  it  is  `NULL',  it  is  not  used.   If
              successful,  the  return  value  is  the  pointer to the result object, else, it is
              `NULL'.  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 character string.  Because
              the region of the return value is allocated with the `malloc' call,  it  should  be
              released  with  the  `free'  call  if  it  is  no  longer in use.  This function is
              available only if QDBM was built with ICONV enabled.

       The  function  `cbencname'  is  used  in  order  to  detect  the  encoding  of  a   string
       automatically.

       const char *cbencname(const char *ptr, int size);
              `ptr'  specifies the pointer to a region.  `size' specifies the size of the region.
              If it is negative, the size is assigned with `strlen(ptr)'.  The  return  value  is
              the  string  of  the  encoding  name  of  the  string.   As  it  stands,  US-ASCII,
              ISO-2022-JP, Shift_JIS, CP932, EUC-JP, UTF-8, UTF-16, UTF-16BE,  and  UTF-16LE  are
              supported.   If  none  of  them  matches, ISO-8859-1 is selected.  This function is
              available only if QDBM was built with ICONV enabled.

       The function `cbjetlag' is used in order to get the jet lag of the local time in seconds.

       int cbjetlag(void);
              The return value is the jet lag of the local time in seconds.

       The function `cbcalendar' is used in order to get the Gregorian calendar of a time.

       void cbcalendar(time_t t, int jl, int *yearp, int *monp, int *dayp, int *hourp, int *minp,
       int *secp);
              `t'  specifies  a  source  time.  If it is negative, the current time is specified.
              `jl' specifies the jet lag of a location in seconds.  `yearp' specifies the pointer
              to  a  variable  to  which  the year is assigned.  If it is `NULL', it is not used.
              `monp' specifies the pointer to a variable to which the month is assigned.   If  it
              is  `NULL',  it  is  not  used.   1  means  January  and 12 means December.  `dayp'
              specifies the pointer to a variable to which the day of the month is assigned.   If
              it is `NULL', it is not used.  `hourp' specifies the pointer to a variable to which
              the hours is assigned.  If it is `NULL', it is  not  used.   `minp'  specifies  the
              pointer to a variable to which the minutes is assigned.  If it is `NULL', it is not
              used.  `secp' specifies the pointer to a variable to which the seconds is assigned.
              If it is `NULL', it is not used.

       The function `cbdayofweek' is used in order to get the day of week of a date.

       int cbdayofweek(int year, int mon, int day);
              `year' specifies the year of a date.  `mon' specifies the month of the date.  `day'
              specifies the day of the date.  The return value is the day of week of the date.  0
              means Sunday and 6 means Saturday.

       The function `cbdatestrwww' is used in order to get the string for a date in W3CDTF.

       char *cbdatestrwww(time_t t, int jl);
              `t'  specifies  a  source  time.  If it is negative, the current time is specified.
              `jl' specifies the jet lag of a location in  seconds.   The  return  value  is  the
              string  of  the date in W3CDTF (YYYY-MM-DDThh:mm:ddTZD).  Because the region of the
              return value is allocated with the `malloc' call, it should be  released  with  the
              `free' call if it is no longer in use.

       The  function  `cbdatestrhttp'  is  used in order to get the string for a date in RFC 1123
       format.

       char *cbdatestrhttp(time_t t, int jl);
              `t' specifies a source time.  If it is negative, the  current  time  is  specified.
              `jl'  specifies  the  jet  lag  of  a location in seconds.  The return value is the
              string of the date in RFC 1123 format (Wdy, DD-Mon-YYYY hh:mm:dd TZD).  Because the
              region  of  the  return  value  is  allocated  with the `malloc' call, it should be
              released with the `free' call if it is no longer in use.

       The function `cbstrmktime' is used in order to get the time value  of  a  date  string  in
       decimal, hexadecimal, W3CDTF, or RFC 822 (1123).

       time_t cbstrmktime(const char *str);
              `str'  specifies  a date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123).
              The return value is the time value of the date or -1  if  the  format  is  invalid.
              Decimal can be trailed by "s" for in seconds, "m" for in minutes, "h" for in hours,
              and "d" for in days.

       The function `cbproctime' is used in order to get user and system processing times.

       void cbproctime(double *usrp, double *sysp);
              `usrp' specifies the pointer to a variable to which the  user  processing  time  is
              assigned.   If  it is `NULL', it is not used.  The unit of time is seconds.  `sysp'
              specifies the pointer to  a  variable  to  which  the  system  processing  time  is
              assigned.  If it is `NULL', it is not used.  The unit of time is seconds.

       The function `cbstdiobin' is used in order to ensure that the standard I/O is binary mode.

       void cbstdiobin(void);
              This function is useful for applications on dosish file systems.

       Functions  of  Cabin  except  for  `cbglobalgc' are thread-safe as long as a handle is not
       accessed by threads at the same time, on the assumption that `errno', `malloc', and so  on
       are thread-safe.

SEE ALSO

       qdbm(3), depot(3), curia(3), relic(3), hovel(3), villa(3), odeum(3), ndbm(3), gdbm(3)