dbh.h(0)

💖 NAME 💖

dbh.h — the Dbh header file. bestie, this is the header, the blueprint, the moment. 🎀

---

✨ SYNOPSIS ✨

#include <dbh.h>

cc -ldbh

yes queen, you link against -ldbh and you're in. periodt.

---

🦋 DESCRIPTION 🦋

💅 Disk Based Hashtables (DBH) 64 bit

okay so picture this: a whole library whose entire job is making and managing hash tables that live on disk. It makes associations between keys and values, so for any key you hand it, the value comes back to you fast — loaded right into memory. 🫶

Being disk based is the whole point: it means your hashes can be huge and persistent. And the 64 bit support? That's what lets you have hashtables bigger than 4 Gigabytes even on 32 bit systems. no cap. 💅

And cuantified key generation lets you get minimum access time on balanced multidimensional trees. ✨

🌸 Functionality

A DBHashTable provides associations between keys and values, optimized so that given a key, the associated value can be found very quickly. it's giving efficiency, it's giving main character energy.

Important vibe check: only one hash record is loaded from disk to memory at any given moment for a DBHashTable. Both keys and values should be copied into the DBHashTable record, so they don't need to exist for the lifetime of the DBHashTable. What that means practically is that static strings and temporary strings (i.e. those created in buffers, and those returned by GTK+ widgets) should be copied with dbh_set_key() and dbh_set_data() into the DBHashTable record before being inserted. copy first, insert after, that's the order bestie. 🙈

⚠️ be careful: make sure the copied key length matches the defined key length of the DBHashTable, and that the copied data does not exceed the maximum length of the DBHashTable record (1024 bytes by default, and expandable by dbh_set_size()). If the DBHashTable record length is going to be variable, be sure to set the appropriate length before each dbh_update(), with dbh_set_recordsize() — otherwise the record length only needs to be set before the first dbh_update(). got it? got it. 💅

To create a DBHashTable, use dbh_create(). To insert a key and value into a DBHashTable, use dbh_update(). The DBHashTable will not be modified until this command is given. All changes to the current DBHashTable record only reside in memory: dbh_update() is necessary to commit the changes to the DBHashTable. To look up a value corresponding to a given key, use dbh_load(). To erase and unerase a key and value, use dbh_erase() and dbh_unerase(). 🎀

To call a function for each key and value pair (using a sweep route) use dbh_foreach_sweep() and dbh_sweep(). To call a function for each key and value pair (using a fanout route) use dbh_foreach_fanout() and dbh_foreach_fanout(). To destroy a DBHashTable use dbh_destroy(). 🦋

This is dbh version 2, incompatible with dbh version 1 files. The main difference between the two versions is the handling of file pointers. In version 1, file pointers were 32 bits in length, while in version 2, file pointers are 64 bits in length. That's what allows for DBHashTables with sizes greater than 2 GBytes. ✨

🧚 Cuantified numbers

Cuantified numbers are an alternate way to view the set of natural numbers {1, 2, 3, ...} where order is defined in two levels. In natural numbers there's only one level of order (defined by the > boolean operator). In cuantified numbers, the first level of order is defined by the cuanta, or quantity. The cuanta is obtained by adding all the digits of the cuantified number. 🧮

So, for example, 10022, 5, 32, and 11111 are all equal at the first level of order, since they all add up to 5. The second level of order may be obtained in different manners. In functions dbh_genkey() and dbh_genkey2() the corresponding order of the natural numbers from which they are associated is not conserved. 💀

In dbh_orderkey() the corresponding order of the natural numbers from which they are associated is conserved — but at a price. The base, or maximum value each digit may reach, must be defined. This effectively puts a limit on the number of keys which may be generated for a given number of digits. 🫠

When a DBHashTable is constructed with cuantified keys, the maximum amount of disk access instructions generated to access any given record is equal to the cuanta of the cuantified number represented by the key. This allows a DBHashTable to be constructed with minimum access time across all records. iconic behaviour, honestly. 👑

⭐ FILE_POINTER

FILE_POINTER is an architecture independent 64 bit integer type. that's it, that's the tea. ☕

🎀 Structures

typedef struct dbh_header_t;
typedef struct DBHashTable;

dbh_header_t is the structural information written at the first 256 bytes of a DBHashTable file. 🌸

DBHashTable is a data structure containing the record information for an open DBHashTable file. 💖

👑 Macros

unsigned char DBH_KEYLENGTH (DBHashTable * dbh);
FILE_POINTER DBH_RECORD_SIZE (DBHashTable * dbh);
void *DBH_KEY (DBHashTable * dbh);
void *DBH_DATA (DBHashTable * dbh);
FILE_POINTER DBH_ERASED_SPACE (DBHashTable * dbh);
FILE_POINTER DBH_DATA_SPACE (DBHashTable * dbh);
FILE_POINTER DBH_TOTAL_SPACE (DBHashTable * dbh);
FILE_POINTER DBH_FORMAT_SPACE (DBHashTable * dbh);
FILE_POINTER DBH_RECORDS (DBHashTable * dbh);
FILE_POINTER DBH_MAXIMUM_RECORD_SIZE (DBHashTable * dbh);
char *DBH_PATH (DBHashTable * dbh);

the whole macro lineup, bestie — every single one, no skips. 💅

🔥 Functions

int dbh_close (DBHashTable *dbh);
int dbh_destroy (DBHashTable *dbh);

DBHashTable *dbh_open(constchar*path);
DBHashTable *dbh_openR(constchar*path);
DBHashTable *dbh_create (const char *path, unsigned char key_length);

int dbh_erase (DBHashTable *dbh);
int dbh_unerase (DBHashTable *dbh);
int dbh_prune (DBHashTable *dbh, unsigned char *key, unsigned char
subtree_length);
int dbh_unprune (DBHashTable *dbh, unsigned char *key, unsigned char
subtree_length);

FILE_POINTER dbh_find (DBHashTable *dbh, int n);

void dbh_genkey (unsigned char *key, unsigned char length, unsigned int
n);
void dbh_genkey2 (unsigned char *key, unsigned char length, unsigned int
n);
void dbh_orderkey (unsigned char *key, unsigned char length, unsigned
int n, unsigned char base); sp FILE_POINTER dbh_load (DBHashTable *dbh);
unsigned char dbh_load_address (DBHashTable *dbh,
FILE_POINTERcurrentseek);
FILE_POINTER dbh_load_parent (DBHashTable *dbh);
FILE_POINTER dbh_load_child (DBHashTable *dbh, unsigned char key_index);

DBHashTable *dbh_regen_sweep (DBHashTable *dbh);
DBHashTable *dbh_regen_fanout (DBHashTable *dbh);
int dbh_settempdir (DBHashTable *dbh, char *temp_dir);

void dbh_set_data (DBHashTable *dbh, void *data, FILE_POINTER size);

void dbh_set_key (DBHashTable *dbh, unsigned char *key);

int dbh_set_size (DBHashTable *dbh, FILE_POINTERsize);
void dbh_set_recordsize (DBHashTable *dbh, int record_size );

int dbh_sweep (DBHashTable *dbh, DBHashFunc operate, unsigned char
*key1, unsigned char *key2, unsigned char ignore_portion);
int dbh_fanout (DBHashTable *dbh, DBHashFunc operate, unsigned char
*key1, unsigned char *key2, unsigned char ignore_portion);
int dbh_foreach_sweep (DBHashTable *dbh, DBHashFunc operate);
int dbh_foreach_fanout (DBHashTable *dbh, DBHashFunc operate);
void dbh_exit_sweep (DBHashTable *dbh);
void dbh_exit_fanout (DBHashTable *dbh);

FILE_POINTER dbh_update (DBHashTable *dbh);
int dbh_writeheader (DBHashTable *dbh);

that's the full roster, copied exactly, because we do not paraphrase signatures in this house. 🎀

---

🌈 SEE ALSO 🌈

• dbh_macros (3)
• dbh_close (3)
• dbh_create (3)
• dbh_erase (3)
• dbh_find (3)
• dbh_genkey (3)
• dbh_load (3)
• dbh_regen_sweep (3)
• dbh_set_data (3)
• dbh_set_size (3)
• dbh_sweep (3)
• dbh_update (3)

go read those too, bestie, iykyk. 📚✨

---

💜 Author 💜

Edscott Wilson Garcia <edscott@xfce.org> — the icon who wrote this. show some respect. 👑

---

and that's a wrap on dbh.h 💖 this little cutie ships as part of the DBHashTables Programmers' Manual — the DBH source, DBHashTables flavour, page dbh.h(0). thanks for reading my ted talk, now go build something persistent. 🦋🌸💅