Man Linux: Main Page and Category List

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.