NAME
XtFindFile - search for a file using substitutions in the path list
SYNTAX
String XtFindFile(String _p_a_t_h, Substitution _s_u_b_s_t_i_t_u_t_i_o_n_s,
Cardinal _n_u_m___s_u_b_s_t_i_t_u_t_i_o_n_s, XtFilePredicate _p_r_e_d_i_c_a_t_e);
ARGUMENTS
-
_p_a_t_h
Specifies a path of file names, including substitution characters.
-
-
_s_u_b_s_t_i_t_u_t_i_o_n_s
Specifies a list of substitutions to make into a path.
-
-
_n_u_m___s_u_b_s_t_i_t_u_t_i_o_n_s
Specifies the number of substitutions passed in.
-
-
_p_r_e_d_i_c_a_t_e
Specifies a procedure to call to judge a potential file name, or NULL.
-
DESCRIPTION
The _p_a_t_h 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,
_X_t_F_i_n_d_F_i_l_e
looks through the
specified _s_u_b_s_t_i_t_u_t_i_o_n_s for that character in the _m_a_t_c_h field and if
found replaces the percent and match characters with the string in the
corresponding _s_u_b_s_t_i_t_u_t_i_o_n field. A _s_u_b_s_t_i_t_u_t_i_o_n field 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,
_X_t_F_i_n_d_F_i_l_e
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
_X_t_F_i_n_d_F_i_l_e
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
_T_r_u_e;
this string is the return value for
_X_t_F_i_n_d_F_i_l_e.
If no string yields a
_T_r_u_e
return from the predicate,
_X_t_F_i_n_d_F_i_l_e
returns NULL.
If the _p_r_e_d_i_c_a_t_e 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
_X_t_F_r_e_e
when it is no longer needed.
SEE ALSO
_X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e