CABIN(3)

📦 version 1.8.78, in debian bookworm, debian trixie, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 CABIN(3) — the utility API of QDBM ✨

okay bestie, gather round, because this is the Quick Database Manager girlies' favorite little toolbox and her name is Cabin 🎀

🌸 NAME 🌸

Cabin — the utility API of QDBM 🫶

✨ SYNOPSIS ✨

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

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

void *cbmalloc(size_t size);

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

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

void cbfree(void *ptr);

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

void cbggcsweep(void);

int cbvmemavail(size_t size);

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

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

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

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

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

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

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

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

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

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

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

char *cbstrtoupper(char *str);

char *cbstrtolower(char *str);

char *cbstrtrim(char *str);

char *cbstrsqzspc(char *str);

int cbstrcountutf(const char *str);

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

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

CBDATUM *cbdatumdup(const CBDATUM *datum);

void cbdatumclose(CBDATUM *datum);

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

const char *cbdatumptr(const CBDATUM *datum);

int cbdatumsize(const CBDATUM *datum);

void cbdatumsetsize(CBDATUM *datum, int size);

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

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

CBLIST *cblistopen(void);

CBLIST *cblistdup(const CBLIST *list);

void cblistclose(CBLIST *list);

int cblistnum(const CBLIST *list);

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

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

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

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

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

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

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

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

void cblistsort(CBLIST *list);

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

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

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

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

CBMAP *cbmapopen(void);

CBMAP *cbmapdup(CBMAP *map);

void cbmapclose(CBMAP *map);

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

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

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

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

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

void cbmapiterinit(CBMAP *map);

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

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

int cbmaprnum(const CBMAP *map);

CBLIST *cbmapkeys(CBMAP *map);

CBLIST *cbmapvals(CBMAP *map);

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

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

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

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

CBHEAP *cbheapdup(CBHEAP *heap);

void cbheapclose(CBHEAP *heap);

int cbheapnum(CBHEAP *heap);

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

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

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

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

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

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

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

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

CBLIST *cbreadlines(const char *name);

CBLIST *cbdirlist(const char *name);

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

int cbremove(const char *name);

CBMAP *cburlbreak(const char *str);

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

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

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

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

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

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

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

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

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

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

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

CBLIST *cbcsvrows(const char *str);

CBLIST *cbcsvcells(const char *str);

char *cbcsvescape(const char *str);

char *cbcsvunescape(const char *str);

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

CBMAP *cbxmlattrs(const char *str);

char *cbxmlescape(const char *str);

char *cbxmlunescape(const char *str);

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

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

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

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

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

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

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

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

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

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

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

int cbjetlag(void);

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

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

char *cbdatestrwww(time_t t, int jl);

char *cbdatestrhttp(time_t t, int jl);

time_t cbstrmktime(const char *str);

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

void cbstdiobin(void);

💖 DESCRIPTION 💖

okay so Cabin is the utility API, and she is literally the girl who does everything behind the scenes ✨ She hands you memory allocating functions, sorting functions, extensible datum, array list, hash map, heap array, and so on — all of it built so you can handle records easily on memory 🧚 This API also features parsing MIME, CSV, and XML, and she comes with various types of encoding and decoding too. it's giving overachiever and we love that for her 💅

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

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

A pointer to CBDATUM is used as a handle of an extensible datum 💖 A datum handle is opened with the function cbdatumopen and closed with cbdatumclose. A pointer to CBLIST is used as a handle of an array list 🌸 A list handle is opened with the function cblistopen and closed with cblistclose. A pointer to CBMAP is used as a handle of a hash map 🦋 A map handle is opened with the function cbmapopen and closed with cbmapclose. A pointer to CBHEAP is used as a handle of a heap array 👑 A heap handle is opened with the function cbheapopen and closed with cbheapclose.

bestie. listen. You should not refer directly to any member of each handles. no peeking inside the handle's personal business, fr fr 🙈 she has boundaries and you're gonna respect them.

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

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

The function cbmalloc is used in order to allocate a region on memory ✨

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

The function cbrealloc is used in order to re-allocate a region on memory ✨

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

The function cbmemdup is used in order to duplicate a region on memory ✨

char *cbmemdup(const char *ptr, int size); — ptr specifies the pointer to a region. size specifies the size of the region. If it is negative, the size is assigned with strlen(ptr). The return value is the pointer to the allocated region of the duplicate. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string 🌈 Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. 🎀

The function cbfree is used in order to free a region on memory ✨

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

The function cbglobalgc is used in order to register the pointer or handle of an object to the global garbage collector 🧹✨

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

The function cbggcsweep is used in order to exercise the global garbage collector explicitly 🧹

void cbggcsweep(void); — sweeps the global garbage collector, bestie. ⚠️ big one: after you call this, you should not use objects that were registered to the global garbage collector any longer. And no, that's not a bug — it's because the global garbage collector is initialized and you can register new objects into it. So like, out with the old, in with the fresh ✨
int cbvmemavail(size_t size); — vibe-checks whether you can actually allocate virtual memory. size says how big the region you wanna allocate newly is. The return value is true if the allocation should be a success, or false if it's gonna flop. Basically a "can we tho?" check 🫶

void cbisort(void *base, int nmemb, int size, int(*compar)(const void *, const void *)); — sorts an array using insert sort. base is the pointer to an array. nmemb is the number of elements in the array. size is the size of each element. compar is the pointer to the comparing function. The two arguments of that comparing function are the pointers of the elements. The comparing function should return positive if the former is big, negative if the latter is big, and 0 if both are equal. Fr fr, insert sort is only useful if most of the elements have already been sorted — it's giving "almost done, just tidying up" 💅
void cbssort(void *base, int nmemb, int size, int(*compar)(const void *, const void *)); — sorts an array using shell sort. base is the pointer to an array. nmemb is the number of elements of the array. size is the size of each element. compar is the pointer to the comparing function. The two arguments are the pointers of the elements. The comparing function should return positive if the former is big, negative if the latter is big, 0 if both are equal. If most elements have been sorted, shell sort may be faster than heap sort or quick sort. lowkey underrated 👑
void cbhsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *)); — sorts an array using heap sort. base is the pointer to an array. nmemb is the number of elements of the array. size is the size of each element. compar is the pointer to the comparing function. The two arguments are the pointers of the elements. The comparing function should return positive if the former is big, negative if the latter is big, 0 if both are equal. Heap sort is robust against bias of input — it does not care about your messy data, it simply does not — but quick sort is faster in most cases. So heap sort is the reliable bestie, not the fastest one 😌
void cbqsort(void *base, int nmemb, int size, int(*compar)(const void *, const void *)); — sorts an array using quick sort. base is the pointer to an array. nmemb is the number of elements of the array. size is the size of each element. compar is the pointer to the comparing function. The two arguments are the pointers of the elements. The comparing function should return positive if the former is big, negative if the latter is big, 0 if both are equal. It IS sensitive to bias of input, but quick sort is the fastest sorting algorithm. main character energy, periodt 🔥

int cbstricmp(const char *astr, const char *bstr); — compares two strings with case insensitive evaluation. astr specifies the pointer of one string. astr specifies the pointer of the other string. (yes, the page says astr twice — we're keeping it 100% as written 🙈). The return value is positive if the former is big, negative if the latter is big, and 0 if both are equivalent. Upper cases and lower cases of alphabets in ASCII code are not distinguished, so "HI" and "hi" are literally the same thing to it 💖
int cbstrfwmatch(const char *str, const char *key); — checks whether a string begins with a key. str is the pointer of a target string. key is the pointer of a forward matching key string. The return value is true if the target string begins with the key, else it's false. Forward match, no cap ✨
int cbstrfwimatch(const char *str, const char *key); — same thing but with case insensitive evaluation 🎀 str is the pointer of a target string. key is the pointer of a forward matching key string. The return value is true if the target string begins with the key, else false. Upper cases and lower cases of alphabets in ASCII code are not distinguished.
int cbstrbwmatch(const char *str, const char *key); — checks whether a string ends with a key. str is the pointer of a target string. key is the pointer of a backward matching key string. The return value is true if the target string ends with the key, else false. Backwards match, she's looking from the tail 🦋
int cbstrbwimatch(const char *str, const char *key); — the ending-with-a-key check, but case insensitive 💜 str is the pointer of a target string. key is the pointer of a backward matching key string. The return value is true if the target string ends with the key, else false. Upper cases and lower cases of alphabets in ASCII code are not distinguished.

char *cbstrstrkmp(const char *haystack, const char *needle); — locates a substring in a string using the KMP method. haystack is the pointer of a target string. needle is the pointer of a substring to be found. The return value is the pointer to the beginning of the substring, or NULL if the substring is not found. Ngl though: in most cases, strstr as a built-in function of the compiler is faster than this function. Still iconic for the algorithm girlies 🧚
char *cbstrstrbm(const char *haystack, const char *needle); — locates a substring in a string using the BM method. haystack is the pointer of a target string. needle is the pointer of a substring to be found. The return value is the pointer to the beginning of the substring, or NULL if the substring is not found. Same tea as above: in most cases, strstr as a built-in function of the compiler is faster than this function. 😭

char *cbstrtoupper(char *str); — converts the letters of a string to upper case. str is the pointer of a string to convert. The return value is the pointer to the string. SCREAM IT 📣
char *cbstrtolower(char *str); — converts the letters of a string to lower case. str is the pointer of a string to convert. The return value is the pointer to the string. gentle whispering mode 🤫
char *cbstrtrim(char *str); — cuts space characters at the head or tail of a string. str is the pointer of a string to convert. The return value is the pointer to the string. Goodbye to the unnecessary whitespace bestie ✂️✨
char *cbstrsqzspc(char *str); — squeezes space characters in a string and trims it. str is the pointer of a string to convert. The return value is the pointer to the string. It's giving "clean your room" but for whitespace 💅
int cbstrcountutf(const char *str); — counts the number of characters in a string of UTF-8. str is the pointer of a string of UTF-8. The return value is the number of characters in the string. Character counting, not byte counting, iykyk 🌸
char *cbstrcututf(char *str, int num); — cuts a string of UTF-8 at the specified number of characters. str is the pointer of a string of UTF-8. num is the number of characters to be kept. The return value is the pointer to the string. Snip snip, keep num of them 🎀

✨ the datum era ✨

CBDATUM *cbdatumopen(const char *ptr, int size); — gets a datum handle. ptr is the pointer to the region of the initial content — and if it's NULL, an empty datum is created instead, no biggie. size is the size of the region, and if it's negative, the size is assigned with strlen(ptr). The return value is a datum handle. Brand new baby datum 🫶
CBDATUM *cbdatumdup(const CBDATUM *datum); — copies a datum. datum is a datum handle. The return value is a new datum handle. twin where have you been 💜
void cbdatumclose(CBDATUM *datum); — frees a datum handle. datum is a datum handle. Because the region of a closed handle is released, it becomes impossible to use the handle afterwards. RIP to that handle, it is GONE. Don't touch it after, bestie, fr 😭
void cbdatumcat(CBDATUM *datum, const char *ptr, int size); — concatenates a datum and a region. datum is a datum handle. ptr is the pointer to the region to be appended. size is the size of the region, and if it's negative, the size is assigned with strlen(ptr). Glue it on, it belongs there now 🔥
const char *cbdatumptr(const CBDATUM *datum); — gets the pointer of the region of a datum. datum is a datum handle. The return value is the pointer of the region of a datum. And 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. Convenient much? 👑
int cbdatumsize(const CBDATUM *datum); — gets the size of the region of a datum. datum is a datum handle. The return value is the size of the region of a datum. Just the number, no drama 💖
void cbdatumsetsize(CBDATUM *datum, int size); — changes the size of the region of a datum. datum is a datum handle. size is the new size of the region. If the new size is bigger than the old one, the surplus region is filled with zero codes. Grow, glow up, get padded with zeros ✨
cbdatumprintf — performs formatted output into a datum. That's the whole vibe of it 🌈

Okay so boom, we're in the function buffet now, and there are a LOT of them, so grab a snack 🍓

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

format is your printf-style format string, bestie. You can use the conversion character % with all these flag characters: s, d, o, u, x, X, c, e, E, f, g, G, @, ?, :, %. The tea on the weird ones:

@ — does the same thing as s but it escapes meta characters of XML. lowkey a lifesaver ✨
? — does the same thing as s but it escapes meta characters of URL.
: — does the same thing as s but it performs MIME encoding as UTF-8. it's giving encoding queen 💅

Every other conversion character just works exactly like with each original. no notes.

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

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

datum specifies a datum handle. sp specifies the pointer to a variable to which the size of the region of the return value is assigned. If it's NULL, it is not used. The return value is the pointer to the region of the datum.

Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string — slay, free string behaviour 🎀

Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. And because the region of the original datum is released, it should not be released again. double-free is NOT the vibe, bestie 😭

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

CBLIST *cblistopen(void);

The return value is a list handle. that's it, that's the function, iconic 👑

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

CBLIST *cblistdup(const CBLIST *list);

list specifies a list handle. The return value is a new list handle. copy-paste energy but make it ✨official✨

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

void cblistclose(CBLIST *list);

list specifies a list handle. Because the region of a closed handle is released, it becomes impossible to use the handle. so like… once it's closed, it's closed. don't come back for it 🙈

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

int cblistnum(const CBLIST *list);

list specifies a list handle. The return value is the number of elements of the list. counting era 🔢

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

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

list specifies a list handle. index specifies the index of an element. sp specifies the pointer to a variable to which the size of the region of the return value is assigned. If it's NULL, it is not used.

The return value is the pointer to the region of the element. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. If index is equal to or more than the number of elements, the return value is NULL. so no out-of-bounds nonsense, the function just says nope 💀

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

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

list specifies a list handle. ptr specifies the pointer to the region of an element. size specifies the size of the region. If it is negative, the size is assigned with strlen(ptr). negative size = "just figure it out yourself" behaviour, love that for you 🫶

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

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

list specifies a list handle. sp specifies the pointer to a variable to which the size of the region of the return value is assigned. If it's NULL, it is not used.

The return value is the pointer to the region of the value. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. If the list is empty, the return value is NULL. nothing to pop? nothing to return. periodt 💅

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

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

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

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

list specifies a list handle. sp specifies the pointer to a variable to which the size of the region of the return value is assigned. If it's NULL, it is not used.

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

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

list specifies a list handle. index specifies the index of an element. ptr specifies the pointer to the region of the element. size specifies the size of the region. If it is negative, the size is assigned with strlen(ptr). inserting yourself into the conversation, literally ✨

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

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

The return value is the pointer to the region of the value. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. If index is equal to or more than the number of elements, no element is removed and the return value is NULL. the list looked at your index and said "bestie what" 💀

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

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

list specifies a list handle. index specifies the index of an element. ptr specifies the pointer to the region of the new content. size specifies the size of the new content. If it is negative, the size is assigned with strlen(ptr). If index is equal to or more than the number of elements, this function has no effect. it simply does nothing. no drama, no error, just silence 🙈

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

void cblistsort(CBLIST *list);

list specifies a list handle. Quick sort is used for sorting. organizing your whole life in lexical order, main character energy 👑

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

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

list specifies a list handle. ptr specifies the pointer to the region of a key. size specifies the size of the region. If it is negative, the size is assigned with strlen(ptr).

The return value is the index of a corresponding element or -1 if there is no corresponding element. If two or more elements corresponds, the former returns. so it goes one by one and stops at the first match — methodical queen 🔍

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

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

list specifies a list handle. It should be sorted in lexical order. ptr specifies the pointer to the region of a key. size specifies the size of the region. If it is negative, the size is assigned with strlen(ptr).

The return value is the index of a corresponding element or -1 if there is no corresponding element. If two or more elements corresponds, which returns is not defined. so if your list isn't sorted, bestie, it's over — that's not a vibe check you're gonna pass 😭

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

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

list specifies a list handle. sp specifies the pointer to a variable to which the size of the region of the return value is assigned.

The return value is the pointer to the region of the result serial region. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. turning your whole list into a glow-up byte array ✨

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

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

ptr specifies the pointer to a byte array. size specifies the size of the region. The return value is a new list handle. it's giving resurrection arc 🦋

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

CBMAP *cbmapopen(void);

The return value is a map handle. brand new map, brand new era 🗺️

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

CBMAP *cbmapdup(CBMAP *map);

map specifies a map handle. The return value is a new map handle. The iterator of the source map is initialized. so heads up, the original's iterator gets reset — it's not staying where it was, bestie 🎀

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

void cbmapclose(CBMAP *map);

map specifies a map handle. Because the region of a closed handle is released, it becomes impossible to use the handle. closed for business, no re-entry 💅

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

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

map specifies a map handle. kbuf specifies the pointer to the region of a key. ksiz specifies the size of the region of the key. If it is negative, the size is assigned with strlen(kbuf). vbuf specifies the pointer to the region of a value. vsiz specifies the size of the region of the value. If it is negative, the size is assigned with strlen(vbuf). over specifies whether the value of the duplicated record is overwritten or not.

If over is false and the key is duplicated, the return value is false, else, it is true. so over is literally the "do I let you overwrite my ex's contact info" switch 🌸

cbmapputcat — okay bestie, this one is giving append-era 💅 it glues a value onto the end of the value of a record that already exists.

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

map — a map handle.
kbuf — pointer to the region of a key.
ksiz — size of the region of the key. If it's negative, the size is assigned with strlen(kbuf) ✨
vbuf — pointer to the region of a value.
vsiz — size of the region of the value. If it's negative, the size is assigned with strlen(vbuf).
And if there's no corresponding record? A new record is created, no cap 💖

cbmapout — the begone function 🦋 deletes a record from a map.

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

map — a map handle.
kbuf — pointer to the region of a key.
ksiz — size of the region of the key. Negative? Then the size is assigned with strlen(kbuf).
Return value: true if it worked, iconically. false comes back when no record corresponds to the specified key — it's giving ghosted 😭

cbmapget — the gimme that function 🔥 pulls a record out of a map.

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

map — a map handle.
kbuf — pointer to the region of a key.
ksiz — size of the region of the key. If negative, size is assigned with strlen(kbuf).
sp — pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used 🙈
On success you get the pointer to the region of the value of the corresponding record. NULL is returned when no record corresponds.
And 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 — cute, convenient, slay ✨

cbmapmove — moves a record to the edge of a map 👑

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

map — a map handle.
kbuf — pointer to the region of a key.
ksiz — size of the region of the key. If it's negative, the size is assigned with strlen(kbuf).
head — the destination, which is head if it's true, or tail if else 💫
Return value is true if successful. false is returned when no record corresponds to the specified key.

cbmapiterinit — sets up the iterator of a map, main character energy 🌸

void cbmapiterinit(CBMAP *map);

map — a map handle.
The iterator is used in order to access the key of every record stored in a map. That's literally its whole job 🎀

cbmapiternext — grabs the next key from the iterator of a map 🦋

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

map — a map handle.
sp — pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used.
On success, the return value is the pointer to the region of the next key; else it's NULL. NULL is returned when no record is to be get out of the iterator.
Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string 💖
And the order of iteration is assured to be the same of the one of storing — consistent queen, we love to see it ⭐

cbmapiterval — gets the value binded to the key you fetched from the iterator of a map 🫶

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

kbuf — pointer to the region of a iteration key.
sp — pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used.
The return value is the pointer to the region of the value of the corresponding record.
And again — an additional zero code is appended at the end of the region of the return value, so it can be treated as a character string 💅

cbmaprnum — the count check, bestie 🔢 how many records are in a map?

int cbmaprnum(const CBMAP *map);

map — a map handle.
The return value is the number of the records stored in the map. Simple, iconic, no notes 💜

cbmapkeys — gets you a list handle containing all the keys in a map 🌈

CBLIST *cbmapkeys(CBMAP *map);

map — a map handle.
The return value is the list handle contains all keys in the map.
> Heads up though — because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use. Clean up after yourself, bestie 🧹

cbmapvals — same vibe, but for all the values in a map 🍓

CBLIST *cbmapvals(CBMAP *map);

map — a map handle.
The return value is the list handle contains all values in the map.
> Same deal — because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use 💖

cbmapdump — serializes a map into a byte array ✨

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

map — a map handle.
sp — pointer to a variable that the size of the region of the return value gets assigned to.
The return value is the pointer to the region of the result serial region.
> Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. Not optional, bestie, that's a leak otherwise 😭

cbmapload — redintegrate a serialized map 🦋 (yes, "redintegrate", that's the word, we're being fancy today)

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

ptr — pointer to a byte array.
size — size of the region.
The return value is a new map handle. Fresh out the box, obsessed 👑

cbmaploadone — extracts a single record out of a serialized map 🔥

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

ptr — pointer to a byte array.
size — size of the region.
kbuf — pointer to the region of a key.
ksiz — size of the region of the key. If it is negative, the size is assigned with strlen(kbuf).
sp — pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used.
On success, the return value is the pointer to the region of the value of the corresponding record. NULL is returned when no record corresponds.
Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string ✨

cbheapopen — gets you a heap handle 🎀

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

size — the size of each record.
max — the maximum number of records in the heap.
compar — pointer to the comparing function. The two arguments specify the pointers of records. The comparing function should return positive if the former is big, negative if the latter is big, and 0 if both are equal. Rules are rules 💅
The return value is a heap handle.

cbheapdup — copies a heap 🌸

CBHEAP *cbheapdup(CBHEAP *heap);

heap — a heap handle.
The return value is a new heap handle. Dupe era 💖

cbheapclose — closes a heap handle 🦋

void cbheapclose(CBHEAP *heap);

heap — a heap handle.
> Because the region of a closed handle is released, it becomes impossible to use the handle. She's gone, don't come back for her 💀

cbheapnum — how many records are stored in a heap? 🔢

int cbheapnum(CBHEAP *heap);

heap — a heap handle.
The return value is the number of the records stored in the heap. Quick lil vibe check ⭐

cbheapinsert — inserts a record into a heap 🫶

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

heap — a heap handle.
ptr — pointer to the region of a record.
The return value is true if the record is added, else false.
> If the new record is bigger than the biggest existing regord, the new record is not added 😤
> And if the new record is added and the number of records exceeds the maximum number, the biggest existing record is removed. Survival of the fittest, no cap.

cbheapval — gets you the pointer to the region of a record in a heap 💜

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

heap — a heap handle.
index — the index of a record.
The return value is the pointer to the region of the record. If index is equal to or more than the number of records, the return value is NULL 🙈
> Note that records are organized by the nagative order the comparing function. Yep, we said it 👀

cbheaptomalloc — converts a heap into an allocated region ✨

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

heap — a heap handle.
np — pointer to a variable that the number of records of the return value gets assigned to. If it's NULL, it is not used.
The return value is the pointer to the region of the heap. Records are sorted 🎀
> Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.
> And because the region of the original heap is released, it should not be released again. Double-free is not the vibe, bestie 😭

cbsprintf — allocates a formatted string on memory 🌈

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

okay so bestie, cbsprintf is the printf-flavored glow-up you didn't know you needed ✨ format is your printf-like format string, and the conversion character % can be used with flag characters like d, o, u, x, X, e, E, f, g, G, c, s, and % — yes, all of them, she contains multitudes 💅 You can tuck specifiers for the field length and the precision in between the conversion characters and the flag characters, and those specifiers are made of decimal characters, ., +, -, and the space character. The rest of the arguments get used according to the format string. What you get back is the pointer to the allocated region of the result string. And because that region was allocated with the malloc call, it should be released with the free call if it's no longer in use — no leaving her on read, she's not going to free herself 😭

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

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

str is the pointer to a source string. pairs is the handle of a map composed of pairs of replacement — the key of each pair is the pattern before replacement and its value is the pattern after replacement. The return value is the pointer to the allocated region of the result string. And you already know the drill: that region was allocated with the malloc call, so it should be released with the free call if it is no longer in use 🫶

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

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

ptr is the pointer to the region of the source content. size is the size of that region — and if it's negative, the size is assigned with strlen(ptr). delim is a string containing delimiting characters; if it's NULL, zero code is used as a delimiter. The return value is a list handle 🎀 And heads up: if two delimiters are successive, it's assumed that an empty element is between the two (she's keeping the empty seats at the table, respect it). Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose.

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

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

name is the name of a file — if it's NULL, the standard input is specified. sp is the pointer to a variable to which the size of the region of the return value is assigned; if it's NULL, it is not used. The return value is the pointer to the allocated region of the read data. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string — cute AND functional, we love her 💖 And because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.

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

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

name is the name of a file — if it's NULL, the standard output is specified. ptr is the pointer to the region of the source content, and size is the size of that region. If size is negative, the size is assigned with strlen(ptr). If it's successful, the return value is true, else it's false. And real talk: if the file exists, it is overwritten. Else, a new file is created. She does not ask permission, she simply writes 💀

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

CBLIST *cbreadlines(const char *name);

name is the name of a file — if it's NULL, the standard input is specified. The return value is a list handle of the lines if successful, else it is NULL. Line separators are cut out (gone, deleted, not invited to the party). Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use 🌸

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

CBLIST *cbdirlist(const char *name);

name is the name of a directory. The return value is a list handle of names if successful, else it is NULL. Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use 🦋

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

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

name is the name of a file or a directory. dirp is the pointer to a variable to which whether the file is a directory is assigned — if it's NULL, it is not used. sizep is the pointer to a variable to which the size of the file is assigned — if it's NULL, it is not used. mtimep is the pointer to a variable to which the last modified time of the file is assigned — if it's NULL, it is not used. If successful, the return value is true, else, false. And false gets returned when the file does not exist or the permission is denied — the two classic reasons, every single time 🙈

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

int cbremove(const char *name);

name is the name of a file or a directory. If successful, the return value is true, else, false. False is returned when the file does not exist or the permission is denied. Note the "recursively" bestie — she is taking the whole tree down with her, main character energy, do not point her at anything you love 👑

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

CBMAP *cburlbreak(const char *str);

str is the pointer to a string of URL. The return value is a map handle, and each key of the map is the name of an element. Let's run through the whole cast 🎬

The key "self" specifies the URL itself.
The key "scheme" specifies the scheme.
The key "host" specifies the host of the server.
The key "port" specifies the port number of the server.
The key "authority" specifies the authority information.
The key "path" specifies the path of the resource.
The key "file" specifies the file name without the directory section.
The key "query" specifies the query string.
The key "fragment" specifies the fragment string.

Supported schema are HTTP, HTTPS, FTP, and FILE. Absolute URL and relative URL are supported. Because the handle of the return value is opened with the function cbmapopen, it should be closed with the function cbmapclose if it is no longer in use ⭐

The function cburlresolve is used in order to resolve a relative URL with another absolute URL.

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

base is an absolute URL of a base location, and target is a URL to be resolved. The return value is a resolved URL. If the target URL is relative, a new URL of relative location from the base location is returned. Else, a copy of the target URL is returned. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use ✨

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

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

ptr is the pointer to a region, and size is the size of that region. If size is negative, the size is assigned with strlen(ptr). The return value is the pointer to the result string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use 💜

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

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

str is the pointer to a source string. sp is the pointer to a variable to which the size of the region of the return value is assigned — if it's NULL, it is not used. The return value is the pointer to the region of the result. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use 🌈

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

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

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

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

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

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

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

Okay so we're mid-glow-up through the function list, and bestie, this next batch? It's giving text-processing royalty. 💅 Let's go.

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

str — the pointer to a source string. The one you wanna decode, babe.
sp — the pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it just… doesn't get used. No stress. 🫶

The return value is the pointer to the region of the result. And because an additional zero code is appended at the end of the region of the return value, you can legit treat the return value as a character string. ✨ Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. (clean up after yourself, iykyk 🧹)

The function cbmimebreak is used in order to split a string of MIME into headers and the body. Lowkey its whole personality.

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

ptr — the pointer to the region of MIME data.
size — the size of the region. If it's negative, the size is assigned with strlen(ptr). (nega-what? yeah, it just measures it for you ✨)
attrs — a map handle to store attributes. If it's NULL, it is not used. Every key of the map is an attribute name, uncapitalized. 👑
sp — the pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used.

The return value is the pointer of the body data. And check out what the attribute map can hold, because this is the good part:

If the content type is defined, the attribute map has the key "TYPE" specifying the type.
If the character encoding is defined, the key "CHARSET" specifies the encoding name.
If the boundary string of multipart is defined, the key "BOUNDARY" specifies the string.
If the content disposition is defined, the key "DISPOSITION" specifies the direction.
If the file name is defined, the key "FILENAME" specifies the name.
If the attribute name is defined, the key "NAME" specifies the name.

Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. 💖

The function cbmimeparts is used in order to split multipart data of MIME into its parts. Slicing it up like a lil fruit salad 🍓

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

ptr — the pointer to the region of multipart data of MIME.
size — the size of the region. If it's negative, the size is assigned with strlen(ptr).
boundary — the pointer to the region of the boundary string.

The return value is a list handle. Each element of the list is the string of a part. And because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use. 🎀

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

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

str — the pointer to a string.
encname — a string of the name of the character encoding.
base — specifies whether to use Base64 encoding. If it's false, quoted-printable is used. (two lanes, pick one 🛣️)

The return value is the pointer to the result string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. ✨

The function cbmimedecode is used in order to decode a string encoded with MIME encoding. The un-encoding, the reversal, the comeback. 💫

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

str — the pointer to an encoded string.
enp — the pointer to a region into which the name of encoding is written. If it's NULL, it is not used. The size of the buffer should be equal to or more than 32 bytes. (fr fr, do NOT undersize this one, bestie 😭)

The function cbcsvrows is used in order to split a string of CSV into rows. Spreadsheet girlies rise 🙈

CBLIST *cbcsvrows(const char *str);

str — the pointer to the region of an CSV string.

The return value is a list handle. Each element of the list is a string of a row. Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use.

The character encoding of the input string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS. And being compatible with MS-Excel, these functions for CSV can handle cells including such meta characters as comma, between double quotation marks. (yes bestie, the Excel vibes were studied 👑)

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

CBLIST *cbcsvcells(const char *str);

str — the pointer to the region of a row of CSV.

The return value is a list handle. Each element of the list is the unescaped string of a cell of the row. Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use. 🦋

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

char *cbcsvescape(const char *str);

str — the pointer to the region of a string.

The return value is the pointer to the escaped string sanitized of meta characters. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. ✨

The function cbcsvunescape is used in order to unescape a string with the escaped meta characters of CSV. Round two, opposite direction. 🔁

char *cbcsvunescape(const char *str);

str — the pointer to the region of a string with meta characters.

The return value is the pointer to the unescaped string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. 💖

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

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

str — the pointer to the region of an XML string.
cr — specifies whether to remove comments. (bye bye, comments ✂️)

The return value is a list handle. Each element of the list is the string of a tag or a text section. Because the handle of the return value is opened with the function cblistopen, it should be closed with the function cblistclose if it is no longer in use.

The character encoding of the input string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS. And because these functions for XML are not XML parser with validation check, it can handle also HTML and SGML. (no validation gatekeeping here, it's chill like that 🌈)

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

CBMAP *cbxmlattrs(const char *str);

str — the pointer to the region of a tag string.

The return value is a map handle. Each key of the map is the name of an attribute. Each value is unescaped. You can get the name of the tag with the key of an empty string. 👀 Because the handle of the return value is opened with the function cbmapopen, it should be closed with the function cbmapclose if it is no longer in use. 🎀

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

char *cbxmlescape(const char *str);

str — the pointer to the region of a string.

The return value is the pointer to the escaped string sanitized of meta characters. This function converts only &, <, >, and ". (just those four, don't come for it 💅) Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. ✨

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

char *cbxmlunescape(const char *str);

str — the pointer to the region of a string.

The return value is the pointer to the unescaped string. This function restores only &, <, >, and ". Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use. 💜

The function cbdeflate is used in order to compress a serial object with ZLIB. Squish it down, bestie 🗜️

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

ptr — the pointer to a region.
size — the size of the region. If it's negative, the size is assigned with strlen(ptr).
sp — the pointer to a variable that the size of the region of the return value gets assigned to.

If successful, the return value is the pointer to the result object, else, it is NULL. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.

⚠️ This function is available only if QDBM was built with ZLIB enabled. No ZLIB, no deflate, that's the whole rule. 😭

The function cbinflate is used in order to decompress a serial object compressed with ZLIB. The un-squish. 🫧

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

ptr — the pointer to a region.
size — the size of the region.
sp — the pointer to a variable that the size of the region of the return value gets assigned to. If it's NULL, it is not used.

If successful, the return value is the pointer to the result object, else, it is NULL. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string. Because the region of the return value is allocated with the malloc call, it should be released with the free call if it is no longer in use.

⚠️ This function is available only if QDBM was built with ZLIB enabled. Same deal as its deflate bestie. 💀

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

okay bestie, next up we got the compression girlies and the time/encoding divas 💖 buckle up, this is a long one but it's literally all vibes once you get it.

the gzip duo 🎀

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

so ptr is your pointer to a region (the stuff you wanna squash), and size is how big that region is. and here's the cute part: if size is negative, it just gets assigned with strlen(ptr) instead — she's flexible like that 💅. sp points to a variable where the size of the return value's region gets dropped. if it all works out you get back a pointer to the result object, and if not? NULL, bestie, sad. and because that return region was allocated with the malloc call, you gotta release it with the free call once you're done with it. also: this function is available only if QDBM was built with ZLIB enabled. no ZLIB, no gz, periodt.

and the function cbgzdecode is the one you reach for to decompress a serial object that got compressed with GZIP 🫶

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

ptr is the pointer to a region, size is the size of that region. sp points to a variable that gets assigned the size of the return value's region — but if it's NULL, it's just not used, no biggie. if it works, you get a pointer to the result object; if not, NULL. and because an additional zero code is appended at the end of the return region, you can literally treat the return value as a character string ✨. same deal as before: allocated with malloc, so free it when you're done. available only if QDBM was built with ZLIB enabled.

the CRC32 moment ⭐

the function cbgetcrc is how you get the CRC32 checksum of a serial object.

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

ptr = pointer to a region, size = size of the region. if size is negative, it's assigned with strlen(ptr). the return value is the CRC32 checksum of the object. available only if QDBM was built with ZLIB enabled.

the LZO duo 🦋

the function cblzoencode is used in order to compress a serial object with LZO.

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

ptr specifies the pointer to a region. size specifies the size of the region. if it's negative, size gets assigned with strlen(ptr). sp points to a variable that gets the size of the return value's region. if successful, return value = pointer to the result object, else NULL. allocated with the malloc call so release it with free when you're done. available only if QDBM was built with LZO enabled.

the function cblzodecode is used in order to decompress a serial object compressed with LZO.

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

ptr = pointer to a region. size = size of the region. sp points to a variable that gets the size of the return value's region — if it's NULL, it's not used. if successful, you get the pointer to the result object, else NULL. an additional zero code is appended at the end of the return region so yes, you can treat it as a character string 💅. allocated with malloc, so free it when you're not using it anymore. available only if QDBM was built with LZO enabled.

the BZIP2 duo 🌸

the function cbbzencode is used in order to compress a serial object with BZIP2.

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

ptr = pointer to a region. size = size of the region, and if it's negative it gets assigned with strlen(ptr). sp points to a variable that receives the size of the return value's region. success → pointer to the result object; otherwise NULL. malloc'd, so free it later. available only if QDBM was built with BZIP2 enabled.

the function cbbzdecode is used in order to decompress a serial object compressed with BZIP2.

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

ptr = pointer to a region. size = size of the region. sp points to a variable getting the size of the return value's region, or NULL if you don't care. success → pointer to the result object, else NULL. an additional zero code is appended at the end so it can be treated as a character string ✨. malloc'd, free it when done. available only if QDBM was built with BZIP2 enabled.

the encoding glow-up era 🌈

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

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

okay so ptr = pointer to a region. size = size of the region, and if it's negative it's assigned with strlen(ptr). icode = the name of the encoding of the input string, ocode = the name of the encoding of the output string (glow-up from icode to ocode, iconic). sp points to a variable that gets the size of the return value's region, or NULL if unused. mp points to a variable that gets the number of missing characters by failure of conversion — or NULL if unused. if successful, return value is the pointer to the result object, else NULL. an additional zero code is appended at the end so it's usable as a character string 🎀. malloc'd → free it later. available only if QDBM was built with ICONV enabled.

the function cbencname is used in order to detect the encoding of a string automatically. she just knows 💅

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

ptr = pointer to a region. size = size of the region, negative means it's assigned with strlen(ptr). the return value is the string of the encoding name of the string. as it stands, these are the supported girlies: US-ASCII, ISO-2022-JP, Shift_JIS, CP932, EUC-JP, UTF-8, UTF-16, UTF-16BE, and UTF-16LE. if none of them matches, ISO-8859-1 is selected (she's the default bestie fr fr). available only if QDBM was built with ICONV enabled.

clocking in — time functions 🕰️

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

int cbjetlag(void);

the return value is the jet lag of the local time in seconds. that's it, that's the whole vibe ✈️

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

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

t specifies a source time — and if it's negative, the current time is specified. jl specifies the jet lag of a location in seconds. then we got the whole pointer squad, and every single one of them is optional (NULL = not used, no stress):

yearp → the year
monp → the month. and listen: 1 means January and 12 means December, don't @ me
dayp → the day of the month
hourp → the hours
minp → the minutes
secp → the seconds

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

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

year = the year of a date, mon = the month, day = the day. the return value is the day of week of the date, where 0 means Sunday and 6 means Saturday. periodt.

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

char *cbdatestrwww(time_t t, int jl);

t = a source time, and if it's negative the current time is specified. jl = the jet lag of a location in seconds. the return value is the string of the date in W3CDTF, formatted like this: YYYY-MM-DDThh:mm:ddTZD 💖. malloc'd region → release it with the free call when you're done.

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

char *cbdatestrhttp(time_t t, int jl);

t = a source time, negative means current time. jl = the jet lag of a location in seconds. the return value is the string of the date in RFC 1123 format: Wdy, DD-Mon-YYYY hh:mm:dd TZD. malloc'd → free it when it's no longer in use.

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

time_t cbstrmktime(const char *str);

str specifies a date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123). the return value is the time value of the date, or -1 if the format is invalid. and here's a lil cheat code: decimal can be trailed by "s" for in seconds, "m" for in minutes, "h" for in hours, and "d" for in days 👑

the function cbproctime is used in order to get user and system processing times.

✨ `cbproctime` ✨

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

bestie, this one is your little timekeeper 🕰️ — it hands you back the processing time, split into the two flavours.

usrp — this is the pointer to a variable where the user processing time gets dropped off. if you pass NULL, it's just not used, no drama, no problem. 🫶 and heads up: the unit of time here is seconds.
sysp — same deal but for the system processing time. pointer to the variable it lands in, and if it's NULL, it is not used. also in seconds. ✨

so yeah, you can ask for one, the other, or both. iconic flexibility, honestly. 💅

💖 `cbstdiobin` 💖

the function cbstdiobin exists so you can make absolutely sure the standard I/O is in binary mode. like, it's giving "please don't mangle my bytes" energy. 😭

void cbstdiobin(void);

this one is useful for applications on dosish file systems — you know the type, the ones that get a lil confused about what a newline is. 🌸

real talk though — every Cabin function except cbglobalgc is thread-safe, but only as long as a handle is not accessed by threads at the same time. that's the whole condition. 🚨 and this all rides on the assumption that errno, malloc, and so on are thread-safe themselves. iykyk. 👑

🌈 SEE ALSO 🌈

and that's a wrap on the whole Cabin page, bestie!! 🎀 this is the Man Page for CABIN(3), dated 2004-04-22 — a certified classic, lowkey vintage, highkey still slaying. go forth and build ur database, queen. 👑💜🦋

📦 where this page comes from

debian bookworm: libqdbm-dev 1.8.78-12+b1 · LGPL-2.1-or-later
debian trixie: libqdbm-dev 1.8.78-13+b3 · LGPL-2.1-or-later
fedora 43: qdbm-devel 1.8.78-71.fc43 · LGPL-2.1-or-later
fedora 43: qdbm-devel 1.8.78-71.fc43 · LGPL-2.1-or-later
fedora 44: qdbm-devel 1.8.78-75.fc44 · LGPL-2.1-or-later
fedora 44: qdbm-devel 1.8.78-75.fc44 · LGPL-2.1-or-later
ubuntu jammy: libqdbm-dev 1.8.78-11build3 · LGPL-2.1-or-later
ubuntu noble: libqdbm-dev 1.8.78-12.1build2 · LGPL-2.1-or-later
ubuntu questing: libqdbm-dev 1.8.78-13build2
ubuntu resolute: libqdbm-dev 1.8.78-15 · LGPL-2.1-or-later
ubuntu stonking: libqdbm-dev 1.8.78-16build1 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms