1X(7) Miscellaneous Information Manual X(7)
2
6 X - a portable, network-transparent window system
7
9 The X Window System is a network transparent window system which runs
10 on a wide range of computing and graphics machines. It should be rela‐
11 tively straightforward to build the X.Org Foundation software distribu‐
12 tion on most ANSI C and POSIX compliant systems. Commercial implemen‐
13 tations are also available for a wide range of platforms.
14 The X.Org Foundation requests that the following names be used when
16 referring to this software:
17 X
19 X Window System
20 X Version 11
21 X Window System, Version 11
22 X11
23 X Window System is a trademark of The Open Group.
25
27 X Window System servers run on computers with bitmap displays. The
28 server distributes user input to and accepts output requests from vari‐
29 ous client programs through a variety of different interprocess commu‐
30 nication channels. Although the most common case is for the client
31 programs to be running on the same machine as the server, clients can
32 be run transparently from other machines (including machines with dif‐
33 ferent architectures and operating systems) as well.
34 X supports overlapping hierarchical subwindows and text and graphics
36 operations, on both monochrome and color displays. For a full explana‐
37 tion of the functions that are available, see the Xlib - C Language X
38 Interface manual, the X Window System Protocol specification, the X
39 Toolkit Intrinsics - C Language Interface manual, and various toolkit
40 documents.
41 The number of programs that use X is quite large. Programs provided in
43 the core X.Org Foundation distribution include: a terminal emulator,
44 xterm; a window manager, twm; a display manager, xdm; a console redi‐
45 rect program, xconsole; a mail interface, xmh; a bitmap editor, bitmap;
46 resource listing/manipulation tools, appres, editres; access control
47 programs, xauth, xhost, and iceauth; user preference setting programs,
48 xrdb, xcmsdb, xset, xsetroot, xstdcmap, and xmodmap; clocks, xclock and
49 oclock; a font displayer, xfd; utilities for listing information about
50 fonts, windows, and displays, xlsfonts, xwininfo, xlsclients, xdpyinfo,
51 xlsatoms, and xprop; screen image manipulation utilities, xwd, xwud,
52 and xmag; a performance measurement utility, x11perf; a font compiler,
53 bdftopcf; a font server and related utilities, xfs, fsinfo, fslsfonts,
54 fstobdf; a display server and related utilities, Xserver, rgb, mkfont‐
55 dir; a clipboard manager, xclipboard; keyboard description compiler and
56 related utilities, xkbcomp, setxkbmap xkbprint, xkbbell, xkbevd, xkb‐
57 vleds, and xkbwatch; a utility to terminate clients, xkill; a firewall
58 security proxy, xfwp; a proxy manager to control them, proxymngr; a
59 utility to find proxies, xfindproxy; web browser plug-ins, libxrx.so
60 and libxrxnest.so; an RX MIME-type helper program, xrx; and a utility
61 to cause part or all of the screen to be redrawn, xrefresh.
62 Many other utilities, window managers, games, toolkits, etc. are
64 included as user-contributed software in the X.Org Foundation distribu‐
65 tion, or are available on the Internet. See your site administrator
66 for details.
67
69 There are two main ways of getting the X server and an initial set of
70 client applications started. The particular method used depends on
71 what operating system you are running and whether or not you use other
72 window systems in addition to X.
73 Display Manager
75 If you want to always have X running on your display, your site
76 administrator can set your machine up to use a Display Manager
77 such as xdm, gdm, or kdm. This program is typically started by
78 the system at boot time and takes care of keeping the server
79 running and getting users logged in. If you are running one of
80 these display managers, you will normally see a window on the
81 screen welcoming you to the system and asking for your login
82 information. Simply type them in as you would at a normal ter‐
83 minal. If you make a mistake, the display manager will display
84 an error message and ask you to try again. After you have suc‐
85 cessfully logged in, the display manager will start up your X
86 environment. The documentation for the display manager you use
87 can provide more details.
88 xinit (run manually from the shell)
90 Sites that support more than one window system might choose to
91 use the xinit program for starting X manually. If this is true
92 for your machine, your site administrator will probably have
93 provided a program named "x11", "startx", or "xstart" that will
94 do site-specific initialization (such as loading convenient
95 default resources, running a window manager, displaying a
96 clock, and starting several terminal emulators) in a nice way.
97 If not, you can build such a script using the xinit program.
98 This utility simply runs one user-specified program to start
99 the server, runs another to start up any desired clients, and
100 then waits for either to finish. Since either or both of the
101 user-specified programs may be a shell script, this gives sub‐
102 stantial flexibility at the expense of a nice interface. For
103 this reason, xinit is not intended for end users.
104
106 From the user's perspective, every X server has a display name of the
107 form:
108 hostname:displaynumber.screennumber
110 This information is used by the application to determine how it should
112 connect to the server and which screen it should use by default (on
113 displays with multiple monitors):
114 hostname
116 The hostname specifies the name of the machine to which the
117 display is physically connected. If the hostname is not given,
118 the most efficient way of communicating to a server on the same
119 machine will be used.
120 displaynumber
122 The phrase "display" is usually used to refer to a collection
123 of monitors that share a common set of input devices (keyboard,
124 mouse, tablet, etc.). Most workstations tend to only have one
125 display. Larger, multi-user systems, however, frequently have
126 several displays so that more than one person can be doing
127 graphics work at once. To avoid confusion, each display on a
128 machine is assigned a display number (beginning at 0) when the
129 X server for that display is started. The display number must
130 always be given in a display name.
131 screennumber
133 Some displays share their input devices among two or more moni‐
134 tors. These may be configured as a single logical screen,
135 which allows windows to move across screens, or as individual
136 screens, each with their own set of windows. If configured
137 such that each monitor has its own set of windows, each screen
138 is assigned a screen number (beginning at 0) when the X server
139 for that display is started. If the screen number is not
140 given, screen 0 will be used.
141 On POSIX systems, the default display name is stored in your DISPLAY
143 environment variable. This variable is set automatically by the xterm
144 terminal emulator. However, when you log into another machine on a
145 network, you may need to set DISPLAY by hand to point to your display.
146 For example,
147 % setenv DISPLAY myws:0
149 $ DISPLAY=myws:0; export DISPLAY
150 The ssh program can be used to start an X program on a remote machine;
151 it automatically sets the DISPLAY variable correctly.
152 Finally, most X programs accept a command line option of -display dis‐
154 playname to temporarily override the contents of DISPLAY. This is most
155 commonly used to pop windows on another person's screen or as part of a
156 "remote shell" command to start an xterm pointing back to your display.
157 For example,
158 % xeyes -display joesws:0 -geometry 1000x1000+0+0
160 % rsh big xterm -display myws:0 -ls </dev/null &
161 X servers listen for connections on a variety of different communica‐
163 tions channels (network byte streams, shared memory, etc.). Since
164 there can be more than one way of contacting a given server, The host‐
165 name part of the display name is used to determine the type of channel
166 (also called a transport layer) to be used. X servers generally sup‐
167 port the following types of connections:
168 local
170 The hostname part of the display name should be the empty
171 string. For example: :0, :1, and :0.1. The most efficient
172 local transport will be chosen.
173 TCPIP
175 The hostname part of the display name should be the server
176 machine's hostname or IP address. Full Internet names, abbre‐
177 viated names, IPv4 addresses, and IPv6 addresses are all
178 allowed. For example: x.org:0, expo:0, [::1]:0,
179 198.112.45.11:0, bigmachine:1, and hydra:0.1.
180
182 An X server can use several types of access control. Mechanisms pro‐
183 vided in Release 7 are:
184 Host Access Simple host-based access control.
185 MIT-MAGIC-COOKIE-1 Shared plain-text "cookies".
186 XDM-AUTHORIZATION-1 Secure DES based private-keys.
187 SUN-DES-1 Based on Sun's secure rpc system.
188 Server Interpreted Server-dependent methods of access control
189 Xdm initializes access control for the server and also places autho‐
191 rization information in a file accessible to the user. Normally, the
192 list of hosts from which connections are always accepted should be
193 empty, so that only clients with are explicitly authorized can connect
194 to the display. When you add entries to the host list (with xhost),
195 the server no longer performs any authorization on connections from
196 those machines. Be careful with this.
197 The file from which Xlib extracts authorization data can be specified
199 with the environment variable XAUTHORITY, and defaults to the file
200 .Xauthority in the home directory. Xdm uses $HOME/.Xauthority and will
201 create it or merge in authorization records if it already exists when a
202 user logs in.
203 If you use several machines and share a common home directory across
205 all of the machines by means of a network file system, you never really
206 have to worry about authorization files, the system should work cor‐
207 rectly by default. Otherwise, as the authorization files are machine-
208 independent, you can simply copy the files to share them. To manage
209 authorization files, use xauth. This program allows you to extract
210 records and insert them into other files. Using this, you can send
211 authorization to remote machines when you login, if the remote machine
212 does not share a common home directory with your local machine. Note
213 that authorization information transmitted ``in the clear'' through a
214 network file system or using ftp or rcp can be ``stolen'' by a network
215 eavesdropper, and as such may enable unauthorized access. In many
216 environments, this level of security is not a concern, but if it is,
217 you need to know the exact semantics of the particular authorization
218 data to know if this is actually a problem.
219 For more information on access control, see the Xsecurity(7) manual
221 page.
222
224 One of the advantages of using window systems instead of hardwired ter‐
225 minals is that applications don't have to be restricted to a particular
226 size or location on the screen. Although the layout of windows on a
227 display is controlled by the window manager that the user is running
228 (described below), most X programs accept a command line argument of
229 the form -geometry WIDTHxHEIGHT+XOFF+YOFF (where WIDTH, HEIGHT, XOFF,
230 and YOFF are numbers) for specifying a preferred size and location for
231 this application's main window.
232 The WIDTH and HEIGHT parts of the geometry specification are usually
234 measured in either pixels or characters, depending on the application.
235 The XOFF and YOFF parts are measured in pixels and are used to specify
236 the distance of the window from the left or right and top and bottom
237 edges of the screen, respectively. Both types of offsets are measured
238 from the indicated edge of the screen to the corresponding edge of the
239 window. The X offset may be specified in the following ways:
240 +XOFF The left edge of the window is to be placed XOFF pixels in from
242 the left edge of the screen (i.e., the X coordinate of the win‐
243 dow's origin will be XOFF). XOFF may be negative, in which
244 case the window's left edge will be off the screen.
245 -XOFF The right edge of the window is to be placed XOFF pixels in
247 from the right edge of the screen. XOFF may be negative, in
248 which case the window's right edge will be off the screen.
249 The Y offset has similar meanings:
251 +YOFF The top edge of the window is to be YOFF pixels below the top
253 edge of the screen (i.e., the Y coordinate of the window's ori‐
254 gin will be YOFF). YOFF may be negative, in which case the
255 window's top edge will be off the screen.
256 -YOFF The bottom edge of the window is to be YOFF pixels above the
258 bottom edge of the screen. YOFF may be negative, in which case
259 the window's bottom edge will be off the screen.
260 Offsets must be given as pairs; in other words, in order to specify
262 either XOFF or YOFF both must be present. Windows can be placed in the
263 four corners of the screen using the following specifications:
264 +0+0 upper left hand corner.
266 -0+0 upper right hand corner.
268 -0-0 lower right hand corner.
270 +0-0 lower left hand corner.
272 In the following examples, a terminal emulator is placed in roughly the
274 center of the screen and a load average monitor, mailbox, and clock are
275 placed in the upper right hand corner:
276 xterm -fn 6x10 -geometry 80x24+30+200 &
278 xclock -geometry 48x48-0+0 &
279 xload -geometry 48x48-96+0 &
280 xbiff -geometry 48x48-48+0 &
281
283 The layout of windows on the screen is controlled by special programs
284 called window managers. Although many window managers will honor geom‐
285 etry specifications as given, others may choose to ignore them (requir‐
286 ing the user to explicitly draw the window's region on the screen with
287 the pointer, for example).
288 Since window managers are regular (albeit complex) client programs, a
290 variety of different user interfaces can be built. The X.Org Founda‐
291 tion distribution comes with a window manager named twm which supports
292 overlapping windows, popup menus, point-and-click or click-to-type
293 input models, title bars, nice icons (and an icon manager for those who
294 don't like separate icon windows).
295 See the user-contributed software in the X.Org Foundation distribution
297 for other popular window managers.
298
300 Collections of characters for displaying text and symbols in X are
301 known as fonts. A font typically contains images that share a common
302 appearance and look nice together (for example, a single size, bold‐
303 ness, slant, and character set). Similarly, collections of fonts that
304 are based on a common type face (the variations are usually called
305 roman, bold, italic, bold italic, oblique, and bold oblique) are called
306 families.
307 Fonts come in various sizes. The X server supports scalable fonts,
309 meaning it is possible to create a font of arbitrary size from a single
310 source for the font. The server supports scaling from outline fonts
311 and bitmap fonts. Scaling from outline fonts usually produces signifi‐
312 cantly better results than scaling from bitmap fonts.
313 An X server can obtain fonts from individual files stored in directo‐
315 ries in the file system, or from one or more font servers, or from a
316 mixtures of directories and font servers. The list of places the
317 server looks when trying to find a font is controlled by its font path.
318 Although most installations will choose to have the server start up
319 with all of the commonly used font directories in the font path, the
320 font path can be changed at any time with the xset program. However,
321 it is important to remember that the directory names are on the
322 server's machine, not on the application's.
323 Bitmap font files are usually created by compiling a textual font
325 description into binary form, using bdftopcf. Font databases are cre‐
326 ated by running the mkfontdir program in the directory containing the
327 source or compiled versions of the fonts. Whenever fonts are added to
328 a directory, mkfontdir should be rerun so that the server can find the
329 new fonts. To make the server reread the font database, reset the font
330 path with the xset program. For example, to add a font to a private
331 directory, the following commands could be used:
332 % cp newfont.pcf ~/myfonts
334 % mkfontdir ~/myfonts
335 % xset fp rehash
336 The xfontsel and xlsfonts programs can be used to browse through the
338 fonts available on a server. Font names tend to be fairly long as they
339 contain all of the information needed to uniquely identify individual
340 fonts. However, the X server supports wildcarding of font names, so
341 the full specification
342 -adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1
344 might be abbreviated as:
346 -*-courier-medium-r-normal--*-100-*-*-*-*-iso8859-1
348 Because the shell also has special meanings for * and ?, wildcarded
350 font names should be quoted:
351 % xlsfonts -fn '-*-courier-medium-r-normal--*-100-*-*-*-*-*-*'
353 The xlsfonts program can be used to list all of the fonts that match a
355 given pattern. With no arguments, it lists all available fonts. This
356 will usually list the same font at many different sizes. To see just
357 the base scalable font names, try using one of the following patterns:
358 -*-*-*-*-*-*-0-0-0-0-*-0-*-*
360 -*-*-*-*-*-*-0-0-75-75-*-0-*-*
361 -*-*-*-*-*-*-0-0-100-100-*-0-*-*
362 To convert one of the resulting names into a font at a specific size,
364 replace one of the first two zeros with a nonzero value. The field
365 containing the first zero is for the pixel size; replace it with a spe‐
366 cific height in pixels to name a font at that size. Alternatively, the
367 field containing the second zero is for the point size; replace it with
368 a specific size in decipoints (there are 722.7 decipoints to the inch)
369 to name a font at that size. The last zero is an average width field,
370 measured in tenths of pixels; some servers will anamorphically scale if
371 this value is specified.
372
374 One of the following forms can be used to name a font server that
375 accepts TCP connections:
376 tcp/hostname:port
378 tcp/hostname:port/cataloguelist
379 The hostname specifies the name (or decimal numeric address) of the
381 machine on which the font server is running. The port is the decimal
382 TCP port on which the font server is listening for connections. The
383 cataloguelist specifies a list of catalogue names, with '+' as a sepa‐
384 rator.
385 Examples: tcp/x.org:7100, tcp/198.112.45.11:7100/all.
387 One of the following forms can be used to name a font server that
389 accepts DECnet connections:
390 decnet/nodename::font$objname
392 decnet/nodename::font$objname/cataloguelist
393 The nodename specifies the name (or decimal numeric address) of the
395 machine on which the font server is running. The objname is a normal,
396 case-insensitive DECnet object name. The cataloguelist specifies a
397 list of catalogue names, with '+' as a separator.
398 Examples: DECnet/SRVNOD::FONT$DEFAULT, decnet/44.70::font$special/sym‐
400 bols.
401
403 Most applications provide ways of tailoring (usually through resources
404 or command line arguments) the colors of various elements in the text
405 and graphics they display. A color can be specified either by an
406 abstract color name, or by a numerical color specification. The numer‐
407 ical specification can identify a color in either device-dependent
408 (RGB) or device-independent terms. Color strings are case-insensitive.
409 X supports the use of abstract color names, for example, "red", "blue".
411 A value for this abstract name is obtained by searching one or more
412 color name databases. Xlib first searches zero or more client-side
413 databases; the number, location, and content of these databases is
414 implementation dependent. If the name is not found, the color is
415 looked up in the X server's database. The text form of this database
416 is commonly stored in the file usr/share/X11/rgb.txt.
417 A numerical color specification consists of a color space name and a
419 set of values in the following syntax:
420 <color_space_name>:<value>/.../<value>
422 An RGB Device specification is identified by the prefix "rgb:" and has
424 the following syntax:
425 rgb:<red>/<green>/<blue>
427 <red>, <green>, <blue> := h | hh | hhh | hhhh
429 h := single hexadecimal digits
430 Note that h indicates the value scaled in 4 bits, hh the value scaled
431 in 8 bits, hhh the value scaled in 12 bits, and hhhh the value scaled
432 in 16 bits, respectively. These values are passed directly to the X
433 server, and are assumed to be gamma corrected.
434 The eight primary colors can be represented as:
436 black rgb:0/0/0
438 red rgb:ffff/0/0
439 green rgb:0/ffff/0
440 blue rgb:0/0/ffff
441 yellow rgb:ffff/ffff/0
442 magenta rgb:ffff/0/ffff
443 cyan rgb:0/ffff/ffff
444 white rgb:ffff/ffff/ffff
445 For backward compatibility, an older syntax for RGB Device is sup‐
447 ported, but its continued use is not encouraged. The syntax is an ini‐
448 tial sharp sign character followed by a numeric specification, in one
449 of the following formats:
450 #RGB (4 bits each)
452 #RRGGBB (8 bits each)
453 #RRRGGGBBB (12 bits each)
454 #RRRRGGGGBBBB (16 bits each)
455 The R, G, and B represent single hexadecimal digits. When fewer than
457 16 bits each are specified, they represent the most-significant bits of
458 the value (unlike the "rgb:" syntax, in which values are scaled). For
459 example, #3a7 is the same as #3000a0007000.
460 An RGB intensity specification is identified by the prefix "rgbi:" and
462 has the following syntax:
463 rgbi:<red>/<green>/<blue>
465 The red, green, and blue are floating point values between 0.0 and 1.0,
467 inclusive. They represent linear intensity values, with 1.0 indicating
468 full intensity, 0.5 half intensity, and so on. These values will be
469 gamma corrected by Xlib before being sent to the X server. The input
470 format for these values is an optional sign, a string of numbers possi‐
471 bly containing a decimal point, and an optional exponent field contain‐
472 ing an E or e followed by a possibly signed integer string.
473 The standard device-independent string specifications have the follow‐
475 ing syntax:
476 CIEXYZ:<X>/<Y>/<Z> (none, 1, none)
478 CIEuvY:<u>/<v>/<Y> (~.6, ~.6, 1)
479 CIExyY:<x>/<y>/<Y> (~.75, ~.85, 1)
480 CIELab:<L>/<a>/<b> (100, none, none)
481 CIELuv:<L>/<u>/<v> (100, none, none)
482 TekHVC:<H>/<V>/<C> (360, 100, 100)
483 All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are floating
485 point values. Some of the values are constrained to be between zero
486 and some upper bound; the upper bounds are given in parentheses above.
487 The syntax for these values is an optional '+' or '-' sign, a string of
488 digits possibly containing a decimal point, and an optional exponent
489 field consisting of an 'E' or 'e' followed by an optional '+' or '-'
490 followed by a string of digits.
491 For more information on device independent color, see the Xlib refer‐
493 ence manual.
494
496 The X keyboard model is broken into two layers: server-specific codes
497 (called keycodes) which represent the physical keys, and server-inde‐
498 pendent symbols (called keysyms) which represent the letters or words
499 that appear on the keys. Two tables are kept in the server for con‐
500 verting keycodes to keysyms:
501 modifier list
503 Some keys (such as Shift, Control, and Caps Lock) are known as
504 modifier and are used to select different symbols that are
505 attached to a single key (such as Shift-a generates a capital
506 A, and Control-l generates a control character ^L). The server
507 keeps a list of keycodes corresponding to the various modifier
508 keys. Whenever a key is pressed or released, the server gener‐
509 ates an event that contains the keycode of the indicated key as
510 well as a mask that specifies which of the modifier keys are
511 currently pressed. Most servers set up this list to initially
512 contain the various shift, control, and shift lock keys on the
513 keyboard.
514 keymap table
516 Applications translate event keycodes and modifier masks into
517 keysyms using a keysym table which contains one row for each
518 keycode and one column for various modifier states. This table
519 is initialized by the server to correspond to normal typewriter
520 conventions. The exact semantics of how the table is inter‐
521 preted to produce keysyms depends on the particular program,
522 libraries, and language input method used, but the following
523 conventions for the first four keysyms in each row are gener‐
524 ally adhered to:
525 The first four elements of the list are split into two groups of
527 keysyms. Group 1 contains the first and second keysyms; Group 2 con‐
528 tains the third and fourth keysyms. Within each group, if the first
529 element is alphabetic and the the second element is the special keysym
530 NoSymbol, then the group is treated as equivalent to a group in which
531 the first element is the lowercase letter and the second element is the
532 uppercase letter.
533 Switching between groups is controlled by the keysym named MODE SWITCH,
535 by attaching that keysym to some key and attaching that key to any one
536 of the modifiers Mod1 through Mod5. This modifier is called the
537 ``group modifier.'' Group 1 is used when the group modifier is off,
538 and Group 2 is used when the group modifier is on.
539 Within a group, the modifier state determines which keysym to use. The
541 first keysym is used when the Shift and Lock modifiers are off. The
542 second keysym is used when the Shift modifier is on, when the Lock mod‐
543 ifier is on and the second keysym is uppercase alphabetic, or when the
544 Lock modifier is on and is interpreted as ShiftLock. Otherwise, when
545 the Lock modifier is on and is interpreted as CapsLock, the state of
546 the Shift modifier is applied first to select a keysym; but if that
547 keysym is lowercase alphabetic, then the corresponding uppercase keysym
548 is used instead.
549
551 Most X programs attempt to use the same names for command line options
552 and arguments. All applications written with the X Toolkit Intrinsics
553 automatically accept the following options:
554 -display display
556 This option specifies the name of the X server to use.
557 -geometry geometry
559 This option specifies the initial size and location of the win‐
560 dow.
561 -bg color, -background color
563 Either option specifies the color to use for the window back‐
564 ground.
565 -bd color, -bordercolor color
567 Either option specifies the color to use for the window border.
568 -bw number, -borderwidth number
570 Either option specifies the width in pixels of the window bor‐
571 der.
572 -fg color, -foreground color
574 Either option specifies the color to use for text or graphics.
575 -fn font, -font font
577 Either option specifies the font to use for displaying text.
578 -iconic
580 This option indicates that the user would prefer that the
581 application's windows initially not be visible as if the win‐
582 dows had be immediately iconified by the user. Window managers
583 may choose not to honor the application's request.
584 -name
586 This option specifies the name under which resources for the
587 application should be found. This option is useful in shell
588 aliases to distinguish between invocations of an application,
589 without resorting to creating links to alter the executable
590 file name.
591 -rv, -reverse
593 Either option indicates that the program should simulate
594 reverse video if possible, often by swapping the foreground and
595 background colors. Not all programs honor this or implement it
596 correctly. It is usually only used on monochrome displays.
597 +rv
599 This option indicates that the program should not simulate
600 reverse video. This is used to override any defaults since
601 reverse video doesn't always work properly.
602 -selectionTimeout
604 This option specifies the timeout in milliseconds within which
605 two communicating applications must respond to one another for
606 a selection request.
607 -synchronous
609 This option indicates that requests to the X server should be
610 sent synchronously, instead of asynchronously. Since Xlib nor‐
611 mally buffers requests to the server, errors do not necessarily
612 get reported immediately after they occur. This option turns
613 off the buffering so that the application can be debugged. It
614 should never be used with a working program.
615 -title string
617 This option specifies the title to be used for this window.
618 This information is sometimes used by a window manager to pro‐
619 vide some sort of header identifying the window.
620 -xnllanguage language[_territory][.codeset]
622 This option specifies the language, territory, and codeset for
623 use in resolving resource and other filenames.
624 -xrm resourcestring
626 This option specifies a resource name and value to override any
627 defaults. It is also very useful for setting resources that
628 don't have explicit command line arguments.
629
631 To make the tailoring of applications to personal preferences easier, X
632 provides a mechanism for storing default values for program resources
633 (e.g. background color, window title, etc.) that is used by programs
634 that use toolkits based on the X Toolkit Intrinsics library libXt.
635 (Programs using the common Gtk+ and Qt toolkits use other configuration
636 mechanisms.) Resources are specified as strings that are read in from
637 various places when an application is run. Program components are
638 named in a hierarchical fashion, with each node in the hierarchy iden‐
639 tified by a class and an instance name. At the top level is the class
640 and instance name of the application itself. By convention, the class
641 name of the application is the same as the program name, but with the
642 first letter capitalized (e.g. Bitmap or Emacs) although some programs
643 that begin with the letter ``x'' also capitalize the second letter for
644 historical reasons.
645 The precise syntax for resources is:
647 ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
649 Comment = "!" {<any character except null or newline>}
650 IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
651 FileName = <valid filename for operating system>
652 ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
653 ResourceName = [Binding] {Component Binding} ComponentName
654 Binding = "." | "*"
655 WhiteSpace = {<space> | <horizontal tab>}
656 Component = "?" | ComponentName
657 ComponentName = NameChar {NameChar}
658 NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
659 Value = {<any character except null or unescaped newline>}
660 Elements separated by vertical bar (|) are alternatives. Curly braces
662 ({...}) indicate zero or more repetitions of the enclosed elements.
663 Square brackets ([...]) indicate that the enclosed element is optional.
664 Quotes ("...") are used around literal characters.
665 IncludeFile lines are interpreted by replacing the line with the con‐
667 tents of the specified file. The word "include" must be in lowercase.
668 The filename is interpreted relative to the directory of the file in
669 which the line occurs (for example, if the filename contains no direc‐
670 tory or contains a relative directory specification).
671 If a ResourceName contains a contiguous sequence of two or more Binding
673 characters, the sequence will be replaced with single "." character if
674 the sequence contains only "." characters, otherwise the sequence will
675 be replaced with a single "*" character.
676 A resource database never contains more than one entry for a given
678 ResourceName. If a resource file contains multiple lines with the same
679 ResourceName, the last line in the file is used.
680 Any whitespace character before or after the name or colon in a
682 ResourceSpec are ignored. To allow a Value to begin with whitespace,
683 the two-character sequence ``\space'' (backslash followed by space) is
684 recognized and replaced by a space character, and the two-character
685 sequence ``\tab'' (backslash followed by horizontal tab) is recognized
686 and replaced by a horizontal tab character. To allow a Value to con‐
687 tain embedded newline characters, the two-character sequence ``\n'' is
688 recognized and replaced by a newline character. To allow a Value to be
689 broken across multiple lines in a text file, the two-character sequence
690 ``\newline'' (backslash followed by newline) is recognized and removed
691 from the value. To allow a Value to contain arbitrary character codes,
692 the four-character sequence ``\nnn'', where each n is a digit character
693 in the range of ``0''-``7'', is recognized and replaced with a single
694 byte that contains the octal value specified by the sequence. Finally,
695 the two-character sequence ``\\'' is recognized and replaced with a
696 single backslash.
697 When an application looks for the value of a resource, it specifies a
699 complete path in the hierarchy, with both class and instance names.
700 However, resource values are usually given with only partially speci‐
701 fied names and classes, using pattern matching constructs. An asterisk
702 (*) is a loose binding and is used to represent any number of interven‐
703 ing components, including none. A period (.) is a tight binding and is
704 used to separate immediately adjacent components. A question mark (?)
705 is used to match any single component name or class. A database entry
706 cannot end in a loose binding; the final component (which cannot be
707 "?") must be specified. The lookup algorithm searches the resource
708 database for the entry that most closely matches (is most specific for)
709 the full name and class being queried. When more than one database
710 entry matches the full name and class, precedence rules are used to
711 select just one.
712 The full name and class are scanned from left to right (from highest
714 level in the hierarchy to lowest), one component at a time. At each
715 level, the corresponding component and/or binding of each matching
716 entry is determined, and these matching components and bindings are
717 compared according to precedence rules. Each of the rules is applied
718 at each level, before moving to the next level, until a rule selects a
719 single entry over all others. The rules (in order of precedence) are:
720 1. An entry that contains a matching component (whether name, class,
722 or "?") takes precedence over entries that elide the level (that
723 is, entries that match the level in a loose binding).
724 2. An entry with a matching name takes precedence over both entries
726 with a matching class and entries that match using "?". An entry
727 with a matching class takes precedence over entries that match
728 using "?".
729 3. An entry preceded by a tight binding takes precedence over entries
731 preceded by a loose binding.
732 Programs based on the X Toolkit Intrinsics obtain resources from the
734 following sources (other programs usually support some subset of these
735 sources):
736 RESOURCE_MANAGER root window property
738 Any global resources that should be available to clients on all
739 machines should be stored in the RESOURCE_MANAGER property on
740 the root window of the first screen using the xrdb program.
741 This is frequently taken care of when the user starts up X
742 through the display manager or xinit.
743 SCREEN_RESOURCES root window property
745 Any resources specific to a given screen (e.g. colors) that
746 should be available to clients on all machines should be stored
747 in the SCREEN_RESOURCES property on the root window of that
748 screen. The xrdb program will sort resources automatically and
749 place them in RESOURCE_MANAGER or SCREEN_RESOURCES, as appro‐
750 priate.
751 application-specific files
753 Directories named by the environment variable XUSERFILESEARCH‐
754 PATH or the environment variable XAPPLRESDIR (which names a
755 single directory and should end with a '/' on POSIX systems),
756 plus directories in a standard place (usually under
757 /usr/share/X11/, but this can be overridden with the XFILE‐
758 SEARCHPATH environment variable) are searched for for applica‐
759 tion-specific resources. For example, application default
760 resources are usually kept in /usr/share/X11/app-defaults/.
761 See the X Toolkit Intrinsics - C Language Interface manual for
762 details.
763 XENVIRONMENT
765 Any user- and machine-specific resources may be specified by
766 setting the XENVIRONMENT environment variable to the name of a
767 resource file to be loaded by all applications. If this vari‐
768 able is not defined, a file named $HOME/.Xdefaults-hostname is
769 looked for instead, where hostname is the name of the host
770 where the application is executing.
771 -xrm resourcestring
773 Resources can also be specified from the command line. The
774 resourcestring is a single resource name and value as shown
775 above. Note that if the string contains characters interpreted
776 by the shell (e.g., asterisk), they must be quoted. Any number
777 of -xrm arguments may be given on the command line.
778 Program resources are organized into groups called classes, so that
780 collections of individual resources (each of which are called
781 instances) can be set all at once. By convention, the instance name of
782 a resource begins with a lowercase letter and class name with an upper
783 case letter. Multiple word resources are concatenated with the first
784 letter of the succeeding words capitalized. Applications written with
785 the X Toolkit Intrinsics will have at least the following resources:
786 background (class Background)
788 This resource specifies the color to use for the window back‐
789 ground.
790 borderWidth (class BorderWidth)
792 This resource specifies the width in pixels of the window bor‐
793 der.
794 borderColor (class BorderColor)
796 This resource specifies the color to use for the window border.
797 Most applications using the X Toolkit Intrinsics also have the resource
799 foreground (class Foreground), specifying the color to use for text and
800 graphics within the window.
801 By combining class and instance specifications, application preferences
803 can be set quickly and easily. Users of color displays will frequently
804 want to set Background and Foreground classes to particular defaults.
805 Specific color instances such as text cursors can then be overridden
806 without having to define all of the related resources. For example,
807 bitmap*Dashed: off
809 XTerm*cursorColor: gold
810 XTerm*multiScroll: on
811 XTerm*jumpScroll: on
812 XTerm*reverseWrap: on
813 XTerm*curses: on
814 XTerm*Font: 6x10
815 XTerm*scrollBar: on
816 XTerm*scrollbar*thickness: 5
817 XTerm*multiClickTime: 500
818 XTerm*charClass: 33:48,37:48,45-47:48,64:48
819 XTerm*cutNewline: off
820 XTerm*cutToBeginningOfLine: off
821 XTerm*titeInhibit: on
822 XTerm*ttyModes: intr ^c erase ^? kill ^u
823 XLoad*Background: gold
824 XLoad*Foreground: red
825 XLoad*highlight: black
826 XLoad*borderWidth: 0
827 emacs*Geometry: 80x65-0-0
828 emacs*Background: rgb:5b/76/86
829 emacs*Foreground: white
830 emacs*Cursor: white
831 emacs*BorderColor: white
832 emacs*Font: 6x10
833 xmag*geometry: -0-0
834 xmag*borderColor: white
835 If these resources were stored in a file called .Xresources in your
837 home directory, they could be added to any existing resources in the
838 server with the following command:
839 % xrdb -merge $HOME/.Xresources
841 This is frequently how user-friendly startup scripts merge user-spe‐
843 cific defaults into any site-wide defaults. All sites are encouraged
844 to set up convenient ways of automatically loading resources. See the
845 Xlib manual section Resource Manager Functions for more information.
846
848 DISPLAY
849 This is the only mandatory environment variable. It must point
850 to an X server. See section "Display Names" above.
851 XAUTHORITY
853 This must point to a file that contains authorization data. The
854 default is $HOME/.Xauthority. See Xsecurity(7), xauth(1),
855 xdm(1), Xau(3).
856 ICEAUTHORITY
858 This must point to a file that contains authorization data. The
859 default is $HOME/.ICEauthority.
860 LC_ALL, LC_CTYPE, LANG
862 The first non-empty value among these three determines the cur‐
863 rent locale's facet for character handling, and in particular
864 the default text encoding. See locale(7), setlocale(3),
865 locale(1).
866 XMODIFIERS
868 This variable can be set to contain additional information
869 important for the current locale setting. Typically set to
870 @im=<input-method> to enable a particular input method. See
871 XSetLocaleModifiers(3).
872 XLOCALEDIR
874 This must point to a directory containing the locale.alias file
875 and Compose and XLC_LOCALE file hierarchies for all locales. The
876 default value is /usr/share/X11/locale.
877 XENVIRONMENT
879 This must point to a file containing X resources. The default is
880 $HOME/.Xdefaults-<hostname>. Unlike $HOME/.Xresources, it is
881 consulted each time an X application starts.
882 XFILESEARCHPATH
884 This must contain a colon separated list of path templates,
885 where libXt will search for resource files. The default value
886 consists of
887 /etc/X11/%L/%T/%N%C%S:\
889 /etc/X11/%l/%T/%N%C%S:\
890 /etc/X11/%T/%N%C%S:\
891 /etc/X11/%L/%T/%N%S:\
892 /etc/X11/%l/%T/%N%S:\
893 /etc/X11/%T/%N%S:\
894 /usr/share/X11/%L/%T/%N%C%S:\
895 /usr/share/X11/%l/%T/%N%C%S:\
896 /usr/share/X11/%T/%N%C%S:\
897 /usr/share/X11/%L/%T/%N%S:\
898 /usr/share/X11/%l/%T/%N%S:\
899 /usr/share/X11/%T/%N%S:\
900 /usr/lib64/X11/%L/%T/%N%C%S:\
901 /usr/lib64/X11/%l/%T/%N%C%S:\
902 /usr/lib64/X11/%T/%N%C%S:\
903 /usr/lib64/X11/%L/%T/%N%S:\
904 /usr/lib64/X11/%l/%T/%N%S:\
905 /usr/lib64/X11/%T/%N%S
906 A path template is transformed to a pathname by substituting:
908 %D => the implementation-specific default path
910 %N => name (basename) being searched for
911 %T => type (dirname) being searched for
912 %S => suffix being searched for
913 %C => value of the resource "customization"
914 (class "Customization")
915 %L => the locale name
916 %l => the locale's language (part before '_')
917 %t => the locale's territory (part after '_` but before '.')
918 %c => the locale's encoding (part after '.')
919 XUSERFILESEARCHPATH
921 This must contain a colon separated list of path templates,
922 where libXt will search for user dependent resource files. The
923 default value is:
924 $XAPPLRESDIR/%L/%N%C:\
926 $XAPPLRESDIR/%l/%N%C:\
927 $XAPPLRESDIR/%N%C:\
928 $HOME/%N%C:\
929 $XAPPLRESDIR/%L/%N:\
930 $XAPPLRESDIR/%l/%N:\
931 $XAPPLRESDIR/%N:\
932 $HOME/%N
933 $XAPPLRESDIR defaults to $HOME, see below.
935 A path template is transformed to a pathname by substituting:
937 %D => the implementation-specific default path
939 %N => name (basename) being searched for
940 %T => type (dirname) being searched for
941 %S => suffix being searched for
942 %C => value of the resource "customization"
943 (class "Customization")
944 %L => the locale name
945 %l => the locale's language (part before '_')
946 %t => the locale's territory (part after '_` but before '.')
947 %c => the locale's encoding (part after '.')
948 XAPPLRESDIR
950 This must point to a base directory where the user stores his
951 application dependent resource files. The default value is
952 $HOME. Only used if XUSERFILESEARCHPATH is not set.
953 XKEYSYMDB
955 This must point to a file containing nonstandard keysym defini‐
956 tions. The default value is /usr/share/X11/XKeysymDB.
957 XCMSDB This must point to a color name database file. The default value
959 is
960 /usr/lib64/X11/Xcms.txt.
961 RESOURCE_NAME
963 This serves as main identifier for resources belonging to the
964 program being executed. It defaults to the basename of pathname
965 of the program.
966 SESSION_MANAGER
968 Denotes the session manager to which the application should con‐
969 nect. See xsm(1), rstart(1).
970 XF86BIGFONT_DISABLE
972 Setting this variable to a non-empty value disables the
973 XFree86-Bigfont extension. This extension is a mechanism to
974 reduce the memory consumption of big fonts by use of shared mem‐
975 ory.
976 XKB_FORCE
978 XKB_DISABLE
979 XKB_DEBUG
980 _XKB_CHARSET
981 _XKB_LOCALE_CHARSETS
982 _XKB_OPTIONS_ENABLE
983 _XKB_LATIN1_LOOKUP
984 _XKB_CONSUME_LOOKUP_MODS
985 _XKB_CONSUME_SHIFT_AND_LOCK
986 _XKB_IGNORE_NEW_KEYBOARDS
987 _XKB_CONTROL_FALLBACK
988 _XKB_COMP_LED _XKB_COMP_FAIL_BEEP
989 These variables influence the X Keyboard Extension.
991
993 The following is a collection of sample command lines for some of the
994 more frequently used commands. For more information on a particular
995 command, please refer to that command's manual page.
996 % xrdb $HOME/.Xresources
998 % xmodmap -e "keysym BackSpace = Delete"
999 % mkfontdir /usr/local/lib/X11/otherfonts
1000 % xset fp+ /usr/local/lib/X11/otherfonts
1001 % xmodmap $HOME/.keymap.km
1002 % xsetroot -solid 'rgbi:.8/.8/.8'
1003 % xset b 100 400 c 50 s 1800 r on
1004 % xset q
1005 % twm
1006 % xmag
1007 % xclock -geometry 48x48-0+0 -bg blue -fg white
1008 % xeyes -geometry 48x48-48+0
1009 % xbiff -update 20
1010 % xlsfonts '*helvetica*'
1011 % xwininfo -root
1012 % xdpyinfo -display joesworkstation:0
1013 % xhost -joesworkstation
1014 % xrefresh
1015 % xwd | xwud
1016 % bitmap companylogo.bm 32x32
1017 % xcalc -bg blue -fg magenta
1018 % xterm -geometry 80x66-0-0 -name myxterm $*
1019
1021 A wide variety of error messages are generated from various programs.
1022 The default error handler in Xlib (also used by many toolkits) uses
1023 standard resources to construct diagnostic messages when errors occur.
1024 The defaults for these messages are usually stored in
1025 usr/share/X11/XErrorDB. If this file is not present, error messages
1026 will be rather terse and cryptic.
1027 When the X Toolkit Intrinsics encounter errors converting resource
1029 strings to the appropriate internal format, no error messages are usu‐
1030 ally printed. This is convenient when it is desirable to have one set
1031 of resources across a variety of displays (e.g. color vs. monochrome,
1032 lots of fonts vs. very few, etc.), although it can pose problems for
1033 trying to determine why an application might be failing. This behavior
1034 can be overridden by the setting the StringConversionWarnings resource.
1035 To force the X Toolkit Intrinsics to always print string conversion
1037 error messages, the following resource should be placed in the file
1038 that gets loaded onto the RESOURCE_MANAGER property using the xrdb pro‐
1039 gram (frequently called .Xresources or .Xres in the user's home direc‐
1040 tory):
1041 *StringConversionWarnings: on
1043 To have conversion messages printed for just a particular application,
1045 the appropriate instance name can be placed before the asterisk:
1046 xterm*StringConversionWarnings: on
1048
1050 XOrgFoundation(7), XStandards(7), Xsecurity(7), appres(1), bdftopcf(1),
1051 bitmap(1), editres(1), fsinfo(1), fslsfonts(1), fstobdf(1), iceauth(1),
1052 imake(1), makedepend(1), mkfontdir(1), oclock(1), proxymngr(1), rgb(1),
1053 resize(1), rstart(1), smproxy(1), twm(1), x11perf(1), x11perfcomp(1),
1054 xauth(1), xclipboard(1), xclock(1), xcmsdb(1), xconsole(1), xdm(1),
1055 xdpyinfo(1), xfd(1), xfindproxy(1), xfs(1), xfwp(1), xhost(1),
1056 xinit(1), xkbbell(1), xkbcomp(1), xkbevd(1), xkbprint(1), xkbvleds(1),
1057 xkbwatch(1), xkill(1), xlogo(1), xlsatoms(1), xlsclients(1), xls‐
1058 fonts(1), xmag(1), xmh(1), xmodmap(1), xprop(1), xrdb(1), xrefresh(1),
1059 xrx(1), xset(1), xsetroot(1), xsm(1), xstdcmap(1), xterm(1), xwd(1),
1060 xwininfo(1), xwud(1). Xserver(1), Xorg(1), Xdmx(1), Xephyr(1),
1061 Xnest(1), Xquartz(1), Xvfb(1), Xvnc(1), XWin(1). Xlib - C Language X
1062 Interface, and X Toolkit Intrinsics - C Language Interface
1063
1065 X Window System is a trademark of The Open Group.
1066
1068 A cast of thousands, literally. Releases 6.7 and later are brought to
1069 you by the X.Org Foundation. The names of all people who made it a
1070 reality will be found in the individual documents and source files.
1071 Releases 6.6 and 6.5 were done by The X.Org Group. Release 6.4 was
1073 done by The X Project Team. The Release 6.3 distribution was from The
1074 X Consortium, Inc. The staff members at the X Consortium responsible
1075 for that release were: Donna Converse (emeritus), Stephen Gildea (emer‐
1076 itus), Kaleb Keithley, Matt Landau (emeritus), Ralph Mor (emeritus),
1077 Janet O'Halloran, Bob Scheifler, Ralph Swick, Dave Wiggins (emeritus),
1078 and Reed Augliere.
1079 The X Window System standard was originally developed at the Laboratory
1081 for Computer Science at the Massachusetts Institute of Technology, and
1082 all rights thereto were assigned to the X Consortium on January 1,
1083 1994. X Consortium, Inc. closed its doors on December 31, 1996. All
1084 rights to the X Window System have been assigned to The Open Group.
1085X Version 11 xorg-docs 1.6 X(7)