XtFindFile() XtFindFile()
Name
XtFindFile - 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 characters.
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.
Description
XtFindFile() performs the substitutions specified by substitutions on each colon-separated element of path in turn, and passes the result-
ing 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 fol-
lowed by a character that appears in substitutions, then that two-character sequence will be replaced by the corresponding string in sub-
stitutions. The "Background" section below provides more details about the substitution 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
directory), 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.
Usage
XtFindFile() is intended as a way to find a file that depends on variables 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 application that wanted to find a directory rather than a file, for exam-
ple, 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 procedure.
Background
There are two substitution sequences that are treated specially:
o The character sequence %: (percent colon) specifies an embedded colon that is not a delimiter; the sequence is replaced by a single
colon.
o 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 separators in the path (i.e., "/" in POSIX) the same way as a single sep-
arator, 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 Also
XtResolvePathname(1),
XtFilePredicate(2).
Xt - File Searching XtFindFile()