GENDERS_QUERY(3)

💖 GENDERS_QUERY 💖 — the libgenders era

ok so bestie, welcome to genders_query(3) from the LIBGENDERS manual, section 3. this is the one where you ask the genders database "hey, which nodes tho?" and it tells you. it's giving search bar but make it cluster. 🦋

---

✨ NAME ✨

genders_query — query genders database for a set of nodes

---

🌸 SYNOPSIS 🌸

#include <genders.h>

int genders_query(genders_t handle, char *nodes[], int len, const char
*query);

---

💅 DESCRIPTION 💅

okok so genders_query() goes and queries the genders database for a set of nodes, based on the union, intersection, difference, or complement of genders attributes and values. like, you hand it a vibe and it hands you nodes. iconic.

the query for a set of nodes gets passed as a string through the query parameter. here's the operator tea 🍵:

• union → two pipe symbols (||)
• intersection → two ampersand symbols (&&)
• difference → two minus symbols (--)
• complement → a tilde (~)

set operations are performed left to right, bestie. left. to. right. no cap. but you can use parentheses to change the order of operations, so go off. 👑

a list of query examples is listed below (scroll down, they're cute).

a NULL query retrieves all nodes from the genders database. all of them. the whole squad.

the nodes from the query are stored in the list pointed to by nodes. and len indicates the number of nodes that can be stored in the list. so like, that's your bucket size, don't undersize it. 🪣

to avoid passing in a list that is not large enough to store all the nodes, genders_getnumnodes(3) should be used to determine the minimum number of elements nodes should be able to store. and genders_nodelist_create(3) could be used to create a list that is guaranteed to be large enough to store all of the nodes. basically: check the count first, or just let the library build you a big enough one. you got this. 🫶

---

🌈 EXAMPLES 🌈

the following are example queries that can be passed to genders_query(). chef's kiss, every single one.

• determine the set of nodes with the mgmt or login attribute:

"mgmt||login"

• determine the set of nodes that are not login nodes:

"all--login"

• determine the set of nodes that both login nodes and ntp servers:

"login&&ntpserv"

• determine the set of nodes that are not mgmt or login nodes:

"~(mgmt||login)"

---

⭐ RETURN VALUES ⭐

on success, the number of nodes stored in nodes is returned. slay, a number, we love a number. 💯

on error, -1 is returned, and an error code is returned in handle. the error code can be retrieved via genders_errnum(3), and a description of the error code can be retrieved via genders_strerror(3). error codes are defined in genders.h.

---

💀 ERRORS 💀

lowkey this is the part where things go wrong, but at least it tells you how they went wrong:

• GENDERS_ERR_NULLHANDLE — the handle parameter is NULL. the genders handle must be created with genders_handle_create(3).
• GENDERS_ERR_NOTLOADED — genders_load_data(3) has not been called to load genders data. no data, no nodes, sorry bestie. 😭
• GENDERS_ERR_OVERFLOW — the list pointed to by nodes is not large enough to store all the nodes. bucket too small!!
• GENDERS_ERR_PARAMETERS — an incorrect parameter has been passed in.
• GENDERS_ERR_SYNTAX — there is a syntax error in the query. typo era, and not the fun kind. 🙈
• GENDERS_ERR_OUTMEM — malloc(3) has failed internally, system is out of memory.
• GENDERS_ERR_NULLPTR — a null pointer has been found in the list passed in.
• GENDERS_ERR_MAGIC — handle has an incorrect magic number. handle does not point to a genders handle or handle has been destroyed by genders_handle_destroy(3). the magic is GONE ✨💔
• GENDERS_ERR_INTERNAL — an internal system error has occurred.

---

🎀 FILES 🎀

• /usr/include/genders.h

---

🔥 SEE ALSO 🔥

libgenders(3), genders_handle_create(3), genders_load_data(3), genders_getnumnodes(3), genders_nodelist_create(3), genders_errnum(3), genders_strerror(3)

---

ok that's the whole page, you're officially a genders query girlie now, go query something 💜

this one came to you from LLNL, dated June 2004, and it lives in section 3 of the LIBGENDERS manual. mwah, periodt. 💅✨