X(1X) X(1X)NAME X - a portable, network-transparent window system SYNOPSIS X [option]... DESCRIPTION X is a network transparent window system which runs under a wide variety of operating systems. It was developed at the Massachusetts Institute of Technology (MIT). The standardrdistribution from MIT works on A/UX version 1.0 (andhigher), Ultrix-32 version 1.2 (and higher), 4.3 BSD, SunOS 3.2 (and higher), HP-UX 6.01, and DOMAIN/IX 9.7. Further- more, many vendors support X under other operating systems. X servers run on computers with bitmapped screens. The server distributes user input to, and accepts output re- quests from, various client applications through a variety of different interprocess communication channels. Although the most common case is for the client applications to be running on the same machine as the server, clients can also be run transparently from other machines (including machines with different architectures and operating systems). X supports overlapping hierarchical subwindows. X also sup- ports text and graphics operations on both monochrome and color screens. For a full explanation of functions, see X11 User's Guide for A/UX. In addition, see Xlib - C Language Interface, X Window System Protocol Specification, X Toolkit Intrinsics - C Language Interface, which are distributed by MIT. The X protocol provides mechanism, not policy. Windows are manipulated (including moving, resizing, and iconifying) not by the server itself, but by a separate program called a window manager. This program is simply another client and requires no special privileges. The twm(1X) window manager is included as part of the provided X startup script. The number of user programs for X is growing rapidly. Of particular interest are: a terminal emulator (xterm(1X)), a window manager (twm (1X)), a display manager (xdm(1X)), a bitmap editor (bitmap(1X)), an access control command (xhost(1X)), user preference setting commands (xrdb(1X), xset(1X), xsetroot(1X), and xmodmap(1X)), a load monitor (xload(1X)), a clock (xclock(1X) and (oclock(1X)), a font displayer (xfd(1X)), utilities for listing information about fonts, windows, and displays (xlsfonts(1X), xlswins(1X), xwininfo(1X), xdpyinfo(1X), and xprop(1X)), a diagnostic for seeing what events are generated and when (xev(1X)), screen image manipulation utilities (xwd(1X), xwud(1X), xpr(1X), and xmag(1X)), and various demonstration clients (xeyes(1X), November, 1990 1
X(1X) X(1X)ico(1X), muncher(1X), and puzzle(1X)). The official names of the software described in this manual page are as follows: X X Window System X Version 11 X Window System, Version 11 X11 Note that the phrases X.11 X-11 X Windows are explicitly excluded from this list and should not be used to describe the X Window System. X Window System is a trademark of the Massachusetts Insti- tute of Technology. Display specification When you first log in, the environment variable DISPLAY is set to a string specifying the name of the machine on which the server is running, a number indicating which of possibly several servers to use, and a number indicating the default screen of the server (default 0). By convention, servers on a particular machine are numbered starting with 0. The for- mat of the DISPLAY string depends on the type of communica- tions channel used to contact the server. The following connection protocols are supported: TCP/IP DISPLAY should be of the form host:dpy.screen, where host is the symbolic name of the machine (for exam- ple, expo), dpy represents the number of the display (usually 0), and screen represents the number of the screen. The screen and preceding period are option- al, with 0 being the default. Full Internet domain names (for example, expo.lcs.mit.edu) are allowed as host names. TCP/IP connections are used by clients executing on remote hosts. UNIX domain DISPLAY should be set to unix:dpy.screen, where dpy is the display number and screen is the screen number; screen and the preceding period are option-ral, with the default value being 0. UNIX domainconnections are used by clients executing locally. 2 November, 1990
X(1X) X(1X)Most commands accept a command-line option of the form -display display that can be used to override the DISPLAY environment vari- able. Geometry specification One of the advantages of window systems over hardwired ter- minals is that applications need not be restricted to a par- ticular size or location on the screen. Although the layout of windows on a display is controlled by the window manager, most applications accept a command-line option for a pre- ferred window size and location for this particular applica- tion. This option, usually specified as -geometry WxH+X+Y, indi- cates that the window should have a width of W and height of H. Depending on the application, the unit of measurement can be pixels or characters. The argument then specifies that the upper-left corner should be placed X pixels to the right and Y pixels below the upper-left corner, or origin (0,0), of the screen. WxH can be omitted to obtain the default ap- plication size, or +X+Y can be omitted to obtain the default application position. The default window geometry is then determined by the window manager. You can use negative values for X and Y to position windows off the screen. In addition, if minus signs are used in- stead of plus signs (for example, WxH-X-Y), then (X,Y) represents the location of the lower-right corner of the window relative to the lower-right corner of the screen. By combining plus and minus signs, you can place the window relative to any of the four corners of the screen. For ex- ample 555x333+11+22 requests a window 555 pixels wide and 333 pixels tall, with the upper-left corner located at (11,22). The argument 300x200-0+0 requests a window measuring 300 by 200 pixels in the upper- right corner of the screen. The argument 48x48--5--10 requests a window measuring 48 by 48 pixels whose lower- right corner is 5 pixels from the right edge of the screen and 10 pixels from the bottom edge. November, 1990 3
X(1X) X(1X)Font names Collections of characters for displaying text and symbols in X are known as fonts. A font typically contains images that share a common appearance, for example, a single size, bold- ness, slant, and character set. Similarly, collections of fonts that are based on a common type face (variations are usually called roman, bold, italic, bold italic, oblique, and bold oblique) are called families. Sets of font families of the same resolution, usually meas- ured in dots per inch, are further grouped into directories, (so named because they were initially stored in file system directories). Each directory contains a database which lists the name of the font and information on how to find the font. The server uses these databases to translate font names (which have nothing to do with filenames) into font data. The list of font directories in which the server looks when trying to find a font is controlled by the font path. Although most installations choose to have the server start up with all commonly used font directories, the font path can be changed at any time with the xset(1X) command. How- ever, it is important to remember that the directory names are on the server's workstation, and not that of the appli- cation. The default font path for the sample server contains three directories: /usr/lib/X11/fonts/misc This directory contains several miscellaneous fonts that are useful on all systems. It contains a very small family of fixed-width fonts (6 x 10, 6 x 12, 6 x 13, 8 x 13, 8 x 13 bold, and 9 x 15) and the cur- sor font. It also has font name aliases for the commonly used fixed and variable fonts. /usr/lib/X11/fonts/75dpi This directory contains fonts contributed by Adobe Systems, Inc., Digital Equipment Corporation, and Bitstream, Inc. for 75-dot-per-inch displays. An integrated selected of sizes, styles, and weights are provided for each family. /usr/lib/X11/fonts/100dpi This directory contains 100-dot-per-inch versions of some of the fonts in the 75dpi directory. Font databases are created by running the mkfontdir command in the directory containing the source or compiled versions of the fonts (in both compressed and uncompressed formats). 4 November, 1990
X(1X) X(1X)Whenever fonts are added to a directory, mkfontdir should be rerun so that the server can find the new fonts. To make the server reread the font database, reset the font path with the xset(1X) command. For example, to add a font to a private directory, the following commands could be used: % cp newfont.snf ~/myfonts % mkfontdir ~/myfonts % xset fp rehash The xlsfonts(1X) command can be used to list all fonts found in font databases in the current font path. Font names tend to be fairly long, as they contain all information needed to uniquely identify individual fonts. However, the sample server supports wildcarding of font names, so the full specification of the font -adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1 can be abbreviated with wildcards as *-courier-medium-r-normal--*-100-* Because the shell also has special meanings for * and ?, wildcarded font names should be quoted: for example, xlsfonts -fn '*-courier-medium-r-normal--*-100-*' If more than one font in a given directory in the font path matches a wildcarded font name, the choice of which particu- lar font to return is left to the server. However, if fonts from more than one directory match a name, the returned font will always be from the first such directory in the font path. The example given above will match fonts in both the 75dpi and 100dpi directories; if the 75dpi directory is ahead of the 100dpi directory in the font path, the smaller version of the font will be used. Color names Most applications provide ways of tailoring (usually through resources or command-line options) the colors of various elements in the text and graphics they display. Although monochrome displays do not provide much choice, color displays frequently allow anywhere between 16 and 16 million different colors. Colors are usually specified by their commonly used names (for example, red, white, or medium slate blue). The server translates these names into appropriate screen colors using a color database that can usually be found in /usr/lib/X11/rgb.txt. Color names are not case-sensitive, November, 1990 5
X(1X) X(1X)meaning that red, Red, and RED all refer to the same color. Many applications also accept color specifications of the following form: #rgb #rrggbb #rrrgggbbb #rrrrggggbbbb where r, g, and b are hexadecimal numbers indicating how much red, green, and blue should be displayed (0 being none, and FFFF being full on). Each field in the specification must have the same number of digits (for example, #rrgb or #gbb are not allowed). Fields that have fewer than four di- gits (for example, #rgb) are padded with zeros following each digit (for example, #r000g000b000). The eight primary colors can be represented as: black #000000000000 (no color at all) red #ffff00000000 (full red) green #0000ffff0000 (full green) blue #00000000ffff (full blue) yellow #ffffffff0000 (full red and green, no blue) magenta #ffff0000ffff (full red and blue, no green) cyan #0000ffffffff (full green and blue, no red) white #ffffffffffff (full red, green, and blue) Unfortunately, red-green-blue (RGB) color specifications are highly unportable because different monitors produce dif- ferent shades when given the same inputs. Similarly, color names are not portable because there is no standard naming scheme and because the color database needs to be tuned for each monitor. Application developers should take care to make their colors tailorable. Keys The X keyboard model is broken into two layers: server- specific codes (called keycodes) which represent the physi- cal keys, and server-independent symbols (called keysyms) which represent the letters or words that appear on the keys. Two tables are kept in the server for converting key- codes to keysyms. modifier list Some keys (such as SHIFT, CONTROL, and CAPS LOCK) are known as modifier keys and are used to select different symbols that are attached to a single key (for example, a SHIFT-a generates a capital A, and CONTROL-l generates a formfeed character ^L). The 6 November, 1990
X(1X) X(1X)server keeps a list of keycodes corresponding to the various modifier keys. Whenever a key is pressed or released, the server generates an event that con- tains the keycode of the indicated key as well as a mask that specifies which of the modifier keys are currently pressed. Most servers set up this list to initially contain the various SHIFT, CONTROL, and CAPS LOCK keys on the keyboard. keymap table Applications translate event keycodes and modifier masks into keysyms using a table that contains one row for each keycode and one column for each of the modifiers. This table is initialized by the server to correspond to normal typewriter conventions, but it is only used by client applications. Although most client applications deal with keysyms directly (such as those written with the X Toolkit), most programming libraries provide routines for converting keysyms into the appropriate type of string (such as ISO Latin-1). However, client applications that use such routines are usually less portable and not as flexible. Command-line options Most X commands attempt to use a common set of names for their command-line options. The X Toolkit automatically handles the following options: -display display Specifies the name of the X server to be used. -geometry geometry Specifies the initial size and location of the win- dow. -bg color, -background color Either option specifies the color to be used as the window background. -bd color, -bordercolor color Either option specifies the color to be used as the window border. -bw width, -borderwidth number Either option specifies the window border width in pixels. -fg color, -foreground color Either option specifies the color to be used for text or graphics. November, 1990 7
X(1X) X(1X)-fn font, -font font Either option specifies the font to be used for displaying text. -iconic Indicates that the application should be initialized as an icon instead of as a full window. The iconic representation of the window is controlled by the window manager currently in use. -name Specifies the name under which resources for the ap- plication should be found. This option is useful in shell aliases to distinguish among invocations of an application, and eliminates the need for creating links to alter the executable filename. -rv, -reverse Either option indicates that the program should simulate reverse video if possible, often accom- plished by swapping the foreground and background colors. Not all programs support reverse video or implement it correctly. It is usually used only on monochrome screens. +rv Indicates that the program should not simulate re- verse video. This is used to override any existing defaults, particularly when reverse video is not working properly. -synchronous Indicates that requests to the X server should be sent synchronously, rather than asynchronously. Be- cause Xlib (the X function call library) normally buffers requests to the server, errors do not neces- sarily get reported immediately upon occurrence. This option disables the Xlib buffering so that the application can be debugged. It should not be used with a working program. -title string Specifies the title to be used for this window. This information is sometimes used by a window manager to provide a window header identification. -xrm resourcestring Specifies a resource name and value to override any defaults. It is also very useful for setting resources that do not have explicit command-line op- tions. 8 November, 1990
X(1X) X(1X)Resources To facilitate the tailoring of applications to personal preferences, X supports several mechanisms for storing pro- gram resource default values, such as those for background color, window title, or menu font. Resources are specified as strings of the form name * subname * subsubname ... : value (For further details about resources, refer to ``Customizing X11'' in X11 User's Guide for A/UX and ``Using the Resource Manager'' in Chapter 10, ``Application Utility Functions,'' in Xlib - C Language Interface.) These strings are loaded into a client upon initialization. The Xlib routine XGetDefault(3X) and the resource utilities within the X Toolkit obtain resources from the following sources: RESOURCE_MANAGER root window property Any global resources that should be available to clients on all machines should be stored in the RESOURCE_MANAGER property on the background window (also called the root window) using the xrdb com- mand. application-specific directory Any application- or machine-specific resources can be stored in the class resource files located in /usr/lib/X11/app-defaults. XENVIRONMENT You can indicate user- and machine-specific resources by setting the XENVIRONMENT environment variable to the name of a resource file to be loaded by all applications. If this variable is not de- fined, the X Toolkit looks for a file by the name of .Xdefaults-hostname, in which hostname is the name of the host where the application is executing. -xrm resourcestring Applications that use the X Toolkit can have resources specified from the command line. The resourcestring is a single resource name and value defined under ``Command-Line Options'' earlier in this section. If the string includes characters in- terpreted by the shell, for example, an asterisk (*), they must be contained within quotation marks. Any number of -xrm options can be specified on the command line. Program resources are organized into groups called classes, so that collections of individual instance resources can be set all at once. By convention, the instance name of a November, 1990 9
X(1X) X(1X)resource begins with a lowercase letter, and the class name begins with an uppercase letter. Multiple word resources are concatenated, with the first letter of the succeeding words capitalized. Applications written with the X Toolkit have at least the following resources: background (class Background) Specifies the color to be used as the window back- ground. borderWidth (class BorderWidth) Specifies the window border width in pixels. borderColor (class BorderColor) Specifies the color to be used in the window border. Most X Toolkit applications also have the resource foreground (class Foreground), specifying the color to be used for text and graphics within the window. By combining class and instance specifications, you can set application preferences quickly and easily. Users of color screens will frequently want to set Background and Fore- ground classes to particular defaults. Specific instances such as the color of text pointers can then be overridden without having to define all related resources. The follow- ing is an example of a resource specification file: bitmap*Dashed:off XTerm*cursorColor: gold XTerm*multiScroll: on XTerm*jumpScroll: on XTerm*reverseWrap: on XTerm*curses: on XTerm*Font: 6x10 XTerm*scrollBar: on XTerm*scrollbar*thickness: 5 XTerm*multiClickTime: 500 XTerm*charClass: 33:48,37:48,45-47:48,64:48 XTerm*cutNewline: off XTerm*cutToBeginningOfLine: off XTerm*titeInhibit: on XTerm*ttyModes: intr^c erase^?kill^u XLoad*Background:gold XLoad*Foreground:red XLoad*highlight:black XLoad*borderWidth:0 emacs*Geometry: 80x65-0-0 emacs*Background: #5b7868 emacs*Foreground: white emacs*Cursor: white emacs*BorderColor: white 10 November, 1990
X(1X) X(1X)emacs*Font: 6x10 xmag*geometry: -0-0 xmag*borderColor: white If these resources were stored in a file called .Xresources in your home directory, for example, they could be added to any existing resources in the server with the following com- mand: xrdb -merge $HOME/.Xresources This is frequently how user-friendly startup scripts merge user-specific defaults into any site-wide defaults. See the ``Using the Resource Manager'' in Chapter 10, ``Application Utility Functions,'' in Xlib - C Language Interface for more information. EXAMPLES The following is a collection of sample command lines for some of the more frequently used commands. For more infor- mation on a particular command, please refer to that command's manual page. xrdb -load $HOME/.Xresources xmodmap -e "keysym BackSpace=Delete" mkfontdir /usr/local/lib/X11/otherfonts xset fp +/usr/local/lib/X11/otherfonts xmodmap $HOME/.keymap.km xsetroot -solid '#888' xset b 100 400 c 50 s 1800 r on xset q xmag xclock -geometry 48x48-0+0 -bg blue -fg white xeyes -geometry 48x48-48+0 xbiff -update 20 xlsfonts '*helvetica*' xlswins -l xwininfo -root xdpyinfo -display joesworkstation:0 xhost -joesworkstation xrefresh xwd|xwud bitmap companylogo.bm 32x32 xcalc -bg blue -fg magenta xterm -geometry 80x66-0-0 -name myxterm $* LIMITATIONS If you encounter a repeatable bug, please contact your site administrator for instructions on how to submit an X Bug Re- port. November, 1990 11
X(1X) X(1X)DIAGNOSTICS A wide variety of error messages are generated from various programs. Various toolkits are encouraged to provide a com- mon mechanism for locating error text so that applications can be tailored easily. Programs written to interface directly to the Xlib C language library are expected to do their own error checking. The default error handler in Xlib (also used by many toolk- its) uses standard resources to construct diagnostic mes- sages when errors occur. The defaults for these messages are usually stored in the file XErrorDB in the /usr/lib/X11 directory. If this file is not installed, error messages will tend to be somewhat cryptic. When the X Toolkit encounters errors converting resource strings to the appropriate internal format, usually no error messages will be printed. This is convenient when it is desirable to have one set of resources across a variety of displays (for example, color versus monochrome, many fonts versus very few fonts, and so forth), although it can pose problems when trying to determine why an application is failing. This behavior can be overridden by setting the StringConversionsWarning resource. To force the Toolkit to always print string conversion error messages, the following resource should be placed at the top of the file that gets loaded onto the RESOURCE_MANAGER pro- perty using the xrdb(1X) command (frequently called .Xresources or .Xres in the user's home directory): *StringConversionWarnings:on To have conversion messages printed for just a particular application, the appropriate instance name can be placed be- fore the asterisk: xterm*StringConversionWarnings:on NOTES The following copyright and permission notice outlines the rights and restrictions covering most parts of the standard distribution of the X Window System from MIT. Other parts have additional or different copyrights and permissions; see the individual source files. Copyright 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991 Massachusetts Institute of Technology and Apple Computer, Inc. 12 November, 1990
X(1X) X(1X)Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright no- tice appear in all copies and that both that copyright no- tice and this permission notice appear in supporting docu- mentation, and that the name of MIT not be used in advertis- ing or publicity pertaining to distribution of the software without specific, written prior permission. MIT makes no representations about the suitability of this software for any purpose. It is provided ``as is'' without express or implied warranty. This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California. SEE ALSO bitmap(1X), ico(1X), mkfontdir(1X), muncher(1X), plaid(1X), puzzle(1X), twm(1X), xbiff(1X), xcalc(1X), xclock(1X), xdpyinfo(1X), xedit(1X), xev(1X), xfd(1X), xhost(1X), xinit(1X), xkill(1X), xload(1X), xlogo(1X), xlsfonts(1X), xlswins(1X), XmacII(1X), xmag(1X), xmodmap(1X), xpr(1X), xprop(1X), xrdb(1X), xrefresh(1X), xset(1X), xsetroot(1X), xterm(1X), xwd(1X), xwininfo(1X), xwud(1X) X11 User's Guide for A/UX Xlib - C Language Interface X Toolkit Intrinsics - C Language Interface November, 1990 13