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.