Ubuntu Manpage: atRetAttr, atSetAttr, atAttrName, atAttrValue, atAllAttrs, atFreeAttrs

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