Man Linux: Main Page and Category List

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)