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.