NAME
af_retattr, af_retnumattr, af_retuserattr, af_rettimeattr, af_setattr,
af_allattrs, af_isstdval, af_freeattr, af_freeattrbuf - AtFS attribute
handling
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);
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) 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)) memory, you should
not use free(3) 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)).
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) 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)
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.