


CABIN(3)              Quick Database Manager             CABIN(3)


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);




Man Page                    2004-04-22                          1





CABIN(3)              Quick Database Manager             CABIN(3)


       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);




Man Page                    2004-04-22                          2





CABIN(3)              Quick Database Manager             CABIN(3)


       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);



Man Page                    2004-04-22                          3





CABIN(3)              Quick Database Manager             CABIN(3)


       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);



Man Page                    2004-04-22                          4





CABIN(3)              Quick Database Manager             CABIN(3)


       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



Man Page                    2004-04-22                          5





CABIN(3)              Quick Database Manager             CABIN(3)


       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  func-
       tion 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  mem-
       ory.

       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 mem-
       ory.

       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



Man Page                    2004-04-22                          6





CABIN(3)              Quick Database Manager             CABIN(3)


              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 wrap-
              per 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 func-
              tion.  The two arguments specify the pointers of elements.   The
              comparing function should returns positive if the former is big,



Man Page                    2004-04-22                          7





CABIN(3)              Quick Database Manager             CABIN(3)


              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 func-
              tion.   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  func-
              tion.   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  func-
              tion.   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 sen-
              sitive to bias of input, quick sort is the fastest sorting algo-
              rithm.

       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.



Man Page                    2004-04-22                          8





CABIN(3)              Quick Database Manager             CABIN(3)


       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



Man Page                    2004-04-22                          9





CABIN(3)              Quick Database Manager             CABIN(3)


              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' speci-
              fies 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 con-
              tent.  If it is `NULL', an empty datum is created.  `size' spec-
              ifies  the  size  of the region.  If it is negative, the size is
              assigned with  `strlen(ptr)'.   The  return  value  is  a  datum



Man Page                    2004-04-22                         10





CABIN(3)              Quick Database Manager             CABIN(3)


              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 han-
              dle.

       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 out-
       put 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',



Man Page                    2004-04-22                         11





CABIN(3)              Quick Database Manager             CABIN(3)


              `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  addi-
              tional  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 orig-
              inal 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



Man Page                    2004-04-22                         12





CABIN(3)              Quick Database Manager             CABIN(3)


              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



Man Page                    2004-04-22                         13





CABIN(3)              Quick Database Manager             CABIN(3)


       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 ele-
              ments, 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 cor-
              responds, the former returns.

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



Man Page                    2004-04-22                         14





CABIN(3)              Quick Database Manager             CABIN(3)


       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 corre-
              sponding 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)'.



Man Page                    2004-04-22                         15





CABIN(3)              Quick Database Manager             CABIN(3)


              `over'  specifies  whether the value of the duplicated record is
              overwritten or not.  If `over' is false and the  key  is  dupli-
              cated, 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  corre-
              sponding 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.




Man Page                    2004-04-22                         16





CABIN(3)              Quick Database Manager             CABIN(3)


       The  function `cbmapiterinit' is used in order to initialize the itera-
       tor 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 con-
       tains all keys in a map.

       CBLIST *cbmapkeys(CBMAP *map);
              `map' specifies a map handle.  The return value is the list han-
              dle  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  con-
       tains all values in a map.





Man Page                    2004-04-22                         17





CABIN(3)              Quick Database Manager             CABIN(3)


       CBLIST *cbmapvals(CBMAP *map);
              `map' specifies a map handle.  The return value is the list han-
              dle 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 corre-
              sponding 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 pos-
              itive  if the former is big, negative if the latter is big, 0 if
              both are equal.  The return value is a heap handle.




Man Page                    2004-04-22                         18





CABIN(3)              Quick Database Manager             CABIN(3)


       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 maxi-
              mum 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



Man Page                    2004-04-22                         19





CABIN(3)              Quick Database Manager             CABIN(3)


       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' speci-
              fies 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 stan-
              dard  input is specified.  `sp' specifies the pointer to a vari-
              able 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



Man Page                    2004-04-22                         20





CABIN(3)              Quick Database Manager             CABIN(3)


              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  stan-
              dard  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 stan-
              dard 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  `cblist-
              close' 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  direc-
       tory and its sub ones recursively.



Man Page                    2004-04-22                         21





CABIN(3)              Quick Database Manager             CABIN(3)


       int cbremove(const char *name);
              `name' specifies the name of a file or a directory.  If success-
              ful, 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 ele-
       ments.

       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 infor-
              mation.  The key "path" specifies the path of the resource.  The
              key  "file"  specifies  the file name without the directory sec-
              tion.  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 loca-
              tion  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  allo-
              cated  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



Man Page                    2004-04-22                         22





CABIN(3)              Quick Database Manager             CABIN(3)


              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 allo-
              cated 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  allo-
              cated  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



Man Page                    2004-04-22                         23





CABIN(3)              Quick Database Manager             CABIN(3)


              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  "DISPO-
              SITION"  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  nega-
              tive, the size is assigned with `strlen(ptr)'.  `boundary' spec-
              ifies 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.



Man Page                    2004-04-22                         24





CABIN(3)              Quick Database Manager             CABIN(3)


       char *cbmimedecode(const char *str, char *enp);
              `str' specifies the pointer to an encoded string.  `enp'  speci-
              fies  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 char-
              acter  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.



Man Page                    2004-04-22                         25





CABIN(3)              Quick Database Manager             CABIN(3)


       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 char-
              acter  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 func-
              tion  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



Man Page                    2004-04-22                         26





CABIN(3)              Quick Database Manager             CABIN(3)


              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  avail-
              able 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  avail-
              able only if QDBM was built with ZLIB enabled.



Man Page                    2004-04-22                         27





CABIN(3)              Quick Database Manager             CABIN(3)


       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 avail-
              able 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.




Man Page                    2004-04-22                         28





CABIN(3)              Quick Database Manager             CABIN(3)


       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 avail-
              able only if QDBM was built with BZIP2 enabled.

       The function `cbiconv' is used in order to convert the character encod-
       ing 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.



Man Page                    2004-04-22                         29





CABIN(3)              Quick Database Manager             CABIN(3)


       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  calen-
       dar 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.




Man Page                    2004-04-22                         30





CABIN(3)              Quick Database Manager             CABIN(3)


       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 pro-
       cessing 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)























Man Page                    2004-04-22                         31


