term-utils/setterm.1

   1 .\" Copyright 1990 Gordon Irlam (gordoni@cs.ua.oz.au)
   2 .\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu)
   3 .\" Copyright 2000 Colin Watson (cjw44@cam.ac.uk)
   4 .\" Do not restrict distribution.
   5 .\" May be distributed under the GNU General Public License
   6 .\"
   7 .TH SETTERM 1 "May 2014" "util-linux" "User Commands"
   8 .SH NAME
   9 setterm \- set terminal attributes
  10 .SH SYNOPSIS
  11 .B setterm
  12 [options]
  13 .SH DESCRIPTION
  14 .B setterm
  15 writes to standard output a character string that will invoke the specified
  16 terminal capabilities.  Where possible
  17 .I terminfo
  18 is consulted to find the string to use.  Some options however (marked "virtual
  19 consoles only" below) do not correspond to a
  20 .BR terminfo (5)
  21 capability.  In this case, if the terminal type is "con" or "linux" the string
  22 that invokes the specified capabilities on the PC Minix virtual console driver
  23 is output.  Options that are not implemented by the terminal are ignored.
  24 .SH OPTIONS
  25 For boolean options
  26 .RB ( on " or " off ),
  27 the default is
  28 .BR on .
  29 .P
  30 Below, an
  31 .I 8-color
  32 can be
  33 .BR black ,
  34 .BR red ,
  35 .BR green ,
  36 .BR yellow ,
  37 .BR blue ,
  38 .BR magenta ,
  39 .BR cyan ,
  40 or
  41 .BR white .
  42 .P
  43 A
  44 .I 16-color
  45 can be an
  46 .IR 8-color ,
  47 or
  48 .BR grey ,
  49 or
  50 .B bright
  51 followed
  52 by
  53 .BR red ,
  54 .BR green ,
  55 .BR yellow ,
  56 .BR blue ,
  57 .BR magenta ,
  58 .BR cyan ,
  59 or
  60 .BR white .
  61 .P
  62 The various color options may be set independently, at least on virtual
  63 consoles, though the results of setting multiple modes (for example,
  64 .B \-\-underline
  65 and
  66 .BR \-\-half\-bright )
  67 are hardware-dependent.
  68 .PP
  69 The optional arguments require '=' (equals sign) and not space between the
  70 option and the argument. For example --option=argument.
  71 .TP
  72 \fB\-\-appcursorkeys\fP on|off
  73 Sets Cursor Key Application Mode on or off.  When on, ESC O A, ESC O B, etc.
  74 will be sent for the cursor keys instead of ESC [ A, ESC [ B, etc.  See the
  75 .I vi and Cursor-Keys
  76 section of the
  77 .I Text-Terminal-HOWTO
  78 for how this can cause problems for \fBvi\fR users.
  79 Virtual consoles only.
  80 .TP
  81 \fB\-\-append\fP \fIconsole_number\fP
  82 Like
  83 .BR \-\-dump ,
  84 but appends to the snapshot file instead of overwriting it.  Only works if no
  85 .B \-\-dump
  86 options are given.
  87 .TP
  88 \fB\-\-background\fP \fI8-color\fP|default
  89 Sets the background text color.
  90 .TP
  91 \fB\-\-blank\fP[=0-60|force|poke]
  92 Sets the interval of inactivity, in minutes, after which the screen will be
  93 automatically blanked (using APM if available).  Without an argument, it gets
  94 the blank status (returns which vt was blanked, or zero for an unblanked vt).
  95 Virtual consoles only.
  96 .IP
  97 The
  98 .B force
  99 argument keeps the screen blank even if a key is pressed.
 100 .IP
 101 The
 102 .B poke
 103 argument unblanks the screen.
 104 .TP
 105 \fB\-\-bfreq\fP[=\fInumber\fP]
 106 Sets the bell frequency in Hertz.  Without an argument, it defaults to
 107 .BR 0 .
 108 Virtual consoles only.
 109 .TP
 110 \fB\-\-blength\fP[=0-2000]
 111 Sets the bell duration in milliseconds.  Without an argument, it defaults to
 112 .BR 0 .
 113 Virtual consoles only.
 114 .TP
 115 \fB\-\-blink\fP on|off
 116 Turns blink mode on or off.  Except on a virtual console,
 117 .B \-\-blink off
 118 turns off all attributes (bold, half-brightness, blink, reverse).
 119 .TP
 120 \fB\-\-bold\fP on|off
 121 urns bold (extra bright) mode on or off.  Except on a virtual console,
 122 .B \-\-bold off
 123 turns off all attributes (bold, half-brightness, blink, reverse).
 124 .TP
 125 \fB\-\-clear\fP[=all|rest]
 126 Without an argument or with the argument
 127 .BR all ,
 128 the entire screen is cleared and the cursor is set to the home position,
 129 just like
 130 .BR clear (1)
 131 does.  With the argument
 132 .BR rest ,
 133 the screen is cleared from the current cursor position to the end.
 134 .TP
 135 \fB\-\-clrtabs\fP[=\fItab1 tab2 tab3\fP ...]
 136 Clears tab stops from the given horizontal cursor positions, in the range
 137 .BR 1-160 .
 138 Without arguments, it clears all tab stops.
 139 Virtual consoles only.
 140 .TP
 141 \fB\-\-cursor\fP on|off
 142 Turns the terminal's cursor on or off.
 143 .TP
 144 \fB\-\-default\fP
 145 Sets the terminal's rendering options to the default values.
 146 .TP
 147 \fB\-\-dump\fP[=\fIconsole_number\fP]
 148 Writes a snapshot of the virtual console with the given number
 149 to the file specified with the
 150 .B \-\-file
 151 option, overwriting its contents; the default is
 152 .IR screen.dump .
 153 Without an argument, it dumps the current virtual console.  This overrides
 154 .BR \-\-append .
 155 .TP
 156 \fB\-\-file\fP \fIfilename\fP
 157 Sets the snapshot file name for any
 158 .B \-\-dump
 159 or
 160 .B \-\-append
 161 options on the same command line.  If this option is not present, the default
 162 is
 163 .I screen.dump
 164 in the current directory.  A path name that exceeds the system maximum will be
 165 truncated, see PATH_MAX from linux/limits.h for the value.
 166 .TP
 167 \fB\-\-foreground\fP \fI8-color\fP|default
 168 Sets the foreground text color.
 169 .TP
 170 \fB\-\-half\-bright\fP on|off
 171 Turns dim (half-brightness) mode on or off.  Except on a virtual console,
 172 .B \-\-half\-bright off
 173 turns off all attributes (bold, half-brightness, blink, reverse).
 174 .TP
 175 \fB\-\-hbcolor\fP [bright] \fI16-color\fP
 176 Sets the color for half-bright characters.
 177 .TP
 178 \fB\-\-initialize\fP
 179 Displays the terminal initialization string, which typically sets the
 180 terminal's rendering options, and other attributes to the default values.
 181 .TP
 182 \fB\-\-inversescreen\fP on|off
 183 Swaps foreground and background colors for the whole screen.
 184 .TP
 185 \fB\-\-linewrap\fP on|off
 186 Makes the terminal continue on a new line when a line is full.
 187 .TP
 188 \fB\-\-msg\fP on|off
 189 Enables or disables the sending of kernel
 190 .BR printk ()
 191 messages to the console.
 192 Virtual consoles only.
 193 .TP
 194 \fB\-\-msglevel\fP 0-8
 195 Sets the console logging level for kernel
 196 .B printk()
 197 messages.  All messages strictly more important than this will be printed, so a
 198 logging level of
 199 .B 0
 200 has the same effect as
 201 .B \-\-msg on
 202 and a logging level of
 203 .B 8
 204 will print all kernel messages.
 205 .BR klogd (8)
 206 may be a more convenient interface to the logging of kernel messages.
 207 .sp
 208 Virtual consoles only.
 209 .TP
 210 \fB\-\-powerdown\fP[=0-60]
 211 Sets the VESA powerdown interval in minutes.  Without an argument, it defaults
 212 to
 213 .B 0
 214 (disable powerdown).  If the console is blanked or the monitor is in suspend
 215 mode, then the monitor will go into vsync suspend mode or powerdown mode
 216 respectively after this period of time has elapsed.
 217 .TP
 218 \fB\-\-powersave\fP \fImode\fP
 219 Valid values for \fImode\fP are:
 220 .RS
 221 .TP
 222 .B vsync|on
 223 Puts the monitor into VESA vsync suspend mode.
 224 .TP
 225 .B hsync
 226 Puts the monitor into VESA hsync suspend mode.
 227 .TP
 228 .B powerdown
 229 Puts the monitor into VESA powerdown mode.
 230 .TP
 231 .B off
 232 Turns monitor VESA powersaving features.
 233 .RE
 234 .TP
 235 \fB\-\-regtabs\fP[=1-160]
 236 Clears all tab stops, then sets a regular tab stop pattern, with one tab every
 237 specified number of positions.  Without an argument, it defaults to
 238 .BR 8 .
 239 Virtual consoles only.
 240 .TP
 241 \fB\-\-repeat\fP on|off
 242 Turns keyboard repeat on or off.
 243 Virtual consoles only.
 244 .TP
 245 \fB\-\-reset\fP
 246 Displays the terminal reset string, which typically resets the terminal to
 247 its power-on state.
 248 .TP
 249 \fB\-\-resize\fP
 250 Reset terminal size by assessing maximum row and column.  This is useful
 251 when actual geometry and kernel terminal driver are not in sync.  Most
 252 notable use case is with serial consoles, that do not use
 253 .BR ioctl (3p)
 254 but just byte streams and breaks.
 255 .TP
 256 \fB\-\-reverse\fP on|off
 257 Turns reverse video mode on or off.  Except on a virtual console,
 258 .B \-\-reverse off
 259 turns off all attributes (bold, half-brightness, blink, reverse).
 260 .TP
 261 \fB\-\-store\fP
 262 Stores the terminal's current rendering options (foreground and background
 263 colors) as the values to be used at reset-to-default.
 264 Virtual consoles only.
 265 .TP
 266 \fB\-\-tabs\fP[=\fItab1 tab2 tab3\fP ...]
 267 Sets tab stops at the given horizontal cursor positions, in the range
 268 .BR 1-160 .
 269 Without arguments, it shows the current tab stop settings.
 270 .TP
 271 \fB\-\-term\fP \fIterminal_name\fP
 272 Overrides the TERM environment variable.
 273 .TP
 274 \fB\-\-ulcolor\fP [bright] \fI16-color\fP
 275 Sets the color for underlined characters.
 276 Virtual consoles only.
 277 .TP
 278 \fB\-\-underline\fP on|off
 279 Turns underline mode on or off.
 280 .TP
 281 \fB\-\-version\fP
 282 Displays version information and exits.
 283 .TP
 284 \fB\-\-help\fP
 285 Displays a help text and exits.
 286 .SH COMPATIBILITY
 287 Since version 2.25
 288 .B setterm
 289 has support for long options with two hyphens, for example
 290 .BR \-\-help ,
 291 beside the historical long options with a single hyphen, for example
 292 .BR \-help .
 293 In scripts it is better to use the backward-compatible single hyphen
 294 rather than the double hyphen.  Currently there are no plans nor good
 295 reasons to discontinue single-hyphen compatibility.
 296 .SH "SEE ALSO"
 297 .BR stty (1),
 298 .BR tput (1),
 299 .BR tty (4),
 300 .BR terminfo (5)
 301 .SH BUGS
 302 Differences between the Minix and Linux versions are not documented.
 303 .SH AVAILABILITY
 304 The setterm command is part of the util-linux package and is available from
 305 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 306 Linux Kernel Archive
 307 .UE .