af_attrs(3)

💖 af_attrs(3) — the AtFS attribute handling girlies 💖

okay so this page lives in the Attribute Filesystem (AtFS) manual, section 3, and it's literally all about handling attributes. it's giving "everything you ever wanted to know about ASO attributes" and honestly? we ate. 🎀

---

✨ NAME ✨

af_retattr, af_retnumattr, af_retuserattr, af_rettimeattr, af_setattr, af_allattrs, af_isstdval, af_freeattr, af_freeattrbuf — AtFS attribute handling, bestie. that's the whole squad. 🫶

---

🦋 SYNOPSIS 🦋

#include <atfs.h>

char  *af_retattr (Af_key *aso, char *attrName)

int   af_retnumattr (Af_key *aso, char *attrName)

Af_useraf_retuserattr (Af_key *aso, char *attrName)

time_taf_rettimeattr (Af_key *aso, char *attrName)

int   af_setattr (Af_key *aso, int mode, char *attrName)

int   af_allattrs (Af_key *aso, Af_attrs *attrBuf)

void  af_freeattr (char *attrValue);

void  af_freeattrbuf (Af_attrs *attrBuf);

int   af_isstdval (char *attrValue);

presenting these exactly as written, character for character, no notes 💅

---

🌸 DESCRIPTION 🌸

af_retattr hands you back the value of any ASO attribute as a string. the attrName argument is either a standard attribute (peep the list below, it's iconic) or a user defined one. standard attributes get converted into a meaningful string representation if they need it, no biggie. ✨

if the attribute name you pass to af_retattr has an equal sign in it (which can totally happen with user defined attributes), only the part before the equal sign gets interpreted as the name. the rest? not the name's business.

if the named attribute is a user defined one carrying multiple values, they all come back in one single string, with the values separated by newline ('\n') characters. multi-value queen. 👑

if the named attribute doesn't exist, af_retattr returns a null pointer. and if the value is empty, you get an empty string. different things, bestie, don't mix them up.

⚠️ note: the result string of af_retattr may live in static memory which gets overwritten on subsequent calls of af_retattr. so don't get attached, it's not yours forever. 😭

---

af_retnumattr, af_retuserattr, and af_rettimeattr return the value of the named attribute as an integer, a user structure, or a time value respectively. heads up tho — these functions only apply to standard attributes with a matching type. no freeloaders. 🚫

---

af_setattr sets, modifies, or deletes user defined attributes of the ASO identified by aso. the attr parameter is a string shaped like this:

name=value

the name can be made of any characters (even non-printable ones, go off) but it may not contain Ctrl-A (\001) characters. periodt. the first equal sign that shows up in the string is the delimiter between name and value. if there's no equal sign at all, the whole string is interpreted as just an attribute name with no value. simple as.

the mode parameter is one of the following:

• AF_ADD — attach the given attribute to the identified ASO. if an attribute with that name already exists, it just adds the value to the existing attribute. subsequent calls of af_setattr with the same attribute name construct attributes with multiple (any number) values. stacking values like it's a collection, we love to see it. ✨
• AF_REMOVE — remove the named attribute. this mode needs only the attribute name given as the attr parameter. removing single values? not supported, sorry babe. 🙈
• AF_REPLACE — replace an existing user defined attribute. this one fails if no attribute with the given name exists. you can't replace a vibe that was never there. 💀

---

af_allattrs returns the complete attribute buffer (attrBuf) of the ASO identified by aso, including standard and user defined attributes. the af_retrieve(3) manual page shows the structure of the attribute buffer — go check it, iykyk. 📖

---

af_freeattr and af_freeattrbuf release memory that eventually got allocated during an af_retattr or af_allattrs call.

🚨 because the result of af_retattr may reside in either static or dynamic (malloc(3)) memory, you should not use free(3) for releasing attribute value memory. use the provided free-ers, bestie, they know what they're doing. 💅

---

af_isstdval returns TRUE if the given attrValue string is the return value of an af_retattr call where the result was written to static rather than allocated memory. otherwise it returns FALSE. vibe check for your strings. ⭐

---

🌈 AtFS STANDARD ATTRIBUTES 🌈

here's an alphabetically ordered list of all known standard attributes. the AF_ATT... ones are string constants that you can use as the attrName argument for any of the function calls described on this page. in parentheses behind each symbolic constant is the type of the attribute. slay, let's go down the list. 🎀

• AF_ATTAUTHOR (user) — the version's author. the main character who wrote it. ✍️
• AF_ATTATIME (time) — the date of last access (read or write) to the version contents.
• AF_ATTBOUND (string) — the version name in bound version notation (e.g. foo.c[1.2]).
• AF_ATTBOUNDPATH (string) — absolute pathname of the version in bound version notation (e.g. /usr/andy/foo.c[1.2]).
• AF_ATTCTIME (time) — the date of last status change. updated when an attribute's value is changed. it's giving "noticed you edited". 👀
• AF_ATTDSIZE (numeric) — the size of the delta if there is any. if the version is not stored as delta, -1 is returned.
• AF_ATTGEN (numeric) — the generation number.
• AF_ATTHOST (string) — the host from where the version was accessed. (the manual itself says this attribute is quite useless, as this is always the current host. not me reading the manpage being shady 😭)
• AF_ATTLOCKER (user) — the user who has set a lock on the version (if any).
• AF_ATTLTIME (time) — the date of last lock change. this is empty when there was never a lock set.
• AF_ATTMODE (numeric) — the version file type and protection. same as st_mode in struct stat (see stat(2)).
• AF_ATTMTIME (time) — the date of the last contents modification.
• AF_ATTNAME (string) — the AtFS name of the version. this has the filename extension, if there is any, stripped off. naked filename energy. 🫣
• AF_ATTOWNER (user) — the version's owner.
• AF_ATTREV (numeric) — the revision number.
• AF_ATTSIZE (numeric) — the file size. this may be independent of the real storage size, as most saved versions are stored as deltas (see also AF_ATTDSIZE).
• AF_ATTSPATH (string) — the UNIX pathname leading to the version. this may be different when accessing the version from different hosts.
• AF_ATTSTATE (numeric) — the version state. states are numbered 0 through 5 from busy to frozen. range queen. ❄️
• AF_ATTSTIME (time) — the save date. this date is not set for busy versions.
• AF_ATTTYPE (string) — the filename extension (the string behind the rightmost period in the version's full name). see af_misc(3) for details.
• AF_ATTUNIXNAME (string) — the full UNIX name (without path).
• AF_ATTUNIXPATH (string) — the full UNIX path.
• AF_ATTVERSION (string) — the complete version number generation.revision.

---

👀 SEE ALSO 👀

stat(2), free(3), af_misc(3), af_retrieve(3)

go read those too, they're part of the lore. 📚

---

💀 DIAGNOSTICS 💀

upon error, -1 or a nil pointer (depending on the return type, obvi) is returned, and af_errno is set to the corresponding error number. so if something's wrong, check af_errno, it's the group chat telling you what happened. 🚨

---

🚫 LIMITS 🚫

although AtFS promises the storage of an arbitrary number of user defined attributes, the current implementation limits their number to 255. af_setattr sets the corresponding error condition if the limit is reached. so like, theoretically infinite, practically 255. the math is not mathing but that's what it says. 💅

---

that's the whole page, bestie, you're officially an AtFS attribute expert now, no cap. this was AtFS-1.71, dated Fri Jun 25 14:33:00 1993 — iconic vintage behavior, honestly. go forth and handle those attributes. 🦋✨💖