Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtFindFile(3)		   Library Functions Manual		XmtFindFile(3)

       XmtFindFile() - look for	application auxiliary files.

       String XmtFindFile(Widget w, String type, String	objname, String
		      suffix, String rootdir, String path, int where)


	    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

		   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.

		   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

	    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	 file-
	    name with XtFree() when done with it.

       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

       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

       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	XtResolvePath-

       %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-

       %A     The application class name, as reported by XtGetApplicationName-

       %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

       %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

       %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.

	      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.

	      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

	      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.

	      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

	      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/%N%C%S: %R/%N%S


       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.

       Chapter 6, Managing Auxiliary Files,
       Chapter 7, Application Resources	and Command-Line Arguments,
       XtResolvePathname(), XtFindFile().

Xmt				  Motif	Tools			XmtFindFile(3)


Want to link to this manual page? Use this URL:

home | help