Man Linux: Main Page and Category List

NAME

       tcutil - the utility API

DESCRIPTION

       The  utility  API  is  a  set  of  routines to handle records on memory
       easily.  Especially, extensible  string,  array  list,  hash  map,  and
       ordered tree are useful.

       To  use the utility API, include ‘tcutil.h’ and related standard header
       files.  Usually, write the following description near the  front  of  a
       source file.

              #include <tcutil.h>
              #include <stdlib.h>
              #include <time.h>
              #include <stdbool.h>
              #include <stdint.h>

       Objects  whose  type  is  pointer  to  ‘TCXSTR’ are used for extensible
       string.  An extensible string  object  is  created  with  the  function
       ‘tcxstrnew’  and  is  deleted  with  the function ‘tcxstrdel’.  Objects
       whose type is pointer to ‘TCLIST’ are used  for  array  list.   A  list
       object is created with the function ‘tclistnew’ and is deleted with the
       function ‘tclistdel’.  Objects whose type is  pointer  to  ‘TCMAP’  are
       used  for  hash  map.   A  map  object  is  created  with  the function
       ‘tcmapnew’ and is deleted with the function ‘tcmapdel’.  Objects  whose
       type  is  pointer to ‘TCTREE’ are used for ordered tree.  A tree object
       is created with the  function  ‘tctreenew’  and  is  deleted  with  the
       function  ‘tctreedel’.  To avoid memory leak, it is important to delete
       every object when it is no longer in use.

API OF BASIC UTILITIES

       The  constant  ‘tcversion’  is  the  string  containing   the   version
       information.

              extern const char *tcversion;

       The variable ‘tcfatalfunc’ is the pointer to the call back function for
       handling a fatal error.

              extern void (*tcfatalfunc)(const char *);
                     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  ‘tcmalloc’  is  used  in  order  to allocate a region on
       memory.

              void *tcmalloc(size_t size);size’ specifies the size of the region.
                     The return value is the pointer to the allocated  region.
                     This   function  handles  failure  of  memory  allocation
                     implicitly.  Because the region of the  return  value  is
                     allocated  with  the ‘malloc’ call, it should be released
                     with the ‘free’ call when it is no longer in use.

       The function ‘tccalloc’ is used in order to allocate a nullified region
       on memory.

              void *tccalloc(size_t nmemb, size_t size);nmemb’ specifies the number of elements.
                     ‘size’ specifies the size of each element.
                     The   return  value  is  the  pointer  to  the  allocated
                     nullified region.
                     This  function  handles  failure  of  memory   allocation
                     implicitly.   Because  the  region of the return value is
                     allocated with the ‘calloc’ call, it should  be  released
                     with the ‘free’ call when it is no longer in use.

       The  function  ‘tcrealloc’  is used in order to re-allocate a region on
       memory.

              void *tcrealloc(void *ptr, size_t size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value  is  the  pointer  to  the  re-allocated
                     region.
                     This   function  handles  failure  of  memory  allocation
                     implicitly.  Because the region of the  return  value  is
                     allocated  with the ‘realloc’ call, it should be released
                     with the ‘free’ call when it is no longer in use.

       The function ‘tcmemdup’ is used in  order  to  duplicate  a  region  on
       memory.

              void *tcmemdup(const void *ptr, size_t size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     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  when  it  is  no
                     longer in use.

       The  function  ‘tcstrdup’  is  used  in  order to duplicate a string on
       memory.

              char *tcstrdup(const void *str);str’ specifies the string.
                     The return value is the allocated  string  equivalent  to
                     the specified string.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The function ‘tcfree’ is used in order to free a region on memory.

              void tcfree(void *ptr);ptr’  specifies  the  pointer  to  the 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.

API OF EXTENSIBLE STRING

       The function ‘tcxstrnew’ is used  in  order  to  create  an  extensible
       string object.

              TCXSTR *tcxstrnew(void);
                     The return value is the new extensible string object.

       The  function  ‘tcxstrnew2’  is  used  in order to create an extensible
       string object from a character string.

              TCXSTR *tcxstrnew2(const char *str);str’ specifies the string of the initial content.
                     The return value is  the  new  extensible  string  object
                     containing the specified string.

       The  function  ‘tcxstrnew3’  is  used  in order to create an extensible
       string object with the initial allocation size.

              TCXSTR *tcxstrnew3(int asiz);asiz’ specifies the initial allocation size.
                     The return value is the new extensible string object.

       The function ‘tcxstrdup’ is used in order to copy an extensible  string
       object.

              TCXSTR *tcxstrdup(const TCXSTR *xstr);xstr’ specifies the extensible string object.
                     The  return  value  is  the  new extensible string object
                     equivalent to the specified object.

       The function ‘tcxstrdel’ is used  in  order  to  delete  an  extensible
       string object.

              void tcxstrdel(TCXSTR *xstr);xstr’ specifies the extensible string object.
                     Note  that the deleted object and its derivatives can not
                     be used anymore.

       The function ‘tcxstrcat’ is used in order to concatenate  a  region  to
       the end of an extensible string object.

              void tcxstrcat(TCXSTR *xstr, const void *ptr, int size);xstr’ specifies the extensible string object.
                     ‘ptr’ specifies the pointer to the region to be appended.
                     ‘size’ specifies the size of the region.

       The function ‘tcxstrcat2’ is used in order to concatenate  a  character
       string to the end of an extensible string object.

              void tcxstrcat2(TCXSTR *xstr, const char *str);xstr’ specifies the extensible string object.
                     ‘str’ specifies the string to be appended.

       The  function  ‘tcxstrptr’  is  used in order to get the pointer of the
       region of an extensible string object.

              const void *tcxstrptr(const TCXSTR *xstr);xstr’ specifies the extensible string object.
                     The return value is the pointer  of  the  region  of  the
                     object.
                     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  ‘tcxstrsize’  is  used  in  order to get the size of the
       region of an extensible string object.

              int tcxstrsize(const TCXSTR *xstr);xstr’ specifies the extensible string object.
                     The return value is the size of the region of the object.

       The  function  ‘tcxstrclear’  is  used  in order to clear an extensible
       string object.

              void tcxstrclear(TCXSTR *xstr);xstr’ specifies the extensible string object.
                     The internal buffer of the object is cleared and the size
                     is set zero.

       The  function  ‘tcxstrprintf’  is  used  in  order to perform formatted
       output into an extensible string object.

              void tcxstrprintf(TCXSTR *xstr, const char *format, ...);xstr’ specifies the extensible string object.
                     ‘format’ specifies the 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’, ‘@’, ‘?’, ‘b’, and ‘%’.  ‘@’ works as
                     with ‘s’ but escapes meta characters of XML.   ‘?’  works
                     as  with  ‘s’  but  escapes  meta characters of URL.  ‘b’
                     converts an integer to the string as binary numbers.  The
                     other conversion character work as with each original.
                     The  other  arguments  are  used  according to the format
                     string.

       The function ‘tcsprintf’ is used  in  order  to  allocate  a  formatted
       string on memory.

              char *tcsprintf(const char *format, ...);format’  specifies  the  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’, ‘@’, ‘?’, ‘b’, and ‘%’.  ‘@’ works as
                     with  ‘s’  but escapes meta characters of XML.  ‘?’ works
                     as with ‘s’ but escapes  meta  characters  of  URL.   ‘b’
                     converts an integer to the string as binary numbers.  The
                     other conversion character work as with each original.
                     The other arguments are  used  according  to  the  format
                     string.
                     The  return  value  is  the  pointer to the 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 when it is no longer in use.

API OF ARRAY LIST

       The function ‘tclistnew’ is used in order to create a list object.

              TCLIST *tclistnew(void);
                     The return value is the new list object.

       The function ‘tclistnew2’ is used in order to create a list object with
       expecting the number of elements.

              TCLIST *tclistnew2(int anum);anum’  specifies  the  number of elements expected to be
                     stored in the list.
                     The return value is the new list object.

       The function ‘tclistnew3’ is used in order to create a list object with
       initial string elements.

              TCLIST *tclistnew3(const char *str, ...);str’ specifies the string of the first element.
                     The  other  arguments are other elements.  They should be
                     trailed by a ‘NULL’ argument.
                     The return value is the new list object.

       The function ‘tclistdup’ is used in order to copy a list object.

              TCLIST *tclistdup(const TCLIST *list);list’ specifies the list object.
                     The return value is the new list object equivalent to the
                     specified object.

       The function ‘tclistdel’ is used in order to delete a list object.

              void tclistdel(TCLIST *list);list’ specifies the list object.
                     Note  that the deleted object and its derivatives can not
                     be used anymore.

       The function ‘tclistnum’ is used in order to get the number of elements
       of a list object.

              int tclistnum(const TCLIST *list);list’ specifies the list object.
                     The return value is the number of elements of the list.

       The  function  ‘tclistval’  is  used in order to get the pointer to the
       region of an element of a list object.

              const void *tclistval(const TCLIST *list, int index, int *sp);list’ specifies the list object.
                     ‘index’ specifies the index of the element.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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.  If ‘index’ is equal to or
                     more  than  the  number  of elements, the return value is
                     ‘NULL’.

       The function ‘tclistval2’ is used in order to  get  the  string  of  an
       element of a list object.

              const char *tclistval2(const TCLIST *list, int index);list’ specifies the list object.
                     ‘index’ specifies the index of the element.
                     The return value is the string of the value.
                     If  ‘index’  is  equal  to  or  more  than  the number of
                     elements, the return value is ‘NULL’.

       The function ‘tclistpush’ is used in order to add an element at the end
       of a list object.

              void tclistpush(TCLIST *list, const void *ptr, int size);list’ specifies the list object.
                     ‘ptr’  specifies  the  pointer  to  the region of the new
                     element.
                     ‘size’ specifies the size of the region.

       The function ‘tclistpush2’ is used in order to add a string element  at
       the end of a list object.

              void tclistpush2(TCLIST *list, const char *str);list’ specifies the list object.
                     ‘str’ specifies the string of the new element.

       The  function  ‘tclistpop’ is used in order to remove an element of the
       end of a list object.

              void *tclistpop(TCLIST *list, int *sp);list’ specifies the list object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     The  return  value  is  the  pointer to the region of the
                     removed 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.  Because the region of the
                     return  value  is  allocated  with  the ‘malloc’ call, it
                     should be released with the ‘free’ call  when  it  is  no
                     longer in use.  If the list is empty, the return value is
                     ‘NULL’.

       The function ‘tclistpop2’ is used in order to remove a  string  element
       of the end of a list object.

              char *tclistpop2(TCLIST *list);list’ specifies the list object.
                     The return value is the string of the removed element.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call  when it is no longer in use.  If the list is empty,
                     the return value is ‘NULL’.

       The function ‘tclistunshift’ is used in order to add an element at  the
       top of a list object.

              void tclistunshift(TCLIST *list, const void *ptr, int size);list’ specifies the list object.
                     ‘ptr’  specifies  the  pointer  to  the region of the new
                     element.
                     ‘size’ specifies the size of the region.

       The function ‘tclistunshift2’ is used in order to add a string  element
       at the top of a list object.

              void tclistunshift2(TCLIST *list, const char *str);list’ specifies the list object.
                     ‘str’ specifies the string of the new element.

       The function ‘tclistshift’ is used in order to remove an element of the
       top of a list object.

              void *tclistshift(TCLIST *list, int *sp);list’ specifies the list object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     The  return  value  is  the  pointer to the region of the
                     removed 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.  Because the region of the
                     return  value  is  allocated  with  the ‘malloc’ call, it
                     should be released with the ‘free’ call  when  it  is  no
                     longer in use.  If the list is empty, the return value is
                     ‘NULL’.

       The function ‘tclistshift2’ is used in order to remove a string element
       of the top of a list object.

              char *tclistshift2(TCLIST *list);list’ specifies the list object.
                     The return value is the string of the removed element.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call  when it is no longer in use.  If the list is empty,
                     the return value is ‘NULL’.

       The function ‘tclistinsert’ is used in order to add an element  at  the
       specified location of a list object.

              void  tclistinsert(TCLIST *list, int index, const void *ptr, int
              size);list’ specifies the list object.
                     ‘index’ specifies the index of the new element.
                     ‘ptr’ specifies the pointer to  the  region  of  the  new
                     element.
                     ‘size’ specifies the size of the region.
                     If  ‘index’  is  equal  to  or  more  than  the number of
                     elements, this function has no effect.

       The function ‘tclistinsert2’ is used in order to add a  string  element
       at the specified location of a list object.

              void tclistinsert2(TCLIST *list, int index, const char *str);list’ specifies the list object.
                     ‘index’ specifies the index of the new element.
                     ‘str’ specifies the string of the new element.
                     If  ‘index’  is  equal  to  or  more  than  the number of
                     elements, this function has no effect.

       The function ‘tclistremove’ is used in order to remove  an  element  at
       the specified location of a list object.

              void *tclistremove(TCLIST *list, int index, int *sp);list’ specifies the list object.
                     ‘index’ specifies the index of the element to be removed.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     The  return  value  is  the  pointer to the region of the
                     removed 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.  Because the region of the
                     return  value  is  allocated  with  the ‘malloc’ call, it
                     should be released with the ‘free’ call  when  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  ‘tclistremove2’  is  used  in  order  to remove a string
       element at the specified location of a list object.

              char *tclistremove2(TCLIST *list, int index);list’ specifies the list object.
                     ‘index’ specifies the index of the element to be removed.
                     The return value is the string of the removed element.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when 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  ‘tclistover’ is used in order to overwrite an element at
       the specified location of a list object.

              void tclistover(TCLIST *list, int index, const  void  *ptr,  int
              size);list’ specifies the list object.
                     ‘index’   specifies  the  index  of  the  element  to  be
                     overwritten.
                     ‘ptr’ specifies the pointer to  the  region  of  the  new
                     content.
                     ‘size’ specifies the size of the new content.
                     If  ‘index’  is  equal  to  or  more  than  the number of
                     elements, this function has no effect.

       The function ‘tclistover2’ is used  in  order  to  overwrite  a  string
       element at the specified location of a list object.

              void tclistover2(TCLIST *list, int index, const char *str);list’ specifies the list object.
                     ‘index’   specifies  the  index  of  the  element  to  be
                     overwritten.
                     ‘str’ specifies the string of the new content.
                     If ‘index’ is  equal  to  or  more  than  the  number  of
                     elements, this function has no effect.

       The  function  ‘tclistsort’ is used in order to sort elements of a list
       object in lexical order.

              void tclistsort(TCLIST *list);list’ specifies the list object.

       The function ‘tclistlsearch’ is used in order to search a  list  object
       for an element using liner search.

              int  tclistlsearch(const  TCLIST  *list,  const  void  *ptr, int
              size);list’ specifies the list object.
                     ‘ptr’ specifies the pointer to the region of the key.
                     ‘size’ specifies the size of the region.
                     The return value is the index of a corresponding  element
                     or -1 if there is no corresponding element.
                     If two or more elements correspond, the former returns.

       The  function  ‘tclistbsearch’ is used in order to search a list object
       for an element using binary search.

              int tclistbsearch(const  TCLIST  *list,  const  void  *ptr,  int
              size);list’ specifies the list object.  It should be sorted in
                     lexical order.
                     ‘ptr’ specifies the pointer to the region of the key.
                     ‘size’ specifies the size of the region.
                     The return value is the index of a corresponding  element
                     or -1 if there is no corresponding element.
                     If  two or more elements correspond, which returns is not
                     defined.

       The function ‘tclistclear’ is used in order to clear a list object.

              void tclistclear(TCLIST *list);list’ specifies the list object.
                     All elements are removed.

       The function ‘tclistdump’ is used in order to serialize a  list  object
       into a byte array.

              void *tclistdump(const TCLIST *list, int *sp);list’ specifies the list object.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The function ‘tclistload’ is used in order to create a list object from
       a serialized byte array.

              TCLIST *tclistload(const void *ptr, int size);ptr’ specifies the pointer to the region  of  serialized
                     byte array.
                     ‘size’ specifies the size of the region.
                     The return value is a new list object.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

API OF HASH MAP

       The function ‘tcmapnew’ is used in order to create a map object.

              TCMAP *tcmapnew(void);
                     The return value is the new map object.

       The  function  ‘tcmapnew2’ is used in order to create a map object with
       specifying the number of the buckets.

              TCMAP *tcmapnew2(uint32_t bnum);bnum’ specifies the number of the buckets.
                     The return value is the new map object.

       The function ‘tcmapnew3’ is used in order to create a map  object  with
       initial string elements.

              TCMAP *tcmapnew3(const char *str, ...);str’ specifies the string of the first element.
                     The  other  arguments are other elements.  They should be
                     trailed by a ‘NULL’ argument.
                     The return value is the new map object.
                     The key and the value of each  record  are  situated  one
                     after the other.

       The function ‘tcmapdup’ is used in order to copy a map object.

              TCMAP *tcmapdup(const TCMAP *map);map’ specifies the map object.
                     The  return value is the new map object equivalent to the
                     specified object.

       The function ‘tcmapdel’ is used in order to delete a map object.

              void tcmapdel(TCMAP *map);map’ specifies the map object.
                     Note that the deleted object and its derivatives can  not
                     be used anymore.

       The  function  ‘tcmapput’ is used in order to store a record into a map
       object.

              void tcmapput(TCMAP *map, const void *kbuf, int ksiz, const void
              *vbuf, int vsiz);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If a record with the same key exists in the  map,  it  is
                     overwritten.

       The function ‘tcmapput2’ is used in order to store a string record into
       a map object.

              void tcmapput2(TCMAP *map, const char *kstr, const char *vstr);map’ specifies the map object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If a record with the same key exists in the  map,  it  is
                     overwritten.

       The function ‘tcmapputkeep’ is used in order to store a new record into
       a map object.

              bool tcmapputkeep(TCMAP *map, const void *kbuf, int ksiz,  const
              void *vbuf, int vsiz);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If successful, the return value  is  true,  else,  it  is
                     false.
                     If  a  record  with  the same key exists in the map, this
                     function has no effect.

       The function ‘tcmapputkeep2’ is used in order to  store  a  new  string
       record into a map object.

              bool  tcmapputkeep2(TCMAP  *map,  const  char  *kstr, const char
              *vstr);map’ specifies the map object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If successful, the return value  is  true,  else,  it  is
                     false.
                     If  a  record  with  the same key exists in the map, this
                     function has no effect.

       The function ‘tcmapputcat’ is used in order to concatenate a  value  at
       the end of the value of the existing record in a map object.

              void  tcmapputcat(TCMAP  *map, const void *kbuf, int ksiz, const
              void *vbuf, int vsiz);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’ specifies the pointer to the region of the  value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If  there  is  no  corresponding  record, a new record is
                     created.

       The function ‘tcmapputcat2’ is used in order to  concatenate  a  string
       value at the end of the value of the existing record in a map object.

              void  tcmapputcat2(TCMAP  *map,  const  char  *kstr,  const char
              *vstr);map’ specifies the map object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If there is no corresponding  record,  a  new  record  is
                     created.

       The  function  ‘tcmapout’  is used in order to remove a record of a map
       object.

              bool tcmapout(TCMAP *map, const void *kbuf, int ksiz);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function ‘tcmapout2’ is used in order to remove a string record  of
       a map object.

              bool tcmapout2(TCMAP *map, const char *kstr);map’ specifies the map object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is  true.   False is
                     returned when no record corresponds to the specified key.

       The  function ‘tcmapget’ is used in order to retrieve a record in a map
       object.

              const void *tcmapget(const TCMAP *map,  const  void  *kbuf,  int
              ksiz, int *sp);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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 ‘tcmapget2’ is used in order to retrieve a  string  record
       in a map object.

              const char *tcmapget2(const TCMAP *map, const char *kstr);map’ specifies the map object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is the string of the
                     value of the corresponding record.   ‘NULL’  is  returned
                     when no record corresponds.

       The  function ‘tcmapmove’ is used in order to move a record to the edge
       of a map object.

              bool tcmapmove(TCMAP *map, const  void  *kbuf,  int  ksiz,  bool
              head);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of a key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘head’  specifies the destination which is the head if it
                     is true or the tail if else.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function ‘tcmapmove2’ is used in order to move a string  record  to
       the edge of a map object.

              bool tcmapmove2(TCMAP *map, const char *kstr, bool head);map’ specifies the map object.
                     ‘kstr’ specifies the string of a key.
                     ‘head’  specifies the destination which is the head if it
                     is true or the tail if else.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function  ‘tcmapiterinit’  is  used  in  order  to  initialize  the
       iterator of a map object.

              void tcmapiterinit(TCMAP *map);map’ specifies the map object.
                     The  iterator is used in order to access the key of every
                     record stored in the map object.

       The function ‘tcmapiternext’ is used in order to get the  next  key  of
       the iterator of a map object.

              const void *tcmapiternext(TCMAP *map, int *sp);map’ specifies the map object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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 can be fetched from 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 as the stored order.

       The function ‘tcmapiternext2’ is used in order  to  get  the  next  key
       string of the iterator of a map object.

              const char *tcmapiternext2(TCMAP *map);map’ specifies the map object.
                     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 can be fetched from the iterator.
                     The order of iteration is assured to be the same  as  the
                     stored order.

       The  function ‘tcmaprnum’ is used in order to get the number of records
       stored in a map object.

              uint64_t tcmaprnum(const TCMAP *map);map’ specifies the map object.
                     The return value is the number of the records  stored  in
                     the map object.

       The  function  ‘tcmapmsiz’  is  used  in order to get the total size of
       memory used in a map object.

              uint64_t tcmapmsiz(const TCMAP *map);map’ specifies the map object.
                     The return value is the total size of memory  used  in  a
                     map object.

       The  function  ‘tcmapkeys’  is  used  in  order to create a list object
       containing all keys in a map object.

              TCLIST *tcmapkeys(const TCMAP *map);map’ specifies the map object.
                     The return value is the new list  object  containing  all
                     keys in the map object.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function  ‘tcmapvals’  is  used  in  order to create a list object
       containing all values in a map object.

              TCLIST *tcmapvals(const TCMAP *map);map’ specifies the map object.
                     The return value is the new list  object  containing  all
                     values in the map object.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function  ‘tcmapaddint’  is  used  in order to add an integer to a
       record in a map object.

              int tcmapaddint(TCMAP *map, const  void  *kbuf,  int  ksiz,  int
              num);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If  the corresponding record exists, the value is treated
                     as an integer and is added to.  If no record corresponds,
                     a new record of the additional value is stored.

       The  function ‘tcmapadddouble’ is used in order to add a real number to
       a record in a map object.

              double tcmapadddouble(TCMAP *map, const void  *kbuf,  int  ksiz,
              double num);map’ specifies the map object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If  the corresponding record exists, the value is treated
                     as  a  real  number  and  is  added  to.   If  no  record
                     corresponds,  a  new  record  of  the additional value is
                     stored.

       The function ‘tcmapclear’ is used in order to clear a map object.

              void tcmapclear(TCMAP *map);map’ specifies the map object.
                     All records are removed.

       The function ‘tcmapcutfront’ is used in order to remove  front  records
       of a map object.

              void tcmapcutfront(TCMAP *map, int num);map’ specifies the map object.
                     ‘num’ specifies the number of records to be removed.

       The  function  ‘tcmapdump’  is  used in order to serialize a map object
       into a byte array.

              void *tcmapdump(const TCMAP *map, int *sp);map’ specifies the map object.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The function ‘tcmapload’ is used in order to create a map object from a
       serialized byte array.

              TCMAP *tcmapload(const void *ptr, int size);ptr’  specifies  the pointer to the region of serialized
                     byte array.
                     ‘size’ specifies the size of the region.
                     The return value is a new map object.
                     Because the object of the return value  is  created  with
                     the  function  ‘tcmapnew’,  it should be deleted with the
                     function ‘tcmapdel’ when it is no longer in use.

API OF ORDERED TREE

       The function ‘tctreenew’ is used in order to create a tree object.

              TCTREE *tctreenew(void);
                     The return value is the new tree object.

       The function ‘tctreenew2’ is used in order to create a tree object with
       specifying the custom comparison function.

              TCTREE *tctreenew2(TCCMP cmp, void *cmpop);cmp’  specifies  the  pointer  to  the custom comparison
                     function.   It  receives  five  parameters.   The   first
                     parameter  is  the pointer to the region of one key.  The
                     second parameter is the size of the region  of  one  key.
                     The  third  parameter is the pointer to the region of the
                     other key.  The fourth  parameter  is  the  size  of  the
                     region  of  the  other  key.   The fifth parameter is the
                     pointer  to  the  optional  opaque  object.   It  returns
                     positive  if the former is big, negative if the latter is
                     big, 0 if both are equivalent.
                     ‘cmpop’ specifies an arbitrary pointer to be given  as  a
                     parameter  of  the  comparison  function.   If  it is not
                     needed, ‘NULL’ can be specified.
                     The return value is the new tree object.
                     The default comparison  function  compares  keys  of  two
                     records  by  lexical order.  The functions ‘tccmplexical’
                     (dafault), ‘tccmpdecimal’, ‘tccmpint32’, and ‘tccmpint64’
                     are built-in.

       The function ‘tctreedup’ is used in order to copy a tree object.

              TCTREE *tctreedup(const TCTREE *tree);tree’ specifies the tree object.
                     The return value is the new tree object equivalent to the
                     specified object.

       The function ‘tctreedel’ is used in order to delete a tree object.

              void tctreedel(TCTREE *tree);
                     ‘tree’ specifies the tree object.
                     Note that the deleted object and its derivatives can  not
                     be used anymore.

       The function ‘tctreeput’ is used in order to store a record into a tree
       object.

              void tctreeput(TCTREE *tree, const void *kbuf, int  ksiz,  const
              void *vbuf, int vsiz);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If a record with the same key exists in the tree,  it  is
                     overwritten.

       The  function  ‘tctreeput2’  is  used in order to store a string record
       into a tree object.

              void tctreeput2(TCTREE  *tree,  const  char  *kstr,  const  char
              *vstr);tree’ specifies the tree object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If  a  record with the same key exists in the tree, it is
                     overwritten.

       The function ‘tctreeputkeep’ is used in order to  store  a  new  record
       into a tree object.

              bool  tctreeputkeep(TCTREE  *tree,  const  void *kbuf, int ksiz,
              const void *vbuf, int vsiz);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’ specifies the pointer to the region of the  value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If  successful,  the  return  value  is true, else, it is
                     false.
                     If a record with the same key exists in  the  tree,  this
                     function has no effect.

       The  function  ‘tctreeputkeep2’  is used in order to store a new string
       record into a tree object.

              bool tctreeputkeep2(TCTREE *tree, const char *kstr,  const  char
              *vstr);tree’ specifies the tree object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If  successful,  the  return  value  is true, else, it is
                     false.
                     If a record with the same key exists in  the  tree,  this
                     function has no effect.

       The  function ‘tctreeputcat’ is used in order to concatenate a value at
       the end of the value of the existing record in a tree object.

              void tctreeputcat(TCTREE *tree,  const  void  *kbuf,  int  ksiz,
              const void *vbuf, int vsiz);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If there is no corresponding  record,  a  new  record  is
                     created.

       The  function  ‘tctreeputcat2’ is used in order to concatenate a string
       value at the end of the value of the existing record in a tree  object.

              void  tctreeputcat2(TCTREE  *tree,  const char *kstr, const char
              *vstr);tree’ specifies the tree object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If there is no corresponding  record,  a  new  record  is
                     created.

       The  function ‘tctreeout’ is used in order to remove a record of a tree
       object.

              bool tctreeout(TCTREE *tree, const void *kbuf, int ksiz);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function ‘tctreeout2’ is used in order to remove a string record of
       a tree object.

              bool tctreeout2(TCTREE *tree, const char *kstr);tree’ specifies the tree object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is  true.   False is
                     returned when no record corresponds to the specified key.

       The  function  ‘tctreeget’  is  used in order to retrieve a record in a
       tree object.

              const void *tctreeget(TCTREE *tree, const void *kbuf, int  ksiz,
              int *sp);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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 ‘tctreeget2’ is used in order to retrieve a string  record
       in a tree object.

              const char *tctreeget2(TCTREE *tree, const char *kstr);tree’ specifies the tree object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is the string of the
                     value of the corresponding record.   ‘NULL’  is  returned
                     when no record corresponds.

       The  function  ‘tctreeiterinit’  is  used  in  order  to initialize the
       iterator of a tree object.

              void tctreeiterinit(TCTREE *tree);tree’ specifies the tree object.
                     The iterator is used in order to access the key of  every
                     record stored in the tree object.

       The  function  ‘tctreeiternext’ is used in order to get the next key of
       the iterator of a tree object.

              const void *tctreeiternext(TCTREE *tree, int *sp);tree’ specifies the tree object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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 can be fetched from 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 ascending of the keys.

       The  function  ‘tctreeiternext2’  is  used in order to get the next key
       string of the iterator of a tree object.

              const char *tctreeiternext2(TCTREE *tree);tree’ specifies the tree object.
                     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 can be fetched from the iterator.
                     The  order of iteration is assured to be ascending of the
                     keys.

       The function ‘tctreernum’ is used in order to get the number of records
       stored in a tree object.

              uint64_t tctreernum(const TCTREE *tree);tree’ specifies the tree object.
                     The  return  value is the number of the records stored in
                     the tree object.

       The function ‘tctreemsiz’ is used in order to get  the  total  size  of
       memory used in a tree object.

              uint64_t tctreemsiz(const TCTREE *tree);tree’ specifies the tree object.
                     The  return  value  is the total size of memory used in a
                     tree object.

       The function ‘tctreekeys’ is used in order  to  create  a  list  object
       containing all keys in a tree object.

              TCLIST *tctreekeys(const TCTREE *tree);tree’ specifies the tree object.
                     The  return  value  is the new list object containing all
                     keys in the tree object.
                     Because the object of the return value  is  created  with
                     the  function  ‘tclistnew’, it should be deleted with the
                     function ‘tclistdel’ when it is no longer in use.

       The function ‘tctreevals’ is used in order  to  create  a  list  object
       containing all values in a tree object.

              TCLIST *tctreevals(const TCTREE *tree);tree’ specifies the tree object.
                     The  return  value  is the new list object containing all
                     values in the tree object.
                     Because the object of the return value  is  created  with
                     the  function  ‘tclistnew’, it should be deleted with the
                     function ‘tclistdel’ when it is no longer in use.

       The function ‘tctreeaddint’ is used in order to add  an  integer  to  a
       record in a tree object.

              int  tctreeaddint(TCTREE  *tree, const void *kbuf, int ksiz, int
              num);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is  treated
                     as an integer and is added to.  If no record corresponds,
                     a new record of the additional value is stored.

       The function ‘tctreeadddouble’ is used in order to add a real number to
       a record in a tree object.

              double tctreeadddouble(TCTREE *tree, const void *kbuf, int ksiz,
              double num);tree’ specifies the tree object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is  treated
                     as  a  real  number  and  is  added  to.   If  no  record
                     corresponds, a new record  of  the  additional  value  is
                     stored.

       The function ‘tctreeclear’ is used in order to clear a tree object.

              void tctreeclear(TCTREE *tree);tree’ specifies the tree object.
                     All records are removed.

       The  function  ‘tctreecutfringe’  is  used  in  order  to remove fringe
       records of a tree object.

              void tctreecutfringe(TCTREE *tree, int num);tree’ specifies the tree object.
                     ‘num’ specifies the number of records to be removed.

       The function ‘tctreedump’ is used in order to serialize a  tree  object
       into a byte array.

              void *tctreedump(const TCTREE *tree, int *sp);tree’ specifies the tree object.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The function ‘tctreeload’ is used in order to create a tree object from
       a serialized byte array.

              TCTREE *tctreeload(const void *ptr, int size,  TCCMP  cmp,  void
              *cmpop);ptr’  specifies  the pointer to the region of serialized
                     byte array.
                     ‘size’ specifies the size of the region.
                     ‘cmp’ specifies the  pointer  to  the  custom  comparison
                     function.
                     ‘cmpop’  specifies  an arbitrary pointer to be given as a
                     parameter of the comparison function.
                     If it is not needed, ‘NULL’ can be specified.
                     The return value is a new tree object.
                     Because the object of the return value  is  created  with
                     the  function  ‘tctreenew’, it should be deleted with the
                     function ‘tctreedel’ when it is no longer in use.

API OF ON-MEMORY HASH DATABASE

       The function ‘tcmdbnew’ is used in order to create  an  on-memory  hash
       database object.

              TCMDB *tcmdbnew(void);
                     The  return  value  is  the  new  on-memory hash database
                     object.
                     The object can be shared by plural threads because of the
                     internal mutex.

       The  function  ‘tcmdbnew2’ is used in order to create an on-memory hash
       database object with specifying the number of the buckets.

              TCMDB *tcmdbnew2(uint32_t bnum);bnum’ specifies the number of the buckets.
                     The return value  is  the  new  on-memory  hash  database
                     object.
                     The object can be shared by plural threads because of the
                     internal mutex.

       The function ‘tcmdbdel’ is used in order to delete  an  on-memory  hash
       database object.

              void tcmdbdel(TCMDB *mdb);mdb’ specifies the on-memory hash database object.

       The  function  ‘tcmdbput’  is  used  in order to store a record into an
       on-memory hash database object.

              void tcmdbput(TCMDB *mdb, const void *kbuf, int ksiz, const void
              *vbuf, int vsiz);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If a record with the same key exists in the database,  it
                     is overwritten.

       The function ‘tcmdbput2’ is used in order to store a string record into
       an on-memory hash database object.

              void tcmdbput2(TCMDB *mdb, const char *kstr, const char *vstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If a record with the same key exists in the database,  it
                     is overwritten.

       The function ‘tcmdbputkeep’ is used in order to store a new record into
       an on-memory hash database object.

              bool tcmdbputkeep(TCMDB *mdb, const void *kbuf, int ksiz,  const
              void *vbuf, int vsiz);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If successful, the return value  is  true,  else,  it  is
                     false.
                     If  a  record  with  the same key exists in the database,
                     this function has no effect.

       The function ‘tcmdbputkeep2’ is used in order to  store  a  new  string
       record into an on-memory hash database object.

              bool  tcmdbputkeep2(TCMDB  *mdb,  const  char  *kstr, const char
              *vstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If successful, the return value  is  true,  else,  it  is
                     false.
                     If  a  record  with  the same key exists in the database,
                     this function has no effect.

       The function ‘tcmdbputcat’ is used in order to concatenate a  value  at
       the end of the existing record in an on-memory hash database.

              void  tcmdbputcat(TCMDB  *mdb, const void *kbuf, int ksiz, const
              void *vbuf, int vsiz);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’ specifies the pointer to the region of the  value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If  there  is  no  corresponding  record, a new record is
                     created.

       The function ‘tcmdbputcat2’ is used in order to concatenate a string at
       the end of the existing record in an on-memory hash database.

              void  tcmdbputcat2(TCMDB  *mdb,  const  char  *kstr,  const char
              *vstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If there is no corresponding  record,  a  new  record  is
                     created.

       The  function  ‘tcmdbout’  is  used  in  order to remove a record of an
       on-memory hash database object.

              bool tcmdbout(TCMDB *mdb, const void *kbuf, int ksiz);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function ‘tcmdbout2’ is used in order to remove a string record  of
       an on-memory hash database object.

              bool tcmdbout2(TCMDB *mdb, const char *kstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is  true.   False is
                     returned when no record corresponds to the specified key.

       The  function  ‘tcmdbget’  is  used in order to retrieve a record in an
       on-memory hash database object.

              void *tcmdbget(TCMDB *mdb, const void *kbuf, int ksiz, int *sp);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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.  Because the region of the
                     return  value  is  allocated  with  the ‘malloc’ call, it
                     should be released with the ‘free’ call  when  it  is  no
                     longer in use.

       The  function  ‘tcmdbget2’ is used in order to retrieve a string record
       in an on-memory hash database object.

              char *tcmdbget2(TCMDB *mdb, const char *kstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     If successful, the return value  is  the  string  of  the
                     value  of  the  corresponding record.  ‘NULL’ is returned
                     when no record corresponds.
                     Because the region of the return value is allocated  with
                     the  ‘malloc’ call, it should be released with the ‘free’
                     call when it is no longer in use.

       The function ‘tcmdbvsiz’ is used in order to get the size of the  value
       of a record in an on-memory hash database object.

              int tcmdbvsiz(TCMDB *mdb, const void *kbuf, int ksiz);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If  successful, the return value is the size of the value
                     of the corresponding record, else, it is -1.

       The function ‘tcmdbvsiz2’ is used in order to get the size of the value
       of a string record in an on-memory hash database object.

              int tcmdbvsiz2(TCMDB *mdb, const char *kstr);mdb’ specifies the on-memory hash database object.
                     ‘kstr’ specifies the string of the key.
                     If  successful, the return value is the size of the value
                     of the corresponding record, else, it is -1.

       The function  ‘tcmdbiterinit’  is  used  in  order  to  initialize  the
       iterator of an on-memory hash database object.

              void tcmdbiterinit(TCMDB *mdb);mdb’ specifies the on-memory hash database object.
                     The  iterator is used in order to access the key of every
                     record stored in the on-memory hash database.

       The function ‘tcmdbiternext’ is used in order to get the  next  key  of
       the iterator of an on-memory hash database object.

              void *tcmdbiternext(TCMDB *mdb, int *sp);mdb’ specifies the on-memory hash database object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return
                     value is assigned.
                     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 can be fetched from 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.  Because the region of the
                     return value is allocated  with  the  ‘malloc’  call,  it
                     should  be  released  with  the ‘free’ call when it is no
                     longer in use.  The order of iteration is assured  to  be
                     the same as the stored order.

       The  function  ‘tcmdbiternext2’  is  used  in order to get the next key
       string of the iterator of an on-memory hash database object.

              char *tcmdbiternext2(TCMDB *mdb);mdb’ specifies the on-memory hash database object.
                     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 can be fetched from the iterator.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.  The order of iteration
                     is assured to be the same as the stored order.

       The function ‘tcmdbfwmkeys’ is used in order to  get  forward  matching
       keys in an on-memory hash database object.

              TCLIST *tcmdbfwmkeys(TCMDB *mdb, const void *pbuf, int psiz, int
              max);mdb’ specifies the on-memory hash database object.
                     ‘pbuf’ specifies the pointer to the region of the prefix.
                     ‘psiz’ specifies the size of the region of the prefix.
                     ‘max’ specifies the maximum number of keys to be fetched.
                     If it is negative, no limit is specified.
                     The return value is a list object  of  the  corresponding
                     keys.   This  function  does  never  fail.  It returns an
                     empty list even if no key corresponds.
                     Because the object of the return value  is  created  with
                     the  function  ‘tclistnew’, it should be deleted with the
                     function ‘tclistdel’ when it is no longer in  use.   Note
                     that  this function may be very slow because every key in
                     the database is scanned.

       The function ‘tcmdbfwmkeys2’ is used in order to get  forward  matching
       string keys in an on-memory hash database object.

              TCLIST *tcmdbfwmkeys2(TCMDB *mdb, const char *pstr, int max);mdb’ specifies the on-memory hash database object.
                     ‘pstr’ specifies the string of the prefix.
                     ‘max’ specifies the maximum number of keys to be fetched.
                     If it is negative, no limit is specified.
                     The return value is a list object  of  the  corresponding
                     keys.   This  function  does  never  fail.  It returns an
                     empty list even if no key corresponds.
                     Because the object of the return value  is  created  with
                     the  function  ‘tclistnew’, it should be deleted with the
                     function ‘tclistdel’ when it is no longer in  use.   Note
                     that  this function may be very slow because every key in
                     the database is scanned.

       The function ‘tcmdbrnum’ is used in order to get the number of  records
       stored in an on-memory hash database object.

              uint64_t tcmdbrnum(TCMDB *mdb);mdb’ specifies the on-memory hash database object.
                     The  return  value is the number of the records stored in
                     the database.

       The function ‘tcmdbmsiz’ is used in order to  get  the  total  size  of
       memory used in an on-memory hash database object.

              uint64_t tcmdbmsiz(TCMDB *mdb);mdb’ specifies the on-memory hash database object.
                     The  return value is the total size of memory used in the
                     database.

       The function ‘tcmdbaddint’ is used in order to  add  an  integer  to  a
       record in an on-memory hash database object.

              int  tcmdbaddint(TCMDB  *mdb,  const  void  *kbuf, int ksiz, int
              num);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is  treated
                     as an integer and is added to.  If no record corresponds,
                     a new record of the additional value is stored.

       The function ‘tcmdbadddouble’ is used in order to add a real number  to
       a record in an on-memory hash database object.

              double  tcmdbadddouble(TCMDB  *mdb,  const void *kbuf, int ksiz,
              double num);mdb’ specifies the on-memory hash database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If the corresponding record exists, the value is  treated
                     as  a  real  number  and  is  added  to.   If  no  record
                     corresponds, a new record  of  the  additional  value  is
                     stored.

       The  function ‘tcmdbvanish’ is used in order to clear an on-memory hash
       database object.

              void tcmdbvanish(TCMDB *mdb);mdb’ specifies the on-memory hash database object.
                     All records are removed.

       The function ‘tcmdbcutfront’ is used in order to remove  front  records
       of an on-memory hash database object.

              void tcmdbcutfront(TCMDB *mdb, int num);mdb’ specifies the on-memory hash database object.
                     ‘num’ specifies the number of records to be removed.

API OF ON-MEMORY TREE DATABASE

       The  function  ‘tcndbnew’  is used in order to create an on-memory tree
       database object.

              TCNDB *tcndbnew(void);
                     The return value  is  the  new  on-memory  tree  database
                     object.
                     The object can be shared by plural threads because of the
                     internal mutex.

       The function ‘tcndbnew2’ is used in order to create an  on-memory  tree
       database object with specifying the custom comparison function.

              TCNDB *tcndbnew2(TCCMP cmp, void *cmpop);cmp’  specifies  the  pointer  to  the custom comparison
                     function.
                     ‘cmpop’ specifies an arbitrary pointer to be given  as  a
                     parameter  of  the  comparison  function.   If  it is not
                     needed, ‘NULL’ can be specified.
                     The return value  is  the  new  on-memory  tree  database
                     object.
                     The  default  comparison  function  compares  keys of two
                     records by lexical order.  The  functions  ‘tccmplexical’
                     (dafault), ‘tccmpdecimal’, ‘tccmpint32’, and ‘tccmpint64’
                     are built-in.  The object can be shared by plural threads
                     because of the internal mutex.

       The  function  ‘tcndbdel’  is used in order to delete an on-memory tree
       database object.

              void tcndbdel(TCNDB *ndb);ndb’ specifies the on-memory tree database object.

       The function ‘tcndbput’ is used in order to  store  a  record  into  an
       on-memory tree database object.

              void tcndbput(TCNDB *ndb, const void *kbuf, int ksiz, const void
              *vbuf, int vsiz);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’ specifies the pointer to the region of the  value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If  a record with the same key exists in the database, it
                     is overwritten.

       The function ‘tcndbput2’ is used in order to store a string record into
       an on-memory tree database object.

              void tcndbput2(TCNDB *ndb, const char *kstr, const char *vstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If  a record with the same key exists in the database, it
                     is overwritten.

       The function ‘tcndbputkeep’ is used in order to store a new record into
       an on-memory tree database object.

              bool  tcndbputkeep(TCNDB *ndb, const void *kbuf, int ksiz, const
              void *vbuf, int vsiz);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’ specifies the pointer to the region of the  value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If  successful,  the  return  value  is true, else, it is
                     false.
                     If a record with the same key  exists  in  the  database,
                     this function has no effect.

       The  function  ‘tcndbputkeep2’  is  used in order to store a new string
       record into an on-memory tree database object.

              bool tcndbputkeep2(TCNDB *ndb,  const  char  *kstr,  const  char
              *vstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If  successful,  the  return  value  is true, else, it is
                     false.
                     If a record with the same key  exists  in  the  database,
                     this function has no effect.

       The  function  ‘tcndbputcat’ is used in order to concatenate a value at
       the end of the existing record in an on-memory tree database.

              void tcndbputcat(TCNDB *ndb, const void *kbuf, int  ksiz,  const
              void *vbuf, int vsiz);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘vbuf’  specifies the pointer to the region of the value.
                     ‘vsiz’ specifies the size of the region of the value.
                     If there is no corresponding  record,  a  new  record  is
                     created.

       The function ‘tcndbputcat2’ is used in order to concatenate a string at
       the end of the existing record in an on-memory tree database.

              void tcndbputcat2(TCNDB  *ndb,  const  char  *kstr,  const  char
              *vstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     ‘vstr’ specifies the string of the value.
                     If  there  is  no  corresponding  record, a new record is
                     created.

       The function ‘tcndbout’ is used in order  to  remove  a  record  of  an
       on-memory tree database object.

              bool tcndbout(TCNDB *ndb, const void *kbuf, int ksiz);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If  successful,  the  return  value  is  true.   False is
                     returned when no record corresponds to the specified key.

       The  function ‘tcndbout2’ is used in order to remove a string record of
       an on-memory tree database object.

              bool tcndbout2(TCNDB *ndb, const char *kstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     If successful,  the  return  value  is  true.   False  is
                     returned when no record corresponds to the specified key.

       The function ‘tcndbget’ is used in order to retrieve  a  record  in  an
       on-memory tree database object.

              void *tcndbget(TCNDB *ndb, const void *kbuf, int ksiz, int *sp);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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.  Because the region of the
                     return value is allocated  with  the  ‘malloc’  call,  it
                     should  be  released  with  the ‘free’ call when it is no
                     longer in use.

       The function ‘tcndbget2’ is used in order to retrieve a  string  record
       in an on-memory tree database object.

              char *tcndbget2(TCNDB *ndb, const char *kstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     If  successful,  the  return  value  is the string of the
                     value of the corresponding record.   ‘NULL’  is  returned
                     when no record corresponds.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The  function ‘tcndbvsiz’ is used in order to get the size of the value
       of a record in an on-memory tree database object.

              int tcndbvsiz(TCNDB *ndb, const void *kbuf, int ksiz);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     If successful, the return value is the size of the  value
                     of the corresponding record, else, it is -1.

       The function ‘tcndbvsiz2’ is used in order to get the size of the value
       of a string record in an on-memory tree database object.

              int tcndbvsiz2(TCNDB *ndb, const char *kstr);ndb’ specifies the on-memory tree database object.
                     ‘kstr’ specifies the string of the key.
                     If successful, the return value is the size of the  value
                     of the corresponding record, else, it is -1.

       The  function  ‘tcndbiterinit’  is  used  in  order  to  initialize the
       iterator of an on-memory tree database object.

              void tcndbiterinit(TCNDB *ndb);ndb’ specifies the on-memory tree database object.
                     The iterator is used in order to access the key of  every
                     record stored in the on-memory database.

       The  function  ‘tcndbiternext’  is used in order to get the next key of
       the iterator of an on-memory tree database object.

              void *tcndbiternext(TCNDB *ndb, int *sp);ndb’ specifies the on-memory tree database object.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     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 can be fetched from 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.  Because the region of the
                     return  value  is  allocated  with  the ‘malloc’ call, it
                     should be released with the ‘free’ call  when  it  is  no
                     longer  in  use.  The order of iteration is assured to be
                     the same as the stored order.

       The function ‘tcndbiternext2’ is used in order  to  get  the  next  key
       string of the iterator of an on-memory tree database object.

              char *tcndbiternext2(TCNDB *ndb);ndb’ specifies the on-memory tree database object.
                     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 can be fetched from the iterator.
                     Because the region of the return value is allocated  with
                     the  ‘malloc’ call, it should be released with the ‘free’
                     call when it is no longer in use.  The order of iteration
                     is assured to be the same as the stored order.

       The  function  ‘tcndbfwmkeys’  is used in order to get forward matching
       keys in an on-memory tree database object.

              TCLIST *tcndbfwmkeys(TCNDB *ndb, const void *pbuf, int psiz, int
              max);ndb’ specifies the on-memory tree database object.
                     ‘pbuf’ specifies the pointer to the region of the prefix.
                     ‘psiz’ specifies the size of the region of the prefix.
                     ‘max’ specifies the maximum number of keys to be fetched.
                     If it is negative, no limit is specified.
                     The  return  value  is a list object of the corresponding
                     keys.  This function does  never  fail.   It  returns  an
                     empty list even if no key corresponds.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function  ‘tcndbfwmkeys2’ is used in order to get forward matching
       string keys in an on-memory tree database object.

              TCLIST *tcndbfwmkeys2(TCNDB *ndb, const char *pstr, int max);ndb’ specifies the on-memory tree database object.
                     ‘pstr’ specifies the string of the prefix.
                     ‘max’ specifies the maximum number of keys to be fetched.
                     If it is negative, no limit is specified.
                     The  return  value  is a list object of the corresponding
                     keys.  This function does  never  fail.   It  returns  an
                     empty list even if no key corresponds.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function ‘tcndbrnum’ is used in order to get the number of records
       stored in an on-memory tree database object.

              uint64_t tcndbrnum(TCNDB *ndb);ndb’ specifies the on-memory tree database object.
                     The return value is the number of the records  stored  in
                     the database.

       The  function  ‘tcndbmsiz’  is  used  in order to get the total size of
       memory used in an on-memory tree database object.

              uint64_t tcndbmsiz(TCNDB *ndb);ndb’ specifies the on-memory tree database object.
                     The return value is the total size of memory used in  the
                     database.

       The  function  ‘tcndbaddint’  is  used  in order to add an integer to a
       record in an on-memory tree database object.

              int tcndbaddint(TCNDB *ndb, const  void  *kbuf,  int  ksiz,  int
              num);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If  the corresponding record exists, the value is treated
                     as an integer and is added to.  If no record corresponds,
                     a new record of the additional value is stored.

       The  function ‘tcndbadddouble’ is used in order to add a real number to
       a record in an on-memory tree database object.

              double tcndbadddouble(TCNDB *ndb, const void  *kbuf,  int  ksiz,
              double num);ndb’ specifies the on-memory tree database object.
                     ‘kbuf’ specifies the pointer to the region of the key.
                     ‘ksiz’ specifies the size of the region of the key.
                     ‘num’ specifies the additional value.
                     The return value is the summation value.
                     If  the corresponding record exists, the value is treated
                     as  a  real  number  and  is  added  to.   If  no  record
                     corresponds,  a  new  record  of  the additional value is
                     stored.

       The function ‘tcndbvanish’ is used in order to clear an on-memory  tree
       database object.

              void tcndbvanish(TCNDB *ndb);ndb’ specifies the on-memory tree database object.
                     All records are removed.

       The function ‘tcndbcutfringe’ is used in order to remove fringe records
       of an on-memory tree database object.

              void tcndbcutfringe(TCNDB *ndb, int num);ndb’ specifies the on-memory tree database object.
                     ‘num’ specifies the number of records to be removed.

API OF MEMORY POOL

       The function ‘tcmpoolnew’ is used in order  to  create  a  memory  pool
       object.

              TCMPOOL *tcmpoolnew(void);
                     The return value is the new memory pool object.

       The  function  ‘tcmpooldel’  is  used  in order to delete a memory pool
       object.

              void tcmpooldel(TCMPOOL *mpool);mpool’ specifies the memory pool object.
                     Note that the deleted object and its derivatives can  not
                     be used anymore.

       The  function  ‘tcmpoolpush’  is used in order to relegate an arbitrary
       object to a memory pool object.

              void *tcmpoolpush(TCMPOOL *mpool, void  *ptr,  void  (*del)(void
              *));mpool’ specifies the memory pool object.
                     ‘ptr’   specifies   the  pointer  to  the  object  to  be
                     relegated.  If it is ‘NULL’, this function has no effect.
                     ‘del’ specifies the pointer to the function to delete the
                     object.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  object  is
                     deleted when the memory pool object is deleted.

       The function ‘tcmpoolpushptr’ is used in order to relegate an allocated
       region to a memory pool object.

              void *tcmpoolpushptr(TCMPOOL *mpool, void *ptr);mpool’ specifies the memory pool object.
                     ‘ptr’  specifies  the  pointer  to  the  region   to   be
                     relegated.  If it is ‘NULL’, this function has no effect.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  region  is
                     released when the memory pool object is deleted.

       The  function  ‘tcmpoolpushxstr’  is  used  in  order  to  relegate  an
       extensible string object to a memory pool object.

              TCXSTR *tcmpoolpushxstr(TCMPOOL *mpool, TCXSTR *xstr);mpool’ specifies the memory pool object.
                     ‘xstr’ specifies the extensible string object.  If it  is
                     ‘NULL’, this function has no effect.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  object  is
                     deleted when the memory pool object is deleted.

       The function ‘tcmpoolpushlist’ is used in  order  to  relegate  a  list
       object to a memory pool object.

              TCLIST *tcmpoolpushlist(TCMPOOL *mpool, TCLIST *list);mpool’ specifies the memory pool object.
                     ‘list’  specifies the list object.  If it is ‘NULL’, this
                     function has no effect.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  object  is
                     deleted when the memory pool object is deleted.

       The function ‘tcmpoolpushmap’ is used in order to relegate a map object
       to a memory pool object.

              TCMAP *tcmpoolpushmap(TCMPOOL *mpool, TCMAP *map);mpool’ specifies the memory pool object.
                     ‘map’ specifies the map object.  If it  is  ‘NULL’,  this
                     function has no effect.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  object  is
                     deleted when the memory pool object is deleted.

       The function ‘tcmpoolpushtree’ is used in  order  to  relegate  a  tree
       object to a memory pool object.

              TCTREE *tcmpoolpushtree(TCMPOOL *mpool, TCTREE *tree);mpool’ specifies the memory pool object.
                     ‘tree’  specifies the tree object.  If it is ‘NULL’, this
                     function has no effect.
                     The return value is the pointer to the given object.
                     This  function  assures  that  the  specified  object  is
                     deleted when the memory pool object is deleted.

       The  function  ‘tcmpoolmalloc’  is  used  in order to allocate a region
       relegated to a memory pool object.

              void *tcmpoolmalloc(TCMPOOL *mpool, size_t size);mpool’ specifies the memory pool object.
                     The return value is the pointer to the  allocated  region
                     under the memory pool.

       The  function ‘tcmpoolxstrnew’ is used in order to create an extensible
       string object relegated to a memory pool object.

              TCXSTR *tcmpoolxstrnew(TCMPOOL *mpool);
                     The return value is  the  new  extensible  string  object
                     under the memory pool.

       The  function ‘tcmpoollistnew’ is used in order to create a list object
       relegated to a memory pool object.

              TCLIST *tcmpoollistnew(TCMPOOL *mpool);
                     The return value is the new list object under the  memory
                     pool.

       The  function  ‘tcmpoolmapnew’  is used in order to create a map object
       relegated to a memory pool object.

              TCMAP *tcmpoolmapnew(TCMPOOL *mpool);
                     The return value is the new map object under  the  memory
                     pool.

       The  function ‘tcmpooltreenew’ is used in order to create a tree object
       relegated to a memory pool object.

              TCTREE *tcmpooltreenew(TCMPOOL *mpool);
                     The return value is the new tree object under the  memory
                     pool.

       The  function ‘tcmpoolpop’ is used in order to remove the most recently
       installed cleanup handler.

              void tcmpoolpop(TCMPOOL *mpool, bool exe);mpool’ specifies the memory pool object.
                     ‘exe’ specifies whether to execute the destructor of  the
                     removed handler.

       The  function ‘tcmpoolglobal’ is used in order to get the global memory
       pool object.

              TCMPOOL *tcmpoolglobal(void);
                     The return value is the global memory pool object.
                     The global memory pool object is a singleton and  assured
                     to be deleted when the process is terminating normally.

API OF MISCELLANEOUS UTILITIES

       The  function  ‘tclmax’ is used in order to get the larger value of two
       integers.

              long tclmax(long a, long b);a’ specifies an integer.
                     ‘b’ specifies the other integer.
                     The return value is the larger value of the two.

       The function ‘tclmin’ is used in order to get the lesser value  of  two
       integers.

              long tclmin(long a, long b);a’ specifies an integer.
                     ‘b’ specifies the other integer.
                     The return value is the lesser value of the two.

       The  function ‘tclrand’ is used in order to get a random number as long
       integer based on uniform distribution.

              unsigned long tclrand(void);
                     The return value is  the  random  number  between  0  and
                     ‘ULONG_MAX’.
                     This  function  uses  the random number source device and
                     generates a real random number if possible.

       The function ‘tcdrand’ is used in order  to  get  a  random  number  as
       double decimal based on uniform distribution.

              double tcdrand(void);
                     The return value is the random number equal to or greater
                     than 0, and less than 1.0.
                     This function uses the random number  source  device  and
                     generates a real random number if possible.

       The  function  ‘tcdrandnd’  is  used in order to get a random number as
       double decimal based on normal distribution.

              double tcdrandnd(double avg, double sd);avg’ specifies the average.
                     ‘sd’ specifies the standard deviation.
                     The return value is the random number.
                     This function uses the random number  source  device  and
                     generates a real random number if possible.

       The  function  ‘tcstricmp’ is used in order to compare two strings with
       case insensitive evaluation.

              int tcstricmp(const char *astr, const char *bstr);astr’ specifies a string.
                     ‘bstr’ specifies 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.

       The function ‘tcstrfwm’ is used in order  to  check  whether  a  string
       begins with a key.

              bool tcstrfwm(const char *str, const char *key);str’ specifies the target string.
                     ‘key’ specifies the forward matching key string.
                     The return value is true if the target string begins with
                     the key, else, it is false.

       The function ‘tcstrifwm’ is used in order to  check  whether  a  string
       begins with a key with case insensitive evaluation.

              bool tcstrifwm(const char *str, const char *key);str’ specifies the target string.
                     ‘key’ specifies the forward matching key string.
                     The return value is true if the target string begins with
                     the key, else, it is false.

       The function ‘tcstrbwm’ is used in order to check whether a string ends
       with a key.

              bool tcstrbwm(const char *str, const char *key);str’ specifies the target string.
                     ‘key’ specifies the backward matching key string.
                     The  return  value is true if the target string ends with
                     the key, else, it is false.

       The function ‘tcstribwm’ is used in order to  check  whether  a  string
       ends with a key with case insensitive evaluation.

              bool tcstribwm(const char *str, const char *key);str’ specifies the target string.
                     ‘key’ specifies the backward matching key string.
                     The  return  value is true if the target string ends with
                     the key, else, it is false.

       The function ‘tcstrdist’  is  used  in  order  to  calculate  the  edit
       distance of two strings.

              int tcstrdist(const char *astr, const char *bstr);astr’ specifies a string.
                     ‘bstr’ specifies of the other string.
                     The  return  value is the edit distance which is known as
                     the Levenshtein distance.   The  cost  is  calculated  by
                     byte.

       The  function  ‘tcstrdistutf’  is  used  in order to calculate the edit
       distance of two UTF-8 strings.

              int tcstrdistutf(const char *astr, const char *bstr);astr’ specifies a string.
                     ‘bstr’ specifies of the other string.
                     The return value is the edit distance which is  known  as
                     the  Levenshtein  distance.   The  cost  is calculated by
                     Unicode character.

       The function ‘tcstrtoupper’ is used in order to convert the letters  of
       a string into upper case.

              char *tcstrtoupper(char *str);str’ specifies the string to be converted.
                     The return value is the string itself.

       The  function ‘tcstrtolower’ is used in order to convert the letters of
       a string into lower case.

              char *tcstrtolower(char *str);str’ specifies the string to be converted.
                     The return value is the string itself.

       The function ‘tcstrtrim’ is used in order to cut  space  characters  at
       head or tail of a string.

              char *tcstrtrim(char *str);str’ specifies the string to be converted.
                     The return value is the string itself.

       The function ‘tcstrsqzspc’ is used in order to squeeze space characters
       in a string and trim it.

              char *tcstrsqzspc(char *str);str’ specifies the string to be converted.
                     The return value is the string itself.

       The function ‘tcstrsubchr’ is used in order to substitute characters in
       a string.

              char  *tcstrsubchr(char  *str,  const  char  *rstr,  const  char
              *sstr);str’ specifies the string to be converted.
                     ‘rstr’ specifies the string containing characters  to  be
                     replaced.
                     ‘sstr’  specifies  the string containing characters to be
                     substituted.
                     If the substitute string is shorter then the  replacement
                     string, corresponding characters are removed.

       The  function  ‘tcstrcntutf’  is  used  in order to count the number of
       characters in a string of UTF-8.

              int tcstrcntutf(const char *str);str’ specifies the string of UTF-8.
                     The return value is  the  number  of  characters  in  the
                     string.

       The function ‘tcstrcututf’ is used in order to cut a string of UTF-8 at
       the specified number of characters.

              char *tcstrcututf(char *str, int num);str’ specifies the string of UTF-8.
                     ‘num’ specifies the number of characters to be kept.
                     The return value is the string itself.

       The function ‘tcstrutftoucs’ is used in order to convert a UTF-8 string
       into a UCS-2 array.

              void tcstrutftoucs(const char *str, uint16_t *ary, int *np);str’ specifies the UTF-8 string.
                     ‘ary’  specifies the pointer to the region into which the
                     result UCS-2 codes are written.  The size of  the  buffer
                     should be sufficient.
                     ‘np’  specifies  the pointer to a variable into which the
                     number of elements of the result array is assigned.

       The function ‘tcstrucstoutf’ is used in order to convert a UCS-2  array
       into a UTF-8 string.

              int tcstrucstoutf(const uint16_t *ary, int num, char *str);ary’ specifies the array of UCS-2 codes.
                     ‘num’ specifies the number of the array.
                     ‘str’  specifies the pointer to the region into which the
                     result UTF-8 string is written.  The size of  the  buffer
                     should be sufficient.
                     The return value is the length of the result string.

       The  function  ‘tcstrsplit’ is used in order to create a list object by
       splitting a string.

              TCLIST *tcstrsplit(const char *str, const char *delims);str’ specifies the source string.
                     ‘delims’  specifies  a   string   containing   delimiting
                     characters.
                     The  return value is a list object of the split elements.
                     If two delimiters are successive, it is assumed  that  an
                     empty  element is between the two.  Because the object of
                     the  return  value   is   created   with   the   function
                     ‘tclistnew’,  it  should  be  deleted  with  the function
                     ‘tclistdel’ when it is no longer in use.

       The function ‘tcstrjoin’ is used in order to create a string by joining
       all elements of a list object.

              char *tcstrjoin(const TCLIST *list, char delim);list’ specifies a list object.
                     ‘delim’ specifies a delimiting character.
                     The return value is the result string.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The  function  ‘tcatoi’  is  used  in  order  to convert a string to an
       integer.

              int64_t tcatoi(const char *str);str’ specifies the string.
                     The return value is the integer.  If the string does  not
                     contain numeric expression, 0 is returned.
                     This  function  is  equivalent  to ‘atoll’ except that it
                     does not depend on the locale.

       The function ‘tcatoix’ is used in order to  convert  a  string  with  a
       metric prefix to an integer.

              int64_t tcatoix(const char *str);str’  specifies  the  string,  which can be trailed by a
                     binary metric prefix.  "K", "M", "G", "T", "P",  and  "E"
                     are supported.  They are case-insensitive.
                     The  return value is the integer.  If the string does not
                     contain  numeric  expression,  0  is  returned.   If  the
                     integer  overflows the domain, ‘INT64_MAX’ or ‘INT64_MIN’
                     is returned according to the sign.

       The function ‘tcatof’ is used in order to convert a string  to  a  real
       number.

              double tcatof(const char *str);str’ specifies the string.
                     The  return value is the real number.  If the string does
                     not contain numeric expression, 0.0 is returned.
                     This function is equivalent to ‘atof’ except that it does
                     not depend on the locale.

       The  function ‘tcregexmatch’ is used in order to check whether a string
       matches a regular expression.

              bool tcregexmatch(const char *str, const char *regex);str’ specifies the target string.
                     ‘regex’ specifies the regular expression string.   If  it
                     begins  with  ‘*’,  the  trailing  substring is used as a
                     case-insensitive regular expression.
                     The return value is true if matching is success, else, it
                     is false.

       The  function  ‘tcregexreplace’  is  used  in  order  to  replace  each
       substring matching a regular expression string.

              char *tcregexreplace(const char *str, const char  *regex,  const
              char *alt);str’ specifies the target string.
                     ‘regex’  specifies  the  regular  expression  string  for
                     substrings.   If  it  begins  with  ‘*’,   the   trailing
                     substring   is   used   as   a  case-insensitive  regular
                     expression.
                     ‘alt’ specifies the alternative string  with  which  each
                     substrings  is  replaced.   Each  ‘&’  in  the  string is
                     replaced with the matched  substring.   Each  ‘´  in  the
                     string  escapes the following character.  Special escapes
                     "1" through "9" referring to the  corresponding  matching
                     sub-expressions  in  the  regular  expression  string are
                     supported.
                     The return value is a new converted string.  Even if  the
                     regular  expression  is  invalid,  a copy of the original
                     string is returned.
                     Because the region of the return value is allocated  with
                     the  ‘malloc’ call, it should be released with the ‘free’
                     call when it is no longer in use.

       The function ‘tcmd5hash’ is used in order to get the MD5 hash value  of
       a serial object.

              void tcmd5hash(const void *ptr, int size, char *buf);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘buf’  specifies the pointer to the region into which the
                     result string is written.  The size of the buffer  should
                     be equal to or more than 48 bytes.

       The  function  ‘tcarccipher’  is  used in order to cipher or decipher a
       serial object with the Arcfour stream cipher.

              void tcarccipher(const void *ptr, int size,  const  void  *kbuf,
              int ksiz, void *obuf);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘kbuf’  specifies the pointer to the region of the cipher
                     key.
                     ‘ksiz’ specifies the size of the  region  of  the  cipher
                     key.
                     ‘obuf’ specifies the pointer to the region into which the
                     result data is written.  The size of the buffer should be
                     equal to or more than the input region.

       The  function  ‘tctime’  is  used  in  order  to get the time of day in
       seconds.

              double tctime(void);
                     The return value is the time  of  day  in  seconds.   The
                     accuracy is in microseconds.

       The  function  ‘tccalendar’  is  used  in  order  to  get the Gregorian
       calendar of a time.

              void tccalendar(int64_t t, int jl, int *yearp,  int  *monp,  int
              *dayp, int *hourp, int *minp, int *secp);t’  specifies the source time in seconds from the epoch.
                     If it is ‘INT64_MAX’, the current time is specified.
                     ‘jl’ specifies the jet lag of a location in seconds.   If
                     it is ‘INT_MAX’, the local jet lag is specified.
                     ‘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  ‘tcdatestrwww’  is  used  in order to format a date as a
       string in W3CDTF.

              void tcdatestrwww(int64_t t, int jl, char *buf);t’ specifies the source time in seconds from the  epoch.
                     If it is ‘INT64_MAX’, the current time is specified.
                     ‘jl’  specifies the jet lag of a location in seconds.  If
                     it is ‘INT_MAX’, the local jet lag is specified.
                     ‘buf’ specifies the pointer to the region into which  the
                     result  string is written.  The size of the buffer should
                     be equal to or more than 48 bytes.
                     W3CDTF represents a date as "YYYY-MM-DDThh:mm:ddTZD".

       The function ‘tcdatestrhttp’ is used in order to format  a  date  as  a
       string in RFC 1123 format.

              void tcdatestrhttp(int64_t t, int jl, char *buf);t’  specifies the source time in seconds from the epoch.
                     If it is ‘INT64_MAX’, the current time is specified.
                     ‘jl’ specifies the jet lag of a location in seconds.   If
                     it is ‘INT_MAX’, the local jet lag is specified.
                     ‘buf’  specifies the pointer to the region into which the
                     result string is written.  The size of the buffer  should
                     be equal to or more than 48 bytes.
                     RFC  1123  format  represents a date as "Wdy, DD-Mon-YYYY
                     hh:mm:dd TZD".

       The function ‘tcstrmktime’ is used in order to get the time value of  a
       date string.

              int64_t tcstrmktime(const char *str);str’  specifies the date string in decimal, hexadecimal,
                     W3CDTF, or RFC 822 (1123).  Decimal can be trailed by "s"
                     for in seconds, "m" for in minutes, "h" for in hours, and
                     "d" for in days.
                     The return value  is  the  time  value  of  the  date  or
                     ‘INT64_MIN’ if the format is invalid.

       The  function  ‘tcjetlag’  is  used  in order to get the jet lag of the
       local time.

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

       The function ‘tcdayofweek’ is used in order to get the day of week of a
       date.

              int tcdayofweek(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.

API OF FILESYSTEM UTILITIES

       The  function  ‘tcrealpath’  is  used in order to get the canonicalized
       absolute path of a file.

              char *tcrealpath(const char *path);path’ specifies the path of the file.
                     The return value is the canonicalized absolute path of  a
                     file, or ‘NULL’ if the path is invalid.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The   function  ‘tcstatfile’  is  used  in  order  to  get  the  status
       information of a file.

              bool tcstatfile(const char *path, bool *isdirp, int64_t  *sizep,
              int64_t *mtimep);path’ specifies the path of the file.
                     ‘isdirp’  specifies  the pointer to a variable into which
                     whether the file is a directory is assigned.   If  it  is
                     ‘NULL’, it is ignored.
                     ‘sizep’  specifies  the  pointer to a variable into which
                     the size of the file is assigned.  If it is ‘NULL’, it is
                     ignored.
                     ‘ntimep’  specifies  the pointer to a variable into which
                     the size of the file is assigned.  If it is ‘NULL’, it is
                     ignored.
                     If  successful,  the  return  value  is true, else, it is
                     false.

       The function ‘tcreadfile’ is used in order to  read  whole  data  of  a
       file.

              void *tcreadfile(const char *path, int limit, int *sp);path’  specifies the path of the file.  If it is ‘NULL’,
                     the standard input is specified.
                     ‘limit’ specifies the limiting size of reading data.   If
                     it is not more than 0, the limitation is not specified.
                     ‘sp’ specifies the pointer to the variable into 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, or ‘NULL’ if  the  file  could  not  be
                     opened.
                     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 when when is no
                     longer in use.

       The function ‘tcreadfilelines’ is used in order to read every line of a
       file.

              TCLIST *tcreadfilelines(const char *path);path’  specifies the path of the file.  If it is ‘NULL’,
                     the standard input is specified.
                     The return value is a  list  object  of  every  lines  if
                     successful, else it is ‘NULL’.
                     Line  separators  are cut out.  Because the object of the
                     return value is created with the function ‘tclistnew’, it
                     should  be  deleted with the function ‘tclistdel’ when it
                     is no longer in use.

       The function ‘tcwritefile’ is used in order to write data into a  file.

              bool tcwritefile(const char *path, const void *ptr, int size);path’  specifies the path of the file.  If it is ‘NULL’,
                     the standard output is specified.
                     ‘ptr’ specifies the pointer to the data region.
                     ‘size’ specifies the size of the region.
                     If successful, the return value  is  true,  else,  it  is
                     false.

       The function ‘tccopyfile’ is used in order to copy a file.

              bool tccopyfile(const char *src, const char *dest);src’ specifies the path of the source file.
                     ‘dest’ specifies the path of the destination file.
                     The  return  value  is  true  if  successful, else, it is
                     false.
                     If the destination file exists, it is overwritten.

       The function ‘tcreaddir’ is used in order to read names of files  in  a
       directory.

              TCLIST *tcreaddir(const char *path);path’ specifies the path of the directory.
                     The return value is a list object of names if successful,
                     else it is ‘NULL’.
                     Links to the directory itself and to the parent directory
                     are ignored.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function  ‘tcglobpat’  is used in order to expand a pattern into a
       list of matched paths.

              TCLIST *tcglobpat(const char *pattern);pattern’ specifies the matching pattern.
                     The return value is a list object of matched  paths.   If
                     no path is matched, an empty list is returned.
                     Because  the  object  of the return value is created with
                     the function ‘tclistnew’, it should be deleted  with  the
                     function ‘tclistdel’ when it is no longer in use.

       The  function  ‘tcremovelink’  is  used  in order to remove a file or a
       directory and its sub ones recursively.

              bool tcremovelink(const char *path);path’ specifies the path of the link.
                     If successful, the return value  is  true,  else,  it  is
                     false.  False is returned when the link does not exist or
                     the permission is denied.

       The function ‘tcwrite’ is used in order to write data into a file.

              bool tcwrite(int fd, const void *buf, size_t size);fd’ specifies the file descriptor.
                     ‘buf’ specifies the buffer to be written.
                     ‘size’ specifies the size of the buffer.
                     The return value is  true  if  successful,  else,  it  is
                     false.

       The function ‘tcread’ is used in order to read data from a file.

              bool tcread(int fd, void *buf, size_t size);fd’ specifies the file descriptor.
                     ‘buf’ specifies the buffer to store into.
                     ‘size’ specifies the size of the buffer.
                     The  return  value  is  true  if  successful, else, it is
                     false.

       The function ‘tclock’ is used in order to lock a file.

              bool tclock(int fd, bool ex, bool nb);fd’ specifies the file descriptor.
                     ‘ex’ specifies whether an exclusive lock or a shared lock
                     is performed.
                     ‘nb’ specifies whether to request with non-blocking.
                     The  return  value  is  true  if  successful, else, it is
                     false.

       The function ‘tcunlock’ is used in order to unlock a file.

              bool tcunlock(int fd);fd’ specifies the file descriptor.
                     The return value is  true  if  successful,  else,  it  is
                     false.

       The function ‘tcsystem’ is used in order to execute a shell command.

              int tcsystem(const char **args, int anum);args’  specifies  an  array  of the command name and its
                     arguments.
                     ‘anum’ specifies the number of elements of the array.
                     The return value is the  exit  code  of  the  command  or
                     ‘INT_MAX’ on failure.
                     The  command  name  and the arguments are quoted and meta
                     characters are escaped.

API OF ENCODING UTILITIES

       The function ‘tcurlencode’ is used in order to encode a  serial  object
       with URL encoding.

              char *tcurlencode(const char *ptr, int size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value is 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 when is no longer in use.

       The  function ‘tcurldecode’ is used in order to decode a string encoded
       with URL encoding.

              char *tcurldecode(const char *str, int *sp);str’ specifies the encoded string.
                     ‘sp’ specifies the pointer to a variable into  which  the
                     size of the region of the return value is assigned.
                     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  when  it  is  no
                     longer in use.

       The  function  ‘tcurlbreak’  is  used  in  order to break up a URL into
       elements.

              TCMAP *tcurlbreak(const char *str);str’ specifies the URL string.
                     The return value is the map object  whose  keys  are  the
                     name  of  elements.   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
                     object  of  the return value is created with the function
                     ‘tcmapnew’,  it  should  be  deleted  with  the  function
                     ‘tcmapdel’ when it is no longer in use.

       The  function ‘tcurlresolve’ is used in order to resolve a relative URL
       with an absolute URL.

              char *tcurlresolve(const char *base, const char *target);base’ specifies the absolute URL of the base location.
                     ‘target’ specifies the URL to be resolved.
                     The return value is the 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 when it is no longer in use.

       The  function ‘tcbaseencode’ is used in order to encode a serial object
       with Base64 encoding.

              char *tcbaseencode(const char *ptr, int size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value is 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 when is no longer in use.

       The function ‘tcbasedecode’ is used in order to decode a string encoded
       with Base64 encoding.

              char *tcbasedecode(const char *str, int *sp);str’ specifies the encoded string.
                     ‘sp’  specifies  the pointer to a variable into which the
                     size of the region of the return value is assigned.
                     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 when it is no
                     longer in use.

       The function ‘tcquoteencode’ is used in order to encode a serial object
       with Quoted-printable encoding.

              char *tcquoteencode(const char *ptr, int size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value is 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 when is no longer in use.

       The  function  ‘tcquotedecode’  is  used  in  order  to decode a string
       encoded with Quoted-printable encoding.

              char *tcquotedecode(const char *str, int *sp);str’ specifies the encoded string.
                     ‘sp’ specifies the pointer to a variable into  which  the
                     size of the region of the return value is assigned.
                     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  when  it  is  no
                     longer in use.

       The  function  ‘tcmimeencode’  is used in order to encode a string with
       MIME encoding.

              char *tcmimeencode(const char *str, const  char  *encname,  bool
              base);str’ specifies the string.
                     ‘encname’  specifies  the  string  of  the  name  of  the
                     character encoding.
                     ‘base’ specifies whether to use Base64 encoding.   If  it
                     is false, Quoted-printable is used.
                     The return value is the result string.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The function ‘tcmimedecode’ is used in order to decode a string encoded
       with MIME encoding.

              char *tcmimedecode(const char *str, char *enp);str’ specifies the encoded string.
                     ‘enp’ specifies the pointer to the 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 result string.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call when it is no longer in use.

       The  function  ‘tcmimebreak’ is used in order to split a string of MIME
       into headers and the body.

              char *tcmimebreak(const char *ptr, int size, TCMAP *headers, int
              *sp);ptr’ specifies the pointer to the region of MIME data.
                     ‘size’ specifies the size of the region.
                     ‘headers’ specifies a map object to store headers.  If it
                     is ‘NULL’, it is not used.  Each key of  the  map  is  an
                     uncapitalized header name.
                     ‘sp’ specifies the pointer to the variable into which the
                     size of the region of the return value is assigned.
                     The return value is the pointer to the region of the body
                     data.
                     If  the  content  type is defined, the header 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 when it is no longer in use.

       The function ‘tcmimeparts’ is used in order to split multipart data  of
       MIME into its parts.

              TCLIST  *tcmimeparts(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.
                     ‘boundary’ specifies the boundary string.
                     The  return  value is a list object.  Each element of the
                     list is the data of a part.
                     Because the object of the return value  is  created  with
                     the  function  ‘tclistnew’, it should be deleted with the
                     function ‘tclistdel’ when it is no longer in use.

       The function ‘tchexencode’ is used in order to encode a  serial  object
       with hexadecimal encoding.

              char *tchexencode(const char *ptr, int size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value is 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 when is no longer in use.

       The  function ‘tchexdecode’ is used in order to decode a string encoded
       with hexadecimal encoding.

              char *tchexdecode(const char *str, int *sp);str’ specifies the encoded string.
                     ‘sp’ specifies the pointer to a variable into  which  the
                     size of the region of the return
                     value is assigned.
                     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  when  it  is  no
                     longer in use.

       The  function  ‘tcpackencode’  is  used  in  order to compress a serial
       object with Packbits encoding.

              char *tcpackencode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The function ‘tcpackdecode’ is used in order  to  decompress  a  serial
       object compressed with Packbits encoding.

              char *tcpackdecode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’  specifies  the pointer to a variable into 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 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 when it is no
                     longer in use.

       The function ‘tcbsencode’ is used in order to compress a serial  object
       with TCBS encoding.

              char *tcbsencode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The  function  ‘tcbsdecode’  is  used  in  order to decompress a serial
       object compressed with TCBS encoding.

              char *tcbsdecode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to a variable into  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 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  when  it  is  no
                     longer in use.

       The  function  ‘tcdeflate’ is used in order to compress a serial object
       with Deflate encoding.

              char *tcdeflate(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The function ‘tcinflate’ is used in order to decompress a serial object
       compressed with Deflate encoding.

              char *tcinflate(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’  specifies  the pointer to a variable into 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 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 when it is no
                     longer in use.

       The function ‘tcgzipencode’ is used  in  order  to  compress  a  serial
       object with GZIP encoding.

              char *tcgzipencode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The  function  ‘tcgzipdecode’  is  used in order to decompress a serial
       object compressed with GZIP encoding.

              char *tcgzipdecode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to a variable into  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 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  when  it  is  no
                     longer in use.

       The function ‘tcgetcrc’ is used in order to get the CRC32 checksum of a
       serial object.

              unsigned int tcgetcrc(const char *ptr, int size);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     The return value is the CRC32 checksum of the object.

       The function ‘tcbzipencode’ is used  in  order  to  compress  a  serial
       object with BZIP2 encoding.

              char *tcbzipencode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to the variable into 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 when it is no longer in use.

       The  function  ‘tcbzipdecode’  is  used in order to decompress a serial
       object compressed with BZIP2 encoding.

              char *tcbzipdecode(const char *ptr, int size, int *sp);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘sp’ specifies the pointer to a variable into  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 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  when  it  is  no
                     longer in use.

       The  function  ‘tcberencode’  is  used  in  order to encode an array of
       nonnegative integers with BER encoding.

              char *tcberencode(const unsigned int *ary, int anum, int *sp);ary’ specifies the pointer to the array  of  nonnegative
                     integers.
                     ‘anum’ specifies the size of the array.
                     ‘sp’  specifies  the pointer to a variable into which the
                     size of the region of the return value is assigned.
                     The return value is the pointer  to  the  region  of  the
                     result.
                     Because  the region of the return value is allocated with
                     the ‘malloc’ call, it should be released with the  ‘free’
                     call if when is no longer in use.

       The  function  ‘tcberdecode’ is used in order to decode a serial object
       encoded with BER encoding.

              unsigned int *tcberdecode(const char *ptr, int size, int *np);ptr’ specifies the pointer to the region.
                     ‘size’ specifies the size of the region.
                     ‘np’ specifies the pointer to a variable into  which  the
                     number of elements of the return value is assigned.
                     The  return  value  is  the  pointer  to the array of the
                     result.
                     Because the region of the return value is allocated  with
                     the  ‘malloc’ call, it should be released with the ‘free’
                     call if when is no longer in use.

       The function ‘tcxmlescape’ is used in order to escape  meta  characters
       in a string with the entity references of XML.

              char *tcxmlescape(const char *str);str’ specifies the string.
                     The return value is the pointer to the escaped string.
                     This  function  escapes  only  ‘&’,  ‘<’,  ‘>’,  and ‘"’.
                     Because the region of the return value is allocated  with
                     the  ‘malloc’ call, it should be released with the ‘free’
                     call when it is no longer in use.

       The function ‘tcxmlunescape’  is  used  in  order  to  unescape  entity
       references in a string of XML.

              char *tcxmlunescape(const char *str);str’ specifies the string.
                     The return value is 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 when it is no longer in use.

SEE ALSO

       tcutest(1), tcucodec(1), tokyocabinet(3)