>xterm - terminal emulator for X
"tersified" by Dennis German
This manual page is for Mac OS X version 10.7.4
xterm [-toolkitoption ...] [-option ...] [shell]
provides DEC VT102/VT220
(VTxxx) and Tektronix 4014 compatible terminals for programs that cannot use the window system
directly. If the underlying operating system supports terminal resizing capabilities (for example,
the SIGWINCH signal in systems derived from 4.3bsd), xterm will use the facilities to notify programs
running in the window whenever it is resized.
displayed properly if your font server supports scalable fonts. The VT220 emulation does not support
soft fonts, it is otherwise complete. Termcap(5) entries that work with xterm include an optional
platform-specific entry, "xterm," "vt102," "vt100," "ansi" and "dumb." xterm automatically searches
the termcap file in this order for these entries and then sets the "TERM" and the "TERMCAP" environ-
ment variables. You may also use "vt220," but must set the terminal emulation level with the
decTerminalID resource. (The "TERMCAP" environment variable is not set if xterm is linked against a
terminfo library, since the requisite information is not provided by the termcap emulation of ter-
Many of the special xterm features may be modified under program control through a set of escape
sequences different from the standard VT102 escape sequences. (See the Xterm Control Sequences docu-
Tektronix 4014 emulation is also fairly good. It supports 12-bit graphics addressing, scaled to
the window size. Four different font sizes and five different lines types are supported. There is
no write-through or defocused mode support. The Tektronix text and graphics commands are recorded
internally by xterm and may be written to a file by sending the COPY escape sequence (or through the
Tektronix menu; see below). The name of the file will be "COPYyyyy-MM-dd.hh:mm:ss", where yyyy, MM,
dd, hh, mm and ss are the year, month, day, hour, minute and second when the COPY was performed (the
file is created in the directory xterm is started in, or the home directory for a login xterm).
Not all of the features described in this manual are necessarily available in this version of xterm.
Some (e.g., the non-VT220 extensions) are available only if they were compiled in, though the most
commonly-used are in the default configuration.
Xterm automatically highlights the text cursor when the pointer enters the window (selected) and
unhighlights it when the pointer leaves the window (unselected). If the window is the focus window,
then the text cursor is highlighted no matter where the pointer is.
In VT102 mode, there are escape sequences to activate and deactivate an alternate screen buffer,
which is the same size as the display area of the window. When activated, the current screen is
saved and replaced with the alternate screen. Saving of lines scrolled off the top of the window is
disabled until the normal screen is restored. The termcap(5) entry for xterm allows the visual edi-
tor vi(1) to switch to the alternate screen for editing and to restore the screen on exit. A popup
menu entry makes it simple to switch between the normal and alternate screens for cut and paste.
In either VT102 or Tektronix mode, there are escape sequences to change the name of the windows.
Additionally, in VT102 mode, xterm implements the window-manipulation control sequences from dtterm,
such as resizing the window, setting its location on the screen.
Xterm allows character-based applications to receive mouse events (currently button-press and release
events, and button-motion events) as keyboard control sequences. See Xterm Control Sequences for
The xterm terminal emulator accepts the standard X Toolkit command line options as well as many
application-specific options. If the option begins with a `+' instead of a `-', the option is
restored to its default value. The -version and -help options are interpreted even if xterm cannot
open the display, and are useful for testing and configuration scripts:
This causes xterm to print a version number to the standard output.
-help standard output. Xterm generates this message, sorting it and noting whether a "-option" or a "+option" turns the feature on or off, since some features historically have been one or the other. Xterm generates a concise help message (multiple
options per line) when an unknown option is used, e.g.,
If the logic for a particular option such as logging is not compiled into xterm, the help
text for that option also is not displayed by the -help option.
One parameter (after all options) may be given. That overrides xterm's built-in choice of shell pro-
gram. Normally xterm checks the SHELL variable. If that is not set, xterm tries to use the shell
program specified in the password file. If that is not set, xterm uses /bin/sh. If the parameter
names an executable file, xterm uses that instead. The parameter must be an absolute path, or name a
file found on the user's PATH (and thereby construct an absolute path). The -e option cannot be used
with this parameter since it uses all parameters following the option.
|Normally, the VT102 DECCOLM escape sequence that switches between 80 and 132 column mode is
ignored. causes the DECCOLM escape sequence to be recognized, and the xterm win-
dow will resize appropriately.
| always highlight the text cursor. By default, xterm
will display a hollow text cursor whenever the focus is lost or the pointer leaves the win-
| do text cursor highlighting based on focus.
|disables active icon support if that feature was compiled into xterm. This is
equivalent to setting the vt1__ resource activeIcon to "false".
|enables active icon support if that feature was compiled into xterm. This is
equivalent to setting the vt1__ resource activeIcon to "true".
| auto-wraparound should be allowed. This allows the cursor to
automatically wrap to the beginning of the next line when it is at the rightmost position of
a line and text is output.
|auto-wraparound should not be allowed.
the size of the inner border (the distance between the outer edge of
the characters and the window border) in pixels. That is the vt1__ internalBorder resource.
The default is 2.
|turn off text cursor blinking. This overrides the cursorBlink resource.
| turn on text cursor blinking. This overrides the cursorBlink resource.
| set the amount of time text cursor is off when blinking via the cursorOffTime resource.
| set the amount of time text cursor is on when blinking via the cursorOffTime resource.
|c Set the vt1__ resource colorBDMode to "false", disabling the display of characters with bold
attribute as color
| Set the vt1__ resource colorBDMode to "true", enabling the display of characters with bold
attribute as color rather than bold
| Set the vt1__ resource cutToBeginningOfLine to "false".
| Set the vt1__ resource cutToBeginningOfLine to "true".
| This sets classes indicated by the given ranges for using in selecting by words. See the
section specifying character classes. and discussion of the charClass resource.
| Set the cjkWidth resource to "true". When turned on, characters with East Asian Ambiguous
(A) category in UTR 11 have a column width of 2. Otherwise, they have a column width of 1.
This may be useful for some legacy CJK text terminal-based programs assuming box drawings and
others to have a column width of 2. It also should be turned on when you specify a TrueType
CJK double-width (bi-width/monospace) font either with -fa at the command line or faceName
resource. The default is "false"
| Reset the cjkWidth resource.
| allows you to override xterm's resource class. Normally it is "XTerm", but can
be set to another class such as "UXTerm" to override selected resources.
|disables recognition of ANSI color-change escape sequences. It sets the color-
Mode resource to "false".
| enables recognition of ANSI color-change escape sequences. This is the same as
the vt1__ resource colorMode.
|newlines should not be cut in line-mode selections. It sets the
cutNewline resource to "false".
|newlines should be cut in line-mode selections. It sets the cut-
Newline resource to "true".
| the color to use for text cursor. The default is to use the same fore-
ground color that is used for text. It sets the cursorColor resource according to the param-
| work around a bug in the more(1) program that causes
it to incorrectly display lines that are exactly the width of the window and are followed by
a line beginning with a tab (the leading tabs are not displayed). is so named
because it was originally thought to be a bug in the curses(3x) cursor motion package.
| not work around the more(1) bug mentioned above.
| disables the escape sequence to change dynamic colors: the vt100 foreground and
background colors, its text cursor color, the pointer cursor foreground and background col-
ors, the Tektronix emulator foreground and background colors, its text cursor color and high-
light color. The option sets the dynamicColors option to "false".
| enables the escape sequence to change dynamic colors. The option sets the dynam-
icColors option to "true".
-e program [ arguments ... ]
| the program (and its command line arguments) to be run in the xterm
window. It also sets the window title and icon name to be the basename of the program being
executed if neither -T nor -n are given on the command line. This must be the last option on
the command line.
| determines the encoding on which xterm runs. It sets the locale resource.
Encodings other than UTF-8 are supported by using luit. The -lc option should be used
instead of -en for systems with locale support.
| a font to be used when displaying bold text. It sets the boldFont
This font must be the same height and width as the normal font, otherwise it is ignored. If
only one of the normal or bold fonts is specified, it will be used as the normal font and the
bold font will be produced by overstriking this font.
See also the discussion of boldMode and alwaysBoldMode resources.
| sets the pattern for fonts selected from the FreeType library if support for that
library was compiled into xterm. This corresponds to the faceName resource. When a CJK dou-
ble-width font is specified, you also need to turn on the cjkWidth resource.
See also the renderFont resource, which combines with this to determine whether FreeType
fonts are initially active.
| compare normal and bold fonts bounding boxes to
ensure they are compatible. It sets the freeBoldBox resource to "false".
| not compare normal and bold fonts bounding boxes to
ensure they are compatible. It sets the freeBoldBox resource to "true".
| not assume that the normal and bold fonts have VT100
line-drawing characters. If any are missing, xterm will draw the characters directly. It
sets the forceBoxChars resource to "false".
| assume that the normal and bold fonts have VT100
line-drawing characters. It sets the forceBoxChars resource to "true".
| sets the pattern for double-width fonts selected from the FreeType library if
support for that library was compiled into xterm. This corresponds to the faceNameDoublesize
| sets the font for active icons if that feature was compiled into xterm.
See also the discussion of the iconFont resource.
| sets the pointsize for fonts selected from the FreeType library if support for
that library was compiled into xterm. This corresponds to the faceSize resource.
| ask the window manager to let it use the full-screen
for display, e.g., without window decorations. It sets the fullscreen resource to "true".
| not ask the window manager to let it use the full-
screen for display. It sets the fullscreen resource to "false".
| the font to be used for displaying wide text. By default, it will
attempt to use a font twice as wide as the font that will be used to draw normal text. If no
double-width font is found, it will improvise, by stretching the normal font. This corre-
sponds to the wideFont resource.
|the font to be used for displaying bold wide text. By default, it will
attempt to use a font twice as wide as the font that will be used to draw bold text. If no
double-width font is found, it will improvise, by stretching the bold font. This corresponds
to the wideBoldFont resource.
|the font to be used for displaying the preedit string in the "OverTheS-
pot" input method.
See also the discussion of the ximFont resource.
|HP Function Key escape codes should be generated for function
keys. It sets the hpFunctionKeys resource to "true".
| HP Function Key escape codes should not be generated for function
keys. It sets the hpFunctionKeys resource to "false".
| use highlightTextColor and highlightColor to override the reversed fore-
ground/background colors in a selection. It sets the highlightColorMode resource to "true".
|not to use highlightTextColor and highlightColor to override the reversed fore-
ground/background colors in a selection. It sets the highlightColorMode resource to "false".
|Turn on the hold resource, i.e., xterm will not immediately destroy its window when the shell
command completes. It will wait until you use the window manager to destroy/kill the window,
or if you use the menu entries that send a signal, e.g., HUP or KILL.
| Turn off the hold resource, i.e., xterm will immediately destroy its window when the shell
| Turn on the ptyInitialErase resource, i.e., use the pseudo-terminal's sense of the stty erase
| Turn off the ptyInitialErase resource, i.e., set the stty erase value using the kb string
from the termcap entry as a reference, if available.
| Turn on the useInsertMode resource, which forces use of insert mode by adding appropriate
entries to the TERMCAP environment variable.
| Turn off the useInsertMode resource.
| Given an X window identifier (a decimal integer), xterm will reparent its top-level shell
widget to that window. This is used to embed xterm within other applications.
| do jump scrolling. It corresponds to the jumpScroll
resource. Normally, text is scrolled one line at a time; allows xterm to move
multiple lines at a time so that it does not fall as far behind. Its use is strongly recom-
mended since it makes xterm much faster when scanning through large amounts of text. The
VT100 escape sequences for enabling and disabling smooth scroll as well as the "VT Options"
menu can be used to turn this feature on or off.
| not do jump scrolling.
| sets the allowC1Printable resource. When allowC1Printable is set, xterm over-
rides the mapping of C1 control characters (code 128-159) to treat them as printable.
| resets the allowC1Printable resource.
| sets the keyboardType resource. Possible values include: "unknown", "default",
"hp", "sco", "sun", "tcap" and "vt220".
The value "unknown", causes the corresponding resource to be ignored.
The value "default", suppresses the associated resources hpFunctionKeys, scoFunctionKeys,
sunFunctionKeys, tcapFunctionKeys and sunKeyboard, using the Sun/PC keyboard layout.
| Turn logging on. Normally logging is not supported, due to security concerns. Some versions
of xterm may have logging enabled. The logfile is written to the directory from which xterm
is invoked. The filename is generated, of the form
depending on how xterm was built.
| Turn logging off.
| Turn on support of various encodings according to the users' locale setting, i.e., LC_ALL,
LC_CTYPE, or LANG environment variables. This is achieved by turning on UTF-8 mode and by
invoking luit for conversion between locale encodings and UTF-8. (luit is not invoked in
UTF-8 locales.) This corresponds to the locale resource.
The actual list of encodings which are supported is determined by luit. Consult the luit
manual page for further details.
See also the discussion of the -u8 option which supports UTF-8 locales.
| Turn off support of automatic selection of locale encodings. Conventional 8bit mode or, in
UTF-8 locales or with -u8 option, UTF-8 mode will be used.
| File name for the encoding converter from/to locale encodings and UTF-8 which is used with
-lc option or locale resource. This corresponds to the localeFilter resource.
| Force scrollbar to the left side of VT100 screen. This is the default, unless you have set
the rightScrollBar resource.
| log-filename. See the -l option.
| the shell that is started in the xterm window will be a login
shell (i.e., the first character of argv will be a dash, indicating to the shell that it
should read the user's .login or .profile).
The -ls flag and the loginShell resource are ignored if -e is also given, because xterm does
not know how to make the shell start the given command after whatever it does when it is a
login shell - the user's shell of choice need not be a Bourne shell after all. Also,
xterm -e is supposed to provide a consistent functionality for other applications that need
to start text-mode programs in a window, and if loginShell were not ignored, the result of
~/.profile might interfere with that.
If you do want the effect of -ls and -e simultaneously, you may get away with something like
xterm -e /bin/bash -l -c "my command here"
Finally, -ls is not completely ignored, because xterm -ls -e does write a /etc/wtmp entry (if
configured to do so), whereas xterm -e does not.
| ask the window manager to maximize its layout on
startup. This corresponds to the maximized resource.
Maximizing is not the reverse of iconifying; it is possible to do both with certain window
| ask the window manager to maximize its layout on
| the shell that is started should not be a login shell (i.e., it
will be a normal "subshell").
| ring a margin bell when the user types near the right
end of a line.
| margin bell should not be rung.
| the maximum time between multi-click selections.
|Turn off the messages resource, i.e., disallow write access to the terminal.
|Turn on the messages resource, i.e., allow write access to the terminal.
| Set the mkWidth resource to "true". This makes xterm use a built-in version of the wide-
character width calculation. The default is "false"
| Reset the mkWidth resource.
| the color to be used for the pointer cursor. The default is to use the
foreground color. This sets the pointerColor resource.
| the number of characters from the right end of a line at which the mar-
gin bell, if enabled, will ring. The default is 10.
| disables the display of underlining.