XtFindFile()XtFindFile()NameXtFindFile - search for a file using substitutions in a path.
Synopsis
String XtFindFile(path, substitutions, num_substitutions, predicate)
String path;
Substitution substitutions;
Cardinal num_substitutions;
XtFilePredicate predicate;
Inputs
path Specifies a path of file names including substitution charac‐
ters.
substitutions
Specifies a list of substitutions to make into the path.
num_substitutions
Specifies the number of substitutions passed in.
predicate Specifies a procedure called to judge each potential file
name, or NULL.
Returns
A filename, or NULL if no file was found.
Availability
Release 4 and later.
DescriptionXtFindFile() performs the substitutions specified by substitutions on
each colon-separated element of path in turn, and passes the resulting
string to predicate. If predicate returns True, XtFindFile() returns
the string. If predicate never returns True, XtFindFile() returns
NULL.
Each element in substitutions is a structure that contains a character
and a string. If any element in path contains a percent sign followed
by a character that appears in substitutions, then that two-character
sequence will be replaced by the corresponding string in substitutions.
The "Background" section below provides more details about the substi‐
tution process.
If predicate is NULL, then an internal predicate is used that returns
True if the string is the name of a readable file (and is not a direc‐
tory), and returns False otherwise. See XtFilePredicate(2) for more
details on how to write a file predicate procedure.
The caller must free the returned string with XtFree() when it is no
longer needed.
UsageXtFindFile() is intended as a way to find a file that depends on vari‐
ables such as the current setting of the locale, or the number of bit‐
planes available on a screen. Most applications can use the higher-
level function XtResolvePathname() which provides a number of standard
substitutions and a default path.
The default predicate procedure is sufficient for most uses. An appli‐
cation that wanted to find a directory rather than a file, for example,
would have to specify a custom predicate, as would an application that
wanted to verify that a file was readable and that the contents of the
file were reasonable would also have to provide a custom predicate pro‐
cedure.
Background
There are two substitution sequences that are treated specially:
· The character sequence %: (percent colon) specifies an embedded
colon that is not a delimiter; the sequence is replaced by a single
colon.
· The character sequence %% (percent percent) specifies a percent
character that does not introduce a substitution; the sequence is
replaced by a single percent character.
A substitution string entry of NULL is equivalent to a pointer to an
empty string.
If the operating system does not interpret multiple embedded name sepa‐
rators in the path (i.e., "/" in POSIX) the same way as a single sepa‐
rator, XtFindFile() will collapse multiple separators into a single one
after performing all string substitutions. Except for collapsing
embedded separators, the contents of the string substitutions are not
interpreted by XtFindFile() and may therefore contain any operating-
system-dependent characters, including additional name separators.
Structures
The Substitution type is defined as follows:
typedef struct {
char match;
String substitution;
} SubstitutionRec, *Substitution;
See AlsoXtResolvePathname(1),
XtFilePredicate(2).
Xt - File Searching XtFindFile()
