X resources

In the X Window System, the X resources are parameters of computer programs such as the name of the font used in the buttons, the background color of menus, etc. They are used in conjunction with or as an alternative to command line parameters and configuration files.

Format

At the X protocol level, resources are strings that are stored in the server and have no special meaning. The syntax and meaning of these strings is given by client libraries and applications.

Every X resource specifies a parameter for a program or one of its components. A fully specified resource has the following format:

application.component.subcomponent.subcomponent.attribute: value

This resource specifies the value of attribute for the component named component.subcomponent.subcomponent of the program application. Resources are often used for specifying the parameters of widgets created by the application. Since these widgets are arranged in a tree, the sequence of component/subcomponent names is used to identify a widget by giving its path within the tree. The value of the resource is the value of an attribute for this widget, such as its background color, etc.

X resources are also used to specify parameters for the program that are not directly related to its widgets, using the same syntax.

X resources are designed to allow the same parameter to be specified for more than one program or component. This is realized by allowing wildcard characters in a resource specification. In particular, the ? character is used to match the application name or a single component. The * character is used to match any number of components. These two characters can be used anywhere but at the end of the resource name. In other words, an attribute cannot be replaced by a wildcard character.

While the resources can be loosely specified via the wildcard characters, queries for the value of a resource must specify that resource exactly. For example, a resource can specify that the background of every component of the xmail program must be red:

xmail*background: red

However, when a program (e.g., the xmail program itself, when it wants to find out which background color to use) accesses the resource database via Xlib functions, it can only request the value of a specific resource. Contrary to most databases, the stored data can be specified loosely (via wildcard characters), but the interrogation cannot. For example, a program can query for the value of xmail.main.background or of xmail.toc.buttons.background, but cannot use ? or * to check the background color of several components at once.

Resources can also be specified for classes of elements: for example, application.widget.widget.attribute: value can be generalized by replacing the application name with its class (e.g., Mail instead of xmh), each widget with its type (Pane, Button, etc.), and the attribute with its type.

Location and use

During X display server execution, the X resources are stored in two standard locations, depending on whether they apply to all screens or to a particular one:

1. the RESOURCE_MANAGER property of the root window of screen 0
2. the SCREEN_RESOURCES property of the root window of an arbitrary screen

X resources are accessible to all programs connected to the X display server, even if running on different computers.

X resources are stored in the server rather than in a configuration file to allow programs started from other computers to use them. Indeed, a program connecting to an X display server from another computer can access the resources via the X protocol. Using the old system of storing program parameters in the .Xdefaults file creates the need of copying this file to all other computers where a program can be started.

Resources are manipulated by the xrdb program. In particular, many X display server configurations run xrdb at start up, instructing it to read the resources from the .Xresources file in the user's home directory. From this point on, every other program finds the resources in the two standard locations. You can view the current resources from a console with xrdb -query.

Client libraries

Xlib contains a number of convenience functions for accessing the resources on the server and manipulating them locally. These functions are used both by xrdb and by every other program that needs these resources. Most of these functions manipulate a resource database, which is a local data structure representing a set of resource specifications. The Xlib functions for resource management are:

• functions for reading the resources on the server into a local string (XResourceManagerString and XScreenResourceString)
• functions for creating, manipulating, and destroying a local resource database (XrmInitialize, XrmDestroyDatabase, XrmGetFileDatabase, XrmPutFileDatabase, XrmGetStringDatabase, XrmLocaleOfDatabase, XrmSetDatabase, XrmGetDatabase, XrmCombineFileDatabase, XrmCombineDatabase, XrmMergeDatabases, XrmParseCommand)
• functions for looking up resources and storing new ones (XrmGetResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPutStringResource, XrmPutLineResource, XrmEnumerateDatabase)

In particular, the function XrmParseCommand allow parsing the command line arguments, reading resources that are then added to a local resource database. This way, the resources can be read from the server and used as defaults that are overridden by command line arguments.

For the sake of efficiency, integers called quarks are defined to represent local strings. Quarks are similar to atoms, but they represent strings stored locally rather than on the server. A number of Xlib functions create an association between strings and quarks. Quarks can be used in place of component names when using one of the above functions; resource names therefore correspond to quark lists.

See also

• X Window System protocols and architecture

External links

• Inessential X Resources for Techno-Dweebs
• Resource Manager Functions of the Xlib client library