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.
-help This causes xterm to print out a verbose message describing its options, one per line. The
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,
for that option also is not displayed by the -help option.
Most of the xterm options are actually parsed by the X Toolkit, which sets resource values. Xterm
provides the X Toolkit with a table of options. A few of these are marked, telling the X Toolkit to
ignore them (-help, -version, -class, -e, and -into). After the X Toolkit has parsed the command-line
parameters, it removes those which it handles, leaving the specially-marked parameters for xterm to
The -version and -help options are interpreted even if xterm cannot open the display, and are useful
for testing and configuration scripts. Along with -class, they are checked before other options. To
do this, xterm has its own (much simpler) argument parser, along with a table of the X Toolkit’s
built-in list of options.
Relying upon the X Toolkit to parse the options and associated values has the advantages of simplicity
and good integration with the X resource mechanism. There are a few drawbacks
· Xterm cannot tell easily whether a resource value was set by one of the external resource- or
application-defaults files, or if it was set through the -xrm option or via some directly relevant
command-line option. Xterm sees only the end-result: a value supplied when creating its widgets.
· Xterm does not know the order in which particular options and items in resource files are
evaluated. Rather, it sees all of the values for a given widget at the same time. In the design
of these options, some are deemed more important, and can override other options.
The X Toolkit uses patterns (constants and wildcards) to match resources. Once a particular
pattern has been used, it will not modify it. To override a given setting, a more-specific
pattern must be used, e.g., replacing “*” with “.”. Some poorly-designed resource files are too
specific to allow the command-line options to affect the relevant widget values.
· In a few cases, the X Toolkit combines its standard options in ways which do not work well with
xterm. This happens with the color (-fg, -bg) and reverse (-rv) options. Xterm makes a special
case of these and adjusts its sense of “reverse” to lessen user surprise.
One parameter (after all options) may be given. That overrides xterm’s built-in choice of shell
· If the parameter is not a relative path, i.e., beginning with “./” or “../”, xterm looks for the
file in the user’s PATH. In either case, this check fails if xterm cannot construct an absolute
· If that check fails (or if no such parameter is given), xterm next checks the “SHELL” variable.
If that specifies an executable file, xterm will attempt to start that. However, xterm
additionally checks if it is a valid shell, and will unset “SHELL” if it is not.
· If “SHELL” is not set to an executable file, xterm tries to use the shell program specified in the
user’s password file entry. As before, xterm verifies if this is a valid shell.
· Finally, if the password file entry does not specify a valid shell, xterm uses /bin/sh.
The -e option cannot be used with this parameter since it uses all parameters following the option.
Xterm validates shell programs by finding their pathname in the text file /etc/shells. It treats the
environment variable “SHELL” specially because (like “TERM”), xterm both reads and updates the
variable, and because the program started by xterm is not necessarily a shell.
Not all options are necessarily configured into your copy of xterm:
-132 Normally, the VT102 DECCOLM escape sequence that switches between 80 and 132 column mode is
window will resize appropriately.
-ah This option indicates that xterm should always highlight the text cursor. By default, xterm
+ah This option indicates that xterm should do text cursor highlighting based on focus.
-ai This option disables active icon support if that feature was compiled into xterm. This is
+ai This option enables active icon support if that feature was compiled into xterm. This is
-aw This option indicates that auto-wraparound should be allowed, and is equivalent to setting the
it is at the rightmost position of a line and text is output.
+aw This option indicates that auto-wraparound should not be allowed, and is equivalent to setting
characters and the window border) in pixels. That is the vt100 internalBorder resource. The
default is “2”.
optimizing their output to the screen. The default is “38400”.
+bc turn off text cursor blinking. This overrides the cursorBlink resource.
-bc turn on text cursor blinking. This overrides the cursorBlink resource.
-bdc Set the vt100 resource colorBDMode to “false”, disabling the display of characters with bold
+bdc Set the vt100 resource colorBDMode to “true”, enabling the display of characters with bold
-cb Set the vt100 resource cutToBeginningOfLine to “false”.
+cb Set the vt100 resource cutToBeginningOfLine to “true”.
CLASSES and the charClass resource).
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”
set to another class such as “UXTerm” to override selected resources.
-cm This option disables recognition of ANSI color-change escape sequences. It sets the colorMode
+cm This option enables recognition of ANSI color-change escape sequences. This is the same as
-cn This option indicates that newlines should not be cut in line-mode selections. It sets the
+cn This option indicates that newlines should be cut in line-mode selections. It sets the
foreground color that is used for text. It sets the cursorColor resource according to the
-cu This option indicates that xterm should work around a bug in the more(1) program that causes
line beginning with a tab (the leading tabs are not displayed). This option is so named
because it was originally thought to be a bug in the curses(3x) cursor motion package.
+cu This option indicates that xterm should not work around the more(1) bug mentioned above.
-dc This option disables the escape sequence to change dynamic colors: the vt100 foreground and
the Tektronix emulator foreground and background colors, its text cursor color and highlight
color. The option sets the dynamicColors option to “false”.
+dc This option enables the escape sequence to change dynamic colors. The option sets the
-e program [ arguments … ]
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.
Encodings other than UTF-8 are supported by using luit. The -lc option should be used instead
of -en for systems with locale support.
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.
library was compiled into xterm. This corresponds to the faceName resource. When a CJK
double-width font is specified, you also need to turn on the cjkWidth resource.
are initially active.
-fbb This option indicates that xterm should compare normal and bold fonts bounding boxes to ensure
+fbb This option indicates that xterm should not compare normal and bold fonts bounding boxes to
-fbx This option indicates that xterm should not assume that the normal and bold fonts have VT100
sets the forceBoxChars resource to “false”.
+fbx This option indicates that xterm should assume that the normal and bold fonts have VT100 line-
support for that library was compiled into xterm. This corresponds to the faceNameDoublesize
that library was compiled into xterm. This corresponds to the faceSize resource.
for display, e.g., without window decorations. It sets the fullscreen resource to “true”.
screen for display. It sets the fullscreen resource to “false”.
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
corresponds to the wideFont resource.
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.
“OverTheSpot” input method.
-hf This option indicates that HP function key escape codes should be generated for function keys.
+hf This option indicates that HP function key escape codes should not be generated for function
-hm Tells xterm to use highlightTextColor and highlightColor to override the reversed
+hm Tells xterm not to use highlightTextColor and highlightColor to override the reversed
-hold Turn on the hold resource, i.e., xterm will not immediately destroy its window when the shell
or if you use the menu entries that send a signal, e.g., HUP or KILL.
+hold Turn off the hold resource, i.e., xterm will immediately destroy its window when the shell
-ie Turn on the ptyInitialErase resource, i.e., use the pseudo-terminal’s sense of the stty erase
+ie Turn off the ptyInitialErase resource, i.e., set the stty erase value using the kb string from
-im Turn on the useInsertMode resource, which forces use of insert mode by adding appropriate
TERMCAP is not used).
+im Turn off the useInsertMode resource.
to whether it begins with “0x”, “0” or neither), xterm will reparent its top-level shell
widget to that window. This is used to embed xterm within other applications.
feature. When using Gtk, there is a limitation of that toolkit which requires that xterm’s
allowSendEvents resource is enabled.
-itc Set the vt100 resource colorITMode to “false”, disabling the display of characters with italic
+itc Set the vt100 resource colorITMode to “true”, enabling the display of characters with italic
-j This option indicates that xterm should do jump scrolling. It corresponds to the jumpScroll
multiple lines at a time so that it does not fall as far behind. Its use is strongly
recommended 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.
+j This option indicates that xterm should not do jump scrolling.
-k8 This option sets the allowC1Printable resource. When allowC1Printable is set, xterm overrides
+k8 This option resets the allowC1Printable resource.
“legacy”, “hp”, “sco”, “sun”, “tcap” and “vt220”.
-l Turn logging on, unless disabled by the logInhibit resource.
due to security concerns in the early 1990s. That was a problem in X11R4 xterm (1989) which
was addressed by a patch to X11R5 late in 1993. X11R6 included these fixes. The older
version (when running with root privilege) would create the log-file using root privilege.
The reason why xterm ran with root privileges was to open pseudo-terminals. Those privileges
are now needed only on very old systems: Unix98 pseudo-terminals made the BSD scheme
+l Turn logging off.
-lc Turn on support of various encodings according to the users’ locale setting, i.e., LC_ALL,
invoking luit for conversion between locale encodings and UTF-8. (luit is not invoked in
UTF-8 locales.) This corresponds to the locale resource.
manual page for further details.
+lc Turn off support of automatic selection of locale encodings. Conventional 8bit mode or, in
option or locale resource. This corresponds to the localeFilter resource.
the rightScrollBar resource.
-ls This option indicates that the shell that is started in the xterm window will be a login shell
read the user’s .login or .profile).
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 configured to do so), whereas xterm -e does not.
startup. This corresponds to the maximized resource.
+ls This option indicates that the shell that is started should not be a login shell (i.e., it
-mb This option indicates that xterm should ring a margin bell when the user types near the right
+mb This option indicates that margin bell should not be rung.
-mesg Turn off the messages resource, i.e., disallow write access to the terminal.
+mesg Turn on the messages resource, i.e., allow write access to the terminal.
character width calculation. The default is “false”
foreground color. This sets the pointerColor resource.
margin bell, if enabled, will ring. The default is “10”.
-nul This option disables the display of underlining.
+nul This option enables the display of underlining.
-pc This option enables the PC-style use of bold colors (see boldColors resource).
+pc This option disables the PC-style use of bold colors.
-pob This option indicates that the window should be raised whenever a Control-G is received.
+pob This option indicates that the window should not be raised whenever a Control-G is received.
them. This corresponds to the reportColors resource.
corresponds to the reportFonts resource.
-rvc This option disables the display of characters with reverse attribute as color.
+rvc This option enables the display of characters with reverse attribute as color.
-rw This option indicates that reverse-wraparound should be allowed. This allows the cursor to
This is very useful for editing long shell command lines and is encouraged. This option can
be turned on and off from the VT Options menu.
+rw This option indicates that reverse-wraparound should not be allowed.
-s This option indicates that xterm may scroll asynchronously, meaning that the screen does not
network latencies are very high and is typically useful when running across a very large
internet or many gateways.
+s This option indicates that xterm should scroll synchronously.
name is not changed. This has the advantage of preventing flicker and the disadvantage of
requiring an extra round trip to the server to find out the previous value. In practice this
should never be a problem.
-sb This option indicates that some number of lines that are scrolled off the top of the window
This option may be turned on and off from the VT Options menu.
+sb This option indicates that a scrollbar should not be displayed.
reverse video is used. See the discussion of the highlightColor resource.
used. See the discussion of the highlightTextColor resource.
-sf This option indicates that Sun function key escape codes should be generated for function
+sf This option indicates that the standard escape codes should be generated for function keys.
-si This option indicates that output to a window should not automatically reposition the screen
+si This option indicates that output to a window should cause it to scroll to the bottom.
-sk This option indicates that pressing a key while using the scrollbar to review previous lines
bottom of the scroll region.
+sk This option indicates that pressing a key while using the scrollbar should not cause the
screen. This corresponds to the saveLines resource. The default is “64”.
-sm This option, corresponding to the sessionMgt resource, indicates that xterm should set up
+sm This option indicates that xterm should not set up session manager callbacks.
-sp This option indicates that Sun/PC keyboard should be assumed, providing mapping for keypad “+”
+sp This option indicates that the standard escape codes should be generated for keypad and
-t This option indicates that xterm should start in Tektronix mode, rather than in VTxxx mode.
sets the “TERM” and the “TERMCAP” environment variables.
+t This option indicates that xterm should start in VTxxx mode.
-tb This option, corresponding to the toolBar resource, indicates that xterm should display a
popup menus, e.g., control/left/mouse for Main Options.
+tb This option indicates that xterm should not set up a toolbar.
specifies the emulation level, used to determine the type of response to a DA control
sequence. Valid values include vt52, vt100, vt101, vt102, vt220, and vt240 (the “vt” is
optional). The default is “vt420”. The term_id argument specifies the terminal ID to use.
(This is the same as the decTerminalID resource).
should be bound to those functions, similar to the stty program. The keywords and their
values are described in detail in the ttyModes resource.
variable. It corresponds to the termName resource. This terminal type must exist in the
terminal database (termcap or terminfo, depending on how xterm is built) and should have li#
and co# entries. If the terminal type is not found, xterm uses the built-in list “xterm”,
-u8 This option sets the utf8 resource. When utf8 is set, xterm interprets incoming data as
option prevents it from being turned off. If you must turn UTF-8 encoding on and off, use the
-wc option or the corresponding wideChars resource, rather than the -u8 option.
resource. That is, if xterm has been compiled to support luit, and the locale resource is not
“false” this option is ignored. We recommend using the -lc option or the “locale: true”
resource in UTF-8 locales when your operating system supports locale, or -en UTF-8 option or
the “locale: UTF-8” resource when your operating system does not support locale.
+u8 This option resets the utf8 resource.
-uc This option makes the cursor underlined instead of a box.
+uc This option makes the cursor a box instead of underlined.
-ulc This option disables the display of characters with underline attribute as color rather than
+ulc This option enables the display of characters with underline attribute as color rather than
-ulit This option, corresponding to the italicULMode resource, disables the display of characters
+ulit This option, corresponding to the italicULMode resource, enables the display of characters
-ut This option indicates that xterm should not write a record into the the system utmp log file.
+ut This option indicates that xterm should write a record into the system utmp log file.
-vb This option indicates that a visual bell is preferred over an audible one. Instead of ringing
+vb This option indicates that a visual bell should not be used.
-wc This option sets the wideChars resource.
not started in UTF-8 mode (or if this resource is not set), initially it maintains those
structures to support 8-bit characters. Xterm can later be switched, using a menu entry or
control sequence, causing it to reallocate those structures to support 16-bit characters.
+wc This option resets the wideChars resource.
-wf This option indicates that xterm should wait for the window to be mapped the first time before
are correct. It is the application’s responsibility to catch subsequent terminal size
+wf This option indicates that xterm should not wait before starting the subprocess.
iconified will cause an XBell sound at the given volume and have “***” prepended to their icon
titles. Most window managers will detect this change immediately, showing you which window
has the output. (A similar feature was in x10 xterm.)
-C This option indicates that this window should receive console output. This is not supported
you must have read and write permission for it. If you are running X under xdm on the console
screen you may need to have the session startup and reset programs explicitly change the
ownership of the console device in order to get this option to work.
-Sccn This option allows xterm to be used as an input and output channel for an existing program and
letters of the name of a pseudo-terminal to use in slave mode, plus the number of the
inherited file descriptor. If the option contains a “/” character, that delimits the
characters used for the pseudo-terminal name from the file descriptor. Otherwise, exactly two
characters are used from the option for the pseudo-terminal name, the remainder is the file
descriptor. Examples (the first two are equivalent since the descriptor follows the last
is possible (though probably not portable) to have an application which passes an open file
descriptor down to xterm past the initialization or the -S option to a process running in the
The following command line arguments are provided for compatibility with older versions. They may not
be supported in the next release as the X Toolkit provides standard options that accomplish the same
%geom This option specifies the preferred size and position of the Tektronix window. It is
#geom This option specifies the preferred position of the icon window. It is shorthand for
“iconName” resource. Note that this is not the same as the toolkit option -name. The default
icon name is the application name.
-r This option indicates that reverse video should be simulated by swapping the foreground and
equivalent to -borderwidth or -bw.
The following standard X Toolkit command line arguments are commonly used with xterm:
resource name is borderColor. Xterm uses the X Toolkit default, which is
resource name is background. The default is “XtDefaultBackground”.
shell widget, and may provide advice to your window manager to set the thickness of the window
frame. Most window managers do not use this information. See the -b option, which controls
the inner border of the xterm window.
is foreground. The default is “XtDefaultForeground”.
resource name is font. The resource value default is fixed.
specification; it can be either g for the global screen (default), c for the current screen or
a screen number.
than as the normal window. The corresponding resource name is iconic.
than the default executable file name. Name should not contain “.” or “*” characters.
-rv This option indicates that reverse video should be simulated by swapping the foreground and
+rv Disable the simulation of reverse video by swapping foreground and background colors.
the user so chooses. The default title is the command line specified after the -e option, if
any, otherwise the application name.
resources that do not have separate command line options.