VILLA(3)

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

✨ NAME ✨

Villa — the advanced API of QDBM, and this is the manual page VILLA(3). 💖

🌸 SYNOPSIS 🌸

okay bestie, first things first, you gotta pull in the headers:

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

and here's the comparing-function type, she's the blueprint for how you want your keys sorted:

typedef int(*VLCFUNC)(const char *aptr, int asiz, const char *bptr, int bsiz);

and now the whole cast of characters, every single one of them:

VILLA *vlopen(const char *name, int omode, VLCFUNC cmp);

int vlclose(VILLA *villa);

int vlput(VILLA *villa, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);

int vlout(VILLA *villa, const char *kbuf, int ksiz);

char *vlget(VILLA *villa, const char *kbuf, int ksiz, int *sp);

int vlvsiz(VILLA *villa, const char *kbuf, int ksiz);

int vlvnum(VILLA *villa, const char *kbuf, int ksiz);

int vlputlist(VILLA *villa, const char *kbuf, int ksiz, const CBLIST *vals);

int vloutlist(VILLA *villa, const char *kbuf, int ksiz);

CBLIST *vlgetlist(VILLA *villa, const char *kbuf, int ksiz);

char *vlgetcat(VILLA *villa, const char *kbuf, int ksiz, int *sp);

int vlcurfirst(VILLA *villa);

int vlcurlast(VILLA *villa);

int vlcurprev(VILLA *villa);

int vlcurnext(VILLA *villa);

int vlcurjump(VILLA *villa, const char *kbuf, int ksiz, int jmode);

char *vlcurkey(VILLA *villa, int *sp);

char *vlcurval(VILLA *villa, int *sp);

int vlcurput(VILLA *villa, const char *vbuf, int vsiz, int cpmode);

int vlcurout(VILLA *villa);

void vlsettuning(VILLA *villa, int lrecmax, int nidxmax, int lcnum, int ncnum);

int vlsetfbpsiz(VILLA *villa, int size);

int vlsync(VILLA *villa);

int vloptimize(VILLA *villa);

char *vlname(VILLA *villa);

int vlfsiz(VILLA *villa);

int vllnum(VILLA *villa);

int vlnnum(VILLA *villa);

int vlrnum(VILLA *villa);

int vlwritable(VILLA *villa);

int vlfatalerror(VILLA *villa);

int vlinode(VILLA *villa);

time_t vlmtime(VILLA *villa);

int vltranbegin(VILLA *villa);

int vltrancommit(VILLA *villa);

int vltranabort(VILLA *villa);

int vlremove(const char *name);

int vlrepair(const char *name, VLCFUNC cmp);

int vlexportdb(VILLA *villa, const char *name);

int vlimportdb(VILLA *villa, const char *name);

💖 DESCRIPTION 💖

Villa is the advanced API of QDBM, periodt. She gives you routines for managing a database file that's a B+ tree 🌳. Every record gets stored sorted, in an order that you define. ikr, main character energy.

Now, with hash databases, the retrieving method is provided only as complete accord — like, exact match or nothing, no in-between. But with Villa? You can retrieve records specified by range ✨. A cursor is what you use to walk through each record in order. And yes, you can store records with duplicating keys in a database, no problem. On top of all that, the transaction mechanism means you can commit or abort operations on a database in a lump — all together, bestie 💅.

Villa is implemented based on Depot and Cabin. A database file of Villa is actual one of Depot, fr fr. The processing speed of retrieving and storing is slower than Depot, but the size of a database is smaller. That's the trade, and it's lowkey a good one.

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

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

A pointer to VILLA is used as a database handle. It is like that some file I/O routines of stdio.h use a pointer to FILE. A database handle is opened with the function vlopen and closed with vlclose. You should not refer directly to any member of the handle 🙈. If a fatal error occurs in a database, any access method via the handle except vlclose will not work and will return error status. Although a process is allowed to use multiple database handles at the same time, handles of the same database file should not be used. 🚫

Before the cursor is used, it should be initialized by one of vlcurfirst, vlcurlast or vlcurjump. Also, after storing or deleting a record with functions except for vlcurput and vlcurout, the cursor should be initialized. Don't forget, she gets moody 😭.

Villa also assigns the external variable dpecode with the error code. The function dperrmsg is used in order to get the message of the error code.

🎀 the comparing function (VLCFUNC) 🎀

You can define a comparing function to specify the order of records. The function should be the following type.

typedef int(*VLCFUNC)(const char *aptr, int asiz, const char *bptr, int bsiz);
  • aptr specifies the pointer to the region of one key.
  • asiz specifies the size of the region of one key.
  • bptr specifies the pointer to the region of the other key.
  • bsiz specifies the size of the region of the other key.

The return value is positive if the former is big, negative if the latter is big, and 0 if both are equivalent. That's the whole vibe check ⭐.

🦋 vlopen — get a database handle

The function vlopen is used in order to get a database handle.

VILLA *vlopen(const char *name, int omode, VLCFUNC cmp);
  • name specifies the name of a database file.
  • omode specifies the connection mode: VL_OWRITER as a writer, VL_OREADER as a reader. If the mode is VL_OWRITER, the following may be added by bitwise or: VL_OCREAT, which means it creates a new database if not exist; VL_OTRUNC, which means it creates a new database regardless if one exists; VL_OZCOMP, which means leaves in the database are compressed; VL_OYCOMP, which means leaves in the database are compressed with LZO; VL_OXCOMP, which means leaves in the database are compressed with BZIP2. Both of VL_OREADER and VL_OWRITER can be added to by bitwise or: VL_ONOLCK, which means it opens a database file without file locking, or VL_OLCKNB, which means locking is performed without blocking.
  • cmp specifies the comparing function: VL_CMPLEX comparing keys in lexical order, VL_CMPINT comparing keys as objects of int in native byte order, VL_CMPNUM comparing keys as numbers of big endian, VL_CMPDEC comparing keys as decimal strings. Any function based on the declaration of the type VLCFUNC can be assigned to the comparing function. The comparing function should be kept same in the life of a database. 🫶

The return value is the database handle or NULL if it is not successful.

While connecting as a writer, an exclusive lock is invoked to the database file. While connecting as a reader, a shared lock is invoked to the database file. The thread blocks until the lock is achieved 😴.

VL_OZCOMP, VL_OYCOMP, and VL_OXCOMP are available only if QDBM was built each with ZLIB, LZO, and BZIP2 enabled. If VL_ONOLCK is used, the application is responsible for exclusion control. No cap. 👑

🌈 vlclose — close that handle

The function vlclose is used in order to close a database handle.

int vlclose(VILLA *villa);
  • villa specifies a database handle.

If successful, the return value is true, else, it is false. Because the region of a closed handle is released, it becomes impossible to use the handle. Updating a database is assured to be written when the handle is closed.

If a writer opens a database but does not close it appropriately, the database will be broken 💀. If the transaction is activated and not committed, it is aborted.

🍓 vlput — store a record

The function vlput is used in order to store a record.

int vlput(VILLA *villa, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);
  • villa specifies a database handle connected as a writer.
  • 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).
  • dmode specifies behavior when the key overlaps, by the following values:
    • VL_DOVER, which means the specified value overwrites the existing one
    • VL_DKEEP, which means the existing value is kept
    • VL_DCAT, which means the specified value is concatenated at the end of the existing value
    • VL_DDUP, which means duplication of keys is allowed and the specified value is added as the last one
    • VL_DDUPR, which means duplication of keys is allowed and the specified value is added as the first one

If successful, the return value is true, else, it is false.

The cursor becomes unavailable due to updating database. like, gone. bye. 🙈

🧚 vlout — delete a record

The function vlout is used in order to delete a record.

int vlout(VILLA *villa, const char *kbuf, int ksiz);
  • villa specifies a database handle connected as a writer.
  • 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).

If successful, the return value is true, else, it is false. False is returned when no record corresponds to the specified key. When the key of duplicated records is specified, the first record of the same key is deleted.

The cursor becomes unavailable due to updating database.

💜 vlget — retrieve a record

The function vlget is used in order to retrieve a record.

char *vlget(VILLA *villa, const char *kbuf, int ksiz, int *sp);
  • villa specifies a database 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).
  • sp specifies the pointer to a variable to which the size of the region of the return value is assigned. If it is NULL, it is not used.

If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is NULL. NULL is returned when no record corresponds to the specified key. When the key of duplicated records is specified, the value of the first record of the same key is selected.

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. don't leak bestie, that's not the vibe 😭

The function vlvsiz is used in order to get the size of the value of a record.

So like, vlvsiz is your girl for finding out how big a value is before you commit, y'know? 💅

int vlvsiz(VILLA *villa, const char *kbuf, int ksiz);
  • villa — the database handle, obvs.
  • kbuf — pointer to the region of a key. Like, the actual key bytes.
  • ksiz — the size of that key region. And if it's negative? Bestie, the size gets assigned with strlen(kbuf). Convenient.
  • Returns — if it worked, you get the size of the value of the corresponding record. If it didn't, you get -1. And if multiple records correspond, you get the size of the first one. Periodt.

Then there's vlvnum, which is literally just "how many records match this key" energy. 🔢

int vlvnum(VILLA *villa, const char *kbuf, int ksiz);
  • villa — database handle.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region. Negative? strlen(kbuf) steps in. 💁‍♀️
  • Returns — the number of corresponding records. And if no record corresponds, you get 0. Not -1, not NULL, just 0. Slay.

Okay so vlputlist is the one that stores plural records for a key. Plural. Multiple. A whole squad of values. 👑

int vlputlist(VILLA *villa, const char *kbuf, int ksiz, const CBLIST *vals);
  • villa — a database handle connected as a writer. Important, she has to have write access.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region, and yes, if it's negative it's strlen(kbuf) again.
  • vals — a list handle of values. And heads up: the list should not be empty. Like, don't even try it.
  • Returns — true if it worked, false if it didn't.
  • > ⚠️ The cursor becomes unavailable due to updating the database. She's gone, babes.

vloutlist deletes all the records for a key. All of them. Scorched earth. 🗑️

int vloutlist(VILLA *villa, const char *kbuf, int ksiz);
  • villa — database handle connected as a writer.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region; negative means strlen(kbuf), you know the drill.
  • Returns — true on success, false otherwise. And it returns false when no record corresponds to the specified key. So false doesn't always mean "something broke," sometimes it means "girl, there was nothing there."
  • > ⚠️ Cursor becomes unavailable due to updating the database. Again. She cannot come to the phone right now.

vlgetlist is the retrieve-values-of-all-records-for-a-key function. The collector. 🌸

CBLIST *vlgetlist(VILLA *villa, const char *kbuf, int ksiz);
  • villa — database handle.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region. Negative → strlen(kbuf).
  • Returns — on success, a list handle of the values of the corresponding records. On failure, NULL. And NULL is also what you get when no record corresponds to the specified key.
  • > 💖 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. Do not forget this. Memory leaks are not cute.

vlgetcat gives you all those values but concatenated. One big blob. String energy. 🧵

char *vlgetcat(VILLA *villa, const char *kbuf, int ksiz, int *sp);
  • villa — database handle.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region; if negative, strlen(kbuf).
  • sp — pointer to a variable that gets the size of the region of the return value assigned to it. If it's NULL, it's just not used. No biggie.
  • Returns — on success, a pointer to the region of the concatenated values of the corresponding record. Otherwise NULL. And NULL shows up when no record corresponds to the specified key.
  • > ✨ Because an additional zero code is appended at the end of the region of the return value, you can treat it as a character string. So yes, it's string-able.
  • > 💀 But 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. Free your girl or she haunts you.

Now we're in cursor territory, and honestly? Main character energy. 👑

vlcurfirst moves the cursor to the first record.

int vlcurfirst(VILLA *villa);
  • villa — database handle.
  • Returns — true on success, false otherwise. False is returned if there is no record in the database.

vlcurlast moves the cursor to the last record.

int vlcurlast(VILLA *villa);
  • villa — database handle.
  • Returns — true on success, else false. False if there is no record in the database.

vlcurprev moves the cursor to the previous record.

int vlcurprev(VILLA *villa);
  • villa — database handle.
  • Returns — true on success, else false. False is returned if there is no previous record.

vlcurnext moves the cursor to the next record.

int vlcurnext(VILLA *villa);
  • villa — database handle.
  • Returns — true on success, else false. False is returned if there is no next record.

vlcurjump is the ✨fancy✨ one — it moves the cursor to a position around a record. Not exactly on it, around it. Vibe check.

int vlcurjump(VILLA *villa, const char *kbuf, int ksiz, int jmode);
  • villa — database handle.
  • kbuf — pointer to the region of a key.
  • ksiz — size of the key region; if it's negative, the size is assigned with strlen(kbuf).
  • jmode — the detail adjustment, and there are two moods:
    • VL_JFORWARD — the cursor is set to the first record of the same key, and the cursor is set to the next substitute if a completely matching record does not exist.
    • VL_JBACKWARD — the cursor is set to the last record of the same key, and the cursor is set to the previous substitute if a completely matching record does not exist.
  • Returns — true on success, else false. False is returned if there is no record corresponding the condition.

vlcurkey grabs the key of whatever record the cursor is sitting on. 🔑

char *vlcurkey(VILLA *villa, int *sp);
  • villa — database handle.
  • sp — pointer to a variable that gets the size of the region of the return value. If it's NULL, it is not used.
  • Returns — on success, a pointer to the region of the key of the corresponding record, else NULL. And NULL is returned when no record corresponds to the cursor.
  • > ✨ An additional zero code is appended at the end of the region of the return value, so you can treat the return value as a character string.
  • > 💀 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. Release her.

vlcurval grabs the value of the record where the cursor is. The twin to vlcurkey, but make it value. 💖

char *vlcurval(VILLA *villa, int *sp);
  • villa — database handle.
  • sp — 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.
  • Returns — on success, a pointer to the region of the value of the corresponding record, else NULL. NULL is returned when no record corresponds to the cursor.
  • > ✨ 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.

vlcurput inserts a record around the cursor. She's flexible like that. 🎀

int vlcurput(VILLA *villa, const char *vbuf, int vsiz, int cpmode);
  • villa — a database handle connected as a writer.
  • vbuf — pointer to the region of a value.
  • vsiz — size of the region of the value. If it is negative, the size is assigned with strlen(vbuf).
  • cpmode — detail adjustment, three options, pick your fighter:
    • VL_CPCURRENT — the value of the current record is overwritten.
    • VL_CPBEFORE — a new record is inserted before the current record.
    • VL_CPCAFTER — a new record is inserted after the current record.

Wait, no, hold on — the original says VL_CPAFTER. Let me not do her dirty: it's VL_CPAFTER — a new record is inserted after the current record. My bad bestie, typo brain. 🙈

  • Returns — true on success, else false. False is returned when no record corresponds to the cursor.
  • > ✨ After insertion, the cursor is moved to the inserted record. She follows the new girl.

vlcurout deletes the record where the cursor is. Bye. 💀

int vlcurout(VILLA *villa);
  • villa — a database handle connected as a writer.
  • Returns — true on success, else false. False is returned when no record corresponds to the cursor.
  • > ✨ After deletion, the cursor is moved to the next record if possible.

vlsettuning is the performance-glow-up function. She's giving optimization. 🔥

void vlsettuning(VILLA *villa, int lrecmax, int nidxmax, int lcnum, int ncnum);
  • villa — database handle.
  • lrecmax — the max number of records in a leaf node of B+ tree. If it is not more than 0, the default value is specified.
  • nidxmax — the max number of indexes in a non-leaf node of B+ tree. If it is not more than 0, the default value is specified.
  • lcnum — the max number of caching leaf nodes. If it is not more than 0, the default value is specified.
  • ncnum — the max number of caching non-leaf nodes. If it is not more than 0, the default value is specified.
  • The default setting is equivalent to vlsettuning(49, 192, 1024, 512). Those are the numbers, memorize them, they're iconic. ⭐
  • > ⚠️ Because tuning parameters are not saved in a database, you should specify them every time you open a database. Every. Single. Time. No shortcuts.

And vlsetfbpsiz is the one that sets the size of the free block pool of a database handle.

int vlsetfbpsiz(VILLA *villa, int size);
  • villa — a database handle that's connected as a writer, bestie, that part matters 💅
  • size — the size of the free block pool of a database

Successful? You get true. Not successful? false. The default size of the free block pool is 256. And here's the tea: if the size is greater, the space efficiency of overwriting values is improved — but the time efficiency is sacrificed. so you're trading speed for packing, pick your struggle 😭

The function vlsync is used in order to synchronize updating contents with the file and the device.

int vlsync(VILLA *villa);
  • villa — a database handle connected as a writer

If successful, the return value is true, else, it is false. This function is useful when another process uses the connected database file. 🫶

Do NOT use this while the transaction is activated. like, literally don't 🙈

The function vloptimize is used in order to optimize a database.

int vloptimize(VILLA *villa);
  • villa — a database handle connected as a writer

If successful, the return value is true, else, it is false. So here's the situation: in an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate 😬 This function is useful to do away with them. glow-up for your database, honestly ✨

Also should not be used while the transaction is activated. periodt.

The function vlname is used in order to get the name of a database.

char *vlname(VILLA *villa);
  • villa — a database handle (any handle, not just a writer, slay)

If successful, the return value is the pointer to the region of the name of the database, else, it is NULL. 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. don't forget the free, bestie, that's a leak 💀

The function vlfsiz is used in order to get the size of a database file.

int vlfsiz(VILLA *villa);
  • villa — a database handle

If successful, the return value is the size of the database file, else, it is -1. Heads up though: because of the I/O buffer, the return value may be less than the hard size. it's giving "close enough" 🦋

The function vllnum is used in order to get the number of the leaf nodes of B+ tree.

int vllnum(VILLA *villa);
  • villa — a database handle

If successful, the return value is the number of the leaf nodes, else, it is -1. counting leaves like it's a cute lil plant 🌸

The function vlnnum is used in order to get the number of the non-leaf nodes of B+ tree.

int vlnnum(VILLA *villa);
  • villa — a database handle

If successful, the return value is the number of the non-leaf nodes, else, it is -1. the non-leaf ones, the backbone, the main character energy 👑

The function vlrnum is used in order to get the number of the records stored in a database.

int vlrnum(VILLA *villa);
  • villa — a database handle

If successful, the return value is the number of the records stored in the database, else, it is -1. 🔥

The function vlwritable is used in order to check whether a database handle is a writer or not.

int vlwritable(VILLA *villa);
  • villa — a database handle

The return value is true if the handle is a writer, false if not. vibe check for your handle 💅

The function vlfatalerror is used in order to check whether a database has a fatal error or not.

int vlfatalerror(VILLA *villa);
  • villa — a database handle

The return value is true if the database has a fatal error, false if not. praying it's false fr fr 🙏

The function vlinode is used in order to get the inode number of a database file.

int vlinode(VILLA *villa);
  • villa — a database handle

The return value is the inode number of the database file. ⭐

The function vlmtime is used in order to get the last modified time of a database.

time_t vlmtime(VILLA *villa);
  • villa — a database handle

The return value is the last modified time of the database. when was the last time it ate? 🍓

The function vltranbegin is used in order to begin the transaction.

int vltranbegin(VILLA *villa);
  • villa — a database handle connected as a writer

If successful, the return value is true, else, it is false.

Because this function does not perform mutual exclusion control in multi-thread, the application is responsible for it. that's on you, bestie 😭 Only one transaction can be activated with a database handle at the same time.

The function vltrancommit is used in order to commit the transaction.

int vltrancommit(VILLA *villa);
  • villa — a database handle connected as a writer

If successful, the return value is true, else, it is false. Updating a database in the transaction is fixed when it is committed successfully. commit it, don't ghost it 💖

The function vltranabort is used in order to abort the transaction.

int vltranabort(VILLA *villa);
  • villa — a database handle connected as a writer

If successful, the return value is true, else, it is false. Updating a database in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. we love a good undo button 🧚

The function vlremove is used in order to remove a database file.

int vlremove(const char *name);
  • name — the name of a database file

If successful, the return value is true, else, it is false. bye bye database 👋💀

The function vlrepair is used in order to repair a broken database file.

int vlrepair(const char *name, VLCFUNC cmp);
  • name — the name of a database file
  • cmp — the comparing function of the database file

If successful, the return value is true, else, it is false.

There is no guarantee that all records in a repaired database file correspond to the original or expected state. no cap, it's a repair not a resurrection 😭

The function vlexportdb is used in order to dump all records as endian independent data.

int vlexportdb(VILLA *villa, const char *name);
  • villa — a database handle
  • name — the name of an output file

If successful, the return value is true, else, it is false. taking your data on a little trip, endian independent so it travels cute 🌈

The function vlimportdb is used in order to load all records from endian independent data.

int vlimportdb(VILLA *villa, const char *name);
  • villa — a database handle connected as a writer. The database of the handle must be empty.
  • name — the name of an input file

If successful, the return value is true, else, it is false. empty database only, she does not share 🎀

If QDBM was built with POSIX thread enabled, the global variable dpecode is treated as thread specific data, and functions of Villa are reentrant. In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that errno, malloc, and so on are thread-safe. ✨ threading tea, iykyk ✨

🦋 VISTA, THE EXTENDED EDITION 🦋

Vista is the extended API of Villa. To compensate for the defect that Villa can not handle a file whose size is more than 2GB, Vista does not use Depot but Curia for handling its internal database. While Vista provides data structure and operations of B+ tree as with Villa, its database is realized as a directory. 👑

In order to use Vista, you should include vista.h instead of villa.h. Because Vista is implemented by overriding symbols of Villa, it can be used as with Villa. That is, Signatures of Villa and Vista is all the same. However, as its adverse effect, modules using Vista can not use Depot nor Villa.

that last bit is the catch, bestie — Vista modules can't touch Depot or Villa, so choose your side 💅

🌸 SEE ALSO 🌸

and that's the whole page, bestie!! 🫶 this was VILLA(3), from the Man Page section, dated 2004-04-22 — yes it's vintage, and it still ate 💖💅

📦 where this page comes from