FreeBSD Manual Pages
XmtFindFile(3) Library Functions Manual XmtFindFile(3) NAME XmtFindFile() - look for application auxiliary files. SYNOPSIS String XmtFindFile(Widget w, String type, String objname, String suffix, String rootdir, String path, int where) ARGUMENTS INPUTS w Any widget in the application; specifies which resource data- base 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. objnameThe 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. rootdirThe 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. RETURNS 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. DESCRIPTION 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 cus- tomization 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-sepa- rated 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 sub- stitutions 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 ex- ample, 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 ele- ment of a path. %a The application name, as reported by XtGetApplicationNameAndClass(). %A The application class name, as reported by XtGetApplicationNameAnd- Class(). %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 re- placed by one of the strings ``small'', ``medium'' or ``large''. %d The depth of the screen in bitplanes. Typical values for this sub- stitution 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 mono- chrome 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 Re- lease 5 and later, it is the value of this resource or the value re- turned by the language procedure, if any is registered. (See XtSet- LanguageProc() for more information.) In Release 5, if the xnlLan- guage resource is not set, the language procedure will usually re- turn the value of the LANG environment variable. The %L substitution in a path allows an application to automatically find international- ized 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 speci- fied 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 spec- ify this flag if you want the user to be able to provide an alter- nate 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 de- fined, 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. In- stead, %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 appli- cation 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 sub- stitution, but convention seems to be to install files in the system directories without suffixes. (This is at least the case for app-de- faults 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 ap- plication resource, and when searching the application path, it uses the configPath application resource. The default value for each of these re- sources is the following path: %R/%L/%a/%N%C%S: %R/%L/%a/%N%S: %R/%l/%a/%N%C%S: %R/%l/%a/%N%S: %R/%a/%N%C%S: %R/%a/%N%S: %R/%N%C%S: %R/%N%S 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 de- bugging feature. SEE ALSO Chapter 6, Managing Auxiliary Files, Chapter 7, Application Resources and Command-Line Arguments, XtResolvePathname(), XtFindFile(). Xmt Motif Tools XmtFindFile(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtFindFile&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>