xtfindfile(3xt) [osf1 man page]
XtFindFile(3Xt) XtFindFile(3Xt) NAME
XtFindFile - search for a file using substitutions in the path list SYNOPSIS
String XtFindFile(path, substitutions, num_substitutions, predicate) String path; Substitution substitutions; Cardinal num_substitutions; XtFilePredicate predicate; ARGUMENTS
Specifies a path of file names, including substitution characters. Specifies a list of substitutions to make into a path. Specifies the number of substitutions passed in. Specifies a procedure to call to judge a potential file name, or NULL. DESCRIPTION
The path 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, XtFindFile looks through the specified substitutions for that character in the match field and if found replaces the percent and match characters with the string in the corresponding substitution field. A substitution 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 (that is, "/" in POSIX) the same way as a single separator, 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. Each resulting string is passed to the predicate procedure until a string is found for which the procedure returns True; this string is the return value for XtFindFile. If no string yields a True return from the predicate, XtFindFile returns NULL. If the predicate 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 XtFree when it is no longer needed. SEE ALSO
X Toolkit Intrinsics -- C Language Interface Xlib -- C Language X Interface XtFindFile(3Xt)
Check Out this Related Man Page
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()