1CABIN(3)                    Quick Database Manager                    CABIN(3)
2
3
4

NAME

6       Cabin - the utility API of QDBM
7
8

SYNOPSIS

10       #include <cabin.h>
11       #include <stdlib.h>
12
13       extern void (*cbfatalfunc)(const char *message);
14
15       void *cbmalloc(size_t size);
16
17       void *cbrealloc(void *ptr, size_t size);
18
19       char *cbmemdup(const char *ptr, int size);
20
21       void cbfree(void *ptr);
22
23       void cbglobalgc(void *ptr, void (*func)(void *));
24
25       void cbggcsweep(void);
26
27       int cbvmemavail(size_t size);
28
29       void  cbisort(void  *base, int nmemb, int size, int(*compar)(const void
30       *, const void *));
31
32       void cbssort(void *base, int nmemb, int size,  int(*compar)(const  void
33       *, const void *));
34
35       void  cbhsort(void  *base, int nmemb, int size, int(*compar)(const void
36       *, const void *));
37
38       void cbqsort(void *base, int nmemb, int size,  int(*compar)(const  void
39       *, const void *));
40
41       int cbstricmp(const char *astr, const char *bstr);
42
43       int cbstrfwmatch(const char *str, const char *key);
44
45       int cbstrfwimatch(const char *str, const char *key);
46
47       int cbstrbwmatch(const char *str, const char *key);
48
49       int cbstrbwimatch(const char *str, const char *key);
50
51       char *cbstrstrkmp(const char *haystack, const char *needle);
52
53       char *cbstrstrbm(const char *haystack, const char *needle);
54
55       char *cbstrtoupper(char *str);
56
57       char *cbstrtolower(char *str);
58
59       char *cbstrtrim(char *str);
60
61       char *cbstrsqzspc(char *str);
62
63       int cbstrcountutf(const char *str);
64
65       char *cbstrcututf(char *str, int num);
66
67       CBDATUM *cbdatumopen(const char *ptr, int size);
68
69       CBDATUM *cbdatumdup(const CBDATUM *datum);
70
71       void cbdatumclose(CBDATUM *datum);
72
73       void cbdatumcat(CBDATUM *datum, const char *ptr, int size);
74
75       const char *cbdatumptr(const CBDATUM *datum);
76
77       int cbdatumsize(const CBDATUM *datum);
78
79       void cbdatumsetsize(CBDATUM *datum, int size);
80
81       void cbdatumprintf(CBDATUM *datum, const char *format, ...);
82
83       char *cbdatumtomalloc(CBDATUM *datum, int *sp);
84
85       CBLIST *cblistopen(void);
86
87       CBLIST *cblistdup(const CBLIST *list);
88
89       void cblistclose(CBLIST *list);
90
91       int cblistnum(const CBLIST *list);
92
93       const char *cblistval(const CBLIST *list, int index, int *sp);
94
95       void cblistpush(CBLIST *list, const char *ptr, int size);
96
97       char *cblistpop(CBLIST *list, int *sp);
98
99       void cblistunshift(CBLIST *list, const char *ptr, int size);
100
101       char *cblistshift(CBLIST *list, int *sp);
102
103       void cblistinsert(CBLIST *list, int index, const char *ptr, int size);
104
105       char *cblistremove(CBLIST *list, int index, int *sp);
106
107       void cblistover(CBLIST *list, int index, const char *ptr, int size);
108
109       void cblistsort(CBLIST *list);
110
111       int cblistlsearch(const CBLIST *list, const char *ptr, int size);
112
113       int cblistbsearch(const CBLIST *list, const char *ptr, int size);
114
115       char *cblistdump(const CBLIST *list, int *sp);
116
117       CBLIST *cblistload(const char *ptr, int size);
118
119       CBMAP *cbmapopen(void);
120
121       CBMAP *cbmapdup(CBMAP *map);
122
123       void cbmapclose(CBMAP *map);
124
125       int  cbmapput(CBMAP *map, const char *kbuf, int ksiz, const char *vbuf,
126       int vsiz, int over);
127
128       void cbmapputcat(CBMAP *map, const char *kbuf,  int  ksiz,  const  char
129       *vbuf, int vsiz);
130
131       int cbmapout(CBMAP *map, const char *kbuf, int ksiz);
132
133       const  char *cbmapget(const CBMAP *map, const char *kbuf, int ksiz, int
134       *sp);
135
136       int cbmapmove(CBMAP *map, const char *kbuf, int ksiz, int head);
137
138       void cbmapiterinit(CBMAP *map);
139
140       const char *cbmapiternext(CBMAP *map, int *sp);
141
142       const char *cbmapiterval(const char *kbuf, int *sp);
143
144       int cbmaprnum(const CBMAP *map);
145
146       CBLIST *cbmapkeys(CBMAP *map);
147
148       CBLIST *cbmapvals(CBMAP *map);
149
150       char *cbmapdump(const CBMAP *map, int *sp);
151
152       CBMAP *cbmapload(const char *ptr, int size);
153
154       char *cbmaploadone(const char *ptr, int size,  const  char  *kbuf,  int
155       ksiz, int *sp);
156
157       CBHEAP  *cbheapopen(int size, int max, int(*compar)(const void *, const
158       void *));
159
160       CBHEAP *cbheapdup(CBHEAP *heap);
161
162       void cbheapclose(CBHEAP *heap);
163
164       int cbheapnum(CBHEAP *heap);
165
166       int cbheapinsert(CBHEAP *heap, const void *ptr);
167
168       void *cbheapval(CBHEAP *heap, int index);
169
170       void *cbheaptomalloc(CBHEAP *heap, int *np);
171
172       char *cbsprintf(const char *format, ...);
173
174       char *cbreplace(const char *str, CBMAP *pairs);
175
176       CBLIST *cbsplit(const char *ptr, int size, const char *delim);
177
178       char *cbreadfile(const char *name, int *sp);
179
180       int cbwritefile(const char *name, const char *ptr, int size);
181
182       CBLIST *cbreadlines(const char *name);
183
184       CBLIST *cbdirlist(const char *name);
185
186       int cbfilestat(const  char  *name,  int  *isdirp,  int  *sizep,  time_t
187       *mtimep);
188
189       int cbremove(const char *name);
190
191       CBMAP *cburlbreak(const char *str);
192
193       char *cburlresolve(const char *base, const char *target);
194
195       char *cburlencode(const char *ptr, int size);
196
197       char *cburldecode(const char *str, int *sp);
198
199       char *cbbaseencode(const char *ptr, int size);
200
201       char *cbbasedecode(const char *str, int *sp);
202
203       char *cbquoteencode(const char *ptr, int size);
204
205       char *cbquotedecode(const char *str, int *sp);
206
207       char *cbmimebreak(const char *ptr, int size, CBMAP *attrs, int *sp);
208
209       CBLIST *cbmimeparts(const char *ptr, int size, const char *boundary);
210
211       char *cbmimeencode(const char *str, const char *encname, int base);
212
213       char *cbmimedecode(const char *str, char *enp);
214
215       CBLIST *cbcsvrows(const char *str);
216
217       CBLIST *cbcsvcells(const char *str);
218
219       char *cbcsvescape(const char *str);
220
221       char *cbcsvunescape(const char *str);
222
223       CBLIST *cbxmlbreak(const char *str, int cr);
224
225       CBMAP *cbxmlattrs(const char *str);
226
227       char *cbxmlescape(const char *str);
228
229       char *cbxmlunescape(const char *str);
230
231       char *cbdeflate(const char *ptr, int size, int *sp);
232
233       char *cbinflate(const char *ptr, int size, int *sp);
234
235       char *cbgzencode(const char *ptr, int size, int *sp);
236
237       char *cbgzdecode(const char *ptr, int size, int *sp);
238
239       unsigned int cbgetcrc(const char *ptr, int size);
240
241       char *cblzoencode(const char *ptr, int size, int *sp);
242
243       char *cblzodecode(const char *ptr, int size, int *sp);
244
245       char *cbbzencode(const char *ptr, int size, int *sp);
246
247       char *cbbzdecode(const char *ptr, int size, int *sp);
248
249       char  *cbiconv(const char *ptr, int size, const char *icode, const char
250       *ocode, int *sp, int *mp);
251
252       const char *cbencname(const char *ptr, int size);
253
254       int cbjetlag(void);
255
256       void cbcalendar(time_t t, int jl, int *yearp, int *monp, int *dayp, int
257       *hourp, int *minp, int *secp);
258
259       int cbdayofweek(int year, int mon, int day);
260
261       char *cbdatestrwww(time_t t, int jl);
262
263       char *cbdatestrhttp(time_t t, int jl);
264
265       time_t cbstrmktime(const char *str);
266
267       void cbproctime(double *usrp, double *sysp);
268
269       void cbstdiobin(void);
270
271

DESCRIPTION

273       Cabin  is  the  utility API which provides memory allocating functions,
274       sorting functions, extensible datum, array list, hash map, heap  array,
275       and  so  on  for  handling records easily on memory.  This API features
276       also parsing MIME, CSV, and XML, and features various types of encoding
277       and decoding.
278
279       In  order  to use Cabin, you should include `cabin.h' and `stdlib.h' in
280       the source files.  Usually, the following description will be near  the
281       beginning of a source file.
282
283              #include <cabin.h>
284              #include <stdlib.h>
285
286       A  pointer  to `CBDATUM' is used as a handle of an extensible datum.  A
287       datum handle is opened with the function `cbdatumopen' and closed  with
288       `cbdatumclose'.   A pointer to `CBLIST' is used as a handle of an array
289       list.  A list handle is  opened  with  the  function  `cblistopen'  and
290       closed with `cblistclose'.  A pointer to `CBMAP' is used as a handle of
291       a hash map.  A map handle is opened with the function  `cbmapopen'  and
292       closed with `cbmapclose'.  A pointer to `CBHEAP' is used as a handle of
293       a heap array.  A heap handle is opened with the  function  `cbheapopen'
294       and  closed  with  `cbheapclose'.  You should not refer directly to any
295       member of each handles.
296
297       The external variable `cbfatalfunc' is the pointer to call  back  func‐
298       tion for handling a fatal error.
299
300       extern void (*cbfatalfunc)(const char *message);
301              The  argument specifies the error message.  The initial value of
302              this variable is `NULL'.  If the value is  `NULL',  the  default
303              function  is  called  when  a fatal error occurs.  A fatal error
304              occurs when memory allocation is failed.
305
306       The function `cbmalloc' is used in order to allocate a region  on  mem‐
307       ory.
308
309       void *cbmalloc(size_t size);
310              `size'  specifies  the  size of the region.  The return value is
311              the pointer to the allocated region.  Because the region of  the
312              return  value  is allocated with the `malloc' call, it should be
313              released with the `free' call if it is no longer in use.
314
315       The function `cbrealloc' is used in order to re-allocate  a  region  on
316       memory.
317
318       void *cbrealloc(void *ptr, size_t size);
319              `ptr'  specifies  the pointer to a region.  `size' specifies the
320              size of the region.  The return value  is  the  pointer  to  the
321              re-allocated  region.  Because the region of the return value is
322              allocated with the `malloc' call, it should be released with the
323              `free' call if it is no longer in use.
324
325       The  function `cbmemdup' is used in order to duplicate a region on mem‐
326       ory.
327
328       char *cbmemdup(const char *ptr, int size);
329              `ptr' specifies the pointer to a region.  `size'  specifies  the
330              size  of  the  region.   If it is negative, the size is assigned
331              with `strlen(ptr)'.  The return value  is  the  pointer  to  the
332              allocated  region  of the duplicate.  Because an additional zero
333              code is appended at the end of the region of the  return  value,
334              the  return value can be treated as a character string.  Because
335              the region of the return value is allocated  with  the  `malloc'
336              call,  it  should  be  released with the `free' call if it is no
337              longer in use.
338
339       The function `cbfree' is used in order to free a region on memory.
340
341       void cbfree(void *ptr);
342              `ptr' specifies the pointer to a region.  If it is `NULL',  this
343              function  has no effect.  Although this function is just a wrap‐
344              per of `free' call, this is useful in applications using another
345              package of the `malloc' series.
346
347       The  function  `cbglobalgc' is used in order to register the pointer or
348       handle of an object to the global garbage collector.
349
350       void cbglobalgc(void *ptr, void (*func)(void *));
351              `ptr' specifies the pointer or  handle  of  an  object.   `func'
352              specifies  the pointer to a function to release resources of the
353              object.  Its argument is the pointer or handle of the object  to
354              release.   This function assures that resources of an object are
355              released when the process exits normally by returning  from  the
356              `main' function or calling the `exit' function.
357
358       The  function  `cbggcsweep'  is  used  in  order to exercise the global
359       garbage collector explicitly.
360
361       void cbggcsweep(void);
362              Note that you should not use objects registered  to  the  global
363              garbage  collector  any  longer  after  calling  this  function.
364              Because the global garbage collector is initialized and you  can
365              register new objects into it.
366
367       The  function  `cbvmemavail'  is used in order to check availability of
368       allocation of the virtual memory.
369
370       int cbvmemavail(size_t size);
371              `size' specifies the size of region to be allocated newly.   The
372              return  value  is true if allocation should be success, or false
373              if not.
374
375       The function `cbisort' is used in order to sort an array  using  insert
376       sort.
377
378       void  cbisort(void  *base, int nmemb, int size, int(*compar)(const void
379       *, const void *));
380              `base' specifies the pointer to an array.  `nmemb' specifies the
381              number  of  elements of the array.  `size' specifies the size of
382              each element.  `compar' specifies the pointer to comparing func‐
383              tion.   The two arguments specify the pointers of elements.  The
384              comparing function should returns positive if the former is big,
385              negative if the latter is big, 0 if both are equal.  Insert sort
386              is useful only if most elements have been sorted already.
387
388       The function `cbssort' is used in order to sort an  array  using  shell
389       sort.
390
391       void  cbssort(void  *base, int nmemb, int size, int(*compar)(const void
392       *, const void *));
393              `base' specifies the pointer to an array.  `nmemb' specifies the
394              number  of  elements of the array.  `size' specifies the size of
395              each element.  `compar' specifies the pointer to comparing func‐
396              tion.   The two arguments specify the pointers of elements.  The
397              comparing function should returns positive if the former is big,
398              negative  if  the  latter  is big, 0 if both are equal.  If most
399              elements have been sorted, shell sort may be  faster  than  heap
400              sort or quick sort.
401
402       The  function  `cbhsort'  is  used in order to sort an array using heap
403       sort.
404
405       void cbhsort(void *base, int nmemb, int size,  int(*compar)(const  void
406       *, const void *));
407              `base' specifies the pointer to an array.  `nmemb' specifies the
408              number of elements of the array.  `size' specifies the  size  of
409              each  element. `compar' specifies the pointer to comparing func‐
410              tion.  The two arguments specify the pointers of elements.   The
411              comparing function should returns positive if the former is big,
412              negative if the latter is big, 0 if both  are  equal.   Although
413              heap  sort is robust against bias of input, quick sort is faster
414              in most cases.
415
416       The function `cbqsort' is used in order to sort an  array  using  quick
417       sort.
418
419       void  cbqsort(void  *base, int nmemb, int size, int(*compar)(const void
420       *, const void *));
421              `base' specifies the pointer to an array.  `nmemb' specifies the
422              number  of  elements of the array.  `size' specifies the size of
423              each element. `compar' specifies the pointer to comparing  func‐
424              tion.   The two arguments specify the pointers of elements.  The
425              comparing function should returns positive if the former is big,
426              negative  if the latter is big, 0 if both are equal.  Being sen‐
427              sitive to bias of input, quick sort is the fastest sorting algo‐
428              rithm.
429
430       The  function  `cbstricmp' is used in order to compare two strings with
431       case insensitive evaluation.
432
433       int cbstricmp(const char *astr, const char *bstr);
434              `astr' specifies the pointer of one  string.   `astr'  specifies
435              the  pointer  of the other string.  The return value is positive
436              if the former is big, negative if the latter is big, 0  if  both
437              are  equivalent.   Upper  cases  and lower cases of alphabets in
438              ASCII code are not distinguished.
439
440       The function `cbstrfwmatch' is used in order to check whether a  string
441       begins with a key.
442
443       int cbstrfwmatch(const char *str, const char *key);
444              `str' specifies the pointer of a target string.  `key' specifies
445              the pointer of a forward matching key string.  The return  value
446              is  true  if  the target string begins with the key, else, it is
447              false.
448
449       The function `cbstrfwimatch' is used in order to check whether a string
450       begins with a key, with case insensitive evaluation.
451
452       int cbstrfwimatch(const char *str, const char *key);
453              `str' specifies the pointer of a target string.  `key' specifies
454              the pointer of a forward matching key string.  The return  value
455              is  true  if  the target string begins with the key, else, it is
456              false.  Upper cases and lower cases of alphabets in  ASCII  code
457              are not distinguished.
458
459       The  function `cbstrbwmatch' is used in order to check whether a string
460       ends with a key.
461
462       int cbstrbwmatch(const char *str, const char *key);
463              `str' specifies the pointer of a target string.  `key' specifies
464              the pointer of a backward matching key string.  The return value
465              is true if the target string ends with  the  key,  else,  it  is
466              false.
467
468       The function `cbstrbwimatch' is used in order to check whether a string
469       ends with a key, with case insensitive evaluation.
470
471       int cbstrbwimatch(const char *str, const char *key);
472              `str' specifies the pointer of a target string.  `key' specifies
473              the pointer of a backward matching key string.  The return value
474              is true if the target string ends with  the  key,  else,  it  is
475              false.   Upper  cases and lower cases of alphabets in ASCII code
476              are not distinguished.
477
478       The function `cbstrstrkmp' is used in order to locate a substring in  a
479       string using KMP method.
480
481       char *cbstrstrkmp(const char *haystack, const char *needle);
482              `haystack'  specifies  the pointer of a target string.  `needle'
483              specifies the pointer of a substring to be  found.   The  return
484              value is the pointer to the beginning of the substring or `NULL'
485              if the substring is not found.  In most  cases,  `strstr'  as  a
486              built-in function of the compiler is faster than this function.
487
488       The  function `cbstrstrkmp' is used in order to locate a substring in a
489       string using BM method.
490
491       char *cbstrstrbm(const char *haystack, const char *needle);
492              `haystack' specifies the pointer of a target  string.   `needle'
493              specifies  the  pointer  of a substring to be found.  The return
494              value is the pointer to the beginning of the substring or `NULL'
495              if  the  substring  is  not found.  In most cases, `strstr' as a
496              built-in function of the compiler is faster than this function.
497
498       The function `cbstrtoupper' is used in order to convert the letters  of
499       a string to upper case.
500
501       char *cbstrtoupper(char *str);
502              `str'  specifies the pointer of a string to convert.  The return
503              value is the pointer to the string.
504
505       The function `cbstrtolower' is used in order to convert the letters  of
506       a string to lower case.
507
508       char *cbstrtolower(char *str);
509              `str'  specifies the pointer of a string to convert.  The return
510              value is the pointer to the string.
511
512       The function `cbstrtrim' is used in order to cut  space  characters  at
513       head or tail of a string.
514
515       char *cbstrtrim(char *str);
516              `str'  specifies the pointer of a string to convert.  The return
517              value is the pointer to the string.
518
519       The function `cbstrsqzspc' is used in order to squeeze space characters
520       in a string and trim it.
521
522       char *cbstrsqzspc(char *str);
523              `str'  specifies the pointer of a string to convert.  The return
524              value is the pointer to the string.
525
526       The function `cbstrcountutf' is used in order to count  the  number  of
527       characters in a string of UTF-8.
528
529       int cbstrcountutf(const char *str);
530              `str'  specifies  the  pointer of a string of UTF-8.  The return
531              value is the number of characters in the string.
532
533       The function `cbstrcututf' is used in order to cut a string of UTF-8 at
534       the specified number of characters.
535
536       char *cbstrcututf(char *str, int num);
537              `str'  specifies the pointer of a string of UTF-8.  `num' speci‐
538              fies the number of characters to be kept.  The return  value  is
539              the pointer to the string.
540
541       The function `cbdatumopen' is used in order to get a datum handle.
542
543       CBDATUM *cbdatumopen(const char *ptr, int size);
544              `ptr'  specifies  the  pointer to the region of the initial con‐
545              tent.  If it is `NULL', an empty datum is created.  `size' spec‐
546              ifies  the  size  of the region.  If it is negative, the size is
547              assigned with `strlen(ptr)'.  The return value is a  datum  han‐
548              dle.
549
550       The function `cbdatumdup' is used in order to copy a datum.
551
552       CBDATUM *cbdatumdup(const CBDATUM *datum);
553              `datum'  specifies  a  datum  handle.  The return value is a new
554              datum handle.
555
556       The function `cbdatumclose' is used in order to free a datum handle.
557
558       void cbdatumclose(CBDATUM *datum);
559              `datum' specifies a datum  handle.   Because  the  region  of  a
560              closed handle is released, it becomes impossible to use the han‐
561              dle.
562
563       The function `cbdatumcat' is used in order to concatenate a datum and a
564       region.
565
566       void cbdatumcat(CBDATUM *datum, const char *ptr, int size);
567              `datum'  specifies  a datum handle.  `ptr' specifies the pointer
568              to the region to be appended.  `size' specifies the size of  the
569              region.    If   it  is  negative,  the  size  is  assigned  with
570              `strlen(ptr)'.
571
572       The function `cbdatumptr' is used in order to get the  pointer  of  the
573       region of a datum.
574
575       const char *cbdatumptr(const CBDATUM *datum);
576              `datum'  specifies  a  datum  handle.   The  return value is the
577              pointer of the region of a datum.  Because  an  additional  zero
578              code  is  appended at the end of the region of the return value,
579              the return value can be treated as a character string.
580
581       The function `cbdatumsize' is used in order to  get  the  size  of  the
582       region of a datum.
583
584       int cbdatumsize(const CBDATUM *datum);
585              `datum'  specifies a datum handle.  The return value is the size
586              of the region of a datum.
587
588       The function `cbdatumsetsize' is used in order to change  the  size  of
589       the region of a datum.
590
591       void cbdatumsetsize(CBDATUM *datum, int size);
592              `datum' specifies a datum handle.  `size' specifies the new size
593              of the region.  If the new size is bigger than the one  of  old,
594              the surplus region is filled with zero codes.
595
596       The function `cbdatumprintf' is used in order to perform formatted out‐
597       put into a datum.
598
599       void cbdatumprintf(CBDATUM *datum, const char *format, ...);
600              `format' specifies a printf-like format string.  The  conversion
601              character `%' can be used with such flag characters as `s', `d',
602              `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `:',
603              `%'.   `@' works as with `s' but escapes meta characters of XML.
604              `?' works as with `s' but escapes meta characters of  URL.   `:'
605              works  as  with  `s'  but  performs MIME encoding as UTF-8.  The
606              other conversion character work as with each original.
607
608       The function `cbdatumtomalloc' is used in order to convert a  datum  to
609       an allocated region.
610
611       char *cbdatumtomalloc(CBDATUM *datum, int *sp);
612              `datum' specifies a datum handle.  `sp' specifies the pointer to
613              a variable to which the size of the region of the  return  value
614              is assigned.  If it is `NULL', it is not used.  The return value
615              is the pointer to the region of the  datum.   Because  an  addi‐
616              tional  zero  code  is  appended at the end of the region of the
617              return value, the return value can be  treated  as  a  character
618              string.   Because  the  region  of the return value is allocated
619              with the `malloc' call, it should be released  with  the  `free'
620              call if it is no longer in use.  Because the region of the orig‐
621              inal datum is released, it should not be released again.
622
623       The function `cblistopen' is used in order to get a list handle.
624
625       CBLIST *cblistopen(void);
626              The return value is a list handle.
627
628       The function `cblistdup' is used in order to copy a list.
629
630       CBLIST *cblistdup(const CBLIST *list);
631              `list' specifies a list handle.  The return value is a new  list
632              handle.
633
634       The function `cblistclose' is used in order to close a list handle.
635
636       void cblistclose(CBLIST *list);
637              `list'  specifies a list handle.  Because the region of a closed
638              handle is released, it becomes impossible to use the handle.
639
640       The function `cblistnum' is used in order to get the number of elements
641       of a list.
642
643       int cblistnum(const CBLIST *list);
644              `list'  specifies a list handle.  The return value is the number
645              of elements of the list.
646
647       The function `cblistval' is used in order to get  the  pointer  to  the
648       region of an element of a list.
649
650       const char *cblistval(const CBLIST *list, int index, int *sp);
651              `list'  specifies a list handle.  `index' specifies the index of
652              an element.  `sp' specifies the pointer to a variable  to  which
653              the  size  of the region of the return value is assigned.  If it
654              is `NULL', it is not used.  The return value is the  pointer  to
655              the  region  of the element.  Because an additional zero code is
656              appended at the end of the  region  of  the  return  value,  the
657              return  value  can be treated as a character string.  If `index'
658              is equal to or more than the  number  of  elements,  the  return
659              value is `NULL'.
660
661       The function `cblistpush' is used in order to add an element at the end
662       of a list.
663
664       void cblistpush(CBLIST *list, const char *ptr, int size);
665              `list' specifies a list handle.  `ptr' specifies the pointer  to
666              the  region  of  an  element.   `size' specifies the size of the
667              region.   If  it  is  negative,  the  size  is   assigned   with
668              `strlen(ptr)'.
669
670       The  function  `cblistpop' is used in order to remove an element of the
671       end of a list.
672
673       char *cblistpop(CBLIST *list, int *sp);
674              `list' specifies a list handle.  `sp' specifies the pointer to a
675              variable  to which the size of the region of the return value is
676              assigned.  If it is `NULL', it is not used.  The return value is
677              the  pointer  to the region of the value.  Because an additional
678              zero code is appended at the end of the  region  of  the  return
679              value,  the  return  value can be treated as a character string.
680              Because the region of the return value  is  allocated  with  the
681              `malloc'  call, it should be released with the `free' call if it
682              is no longer in use.  If the list is empty, the return value  is
683              `NULL'.
684
685       The  function `cblistunshift' is used in order to add an element at the
686       top of a list.
687
688       void cblistunshift(CBLIST *list, const char *ptr, int size);
689              `list' specifies a list handle.  `ptr' specifies the pointer  to
690              the  region  of  an  element.   `size' specifies the size of the
691              region.   If  it  is  negative,  the  size  is   assigned   with
692              `strlen(ptr)'.
693
694       The function `cblistshift' is used in order to remove an element of the
695       top of a list.
696
697       char *cblistshift(CBLIST *list, int *sp);
698              `list' specifies a list handle.  `sp' specifies the pointer to a
699              variable  to which the size of the region of the return value is
700              assigned.  If it is `NULL', it is not used.  The return value is
701              the  pointer  to the region of the value.  Because an additional
702              zero code is appended at the end of the  region  of  the  return
703              value,  the  return  value can be treated as a character string.
704              Because the region of the return value  is  allocated  with  the
705              `malloc'  call, it should be released with the `free' call if it
706              is no longer in use.  If the list is empty, the return value  is
707              `NULL'.
708
709       The  function  `cblistinsert' is used in order to add an element at the
710       specified location of a list.
711
712       void cblistinsert(CBLIST *list, int index, const char *ptr, int size);
713              `list' specifies a list handle.  `index' specifies the index  of
714              an  element.   `ptr'  specifies the pointer to the region of the
715              element.  `size' specifies the size of the  region.   If  it  is
716              negative, the size is assigned with `strlen(ptr)'.
717
718       The  function  `cblistremove'  is used in order to remove an element at
719       the specified location of a list.
720
721       char *cblistremove(CBLIST *list, int index, int *sp);
722              `list' specifies a list handle.  `index' specifies the index  of
723              an  element.   `sp' specifies the pointer to a variable to which
724              the size of the region of the return value is assigned.   If  it
725              is  `NULL',  it is not used.  The return value is the pointer to
726              the region of the value.  Because an  additional  zero  code  is
727              appended  at  the  end  of  the  region of the return value, the
728              return value can be treated as a character string.  Because  the
729              region  of the return value is allocated with the `malloc' call,
730              it should be released with the `free' call if it is no longer in
731              use.   If  `index'  is  equal to or more than the number of ele‐
732              ments, no element is removed and the return value is `NULL'.
733
734       The function `cblistover' is used in order to overwrite an  element  at
735       the specified location of a list.
736
737       void cblistover(CBLIST *list, int index, const char *ptr, int size);
738              `list'  specifies a list handle.  `index' specifies the index of
739              an element.  `ptr' specifies the pointer to the  region  of  the
740              new  content.  `size' specifies the size of the new content.  If
741              it is negative, the size is  assigned  with  `strlen(ptr)'.   If
742              `index'  is  equal  to or more than the number of elements, this
743              function has no effect.
744
745       The function `cblistsort' is used in order to sort elements of  a  list
746       in lexical order.
747
748       void cblistsort(CBLIST *list);
749              `list' specifies a list handle.  Quick sort is used for sorting.
750
751       The  function  `cblistlsearch' is used in order to search a list for an
752       element using liner search.
753
754       int cblistlsearch(const CBLIST *list, const char *ptr, int size);
755              `list' specifies a list handle.  `ptr' specifies the pointer  to
756              the  region  of a key.  `size' specifies the size of the region.
757              If it is negative, the size is assigned with `strlen(ptr)'.  The
758              return  value  is  the index of a corresponding element or -1 if
759              there is no corresponding element.  If two or more elements cor‐
760              responds, the former returns.
761
762       The  function  `cblistbsearch' is used in order to search a list for an
763       element using binary search.
764
765       int cblistbsearch(const CBLIST *list, const char *ptr, int size);
766              `list' specifies a list handle.  It should be sorted in  lexical
767              order.   `ptr'  specifies  the  pointer  to the region of a key.
768              `size' specifies the size of the region.  If it is negative, the
769              size  is  assigned  with `strlen(ptr)'.  The return value is the
770              index of a corresponding element or -1 if  there  is  no  corre‐
771              sponding  element.   If  two or more elements corresponds, which
772              returns is not defined.
773
774       The function `cblistdump' is used in order to serialize a list  into  a
775       byte array.
776
777       char *cblistdump(const CBLIST *list, int *sp);
778              `list' specifies a list handle.  `sp' specifies the pointer to a
779              variable to which the size of the region of the return value  is
780              assigned.   The return value is the pointer to the region of the
781              result serial region.  Because the region of the return value is
782              allocated with the `malloc' call, it should be released with the
783              `free' call if it is no longer in use.
784
785       The function `cblistload' is used in order to redintegrate a serialized
786       list.
787
788       CBLIST *cblistload(const char *ptr, int size);
789              `ptr'  specifies  the pointer to a byte array.  `size' specifies
790              the size of the region.  The return value is a new list handle.
791
792       The function `cbmapopen' is used in order to get a map handle.
793
794       CBMAP *cbmapopen(void);
795              The return value is a map handle.
796
797       The function `cbmapdup' is used in order to copy a map.
798
799       CBMAP *cbmapdup(CBMAP *map);
800              `map' specifies a map handle.  The return value  is  a  new  map
801              handle.  The iterator of the source map is initialized.
802
803       The function `cbmapclose' is used in order to close a map handle.
804
805       void cbmapclose(CBMAP *map);
806              `map'  specifies  a  map handle.  Because the region of a closed
807              handle is released, it becomes impossible to use the handle.
808
809       The function `cbmapput' is used in order to store a record into a map.
810
811       int cbmapput(CBMAP *map, const char *kbuf, int ksiz, const char  *vbuf,
812       int vsiz, int over);
813              `map'  specifies  a map handle.  `kbuf' specifies the pointer to
814              the region of a key.  `ksiz' specifies the size of the region of
815              the  key.   If  it  is  negative,  the  size  is  assigned  with
816              `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a
817              value.   `vsiz'  specifies  the size of the region of the value.
818              If it is negative, the size  is  assigned  with  `strlen(vbuf)'.
819              `over'  specifies  whether the value of the duplicated record is
820              overwritten or not.  If `over' is false and the  key  is  dupli‐
821              cated, the return value is false, else, it is true.
822
823       The  function  `cbmapputcat' is used in order to concatenate a value at
824       the end of the value of the existing record.
825
826       void cbmapputcat(CBMAP *map, const char *kbuf,  int  ksiz,  const  char
827       *vbuf, int vsiz);
828              `map'  specifies  a map handle.  `kbuf' specifies the pointer to
829              the region of a key.  `ksiz' specifies the size of the region of
830              the  key.   If  it  is  negative,  the  size  is  assigned  with
831              `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a
832              value.   `vsiz'  specifies  the size of the region of the value.
833              If it is negative, the size is assigned with `strlen(vbuf)'.  If
834              there is no corresponding record, a new record is created.
835
836       The function `cbmapout' is used in order to delete a record in a map.
837
838       int cbmapout(CBMAP *map, const char *kbuf, int ksiz);
839              `map'  specifies  a map handle.  `kbuf' specifies the pointer to
840              the region of a key.  `ksiz' specifies the size of the region of
841              the  key.   If  it  is  negative,  the  size  is  assigned  with
842              `strlen(kbuf)'.  If successful, the return value is true.  False
843              is returned when no record corresponds to the specified key.
844
845       The function `cbmapget' is used in order to retrieve a record in a map.
846
847       const  char *cbmapget(const CBMAP *map, const char *kbuf, int ksiz, int
848       *sp);
849              `map' specifies a map handle.  `kbuf' specifies the  pointer  to
850              the region of a key.  `ksiz' specifies the size of the region of
851              the  key.   If  it  is  negative,  the  size  is  assigned  with
852              `strlen(kbuf)'.   `sp'  specifies  the  pointer to a variable to
853              which the size of the region of the return  value  is  assigned.
854              If  it  is  `NULL',  it  is not used.  If successful, the return
855              value is the pointer to the region of the value  of  the  corre‐
856              sponding record.  `NULL' is returned when no record corresponds.
857              Because an additional zero code is appended at the  end  of  the
858              region of the return value, the return value can be treated as a
859              character string.
860
861       The function `cbmapmove' is used in order to move a record to the  edge
862       of a map.
863
864       int cbmapmove(CBMAP *map, const char *kbuf, int ksiz, int head);
865              `map'  specifies  a map handle.  `kbuf' specifies the pointer to
866              the region of a key.  `ksiz' specifies the size of the region of
867              the  key.   If  it  is  negative,  the  size  is  assigned  with
868              `strlen(kbuf)'.  `head' specifies the destination which is  head
869              if  it is true or tail if else.  If successful, the return value
870              is true.  False is returned when no record  corresponds  to  the
871              specified key.
872
873       The  function `cbmapiterinit' is used in order to initialize the itera‐
874       tor of a map.
875
876       void cbmapiterinit(CBMAP *map);
877              `map' specifies a map handle.  The iterator is used in order  to
878              access the key of every record stored in a map.
879
880       The  function  `cbmapiternext'  is used in order to get the next key of
881       the iterator of a map.
882
883       const char *cbmapiternext(CBMAP *map, int *sp);
884              `map' specifies a map handle.  `sp' specifies the pointer  to  a
885              variable  to which the size of the region of the return value is
886              assigned.  If it is `NULL', it is not used.  If successful,  the
887              return value is the pointer to the region of the next key, else,
888              it is `NULL'.  `NULL' is returned when no record is  to  be  get
889              out  of  the  iterator.   Because  an  additional  zero  code is
890              appended at the end of the  region  of  the  return  value,  the
891              return value can be treated as a character string.  The order of
892              iteration is assured to be the same of the one of storing.
893
894       The function `cbmapiterval' is used in order to get the value binded to
895       the key fetched from the iterator of a map.
896
897       const char *cbmapiterval(const char *kbuf, int *sp);
898              `kbuf'  specifies  the pointer to the region of a iteration key.
899              `sp' specifies the pointer to a variable to which  the  size  of
900              the region of the return value is assigned.  If it is `NULL', it
901              is not used.  The return value is the pointer to the  region  of
902              the  value  of  the corresponding record.  Because an additional
903              zero code is appended at the end of the  region  of  the  return
904              value, the return value can be treated as a character string.
905
906       The  function  `cbmaprnum'  is  used  in order to get the number of the
907       records stored in a map.
908
909       int cbmaprnum(const CBMAP *map);
910              `map' specifies a map handle.  The return value is the number of
911              the records stored in the map.
912
913       The  function  `cbmapkeys' is used in order to get the list handle con‐
914       tains all keys in a map.
915
916       CBLIST *cbmapkeys(CBMAP *map);
917              `map' specifies a map handle.  The return value is the list han‐
918              dle  contains  all  keys  in the map.  Because the handle of the
919              return value is opened with the function `cblistopen', it should
920              be  closed with the function `cblistclose' if it is no longer in
921              use.
922
923       The function `cbmapvals' is used in order to get the list  handle  con‐
924       tains all values in a map.
925
926       CBLIST *cbmapvals(CBMAP *map);
927              `map' specifies a map handle.  The return value is the list han‐
928              dle contains all values in the map.  Because the handle  of  the
929              return value is opened with the function `cblistopen', it should
930              be closed with the function `cblistclose' if it is no longer  in
931              use.
932
933       The  function  `cbmapdump'  is  used in order to serialize a map into a
934       byte array.
935
936       char *cbmapdump(const CBMAP *map, int *sp);
937              `map' specifies a map handle.  `sp' specifies the pointer  to  a
938              variable  to which the size of the region of the return value is
939              assigned.  The return value is the pointer to the region of  the
940              result serial region.  Because the region of the return value is
941              allocated with the `malloc' call, it should be released with the
942              `free' call if it is no longer in use.
943
944       The  function `cbmapload' is used in order to redintegrate a serialized
945       map.
946
947       CBMAP *cbmapload(const char *ptr, int size);
948              `ptr' specifies the pointer to a byte array.   `size'  specifies
949              the size of the region.  The return value is a new map handle.
950
951       The function `cbmaploadone' is used in order to extract a record from a
952       serialized map.
953
954       char *cbmaploadone(const char *ptr, int size,  const  char  *kbuf,  int
955       ksiz, int *sp);
956              `ptr'  specifies  the pointer to a byte array.  `size' specifies
957              the size of the region.  `kbuf' specifies  the  pointer  to  the
958              region of a key.  `ksiz' specifies the size of the region of the
959              key.   If  it  is  negative,   the   size   is   assigned   with
960              `strlen(kbuf)'.   `sp'  specifies  the  pointer to a variable to
961              which the size of the region of the return  value  is  assigned.
962              If  it  is  `NULL',  it  is not used.  If successful, the return
963              value is the pointer to the region of the value  of  the  corre‐
964              sponding record.  `NULL' is returned when no record corresponds.
965              Because an additional zero code is appended at the  end  of  the
966              region of the return value, the return value can be treated as a
967              character string.
968
969       The function `cbheapopen' is used in order to get a heap handle.
970
971       CBHEAP *cbheapopen(int size, int max, int(*compar)(const void *,  const
972       void *));
973              `size'  specifies  the size of each record.  `max' specifies the
974              maximum number of records in the heap.  `compar'  specifies  the
975              pointer  to  comparing  function.  The two arguments specify the
976              pointers of records.  The comparing function should returns pos‐
977              itive  if the former is big, negative if the latter is big, 0 if
978              both are equal.  The return value is a heap handle.
979
980       The function `cbheapdup' is used in order to copy a heap.
981
982       CBHEAP *cbheapdup(CBHEAP *heap);
983              `heap' specifies a heap handle.  The return value is a new  heap
984              handle.
985
986       The function `cbheapclose' is used in order to close a heap handle.
987
988       void cbheapclose(CBHEAP *heap);
989              `heap'  specifies a heap handle.  Because the region of a closed
990              handle is released, it becomes impossible to use the handle.
991
992       The function `cbheapnum' is used in order to  get  the  number  of  the
993       records stored in a heap.
994
995       int cbheapnum(CBHEAP *heap);
996              `heap'  specifies a heap handle.  The return value is the number
997              of the records stored in the heap.
998
999       The function `cbheapinsert' is used in order to insert a record into  a
1000       heap.
1001
1002       int cbheapinsert(CBHEAP *heap, const void *ptr);
1003              `heap'  specifies a heap handle.  `ptr' specifies the pointer to
1004              the region of a record.  The return value is true if the  record
1005              is added, else false.  If the new record is bigger than the big‐
1006              gest existing regord, the new record is not added.  If  the  new
1007              record  is  added  and the number of records exceeds the maximum
1008              number, the biggest existing record is removed.
1009
1010       The function `cbheapval' is used in order to get  the  pointer  to  the
1011       region of a record in a heap.
1012
1013       void *cbheapval(CBHEAP *heap, int index);
1014              `heap'  specifies a heap handle.  `index' specifies the index of
1015              a record.  The return value is the pointer to the region of  the
1016              record.   If  `index'  is  equal  to  or more than the number of
1017              records, the return value is  `NULL'.   Note  that  records  are
1018              organized by the nagative order the comparing function.
1019
1020       The  function `cbheaptomalloc' is used in order to convert a heap to an
1021       allocated region.
1022
1023       void *cbheaptomalloc(CBHEAP *heap, int *np);
1024              `heap' specifies a heap handle.  `np' specifies the pointer to a
1025              variable  to  which the number of records of the return value is
1026              assigned.  If it is `NULL', it is not used.  The return value is
1027              the  pointer  to  the  region  of the heap.  Records are sorted.
1028              Because the region of the return value  is  allocated  with  the
1029              `malloc'  call, it should be released with the `free' call if it
1030              is no longer in use.  Because the region of the original heap is
1031              released, it should not be released again.
1032
1033       The  function  `cbsprintf'  is  used  in  order to allocate a formatted
1034       string on memory.
1035
1036       char *cbsprintf(const char *format, ...);
1037              `format' specifies a printf-like format string.  The  conversion
1038              character `%' can be used with such flag characters as `d', `o',
1039              `u', `x', `X', `e', `E', `f',  `g',  `G',  `c',  `s',  and  `%'.
1040              Specifiers  of  the  field  length  and the precision can be put
1041              between the conversion characters and the flag characters.   The
1042              specifiers consist of decimal characters, `.', `+', `-', and the
1043              space character.  The other arguments are used according to  the
1044              format string.  The return value is the pointer to the allocated
1045              region of the result string.  Because the region of  the  return
1046              value is allocated with the `malloc' call, it should be released
1047              with the `free' call if it is no longer in use.
1048
1049       The function `cbreplace' is used in order to replace some patterns in a
1050       string.
1051
1052       char *cbreplace(const char *str, CBMAP *pairs);
1053              `str'  specifies the pointer to a source string.  `pairs' speci‐
1054              fies the handle of a map composed of pairs of replacement.   The
1055              key  of each pair specifies a pattern before replacement and its
1056              value specifies the pattern after replacement.  The return value
1057              is  the  pointer  to  the allocated region of the result string.
1058              Because the region of the return value  is  allocated  with  the
1059              `malloc'  call, it should be released with the `free' call if it
1060              is no longer in use.
1061
1062       The function `cbsplit' is used in order to make a list by  splitting  a
1063       serial datum.
1064
1065       CBLIST *cbsplit(const char *ptr, int size, const char *delim);
1066              `ptr' specifies the pointer to the region of the source content.
1067              `size' specifies the size of the region.  If it is negative, the
1068              size is assigned with `strlen(ptr)'.  `delim' specifies a string
1069              containing delimiting characters.  If it is `NULL', zero code is
1070              used as a delimiter.  The return value is a list handle.  If two
1071              delimiters are successive, it is assumed that an  empty  element
1072              is  between  the two.  Because the handle of the return value is
1073              opened with the function `cblistopen', it should be closed  with
1074              the function `cblistclose'.
1075
1076       The  function  `cbreadfile'  is  used  in order to read whole data of a
1077       file.
1078
1079       char *cbreadfile(const char *name, int *sp);
1080              `name' specifies the name of a file.  If it is `NULL', the stan‐
1081              dard  input is specified.  `sp' specifies the pointer to a vari‐
1082              able to which the size of the region  of  the  return  value  is
1083              assigned.  If it is `NULL', it is not used.  The return value is
1084              the pointer to the allocated region of the read  data.   Because
1085              an  additional zero code is appended at the end of the region of
1086              the return value, the return value can be treated as a character
1087              string.   Because  the  region  of the return value is allocated
1088              with the `malloc' call, it should be released  with  the  `free'
1089              call if it is no longer in use.
1090
1091       The  function  `cbwritefile'  is  used in order to write a serial datum
1092       into a file.
1093
1094       int cbwritefile(const char *name, const char *ptr, int size);
1095              `name specifies the name of a file.  If it is `NULL', the  stan‐
1096              dard  output  is  specified.  `ptr' specifies the pointer to the
1097              region of the source content.  `size' specifies the size of  the
1098              region.    If   it  is  negative,  the  size  is  assigned  with
1099              `strlen(ptr)'.  If successful, the return value is  true,  else,
1100              it  is  false.   If the file exists, it is overwritten.  Else, a
1101              new file is created.
1102
1103       The function `cbreadlines' is used in order to read  every  line  of  a
1104       file.
1105
1106       CBLIST *cbreadlines(const char *name);
1107              `name' specifies the name of a file.  If it is `NULL', the stan‐
1108              dard input is specified.  The return value is a list  handle  of
1109              the  lines  if successful, else it is NULL.  Line separators are
1110              cut out.  Because the handle of the return value is opened  with
1111              the function `cblistopen', it should be closed with the function
1112              `cblistclose' if it is no longer in use.
1113
1114       The function `cbdirlist' is used in order to read names of files  in  a
1115       directory.
1116
1117       CBLIST *cbdirlist(const char *name);
1118              `name' specifies the name of a directory.  The return value is a
1119              list handle of names if successful, else it  is  NULL.   Because
1120              the  handle  of  the  return  value  is opened with the function
1121              `cblistopen', it should be closed  with  the  function  `cblist‐
1122              close' if it is no longer in use.
1123
1124       The  function `cbfilestat' is used in order to get the status of a file
1125       or a directory.
1126
1127       int cbfilestat(const  char  *name,  int  *isdirp,  int  *sizep,  time_t
1128       *mtimep);
1129              `name'  specifies  the  name  of  a file or a directory.  `dirp'
1130              specifies the pointer to a variable to which whether the file is
1131              a  directory  is  assigned.   If  it  is `NULL', it is not used.
1132              `sizep' specifies the pointer to a variable to which the size of
1133              the  file  is  assigned.   If  it  is  `NULL',  it  is not used.
1134              `mtimep' specifies the pointer to a variable to which  the  last
1135              modified  time  of the file is assigned.  If it is `NULL', it is
1136              not used.  If successful, the return value is true, else, false.
1137              False is returned when the file does not exist or the permission
1138              is denied.
1139
1140       The function `cbremove' is used in order to remove a file or  a  direc‐
1141       tory and its sub ones recursively.
1142
1143       int cbremove(const char *name);
1144              `name' specifies the name of a file or a directory.  If success‐
1145              ful, the return value is true, else, false.  False  is  returned
1146              when the file does not exist or the permission is denied.
1147
1148       The  function `cburlbreak' is used in order to break up a URL into ele‐
1149       ments.
1150
1151       CBMAP *cburlbreak(const char *str);
1152              `str' specifies the pointer to a  string  of  URL.   The  return
1153              value  is  a  map handle.  Each key of the map is the name of an
1154              element.  The key "self" specifies  the  URL  itself.   The  key
1155              "scheme"  specifies  the  scheme.   The key "host" specifies the
1156              host of the server.  The key "port" specifies the port number of
1157              the  server.  The key "authority" specifies the authority infor‐
1158              mation.  The key "path" specifies the path of the resource.  The
1159              key  "file"  specifies  the file name without the directory sec‐
1160              tion.  The key "query" specifies  the  query  string.   The  key
1161              "fragment"  specifies the fragment string.  Supported schema are
1162              HTTP, HTTPS, FTP, and FILE.  Absolute URL and relative  URL  are
1163              supported.   Because  the  handle  of the return value is opened
1164              with the function `cbmapopen', it  should  be  closed  with  the
1165              function `cbmapclose' if it is no longer in use.
1166
1167       The  runction `cburlresolve' is used in order to resolve a relative URL
1168       with another absolute URL.
1169
1170       char *cburlresolve(const char *base, const char *target);
1171              `base' specifies an absolute URL of a base  location.   `target'
1172              specifies  a URL to be resolved.  The return value is a resolved
1173              URL.  If the target URL is relative, a new URL of relative loca‐
1174              tion  from  the  base location is returned.  Else, a copy of the
1175              target URL is returned.  Because the region of the return  value
1176              is  allocated with the `malloc' call, it should be released with
1177              the `free' call if it is no longer in use.
1178
1179       The function `cburlencode' is used in order to encode a  serial  object
1180       with URL encoding.
1181
1182       char *cburlencode(const char *ptr, int size);
1183              `ptr'  specifies  the pointer to a region.  `size' specifies the
1184              size of the region.  If it is negative,  the  size  is  assigned
1185              with  `strlen(ptr)'.   The  return  value  is the pointer to the
1186              result string.  Because the region of the return value is  allo‐
1187              cated  with  the  `malloc'  call, it should be released with the
1188              `free' call if it is no longer in use.
1189
1190       The function `cburldecode' is used in order to decode a string  encoded
1191       with URL encoding.
1192
1193       char *cburldecode(const char *str, int *sp);
1194              `str'  specifies the pointer to a source string.  `sp' specifies
1195              the pointer to a variable to which the size of the region of the
1196              return value is assigned.  If it is `NULL', it is not used.  The
1197              return value is  the  pointer  to  the  region  of  the  result.
1198              Because  an  additional  zero code is appended at the end of the
1199              region of the return value, the return value can be treated as a
1200              character  string.   Because  the  region of the return value is
1201              allocated with the `malloc' call, it should be released with the
1202              `free' call if it is no longer in use.
1203
1204       The  function `cbbaseencode' is used in order to encode a serial object
1205       with Base64 encoding.
1206
1207       char *cbbaseencode(const char *ptr, int size);
1208              `ptr' specifies the pointer to a region.  `size'  specifies  the
1209              size  of  the  region.   If it is negative, the size is assigned
1210              with `strlen(ptr)'.  The return value  is  the  pointer  to  the
1211              result  string.  Because the region of the return value is allo‐
1212              cated with the `malloc' call, it should  be  released  with  the
1213              `free' call if it is no longer in use.
1214
1215       The function `cbbasedecode' is used in order to decode a string encoded
1216       with Base64 encoding.
1217
1218       char *cbbasedecode(const char *str, int *sp);
1219              `str' specifies the pointer to a source string.  `sp'  specifies
1220              the pointer to a variable to which the size of the region of the
1221              return value is assigned.  If it is `NULL', it is not used.  The
1222              return  value  is  the  pointer  to  the  region  of the result.
1223              Because an additional zero code is appended at the  end  of  the
1224              region of the return value, the return value can be treated as a
1225              character string.  Because the region of  the  return  value  is
1226              allocated with the `malloc' call, it should be released with the
1227              `free' call if it is no longer in use.
1228
1229       The function `cbquoteencode' is used in order to encode a serial object
1230       with quoted-printable encoding.
1231
1232       char *cbquoteencode(const char *ptr, int size);
1233              `ptr'  specifies  the pointer to a region.  `size' specifies the
1234              size of the region.  If it is negative,  the  size  is  assigned
1235              with  `strlen(ptr)'.   The  return  value  is the pointer to the
1236              result string.  Because the region of the return value is  allo‐
1237              cated  with  the  `malloc'  call, it should be released with the
1238              `free' call if it is no longer in use.
1239
1240       The function `cbquotedecode' is  used  in  order  to  decode  a  string
1241       encoded with quoted-printable encoding.
1242
1243       char *cbquotedecode(const char *str, int *sp);
1244              `str'  specifies the pointer to a source string.  `sp' specifies
1245              the pointer to a variable to which the size of the region of the
1246              return value is assigned.  If it is `NULL', it is not used.  The
1247              return value is  the  pointer  to  the  region  of  the  result.
1248              Because  an  additional  zero code is appended at the end of the
1249              region of the return value, the return value can be treated as a
1250              character  string.   Because  the  region of the return value is
1251              allocated with the `malloc' call, it should be released with the
1252              `free' call if it is no longer in use.
1253
1254       The  function  `cbmimebreak' is used in order to split a string of MIME
1255       into headers and the body.
1256
1257       char *cbmimebreak(const char *ptr, int size, CBMAP *attrs, int *sp);
1258              `ptr' specifies the pointer to the region of MIME data.   `size'
1259              specifies  the  size of the region.  If it is negative, the size
1260              is assigned with `strlen(ptr)'.  `attrs' specifies a map  handle
1261              to store attributes.  If it is `NULL', it is not used.  Each key
1262              of the map is an attribute name uncapitalized.   `sp'  specifies
1263              the pointer to a variable to which the size of the region of the
1264              return value is assigned.  If it is `NULL', it is not used.  The
1265              return  value  is  the pointer of the body data.  If the content
1266              type is defined, the attribute map has the key "TYPE" specifying
1267              the  type.   If  the  character  encoding  is  defined,  the key
1268              "CHARSET" specifies the encoding name.  If the  boundary  string
1269              of  multipart  is  defined,  the  key  "BOUNDARY"  specifies the
1270              string.  If the content disposition is defined, the key  "DISPO‐
1271              SITION"  specifies  the direction.  If the file name is defined,
1272              the key "FILENAME" specifies the name.  If the attribute name is
1273              defined,  the key "NAME" specifies the name.  Because the region
1274              of the return value is allocated  with  the  `malloc'  call,  it
1275              should  be  released  with the `free' call if it is no longer in
1276              use.
1277
1278       The function `cbmimeparts' is used in order to split multipart data  of
1279       MIME into its parts.
1280
1281       CBLIST *cbmimeparts(const char *ptr, int size, const char *boundary);
1282              `ptr'  specifies  the pointer to the region of multipart data of
1283              MIME.  `size' specifies the size of the region.  If it is  nega‐
1284              tive, the size is assigned with `strlen(ptr)'.  `boundary' spec‐
1285              ifies the pointer to the region of  the  boundary  string.   The
1286              return  value is a list handle.  Each element of the list is the
1287              string of a part.  Because the handle of  the  return  value  is
1288              opened  with the function `cblistopen', it should be closed with
1289              the function `cblistclose' if it is no longer in use.
1290
1291       The function `cbmimeencode' is used in order to encode  a  string  with
1292       MIME encoding.
1293
1294       char *cbmimeencode(const char *str, const char *encname, int base);
1295              `str'  specifies the pointer to a string.  `encname' specifies a
1296              string of the name of the character encoding.  The return  value
1297              is  the  pointer to the result string.  `base' specifies whether
1298              to use Base64 encoding.  If it  is  false,  quoted-printable  is
1299              used.   Because the region of the return value is allocated with
1300              the `malloc' call, it should be released with the `free' call if
1301              it is no longer in use.
1302
1303       The function `cbmimedecode' is used in order to decode a string encoded
1304       with MIME encoding.
1305
1306       char *cbmimedecode(const char *str, char *enp);
1307              `str' specifies the pointer to an encoded string.  `enp'  speci‐
1308              fies  the pointer to a region into which the name of encoding is
1309              written.  If it is `NULL', it is not used.  The size of the buf‐
1310              fer  should be equal to or more than 32 bytes.  The return value
1311              is the pointer to the result string.  Because the region of  the
1312              return  value  is allocated with the `malloc' call, it should be
1313              released with the `free' call if it is no longer in use.
1314
1315       The function `cbcsvrows' is used in order to split a string of CSV into
1316       rows.
1317
1318       CBLIST *cbcsvrows(const char *str);
1319              `str' specifies the pointer to the region of an CSV string.  The
1320              return value is a list handle.  Each element of the  list  is  a
1321              string  of  a  row.   Because  the handle of the return value is
1322              opened with the function `cblistopen', it should be closed  with
1323              the function `cblistclose' if it is no longer in use.  The char‐
1324              acter encoding of the input string should  be  US-ASCII,  UTF-8,
1325              ISO-8859-*,   EUC-*,   or   Shift_JIS.   Being  compatible  with
1326              MS-Excel, these functions for CSV  can  handle  cells  including
1327              such meta characters as comma, between double quotation marks.
1328
1329       The function `cbcsvcells' is used in order to split the string of a row
1330       of CSV into cells.
1331
1332       CBLIST *cbcsvcells(const char *str);
1333              `str' specifies the pointer to the region of a row of CSV.   The
1334              return  value is a list handle.  Each element of the list is the
1335              unescaped string of a cell of the row.  Because  the  handle  of
1336              the  return  value  is opened with the function `cblistopen', it
1337              should be closed with the function `cblistclose'  if  it  is  no
1338              longer in use.
1339
1340       The function `cbcsvescape' is used in order to escape a string with the
1341       meta characters of CSV.
1342
1343       char *cbcsvescape(const char *str);
1344              `str' specifies the pointer to the  region  of  a  string.   The
1345              return  value  is the pointer to the escaped string sanitized of
1346              meta characters.  Because the region  of  the  return  value  is
1347              allocated with the `malloc' call, it should be released with the
1348              `free' call if it is no longer in use.
1349
1350       The function `cbcsvunescape' is used in order to unescape a string with
1351       the escaped meta characters of CSV.
1352
1353       char *cbcsvunescape(const char *str);
1354              `str'  specifies the pointer to the region of a string with meta
1355              characters.  The return value is the pointer  to  the  unescaped
1356              string.   Because  the  region  of the return value is allocated
1357              with the `malloc' call, it should be released  with  the  `free'
1358              call if it is no longer in use.
1359
1360       The  function  `cbxmlbreak'  is  used in order to split a string of XML
1361       into tags and text sections.
1362
1363       CBLIST *cbxmlbreak(const char *str, int cr);
1364              `str' specifies the pointer to the  region  of  an  XML  string.
1365              `cr'  specifies whether to remove comments.  The return value is
1366              a list handle.  Each element of the list is the string of a  tag
1367              or  a  text  section.  Because the handle of the return value is
1368              opened with the function `cblistopen', it should be closed  with
1369              the function `cblistclose' if it is no longer in use.  The char‐
1370              acter encoding of the input string should  be  US-ASCII,  UTF-8,
1371              ISO-8859-*,  EUC-*,  or  Shift_JIS.  Because these functions for
1372              XML are not XML parser with validation check, it can handle also
1373              HTML and SGML.
1374
1375       The function `cbxmlattrs' is used in order to get the map of attributes
1376       of an XML tag.
1377
1378       CBMAP *cbxmlattrs(const char *str);
1379              `str' specifies the pointer to the region of a tag string.   The
1380              return  value  is a map handle.  Each key of the map is the name
1381              of an attribute.  Each value is unescaped.  You can get the name
1382              of  the tag with the key of an empty string.  Because the handle
1383              of the return value is opened with the function `cbmapopen',  it
1384              should  be  closed  with  the  function `cbmapclose' if it is no
1385              longer in use.
1386
1387       The function `cbxmlescape' is used in order to escape a string with the
1388       meta characters of XML.
1389
1390       char *cbxmlescape(const char *str);
1391              `str'  specifies  the  pointer  to  the region of a string.  The
1392              return value is the pointer to the escaped string  sanitized  of
1393              meta characters.  This function converts only `&', `<', `>', and
1394              `"'.  Because the region of the return value is  allocated  with
1395              the `malloc' call, it should be released with the `free' call if
1396              it is no longer in use.
1397
1398       The function `cbxmlunescape' is used in order to unescape a string with
1399       the entity references of XML.
1400
1401       char *cbxmlunescape(const char *str);
1402              `str'  specifies  the  pointer  to  the region of a string.  The
1403              return value is the pointer to the unescaped string.  This func‐
1404              tion  restores  only  `&amp;',  `&lt;',  `&gt;',  and  `&quot;'.
1405              Because the region of the return value  is  allocated  with  the
1406              `malloc'  call, it should be released with the `free' call if it
1407              is no longer in use.
1408
1409       The function `cbdeflate' is used in order to compress a  serial  object
1410       with ZLIB.
1411
1412       char *cbdeflate(const char *ptr, int size, int *sp);
1413              `ptr'  specifies  the pointer to a region.  `size' specifies the
1414              size of the region.  If it is negative,  the  size  is  assigned
1415              with `strlen(ptr)'.  `sp' specifies the pointer to a variable to
1416              which the size of the region of the return  value  is  assigned.
1417              If  successful,  the  return  value is the pointer to the result
1418              object, else, it is `NULL'.  Because the region  of  the  return
1419              value is allocated with the `malloc' call, it should be released
1420              with the `free' call if it is no longer in use.   This  function
1421              is available only if QDBM was built with ZLIB enabled.
1422
1423       The function `cbinflate' is used in order to decompress a serial object
1424       compressed with ZLIB.
1425
1426       char *cbinflate(const char *ptr, int size, int *sp);
1427              `ptr' specifies the pointer to a region.  `size'  specifies  the
1428              size of the region.  `sp' specifies the pointer to a variable to
1429              which the size of the region of the return  value  is  assigned.
1430              If  it  is  `NULL',  it  is not used.  If successful, the return
1431              value is the pointer to the result object, else, it  is  `NULL'.
1432              Because  an  additional  zero code is appended at the end of the
1433              region of the return value, the return value can be treated as a
1434              character  string.   Because  the  region of the return value is
1435              allocated with the `malloc' call, it should be released with the
1436              `free'  call if it is no longer in use.  This function is avail‐
1437              able only if QDBM was built with ZLIB enabled.
1438
1439       The function `cbgzencode' is used in order to compress a serial  object
1440       with GZIP.
1441
1442       char *cbgzencode(const char *ptr, int size, int *sp);
1443              `ptr'  specifies  the pointer to a region.  `size' specifies the
1444              size of the region.  If it is negative,  the  size  is  assigned
1445              with `strlen(ptr)'.  `sp' specifies the pointer to a variable to
1446              which the size of the region of the return  value  is  assigned.
1447              If  successful,  the  return  value is the pointer to the result
1448              object, else, it is `NULL'.  Because the region  of  the  return
1449              value is allocated with the `malloc' call, it should be released
1450              with the `free' call if it is no longer in use.   This  function
1451              is available only if QDBM was built with ZLIB enabled.
1452
1453       The  function  `cbgzdecode'  is  used  in  order to decompress a serial
1454       object compressed with GZIP.
1455
1456       char *cbgzdecode(const char *ptr, int size, int *sp);
1457              `ptr' specifies the pointer to a region.  `size'  specifies  the
1458              size of the region.  `sp' specifies the pointer to a variable to
1459              which the size of the region of the return  value  is  assigned.
1460              If  it  is  `NULL',  it  is not used.  If successful, the return
1461              value is the pointer to the result object, else, it  is  `NULL'.
1462              Because  an  additional  zero code is appended at the end of the
1463              region of the return value, the return value can be treated as a
1464              character  string.   Because  the  region of the return value is
1465              allocated with the `malloc' call, it should be released with the
1466              `free'  call if it is no longer in use.  This function is avail‐
1467              able only if QDBM was built with ZLIB enabled.
1468
1469       The function `cbgetcrc' is used in order to get the CRC32 checksum of a
1470       serial object.
1471
1472       unsigned int cbgetcrc(const char *ptr, int size);
1473              `ptr'  specifies  the pointer to a region.  `size' specifies the
1474              size of the region.  If it is negative,  the  size  is  assigned
1475              with  `strlen(ptr)'.   The return value is the CRC32 checksum of
1476              the object.  This function is available only if QDBM  was  built
1477              with ZLIB enabled.
1478
1479       The function `cblzoencode' is used in order to compress a serial object
1480       with LZO.
1481
1482       char *cblzoencode(const char *ptr, int size, int *sp);
1483              `ptr' specifies the pointer to a region.  `size'  specifies  the
1484              size  of  the  region.   If it is negative, the size is assigned
1485              with `strlen(ptr)'.  `sp' specifies the pointer to a variable to
1486              which  the  size  of the region of the return value is assigned.
1487              If successful, the return value is the  pointer  to  the  result
1488              object,  else,  it  is `NULL'.  Because the region of the return
1489              value is allocated with the `malloc' call, it should be released
1490              with  the  `free' call if it is no longer in use.  This function
1491              is available only if QDBM was built with LZO enabled.
1492
1493       The function `cblzodecode' is used in  order  to  decompress  a  serial
1494       object compressed with LZO.
1495
1496       char *cblzodecode(const char *ptr, int size, int *sp);
1497              `ptr'  specifies  the pointer to a region.  `size' specifies the
1498              size of the region.  `sp' specifies the pointer to a variable to
1499              which  the  size  of the region of the return value is assigned.
1500              If it is `NULL', it is not  used.   If  successful,  the  return
1501              value  is  the pointer to the result object, else, it is `NULL'.
1502              Because an additional zero code is appended at the  end  of  the
1503              region of the return value, the return value can be treated as a
1504              character string.  Because the region of  the  return  value  is
1505              allocated with the `malloc' call, it should be released with the
1506              `free' call if it is no longer in use.  This function is  avail‐
1507              able only if QDBM was built with LZO enabled.
1508
1509       The  function `cbbzencode' is used in order to compress a serial object
1510       with BZIP2.
1511
1512       char *cbbzencode(const char *ptr, int size, int *sp);
1513              `ptr' specifies the pointer to a region.  `size'  specifies  the
1514              size  of  the  region.   If it is negative, the size is assigned
1515              with `strlen(ptr)'.  `sp' specifies the pointer to a variable to
1516              which  the  size  of the region of the return value is assigned.
1517              If successful, the return value is the  pointer  to  the  result
1518              object,  else,  it  is `NULL'.  Because the region of the return
1519              value is allocated with the `malloc' call, it should be released
1520              with  the  `free' call if it is no longer in use.  This function
1521              is available only if QDBM was built with BZIP2 enabled.
1522
1523       The function `cbbzdecode' is used  in  order  to  decompress  a  serial
1524       object compressed with BZIP2.
1525
1526       char *cbbzdecode(const char *ptr, int size, int *sp);
1527              `ptr'  specifies  the pointer to a region.  `size' specifies the
1528              size of the region.  `sp' specifies the pointer to a variable to
1529              which  the  size  of the region of the return value is assigned.
1530              If it is `NULL', it is not  used.   If  successful,  the  return
1531              value  is  the pointer to the result object, else, it is `NULL'.
1532              Because an additional zero code is appended at the  end  of  the
1533              region of the return value, the return value can be treated as a
1534              character string.  Because the region of  the  return  value  is
1535              allocated with the `malloc' call, it should be released with the
1536              `free' call if it is no longer in use.  This function is  avail‐
1537              able only if QDBM was built with BZIP2 enabled.
1538
1539       The function `cbiconv' is used in order to convert the character encod‐
1540       ing of a string.
1541
1542       char *cbiconv(const char *ptr, int size, const char *icode, const  char
1543       *ocode, int *sp, int *mp);
1544              `ptr'  specifies  the pointer to a region.  `size' specifies the
1545              size of the region.  If it is negative,  the  size  is  assigned
1546              with  `strlen(ptr)'.   `icode' specifies the name of encoding of
1547              the input string.  `ocode' specifies the name of encoding of the
1548              output  string.   `sp'  specifies  the  pointer to a variable to
1549              which the size of the region of the return  value  is  assigned.
1550              If  it is `NULL', it is not used.  `mp' specifies the pointer to
1551              a variable to which the number of missing characters by  failure
1552              of conversion is assigned.  If it is `NULL', it is not used.  If
1553              successful, the return  value  is  the  pointer  to  the  result
1554              object,  else, it is `NULL'.  Because an additional zero code is
1555              appended at the end of the  region  of  the  return  value,  the
1556              return  value can be treated as a character string.  Because the
1557              region of the return value is allocated with the `malloc'  call,
1558              it should be released with the `free' call if it is no longer in
1559              use.  This function is available only if  QDBM  was  built  with
1560              ICONV enabled.
1561
1562       The  function  `cbencname' is used in order to detect the encoding of a
1563       string automatically.
1564
1565       const char *cbencname(const char *ptr, int size);
1566              `ptr' specifies the pointer to a region.  `size'  specifies  the
1567              size  of  the  region.   If it is negative, the size is assigned
1568              with `strlen(ptr)'.  The return  value  is  the  string  of  the
1569              encoding   name   of   the  string.   As  it  stands,  US-ASCII,
1570              ISO-2022-JP, Shift_JIS, CP932, EUC-JP, UTF-8, UTF-16,  UTF-16BE,
1571              and UTF-16LE are supported.  If none of them matches, ISO-8859-1
1572              is selected.  This function is available only if QDBM was  built
1573              with ICONV enabled.
1574
1575       The  function  `cbjetlag'  is  used  in order to get the jet lag of the
1576       local time in seconds.
1577
1578       int cbjetlag(void);
1579              The return value is the jet lag of the local time in seconds.
1580
1581       The function `cbcalendar' is used in order to get the Gregorian  calen‐
1582       dar of a time.
1583
1584       void cbcalendar(time_t t, int jl, int *yearp, int *monp, int *dayp, int
1585       *hourp, int *minp, int *secp);
1586              `t' specifies a source time.  If it  is  negative,  the  current
1587              time  is specified.  `jl' specifies the jet lag of a location in
1588              seconds.  `yearp' specifies the pointer to a variable  to  which
1589              the  year is assigned.  If it is `NULL', it is not used.  `monp'
1590              specifies the pointer to  a  variable  to  which  the  month  is
1591              assigned.  If it is `NULL', it is not used.  1 means January and
1592              12 means December.  `dayp' specifies the pointer to  a  variable
1593              to  which the day of the month is assigned.  If it is `NULL', it
1594              is not used.  `hourp' specifies the pointer  to  a  variable  to
1595              which  the  hours is assigned.  If it is `NULL', it is not used.
1596              `minp' specifies the pointer to a variable to which the  minutes
1597              is assigned.  If it is `NULL', it is not used.  `secp' specifies
1598              the pointer to a variable to which the seconds is assigned.   If
1599              it is `NULL', it is not used.
1600
1601       The function `cbdayofweek' is used in order to get the day of week of a
1602       date.
1603
1604       int cbdayofweek(int year, int mon, int day);
1605              `year' specifies the year of a date.  `mon' specifies the  month
1606              of  the  date.  `day' specifies the day of the date.  The return
1607              value is the day of week of the date.   0  means  Sunday  and  6
1608              means Saturday.
1609
1610       The  function  `cbdatestrwww'  is used in order to get the string for a
1611       date in W3CDTF.
1612
1613       char *cbdatestrwww(time_t t, int jl);
1614              `t' specifies a source time.  If it  is  negative,  the  current
1615              time  is specified.  `jl' specifies the jet lag of a location in
1616              seconds.  The return value is the string of the date  in  W3CDTF
1617              (YYYY-MM-DDThh:mm:ddTZD).   Because  the  region  of  the return
1618              value is allocated with the `malloc' call, it should be released
1619              with the `free' call if it is no longer in use.
1620
1621       The  function  `cbdatestrhttp' is used in order to get the string for a
1622       date in RFC 1123 format.
1623
1624       char *cbdatestrhttp(time_t t, int jl);
1625              `t' specifies a source time.  If it  is  negative,  the  current
1626              time  is specified.  `jl' specifies the jet lag of a location in
1627              seconds.  The return value is the string of the date in RFC 1123
1628              format  (Wdy,  DD-Mon-YYYY hh:mm:dd TZD).  Because the region of
1629              the return value is allocated with the `malloc' call, it  should
1630              be released with the `free' call if it is no longer in use.
1631
1632       The  function `cbstrmktime' is used in order to get the time value of a
1633       date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123).
1634
1635       time_t cbstrmktime(const char *str);
1636              `str' specifies a date string in decimal,  hexadecimal,  W3CDTF,
1637              or  RFC  822  (1123).  The return value is the time value of the
1638              date or -1 if the format is invalid.  Decimal can be trailed  by
1639              "s"  for  in  seconds, "m" for in minutes, "h" for in hours, and
1640              "d" for in days.
1641
1642       The function `cbproctime' is used in order to get user and system  pro‐
1643       cessing times.
1644
1645       void cbproctime(double *usrp, double *sysp);
1646              `usrp'  specifies  the  pointer  to a variable to which the user
1647              processing time is assigned.  If it is `NULL', it is  not  used.
1648              The  unit of time is seconds.  `sysp' specifies the pointer to a
1649              variable to which the system processing time is assigned.  If it
1650              is `NULL', it is not used.  The unit of time is seconds.
1651
1652       The  function `cbstdiobin' is used in order to ensure that the standard
1653       I/O is binary mode.
1654
1655       void cbstdiobin(void);
1656              This function is useful for applications on dosish file systems.
1657
1658       Functions of Cabin except for `cbglobalgc' are thread-safe as long as a
1659       handle  is  not accessed by threads at the same time, on the assumption
1660       that `errno', `malloc', and so on are thread-safe.
1661
1662

SEE ALSO

1664       qdbm(3), depot(3), curia(3), relic(3),  hovel(3),  villa(3),  odeum(3),
1665       ndbm(3), gdbm(3)
1666
1667
1668
1669Man Page                          2004-04-22                          CABIN(3)
Impressum