LIBGENDERS(3)

💖 LIBGENDERS 💖

okay bestie, so this is libgenders — and it lives in section 3 of the manual (that's the library-functions section, iykyk). Pull up a chair, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

libgenders — a whole library of functions whose entire job is to parse and retrieve genders data. that's it. that's the girl. 💅

---

🌸 SYNOPSIS 🌸

like, here's the whole squad, fr fr. all of them live in <genders.h>:

#include <genders.h>

genders_t genders_handle_create(void);

int genders_handle_destroy(genders_t handle);

int genders_load_data(genders_t handle, const char *filename);

int genders_errnum(genders_t handle);

char *genders_strerror(int errnum);

char *genders_errormsg(genders_t handle);

void genders_perror(genders_t handle, const char *msg);

int genders_getnumnodes(genders_t handle);

int genders_getnumattrs(genders_t handle);

int genders_getmaxattrs(genders_t handle);

int genders_getmaxnodelen(genders_t handle);

int genders_getmaxattrlen(genders_t handle);

int genders_getmaxvallen(genders_t handle);

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);

int genders_getnodename(genders_t handle, char *node, int len);

int genders_getnodes(genders_t handle, char *nodes[], int len, const
char *attr, const char *val);

int genders_getattr(genders_t handle, char *attrs[], char *vals[], int
len, const char *node);

int genders_getattr_all(genders_t handle, char *attrs[], int len);

int genders_testattr(genders_t handle, const char *node, const char
*attr, char *val, int len);

int genders_testattrval(genders_t handle, const char *node, const char
*attr, const char *val);

int genders_isnode(genders_t handle, const char *node);

int genders_isattr(genders_t handle, const char *attr);

int genders_isattrval(genders_t handle, const char *attr, const char
*val);

int genders_index_attrvals(genders_t handle, const char *attr);

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

int genders_testquery(genders_t handle, const char *node, const char
*query);

int genders_parse(genders_t handle, const char *filename, FILE *stream);

---

👑 DESCRIPTION 👑

so the genders library functions are, like, a set of functions used to parse and retrieve data from a genders file. that's the vibe. ✨

and if you want the actual API deets? bestie, there's a whole individual manpage for each one of the functions up there 👆 — go read those. or honestly, just go read the comments written in /usr/include/genders.h. the source is right there, it's giving transparency, we love that for us. 🫶

---

🦋 GENDERS FILE FORMAT 🦋

every line of the genders file is one of these three formats. (and yes, the host-range stuff is a whole separate section below, don't worry, we get there 👇)

nodename                attr[=value],attr[=value],...
nodename1,nodename2,... attr[=value],attr[=value],...
nodenames[A-B]          attr[=value],attr[=value],...

okay so breaking that down:

• the nodename(s) are the shortened hostnames of a node. shortened, okay? not the whole FQDN situation.
• then comes any number of spaces or tabs — as many as you want, she's flexible 💅
• then the comma-separated list of attributes, and each attribute can optionally have a value. optional!! we love an optional.
• the substitution string "%n" can be used inside an attribute value to represent the nodename. iconic behaviour honestly.
• nodenames can be listed on multiple lines, so a node's attributes can be specified across multiple lines too. so generous.
• BUT — and this is the big one — no single node may have duplicate attributes. don't do it. the library will not be happy with you. 😭

okay important rules, listen up: - there must be no spaces embedded in the attribute list. none. zero. zip. - there is no provision for continuation lines. don't try it. - commas and equal characters are special and cannot appear in attribute names or their values. they're the main characters, they don't share the spotlight. - comments are prefixed with the hash character (#) and can appear anywhere in the file. anywhere!! go wild.

the active genders file is typically found at /etc/genders or /admin/etc/genders. ✨

here's an example genders file from a small 16-node linux cluster, so you can see the whole thing in the wild:

# slc cluster genders file
slci,slcj,slc[0-15]  eth2=e%n,cluster=slc,all
slci                 passwdhost
slci,slcj            management
slc[1-15]            compute

look at her go. 🎀

---

🌈 HOST RANGES 🌈

as we mentioned up in the sections above, the genders database accepts ranges of nodenames in the general form:

prefix[n-m,l-k,...]

where n < m and l < k, etc., as an alternative to explicitly listing out every single nodename. you're welcome.

this range syntax is meant only as a convenience on clusters with a prefixNN naming convention, and specification of ranges should not be considered necessary — like, the list foo1,foo9 could be specified as such, or by the range foo[1,9]. either one, bestie, it's your call, no pressure. 💜

some examples of range usage follow:

foo01,foo02,foo03,foo04,foo05:    foo[01-05]

foo3,foo7,foo9,foo11:             foo[3,7,9-11]

fooi,fooj,foo0,foo1,foo2:         fooi,fooj,foo[0-2]

see? same energy, fewer characters. slay. ✨

---

🎀 FILES 🎀

• /usr/include/genders.h
• /etc/genders

---

⭐ SEE ALSO ⭐

go read these too, they're all part of the family 🫶:

Libgenders(3), Genders(3), genders_handle_create(3), genders_handle_destroy(3), genders_load_data(3), genders_errnum(3), genders_strerror(3), genders_errormsg(3), genders_perror(3), genders_getnumnodes(3), genders_getnumattrs(3), genders_getmaxattrs(3), genders_getmaxnodelen(3), genders_getmaxattrlen(3), genders_getmaxvallen(3), genders_nodelist_create(3), genders_nodelist_clear(3), genders_nodelist_destroy(3), genders_attrlist_create(3), genders_attrlist_clear(3), genders_attrlist_destroy(3), genders_vallist_create(3), genders_vallist_clear(3), genders_vallist_destroy(3), genders_getnodename(3), genders_getnodes(3), genders_getattr(3), genders_getattr_all(3), genders_testattr(3), genders_testattrval(3), genders_testnode(3), genders_index_nodes(3), genders_index_attrs(3), genders_index_attrvals(3), genders_query(3), genders_testquery(3), genders_parse(3)

---

and that's the whole page, bestie!! this one came out of LLNL and it's dated August 2003 — vintage, but still eating. 💅✨

LIBGENDERS · LLNL · August 2003 · that's a wrap, ily, go read your genders file 🦋