|w||Any widget in the application; specifies which resource database and application resources to use.|
|type||The string that describes type of the file; substituted for %T in path. If you specify NULL, the empty string will be used.|
|objname||The base name of the file; substituted for %N in path. If you specify NULL, the application class name will be used.|
|suffix||The suffix of the file; substituted for %S in path. If you specify NULL, the empty string will be used.|
|rootdir||The name of a directory to search under; substituted for %R in path. If you specify NULL, the configDir application resource will be used.|
|path||A colon-separated list of file specifications to check, or NULL.|
|where||Flags that specify whether XmtFindFile() should also search in standard user, application, and system paths.|
The fully qualified name of a file that exists and is read able, or NULL if no such file could be found. You must free this filename with XtFree() when done with it.
XmtFindFile() finds a fully qualified filename for an application auxiliary file with a specified base name, type, and suffix. Using XmtFindFile() to look up filenames is generally better than hardcoding those file names in an applica tion because it allows the system administrator flexibility in where she installs the auxiliary files for your application, and it allows flexibility at run time to read different files at run-time depending on the setting of the LANG environment variable, or the standard X11R5 customization application resource, for example.
XmtFindFile() is based on the Intrinsics function XtResolve Pathname() but extends it in a couple of important ways. It works by performing a standard set of string substitutions (described below) on each of the colon-separated elements of path in turn. Once the substitution is done, it checks to see if the resulting string names a file that exists and is readable. If so, it returns that filename.
Note that XmtFindFile() returns filenames in allocated memory that must be freed with XtFree() when you are done with it. Also note that if objname begins with /, ./, or ../, then XmtFindFile() assumes that it is already a fully qualified (absolute or relative) filename, and simply returns a copy of that name without conducting a search.
The substitutions performed by XmtFindFile(), and the paths that it can search are described in the sections below.
XmtFindFile() performs the following substitutions on any path it searches. %R, %H, %a, %A, %v, %z, and %d are added by XmtFindFile(); the other substitutions are standard ones supported by XtResolvePathname().
%R The root directory of the search. This is replaced with the value of the rootdir argument, or if that is NULL, with the value of the XmtNconfigDir application resource. When searching the user path (as described below), however, %R is replaced with the users home directory, or with the value of the XAPPLRESDIR environment variable. %H The users home directory. This substitution can be use ful when looking for configuration files that are always installed in the users home directory. You could use a path like %H/.%a, for example, to find the dot file for an application. Note that it generally does not make sense to use both %R and %H in the same element of a path. %a The application name, as reported by XtGetApplicationNameAndClass(). %A The application class name, as reported by XtGetApplicationNameAndClass(). %v The visual type of the screen. This substitution is replaced with one of the strings color (for color screens) , gray (for grayscale screens) and monochrome (for monochrome screens). %z The approximate size or resolution of the screen, as determined by its absolute number of pixels, not by screen size in inches or screen resolution in dots-per-inch. This substitution will be replaced by one of the strings small, medium or large. %d The depth of the screen in bitplanes. Typical values for this substitution are 1 (for monochrome screens), and 8 (for the common variety of 256-color screens). %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, then the empty string is used. %N The value of the objname argument, or the applications class name if objname is NULL. %S The value of the suffix argument. This will generally be some suffix that identifies the type of the file, such as .xbm for a bitmap file or .ad for an app-defaults file. Note that files are often installed without a suffix when they are in directories (like /usr/lib/X11/app-defaults) that identify the file type. You should generally supply a suffix argument to XmtFindFile(), but some paths will never contain the %S substitution. If suffix is not specified, then %S will be replaced with the empty string. %C The value of the customization application resource. 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 X11R5 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() 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. The %L substitution in a path allows an application to automatically find internationalized versions of its resources, online help files, pixmaps, and so on. %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. Other Searches The where argument specifies where XmtFindFile() should look for the specified file. It may be one of the following constants, or the bitwise OR of any of them. XmtSearchPathOnly This is a symbolic name for the constant 0. When no flags are set in the where argument, XmtFindFile() searches only the specified path, and not in any of the standard places. If you do not specify any of the flags below, then you must specify an explicit path to be searched. XmtSearchUserPath This flag specifies that XmtFindFile() should search the standard user path before it searches anywhere else. Note that this search is performed before even the specified path is searched. Only specify this flag if you want the user to be able to provide an alternate to whatever file you are looking up.
The standard user path is specified by the XUSERFILESEARCHPATH environment variable, or if that variable is not defined, by the userConfigPath application resource, or if that resource is not defined, the XmtFindFile() default path (which is specified below.) When searching the user path, the %R substitution is not replaced with the rootdir argument or the configDir application resource. Instead, %R is replaced with the XAPPLRESDIR environment variable, or with the users home directory. Searching for user files in this way is consistent with what the Xt Intrinsics do when looking up user app-defaults files for applications.
XmtSearchAppPath This flag specifies that XmtFindFile() should search the standard application path. The application path is searched after the user path is searched, if XmtSearchUserPath is specified, and after the specified path, if any, is searched.
The standard application path is specified by the configPath application resource. If this resource is not specified, a default value (described below) which is suitable for most applications is used. For this search, the %R substitution is replaced by the value of the rootdir argument, or if that is not specified, by the value of the configDir application resource. The default value for configDir is /usr/lib/X11, but it will often be set in an app-defaults file to something like /usr/local/lib or /usr/X11R5/lib.
This standard application path is usually suitable for almost all auxiliary files that an application must read, so you may often call XmtFindFile() with no rootdir argument, no path argument, and where set to XmtSearchAppPath.
XmtSearchSysPath This flag specifies that XmtFindFile() should search the standard system path. This search is only done if any previous searches through the user path, the specified path, and the application path failed.
The standard application path is defined to be the path that XtResolvePathname() searches when no path is specified to it. This is the value of the XFILESEARCHPATH environment variable, or if that is not defined, the default XtResolvePathname() path. This default path is implementation-dependent, but it is usually under /usr/lib/X11. This is the path that the Xt Intrinsics use to find an applications app-defaults file. See XtResolvePathname() for more information on this default system path.
For the search of the system path, none of the special XmtFindFile() substitutions are performed: %R, %H, %a, %A, %v, %z, or %d. Also, if a suffix argument was supplied, and the search failed, then the search is performed again, without the suffix. This is done because the default Xt ResolvePathname() path generally includes the %S substitution, but convention seems to be to install files in the system directories without suffixes. (This is at least the case for app-defaults file in /usr/lib/X11/app-defaults.)
XmtSearchEverywhere This constant is just the bitwise-OR of each of the other constants; it is shorthand to tell XmtFindFile() to search every place it knows how. You can OR together any combination of the XmtSearchUserPath, XmtSearchAppPath, and XmtSearchSysPath for the where argument.
The Default Path
When searching the user path, XmtFindFile() checks the userConfigPath application resource, and when searching the application path, it uses the configPath application resource. The default value for each of these resources is the following path:
If you set the XMTDEBUGFINDFILE environment variable, then XmtFindFile() will print the name of every file it checks for. This can be quite helpful when trying to get your application to correctly look for its configuration files. Compile the Xmt library with the -NDEBUG flag to disable this debugging feature.
Chapter 6, Managing Auxiliary Files,
Chapter 7, Application Resources and Command-Line Arguments, XtResolvePathname(), XtFindFile().
|Xmt||XMTFINDFILE (3)||Motif Tools|