Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TCUTIL(3)			 Tokyo Cabinet			     TCUTIL(3)

NAME
       tcutil -	the utility API

DESCRIPTION
       The  utility  API is a set of routines to handle	records	on memory eas-
       ily.  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  ob-
       ject  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 `tcmap-
       new' 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 ob-
       ject when it is no longer in use.

API OF BASIC UTILITIES
       The constant `tcversion'	is the string containing the version  informa-
       tion.

	      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 al-
		     location is failed.

       The  function  `tcmalloc' is used in order to allocate a	region on mem-
       ory.

	      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  im-
		     plicitly.	 Because the region of the return value	is al-
		     located 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	nulli-
		     fied region.
		     This  function  handles  failure of memory	allocation im-
		     plicitly.	Because	the region of the return value is  al-
		     located  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 re-
		     gion.
		     This function handles failure of  memory  allocation  im-
		     plicitly.	 Because the region of the return value	is al-
		     located 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 mem-
       ory.

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

	      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 con-
		     taining 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 re-
       gion 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  ob-
		     ject.
		     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 re-
       gion 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  out-
       put 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 char-
		     acters  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'  con-
		     verts  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 char-
		     acters 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' con-
		     verts 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  re-
		     sult 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 re-
       gion 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 ele-
       ment 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  ele-
		     ments, 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 ele-
		     ment.
		     `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  re-
		     moved 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 ele-
		     ment.
		     `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  re-
		     moved 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 ele-
		     ment.
		     `size' specifies the size of the region.
		     If	`index'	is equal to or more than the  number  of  ele-
		     ments, 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  ele-
		     ments, 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 re-
		     moved 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 ele-
       ment 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 re-
		     moved 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	 over-
		     written.
		     `ptr' specifies the pointer to the	region of the new con-
		     tent.
		     `size' specifies the size of the new content.
		     If	`index'	is equal to or more than the  number  of  ele-
		     ments, this function has no effect.

       The  function `tclistover2' is used in order to overwrite a string ele-
       ment 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	 over-
		     written.
		     `str' specifies the string	of the new content.
		     If	 `index'  is  equal to or more than the	number of ele-
		     ments, 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 re-
		     sult 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 af-
		     ter 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 cre-
		     ated.

       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 cre-
		     ated.

       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  re-
		     turned 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  re-
		     turned 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 re-
		     gion 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  re-
		     turned 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 re-
		     turned when no record corresponds to the specified	key.

       The function `tcmapiterinit' is used in order to	initialize the	itera-
       tor 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 mem-
       ory 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 con-
       taining 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 con-
       taining 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	corre-
		     sponds, 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  re-
		     sult 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	param-
		     eter 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 for-
		     mer 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 cre-
		     ated.

       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 cre-
		     ated.

       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 re-
		     turned 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 re-
		     turned 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 re-
		     gion 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	itera-
       tor 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 con-
       taining 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 con-
       taining 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	corre-
		     sponds, 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  re-
		     sult 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 ob-
		     ject.
		     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  ob-
		     ject.
		     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 cre-
		     ated.

       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 cre-
		     ated.

       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 re-
		     turned 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 re-
		     turned 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 re-
		     gion 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	itera-
       tor 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 re-
		     gion of the next key, else, it is `NULL'.	`NULL' is  re-
		     turned 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 mem-
       ory 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	corre-
		     sponds, 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  ob-
		     ject.
		     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  ob-
		     ject.
		     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 cre-
		     ated.

       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 cre-
		     ated.

       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  re-
		     turned 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  re-
		     turned 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 re-
		     gion 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	itera-
       tor 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 re-
		     gion of the next key, else, it is `NULL'.	`NULL' is  re-
		     turned 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 re-
		     gion  of the next key, else, it is	`NULL'.	 `NULL'	is re-
		     turned 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 mem-
       ory 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	corre-
		     sponds, 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  ob-
       ject.

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

       The  function `tcmpooldel' is used in order to delete a memory pool ob-
       ject.

	      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 rele-
		     gated.  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 rele-
		     gated.  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  re-
		     leased when the memory pool object	is deleted.

       The function `tcmpoolpushxstr' is used in order to relegate an extensi-
       ble 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  ob-
       ject 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  ob-
       ject 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 rel-
       egated 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  un-
		     der 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 of a memory pool object.

	      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 `tcmpoolclear' is used in order to remove all cleanup han-
       dler of a memory	pool object.

	      void tcmpoolclear(TCMPOOL	*mpool,	bool exe);
		     `mpool' specifies the memory pool object.
		     `exe' specifies whether to	execute	the destructors	of the
		     removed handlers.

       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  dou-
       ble 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,	 nega-
		     tive if the latter	is big,	0 if both are equivalent.

       The  function `tcstrfwm'	is used	in order to check whether a string be-
       gins 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 be-
       gins 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 dis-
       tance 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 dis-
       tance 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 Uni-
		     code 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 charac-
		     ters.
		     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  `tclist-
		     new',  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 inte-
       ger.

	      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 met-
       ric prefix to an	integer.

	      int64_t tcatoix(const char *str);
		     `str' specifies the string, which can be trailed by a bi-
		     nary 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	 inte-
		     ger  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 sub-
       string 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 sub-
		     strings.  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  re-
		     placed 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 sup-
		     ported.
		     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 se-
       rial 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  sec-
       onds.

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

       The function `tccalendar' is used in order to get the Gregorian	calen-
       dar 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  lo-
       cal time.

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

       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 ab-
       solute 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  informa-
       tion 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 suc-
		     cessful, 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 di-
       rectory 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 ar-
		     guments.
		     `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 re-
		     sult.
		     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 ele-
       ments.

	      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" indicates the URL it-
		     self.  The	key "scheme" indicates the  scheme.   The  key
		     "host"  indicates the host	of the server.	The key	"port"
		     indicates the port	number of the server.	The  key  "au-
		     thority"  indicates  the  authority information.  The key
		     "path" indicates the  path	 of  the  resource.   The  key
		     "file" indicates the file name without the	directory sec-
		     tion.  The	key "query" indicates the query	 string.   The
		     key "fragment" indicates the fragment string.
		     Supported	schema	are HTTP, HTTPS, FTP, and FILE.	 Abso-
		     lute URL and relative URL are supported.  Because the ob-
		     ject  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  re-
		     sult.
		     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 en-
       coded 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 re-
		     sult.
		     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 charac-
		     ter 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 un-
		     capitalized 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	encod-
		     ing  is defined, the key "CHARSET"	indicates the encoding
		     name.  If the boundary string of  multipart  is  defined,
		     the  key "BOUNDARY" indicates the string.	If the content
		     disposition is defined, the key  "DISPOSITION"  indicates
		     the  direction.   If  the	file  name is defined, the key
		     "FILENAME"	indicates the name.  If	the attribute name  is
		     defined,  the key "NAME" indicates	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 re-
		     sult.
		     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 ob-
       ject 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 re-
		     sult 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 ob-
       ject 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 re-
		     sult 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 re-
		     sult 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 ob-
       ject 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 re-
		     sult 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 re-
		     sult 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 re-
		     sult 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  ob-
       ject 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 re-
		     sult 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 ob-
       ject 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 re-
		     sult 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  ob-
       ject 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 re-
		     sult 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 ob-
       ject 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 re-
		     sult 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 non-
       negative	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  re-
		     sult.
		     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 re-
		     sult.
		     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 `"'.  Be-
		     cause 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	refer-
       ences 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  al-
		     located  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)

Man Page			  2012-08-18			     TCUTIL(3)

NAME | DESCRIPTION | API OF BASIC UTILITIES | API OF EXTENSIBLE STRING | API OF ARRAY LIST | API OF HASH MAP | API OF ORDERED TREE | API OF ON-MEMORY HASH DATABASE | API OF ON-MEMORY TREE DATABASE | API OF MEMORY POOL | API OF MISCELLANEOUS UTILITIES | API OF FILESYSTEM UTILITIES | API OF ENCODING UTILITIES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tcutil&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help