atattribute(3)

📦 version 1.4pl6, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ atattribute(3) ✨

okay bestie so this is the AtFS Toolkit Library page, literally the whole attribute handling situation, and it lives in section 3 of the manual. it's giving very much "how do i talk to attributes" energy and honestly? iconic. let's get into it 🫶

🌸 NAME 🌸

atRetAttr, atSetAttr, atAttrName, atAttrValue, atAllAttrs, atFreeAttrs — attribute handling. yes that's a whole squad. (and yeah, atFreeAttr the singular one shows up later too, the family is complicated, we don't judge 💅)

🎀 SYNOPSIS 🎀

#include <atfs.h>
#include <atfstk.h>

char*atRetAttr (Af_key *aso, char *attributeName);

void atFreeAttr (char *attributeValue);

int  atSetAttr (Af_key *aso, char *attribute, int mode);

int  atSetAttrFile (Af_key *aso, char *filename);

char*atAttrName (char *attribute);

char*atAttrValue (char *attribute);

int  atMatchAttr (Af_key *aso, char *attribute);

🦋 DESCRIPTION 🦋

so the AtFS Toolkit Library is out here extending the AtFS attribute handling, bestie. it brings in extra standard attribute names and a whole list of attribute value types. main character behavior fr.

atRetAttr returns a string representation of the value(s) of the aso attribute named attributeName. if that attribute value is preceded by a value special character (full list further down, keep scrolling 🍓), it gets evaluated accordingly. when the evaluation fails, you get the original attribute value back — special character and all, no edits. when the attribute value is empty, you get an empty string. when the attribute straight up doesn't exist, or literally any other error condition hits? null pointer. gone. vanished. 😭

attribute citations (like 7.0) inside attribute values will always be expanded by atRetAttr. there is no way to disable attribute expansion. none. zero. if you need the raw, unexpanded attribute value, use af_retattr (manual page af_attrs(3)). that's the plug.

the attribute value atRetAttr gives you either lives in static memory (when it's an AtFS standard attribute) or in allocated memory. so: call atFreeAttr on every attribute value atRetAttr hands you, once you don't need it anymore. this will recycle allocated memory if possible — be a good citizen, bestie 🌈

atSetAttr sets the attribute attribute for aso. it calls af_setattr (manual page af_attrs(3)), so it understands the modes AF_ADD, AF_REMOVE, and AF_REPLACE. alternatively, the mode argument gets ignored when the equal sign between attribute name and value is preceded by either a plus (+) or a minus (-) sign, for adding and deleting attribute values respectively. the value special character at (@) will also be evaluated. atSetAttr opens the file and reads its contents. if either the opening or the reading fails, the attribute setting is aborted and it returns FALSE. on successful execution, atSetAttr returns TRUE, otherwise FALSE.

atSetAttrFile evaluates a file containing attributes. it opens the named file (filename) and interprets each line in that file as an attribute argument to atSetAttr. yes, every single line. batch mode, we love her ✨

atAttrName fills a static memory buffer with the name of the given attribute and returns a pointer to that buffer. heads up: subsequent calls of atAttrName overwrite previous results. so don't be clinging to old pointers, okay? 🙈

atAttrValue returns a pointer to the value part of attribute.

atMatchAttr checks if aso has the given attribute. result values are TRUE or FALSE. if just an attribute name is given, atMatchAttr returns a positive result when the attribute exists in the aso's attribute list, or — in the case that it's a standard attribute — if its value is non null. a full attribute (name and value) must match an attribute in the aso's attribute list. and plot twist: the value of the given attribute argument may be a (sh(1)) pattern 👑

💖 ATTRIBUTE FORMAT 💖

attributes have the general format name=value. additionally, a plus or minus sign may precede, and a value special character may follow, the equal sign:

<name>[+-]=[^@!*]<value>
  • plus (+) — a plus sign preceding the equal sign indicates that the value shall be added to existing values (no matter if there are any).
  • minus (-) — with the minus sign, the value shall be removed from the list of values, if it exists.

and now, the moment you've been waiting for 💅 the complete list of value special characters recognized by AtFStk:

  • circumflex (^) — the value is regarded as a reference to a file or ASO carrying the real attribute value as contents.
  • at (@) — an attribute value starting with an at (@) is considered to be a file name from where the real attribute value is to be taken. in contrary to the circumflex notation above, this causes the file to be read only once, when setting the attribute value.
  • exclam (!) — this introduces execution attributes. the attribute value is regarded as a command to be passed to a shell process. on access, the command will be executed and its output will be catched as the real attribute value. yes really, it runs stuff. 😳
  • asterisk (*) — this denotes a pointer attribute, modeling relationships between attributed software objects. when atSetAttr finds an attribute value with an asterisk as first character, it interprets the remaining value string as a version identifier and tries to bind it using atBindVersion (manual page atbind(3)). on success, the network path (see atNetworkPath(3)) of the identified ASO will be stored as attribute value together with the leading asterisk. atRetAttr maps pointer attributes to local pathnames using atLocalPath (manual page atnetwork(3)).

👑 STANDARD ATTRIBUTES 👑

there are a number of standard attributes defined by the AtFS toolkit library and by AtFS (Attribute Filesystem) for each ASO. for a list of the AtFS standard attributes, see the af_attrs(3) manual page. and this is the list of all standard attribute names defined in AtFStk:

  • Header — a compound attribute consisting of a $Header: Label followed by the bound file name (AF_ATTBOUND), the version date (vtime — see below), the version's author and state, and a trailing dollar sign ($). example:
$Header: attrs.c[1.1] Tue Dec  1 17:01:10 1992 andy@cs.tu-berlin.de proposed $
  • Log — the version's modification history from the very beginning. this might be long. like, long long. 😭
  • note — the modification note of the version as set by the author.
  • pred, succ — the physical predecessor/successor version as stored in AtFS. if there is none, the string n/a (not available) is returned.
  • vtime — the version date. for busy versions, this is the date of last modification; for saved versions, it is the saving date.
  • xpon, xpoff — pseudo attribute turning attribute expansion on and off (see above).

some other names are mapped to the appropriate AtFS standard name:

  • atime → AF_ATTATIME
  • author → AF_ATTAUTHOR
  • ctime → AF_ATTCTIME
  • dsize → AF_ATTDSIZE
  • generation → AF_ATTGEN
  • host → AF_ATTHOST
  • lock → AF_ATTLOCKER
  • ltime → AF_ATTLTIME
  • mtime → AF_ATTMTIME
  • name → AF_ATTNAME
  • owner → AF_ATTOWNER
  • revision → AF_ATTREV
  • self → AF_ATTBOUND
  • selfpath → AF_ATTBOUNDPATH
  • size → AF_ATTSIZE
  • state → AF_ATTSTATE
  • stime → AF_ATTSTIME
  • syspath → AF_ATTSPATH
  • type → AF_ATTTYPE
  • unixname → AF_ATTUNIXNAME
  • version → AF_ATTVERSION

(the AtFS names above are constant definitions, iykyk 💜)

atSetAttr may also be used to set standard attributes where possible. the attributes that may be altered are:

⭐ RETURN VALUES ⭐

on error, the atError variable is set to a non null value, and atErrMsg holds a diagnostic message.

atRetAttr returns a null pointer on error, or if the desired attribute does not exist. atSetAttr and atSetAttrFile return FALSE on any error condition. atMatchAttr returns FALSE if an error occurred or if the attribute does not match.

🌈 SEE ALSO 🌈

af_attrs(3), atbind(3), atnetwork(3)

and that's the whole page, bestie, you ate it 💅 this was AtFStk-1.12, dated Tue Jun 29 16:16:22 1993 — yeah she's an elder icon and we respect her 👑💖

📦 where this page comes from