XtFindFile(3Xt)

NAME
       XtFindFile - search for a file using substitutions in the
       path list

SYNTAX
       String XtFindFile(path, substitutions, num_substitu-
       tions,predicate)
             String path;
             Substitution substitutions;
             Cardinal num_substitutions;
             XtFilePredicate predicate;

ARGUMENTS
       path      Specifies a path of file names, including sub-
                 stitution characters.

       substitutions
                 Specifies a list of substitutions to make into a
                 path.

       num_substitutions
                 Specifies the number of substitutions passed in.

       predicate Specifies a procedure to call to judge a poten-
                 tial file name, or NULL.

DESCRIPTION
       The path parameter 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 selected by the following character.  The
       character sequence ``%:'' specifies an embedded colon that
       is not a delimiter; the sequence is replaced by a single
       colon.  The character sequence ``%%'' 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,
       looks through the specified substitutions for that charac-
       ter in the match field and if found replaces the percent
       and match characters with the string in the corresponding
       substitution field.  A substitution field entry of NULL is
       equivalent to a pointer to an empty string.  If the oper-
       ating system does not interpret multiple embedded name
       separators in the path (i.e., ``/'' in POSIX) the same way
       as a single separator, will collapse multiple separators
       into a single one after performing all string substitu-
       tions.  Except for collapsing embedded separators, the
       contents of the string substitutions are not interpreted
       by and may therefore contain any operating-system-depen-
       dent characters, including additional name separators.
       Each resulting string is passed to the predicate procedure
       until a string is found for which the procedure returns
       this string is the return value for If no string yields a
       return from the predicate, returns NULL.

       If the predicate parameter is NULL, an internal procedure
       that checks if the file exists, is readable, and is not a
       directory will be used.

       It is the responsibility of the caller to free the
       returned string using when it is no longer needed.

SEE ALSO
       X Toolkit Intrinsics - C Language Interface
       Xlib - C Language X Interface