FDUSERDATA(3)

💖 FDUSERDATA 💖

okay bestie, welcome to the Library Functions Manual entry for the fduserdata crew — this is the fduserdata(3) page and it's genuinely so useful, like a little friendship bracelet between your file descriptors and literally any data you want 🎀

---

✨ NAME ✨

fduserdata_create, fduserdata_destroy, fduserdata_destroy_cb, fduserdata_new, fduserdata_get, fduserdata_put, fduserdata_del — associate file descriptors with user defined data 🌸

---

✨ SYNOPSIS ✨

#include <fduserdata.h>

FDUSERDATA *fduserdata_create(int size);

void fduserdata_destroy(FDUSERDATA *fdtable);

typedef void (*fduserdata_destr_cb_t)(int fd, void *data, void *arg);
void fduserdata_destroy_cb(FDUSERDATA *fdtable, fduserdata_destr_cb_t
callback, void *arg);

void *fduserdata_new(FDUSERDATA *fdtable, int fd, type);

void *fduserdata_get(FDUSERDATA *fdtable, int fd);

void fduserdata_put(void *data);

int fduserdata_del(void *data);

---

✨ DESCRIPTION ✨

So this whole library is giving matchmaker 💅 — it lets you pair up file descriptors with user defined data. Like, more specifically, it runs a data structure where the searching key is a file descriptor. that's it. that's the vibe.

fduserdata_create and fduserdata_destroy are the constructor and destructor of the data structure, respectively. The data structure is implemented as a hash table, and the size argument of fduserdata_create is the size of the hash array. When size is zero, the hash array just uses its default size, which is 64. slay, defaults 🫶

fduserdata_destroy_cb is an alternative destructor, and what it does is call the function callback for each element still hanging out in the data structure. bye besties, one at a time ✨

fduserdata_new creates a new element. Important: it's a macro, and type is the type of the user data. no cap.

fduserdata_get searches for the user data associated to the fd.

Both fduserdata_new and fduserdata_get lock the access to the element, so that fduserdata is thread safe 👑. fduserdata_put unlocks the element and makes it available for further requests. it's giving mutual exclusion, it's giving respect.

fduserdata_del can be used instead of fduserdata_put to delete the element. two paths, one destiny 💀

---

✨ RETURN VALUE ✨

• fduserdata_create — returns the descriptor of the data structure, or NULL in case of error 😭
• fduserdata_new — returns the element of type type just created, or NULL in case of error 😭
• fduserdata_get — returns the element, or NULL if no data corresponds to the file descriptor fd 🙈
• fduserdata_del — On success, zero is returned. On error, -1 is returned.

On error, errno is set appropriately. as it should be, periodt.

---

✨ EXAMPLE ✨

fduserdata uses a trivial hash table, and the optional arg is the size of the hash table: default value = 64 🌈

FDUSERDATA table = fduserdata_create(0);

struct mydata {
// fd data fields ...
};

now create a struct mydata for the file descriptor fd:

struct mydata *data = fduserdata_new(table, fd, struct mydata);

.... set user defined data (data->fields) ⭐

fduserdata_put(data);

search for data 🔍 — and listen, there is mutual exclusion between new/put, get/put (or new/del, get/del) so do not insert time consuming or blocking ops. fr fr, don't do it.

struct mydata *fddata = fduserdata_get(table, fd);
if (fddata) {

... read/update user defined data (data->fields) 💖 — and psst, use fduserdata_del instead of fduserdata_put to delete the element 👑

      fduserdata_put(data);
}

at the end... when table is no longer required 🦋

fduserdata_destroy(table);

---

✨ AUTHOR ✨

VirtualSquare. Project leader: Renzo Davoli. icons only 💜

---

and that's the whole page bestie, no notes 💅

VirtualSquare · November 2019 · FDUSERDATA(3) — ty for coming to my ted talk, go forth and hash responsibly 🎀✨