XtResolvePathname()XtResolvePathname()NameXtResolvePathname - search for a file using standard substitutions in a
path list.
Synopsis
String XtResolvePathname(display, type, filename, suffix, path,
substitutions, num_substitutions, predicate)
Display *display;
String type, filename, suffix, path;
Substitution substitutions;
Cardinal num_substitutions;
XtFilePredicate predicate;
Inputs
display Specifies the display.
type Specifies the type of the file to find, or NULL; substituted
for %T.
filename Specifies the base name of the file to find, or NULL; substi‐
tuted for %N.
suffix Specifies the suffix of the file to find, or NULL; substi‐
tuted for %S.
path Specifies the list of file specifications to test, or NULL.
substitutions
Specifies a list of additional substitutions to make into the
path, or NULL.
num_substitutions
Specifies the number of entries in substitutions.
predicate Specifies a procedure called to test each potential file
name, or NULL.
Returns
A filename, or NULL if no appropriate file was found.
Availability
Release 4 and later.
DescriptionXtResolvePathname() is used to find a file (often a resource file)
which has a name, and is installed in a directory, that depends on the
language in use by the application, the type of the file, the class
name of the application, and, in Release 5, the value of the customiza‐
tion resource.
XtResolvePathname() performs a number of standard substitutions, and
any extra substitutions specified in substitutions, on each colon-sepa‐
rated element of path in turn, and passes the resulting string to pred‐
icate. If predicate returns True, XtResolvePathname() returns the
string. If predicate does not return True for any of the elements in
path, XtResolvePathname() returns NULL.
It is the responsibility of the caller to free the returned string
using XtFree() when it is no longer needed.
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 direc‐
tory), and returns False otherwise. See XtFilePredicate(2) for more
details on how to write a customized file predicate procedure.
If any element in path contains a percent sign followed by one of the
standard characters N, T, S, C, L, l, t, or c, then that two-character
sequence is replaced with one of the standard substitutions described
below. If a percent sign is followed by a substitution character spec‐
ified in substitutions, then that non-standard substitution will be
performed. See the "Background" section below for more information on
non-standard substitutions. The standard substitutions are as follows:
%T The value of the type argument. This is the general category of
file, such as "app-defaults," "bitmap," or "help." If type is NULL,
the empty string is used.
%N The value of the filename argument, or the application's class name
if filename is NULL. (The application's class name is passed to
XtAppInitialize() or XtDisplayInitialize() and is associated with
the display).
%S The value of the suffix argument. For app-defaults file, this
should be NULL. For bitmap files, however, it might be ".bm". If
suffix is NULL, the empty string is used.
%C The value of the customization resource in the database associated
with display. The user may set this resource to a value such as
"-color" to indicate that files (resource files, bitmaps, etc.)
appropriate for a color screen should be found, or to "-mono" if
they are using a monochrome screen. If this resource is not speci‐
fied, the empty string is used for the substitution. This substitu‐
tion is performed only in Release 5 and later releases.
%L The value of the language string associated with the display. This
is the value of the xnlLanguage resource in Release 4, and in
Release 5 and later, it is the value of this resource or the value
returned by the language procedure, if any is registered. (See
XtSetLanguageProc() and XtDisplayInitialize() for more information.)
In Release 5, if the xnlLanguage resource is not set, the language
procedure will usually return the value of the LANG environment
variable.
%l The "language part" of the language string of the display.
%t The "territory part" of the language string of the display.
%c The "codeset part" of the language string of the display.
These substitutions are performed on the elements of path, or if path
is NULL, on the path specified in the XFILESEARCHPATH environment vari‐
able. If this variable is not defined, a default path is used.
See the "Background" section below for an explanation of the default
path, the various parts of the language string, and of non-standard
substitutions.
Usage
The Intrinsics use XtResolvePathname() to find an application's app-
defaults file (see XtAppInitialize()). If your application reads other
files which contain bitmaps, help text, or other information that may
need to be customized depending on the user's customization resource or
preferred language, you should use XtResolvePathname() to find the
file. This greatly aids the portability and customizability of your
application.
A disadvantage of this approach is that it requires your files to be
installed in locations removed from the application itself. Still,
files have to be installed somewhere, and XtResolvePathname() provides
some standardization for this installation process.
Note that you can pass NULL for many of the arguments to this function.
The return value of the function is a filename, not an opened file.
If you are not interested in any of the standard substitutions, or the
default path, you can use XtFindFile() to search for a file. This is a
lower-level function than most applications will want to use. XtRe‐
solvePathname() calls XtFindFile() itself.
Example
To find the app-defaults file for an application, you can simply use
XtResolvePathname as
follows:
filename = XtResolvePathname(dpy, "app-defaults", NULL, NULL, NULL,
NULL, 0, NULL);
If your application needs to read a help file which you plan to install
in /usr/lib/X11/help (/usr/lib/X11/ will be part of the default path on
most implementations) with the same name as the application class, and
with the suffix, ".txt", you could use XtResolvePathname() as follows:
filename = XtResolvePathname(dpy, "help", NULL, ".txt", NULL,
NULL, 0, NULL);
If your application needs to read a number of bitmap files, you should
probably not install them directly in /usr/lib/X11/bitmaps because
their names may conflict with bitmaps used by other applications. You
could find them from a subdirectory of this directory as follows:
sprintf(basename, "%s/%s", application_class, bitmap_name);
bitmap_file = XtResolvePathname(dpy, "bitmaps", basename, ".bm",
NULL, NULL, 0, NULL);
Background
This section explains the default path used by XtResolvePathname(), the
various parts of the language string, and how to specify non-standard
substitutions.
The Default Path
If the path argument is NULL, the value of the XFILESEARCHPATH environ‐
ment variable will be used. If XFILESEARCHPATH is not defined, an
implementation-specific default path will be used which contains at
least 6 entries. These entries must contain the following substitu‐
tions:
1. %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c
2. %C, %N, %S, %T, %l
3. %C, %N, %S, %T
4. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c
5. %N, %S, %T, %l
6. %N, %S, %T
The order of these six entries within the path must be as given above.
The order and use of substitutions within a given entry is implementa‐
tion dependent. If the path begins with a colon, it will be preceded
by %N%S. If the path includes two adjacent colons, %N%S will be
inserted between them.
A suggested value for the default path on POSIX-based systems is:
/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
Using this example, if the user has specified a language, it will be
used as a subdirectory of /usr/lib/X11 that will be searched for other
files. If the desired file is not found there, the lookup will be
tried again using just the language part of the specification. If the
file is not there, it will be looked for in /usr/lib/X11. The type
parameter is used as a subdirectory of the language directory or of
/usr/lib/X11, and suffix is appended to the file name.
The Language String
In Release 4, the language string was of the following form:
language[_territory][.codeset]
In Release 5, the format of the language string is specified to be
implementation defined, and it may have a "language part" a "territory"
part and a "codeset part". In practice, the Release 4 format is still
a common one, with a language string like "en_GB.iso8859-1" meaning
English, as spoken in Great Britain, encoded in the ISO8859-1 encoding
(Latin-1).
Non-standard Substitutions
You can have XtResolvePathname() introduce additional substitutions
into the specified path by passing an array of SubstitutionRec struc‐
tures. Each element in substitutions is a structure that contains a
character and a string. If any element in path contains a percent sign
followed by a character that appears in substitutions, then that two
character sequence will be replaced by the corresponding string in sub‐
stitutions.
There are two substitution sequences that are treated specially:
· 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.
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 sepa‐
rators in the path (i.e., "/" in POSIX) the same way as a single sepa‐
rator, XtResolvePathname() will collapse multiple separators into a
single one after performing all string substitutions. Except for col‐
lapsing embedded separators, the contents of the string substitutions
are not interpreted by XtResolvePathname() 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 AlsoXtAppInitialize(1), XtDisplayInitialize(1), XtFindFile(1), XtSet‐
LanguageProc(1),
XtFilePredicate(2).
Xt - File Searching XtResolvePathname()
