Provided by: atfs-dev_1.4pl6-15_amd64 bug

NAME

       atRetAttr,   atSetAttr,  atAttrName,  atAttrValue,  atAllAttrs,  atFreeAttrs  -  attribute
       handling

SYNOPSIS

       #include <atfs.h>
       #include <atfstk.h>

       char*atRetAttr (Af_key *aso, char *attributeName);

       void atFreeAttr (char *attributeValue);

       int  atSetAttr (Af_key *aso, char *attribute, int mode);

       int  atSetAttrFile (Af_key *aso, char *filename);

       char*atAttrName (char *attribute);

       char*atAttrValue (char *attribute);

       int  atMatchAttr (Af_key *aso, char *attribute);

DESCRIPTION

       The AtFS Toolkit Library extends the AtFS attribute  handling.  It  introduces  additional
       standard attribute names and a list of attribute value types.

       atRetAttr  returns  a  string  representation  of  the value(s) of the aso attribute named
       attributeName. If the attribute value is preceded by a value special character  (see  list
       below),  it  will  be  evaluated  accordingly.  When  the  evaluation  fails, the original
       attribute value, including value special character, is returned.  When the attribute value
       is  empty,  an empty string is returned. When the attribute does not exist or on any other
       error condition, a null pointer is returned.

       Attribute citations (like 7.0) in attribute values will always be expanded  by  atRetAttr.
       There  is no way to disable attribute expansion. If you need the raw, unexpanded attribute
       value, use af_retattr (manual page af_attrs(3)).

       The attribute value returned by atRetAttr either resides in static memory (in case of AtFS
       standard  attributes)  or  in  allocated  memory.   Use atFreeAttr on each attribute value
       returned by atRetAttr when this not needed any longer. This will recycle allocated  memory
       if possible.

       atSetAttr  sets  the  attribute  attribute  for  aso.  It  calls  af_setattr  (manual page
       af_attrs(3))  and  hence  understands  the  modes  AF_ADD,  AF_REMOVE,   and   AF_REPLACE.
       Alternatively,  the  mode  argument is ignored, when the equal sign between attribute name
       and value is preceded by either a plus (+) or a minus (-) sign  for  adding  and  deleting
       attribute  values.  The  value  special character at (@) will also be evaluated. atSetAttr
       opens the file and reads its contents.  If  either  the  opening  or  reading  fails,  the
       attribute setting is aborted and returns FALSE. On successful execution, atSetAttr returns
       TRUE, otherwise FALSE.

       atSetAttrFile evaluates a file containing attributes. If opens the named  file  (filename)
       and interprets each line in the file as attribute argument to atSetAttr.

       atAttrName fills a static memory buffer with the name of the given attribute and returns a
       pointer to this buffer. Subsequent calls of atAttrName overwrite previous results.

       atAttrValue returns a pointer to the value part of attribute.

       atMatchAttr checks if aso has the given attribute. Result values are  TRUE  or  FALSE.  If
       just  an  attribute  name is given, atMatchAttr returns a positive result if the attribute
       exists in the asos attribute list or, in the case that it is a standard attribute, if it's
       value  is  non null. A full attribute (name and value) must match an attribute in the asos
       attribute list. The value of the given attribute argument may be a (sh(1)) pattern.

ATTRIBUTE FORMAT

       Attributes have the general format name=value. Additionally, a  plus  or  minus  sign  may
       precede    and    a    value    special    character    may    follow   the   equal   sign
       (<name>[+-]=[^@!*]<value>).

       plus (+)
                A plus sign preceding the equal sign indicates, that the value shall be added  to
                existing values (no matter if there are any).

       minus (-)
                With  the  minus  sign, the value shall be removed from the list of values, if it
                exists.

       The following is the complete list of value special characters recognized by AtFStk.

       circumflex (^)
                The value is regarded as a reference to a file or ASO carrying the real attribute
                value as contents.

       at (@)   An  attribute  value starting with an at (@) is considered to be a file name from
                where the real attribute value is to be taken.  In  contrary  to  the  circumflex
                notation  above,  this causes the file read only once, when setting the attribute
                value.

       exclam (!)
                This introduces execution attributes. The attribute value is regarded as  command
                to  be passed to a shell process. On access, the command will be executed and its
                output will be catched as real attribute value.

       asterisk (*)
                This denotes  a  pointer  attribute  modeling  relationships  between  attributed
                software  objects.  When  atSetAttr  finds an attribute value with an asterisk as
                first character it interprets the remaining value string  as  version  identifier
                and tries to bind it using atBindVersion (manual page atbind(3)). On success, the
                network path (see atNetworkPath(3)) of the  identifies  ASO  will  be  stored  as
                attribute  value  together  with  the  leading  asterisk.  atRetAttr maps pointer
                attributes to local pathnames using atLocalPath (manual page atnetwork(3)).

STANDARD ATTRIBUTES

       There are a number of standard attributes defined by the AtFS toolkit library and by  AtFS
       (Attribute  Filesystem)  for  each ASO. For a list of the AtFS standard attributes see the
       af_attrs(3) manual page.  This is a list  of  all  standard  attribute  names  defined  in
       AtFStk.

       Header  A  compound  attribute  consisting  of a $Header: Label followed by the bound file
               name (AF_ATTBOUND), the version date (vtime - see below), the versions author  and
               state and a trailing dollar sign ($).  Example:
               $Header: attrs.c[1.1] Tue Dec  1 17:01:10 1992 andy@cs.tu-berlin.de proposed $

       Log     The versions modification history from the very beginning. This might be long.

       note    The modification note of the version as set by the author.

       pred, succ
               The  physical  predecessor/successor  version as stored in AtFS. If there is none,
               the string n/a (not available) is returned.

       vtime   The version date. For busy versions, this is the date of  last  modification,  for
               saved versions, it is the saving date.

       xpon, xpoff
               Pseudo attribute turning attribute expansion on and off (see above).

       Some other names are mapped to the appropriate AtFS standard name:
         AtFStk name                  AtFS name (constant definition)AtFStk nameAtFS name (constant definition)
         atime     AF_ATTATIME        revision  AF_ATTREV
         author    AF_ATTAUTHOR       self      AF_ATTBOUND
         ctime     AF_ATTCTIME        selfpath  AF_ATTBOUNDPATH
         dsize     AF_ATTDSIZE        size      AF_ATTSIZE
         generation                   AF_ATTGEN stateAF_ATTSTATE
         host      AF_ATTHOST         stime     AF_ATTSTIME
         lock      AF_ATTLOCKER       syspath   AF_ATTSPATH
         ltime     AF_ATTLTIME        type      AF_ATTTYPE
         mtime     AF_ATTMTIME        unixname  AF_ATTUNIXNAME
         name      AF_ATTNAME         version   AF_ATTVERSION
         owner     AF_ATTOWNER

       atSetAttr  may also be used to set standard attributes where possible. Attributes that may
       be altered are
         Attribute           Mapped to AtFS function
         author              af_chauthor (af_protect(3))
         generation, revision, versionaf_svnum (af_version(3))
         mode                af_chmod (af_protect(3))
         owner               af_chowner (af_protect(3))
         state               af_sstate (af_version(3))
         note                af_snote (af_note(3))

RETURN VALUES

       On error, the atError variable is set to a nun null value, and atErrMsg holds a diagnostic
       message.  atRetAttr  returns a null pointer on error, or if the desired attribute does not
       exist.  atSetAttr and atSetAttrFile return  FALSE  on  any  error  condition.  atMatchAttr
       returns FALSE if an error occurred or if the attribute does not match.

SEE ALSO

       af_attrs(3), atbind(3), atnetwork(3)