.\" Copyright 1990 Gordon Irlam (gordoni@cs.ua.oz.au)
.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)
-.\" Most of this was copied from the source code.
+.\" Copyright 2000 Colin Watson (cjw44@cam.ac.uk)
.\" Do not restrict distribution.
.\" May be distributed under the GNU General Public License
.\"
-.\" Most options documented by Colin Watson (cjw44@cam.ac.uk)
-.\" Undocumented: -snow, -softscroll, -standout; these are
-.\" commented out in the source
-.\"
-.TH SETTERM 1 "7 January 2000" "Util-Linux 2.10" "Linux Programmer's Manual"
+.TH SETTERM 1 "May 2014" "util-linux" "User Commands"
.SH NAME
setterm \- set terminal attributes
.SH SYNOPSIS
.B setterm
-.RI [ options ]
+[options]
.SH DESCRIPTION
.B setterm
-writes to standard output a character string that will invoke the
-specified terminal capabilities. Where possible
+writes to standard output a character string that will invoke the specified
+terminal capabilities. Where possible
.I terminfo
-is consulted to find the string to use. Some options however (marked
-"virtual consoles only" below) do not correspond to a
+is consulted to find the string to use. Some options however (marked "virtual
+consoles only" below) do not correspond to a
.BR terminfo (5)
-capability. In this case, if the terminal type is "con" or "linux" the
-string that invokes the specified capabilities on the PC Minix virtual
-console driver is output. Options that are not implemented by the terminal
-are ignored.
+capability. In this case, if the terminal type is "con" or "linux" the string
+that invokes the specified capabilities on the PC Minix virtual console driver
+is output. Options that are not implemented by the terminal are ignored.
.SH OPTIONS
-For boolean options (\fBon\fP or \fBoff\fP), the default is \fBon\fP.
+For boolean options
+.RB ( on " or " off ),
+the default is
+.BR on .
.P
-For conciseness, an \fI8-color\fP below is \fBblack\fP, \fBred\fP,
-\fBgreen\fP, \fByellow\fP, \fBblue\fP, \fBmagenta\fP, \fBcyan\fP, or
-\fBwhite\fP.
+Below, an
+.I 8-color
+can be
+.BR black ,
+.BR red ,
+.BR green ,
+.BR yellow ,
+.BR blue ,
+.BR magenta ,
+.BR cyan ,
+or
+.BR white .
.P
-A \fI16-color\fP is an \fI8-color\fP, \fBgrey\fP, or \fBbright\fP followed
-by \fBred\fP, \fBgreen\fP, \fByellow\fP, \fBblue\fP, \fBmagenta\fP,
-\fBcyan\fP, or \fBwhite\fP.
+A
+.I 16-color
+can be an
+.IR 8-color ,
+or
+.BR grey ,
+or
+.B bright
+followed
+by
+.BR red ,
+.BR green ,
+.BR yellow ,
+.BR blue ,
+.BR magenta ,
+.BR cyan ,
+or
+.BR white .
.P
-The various color options may be set independently, at least at virtual
+The various color options may be set independently, at least on virtual
consoles, though the results of setting multiple modes (for example,
-.BR \-underline " and " \-half-bright )
+.B \-\-underline
+and
+.BR \-\-half\-bright )
are hardware-dependent.
.TP
-.BR \-term " terminal_name"
-Overrides the TERM environment variable.
-.TP
-.B \-reset
-Displays the terminal reset string, which typically resets the terminal to
-its power on state.
-.TP
-.B \-initialize
-Displays the terminal initialization string, which typically sets the
-terminal's rendering options, and other attributes to the default values.
-.TP
-.BR \-cursor " [" on | off ]
-Turns the terminal's cursor on or off.
-.TP
-.BR \-repeat " [" on | off "] (virtual consoles only)"
-Turns keyboard repeat on or off.
-.TP
-.BR \-appcursorkeys " [" on | off "] (virtual consoles only)"
-Sets Cursor Key Application Mode on or off. When on, ESC O A, ESC O B, etc.
+\fB\-\-appcursorkeys\fP [\fBon\fP|\fBoff\fP] (virtual consoles only)
+Sets Cursor Key Application Mode on or off. When on, ESC O A, ESC O B, etc.
will be sent for the cursor keys instead of ESC [ A, ESC [ B, etc. See the
-"vi and Cursor-Keys" section of the Text-Terminal-HOWTO for how this can
-cause problems for vi users.
-.TP
-.BR \-linewrap " [" on | off "] (virtual consoles only)"
-Turns automatic line-wrapping on or off.
-.TP
-.B \-default
-Sets the terminal's rendering options to the default values.
-.TP
-\fB\-foreground\fP \fI8-color\fP|\fBdefault\fP (virtual consoles only)
-Sets the foreground text color.
-.TP
-\fB\-background\fP \fI8-color\fP|\fBdefault\fP (virtual consoles only)
+.I vi and Cursor-Keys
+section of the
+.I Text-Terminal-HOWTO
+for how this can cause problems for \fBvi\fR users.
+.TP
+\fB\-\-append\fP [\fIconsole_number\fP]
+Like
+.BR \-\-dump ,
+but appends to the snapshot file instead of overwriting it. Only works if no
+.B \-\-dump
+options are given.
+.TP
+\fB\-\-background\fP \fI8-color\fP|\fBdefault\fP
Sets the background text color.
.TP
-\fB\-ulcolor\fP \fI16-color\fP (virtual consoles only)
-Sets the color for underlined characters.
-.TP
-\fB\-hbcolor\fP \fI16-color\fP (virtual consoles only)
-Sets the color for half-bright characters.
-.TP
-.BR \-inversescreen " [" on | off "] (virtual consoles only)"
-Inverts the screen colors. Foreground and background are swapped, as are
-underline and half-brightness.
+\fB\-\-blank\fP [\fB0-60\fP|\fBforce\fP|\fBpoke\fP] (virtual consoles only)
+Sets the interval of inactivity, in minutes, after which the screen will be
+automatically blanked (using APM if available). Without an argument, it gets
+the blank status (returns which vt was blanked, or zero for an unblanked vt).
+.IP
+The
+.B force
+option keeps the screen blank even if a key is pressed.
+.IP
+The
+.B poke
+option unblanks the screen.
.TP
-.BR \-bold " [" on | off ]
-Turns bold (extra bright) mode on or off. Except at a virtual console,
-\fB\-bold off\fP turns off all attributes (bold, half-brightness, blink,
-reverse).
+\fB\-\-bfreq\fP [\fInumber\fP] (virtual consoles only)
+Sets the bell frequency in Hertz. Without an argument, it defaults to
+.BR 0 .
.TP
-.BR \-half-bright " [" on | off ]
-Turns dim (half-brightness) mode on or off (see \fB\-hbcolor\fP). Except at
-a virtual console, \fB\-half-bright off\fP turns off all attributes (bold,
-half-brightness, blink, reverse).
+\fB\-\-blength\fP [\fB0-2000\fP] (virtual consoles only)
+Sets the bell duration in milliseconds. Without an argument, it defaults to
+.BR 0 .
.TP
-.BR \-blink " [" on | off ]
-Turns blink mode on or off. Except at a virtual console, \fB\-blink off\fP
+.BR \-\-blink " [" on | off ]
+Turns blink mode on or off. Except on a virtual console,
+.B \-\-blink off
turns off all attributes (bold, half-brightness, blink, reverse).
.TP
-.BR \-reverse " [" on | off ]
-Turns reverse video mode on or off. Except at a virtual console,
-\fB\-reverse off\fP turns off all attributes (bold, half-brightness, blink,
-reverse).
+.BR \-\-bold " [" on | off ]
+Turns bold (extra bright) mode on or off. Except on a virtual console,
+.B \-\-bold off
+turns off all attributes (bold, half-brightness, blink, reverse).
.TP
-.BR \-underline " [" on | off ]
-Turns underline mode on or off (see \fB\-ulcolor\fP).
+\fB\-\-clear\fP[=\fBall\fP|\fBrest\fP]
+Without an argument or with the argument
+.BR all ,
+the entire screen is cleared and the cursor is set to the home position,
+just like
+.BR clear (1)
+does. With the argument
+.BR rest ,
+the screen is cleared from the current cursor position to the end.
+.TP
+\fB\-\-clrtabs\fP [\fItab1 tab2 tab3\fP ...] (virtual consoles only)
+Clears tab stops from the given horizontal cursor positions, in the range
+.BR 1-160 .
+Without arguments, it clears all tab stops.
.TP
-.BR \-store " (virtual consoles only)"
-Stores the terminal's current rendering options (foreground and
-background colors) as the values to be used at reset-to-default.
+.BR \-\-cursor " [" on | off ]
+Turns the terminal's cursor on or off.
.TP
-.BR \-clear " [" all ]
-Clears the screen and "homes" the cursor, as
-.BR clear (1).
+\fB\-\-default\fP
+Sets the terminal's rendering options to the default values.
.TP
-.B \-clear rest
-Clears from the current cursor position to the end of the screen.
+\fB\-\-dump\fP [\fIconsole_number\fP]
+Writes a snapshot of the virtual console with the given number
+to the file specified with the
+.B \-\-file
+option, overwriting its contents; the default is
+.IR screen.dump .
+Without an argument, it dumps the current virtual console. This overrides
+.BR \-\-append .
+.TP
+\fB\-\-file\fP \fIfilename\fP
+Sets the snapshot file name for any
+.B \-\-dump
+or
+.B \-\-append
+options on the same command line. If this option is not present, the default
+is
+.I screen.dump
+in the current directory. A path name that exceeds the system maximum will be
+truncated, see PATH_MAX from linux/limits.h for the value.
+.TP
+\fB\-\-foreground\fP \fI8-color\fP|\fBdefault\fP
+Sets the foreground text color.
.TP
-.BR \-tabs " [\fItab1 tab2 tab3\fP ...] (virtual consoles only)"
-Sets tab stops at the given horizontal cursor positions, in the range 1-160.
-Without arguments, shows the current tab stop settings.
+.BR \-\-half\-bright " [" on | off ]
+Turns dim (half-brightness) mode on or off. Except on a virtual console,
+.B \-\-half\-bright off
+turns off all attributes (bold, half-brightness, blink, reverse).
.TP
-.BR \-clrtabs " [\fItab1 tab2 tab3\fP ...] (virtual consoles only)"
-Clears tab stops from the given horizontal cursor positions, in the range
-1-160. Without arguments, clears all tab stops.
+\fB\-\-hbcolor\fP \fI16-color\fP
+Sets the color for half-bright characters.
.TP
-.BR \-regtabs " [\fI1-160\fP] (virtual consoles only)"
-Clears all tab stops, then sets a regular tab stop pattern, with one tab
-every specified number of positions. Without an argument, defaults to 8.
+\fB\-\-initialize\fP
+Displays the terminal initialization string, which typically sets the
+terminal's rendering options, and other attributes to the default values.
.TP
-.BR \-blank " [\fI0-60\fP|\fBforce\fP|\fBpoke\fP] (virtual consoles only)"
-Sets the interval of inactivity, in minutes, after which the screen will be
-automatically blanked (using APM if available). Without an argument, gets the
-blank status (returns which vt was blanked or zero for unblanked vt).
-
-The
-.B force
-option keeps screen blank even if a key is pressed.
-
-The
-.B poke
-option unblank the screen.
-.TP
-.BR \-dump " [\fI1-NR_CONS\fP]"
-Writes a snapshot of the given virtual console (with attributes) to the file
-specified in the \fB\-file\fP option, overwriting its contents; the default
-is screen.dump. Without an argument, dumps the current virtual console.
-Overrides \fB\-append\fP.
-.TP
-.BR \-append " [\fI1-NR_CONS\fP]"
-Like \fB\-dump\fP, but appends to the snapshot file instead of overwriting
-it. Only works if no \fB\-dump\fP options are given.
-.TP
-.BI \-file " dumpfilename"
-Sets the snapshot file name for any \fB\-dump\fP or \fB\-append\fP options
-on the same command line. If this option is not present, the default is
-screen.dump in the current directory. A path name that exceeds system
-maximum will be truncated, see PATH_MAX from linux/limits.h for the value.
-.TP
-.BR \-msg " [" on | off "] (virtual consoles only)"
-Enables or disables the sending of kernel \fBprintk()\fP messages to the
-console.
-.TP
-.BR \-msglevel " \fI1-8\fP (virtual consoles only)"
-Sets the console logging level for kernel \fBprintk()\fP messages. All
-messages strictly more important than this will be printed, so a logging
-level of 0 has the same effect as \fB\-msg on\fP and a logging level of 8
+.BR \-\-inversescreen " [" on | off ]
+Swaps foreground and background colors for the whole screen.
+.TP
+.BR \-\-linewrap " [" on | off ]
+Makes the terminal continue on a new line when a line is full.
+.TP
+.BR \-\-msg " [" on | off "] (virtual consoles only)"
+Enables or disables the sending of kernel
+.BR printk ()
+messages to the console.
+.TP
+\fB\-\-msglevel\fP \fB0-8\fP (virtual consoles only)
+Sets the console logging level for kernel
+.B printk()
+messages. All messages strictly more important than this will be printed, so a
+logging level of
+.B 0
+has the same effect as
+.B \-\-msg on
+and a logging level of
+.B 8
will print all kernel messages.
.BR klogd (8)
may be a more convenient interface to the logging of kernel messages.
.TP
-.BR "\-powersave on" | vsync
+\fB\-\-powerdown\fP [\fB0-60\fP]
+Sets the VESA powerdown interval in minutes. Without an argument, it defaults
+to
+.B 0
+(disable powerdown). If the console is blanked or the monitor is in suspend
+mode, then the monitor will go into vsync suspend mode or powerdown mode
+respectively after this period of time has elapsed.
+.TP
+\fB\-\-powersave\fP \fBoff\fP
+Turns off monitor VESA powersaving features.
+.TP
+\fB\-\-powersave\fP \fBon\fP|\fBvsync\fP
Puts the monitor into VESA vsync suspend mode.
.TP
-.B \-powersave hsync
+\fB\-\-powersave\fP \fBpowerdown\fP
+Puts the monitor into VESA powerdown mode.
+.TP
+\fB\-\-powersave\fP \fBhsync\fP
Puts the monitor into VESA hsync suspend mode.
.TP
-.B \-powersave powerdown
-Puts the monitor into VESA powerdown mode.
+\fB\-\-regtabs\fP [\fB1-160\fP] (virtual consoles only)
+Clears all tab stops, then sets a regular tab stop pattern, with one tab every
+specified number of positions. Without an argument, it defaults to
+.BR 8 .
.TP
-.BR \-powersave " [" off "]"
-Turns off monitor VESA powersaving features.
+.BR \-\-repeat " [" on | off "] (virtual consoles only)"
+Turns keyboard repeat on or off.
.TP
-.BR \-powerdown " [\fI0-60\fP]"
-Sets the VESA powerdown interval in minutes. Without an argument, defaults
-to 0 (disable powerdown). If the console is blanked or the monitor is in
-suspend mode, then the monitor will go into vsync suspend mode or powerdown
-mode respectively after this period of time has elapsed.
+\fB\-\-reset\fP
+Displays the terminal reset string, which typically resets the terminal to
+its power-on state.
+.TP
+\fB\-\-resize\fP
+Reset terminal size by assessing maximum row and column. This is useful
+when actual geometry and kernel terminal driver are not in sync. Most
+notable use case is with serial consoles, that do not use
+.BR ioctl (3p)
+but just byte streams and breaks.
+.TP
+\fB\-\-reverse\fP [\fBon\fP|\fBoff\fP]
+Turns reverse video mode on or off. Except on a virtual console,
+.B \-\-reverse off
+turns off all attributes (bold, half-brightness, blink, reverse).
.TP
-.BR \-blength " [\fI0-2000\fP]"
-Sets the bell duration in milliseconds. Without an argument, defaults to 0.
+\fB\-\-store\fP (virtual consoles only)
+Stores the terminal's current rendering options (foreground and background
+colors) as the values to be used at reset-to-default.
.TP
-.BR \-bfreq " [\fIfreqnumber\fP]"
-Sets the bell frequency in Hz. Without an argument, defaults to 0.
+\fB\-\-tabs\fP [\fItab1 tab2 tab3\fP ...]
+Sets tab stops at the given horizontal cursor positions, in the range
+.BR 1-160 .
+Without arguments, it shows the current tab stop settings.
.TP
-.BR \-version
-Output version information and exit.
+\fB\-\-term\fP \fIterminal_name\fP
+Overrides the TERM environment variable.
.TP
-.BR \-help
-Output help screen and exit.
+\fB\-\-ulcolor\fP \fI16-color\fP (virtual consoles only)
+Sets the color for underlined characters.
+.TP
+.BR \-\-underline " [" on | off ]
+Turns underline mode on or off.
+.TP
+\fB\-\-version\fP
+Displays version information and exits.
+.TP
+\fB\-\-help\fP
+Displays a help text and exits.
+.SH COMPATIBILITY
+Since version 2.25
+.B setterm
+has support for long options with two hyphens, for example
+.BR \-\-help ,
+beside the historical long options with a single hyphen, for example
+.BR \-help .
+In scripts it is better to use the backward-compatible single hyphen
+rather than the double hyphen. Currently there are no plans nor good
+reasons to discontinue single-hyphen compatibility.
.SH "SEE ALSO"
-.BR tput (1),
.BR stty (1),
-.BR terminfo (5),
-.BR tty (4)
+.BR tput (1),
+.BR tty (4),
+.BR terminfo (5)
.SH BUGS
Differences between the Minix and Linux versions are not documented.
.SH AVAILABILITY
The setterm command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .
projects / thirdparty / util-linux.git / blobdiff