XtResolvePathname() XtResolvePathname()
Name
XtResolvePathname - 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; substituted for %N.
suffix Specifies the suffix of the file to find, or NULL; substituted 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.
Description
XtResolvePathname() 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-sep-
arated element of path in turn, and passes the resulting string to predicate. 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
directory), 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-charac-
ter sequence is replaced with one of the standard substitutions described below. If a percent sign is followed by a substitution character
specified 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 specified, the empty string is used for the substitution. This substitution 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
variable. 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. XtResolvePathname() 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-stan-
dard substitutions.
The Default Path
If the path argument is NULL, the value of the XFILESEARCHPATH environment 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 imple-
mentation 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 substitutions.
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, 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 Also
XtAppInitialize(1), XtDisplayInitialize(1), XtFindFile(1), XtSetLanguageProc(1),
XtFilePredicate(2).
Xt - File Searching XtResolvePathname()