NAME

SYNOPSIS

ARGUMENTS

RETURNS

DESCRIPTION

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.

Substitutions

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 user's home directory, or with the value of the XAPPLRESDIR environment variable.

%H

The user's home directory. This substitution can be use ful when looking for configuration files that are always installed in the user's 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 application's 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 user's 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 application's 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:

Debugging

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.

SEE ALSO