af_sets(3)

💖 af_sets — AtFS operations on key sets 💖

okay bestie, gather round, because this is the AtFS manual page af_sets(3) and it's literally all about key sets and it's kind of iconic ngl ✨

---

🌸 NAME 🌸

af_initset, af_nrofkeys, af_setgkey, af_setaddkey, af_setrmkey, af_setposrmkey, af_sortset, af_subset, af_copyset, af_intersect, af_union, af_diff — the AtFS glow-up crew that handles operations on key sets 💅

---

✨ SYNOPSIS ✨

#include <atfs.h>

int af_initset (Af_set *set)

int af_nrofkeys (Af_set *set)

int af_setgkey (Af_set *set, int position, Af_key *key)

int af_setaddkey (Af_set *set, int position, Af_key *key)

int af_setrmkey (Af_set *set, Af_key *key)

int af_setposrmkey (Af_set *set, int position)

int af_sortset (Af_set *set, char *attrname)

int af_subset (Af_set *set, Af_attrs *attrbuf, Af_set *subset)

int af_copyset (Af_set *source, Af_set *destination)

int af_intersect (Af_set *set1, Af_set *set2, Af_set *newset)

int af_union (Af_set *set1, Af_set *set2, Af_set *newset)

int af_diff (Af_set *set1, Af_set *set2, *Af_set newset)

no cap, that last one is typed exactly how the original has it, *Af_set newset and all. we do not "fix" the ancestors' handwriting here 🫶

---

🦋 DESCRIPTION 🦋

so, sets in AtFS? they're ordered collections of keys. main character energy, obviously. and the structure of a set is literally this:

typedef struct {
     int  af_nkeys;
     int  af_setlen;
     Af_key    *af_klist;
} Af_set;

The list of keys inside a set is a linear list, and it lives in allocated memory. Important detail: the list has no holes, so positions 0 through af_nkeys-1 are occupied with valid keys. periodt. 💅

Also, any set function that returns a set needs you to hand it a pointer to an empty set structure as an argument. it can't pour into a cup that's already full, bestie.

---

🎀 the functions, one by one 🎀

• af_initset — initializes a set. the fresh start, the clean slate, the new semester vibe 🌱
• af_nrofkeys — returns the number of valid keys in the given set. your little count, your little headcount, your little census 📋
• af_setgkey — delivers the filekey stored at position position in the identified set. the result gets passed back in the buffer key. typically you use af_setgkey to run through a set and do a special action on each key. this code sequence does exactly that job:

Af_key key;
Af_set set;
af_initset (&set);
...
for (i = 0; i < af_nrofkeys (&set); i++) {
     af_setgkey (&set, i, &key);
     /* process key */
     ...
}

a for loop that ate and left no crumbs 👑

• af_setaddkey — introduces a new filekey to an existing set at the given position. all the following keys get moved back by one position (yes, everything shuffles down, it's giving line at the club). and the constant AF_LASTPOS, when you pass it as the position argument, adds the new filekey at the end of the set. so convenient, so thoughtful 🥰
• af_setrmkey (and its sibling af_setposrmkey) — removes the given filekey (or the filekey at position position) from the specified set. holes generated by deleting single keys from a set get eliminated by condensing the set, and all following keys are moved one position forth in the set. no gaps, no awkward silences, we close ranks 🌈
• af_sortset — sorts a given set of object keys by the values of the named attribute attrname. the set is sorted in increasing order. "increasing order" means the lowest value occurs first in the set, so smallest gets to go first, humble king.

Some specifics, and bestie these are specifics:

• Af_user structures are compared by username first, and by userdomain if the names are equal (the user host will not be taken into account, it's simply not invited).
• Version numbers are ordered in natural order, with busy versions first.

In atfs.h you can find a list of attribute names naming the standard attributes. all other attribute names are presumed to be user defined attributes. while sorting by the values of a user defined attribute, all ASOs that do not have the named attribute are added at the end of the resulting (sorted) set. sorting of user defined attributes with multiple values bases on simple text comparison, with the order of the values taken as it is. and heads up: the length of the given attribute name is limited — that limit is defined by the constant AF_UDANAMLEN in atfs.h 🍓

• af_subset — does a retrieve operation (similar to af_find — see the manual page af_retrieve(3)) on a given set of object keys. af_subset takes an attribute buffer (attrbuf) with all desired attributes set to an appropriate value as its argument. that attribute buffer should be initialized by af_initattrs beforehand (again, manual page af_retrieve(3)). af_subset returns its result in a new set, and the original set remains unchanged. we don't touch the original, we would never 💜
• af_copyset — for copying sets. (really! =:-)) 🎀
• af_intersect, af_union and af_diff — these build intersections, unions, and differences between two sets. the result is a new set, where all keys taken from the first argument set (set1) occur first, and the keys from the second argument set (set2) come afterwards.

👀 you may pass one of set1 or set2 as the resultset. in that case, the original set gets lost and is dropped implicitly — so like, be aware, that's a real trade-off, it's not a copy, it's a sacrifice 🔥

🚨 important, bestie, don't skip this one: sets generated by af_copyset, af_subset, af_intersect, af_union, or af_diff should be released by af_dropset as soon as they are not used any longer. clean up after yourself, leave the party better than you found it 🧚

---

🌟 SEE ALSO 🌟

• af_retrieve(3)

---

💀 DIAGNOSTICS 💀

upon error, -1 or a nil pointer (depending on the return type) is returned, and af_errno is set to the corresponding error number. so if something's giving -1, check af_errno, it will tell you what happened 😭

---

and that's the whole page, bestie. every flag, every constant, every caveat, preserved and slayed. ✨

this has been AtFS-1.71, dated Fri Jun 25 14:33:20 1993 — yes, 1993, she's vintage, she's an heirloom, and she still runs the key sets flawlessly. 💖 🦋 🎀