hpux man page for xtfindfile

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()