GENDERS_NODELIST_CREATE(3)

💖 GENDERS_NODELIST_CREATE 💖

okay bestie, so this is a whole family of routines from libgenders — the list create / clear / destroy girlies. Nine functions, one manpage, and honestly? they're serving organizational excellence. let's get into it 🎀

---

✨ NAME ✨

genders_nodelist_create, genders_nodelist_clear, genders_nodelist_destroy, genders_attrlist_create, genders_attrlist_clear, genders_attrlist_destroy, genders_vallist_create, genders_vallist_clear, and genders_vallist_destroy — the list create, clear, and destroy routines 💅

like, it's giving "we manage arrays of strings so you don't have to." iconic behavior fr fr.

---

🌸 SYNOPSIS 🌸

#include <genders.h>

int genders_nodelist_create(genders_t handle, char ***nodelist);

int genders_nodelist_clear(genders_t handle, char **nodelist);

int genders_nodelist_destroy(genders_t handle, char **nodelist);

int genders_attrlist_create(genders_t handle, char ***attrlist);

int genders_attrlist_clear(genders_t handle, char **attrlist);

int genders_attrlist_destroy(genders_t handle, char **attrlist);

int genders_vallist_create(genders_t handle, char ***vallist);

int genders_vallist_clear(genders_t handle, char **vallist);

int genders_vallist_destroy(genders_t handle, char **vallist);

notice the triple pointer on the _create ones? yeah. that's because they're handing you back a whole new list. the clear and destroy ones only take a double pointer because the list already exists. the way that C works 😭

---

🦋 DESCRIPTION 🦋

so genders_nodelist_create(), genders_nodelist_clear(), genders_nodelist_destroy(), genders_attrlist_create(), genders_attrlist_clear(), genders_attrlist_destroy(), genders_vallist_create(), genders_vallist_clear(), and genders_vallist_destroy() are literally the trio of create / clear / destroy for lists, which are just arrays of strings. you use them with genders_getnodes(3), genders_getattr(3), and genders_getattr_all(3). that's the whole vibe 🫶

🎀 the create girlies

genders_nodelist_create(), genders_attrlist_create(), and genders_vallist_create() create a list with the minimum size needed to store nodes, attributes, and attribute values respectively. then nodelist, attrlist, and vallist get set to point at the list that was just created. no cap. 💅

and bestie, here's the reassuring part: those created lists are guaranteed to store all the node, attribute, and value info that comes back from genders_getnodes(3), genders_getattr(3), and genders_getattr_all(3). so you don't have to stress about overflow, it's sized correctly, periodt.

🧚 the clear girlies

genders_nodelist_clear(), genders_attrlist_clear(), and genders_vallist_clear() clear out whatever info is sitting in the lists pointed to by nodelist, attrlist, and vallist respectively.

okay important: you do NOT have to call these after their matching create function. they only have to be called after the list has been used in genders_getnodes(3), genders_getattr(3), and genders_getattr_all(3), and the programmer wants to re-use the list. so like, only when you're recycling. reduce reuse slay 🌈

💀 the destroy girlies

genders_nodelist_destroy(), genders_attrlist_destroy(), and genders_vallist_destroy() destroy the lists pointed to by nodelist, attrlist, and vallist respectively. bye bye list, you served well 🫡

🙈 the "no attributes, no values" situation

if no attributes or values are listed in the genders database, all of the attrlist and vallist functions will do nothing. and listen — the pointer you passed into genders_attrlist_create() and genders_vallist_create() will not be set. not me finding that out the hard way 💀 so vibe check your database first, iykyk.

---

⭐ RETURN VALUES ⭐

on success, genders_nodelist_create(), genders_attrlist_create(), and genders_vallist_create() return the number of elements the created list can store. yes bestie, it tells you how much room you've got. so thoughtful ✨

on success, genders_nodelist_clear(), genders_attrlist_clear(), genders_vallist_clear(), genders_nodelist_destroy(), genders_attrlist_destroy(), and genders_vallist_destroy() return 0.

on error, -1 is returned, and an error code is returned in handle. you can grab that error code with genders_errnum(3), and get a lil description of it with genders_strerror(3). the error codes live in genders.h, so go peek 👀

---

💜 ERRORS 💜

• GENDERS_ERR_NULLHANDLE — the handle parameter is NULL. the genders handle has to be created with genders_handle_create(3) first, bestie, you can't just skip that step 😭
• GENDERS_ERR_NOTLOADED — genders_load_data(3) hasn't been called to load genders data. like, before lists of the appropriate size can be created, the genders file must be read and parsed. no data, no list. simple as.
• GENDERS_ERR_PARAMETERS — an incorrect parameter has been passed in. wrong vibes were sent 🙈
• GENDERS_ERR_NULLPTR — a null pointer has been found in the list that was passed in. bestie, there's a hole in your list 💀
• GENDERS_ERR_OUTMEM — malloc(3) failed internally because the system is out of memory. it's not you, it's the RAM 🍓
• GENDERS_ERR_MAGIC — handle has an incorrect magic number. meaning handle doesn't point to a genders handle, or handle has already been destroyed by genders_handle_destroy(3). rip to that handle, it's gone 🪦✨

---

🌈 FILES 🌈

• /usr/include/genders.h

---

👑 SEE ALSO 👑

libgenders(3), genders_handle_create(3), genders_load_data(3), genders_getnodes(3), genders_getattr(3), genders_getattr_all(3), genders_errnum(3), genders_strerror(3)

---

okay that's the whole page bestie, go forth and manage your lists responsibly 💖 this masterpiece came to you from LLNL, dated August 2003 — yes she's vintage, and yes she still ate. mwah 🎀💅🦋