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