Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
NAME
Xdefaults, Xresources - X Window System resource management
DESCRIPTION
The file .Xdefaults in a user's home directory contains
default resources for X-clients. Although this is the most
common place for a user to put resources, it is not always
the most appropriate. To fully understand the resource
mechanism, you must understand the history of resources.
An application's resources are generated by merging the
following 6 sources:
1- System application default resources.
2- User application default resources.
3- User general default resources.
4- Screen resources.
5- Environment resources.
6- Command line resources.
For each source only one file (or property) is read;
therefore, when a list of files is specified for a resource
(ie. source 1 or 2) the first file found will be used. The
merging process is done in the specified order, identical
resource specifications from different sources are
overwritten, so the later source is used. Therefore, command
line resources can override resources from any other source.
For a further discussion of resource precedence rules, see
XrmGetResource(3).
1a- use XFILESEARCHPATH if defined
1b- else use the first file found in the following list:
/usr/lib/X11/%L/app-defaults/%N%C
/usr/lib/X11/%l/app-defaults/%N%C
/usr/lib/X11/app-defaults/%N%C
/usr/lib/X11/%L/app-defaults/%N
/usr/lib/X11/%l/app-defaults/%N
/usr/lib/X11/app-defaults/%N
1c- else use internal fallback resources set by
XtAppSetFallbackResources(3Xt).
2a- use XUSERFILESEARCHPATH if defined
2b- else if XAPPLRESDIR defined,
use the first file found in the following list:
$XAPPLRESDIR/%L/%N%C
$XAPPLRESDIR/%l/%N%C
$XAPPLRESDIR/%N%C
$HOME/%N%C
$XAPPLRESDIR/%L/%N
Licensed material--property of copyright holder(s) Page 1
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
$XAPPLRESDIR/%l/%N
$XAPPLRESDIR/%N
$HOME/%N
2c- else, use the first file found in the following list:
$HOME/%L/%N%C
$HOME/%l/%N%C
$HOME/%N%C
$HOME/%L/%N
$HOME/%l/%N
$HOME/%N
3a- use RESOURCEMANAGER property of the default root
window, if defined
3b- else, use $HOME/.Xdefaults
4- use SCREENRESOURCES property of the requested screen
5a- use the file specified by $XENVIRONMENT if defined
5b- else, use $HOME/.Xdefaults-`hostname`
6- Command line arguments.
HISTORY OF RESOURCES
The following is a somewhat chronological account of the
development of resource management for the X Window System.
Considerable editorial license has been taken to make it
easy for the reader to understand.
In the beginning (ie. X10) there were only command line
arguments. Massive command line arguments, as in the case
of xterm which has 52 different command line options. It was
soon realized another mechanism was needed for setting
program options in a generic way. So the idea of an
.Xdefaults file was born. It would live in a user's home
directory; therefore, different users could set different
options according to their personal preference. And it
would contain option settings, one per line, in the
following format:
<application name>.<option name>:<value>
This format would later be extended to include the widget
class and hierarchy used in the X Toolkit Intrinsics (Xt).
Since the X Window System is network based, all the clients
a user has started are not necessarily executing on the same
host system. This brings up a problem if a user's home
directory is not accessible to all host systems, or if there
is no concept of a user's home directory, such as on an MS-
Licensed material--property of copyright holder(s) Page 2
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
DOS system. The solution was to invent the program xrdb(1)
which loaded the RESOURCEMANAGER property attached to the
root window of the display with the contents of the user's
.Xdefaults file. The function XGetDefault(3) was modified
to look for the RESOURCEMANAGER property. If the property
was not found, it would then read the user's .Xdefaults
file, to be backwardly compatible with systems that did not
have xrdb(1).
This backward compatibility has several unexpected side-
affects. By default xrdb(1) runs the .Xdefaults file
through the C pre-processor before loading it into the
RESOURCEMANAGER property. However, when XGetDefault(3)
reads the .Xdefaults file it does not pre-process it.
Fortunately the Xlib resource manager functions silently
ignores any malformed resource specifications. C-style
comments, #ifdef's and #include's don't work as expected
when the RESOURCEMANAGER property does not exist.
Although, in X11R5 a limited version of the #include
directive is supported.
The worst side-affect of xrdb(1) using the C pre-processor
is the common misconception that all resource files are
pre-processed. In fact, only the .Xdefaults file is pre-
processed, and only when it is loaded into the
RESOURCEMANAGER property by xrdb(1).
Now that all resources are set on a network-wide basis with
the RESOURCEMANAGER property, a need for setting host
specific resources was needed. So the file .Xdefaults-<host>
(where <host> is replaced by the hostname of the system) in
a user's home directory was invented. This file is read by
XGetDefault(3) and is not pre-processed. For systems
without home directories, or if you want to override the
above behavior, the environment variable XENVIRONMENT can be
set to the pathname of a file containing the host specific
resources.
The X Toolkit Intrinsics was the dawn of a new era for
resource management. No longer would mere mortals have to
comprehend all of the vast possibilities available through
this emerging technology. The current implementation of
XGetDefault(3) is described above, the new functionality
described below is only available through the X Toolkit
Intrinsics.
Application writers needed to distribute resources with
their applications, but did not want to require the users to
merge them with their .Xdefaults files. The directory
/usr/lib/X11/app-defaults was created. In it would be a
file for each application installed on the system. The name
of the files would be the same as the class name of the
Licensed material--property of copyright holder(s) Page 3
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
application. The convention of capitalizing the first
character of the application name, except if it starts with
an 'x', in which case the first two letters are capitalized,
to form the class name of an application, is not always
followed. So while mwm and xterm have the class names Mwm
and XTerm, xfd has the class name Xfd.
The user's .Xdefaults file started to growing without
bounds. With each new client up to 100 lines were added to a
user's .Xdefaults file. The solution was to bring the
system app-defaults directory concept to the user level. A
user's home directory is searched for a file matching the
class name of the application. And for systems without home
directories, or for those users who don't want cluttered
home directories, the environment variable XAPPLRESDIR can
be set to the pathname of a directory containing the user's
application resource files.
Next came internationalization (I18N). The environment
variable XFILESEARCHPATH would specify a colon separated
list of files to search for a system default application
resource file. The default value is:
/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:/usr/lib/X11/%T/%N%C%S:
/usr/lib/X11/%L/%T/%N%S:/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
The "%" meta-notation is the same as used in with the
catopen(3) library function. The default list of
metacharacters is:
%N The application's class name.
%T The type of the file.
%S The filename suffix.
%C The value of the customization resource.
%L The the value of the LANG environment variable.
%l The language part of %L.
%t The territory part of %L.
%c The codeset part of %L.
%% A single %
The LANG environment variable should comply with the XPG
language specification, which has three fields in the
following order, language, territory and codeset. It has the
form:
LANG=language[_territory[.codeset]]
The LANG environment variable can be overridden by the
xnlLanguage resource (eg. "*xnlLanguage: french") in the
user's default resources (RESOURCEMANAGER property or
$HOME/.Xdefaults). It can also be overridden on the command
line with the -xnllanguage option, which takes precedence
Licensed material--property of copyright holder(s) Page 4
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
over the user default resources. The other resource sources,
system/user application defaults, screen, and environment
resources (1, 2, 4 & 5), are not searched for the
xnlLanguage resource.
XFILESEARCHPATH is used by XtResolvePathname(3) to retrieve
data files (including resource files) used by an
application. Since this is a new function for X11R4, it is
not used by all applications. Also applications can define
more metacharacters than listed above.
For application resource files the type (%T) is set to
"app-defaults", and the suffix (%S) is empty. For example,
if LANG is set to "Spanish_Mexico", xterm would use the
following list of files, in the specified order, to find its
system default application resources:
/usr/lib/X11/Spanish_Mexico/app-defaults/XTerm
/usr/lib/X11/Spanish/app-defaults/XTerm
/usr/lib/X11/app-defaults/XTerm
The search for user resource files was extended for I18N by
defining, in addition to XAPPLRESDIR, a new environment
variable XUSERFILESEARCHPATH. Its default value depends on
if XAPPLRESDIR is set. If so the search path for a user's
resource file is as follows:
$XAPPLRESDIR/%L/%N%C:$XAPPLRESDIR/%l/%N%C:$XAPPLRESDIR/%N:$HOME/%N%C:
$XAPPLRESDIR/%L/%N:$XAPPLRESDIR/%l/%N:$XAPPLRESDIR/%N:$HOME/%N
else if XAPPLRESDIR is not defined:
$HOME/%L/%N%C:$HOME/%l/%N%C:$HOME/%N%C:$HOME/%L/%N:$HOME/%l/%N:$HOME/%N
The customization meta character (%C), which is new for
X11R5, is used in the default value of XFILESEARCHPATH and
XUSERFILESEARCHPATH. It is intended to customize resources
for color vs. monochrome systems. Typically the
customization is set in a user's .Xdefaults file as follows:
#ifdef COLOR
*Customization: -color
#else
*Customization: -mono
#endif
The different sources are actually combined in order of
precedence. The command line arguments (source 7) are read
first. Therefore, the value of the customization meta
character (%C), used to resolve the filename for the user
application default resources (source 2), is set by the
previously read sources. Likewise the user app-defaults
Licensed material--property of copyright holder(s) Page 5
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
(source 2) can effect the filename resolution for the system
app-defaults (source 1).
NOTE
The environment variable XFILESEARCHPATH is used to search
for more than just app-default files, such as bitmaps, and
help files. Therefore, the file type and suffix meta
characters (%T and %S) should always be used when setting
XFILESEARCHPATH.
ENVIRONMENT
HOME the user's home directory.
LANG the user's preferred language.
XENVIRONMENT a file to be read for the environment default
resources, if not set $HOME/.Xdefaults-`hostname` is
read.
XAPPLRESDIR a directory containing the user's application
default resource files, if not set $HOME is used.
XFILESEARCHPATH a colon separated list of files used to get the
system application default file.
XUSERFILESEARCHPATH a colon separated list of files used to get
the user's application default file.
SEE ALSO
X(1), xrdb(1), XGetDefault(3), XrmGetResource(3),
XtAppInitialize(3)
FILES
$HOME/.Xdefaults
$HOME/.Xdefaults-`hostname`
$HOME/app-defaults/%N
$HOME/app-defaults/%N%C
$HOME/%L/app-defaults/%N
$HOME/%L/app-defaults/%N%C
$HOME/%l/app-defaults/%N
$HOME/%l/app-defaults/%N%C
$XAPPLRESDIR/app-defaults/%N
$XAPPLRESDIR/app-defaults/%N%C
$XAPPLRESDIR/%L/app-defaults/%N
$XAPPLRESDIR/%L/app-defaults/%N%C
$XAPPLRESDIR/%l/app-defaults/%N
$XAPPLRESDIR/%l/app-defaults/%N%C
/usr/lib/X11/app-defaults/%N
/usr/lib/X11/app-defaults/%N%C
/usr/lib/X11/%L/app-defaults/%N
/usr/lib/X11/%L/app-defaults/%N%C
/usr/lib/X11/%l/app-defaults/%N
Licensed material--property of copyright holder(s) Page 6
Xdefaults(5) X Version 11 (Release 5) Xdefaults(5)
/usr/lib/X11/%l/app-defaults/%N%C
Licensed material--property of copyright holder(s) Page 7