'\"macro stdmacro
.if n .pH g1.x @(#)x	40.3 of 1/9/90
.nr X
.if \nX=0 .ds x} X 1 "9/1/88" "X\s-2WIN\s+2 3.0" "\&"
.if \nX=1 .ds x} X 1 "9/1/88" "X\s-2WIN\s+2 3.0"
.if \nX=2 .ds x} X 1 "" "\&"
.if \nX=3 .ds x} X "" "" "\&"
.TH \*(x}
.tr ~
.SH NAME
X - a portable, network transparent window system
.SH SYNOPSIS
.PP
X is a network transparent window system developed at MIT which runs on a wide
range of computing and graphics machines.  
.sp
.SH DESCRIPTION
.PP
X window system servers run on computers with bitmap displays.
The server distributes user input to and accepts output requests from various
client programs through a variety of different interprocess
communication channels.  Although the most common case is for the client
programs to be
running on the same machine as the server, clients can be run transparently
from other machines (including machines with different architectures and
operating systems) as well.
.PP
X supports overlapping hierarchical subwindows and text and
graphics operations, on both monochrome and color
displays.
For a full explanation of the functions that are available, see
the \fIXlib - C Language X Interface\fP manual, 
the \fIX Window System Protocol\fP specification,
and various toolkit documents.
.PP
The number of programs that use \fIX\fP is growing rapidly.  Of particular
interest are:
a terminal emulator (\fIxterm\fP),
a window manager (\fIolwm\fP), 
a bitmap editor (\fIbitmap\fP),
an access control program (\fIxhost\fP),
user preference setting programs (\fIxrdb\fP, \fIxset\fP, \fIxsetroot\fP,
and \fIxmodmap\fP),
a clock (\fIxclock\fP),
a font displayer (\fIxfd\fP),
utilities for listing information about fonts, windows, and displays
(\fIxlsfonts\fP, \fIxdpyinfo\fP, 
and \fIxprop\fP),
a diagnostic for seeing what events are generated and when (\fIxev\fP),
screen image manipulation utilities (\fIxwd\fP, \fIxwud\fP, \fIxpr\fP, 
and \fIxmag\fP),
and various demos (\fIxeyes\fP, \fIico\fP, \fImuncher\fP, \fIpuzzle\fP, etc.).
.SH STARTING UP
.PP 
.B "\fIxinit\fP (run manually from the shell)"
.PP
Sites that support more than one window system might choose to use the
\fIxinit\fP program for starting X manually.  If this is true for your 
machine, your site administrator will probably have provided a program 
named "x11", "startx", or "xstart" that will do site-specific initialization
(such as loading convenient default resources, running a window manager, 
displaying a clock, and starting several terminal emulators) in a nice
way.  If not, you can build such a script using the \fIxinit\fP program.
This utility simply runs one user-specified program to start the server,
runs another to start up any desired clients, and then waits for either to
finish.  Since either or both of the user-specified programs may be a shell 
script, this gives substantial flexibility at the expense of a
nice interface.  For this reason, \fIxinit\fP is not intended for end users.
.SH "DISPLAY NAMES"
.PP
When you first log in, the environment variable DISPLAY should be 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 possibly
a number indicating the default screen of the server (usually this is
omitted and defaults to 0). By convention, servers on a particular
machine are numbered starting with zero. The format of the DISPLAY string
depends on the type of communications channel used to contact the server,
and is used by the application to determine how it should
connect to the server and which screen it should use by default
(on displays with multiple monitors):
.TP 8
.I hostname
The \fIhostname\fP specifies the name of the machine to which the display is
physically connected.  
When you log into another
machine on a network, you'll need to set DISPLAY by hand to point to your
display.  For example,
.sp
.in +8
.nf
$ DISPLAY=myws:0; export DISPLAY
.fi
.in -8
.PP
.SH "GEOMETRY SPECIFICATIONS"
One of the advantages of using window systems instead of
hardwired terminals is that 
applications don't have to be restricted to a particular size or location
on the screen.
Although the layout of windows on a display is controlled
by the window manager that the user is running, 
most X programs accept
a command line argument of the form \fB-geometry \fIWIDTHxHEIGHT+XOFF+YOFF\fR
where \fIWIDTH\fP, \fIHEIGHT\fP, \fIXOFF\fP, and \fIYOFF\fP are numbers)
for specifying a prefered size and location for this application's main
window.
.PP
The \fIWIDTH\fP and \fIHEIGHT\fP parts of the geometry specification are
usually measured in either pixels or characters, depending on the application.
The \fIXOFF\fP and \fIYOFF\fP parts are measured in pixels and are used to
specify the distance of the window from the left or right and top and bottom
edges of the screen, respectively.  Both types of offsets are measured from the
indicated edge of the screen to the corresponding edge of the window.  The X
offset may be specified in the following ways:
.TP 8
.I +XOFF
The left edge of the window is to be placed \fIXOFF\fP pixels in from the
left edge of the screen (i.e. the X coordinate of the window's origin will be 
\fIXOFF\fP).  \fIXOFF\fP may be negative, in which case the window's left edge 
will be off the screen.
.TP 8
.I -XOFF
The right edge of the window is to be placed \fIXOFF\fP pixels in from the
right edge of the screen.  \fIXOFF\fP may be negative, in which case the 
window's right edge will be off the screen.
.PP
The Y offset has similar meanings:
.TP 8
.I +YOFF
The top edge of the window is to be \fIYOFF\fP pixels below the
top edge of the screen (i.e. the Y coordinate of the window's origin will be
\fIYOFF\fP).  \fIYOFF\fP may be negative, in which case the window's top edge 
will be off the screen.
.TP 8
.I -YOFF
The bottom edge of the window is to be \fIYOFF\fP pixels above the
bottom edge of the screen.  \fIYOFF\fP may be negative, in which case 
the window's bottom edge will be off the screen.
.PP
Offsets must be given as pairs; in other words, in order to specify either
\fIXOFF\fP or \fIYOFF\fP both must be present.  Windows can be placed in the
four corners of the screen using the following specifications:
.TP 8
.I +0+0
upper left hand corner.
.TP 8
.I -0+0
upper right hand corner.
.TP 8
.I -0-0
lower right hand corner.
.TP 8
.I +0-0
lower left hand corner.
.PP
In the following examples, a terminal emulator will be placed in roughly
the center of the screen and
mailbox, and clock will be placed in the upper right 
hand corner:
.sp
.nf
        xterm -fn 6x10 -geometry 80x24+30+200 &
        xclock -geometry 48x48-0+0 &
        xbiff -geometry 48x48-48+0 &
.fi
.PP
.SH WINDOW MANAGERS
The layout of windows on the screen is controlled by special programs called
\fIwindow managers\fP.  Although many window managers will honor geometry
specifications as given, others may choose to ignore them (requiring the user
to explicitly draw the window's region on the screen with the pointer, for 
example).
.SH "FONT NAMES"
Collections of characters for displaying text and symbols in X are known as
\fIfonts\fP.  A font typically contains images that share a common appearance
and look nice together (for example, a single size, boldness, slant, and
character set).  Similarly, collections of fonts that are based on a common
type face (the variations are usually called roman, bold, italic, bold italic, 
oblique, and bold oblique) are called \fIfamilies\fP.  
.PP
Sets of 
font families of the same resolution (usually measured in dots per inch) 
are further grouped into \fIdirectories\fP
(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 \fIfont names\fP (which have nothing to do with
file names) into font data.
.PP
The list of font directories in which the server looks when trying to find
a font is controlled by the \fIfont path\fP.  
The font path can be changed at any time with the \fIxset\fP
program.  However, it is important to remember that the directory names are
on the \fBserver\fP's machine, not on the application's.
.PP
The default font path for
the server contains three directories:
.TP 8
.I /usr/lib/X11/fonts/misc
This directory contains several miscellaneous fonts that are useful on all
systems.  It contains a family of fixed-width fonts (\fB6x10\fP, 
\fB6x12\fP, \fB6x13\fP, \fB8x13\fP, \fB8x13bold\fP, and \fB9x15\fP) and the
cursor font.  It also has font name aliases for the commonly used fonts
\fBfixed\fP and \fBvariable\fP. The X11R2 fonts are also found in this
directory.
.TP 8
.I /usr/lib/X11/fonts/75dpi
This directory contains fonts contributed by Adobe Systems, Inc. and
Digital Equipment Corporation and by Bitstream, Inc.
for 75 dots per inch displays.  An integrated selection of sizes, styles, 
and weights are provided for each family.
.TP 8
.I /usr/lib/X11/fonts/100dpi
This directory contains 100 dots per inch versions of some of the fonts in the 
\fI75dpi\fP directory.  
.PP
An additional directory, /usr/lib/X11/fonts/Xol,  contains the OPEN LOOK 
fonts. This directory is
not part of the server's default font path, but can be set using the
XWINFONTPATH environment variable. The XWINFONTPATH is an environment
variable that should be set to the full pathname of the directories that
should be part of the server's default font path. This variable should
be exported. For example, to include the OPEN LOOK fonts in the server's
default font path put the following commands in a startup file:
.TP 8
XWINFONTPATH=/usr/lib/X11/fonts/Xol,/usr/lib/X11/fonts/misc/,/usr/lib/
              X11/fonts/ 75dpi/,/usr/lib/X11/fonts/100dpi
.br
export XWINFONTPATH
.PP
Both the default font path and the XWINFONTPATH environment variable can
be overrode by using a command line argument when starting the server.
.PP
Font databases are created by running the \fImkfontdir\fP program in the
directory containing the compiled versions of the fonts.
Whenever fonts are added to a directory, \fImkfontdir\fP 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 \fIxset\fP program.  For example,
to add a font to a private directory, the following commands could be used:
.sp
.nf
        $  cp newfont.snf /mydir/myfonts
        $  mkfontdir /mydir/myfonts
        $  xset fp+ /mydir/myfonts 
        $  xset fp rehash 
.fi
.PP
The \fIxlsfonts\fP program can be used to list all of the fonts that are
found in font databases in the current font path.  
Font names tend to be fairly long as they contain all of the information
needed to uniquely identify individual fonts.  However, the sample server
supports wildcarding of font names, so the full specification
.sp
.ce 1
\fI-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1\fP
.sp
could be abbreviated as:
.sp
.ce 1
\fI*-courier-medium-r-normal--*-100-*\fP
.PP
Because the shell also has special meanings for \fI*\fP and \fI?\fP,
wildcarded font names should be quoted:
.sp
.nf
        $  xlsfonts -fn '*-courier-medium-r-normal--*-100-*'
.fi
.PP
If a trailing blank is part of
the font name, then the font name must be quoted. 
When in doubt quote the font names. 
If more than one font in a given directory in the font path matches a
wildcarded font name, the choice of which particular 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 \fI75dpi\fP and
\fI100dpi\fP directories; if the \fI75dpi\fP directory is ahead of the
\fI100dpi\fP directory in the font path, the smaller version of the font will 
be used.  
.SH "COLOR NAMES"
Most applications provide ways of tailoring (usually through resources or
command line arguments) the colors of various elements
in the text and graphics they display.  Although black and white displays
don't provide much of a choice, color displays frequently allow anywhere
between 16 and 16 million different colors.  
.PP
Colors are usually specified by their commonly-used names
(for example, \fIred\fP, \fIwhite\fP, or \fImedium slate blue\fP).
The server translates these names into appropriate screen 
colors using
a color database that can usually be found 
in \fI/usr/lib/X11/rgb.<display_type>.txt\fP, 
where display_type is either ega, vga, or mtg.
Color names are case-insensative, meaning that \fIred\fP, \fIRed\fP, 
and \fIRED\fP all refer to the same color.  
.PP
Many applications also accept color specifications of the following form:
.sp
.ce 4
#rgb
#rrggbb
#rrrgggbbb
#rrrrggggbbbb
.sp
where \fIr\fP, \fIg\fP, and \fIb\fP are hexidecimal numbers indicating how
much \fIred\fP, \fIgreen\fP, and \fIblue\fP should be displayed (zero being
none and ffff being on full).  Each field
in the specification must have the same number of digits (e.g., #rrgb or
#gbb are not allowed).  Fields that have fewer than four digits (e.g. #rgb)
are padded out with zero's following each digit (e.g. #r000g000b000).  The
eight primary colors can be represented as:
.sp
.ta 1.25in
.in +8
.nf
black	#000000000000 (no color at all)
red	#ffff00000000
green	#0000ffff0000
blue	#00000000ffff
yellow	#ffffffff0000 (full red and green, no blue)
magenta	#ffff0000ffff
cyan	#0000ffffffff
white	#ffffffffffff (full red, green, and blue)
.fi
.in -8
.PP
Unfortunately, RGB color specifications are highly unportable since different
monitors produce different shades when given the same inputs.  Similarly,
color names aren't portable because there is no standard naming scheme and 
because the color database needs to be tuned for each monitor.
.PP
Application developers should take care to make their colors tailorable.
.SH "KEYS"
.PP
The X keyboard model is broken into two layers:  server-specific codes
(called \fIkeycodes\fP) which represent the physical keys, and 
server-independent symbols (called \fIkeysyms\fP) which
represent the letters or words that appear on the keys.  
Two tables are kept in the server for converting keycodes to keysyms:
.TP 8
.I "modifier list"
Some keys (such as Shift, Control, and Caps Lock) are known as \fImodifier\fP
and are used to select different symbols that are attached to a single key
(such as Shift-a generates a capital A, and Control-l generates a formfeed
character ^L).  The server keeps a list of keycodes corresponding to the
various modifier keys.  Whenever a key is pressed or released, the server 
generates an \fIevent\fP that contains the keycode of the indicated key as 
well as a mask that specifies which of the modifer keys are currently pressed.
Most servers set up this list to initially contain
the various shift, control, and shift lock keys on the keyboard.  
.TP 8
.I "keymap table"
Applications translate event keycodes and modifier masks into keysyms
using a \fIkeysym table\fP which 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 is only used by
client programs.  
.PP
Although most programs 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,
programs that use such routines are usually less portable and not as flexible.
.SH "OPTIONS"
Most X programs attempt to use the same names for command line options and
arguments.  All applications written with the X Toolkit automatically accept
the following options:
.TP 8
.B \-display \fIdisplay\fP
This option specifies the name of the X server to use.
.TP 8
.B \-geometry \fIgeometry\fP
This option specifies the initial size and location of the window.
.TP 8
.B \-bg \fIcolor\fP, \fB\-background \fIcolor\fP
Either option specifies the color to use for the window background.
.TP 8
.B \-bd \fIcolor\fP, \fB\-bordercolor \fIcolor\fP
Either option specifies the color to use for the window border.
.TP 8
.B \-bw \fInumber\fP, \fB\-borderwidth \fInumber\fP
Either option specifies the width in pixels of the window border.
.TP 8
.B \-fg \fIcolor\fP, \fB\-foreground \fIcolor\fP
Either option specifies the color to use for text or graphics.
.TP 8
.B \-fn \fIfont\fP, \fB-font \fIfont\fP
Either option specifies the font to use for displaying text.
.TP 8
.B \-iconic
.br
This option indicates that the user would prefer that the application's
windows initially not be visible as if the windows had be immediately 
iconified by the user.  Window managers may choose not to honor the
application's request.  
.TP 8
.B \-name
.br
This option specifies the name under which resources for the
application should be found.  This option is useful in shell
aliases to distinguish between invocations of an application,
without resorting to creating links to alter the executable file name.
.TP 8
.B \-rv\fP, \fB\-reverse\fP
Either option indicates that the program should simulate reverse video if 
possible, often by swapping the foreground and background colors.  Not all
programs honor this or implement it correctly.  It is usually only used on
monochrome displays.
.TP 8
.B \+rv
.br
This option indicates that the program should not simulate reverse video.  
This is used to
override any defaults since reverse video doesn't always work properly.
.TP 8
.B \-synchronous
This option indicates that requests to the X server should be sent 
synchronously, instead of asynchronously.  Since 
.I Xlib
normally buffers requests to the server, errors do not necessarily get reported
immediately after they occur.  This option turns off the buffering so that
the application can be debugged.  It should never be used with a working 
program.
.TP 8
.B \-title \fIstring\fP
This option specifies the title to be used for this window.  This information 
is sometimes
used by a window manager to provide some sort of header identifying the window.
.TP 8
.B \-xrm \fIresourcestring\fP
This option specifies a resource name and value to override any defaults.  It 
is also very useful for setting resources that don't have explicit command 
line arguments.
.SH "RESOURCES"
To make the tailoring of applications to personal preferences easier, X 
supports several mechanisms for storing default values for program resources 
(e.g. background color, window title, etc.)
Resources are specified as strings of the form 
.sp
.ce 1
\fIname*subname*subsubname...: value\fP
.sp
that are read in from various places when an application is run.
The \fIXlib\fP routine
.I XGetDefault(3X)
and the resource utilities within the X Toolkit
obtain resources from the following sources:
.TP 8
.B "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
root window using the \fIxrdb\fP program.  This is frequently taken care
of when the user starts up X through the display manager or \fIxinit\fP.
.TP 8
.B "application-specific files"
Any application- or machine-specific resources can be stored in
the class resource files located in the XAPPLOADDIR directory (this is a 
configuration parameter that is /usr/lib/X11/app-defaults in the 
standard distribution). 
.TP 8
.B XENVIRONMENT
Any user- and machine-specific resources may be specified by setting
the XENVIRONMENT environment variable to the name of a resource file
to be loaded by all applications.  If this variable is not defined,
the X Toolkit looks for a file named .Xdefaults or .Xdefaults-\fIhostname\fP,
where \fIhostname\fP is the name of the host where the application
is executing.
.TP 8
.B \-xrm \fIresourcestring\fP
Applications that use the X Toolkit can have resources specified from the 
command line.  The \fIresourcestring\fP is a single resource name and value as
shown above.  Note that if the string contains characters interpreted by
the shell (e.g., asterisk), they must be quoted.
Any number of \fB\-xrm\fP arguments may be given on the
command line.
.PP
Program resources are organized into groups called \fIclasses\fP, so that 
collections of individual resources (each of which are 
called \fIinstances\fP)
can be set all at once.  By convention, the instance name of a resource
begins with a lowercase letter and class name with an upper case letter.
Multiple word resources are concatentated with the first letter of the 
succeeding words capitalized.  Applications written with the X Toolkit
will have at least the following resources:
.PP
.TP 8
.B background (\fPclass\fB Background)
This resource specifies the color to use for the window background.
.PP
.TP 8
.B borderWidth (\fPclass\fB BorderWidth)
This resource specifies the width in pixels of the window border.
.PP
.TP 8
.B borderColor (\fPclass\fB BorderColor)
This resource specifies the color to use for the window border.
.PP
Most X Toolkit applications also have the resource \fBforeground\fP
(class \fBForeground\fP), specifying the color to use for text
and graphics within the window.
.PP
By combining class and instance specifications, application preferences 
can be set quickly and easily.  Users of color displays will frequently
want to set Background and Foreground classes to particular defaults.
Specific color instances such as text cursors can then be overridden
without having to define all of the related resources.  For example,
.sp
.nf
        bitmap*Dashed:  off
        xterm*cursorColor:  gold
        xterm*multiScroll:  on
        xtermX*jumpScroll:  on
        xterm*Font:  6x10
        xterm*scrollBar: on
        xmag*geometry: -0-0
        xmag*borderColor:  white
.fi
.PP
If these resources were stored in a file called \fI.Xresources\fP in your home
directory, they could be added to any existing resources in the server with
the following command:
.sp
.nf
        $  xrdb -merge $HOME/.Xresources
.fi
.sp
This is frequently how user-friendly startup scripts merge user-specific 
defaults
into any site-wide defaults. 
.SH "EXAMPLES"
The following is a collection of sample command lines for some of the 
more frequently used commands.  For more information on a particular command,
please refer to that command's manual page.
.sp
.nf
        $  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 q
        $  xset fp- /usr/local/lib/X11/otherfonts/
        $  xmag
        $  xclock -geometry 48x48-0+0 -bg blue -fg white
        $  xeyes -geometry 48x48-48+0
        $  xbiff -update 20 
        $  xlsfonts '*helvetica*'
        $  xlswins -l
        $  xdpyinfo -display joesworkstation:0
        $  xhost -joesworkstation
        $  xrefresh
        $  xwd | xwud
        $  xcalc -bg blue -fg magenta
        $  xterm -geometry 80x66-0-0 -name myxterm $*
.fi
.SH DIAGNOSTICS
A wide variety of error messages are generated from various programs.  Various
toolkits are encouraged to provide a common mechanism for locating error 
text so that applications can be tailored easily.  Programs written
to interface directly
to the \fIXlib\fP C language library are expected to do their own error
checking.
.PP
The default error handler in \fIXlib\fP (also used by many toolkits) uses
standard resources to construct diagnostic messages when errors occur.  The
defaults for these messages are usually stored in \fI/usr/lib/X11/XErrorDB\fP.
If this file is not present, error messages will be rather terse and cryptic.
.PP
When the X Toolkit encounters errors converting resource strings to the
appropriate internal format, no error messages are usually printed.  This is
convenient when it is desirable to have one set of resources across a variety
of displays (e.g. color vs. monochrome, lots of fonts vs. very few, etc.),
although it can pose problems for trying to determine why an application might
be failing.  This behavior can be overridden by the setting the
\fIStringConversionsWarning\fP resource.
.PP
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 property
using the \fIxrdb\fP program (frequently called \fI.Xresources\fP
or \fI.Xres\fP in the user's home directory):
.sp
.nf
        *StringConversionWarnings: on
.fi
.sp
To have conversion messages printed for just a particular application,
the appropriate instance name can be placed before the asterisk:
.sp
.nf
        xterm*StringConversionWarnings: on
.fi
.SH BUGS
If you encounter a \fBrepeatable\fP bug, please contact your site 
administrator for instructions on how to submit an X Bug Report.
.SH "SEE ALSO"
.PP
Xserver(1),
mkfontdir(1),
bitmap(1), xbiff(1), xcalc(1), xclock(1),
xdpyinfo(1), xedit(1), xev(1), xfd(1), xhost(1), xinit(1), xkill(1),
xlogo(1), xlsfonts(1), xlswins(1), xmag(1), xmodmap(1),
xpr(1), xprop(1), xrdb(1), xrefresh(1), xset(1), xsetroot(1),
xterm(1), xwd(1), xwud(1),
bdftosnf(1),
.I "Xlib \- C Language X Interface\fR,\fP"
.I "X Toolkit Intrinsics - C Language X Interface\fR,\fP"
and
.I "Using and Specifying X Resources"
.SH COPYRIGHT
.sp
Copyright 1984, 1985, 1986, 1987, 1988, Massachusetts Institute of 
Technology.


