--- name: "af_attrs" section: "3" platform: "linux" package: "atfs-dev" version: "1.4pl6-15+b1" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/af_attrs" --- # af\_attrs(3) AtFS attribute handling ## NAME af\_retattr, af\_retnumattr, af\_retuserattr, af\_rettimeattr, af\_setattr, af\_allattrs, af\_isstdval, af\_freeattr, af\_freeattrbuf - AtFS attribute handling ## SYNOPSIS \#include \ char \*af\_retattr (Af\_key \*aso, char \*attrName) int af\_retnumattr (Af\_key \*aso, char \*attrName) Af\_user af\_retuserattr (Af\_key \*aso, char \*attrName) time\_t af\_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); ## DESCRIPTION *af\_retattr* returns the value of any ASO attribute in string representation. The *attrName* argument denotes either a standard attribute (according to the list below) or a user defined attribute. Standard attributes are converted to a meaningful string representation if necessary. If the attribute name given to af\_retattr contains an equal sign (this may be the case with user defined attributes), only the part before the equal sign will be interpreted as name. If the named attribute is a user defined attribute carrying multiple values, these will be returned in *one* string, with the values separated by newline ('\\n') characters. If the named attribute does not exist, af\_retattr returns a null pointer. If the value is empty, an empty string is returned. **Note:** The result string of af\_retattr may reside in static memory which is overwritten on subsequent calls of af\_retattr. *af\_retnumattr*, *af\_retuserattr*, and *af\_rettimeattr* return the value of the named attribute as integer, user structure or time value. These functions only apply to standard attributes with a matching type. *Af\_setattr* sets, modifies, or deletes user defined attributes of the ASO identified by *aso*. The *attr* parameter is a string of the form: *name=value*. The name may consist of any characters (even non-printable) but it may not contain Ctrl-A (\\001) characters. The first equal sign that appears in the string is interpreted as the delimiter between name and value. If the string does not contain an equal sign, it is interpreted as just an attribute name without value. The *mode* parameter is one of the following: - AF\_ADD Attach the given attribute to the identified ASO. If an attribute with the given name already exists, add just the value to the existing attribute. Subsequent calls of af\_setattr with the same attribute name construct attributes with multiple (any number) values. - AF\_REMOVE Remove the named attribute. This mode requires only the attribute name to be given as attr parameter. Removal of single values is not supported. - AF\_REPLACE Replace an existing user defined attribute. The replacement fails, if no attribute with the given name exists. *af\_allattrs* returns the complete attribute buffer (*attrBuf*) of the ASO identified by *aso* including standard and user defined attributes. The [af\_retrieve(3)](/af_retrieve/3.md) manual page shows the structure of the attribute buffer. *af\_freeattr* and *af\_freeattrbuf* release memory eventually allocated during a af\_retattr or af\_allattrs call. As the result of af\_retattr may reside either in static or dynamic ([malloc(3)](/malloc/3.md)) memory, you should not use [free(3)](/free/3.md) for releasing attribute value memory. *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. ## AtFS STANDARD ATTRIBUTES The following is an alphabetically ordered list of all known standard attributes. AF\_ATT... are string constants that may be used as *attrName* argument for any of the function calls described on this manual page. In parenthesis behind each symbolic constant, the type of the attribute is shown. - AF\_ATTAUTHOR (user) The versions author. - 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 attributes value is changed. - 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 (this attribute is quite useless, as this is always the current host). - 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)](/stat/2.md)). - 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. - AF\_ATTOWNER (user) The versions 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 trough 5 from *busy* to *frozen*. - 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 versions full name). See [af\_misc(3)](/af_misc/3.md) 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)](/stat/2.md), [free(3)](/free/3.md), [af\_misc(3)](/af_misc/3.md), [af\_retrieve(3)](/af_retrieve/3.md) ## 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. ## 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.