atExpand(3) attribute expansion

Other Alias

atExpandAttrs

SYNOPSIS

#include <atfs.h>
#include <atfstk.h>

int atExpandAttrs (Af_key *aso, char *buf, size_t bufSize, FILE *dest, size_t destSize, int mode);

int atExpand;

DESCRIPTION

atExpandAttrs scans the char buffer buf to the extent of bufSize for strings of the form $__attributeName 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 dest. If an attribute with name attributeName is set for the current attributed software object aso, 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.

Despite the type of the dest 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 mode argument and bufSize must be set to indicate the length of the destination buffer dest (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.

The atExpand 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 $__xpoff in any buffer scanned by atExpandAttrs. Another pseudo attribute citation $__xpon 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.

DIAGNOSTICS

atExpandAttrs returns -1 on error. Additionally, the atError variable is set and afErrMsg holds a diagnostic message.