HOVEL(3)

👑 HOVEL(3) — the Quick Database Manager glow-up 👑

okay bestie, sit down, hydrate, because we're about to talk about Hovel, which is the GDBM-compatible API of QDBM 🦋. Yes, that QDBM. The Quick Database Manager one. This is the HOVEL(3) page and she is long, so buckle up — this is part one of two, we're not done yet, don't go anywhere 💅

---

✨ NAME ✨

Hovel — literally just: the GDBM-compatible API of QDBM. That's the whole vibe. She's a compatibility layer and she ate 🎀

---

🌸 SYNOPSIS 🌸

first things first, you gotta invite her in, so you #include all her little friends:

#include <hovel.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>

then, the icon herself, the datum type. she's a struct, she's tiny, she carries your bytes around:

typedef struct { char *dptr; size_t dsize; } datum;

then the globals, aka the girlies who just hang out in the open, no arguments, no nothing:

extern char *gdbm_version;

extern gdbm_error gdbm_errno;

gdbm_version is a char * that's just... out there. and gdbm_errno is your gdbm_error global — she's the one holding the receipts when something goes wrong 😭

---

then the function roster, and yes we're listing every single one because nobody gets left behind, periodt:

char *gdbm_strerror(gdbm_error gdbmerrno);

she takes a gdbm_error gdbmerrno and hands you back a char *. no cap.

GDBM_FILE gdbm_open(char *name, int block_size, int read_write, int
mode, void (*fatal_func)(void));

open her up. char *name, int block_size, int read_write, int mode, and a void (*fatal_func)(void) callback for when things get dramatic.

GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum, int
dnum, int align);

the sequel 💖 char *name, int read_write, int mode, int bnum, int dnum, int align. different flavor, same energy.

void gdbm_close(GDBM_FILE dbf);

say bye. GDBM_FILE dbf, returns void, she's not gonna give you a status report, she's just leaving 👋

int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);

put a thing in. GDBM_FILE dbf, a datum key, a datum content, an int flag. returns int, obviously.

int gdbm_delete(GDBM_FILE dbf, datum key);

yeet the thing. GDBM_FILE dbf and a datum key, returns int.

datum gdbm_fetch(GDBM_FILE dbf, datum key);

get the thing back. GDBM_FILE dbf and a datum key, and she hands you a datum — that's the whole point, bestie.

int gdbm_exists(GDBM_FILE dbf, datum key);

does it exist tho?? 👀 GDBM_FILE dbf, datum key, returns int.

datum gdbm_firstkey(GDBM_FILE dbf);

first one in the lineup. just a GDBM_FILE dbf, gives you back a datum.

datum gdbm_nextkey(GDBM_FILE dbf, datum key);

and the next one. GDBM_FILE dbf, a datum key, returns a datum. yes you need both, she said so.

void gdbm_sync(GDBM_FILE dbf);

flush that vibe to disk. GDBM_FILE dbf, returns void, no notes.

int gdbm_reorganize(GDBM_FILE dbf);

the glow-up function ✨ GDBM_FILE dbf, returns int.

int gdbm_fdesc(GDBM_FILE dbf);

file descriptor reveal. GDBM_FILE dbf, returns int.

int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);

set your options, main character energy. GDBM_FILE dbf, int option, int *value — yes that's a pointer, don't panic — and int size. returns int.

---

okay that's the synopsis, we got all the signatures down and not one of them got dropped 💜 the rest is coming, stay with me, don't scroll away —

✨ DESCRIPTION ✨

Okay bestie, listen up 💖 Hovel is the API that's compatible with GDBM. So basically Hovel wraps functions of Depot and Curia as the API of GDBM. It makes porting an app from GDBM to QDBM super easy. In most cases you only need to swap the includes of gdbm.h with hovel.h and replace the linking option -lgdbm with -lqdbm. But heads up: Hovel cannot handle database files made by the original GDBM. No cap.

To use Hovel, you should include hovel.h, stdlib.h, sys/types.h, and sys/stat.h in your source files. Usually that looks like this near the top of a source file:

#include <hovel.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>

An object of GDBM_FILE is used as a database handle. You open a database handle with gdbm_open and close it with gdbm_close. Do not refer directly to any member of a handle — that's not the vibe. Although Hovel usually works as a wrapper of Depot and handles a database file, if you use gdbm_open2 to open the handle, you can make the handle behave as a wrapper of Curia and treat a database directory. Iconic.

Structures of datum type are used to give and receive data of keys and values with Hovel's functions.

typedef struct { char *dptr; size_t dsize; } datum;

dptr specifies the pointer to the region of a key or a value. dsize specifies the size of the region. Cute and simple 💅

The external variable gdbm_version is the string containing the version information.

extern char *gdbm_version;

The external variable gdbm_errno is assigned with the last happened error code. Refer to hovel.h for details of the error codes.

extern gdbm_error gdbm_errno;

The initial value of this variable is GDBM_NO_ERROR. The other values are:

• GDBM_MALLOC_ERROR
• GDBM_BLOCK_SIZE_ERROR
• GDBM_FILE_OPEN_ERROR
• GDBM_FILE_WRITE_ERROR
• GDBM_FILE_SEEK_ERROR
• GDBM_FILE_READ_ERROR
• GDBM_BAD_MAGIC_NUMBER
• GDBM_EMPTY_DATABASE
• GDBM_CANT_BE_READER
• GDBM_CANT_BE_WRITER
• GDBM_READER_CANT_DELETE
• GDBM_READER_CANT_STORE
• GDBM_READER_CANT_REORGANIZE
• GDBM_UNKNOWN_UPDATE
• GDBM_ITEM_NOT_FOUND
• GDBM_REORGANIZE_FAILED
• GDBM_CANNOT_REPLACE
• GDBM_ILLEGAL_DATA
• GDBM_OPT_ALREADY_SET
• GDBM_OPT_ILLEGAL

The function gdbm_strerror is used to get a message string corresponding to an error code.

char *gdbm_strerror(gdbm_error gdbmerrno);

gdbmerrno specifies an error code. The return value is the message string of the error code. The region of the return value is not writable — so don't even think about touching it, bestie.

The function gdbm_open is used to get a database handle after the fashion of GDBM.

GDBM_FILE gdbm_open(char *name, int block_size, int read_write, int
mode, void (*fatal_func)(void));

name specifies the name of a database. block_size is ignored. read_write specifies the connection mode: GDBM_READER as a reader, GDBM_WRITER, GDBM_WRCREAT, and GDBM_NEWDB as a writer. GDBM_WRCREAT makes a database file or directory if it does not exist. GDBM_NEWDB makes a new database even if it exists. You can add the following to writer modes by bitwise or:

• GDBM_SYNC — means a database is synchronized after every updating method.
• GDBM_NOLOCK — means a database is opened without file locking.
• GDBM_LOCKNB — means file locking is performed without blocking.
• GDBM_FAST — is ignored.
• GDBM_SPARSE — is an original mode of QDBM and makes database a sparse file.

mode specifies mode of a database file as the one of open call does. fatal_func is ignored. The return value is the database handle or NULL if it is not successful.

The function gdbm_open2 is used to get a database handle after the fashion of QDBM.

GDBM_FILE gdbm_open2(char *name, int read_write, int mode, int bnum, int
dnum, int align);

name specifies the name of a database. read_write specifies the connection mode: GDBM_READER as a reader, GDBM_WRITER, GDBM_WRCREAT, and GDBM_NEWDB as a writer. GDBM_WRCREAT makes a database file or directory if it does not exist. GDBM_NEWDB makes a new database even if it exists. You can add the following to writer modes by bitwise or:

• GDBM_SYNC — means a database is synchronized after every updating method.
• GDBM_NOLOCK — means a database is opened without file locking.
• GDBM_LOCKNB — means file locking is performed without blocking.
• GDBM_FAST — is ignored.
• GDBM_SPARSE — is an original mode of QDBM and makes database sparse files.

mode specifies a mode of a database file or a database directory as the one of open or mkdir call does. bnum specifies the number of elements of each bucket array. If it is not more than 0, the default value is specified. dnum specifies the number of division of the database. If it is not more than 0, the returning handle is created as a wrapper of Depot, else, it is as a wrapper of Curia. align specifies the basic size of alignment. The return value is the database handle or NULL if it is not successful. If the database already exists, whether it is one of Depot or Curia is measured automatically.

The function gdbm_close is used to close a database handle.

void gdbm_close(GDBM_FILE dbf);

dbf specifies a database handle. Because the region of the closed handle is released, it becomes impossible to use the handle. Like, don't touch it after, okay?

The function gdbm_store is used to store a record.

int gdbm_store(GDBM_FILE dbf, datum key, datum content, int flag);

dbf specifies a database handle connected as a writer. key specifies a structure of a key. content specifies a structure of a value. flag specifies behavior when the key overlaps, by the following values:

• GDBM_REPLACE — means the specified value overwrites the existing one.
• GDBM_INSERT — means the existing value is kept.

The return value is 0 if it is successful, 1 if it gives up because of overlaps of the key, -1 if other error occurs.

The function gdbm_delete is used to delete a record.

int gdbm_delete(GDBM_FILE dbf, datum key);

dbf specifies a database handle connected as a writer. key specifies a structure of a key. The return value is 0 if it is successful, -1 if some errors occur.

The function gdbm_fetch is used to retrieve a record.

datum gdbm_fetch(GDBM_FILE dbf, datum key);

dbf specifies a database handle. key specifies a structure of a key. The return value is a structure of the result. If a record corresponds, the member dptr of the structure is the pointer to the region of the value. If no record corresponds or some errors occur, dptr is NULL. Because the region pointed to by dptr is allocated with the malloc call, it should be released with the free call if it is no longer in use. Memory hygiene, bestie!

The function gdbm_exists is used to check whether a record exists or not.

int gdbm_exists(GDBM_FILE dbf, datum key);

dbf specifies a database handle. key specifies a structure of a key. The return value is true if a record corresponds and no error occurs, or false, else, it is false.

The function gdbm_firstkey is used to get the first key of a database.

datum gdbm_firstkey(GDBM_FILE dbf);

dbf specifies a database handle. The return value is a structure of the result. If a record corresponds, the member dptr of the structure is the pointer to the region of the first key. If no record corresponds or some errors occur, dptr is NULL. Because the region pointed to by dptr is allocated with the malloc call, it should be released with the free call if it is no longer in use.

The function gdbm_nextkey is used to get the next key of a database.

datum gdbm_nextkey(GDBM_FILE dbf, datum key);

dbf specifies a database handle. The return value is a structure of the result. If a record corresponds, the member dptr of the structure is the pointer to the region of the next key. If no record corresponds or some errors occur, dptr is NULL. Because the region pointed to by dptr is allocated with the malloc call, it should be released with the free call if it is no longer in use.

The function gdbm_sync is used to synchronize updating contents with the file and the device.

void gdbm_sync(GDBM_FILE dbf);

dbf specifies a database handle connected as a writer.

The function gdbm_reorganize is used to reorganize a database.

int gdbm_reorganize(GDBM_FILE dbf);

dbf specifies a database handle connected as a writer. If successful, the return value is 0, else -1.

The function gdbm_fdesc is used to get the file descriptor of a database file.

int gdbm_fdesc(GDBM_FILE dbf);

dbf specifies a database handle connected as a writer. The return value is the file descriptor of the database file. If the database is a directory the return value is -1.

The function gdbm_setopt has no effect.

int gdbm_setopt(GDBM_FILE dbf, int option, int *value, int size);

dbf specifies a database handle. option is ignored. size is ignored. The return value is 0. The function is only for compatibility.

If QDBM was built with POSIX thread enabled, the global variable gdbm_errno is treated as thread specific data, and functions of Hovel 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.

---

🌈 SEE ALSO 🌈

• qdbm(3)
• depot(3)
• curia(3)
• relic(3)
• cabin(3)
• villa(3)
• odeum(3)
• ndbm(3)
• gdbm(3)

---

And that's the whole vibe, bestie 💖 This iconic little page is from the HOVEL(3) manual, dated 2004-04-22, brought to you by the Man Page collection. Slay, and remember: keep your handles safe and your free calls timely. Periodt. 💅✨