TCHDB(3)

📦
version 1.4.48 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

tchdb — the hash database API, bestie. That's the TCHDB(3) manual. 💅

✨ DESCRIPTION ✨

A hash database is literally a file containing a hash table, and it's handled with the hash database API. No cap. 🗂️✨

To use the hash database API, include tcutil.h, tchdb.h, and related standard header files. Usually, write the following description near the front of a source file:

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

Objects whose type is pointer to TCHDB are used to handle hash databases. A hash database object is created with the function tchdbnew and is deleted with the function tchdbdel. To avoid memory leak, it is important to delete every object when it is no longer in use. 🧹💖

Before operations to store or retrieve records, it is necessary to open a database file and connect the hash database object to it. The function tchdbopen is used to open a database file and the function tchdbclose is used to close the database file. To avoid data missing or corruption, it is important to close every database file when it is no longer in use. It is forbidden for multiple database objects in a process to open the same database at the same time. 🚫👯‍♀️

💖 API 💖

tchdberrmsg — need the message string that goes with an error code? This is your girl. 📢

const char *tchdberrmsg(int ecode);
  • ecode specifies the error code.
  • The return value is the message string of the error code.

tchdbnew — creates a shiny new hash database object. 🌟

TCHDB *tchdbnew(void);
  • The return value is the new hash database object.

tchdbdel — deletes a hash database object. 🗑️

void tchdbdel(TCHDB *hdb);
  • hdb specifies the hash database object.
  • If the database is not closed, it is closed implicitly.
  • Note that the deleted object and its derivatives can not be used anymore.

tchdbecode — gets the last happened error code of a hash database object. 🚨

int tchdbecode(TCHDB *hdb);
  • hdb specifies the hash database object.
  • The return value is the last happened error code.
  • The following error codes are defined:
    • TCESUCCESS — success 🎉
    • TCETHREAD — threading error 🧵
    • TCEINVALID — invalid operation 🙅
    • TCENOFILE — file not found 🕵️
    • TCENOPERM — no permission 🔒
    • TCEMETA — invalid meta data 🧠
    • TCERHEAD — invalid record header 📄
    • TCEOPEN — open error 🚪
    • TCECLOSE — close error 🚪
    • TCETRUNC — trunc error ✂️
    • TCESYNC — sync error 🔄
    • TCESTAT — stat error 📊
    • TCESEEK — seek error 🔍
    • TCEREAD — read error 📖
    • TCEWRITE — write error ✍️
    • TCEMMAP — mmap error 🗺️
    • TCELOCK — lock error 🔐
    • TCEUNLINK — unlink error 🔗
    • TCERENAME — rename error 🏷️
    • TCEMKDIR — mkdir error 📁
    • TCERMDIR — rmdir error 🗑️
    • TCEKEEP — existing record 👯
    • TCENOREC — no record found 🫥
    • TCEMISC — miscellaneous error 🎲

tchdbsetmutex — sets mutual exclusion control of a hash database object for threading. 🔐

bool tchdbsetmutex(TCHDB *hdb);
  • hdb specifies the hash database object which is not opened.
  • If successful, the return value is true, else, it is false.
  • Note that the mutual exclusion control of the database should be set before the database is opened.

tchdbtune — sets the tuning parameters of a hash database object. 🎛️

bool tchdbtune(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t
fpow, uint8_t opts);
  • hdb specifies the hash database object which is not opened.
  • bnum specifies the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is 16381. Suggested size of the bucket array is about from 0.5 to 4 times of the number of all records to be stored.
  • apow specifies the size of record alignment by power of 2. If it is negative, the default value is specified. The default value is 4 standing for 2^4=16.
  • fpow specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the default value is specified. The default value is 10 standing for 2^10=1024.
  • opts specifies options by bitwise-or:
    • HDBTLARGE — the size of the database can be larger than 2GB by using 64-bit bucket array
    • HDBTDEFLATE — each record is compressed with Deflate encoding
    • HDBTBZIP — each record is compressed with BZIP2 encoding
    • HDBTTCBS — each record is compressed with TCBS encoding
  • If successful, the return value is true, else, it is false.
  • Note that the tuning parameters should be set before the database is opened.

tchdbsetcache — sets the caching parameters of a hash database object. 🧠💾

bool tchdbsetcache(TCHDB *hdb, int32_t rcnum);
  • hdb specifies the hash database object which is not opened.
  • rcnum specifies the maximum number of records to be cached. If it is not more than 0, the record cache is disabled. It is disabled by default.
  • If successful, the return value is true, else, it is false.
  • Note that the caching parameters should be set before the database is opened.

tchdbsetxmsiz — sets the size of the extra mapped memory of a hash database object. 🗺️

bool tchdbsetxmsiz(TCHDB *hdb, int64_t xmsiz);
  • hdb specifies the hash database object which is not opened.
  • xmsiz specifies the size of the extra mapped memory. If it is not more than 0, the extra mapped memory is disabled. The default size is 67108864.
  • If successful, the return value is true, else, it is false.
  • Note that the mapping parameters should be set before the database is opened.

tchdbsetdfunit — sets the unit step number of auto defragmentation of a hash database object. 🧹✨

bool tchdbsetdfunit(TCHDB *hdb, int32_t dfunit);
  • hdb specifies the hash database object which is not opened.
  • dfunit specifies the unit step number. If it is not more than 0, the auto defragmentation is disabled. It is disabled by default.
  • If successful, the return value is true, else, it is false.
  • Note that the defragmentation parameters should be set before the database is opened.

tchdbopen — opens a database file and connects a hash database object. 🚪🔑

bool tchdbopen(TCHDB *hdb, const char *path, int omode);
  • hdb specifies the hash database object which is not opened.
  • path specifies the path of the database file.
  • omode specifies the connection mode: HDBOWRITER as a writer, HDBOREADER as a reader.
  • If the mode is HDBOWRITER, the following may be added by bitwise-or:
    • HDBOCREAT — creates a new database if not exist
    • HDBOTRUNC — creates a new database regardless if one exists
    • HDBOTSYNC — every transaction synchronizes updated contents with the device
  • Both of HDBOREADER and HDBOWRITER can be added to by bitwise-or:
    • HDBONOLCK — opens the database file without file locking
    • HDBOLCKNB — locking is performed without blocking
  • If successful, the return value is true, else, it is false.

tchdbclose — closes a hash database object. 🚪💨

bool tchdbclose(TCHDB *hdb);
  • hdb specifies the hash database object.
  • If successful, the return value is true, else, it is false.
  • Update of a database is assured to be written when the database is closed. If a writer opens a database but does not close it appropriately, the database will be broken. 😭💔

tchdbput — stores a record into a hash database object. 📥

bool tchdbput(TCHDB *hdb, const void *kbuf, int ksiz, const void
*vbuf, int vsiz);
  • hdb specifies the hash database object connected as a writer.
  • kbuf specifies the pointer to the region of the key.
  • ksiz specifies the size of the region of the key.
  • vbuf specifies the pointer to the region of the value.
  • vsiz specifies the size of the region of the value.
  • If successful, the return value is true, else, it is false.
  • If a record with the same key exists in the database, it is overwritten.

tchdbput2 — stores a string record into a hash database object. 📝

bool tchdbput2(TCHDB *hdb, const char *kstr, const char *vstr);
  • hdb specifies the hash database object connected as a writer.
  • kstr specifies the string of the key.
  • vstr specifies the string of the value.
  • If successful, the return value is true, else, it is false.
  • If a record with the same key exists in the database, it is overwritten.

tchdbputkeep — stores a new record into a hash database object.

🫶 tchdbputkeep — the "no, don't overwrite my fave" function

bool tchdbputkeep(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
  • hdb — bestie, this is the hash database object, and it has to be connected as a writer. No read-only energy allowed here.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

If it works, the return value is true. If it doesn't, it's false.

💅 Real talk: if a record with the same key already exists in the database, this function literally does nothing. No effect. It just looks at it and goes "not my problem". Iconic of it honestly.

🌸 tchdbputkeep2 — same vibe, but strings

bool tchdbputkeep2(TCHDB *hdb, const char *kstr, const char *vstr);

The function tchdbputkeep2 is the one you call to store a new string record into a hash database object.

  • hdb — the hash database object, and yes, it must be connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

Return value is true on success, false otherwise.

🎀 Same rule as its sibling: if a record with the same key exists in the database, this function has no effect. Periodt.

💖 tchdbputcat — append girlie

bool tchdbputcat(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

The function tchdbputcat is used to concatenate a value at the end of the existing record in a hash database object. It's giving "and also…" energy.

  • hdb — the hash database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true if it worked, false if it didn't.

🦋 Plot twist: if there's no corresponding record, a brand new record gets created. So it never leaves you on read.

🌈 tchdbputcat2 — append, but string edition

bool tchdbputcat2(TCHDB *hdb, const char *kstr, const char *vstr);

The function tchdbputcat2 is the one that concatenates a string value at the end of the existing record in a hash database object.

  • hdb — the hash database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true on success, false otherwise.

🦋 And again: no corresponding record? A new record is created. Bestie behavior fr.

⚡ tchdbputasync — main character speedrun mode

bool tchdbputasync(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

The function tchdbputasync stores a record into a hash database object in asynchronous fashion. It does not wait around. It has places to be.

  • hdb — the hash database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value.

true if successful, false if not.

If a record with the same key exists in the database, it gets overwritten. And here's the tea: records passed to this function are accumulated into the inner buffer and wrote into the file at a blast. 💥

🌟 tchdbputasync2 — async, string remix

bool tchdbputasync2(TCHDB *hdb, const char *kstr, const char *vstr);

The function tchdbputasync2 stores a string record into a hash database object in asynchronous fashion. Same speedrun energy, just with strings.

  • hdb — the hash database object, connected as a writer.
  • kstr — the string of the key.
  • vstr — the string of the value.

true on success, false otherwise.

If a record with the same key exists, it is overwritten. Records passed here get accumulated into the inner buffer and wrote into the file at a blast. Same deal. 💥

🗑️ tchdbout — it's giving removal

bool tchdbout(TCHDB *hdb, const void *kbuf, int ksiz);

The function tchdbout removes a record from a hash database object. Unfollow, block, delete.

  • hdb — the hash database object, connected as a writer.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.

Return value is true if it worked, false if it didn't.

🗑️✨ tchdbout2 — removal, but the key is a string

bool tchdbout2(TCHDB *hdb, const char *kstr);

The function tchdbout2 removes a string record from a hash database object.

  • hdb — the hash database object, connected as a writer.
  • kstr — the string of the key.

true if successful, false if not.

🔍 tchdbget — the retrieval

void *tchdbget(TCHDB *hdb, const void *kbuf, int ksiz, int *sp);

The function tchdbget retrieves a record from a hash database object.

  • hdb — the hash database object. (No writer requirement here, slay, read away.)
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • sp — pointer to the variable into which the size of the region of the return value is assigned.

If it works, the return value is the pointer to the region of the value of the corresponding record. NULL comes back if no record corresponds.

Because an additional zero code is appended at the end of the region of the return value, you can treat the return value as a character string. 🎀

⚠️ And because the region of the return value is allocated with the malloc call, you must release it with the free call when it's no longer in use. Don't leak, bestie. It's not cute.

🔍💖 tchdbget2 — retrieval, string style

char *tchdbget2(TCHDB *hdb, const char *kstr);

The function tchdbget2 retrieves a string record from a hash database object.

  • hdb — the hash database object.
  • kstr — the string of the key.

If successful, the return value is the string of the value of the corresponding record. NULL if no record corresponds.

⚠️ Same warning, same energy: the region of the return value is allocated with the malloc call, so free it when you're done. 🫶

🧺 tchdbget3 — retrieval but you brought your own buffer

int tchdbget3(TCHDB *hdb, const void *kbuf, int ksiz, void *vbuf, int max);

The function tchdbget3 retrieves a record from a hash database object and writes the value into a buffer.

  • hdb — the hash database object.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.
  • vbuf — pointer to the buffer into which the value of the corresponding record is written.
  • max — the size of the buffer.

If it works, the return value is the size of the written data. Otherwise it's -1. And -1 is also returned if no record corresponds to the specified key.

⚠️ Heads up: an additional zero code is NOT appended at the end of the region of the writing buffer. So don't go treating it like a string, okay? That's a different function.

📏 tchdbvsiz — how big is the value tho

int tchdbvsiz(TCHDB *hdb, const void *kbuf, int ksiz);

The function tchdbvsiz gets the size of the value of a record in a hash database object.

  • hdb — the hash database object.
  • kbuf — pointer to the region of the key.
  • ksiz — size of the region of the key.

If successful, the return value is the size of the value of the corresponding record. Otherwise it's -1.

📏🌸 tchdbvsiz2 — same size check, string key

int tchdbvsiz2(TCHDB *hdb, const char *kstr);

The function tchdbvsiz2 gets the size of the value of a string record in a hash database object.

  • hdb — the hash database object.
  • kstr — the string of the key.

If successful, the return value is the size of the value of the corresponding record, else -1.

🔁 tchdbiterinit — starting the little tour

bool tchdbiterinit(TCHDB *hdb);

The function tchdbiterinit initializes the iterator of a hash database object.

  • hdb — the hash database object.

true on success, false if not.

The iterator is what you use to access the key of every record stored in a database. All of them. The whole roster. 👑

🚶‍♀️ tchdbiternext — next key, please

void *tchdbiternext(TCHDB *hdb, int *sp);

The function tchdbiternext gets the next key of the iterator of a hash database object.

  • hdb — the hash database object.
  • sp — pointer to the variable into which the size of the region of the return value is assigned.

If successful, the return value is the pointer to the region of the next key. Otherwise it's NULL. And NULL is returned when no record is to be get out of the iterator — aka the tour is over, go home. 🏠

Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.

Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. (Yes. Again. Every single time. Free your stuff. 💀)

You can access every record by just iterating this call. Calling it in a loop = the whole database, one key at a time. It is allowed to update or remove records whose keys are fetched while the iteration.

⚠️ BUT — and this is the big BUT — it is not assured if updating the database is occurred while the iteration. So like… go off, but be aware.

Also, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access. Don't expect a cute alphabetical lineup. It's chaos, and we love that for it. 🦋

🚶‍♀️🎀 tchdbiternext2 — next key string, please

The function tchdbiternext2 is used in order to get the next key string of the iterator of a hash database object.

Next up, the iterator era continues. tchdbiternext2 is your lil key-pulling bestie 🦋

char *tchdbiternext2(TCHDB *hdb);
  • hdb specifies the hash database object.
  • If successful, the return value is the string of the next key, else, it is NULL. NULL is returned when no record is to be get out of the iterator.
  • Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use.
  • It is possible to access every record by iteration of calling this function.
  • However, it is not assured if updating the database is occurred while the iteration.
  • Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

Then tchdbiternext3 slides in for the extensible-object girlies ✨ It gets the next extensible objects of the iterator of a hash database object.

bool tchdbiternext3(TCHDB *hdb, TCXSTR *kxstr, TCXSTR *vxstr);
  • hdb specifies the hash database object.
  • kxstr specifies the object into which the next key is wrote down.
  • vxstr specifies the object into which the next value is wrote down.
  • If successful, the return value is true, else, it is false. False is returned when no record is to be get out of the iterator.

tchdbfwmkeys is giving forward-matching-key energy 🔍 It grabs forward matching keys in a hash database object.

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

And tchdbfwmkeys2 is the string-prefix remix 🎀 Same forward-matching-key vibe, but for string keys in a hash database object.

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

tchdbaddint is your integer-addition icon 💅 It adds an integer to a record in a hash database object.

int tchdbaddint(TCHDB *hdb, const void *kbuf, int ksiz, int num);
  • hdb specifies the hash database object connected as a writer.
  • kbuf specifies the pointer to the region of the key.
  • ksiz specifies the size of the region of the key.
  • num specifies the additional value.
  • If successful, the return value is the summation value, else, it is INT_MIN.
  • If the corresponding record exists, the value is treated as an integer and is added to. If no record corresponds, a new record of the additional value is stored.

Next is tchdbdbadddouble — and yeah bestie, the signature right below says tchdbadddouble, we are keeping every character exactly as the page says, no editing periodt. It adds a real number to a record in a hash database object.

double tchdbadddouble(TCHDB *hdb, const void *kbuf, int ksiz, double num);
  • hdb specifies the hash database object connected as a writer.
  • kbuf specifies the pointer to the region of the key.
  • ksiz specifies the size of the region of the key.
  • num specifies the additional value.
  • If successful, the return value is the summation value, else, it is Not-a-Number.
  • If the corresponding record exists, the value is treated as a real number and is added to. If no record corresponds, a new record of the additional value is stored.

tchdbsync is the “make it match the file and device” girlie 💾 It synchronizes updated contents of a hash database object with the file and the device.

bool tchdbsync(TCHDB *hdb);
  • hdb specifies the hash database object connected as a writer.
  • If successful, the return value is true, else, it is false.
  • This function is useful when another process connects to the same database file.

tchdboptimize is here to glow up your database file ✨ It optimizes the file of a hash database object.

bool tchdboptimize(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);
  • hdb specifies the hash database object connected as a writer.
  • bnum specifies the number of elements of the bucket array. If it is not more than 0, the default value is specified. The default value is two times of the number of records.
  • apow specifies the size of record alignment by power of 2. If it is negative, the current setting is not changed.
  • fpow specifies the maximum number of elements of the free block pool by power of 2. If it is negative, the current setting is not changed.
  • opts specifies options by bitwise-or: HDBTLARGE specifies that the size of the database can be larger than 2GB by using 64-bit bucket array, HDBTDEFLATE specifies that each record is compressed with Deflate encoding, HDBTBZIP specifies that each record is compressed with BZIP2 encoding, HDBTTCBS specifies that each record is compressed with TCBS encoding. If it is UINT8_MAX, the current setting is not changed.
  • If successful, the return value is true, else, it is false.
  • This function is useful to reduce the size of the database file with data fragmentation by successive updating.

tchdbvanish is the dramatic “remove all records” moment 😭 It removes all records of a hash database object.

bool tchdbvanish(TCHDB *hdb);
  • hdb specifies the hash database object connected as a writer.
  • If successful, the return value is true, else, it is false.

tchdbcopy is your backup bestie 🫶 It copies the database file of a hash database object.

bool tchdbcopy(TCHDB *hdb, const char *path);
  • hdb specifies the hash database object.
  • path specifies the path of the destination file. If it begins with @, the trailing substring is executed as a command line.
  • If successful, the return value is true, else, it is false. False is returned if the executed command returns non-zero code.
  • The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress. So, this function is useful to create a backup file of the database file.

tchdbtranbegin starts the transaction era 🔥 It begins the transaction of a hash database object.

bool tchdbtranbegin(TCHDB *hdb);
  • hdb specifies the hash database object connected as a writer.
  • If successful, the return value is true, else, it is false.
  • The database is locked by the thread while the transaction so that only one transaction can be activated with a database object at the same time. Thus, the serializable isolation level is assumed if every database operation is performed in the transaction. All updated regions are kept track of by write ahead logging while the transaction. If the database is closed during transaction, the transaction is aborted implicitly.

tchdbtrancommit is the “yes, lock it in” girlie 💖 It commits the transaction of a hash database object.

bool tchdbtrancommit(TCHDB *hdb);
  • hdb specifies the hash database object connected as a writer.
  • If successful, the return value is true, else, it is false.
  • Update in the transaction is fixed when it is committed successfully.

tchdbtranabort is the “nope, undo that” energy 🙈 It aborts the transaction of a hash database object.

bool tchdbtranabort(TCHDB *hdb);
  • hdb specifies the hash database object connected as a writer.
  • If successful, the return value is true, else, it is false.
  • Update in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction.

tchdbpath is your file-path reveal 🌈 It gets the file path of a hash database object.

const char *tchdbpath(TCHDB *hdb);
  • hdb specifies the hash database object.
  • The return value is the path of the database file or NULL if the object does not connect to any database file.

And tchdbrnum is the record-count check 👑 It gets the number of records of a hash database object.

uint64_t tchdbrnum(TCHDB *hdb);
  • hdb specifies the hash database object.
  • The return value is the number of records or 0 if the object does not connect to any database file.

🎀 tchdbfsiz — the little size check-in 🎀

Okay bestie, so this one is your "how big is this thing actually" function. You use tchdbfsiz when you wanna know the size of the database file attached to a hash database object. That's it, that's the whole job. Very demure, very mindful. 💅

uint64_t tchdbfsiz(TCHDB *hdb);
  • hdb — specifies the hash database object. Like, which one are we measuring, girl. 🫶

Return value: it gives you back the size of the database file. But — and this is important, no cap — if the object isn't connected to any database file at all, you get 0. Zero. Nada. The void. So don't go reading tea leaves out of a 0, it just means "there's no file here, bestie." 😭

fr fr, 0 is the "not connected to anything" answer, not a "the file is empty" answer. know the difference, it's giving literacy. 📚

🌈 SEE ALSO 🌈

Go read the whole fam, they're all iconic in their own way:

And that's a wrap on the TCHDB(3) page, babes! 🦋 This lil' manual comes from the source/version stamped 2012-08-18 (yes she's a vintage queen, she's been slaying since 2012 👑), and the whole thing is filed under TCHDB(3) in the Man Page section. Go forth and index responsibly, my main character. 💖✨

📦 where this page comes from