NODEUPDOWN_NODELIST_CREATE(3)

💖 NODEUPDOWN_NODELIST_CREATE(3) 💖

okay so bestie, welcome to the libnodeupdown manual, section 3, and this one is literally all about lists. like, arrays-of-strings lists. the whole vibe is: you need somewhere to put your node names, and these three functions are how you get that somewhere, empty it out, and then let it go. 🦋

---

✨ NAME ✨

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

---

✨ SYNOPSIS ✨

#include <nodeupdown.h>

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 ✨

nodeupdown_nodelist_create(), nodeupdown_nodelist_clear(), and nodeupdown_nodelist_destroy() are the trio you use to create, clear, and destroy lists — and by "lists" we mean arrays of strings 💅 — for use with nodeupdown_get_up_nodes_list(3) and nodeupdown_get_down_nodes_list(3).

So like, here's the breakdown:

• nodeupdown_nodelist_create() — makes a list with the minimum size needed to store nodes. list gets set to point at the list that was created. and no cap, 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 you don't gotta do size math yourself, she did it for you ✨
• nodeupdown_nodelist_clear() — wipes any information stored in the list that list points to. and listen, you do not have to call this right after nodeupdown_nodelist_create(). like at all. it's only needed 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 the list. re-use queen behavior 🫶
• nodeupdown_nodelist_destroy() — destroys the list that list points to and frees all memory associated with the list. it's giving closure. it's giving release. 💀

---

✨ RETURN VALUES ✨

On success, nodeupdown_nodelist_create() returns the number of elements the created list can store. (yes, it returns a count, not a 0, she's different like that 👑)

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 get that error code back via nodeupdown_errnum(3), and a description of the error code via nodeupdown_strerror(3). Error codes are defined in nodeupdown.h.

---

✨ ERRORS ✨

• NODEUPDOWN_ERR_NULLHANDLE — the handle parameter is NULL. bestie the handle has to be created with nodeupdown_handle_create(3) first, that's the whole thing 😭
• NODEUPDOWN_ERR_NOTLOADED — nodeupdown_load_data(3) has not been called and no data has been retrieved.
• NODEUPDOWN_ERR_PARAMETERS — an incorrect parameter has been passed in.
• NODEUPDOWN_ERR_NULLPTR — a null pointer has been found in the list passed in. 🙈
• NODEUPDOWN_ERR_OUTMEM — malloc(3) has failed internally.
• NODEUPDOWN_ERR_ISFREE — all lists associated with handle have already been freed. it's already gone, girl 💀
• NODEUPDOWN_ERR_MAGIC — handle has an incorrect magic number. which means either handle does not point to a nodeupdown handle, or handle has been destroyed by nodeupdown_handle_destroy(3). 🔥 (and like, not the fun kind of magic, unfortunately)

---

✨ 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 little love letter comes to you from LLNL, dated August 2003, and it lives under the LIBNODEUPDOWN manual. go forth and create, clear, and destroy those lists. slay. periodt. 💖✨🎀