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.
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 name AtFS 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 state AF_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, version af_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)
