.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: atexpand.3[7.0] Fri Jun 25 16:39:36 1993 andy@cs.tu-berlin.de frozen $
..
.TH atexpand 3 "Fri Jun 25 16:39:36 1993" "AtFStk-1.12" "AtFS Toolkit Library"
.SH NAME
atExpandAttrs, atExpand \- attribute expansion
.SH SYNOPSIS
#include <atfs.h>
.br
#include <atfstk.h>
.sp
int atExpandAttrs (Af_key *aso, char *buf, size_t bufSize, FILE *dest,
size_t destSize, int mode);
.sp
int atExpand;
.SH DESCRIPTION
\fIatExpandAttrs\fP scans the char buffer \fIbuf\fP to the extent of
\fIbufSize\fP for strings of the form \fI$__attributeName\fP
optionally followed by a delimiting (second) dollar sign ($). If such
a string is found, the buffer contents up to the character preceding
the first dollar sign will be sent to the destination output
\fIdest\fP. If an attribute with name attributeName is set for the
current attributed software object \fIaso\fP, the citation-string will be
substituted by the value of that attribute and appended to the output.
Output of buf contents resumes with the first character after
the whitespace character or dollar sign delimiting attributeName.
.LP
Despite the type of the \fIdest\fP argument (pointer to file
structure), atExpandAttrs may be caused to copy it's output to a
string buffer rather than an open file. In this case, the constant
AT_EXPAND_STRING must be given as \fImode\fP argument and
\fIbufSize\fP must be set to indicate the length of the destination
buffer \fIdest\fP (will be casted to character pointer). If destSize
is to small to hold the result string, atExpandAttrs returns a
negative value. In the regular case, where output shall be written to
a file, the mode parameter must be AT_EXPAND_FILE.
.LP
The \fIatExpand\fP variable suppresses attribute expansion when set
FALSE. The variable may be set either directly from the
application program if indirectly by evaluation of the pseudo
attribute citation \fI$__xpoff\fP in any buffer scanned by
atExpandAttrs. Another pseudo attribute citation \fI$__xpon\fP
cancels the effect of a previous $__xpoff and switches attribute
citation on again. It does not, however, enable attribute citation if
this was disabled explicitly by the application program.
.SH DIAGNOSTICS
atExpandAttrs returns -1 on error. Additionally, the \fIatError\fP
variable is set and \fIafErrMsg\fP holds a diagnostic message.
.SH SEE ALSO
atattribute(3)