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;
Arguments
pathSpecifies 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.
predicateSpecifies a procedure called to judge each potential file name, or NULL.
Description
The Intrinsics provide two routines to look for a file by name using string substitutions in a list of file specifications. XtFindFile uses an arbitrary set of client-specified substitutions whereas XtResolvePathname uses a set of standard substitutions corresponding to the X/Open Portability Guide language localization conventions. Most applications should use XtResolvePathname, which calls XtFindFile.
XtFindFile searches for a file. The path argument specifies a string that consists of a series of potential file names delimited by colons. Within each name, the percent character specifies a string substitution controlled by the following character. For example:
•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.
•If a percent character is followed by any other character, XtFindFile looks through the specified substitutions for that character in the match field, and if that character is found XtFindFile replaces the percent and match characters with the string in the corresponding substitution field.
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 separator, 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. Each resulting string is passed to the predicate procedure until a string is found for which the procedure returns True; this string is the return value for XtFindFile. If no string returns a True from the predicate, XtFindFile returns NULL.
If predicate is NULL, an internal procedure is used. This procedure checks that the file exists, that it is readable, and that it is not a directory.
The caller must free the returned string using XtFree when the string is no longer needed.
Structures
A string substitution is defined by a list of Substitution entries.
typedef struct {
char match;
String substitution;
} SubstitutionRec, ∗Substitution;