.ig Copyright (C) 1993,1994 by the author(s). This software is published in the hope that it will be useful, but WITHOUT ANY WARRANTY for any part of this software to work correctly or as described in the manuals. See the ShapeTools Public License for details. Permission is granted to use, copy, modify, or distribute any part of this software but only under the conditions described in the ShapeTools Public License. A copy of this license is supposed to have been given to you along with ShapeTools in a file named LICENSE. Among other things, this copyright notice and the Public License must be preserved on all copies. Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de) $Header: atattribute.3[7.0] Tue Jun 29 16:16:22 1993 andy@cs.tu-berlin.de frozen $ .. .TH atattribute 3 "Tue Jun 29 16:16:22 1993" "AtFStk-1.12" "AtFS Toolkit Library" .SH NAME atRetAttr, atSetAttr, atAttrName, atAttrValue, atAllAttrs, atFreeAttrs \- attribute handling .SH SYNOPSIS #include .br #include .ta 1.2c .sp char* atRetAttr (Af_key *aso, char *attributeName); .sp void atFreeAttr (char *attributeValue); .sp int atSetAttr (Af_key *aso, char *attribute, int mode); .sp int atSetAttrFile (Af_key *aso, char *filename); .sp char* atAttrName (char *attribute); .sp char* atAttrValue (char *attribute); .sp int atMatchAttr (Af_key *aso, char *attribute); .sp .SH DESCRIPTION The AtFS Toolkit Library extends the AtFS attribute handling. It introduces additional standard attribute names and a list of attribute value types. .LP \fIatRetAttr\fP returns a string representation of the value(s) of the \fIaso\fP attribute named \fIattributeName\fP. 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. .LP Attribute citations (like \fC7.0\fP) 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)). .LP The attribute value returned by atRetAttr either resides in static memory (in case of AtFS standard attributes) or in allocated memory. Use \fIatFreeAttr\fP on each attribute value returned by atRetAttr when this not needed any longer. This will recycle allocated memory if possible. .LP \fIatSetAttr\fP sets the attribute \fIattribute\fP for \fIaso\fP. It calls af_setattr (manual page af_attrs(3)) and hence understands the \fImode\fPs 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 \fIat\fP (@) 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. .LP \fIatSetAttrFile\fP evaluates a file containing attributes. If opens the named file (\fIfilename\fP) and interprets each line in the file as attribute argument to atSetAttr. .LP \fIatAttrName\fP fills a static memory buffer with the name of the given \fIattribute\fP and returns a pointer to this buffer. Subsequent calls of atAttrName overwrite previous results. .LP \fIatAttrValue\fP returns a pointer to the value part of \fIattribute\fP. .LP \fIatMatchAttr\fP checks if \fIaso\fP has the given \fIattribute\fP. 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. .SH ATTRIBUTE FORMAT Attributes have the general format \fCname=value\fP. Additionally, a plus or minus sign may precede and a value special character may follow the equal sign (\fC[+-]=[^@!*]\fP). .TP 2.2c plus (+) A plus sign preceding the equal sign indicates, that the value shall be added to existing values (no matter if there are any). .TP minus (-) With the minus sign, the value shall be removed from the list of values, if it exists. .LP The following is the complete list of value special characters recognized by AtFStk. .TP 2.2c circumflex (^) The value is regarded as a \fIreference\fP to a file or ASO carrying the real attribute value as contents. .TP 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. .TP exclam (!) This introduces \fIexecution\fP 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. .TP 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)). .SH STANDARD ATTRIBUTES There are a number of \fIstandard attributes\fP 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. .TP 2c Header A compound attribute consisting of a \fI$Header:\fP 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: .br \f(CB\s-2$Header: attrs.c[1.1] Tue Dec 1 17:01:10 1992 andy@cs.tu-berlin.de proposed $\s+2\fP .TP Log The versions modification history from the very beginning. This might be long. .TP note The modification note of the version as set by the author. .TP pred, succ The physical predecessor/successor version as stored in AtFS. If there is none, the string \fIn/a\fP (not available) is returned. .TP vtime The version date. For busy versions, this is the date of last modification, for saved versions, it is the saving date. .TP xpon, xpoff Pseudo attribute turning attribute expansion on and off (see above). .LP Some other names are mapped to the appropriate AtFS standard name: .nf .ta 0.5c 3c 8c 10.5c .sp 0.2c \fIAtFStk name AtFS name (constant definition) AtFStk name AtFS name (constant definition)\fP .sp 0.2c 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 .fi .LP atSetAttr may also be used to set standard attributes where possible. Attributes that may be altered are .nf .ta 0.5c 5.5c .sp 0.2c \fIAttribute\fP \fIMapped to AtFS function\fP .sp 0.2c 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)) .fi .SH RETURN VALUES On error, the \fIatError\fP variable is set to a nun null value, and \fIatErrMsg\fP holds a diagnostic message. \fIatRetAttr\fP returns a null pointer on error, or if the desired attribute does not exist. \fIatSetAttr\fP and \fIatSetAttrFile\fP return FALSE on any error condition. \fIatMatchAttr\fP returns FALSE if an error occurred or if the attribute does not match. .SH SEE ALSO af_attrs(3), atbind(3), atnetwork(3)