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