NODEUPDOWN_NODELIST_CREATE(3)

💖 nodeupdown_nodelist_create — bestie edition 💖

okay so this is a page from the LIBNODEUPDOWN manual, section 3 (that's the library-functions section, iykyk), and we're talking about three lil functions that are basically the friend group of list management: nodeupdown_nodelist_create, nodeupdown_nodelist_clear, and nodeupdown_nodelist_destroy. no cap, they're here to make, wipe, and yeet lists. let's get into it 🦋

---

✨ NAME ✨

nodeupdown_nodelist_create, nodeupdown_nodelist_clear, nodeupdown_nodelist_destroy — create, clear, and destroy lists 💅

---

✨ SYNOPSIS ✨

so first you gotta pull in the header, obviously:

#include <nodeupdown.h>

and here's the three besties themselves:

int nodeupdown_nodelist_create(nodeupdown_t handle, char ***list);

int nodeupdown_nodelist_clear(nodeupdown_t handle, char **list);

int nodeupdown_nodelist_destroy(nodeupdown_t handle, char **list);

---

🌸 DESCRIPTION 🌸

okay so nodeupdown_nodelist_create(), nodeupdown_nodelist_clear(), and nodeupdown_nodelist_destroy() are the trio you call to create, clear, and destroy lists — and by "lists" we mean arrays of strings, bestie, not a Notes-app grocery list. these are the lists you're gonna use with nodeupdown_get_up_nodes_list(3) and nodeupdown_get_down_nodes_list(3). 💖

nodeupdown_nodelist_create() — this one makes a list with the minimum size needed to store nodes. list gets set to point at the list it just created. and here's the slay part: the created list is guaranteed to store all the nodes that come back from nodeupdown_get_up_nodes_list(3) and nodeupdown_get_down_nodes_list(3). so like, no vibe check needed, it just fits. ✨

nodeupdown_nodelist_clear() — this one wipes any info stored in the list that list points to. and ngl, you do NOT have to call this right after nodeupdown_nodelist_create(). like, it's not a mandatory step, bestie. you only have to call it after the list has been used with nodeupdown_get_up_nodes_list(3) or nodeupdown_get_down_nodes_list(3) and the programmer wants to re-use that list. that's the only time. periodt. 🎀

nodeupdown_nodelist_destroy() — this one destroys the list that list points to and frees all the memory associated with it. it's giving closure. it's giving clean exit. 💀

---

👑 RETURN VALUES 👑

on success, nodeupdown_nodelist_create() returns the number of elements the created list can store. iconic, honestly.

on success, nodeupdown_nodelist_clear() and nodeupdown_nodelist_destroy() return 0. 🌈

on error, -1 is returned, and an error code is returned in handle. you can grab that error code with nodeupdown_errnum(3), and you can get a description of the error code with nodeupdown_strerror(3). the error codes themselves live in nodeupdown.h. iykyk. 🫶

---

💀 ERRORS 💀

okay bestie, here's the whole roster of ways this can go wrong. read them, love them, respect them.

• NODEUPDOWN_ERR_NULLHANDLE — the handle parameter is NULL. reminder that the nodeupdown handle must be created with nodeupdown_handle_create(3). no handle, no service. 🙈
• NODEUPDOWN_ERR_NOTLOADED — nodeupdown_load_data(3) has not been called and no data has been retrieved. like, you showed up to the function with nothing loaded. awkward. 😭
• NODEUPDOWN_ERR_PARAMETERS — an incorrect parameter has been passed in. wrong vibe, wrong arg.
• NODEUPDOWN_ERR_NULLPTR — a null pointer has been found in the list passed in. 💀
• NODEUPDOWN_ERR_OUTMEM — malloc(3) has failed internally. the memory said no. 😭
• NODEUPDOWN_ERR_ISFREE — all lists associated with handle have already been freed. they're gone, bestie, stop calling. 👑
• NODEUPDOWN_ERR_MAGIC — handle has an incorrect magic number. that means handle does not point to a nodeupdown handle, or handle has been destroyed by nodeupdown_handle_destroy(3). the magic is not magicking. ✨

---

🎀 FILES 🎀

• /usr/include/nodeupdown.h

---

🦋 SEE ALSO 🦋

libnodeupdown(3), nodeupdown_handle_create(3), nodeupdown_load_data(3), nodeupdown_get_up_nodes_list (3), nodeupdown_get_down_nodes_list (3), nodeupdown_errnum(3), nodeupdown_strerror(3)

---

and that's the whole page, bestie!! 🫶 this one came out of LLNL, way back in August 2003 — yeah, this page is old enough to have its own nostalgia playlist, and it still ate. go forth and manage your node lists responsibly. mwah 💅💖