TCFDB(3)

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

✨ NAME ✨

tcfdb — the fixed-length database API. Like, this whole page is TCFDB(3) from Tokyo Cabinet, bestie. 💅

💖 DESCRIPTION 💖

Okay so a fixed-length database is literally just a file containing an array of fixed-length elements, and you handle it with the fixed-length database API. No cap. 🦋

To use the fixed-length database API, include tcutil.h, tcfdb.h, and related standard header files. Usually, write the following description near the front of a source file. ✨

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

Objects whose type is pointer to TCFDB are used to handle fixed-length databases. A fixed-length database object is created with the function tcfdbnew and is deleted with the function tcfdbdel. To avoid memory leak, it is important to delete every object when it is no longer in use. Memory leak is not the vibe, bestie. 😭

Before operations to store or retrieve records, it is necessary to open a database file and connect the fixed-length database object to it. The function tcfdbopen is used to open a database file and the function tcfdbclose 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. Like, do not do that. 🚫

🌈 API 🌈

Here's every function, every signature, every default, every error code, every warning. Periodt. 👑

✨ tcfdberrmsg ✨

The function tcfdberrmsg is used in order to get the message string corresponding to an error code.

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

✨ tcfdbnew ✨

The function tcfdbnew is used in order to create a fixed-length database object.

TCFDB *tcfdbnew(void);
  • The return value is the new fixed-length database object.

✨ tcfdbdel ✨

The function tcfdbdel is used in order to delete a fixed-length database object.

void tcfdbdel(TCFDB *fdb);
  • fdb specifies the fixed-length 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.

✨ tcfdbecode ✨

The function tcfdbecode is used in order to get the last happened error code of a fixed-length database object.

int tcfdbecode(TCFDB *fdb);
  • fdb specifies the fixed-length database object.
  • The return value is the last happened error code.

The following error codes are defined:

  • TCESUCCESS for success
  • TCETHREAD for threading error
  • TCEINVALID for invalid operation
  • TCENOFILE for file not found
  • TCENOPERM for no permission
  • TCEMETA for invalid meta data
  • TCERHEAD for invalid record header
  • TCEOPEN for open error
  • TCECLOSE for close error
  • TCETRUNC for trunc error
  • TCESYNC for sync error
  • TCESTAT for stat error
  • TCESEEK for seek error
  • TCEREAD for read error
  • TCEWRITE for write error
  • TCEMMAP for mmap error
  • TCELOCK for lock error
  • TCEUNLINK for unlink error
  • TCERENAME for rename error
  • TCEMKDIR for mkdir error
  • TCERMDIR for rmdir error
  • TCEKEEP for existing record
  • TCENOREC for no record found
  • TCEMISC for miscellaneous error

✨ tcfdbsetmutex ✨

The function tcfdbsetmutex is used in order to set mutual exclusion control of a fixed-length database object for threading.

bool tcfdbsetmutex(TCFDB *fdb);
  • fdb specifies the fixed-length database object which is not opened.
  • If successful, the return value is true, else, it is false.
  • Note that the mutual exclusion control is needed if the object is shared by plural threads and this function should be called before the database is opened.

✨ tcfdbtune ✨

The function tcfdbtune is used in order to set the tuning parameters of a fixed-length database object.

bool tcfdbtune(TCFDB *fdb, int32_t width, int64_t limsiz);
  • fdb specifies the fixed-length database object which is not opened.
  • width specifies the width of the value of each record. If it is not more than 0, the default value is specified. The default value is 255.
  • limsiz specifies the limit size of the database file. If it is not more than 0, the default value is specified. The default value is 268435456.
  • If successful, the return value is true, else, it is false.
  • Note that the tuning parameters should be set before the database is opened.

✨ tcfdbopen ✨

The function tcfdbopen is used in order to open a database file and connect a fixed-length database object.

bool tcfdbopen(TCFDB *fdb, const char *path, int omode);
  • fdb specifies the fixed-length database object which is not opened.
  • path specifies the path of the database file.
  • omode specifies the connection mode: FDBOWRITER as a writer, FDBOREADER as a reader. If the mode is FDBOWRITER, the following may be added by bitwise-or: FDBOCREAT, which means it creates a new database if not exist, FDBOTRUNC, which means it creates a new database regardless if one exists, FDBOTSYNC, which means every transaction synchronizes updated contents with the device. Both of FDBOREADER and FDBOWRITER can be added to by bitwise-or: FDBONOLCK, which means it opens the database file without file locking, or FDBOLCKNB, which means locking is performed without blocking.
  • If successful, the return value is true, else, it is false.

✨ tcfdbclose ✨

The function tcfdbclose is used in order to close a fixed-length database object.

bool tcfdbclose(TCFDB *fdb);
  • fdb specifies the fixed-length 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.
⚠️ bestie, if a writer opens a database but does not close it appropriately, the database will be broken. That is not a drill. 💀

✨ tcfdbput ✨

The function tcfdbput is used in order to store a record into a fixed-length database object.

bool tcfdbput(TCFDB *fdb, int64_t id, const void *vbuf, int
              vsiz);
  • fdb specifies the fixed-length database object connected as a writer.
  • id specifies the ID number. It should be more than 0. If it is FDBIDMIN, the minimum ID number of existing records is specified. If it is FDBIDPREV, the number less by one than the minimum ID number of existing records is specified. If it is FDBIDMAX, the maximum ID number of existing records is specified. If it is FDBIDNEXT, the number greater by one than the maximum ID number of existing records is specified.
  • vbuf specifies the pointer to the region of the value.
  • vsiz specifies the size of the region of the value. If the size of the value is greater than the width tuning parameter of the database, the size is cut down to the width.
  • 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.

✨ tcfdbput2 ✨

The function tcfdbput2 is used in order to store a record with a decimal key into a fixed-length database object.

bool tcfdbput2(TCFDB *fdb, const void *kbuf, int ksiz, const void
              *vbuf, int vsiz);
  • fdb specifies the fixed-length database object connected as a writer.
  • kbuf specifies the pointer to the region of the decimal key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • 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 the size of the value is greater than the width tuning parameter of the database, the size is cut down to the width.
  • 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.

✨ tcfdbput3 ✨

The function tcfdbput3 is used in order to store a string record with a decimal key into a fixed-length database object.

bool tcfdbput3(TCFDB *fdb, const char *kstr, const void *vstr);
  • fdb specifies the fixed-length database object connected as a writer.
  • kstr specifies the string of the decimal key. It should be more than 0. If it is "min", the minimum ID number of existing records is specified. If it is "prev", the number less by one than the minimum ID number of existing records is specified. If it is "max", the maximum ID number of existing records is specified. If it is "next", the number greater by one than the maximum ID number of existing records is specified.
  • 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.

✨ tcfdbputkeep ✨

The function tcfdbputkeep is used in order to store a new record into a fixed-length database object.

💾 tcfdbputkeep

bool tcfdbputkeep(TCFDB *fdb, int64_t id, const void *vbuf, int vsiz);

okay so this one is the polite version of putting stuff in — it only writes if the seat is actually free. ✨

  • fdb — the fixed-length database object, and bestie, it has to be connected as a writer. reader vibes will not cut it here.
  • id — the ID number. It should be more than 0. And here's the fun part, it can also be one of these lil magic constants:
    • FDBIDMIN → the minimum ID number of existing records
    • FDBIDPREV → the number less by one than the minimum ID number of existing records
    • FDBIDMAX → the maximum ID number of existing records
    • FDBIDNEXT → the number greater by one than the maximum ID number of existing records
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value. 🫶 heads up: if the size of the value is greater than the width tuning parameter of the database, the size gets cut down to the width. no negotiating.

If it works, the return value is true; if not, it's false.

and the whole point of "keep": if a record with the same key already exists in the database, this function has no effect. it just… sits there. respectfully. 💅

🔢 tcfdbputkeep2

bool tcfdbputkeep2(TCFDB *fdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

same energy as above, but the key comes in as a decimal key instead of a raw int. 🌸

  • fdb — the fixed-length database object connected as a writer.
  • kbuf — pointer to the region of the decimal key. It should be more than 0. And yes, the magic words work here too, except as strings:
    • "min" → the minimum ID number of existing records
    • "prev" → the number less by one than the minimum ID number of existing records
    • "max" → the maximum ID number of existing records
    • "next" → the number greater by one than the maximum ID number of existing records
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value. and again: if the size of the value is greater than the width tuning parameter of the database, the size is cut down to the width. ✂️

Success → true. Otherwise → false.

same rule, same drama: if a record with the same key exists in the database, this function has no effect. periodt.

🎀 tcfdbputkeep3

bool tcfdbputkeep3(TCFDB *fdb, const char *kstr, const void *vstr);

the string-flavored twin. storing a new string record with a decimal key, bestie. 🦋

  • fdb — the fixed-length database object connected as a writer.
  • kstr — the string of the decimal key. It should be more than 0. And the magic words:
    • "min" → the minimum ID number of existing records
    • "prev" → the number less by one than the minimum ID number of existing records
    • "max" → the maximum ID number of existing records
    • "next" → the number greater by one than the maximum ID number of existing records
  • vstr — the string of the value.

Success → true, else → false.

and you already know: if a record with the same key exists in the database, this function has no effect. it's giving boundaries. 👑

➕ tcfdbputcat

bool tcfdbputcat(TCFDB *fdb, int64_t id, const void *vbuf, int vsiz);

this one concatenates a value onto the end of an existing record. like adding to the group chat instead of starting a new one. 💬

  • fdb — the fixed-length database object connected as a writer.
  • id — the ID number. It should be more than 0. magic constants:
    • FDBIDMIN → the minimum ID number of existing records
    • FDBIDPREV → the number less by one than the minimum ID number of existing records
    • FDBIDMAX → the maximum ID number of existing records
    • FDBIDNEXT → the number greater by one than the maximum ID number of existing records
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value. (if the size of the value is greater than the width tuning parameter of the database, the size is cut down to the width. same rules, every time. 💅)

Success → true, else → false.

plot twist tho: if there is no corresponding record, a new record is created. it said "fine, I'll do it myself." 😭

🔢➕ tcfdbputcat2

bool tcfdbputcat2(TCFDB *fdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

concatenate a value with a decimal key. same vibe, different key type. ✨

  • fdb — the fixed-length database object connected as a writer.
  • kbuf — pointer to the region of the decimal key. It should be more than 0. and the stringy magic words:
    • "min" → the minimum ID number of existing records
    • "prev" → the number less by one than the minimum ID number of existing records
    • "max" → the maximum ID number of existing records
    • "next" → the number greater by one than the maximum ID number of existing records
  • ksiz — size of the region of the key.
  • vbuf — pointer to the region of the value.
  • vsiz — size of the region of the value. and if the size of the value is greater than the width tuning parameter of the database, the size is cut down to the width. 🫶

Success → true, else → false.

and if there is no corresponding record, a new record is created. iconic behavior honestly.

🎀➕ tcfdbputcat3

bool tcfdbputcat3(TCFDB *fdb, const char *kstr, const void *vstr);

concatenate a string value with a decimal key. the string trio is complete. 🌈

  • fdb — the fixed-length database object connected as a writer.
  • kstr — the string of the decimal key. It should be more than 0. magic words:
    • "min" → the minimum ID number of existing records
    • "prev" → the number less by one than the minimum ID number of existing records
    • "max" → the maximum ID number of existing records
    • "next" → the number greater by one than the maximum ID number of existing records
  • vstr — the string of the value.

Success → true, else → false.

and again, fr fr: if there is no corresponding record, a new record is created.

🗑️ tcfdbout

bool tcfdbout(TCFDB *fdb, int64_t id);

removing a record. it's giving unsubscribe. 💀

  • fdb — the fixed-length database object connected as a writer.
  • id — the ID number. It should be more than 0. and note that this one only takes two magic constants:
    • FDBIDMIN → the minimum ID number of existing records
    • FDBIDMAX → the maximum ID number of existing records
no FDBIDPREV, no FDBIDNEXT here, bestie. don't try it. 🙈

Success → true, else → false.

🔢🗑️ tcfdbout2

bool tcfdbout2(TCFDB *fdb, const void *kbuf, int ksiz);

remove a record with a decimal key. same deletion energy, decimal key. ✨

  • fdb — the fixed-length database object connected as a writer.
  • kbuf — pointer to the region of the decimal key. It should be more than 0. and only two magic words this time:
    • "min" → the minimum ID number of existing records
    • "max" → the maximum ID number of existing records
  • ksiz — size of the region of the key.

Success → true, else → false.

🎀🗑️ tcfdbout3

bool tcfdbout3(TCFDB *fdb, const char *kstr);

remove a string record with a decimal key. last of the out squad. 🫶

  • fdb — the fixed-length database object connected as a writer.
  • kstr — the string of the decimal key. It should be more than 0. and again, just the two:
    • "min" → the minimum ID number of existing records
    • "max" → the maximum ID number of existing records

Success → true, else → false.

🔍 tcfdbget

and now for the moment we've all been waiting for — the function tcfdbget is used in order to retrieve a record in a fixed-length database object. 👑

🌸 tcfdbget — the classic getter

void *tcfdbget(TCFDB *fdb, int64_t id, int *sp);

Okay bestie, this is the one you'll be calling the most, so listen up 💖

  • fdb — your fixed-length database object. The whole vibe.
  • id — the ID number you're hunting for. It should be more than 0. BUT!! if you pass FDBIDMIN, you get the minimum ID number of the existing records instead, and if you pass FDBIDMAX, you get the maximum ID number of the existing records. Literal "just give me the first/last one" energy 👑
  • sp — a pointer to the variable where the size of the returned region gets dumped. It's giving "here's the receipt, keep it" 🧾

If it works, you get back the pointer to the region of the value of the matching record. If nothing matches, you get NULL. No record, no vibes, no nothing 😭

Heads up: there's an extra zero code appended at the end of the returned region, so you can absolutely treat the return value like a character string ✨

And because that region was allocated with the malloc call, you must release it with the free call once you're done with it. Not freeing it is not the move, bestie — that's a leak 🙈

🎀 tcfdbget2 — getter but the key is decimal

void *tcfdbget2(TCFDB *fdb, const void *kbuf, int ksiz, int *sp);

Same energy as tcfdbget, but this one retrieves a record with a decimal key in a fixed-length database object.

  • fdb — the fixed-length database object, obviously 💅
  • kbuf — pointer to the region of the decimal key. It should be more than 0. If you pass "min", you're asking for the minimum ID number of existing records; if you pass "max", you're asking for the maximum ID number of existing records. Sneaky little string keywords, we love to see it ✨
  • ksiz — the size of the region of the key.
  • sp — pointer to the variable that receives the size of the region of the return value.

Successful? You get the pointer to the region of the value of the corresponding record. No match? NULL. That's it, that's the deal 🦋

Additional zero code gets appended at the end of the returned region, so string treatment is fully allowed 🌈

And yeah — malloc allocated, so free it when you're done. Every single time. Periodt 💜

🦋 tcfdbget3 — string record, decimal key, pure convenience

char *tcfdbget3(TCFDB *fdb, const char *kstr);

This one retrieves a string record with a decimal key. It's the low-effort, high-reward version, and honestly? Iconic.

  • fdb — your fixed-length database object.
  • kstr — the string of the decimal key. Should be more than 0. Pass "min" for the minimum ID number of existing records, pass "max" for the maximum ID number of existing records. Same rules, same magic words 🔥

If it works you get the string of the value of the corresponding record. If not, NULL — no record corresponds, so sorry babe 😭

Yes, there's still that additional zero code at the end of the returned region, so you can treat it as a character string 💖

It's malloc-allocated. free it. You know the drill by now 🫶

💅 tcfdbget4 — write it straight into your own buffer

int tcfdbget4(TCFDB *fdb, int64_t id, void *vbuf, int max);

Not me giving you a getter that writes into your buffer instead of handing you a fresh malloc region — main character energy fr fr 👑

  • fdb — the fixed-length database object.
  • id — the ID number. Should be more than 0. FDBIDMIN gets you the minimum ID number of existing records, FDBIDMAX gets you the maximum ID number of existing records. (Yes, same deal as tcfdbget, keep up bestie ✨)
  • vbuf — pointer to the buffer where the value of the corresponding record gets written.
  • max — the size of the buffer. Don't be cute with this one.

If it works, the return value is the size of the written data. If not, it's -1. And -1 is also what you get if no record corresponds to the specified key. Rude but consistent 💀

⚠️ IMPORTANT: an additional zero code is not appended at the end of the region of the writing buffer. So don't go treating vbuf like a string without doing that yourself. This is not the same as the other getters and you will get caught out 🌸

🌈 tcfdbvsiz — just tell me how big it is

int tcfdbvsiz(TCFDB *fdb, int64_t id);

Want the size of the value of a record without actually grabbing the value? Vibe check only, no full download 💖

  • fdb — the fixed-length database object.
  • id — the ID number. More than 0, please. FDBIDMIN → minimum ID number of existing records. FDBIDMAX → maximum ID number of existing records. You know it 🎀

If it works, you get the size of the value of the corresponding record. If not, -1. That's the whole function, she's simple and she's slaying ✨

⭐ tcfdbvsiz2 — size check, decimal key edition

int tcfdbvsiz2(TCFDB *fdb, const void *kbuf, int ksiz);

Size of the value, but with a decimal key. Same plot, different key type 🦋

  • fdb — the fixed-length database object.
  • kbuf — pointer to the region of the decimal key. Should be more than 0. "min" for the minimum ID number of existing records, "max" for the maximum ID number of existing records. The keyword thing again, we stay consistent 💅
  • ksiz — the size of the region of the key.

Success → the size of the value of the corresponding record. Failure → -1. Short and sweet, love that for us 💜

🍓 tcfdbvsiz3 — size of a string value, decimal key

int tcfdbvsiz3(TCFDB *fdb, const char *kstr);

Getting the size of the string value with a decimal key. The 3 of the vsiz family, and she delivers 🔥

  • fdb — the fixed-length database object.
  • kstr — the string of the decimal key. Should be more than 0. "min" → minimum ID number of existing records. "max" → maximum ID number of existing records. As always 🌸

Works → the size of the value of the corresponding record. Doesn't work → -1. Finishing strong 🫶

🧚 tcfdbiterinit — spin up the iterator

bool tcfdbiterinit(TCFDB *fdb);

Bestie, this initializes the iterator of a fixed-length database object. If you wanna walk through every record in the database, this is step one, no skips 💖

  • fdb — the fixed-length database object.

Returns true if it worked, false if it didn't. That's it 😌

The iterator is the thing you use to access the key of every record stored in the database. It's your little tour guide 👑

👑 tcfdbiternext — next ID, let's go

uint64_t tcfdbiternext(TCFDB *fdb);

After you've hit tcfdbiterinit, you keep calling this to get the next ID number out of the iterator. Yes, in a loop. Yes, it works. Trust ✨

  • fdb — the fixed-length database object.

Success → the next ID number of the iterator. Otherwise → 0. And 0 is also what you get when there's no record left to be gotten out of the iterator. So 0 means "we're done here", not "we found a record with ID 0" — read the room 💀

  • It's possible to access every record by iterating this function. Full coverage, no record left behind 🌈
  • It is allowed to update or remove records whose keys are fetched while the iteration. Live editing, we love a flexible API 💅
  • The order of this traversal access method is ascending of the ID number. Smallest to biggest, always 🎀

🦋 tcfdbiternext2 — next decimal key, pointer style

void *tcfdbiternext2(TCFDB *fdb, int *sp);

The decimal-key sibling of tcfdbiternext. Same iteration energy, different return type 💜

  • fdb — the fixed-length database object.
  • sp — pointer to the variable into which the size of the region of the return value gets assigned.

Success → the pointer to the region of the next decimal key. Otherwise → NULL. And NULL is also what you get when there's no record to be gotten out of the iterator. Same "we're done" signal as before 😭

Additional zero code at the end of the returned region → string treatment is allowed, bestie 💖

malloc-allocated, so free it when it's no longer in use. Every time. No exceptions 🫶

  • Every record is accessible by iterating this function.
  • Updating or removing records whose keys are fetched during the iteration? Totally allowed.
  • Traversal order is ascending of the ID number. Ascending. Always ascending 🔥

🌸 tcfdbiternext3 — next decimal key, string style

char *tcfdbiternext3(TCFDB *fdb);

The string-flavored one. No sp, no pointer math, just vibes and a char * 🎀

  • fdb — the fixed-length database object.

Success → the string of the next decimal key. Otherwise → NULL, and NULL also means no record is left to be gotten out of the iterator. When it's over, it's over 💅

malloc-allocated, so free it once it's no longer in use. You already knew that but I'm saying it anyway because I care 🥺
  • Every record is reachable by iterating this function.
  • Updating or removing records whose keys are fetched during the iteration is allowed.
  • The order of this traversal access method is ascending of the ID number. Ascending, bestie. Ascending ⭐

🌈 tcfdbrange — range matching ID numbers

The function tcfdbrange is used in order to get range matching ID numbers in a fixed-length database object.

🦋 tcfdbrange

uint64_t *tcfdbrange(TCFDB *fdb, int64_t lower, int64_t upper, int max, int *np);

okay so this is THE "gimme every record in this range bestie" function and honestly? iconic. 🎀

  • fdb — the fixed-length database object. your main character.
  • lower — the lower limit of the range. if you pass FDBIDMIN here, it means "the minimum ID, pls and ty".
  • upper — the upper limit of the range. pass FDBIDMAX and it means "the maximum ID, exactly".
  • max — the max number of keys to be fetched. if it's negative, no limit at all, we go feral, we go unhinged. 🔥
  • np — the pointer to the variable where the number of elements of the return value gets assigned.

if it works you get back a pointer to an array of ID numbers of the corresponding records. on failure you get NULL. but lowkey? this function does never fail. it returns an empty array even if no key corresponds. she's resilient like that. 💅

heads up bestie: the region of the return value is allocated with the malloc call, so it should be released with the free call when it is no longer in use. don't leave her hanging, she deserves closure. 🫶

🌸 tcfdbrange2

the function tcfdbrange2 is used in order to get range matching decimal keys in a fixed-length database object.

TCLIST *tcfdbrange2(TCFDB *fdb, const void *lbuf, int lsiz, const void *ubuf, int usiz, int max);
  • fdb — the fixed-length database object, obviously.
  • lbuf — pointer to the region of the lower key. if it's "min", the minimum ID number of existing records is specified.
  • lsiz — the size of the region of the lower key.
  • ubuf — pointer to the region of the upper key. if it's "max", the maximum ID number of existing records is specified.
  • usiz — the size of the region of the upper key.
  • max — the max number of keys to be fetched. negative? no limit. we ball. 🏀

the return value is a list object of the corresponding decimal keys. this function does never fail — it returns an empty list even if no key corresponds. no cap.

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. also pls note that this function may be very slow because every key in the database is scanned. she's thorough, not fast. 😭

🧚 tcfdbrange3

the function tcfdbrange3 is used in order to get range matching decimal keys with strings in a fixed-length database object.

TCLIST *tcfdbrange3(TCFDB *fdb, const char *lstr, const char *ustr, int max);
  • fdb — the fixed-length database object.
  • lstr — the string of the lower key. if it's "min", the minimum ID number of existing records is specified.
  • ustr — the string of the upper key. if it's "max", the maximum ID number of existing records is specified.
  • max — the max number of keys to be fetched. negative means no limit, live your truth.

the return value is a list object of the corresponding decimal keys. this function does never fail. it returns an empty list even if no key corresponds. periodt.

created with tclistnew → delete it with tclistdel when you're done, bestie. and yeah, this one may be very slow because every single key in the database gets scanned. every. single. one. 💀

🌈 tcfdbrange4

the function tcfdbrange4 is used in order to get keys with an interval notation in a fixed-length database object.

TCLIST *tcfdbrange4(TCFDB *fdb, const void *ibuf, int isiz, int max);
  • fdb — the fixed-length database object.
  • ibuf — pointer to the region of the interval notation.
  • isiz — the size of the region of the interval notation.
  • max — max number of keys to be fetched. negative = no limit, no thoughts, head empty. ✨

the return value is a list object of the corresponding decimal keys. this function does never fail, she returns an empty list even if no key corresponds. obsessed.

the return value object is made with tclistnew, so delete it with tclistdel when it's no longer in use. and note that this function may be very slow because every key in the database is scanned. it's giving full-table-scan energy, iykyk.

⭐ tcfdbrange5

the function tcfdbrange5 is used in order to get keys with an interval notation string in a fixed-length database object.

TCLIST *tcfdbrange5(TCFDB *fdb, const void *istr, int max);
  • fdb — the fixed-length database object.
  • istr — pointer to the region of the interval notation string.
  • max — max number of keys to be fetched. if it's negative, no limit, we simply do not cap. 💅

the return value is a list object of the corresponding decimal keys. this function does never fail — it returns an empty list even if no key corresponds, which is honestly so forgiving of her.

created via tclistnew, so clean up with tclistdel when you're done. and yes, she may be very slow because every key in the database is scanned. it is what it is. 😭

💜 tcfdbaddint

the function tcfdbaddint is used in order to add an integer to a record in a fixed-length database object. math girlies rise. 🔥

int tcfdbaddint(TCFDB *fdb, int64_t id, int num);
  • fdb — the fixed-length database object, connected as a writer. (writer only, bestie, don't try it as a reader.)
  • id — the ID number. it should be more than 0. and it can also be one of the cute special values:
    • FDBIDMIN → the minimum ID number of existing records is specified.
    • FDBIDPREV → the number less by one than the minimum ID number of existing records is specified.
    • FDBIDMAX → the maximum ID number of existing records is specified.
    • FDBIDNEXT → the number greater by one than the maximum ID number of existing records is specified.
  • num — the additional value.

if it works, the return value is the summation value. otherwise it's 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. so either way you're getting a number back. slay.

🍓 tcfdbadddouble

the function tcfdbadddouble is used in order to add a real number to a record in a fixed-length database object.

double tcfdbadddouble(TCFDB *fdb, int64_t id, double num);
  • fdb — the fixed-length database object, connected as a writer.
  • id — the ID number. should be more than 0. and again with the special values:
    • FDBIDMIN → the minimum ID number of existing records is specified.
    • FDBIDPREV → the number less by one than the minimum ID number of existing records is specified.
    • FDBIDMAX → the maximum ID number of existing records is specified.
    • FDBIDNEXT → the number greater by one than the maximum ID number of existing records is specified.
  • num — the additional value.

if it works, the return value is the summation value. if not, it's Not-a-Number. a whole NaN. not me getting a NaN from my database. 💀

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.

🎀 tcfdbsync

the function tcfdbsync is used in order to synchronize updated contents of a fixed-length database object with the file and the device.

bool tcfdbsync(TCFDB *fdb);
  • fdb — the fixed-length database object, connected as a writer.

if successful, the return value is true. otherwise, false. simple as.

this function is useful when another process connects to the same database file. sharing is caring, bestie. 🫶

👑 tcfdboptimize

the function tcfdboptimize is used in order to optimize the file of a fixed-length database object. glow-up time. ✨

bool tcfdboptimize(TCFDB *fdb, int32_t width, int64_t limsiz);
  • fdb — the fixed-length database object, connected as a writer.
  • width — the width of the value of each record. if it's not more than 0, the current setting is not changed. (so 0 or below = "keep her as she is".)
  • limsiz — the limit size of the database file. if it's not more than 0, the current setting is not changed either.

if successful, the return value is true. else, false.

🫶 tcfdbvanish

the function tcfdbvanish is used in order to remove all records of a fixed-length database object.

bool tcfdbvanish(TCFDB *fdb);
  • fdb — the fixed-length database object, connected as a writer.

if successful, the return value is true. else, false.

ok so this one literally makes everything disappear. poof. no takebacks. 👻

💖 tcfdbcopy

the function tcfdbcopy is used in order to copy the database file of a fixed-length database object.

bool tcfdbcopy(TCFDB *fdb, const char *path);
  • fdb — the fixed-length database object.
  • path — the path of the destination file. and here's the cute part: if it begins with @, the trailing substring is executed as a command line. 🎀

if successful, the return value is true. else, 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. she's literally the responsible friend who holds your stuff while you run around. 🫶

🌟 tcfdbtranbegin

the function tcfdbtranbegin is used in order to begin the transaction of a fixed-length database object.

okay bestie, last stretch, we're in the transaction-and-stats era of this page and honestly? it's giving ✨backend glitz✨ let's go 💅

🌈 tcfdbtranbegin — start the ✨moment✨

bool tcfdbtranbegin(TCFDB *fdb);
  • fdb — the fixed-length database object, and she MUST be connected as a writer. no reader energy allowed here 🙅‍♀️

Returns true if it worked, false if it didn't. that's it, that's the whole vibe check.

okay so the deets, because they matter 🫶:

  • the database gets locked by the thread for the whole transaction, so only one transaction can be active on a database object at a time. no sharing, no tag-teaming, she's monogamous 💀
  • so if you do every database operation inside the transaction, you're lowkey getting serializable isolation level for free. iconic behavior, no cap.
  • all the updated regions are tracked by write ahead logging while the transaction runs. she's keeping receipts 📝
  • and if the database gets closed mid-transaction? the transaction is aborted implicitly. so rude, but also correct. don't close her while she's mid-sentence bestie 😭

💖 tcfdbtrancommit — say yes to the changes

use tcfdbtrancommit to commit the transaction of a fixed-length database object. periodt.

bool tcfdbtrancommit(TCFDB *fdb);
  • fdb — the fixed-length database object, connected as a writer. again: writer only, bestie 🎀
  • returns true on success, false otherwise

the update inside the transaction gets locked in forever when it commits successfully. no take-backs, it's canon now 👑

🦋 tcfdbtranabort — nvm bestie, forget I said anything

use tcfdbtranabort to abort the transaction of a fixed-length database object. it's the "actually never mind 🙈" of database ops.

bool tcfdbtranabort(TCFDB *fdb);
  • fdb — the fixed-length database object, connected as a writer (you know the drill by now 💅)
  • returns true on success, false otherwise

when it aborts, the update in the transaction is discarded. and the state of the database gets rolled back to before the transaction</straight>. so it's like it never even happened. we love a clean slate ✨

🎀 tcfdbpath — where does she live

use tcfdbpath to get the file path of a fixed-length database object. lowkey just asking for her address 🏡

const char *tcfdbpath(TCFDB *fdb);
  • fdb — the fixed-length database object
  • returns the path of the database file, or NULL if the object doesn't connect to any database file

🌸 tcfdbrnum — how many records, bestie

use tcfdbrnum to get the number of records in a fixed-length database object.

uint64_t tcfdbrnum(TCFDB *fdb);
  • fdb — the fixed-length database object
  • returns the number of records, or 0 if the object doesn't connect to any database file

yes, 0. so if you get a zero, check whether she's even connected before you spiral 🙈

⭐ tcfdbfsiz — how big is the file

use tcfdbfsiz to get the size of the database file of a fixed-length database object.

uint64_t tcfdbfsiz(TCFDB *fdb);
  • fdb — the fixed-length database object
  • returns the size of the database file, or 0 if the object doesn't connect to any database file

👀 SEE ALSO

and that's the whole page bestie, we ate and left absolutely zero crumbs 💅✨

the page signs off as Man Page, version/date 2012-08-18, filed under TCFDB(3) — so go forth, connect as a writer, commit your little heart out, and remember: abort is always an option 🫶💖🎀🦋🌸

📦 where this page comes from