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