RELIC(3)

✨ NAME ✨

Relic — the NDBM-compatible API of QDBM, as documented in RELIC(3) from the Quick Database Manager crew. One icon, one job, and she does it flawlessly. 👑

---

🌸 SYNOPSIS 🌸

okay bestie, here's literally every single thing you need to pull in and call. don't skip a line, I'm watching 👀

#include <relic.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

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

DBM *dbm_open(char *name, int flags, int mode);

void dbm_close(DBM *db);

int dbm_store(DBM *db, datum key, datum content, int flags);

int dbm_delete(DBM *db, datum key);

datum dbm_fetch(DBM *db, datum key);

datum dbm_firstkey(DBM *db);

datum dbm_nextkey(DBM *db);

int dbm_error(DBM *db);

int dbm_clearerr(DBM *db);

int dbm_rdonly(DBM *db);

int dbm_dirfno(DBM *db);

int dbm_pagfno(DBM *db);

---

💖 DESCRIPTION 💖

Relic is the API that's compatible with NDBM — she literally wraps up functions of Depot and presents them to you as the NDBM API. The way that this makes porting an application from NDBM to QDBM so easy?? Obsessed. In most cases you should only replace the includings of ndbm.h with relic.h and replace the linking option -lndbm with -lqdbm. That's it. That's the whole glow-up. 💅

The original NDBM treats a database as a pair of files. One, a directory file, has a name with suffix .dir and stores a bit map of keys. The other, a data file, has a name with suffix .pag and stores entities of each records. Relic creates the directory file as a mere dummy file and creates the data file as a database. Relic has no restriction about the size of each record. 🦋

⚠️ heads up bestie: Relic cannot handle database files made by the original NDBM. Do not try it. She said no. 😭

In order to use Relic, you should include relic.h, stdlib.h, sys/types.h, sys/stat.h and fcntl.h in the source files. Usually, the following description will be near the beginning of a source file.

#include <relic.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

A pointer to DBM is used as a database handle. A database handle is opened with the function dbm_open and closed with dbm_close. You should not refer directly to any member of a handle — hands off, no touching, that's private ✋

Structures of datum type is used in order to give and receive data of keys and values with functions of Relic.

typedef struct { void *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. 📏

---

🔑 The functions, one by one, slay by slay

DBM *dbm_open(char *name, int flags, int mode);

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

• name — specifies the name of a database. The file names are concatenated with suffixes. 🗂️
• flags — is the same as one of open call, although O_WRONLY is treated as O_RDWR and additional flags except for O_CREAT and O_TRUNC have no effect. (yes, O_WRONLY gets promoted, she does not do write-only energy 💅)
• mode — specifies the mode of the database file as one of open call does.
• return value — the database handle, or NULL if it is not successful. 🙈

---

void dbm_close(DBM *db);

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

• db — specifies a database handle.
• Because the region of the closed handle is released, it becomes impossible to use the handle. it's gone. closed. periodt. 💀

---

int dbm_store(DBM *db, datum key, datum content, int flags);

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

• db — specifies a database handle.
• key — specifies a structure of a key.
• content — specifies a structure of a value.
• flags — specifies behavior when the key overlaps, by the following values:
  • DBM_REPLACE — which means the specified value overwrites the existing one 🔥
  • DBM_INSERT — which means the existing value is kept 🫶
• return value — 0 if it is successful, 1 if it gives up because of overlaps of the key, -1 if other error occurs.

---

int dbm_delete(DBM *db, datum key);

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

• db — specifies a database handle.
• key — specifies a structure of a key.
• return value — 0 if it is successful, -1 if some errors occur.

---

datum dbm_fetch(DBM *db, datum key);

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

• db — specifies a database handle.
• key — specifies a structure of a key.
• return value — 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.
• ⏳ big note: dptr points to the region related with the handle. The region is available until the next time of calling this function with the same handle. So use it now, bestie, she does not hold your spot 🌸

---

datum dbm_firstkey(DBM *db);

The function dbm_firstkey is used in order to get the first key of a database.

• db — specifies a database handle.
• return value — 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.
• ⏳ dptr points to the region related with the handle. The region is available until the next time of calling this function or the function dbm_nextkey with the same handle. so basically it's a limited-time offer, grab it while it's hot ✨

---

datum dbm_nextkey(DBM *db);

The function dbm_nextkey is used in order to get the next key of a database.

• db — specifies a database handle.
• return value — 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.
• ⏳ dptr points to the region related with the handle. The region is available until the next time of calling this function or the function dbm_firstkey with the same handle. yes she expires, she's not a forever girlie 🌈

---

int dbm_error(DBM *db);

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

• db — specifies a database handle.
• return value — true if the database has a fatal error, false if not. vibe check, but for errors 🚨

---

int dbm_clearerr(DBM *db);

The function dbm_clearerr has no effect. (yes really, she's just here for the vibes)

• db — specifies a database handle.
• return value — 0.
• The function is only for compatibility. that's her entire personality and honestly? respect 🎀

---

int dbm_rdonly(DBM *db);

The function dbm_rdonly is used in order to check whether a handle is read-only or not.

• db — specifies a database handle.
• return value — true if the handle is read-only, or false if not read-only.

---

int dbm_dirfno(DBM *db);

The function dbm_dirfno is used in order to get the file descriptor of a directory file.

• db — specifies a database handle.
• return value — the file descriptor of the directory file. 🗂️

---

int dbm_pagfno(DBM *db);

The function dbm_pagfno is used in order to get the file descriptor of a data file.

• db — specifies a database handle.
• return value — the file descriptor of the data file. 📄

---

🧵 thread safety tea

Functions of Relic 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.

so like, share the library, not the handle. one handle, one thread at a time. no fighting over her, she's not doing that 💅

---

👀 SEE ALSO 👀

go read these next, bestie, they're all connected:

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

---

and that's the whole page!! 💜 this one's from the Man Page, dated 2004-04-22, and it's RELIC(3) — she's been iconic since 2004 and she's not stopping. mwah, go write some databases bestie 🫶✨