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 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. 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 file- name with XtFree() when done with it. DESCRIPTION XmtFindFile() finds a fully qualified filename for an application aux- iliary 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 admin- istrator 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. 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 XtResolvePath- name(). %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 XAP- PLRESDIR 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 XtGetApplicationNameAnd- Class(). %A The application class name, as reported by XtGetApplicationName- AndClass(). %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 substi- tution. 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 bit- wise 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 spec- ified 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 ``stan- dard 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 XUSERFILESEARCH- PATH 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 speci- fied 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 XAPPLRES- DIR 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 ``stan- dard 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 ``stan- dard 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 XtResolvePath- name() for more information on this default system path. For the search of the system path, none of the special XmtFind- File() 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 gen- erally 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 con- stants; 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: %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 XmtFind- File() 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 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.0>