]>
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. |
bc6439ba KZ |
68 | .PP |
69 | The optional arguments require '=' (equals sign) and not space between the | |
70 | option and the argument. For example --option=argument. | |
6dbe3af9 | 71 | .TP |
bc6439ba | 72 | \fB\-\-appcursorkeys\fP on|off |
8e3bdb34 | 73 | Sets Cursor Key Application Mode on or off. When on, ESC O A, ESC O B, etc. |
22853e4a | 74 | will be sent for the cursor keys instead of ESC [ A, ESC [ B, etc. See the |
8e3bdb34 SK |
75 | .I vi and Cursor-Keys |
76 | section of the | |
77 | .I Text-Terminal-HOWTO | |
e73a0720 | 78 | for how this can cause problems for \fBvi\fR users. |
bc6439ba | 79 | Virtual consoles only. |
8e3bdb34 | 80 | .TP |
bc6439ba | 81 | \fB\-\-append\fP \fIconsole_number\fP |
8e3bdb34 SK |
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 | |
bc6439ba | 88 | \fB\-\-background\fP \fI8-color\fP|default |
22853e4a KZ |
89 | Sets the background text color. |
90 | .TP | |
bc6439ba | 91 | \fB\-\-blank\fP[=0-60|force|poke] |
115bfafa | 92 | Sets the interval of inactivity, in minutes, after which the screen will be |
e73a0720 BS |
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). | |
bc6439ba | 95 | Virtual consoles only. |
8e3bdb34 | 96 | .IP |
115bfafa JA |
97 | The |
98 | .B force | |
bc6439ba | 99 | argument keeps the screen blank even if a key is pressed. |
8e3bdb34 | 100 | .IP |
115bfafa JA |
101 | The |
102 | .B poke | |
bc6439ba | 103 | argument unblanks the screen. |
22853e4a | 104 | .TP |
bc6439ba | 105 | \fB\-\-bfreq\fP[=\fInumber\fP] |
e73a0720 | 106 | Sets the bell frequency in Hertz. Without an argument, it defaults to |
8e3bdb34 | 107 | .BR 0 . |
bc6439ba | 108 | Virtual consoles only. |
22853e4a | 109 | .TP |
bc6439ba | 110 | \fB\-\-blength\fP[=0-2000] |
e73a0720 | 111 | Sets the bell duration in milliseconds. Without an argument, it defaults to |
8e3bdb34 | 112 | .BR 0 . |
bc6439ba | 113 | Virtual consoles only. |
22853e4a | 114 | .TP |
bc6439ba | 115 | \fB\-\-blink\fP on|off |
e73a0720 | 116 | Turns blink mode on or off. Except on a virtual console, |
8e3bdb34 | 117 | .B \-\-blink off |
22853e4a KZ |
118 | turns off all attributes (bold, half-brightness, blink, reverse). |
119 | .TP | |
bc6439ba KZ |
120 | \fB\-\-bold\fP on|off |
121 | urns bold (extra bright) mode on or off. Except on a virtual console, | |
8e3bdb34 SK |
122 | .B \-\-bold off |
123 | turns off all attributes (bold, half-brightness, blink, reverse). | |
22853e4a | 124 | .TP |
bc6439ba | 125 | \fB\-\-clear\fP[=all|rest] |
e73a0720 BS |
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 | |
8e3bdb34 | 130 | .BR clear (1) |
e73a0720 BS |
131 | does. With the argument |
132 | .BR rest , | |
133 | the screen is cleared from the current cursor position to the end. | |
22853e4a | 134 | .TP |
bc6439ba | 135 | \fB\-\-clrtabs\fP[=\fItab1 tab2 tab3\fP ...] |
22853e4a | 136 | Clears tab stops from the given horizontal cursor positions, in the range |
8e3bdb34 | 137 | .BR 1-160 . |
e73a0720 | 138 | Without arguments, it clears all tab stops. |
bc6439ba | 139 | Virtual consoles only. |
22853e4a | 140 | .TP |
bc6439ba | 141 | \fB\-\-cursor\fP on|off |
115bfafa | 142 | Turns the terminal's cursor on or off. |
22853e4a | 143 | .TP |
8e3bdb34 | 144 | \fB\-\-default\fP |
115bfafa | 145 | Sets the terminal's rendering options to the default values. |
22853e4a | 146 | .TP |
bc6439ba | 147 | \fB\-\-dump\fP[=\fIconsole_number\fP] |
e73a0720 BS |
148 | Writes a snapshot of the virtual console with the given number |
149 | to the file specified with the | |
8e3bdb34 SK |
150 | .B \-\-file |
151 | option, overwriting its contents; the default is | |
152 | .IR screen.dump . | |
e73a0720 | 153 | Without an argument, it dumps the current virtual console. This overrides |
8e3bdb34 SK |
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 | |
e73a0720 | 164 | in the current directory. A path name that exceeds the system maximum will be |
8e3bdb34 SK |
165 | truncated, see PATH_MAX from linux/limits.h for the value. |
166 | .TP | |
bc6439ba | 167 | \fB\-\-foreground\fP \fI8-color\fP|default |
e73a0720 BS |
168 | Sets the foreground text color. |
169 | .TP | |
bc6439ba | 170 | \fB\-\-half\-bright\fP on|off |
e73a0720 | 171 | Turns dim (half-brightness) mode on or off. Except on a virtual console, |
b06c1ca6 | 172 | .B \-\-half\-bright off |
e73a0720 BS |
173 | turns off all attributes (bold, half-brightness, blink, reverse). |
174 | .TP | |
bc6439ba | 175 | \fB\-\-hbcolor\fP [bright] \fI16-color\fP |
f28985ff | 176 | Sets the color for half-bright characters. |
b5700fe5 | 177 | .TP |
8e3bdb34 | 178 | \fB\-\-initialize\fP |
b5700fe5 SK |
179 | Displays the terminal initialization string, which typically sets the |
180 | terminal's rendering options, and other attributes to the default values. | |
181 | .TP | |
bc6439ba | 182 | \fB\-\-inversescreen\fP on|off |
e73a0720 | 183 | Swaps foreground and background colors for the whole screen. |
b5700fe5 | 184 | .TP |
bc6439ba | 185 | \fB\-\-linewrap\fP on|off |
e73a0720 | 186 | Makes the terminal continue on a new line when a line is full. |
b5700fe5 | 187 | .TP |
bc6439ba | 188 | \fB\-\-msg\fP on|off |
8e3bdb34 | 189 | Enables or disables the sending of kernel |
3fe5e8ec | 190 | .BR printk () |
8e3bdb34 | 191 | messages to the console. |
bc6439ba | 192 | Virtual consoles only. |
8e3bdb34 | 193 | .TP |
bc6439ba | 194 | \fB\-\-msglevel\fP 0-8 |
8e3bdb34 SK |
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 | |
e73a0720 | 199 | .B 0 |
8e3bdb34 SK |
200 | has the same effect as |
201 | .B \-\-msg on | |
202 | and a logging level of | |
e73a0720 | 203 | .B 8 |
22853e4a KZ |
204 | will print all kernel messages. |
205 | .BR klogd (8) | |
206 | may be a more convenient interface to the logging of kernel messages. | |
bc6439ba KZ |
207 | .sp |
208 | Virtual consoles only. | |
22853e4a | 209 | .TP |
bc6439ba | 210 | \fB\-\-powerdown\fP[=0-60] |
e73a0720 | 211 | Sets the VESA powerdown interval in minutes. Without an argument, it defaults |
8e3bdb34 | 212 | to |
e73a0720 | 213 | .B 0 |
8e3bdb34 SK |
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. | |
115bfafa | 217 | .TP |
bc6439ba KZ |
218 | \fB\-\-powersave\fP \fImode\fP |
219 | Valid values for \fImode\fP are: | |
220 | .RS | |
115bfafa | 221 | .TP |
bc6439ba | 222 | .B vsync|on |
22853e4a KZ |
223 | Puts the monitor into VESA vsync suspend mode. |
224 | .TP | |
bc6439ba KZ |
225 | .B hsync |
226 | Puts the monitor into VESA hsync suspend mode. | |
227 | .TP | |
228 | .B powerdown | |
115bfafa JA |
229 | Puts the monitor into VESA powerdown mode. |
230 | .TP | |
bc6439ba KZ |
231 | .B off |
232 | Turns monitor VESA powersaving features. | |
233 | .RE | |
22853e4a | 234 | .TP |
bc6439ba | 235 | \fB\-\-regtabs\fP[=1-160] |
8e3bdb34 | 236 | Clears all tab stops, then sets a regular tab stop pattern, with one tab every |
e73a0720 | 237 | specified number of positions. Without an argument, it defaults to |
8e3bdb34 | 238 | .BR 8 . |
bc6439ba | 239 | Virtual consoles only. |
22853e4a | 240 | .TP |
bc6439ba | 241 | \fB\-\-repeat\fP on|off |
115bfafa | 242 | Turns keyboard repeat on or off. |
bc6439ba | 243 | Virtual consoles only. |
22853e4a | 244 | .TP |
8e3bdb34 | 245 | \fB\-\-reset\fP |
115bfafa | 246 | Displays the terminal reset string, which typically resets the terminal to |
e73a0720 | 247 | its power-on state. |
22853e4a | 248 | .TP |
5d795999 SK |
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 | |
dbeb1d73 | 253 | .BR ioctl (3p) |
5d795999 SK |
254 | but just byte streams and breaks. |
255 | .TP | |
bc6439ba | 256 | \fB\-\-reverse\fP on|off |
e73a0720 | 257 | Turns reverse video mode on or off. Except on a virtual console, |
8e3bdb34 SK |
258 | .B \-\-reverse off |
259 | turns off all attributes (bold, half-brightness, blink, reverse). | |
6dbe3af9 | 260 | .TP |
bc6439ba | 261 | \fB\-\-store\fP |
8e3bdb34 SK |
262 | Stores the terminal's current rendering options (foreground and background |
263 | colors) as the values to be used at reset-to-default. | |
bc6439ba | 264 | Virtual consoles only. |
115bfafa | 265 | .TP |
bc6439ba | 266 | \fB\-\-tabs\fP[=\fItab1 tab2 tab3\fP ...] |
8e3bdb34 SK |
267 | Sets tab stops at the given horizontal cursor positions, in the range |
268 | .BR 1-160 . | |
e73a0720 | 269 | Without arguments, it shows the current tab stop settings. |
115bfafa | 270 | .TP |
8e3bdb34 | 271 | \fB\-\-term\fP \fIterminal_name\fP |
115bfafa JA |
272 | Overrides the TERM environment variable. |
273 | .TP | |
bc6439ba | 274 | \fB\-\-ulcolor\fP [bright] \fI16-color\fP |
115bfafa | 275 | Sets the color for underlined characters. |
bc6439ba | 276 | Virtual consoles only. |
6e8e22ad | 277 | .TP |
bc6439ba | 278 | \fB\-\-underline\fP on|off |
e73a0720 BS |
279 | Turns underline mode on or off. |
280 | .TP | |
8e3bdb34 | 281 | \fB\-\-version\fP |
e73a0720 | 282 | Displays version information and exits. |
6e8e22ad | 283 | .TP |
8e3bdb34 | 284 | \fB\-\-help\fP |
e73a0720 | 285 | Displays a help text and exits. |
f0dcd918 | 286 | .SH COMPATIBILITY |
e73a0720 | 287 | Since version 2.25 |
f0dcd918 SK |
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 . | |
e73a0720 BS |
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. | |
5a829806 | 296 | .SH SEE ALSO |
6dbe3af9 | 297 | .BR stty (1), |
f053ff1e MK |
298 | .BR tput (1), |
299 | .BR tty (4), | |
300 | .BR terminfo (5) | |
6dbe3af9 | 301 | .SH BUGS |
fd6b7a7f | 302 | Differences between the Minix and Linux versions are not documented. |
86d62711 | 303 | .SH AVAILABILITY |
601d12fb | 304 | The setterm command is part of the util-linux package and is available from |
d673b74e | 305 | .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
8e3bdb34 SK |
306 | Linux Kernel Archive |
307 | .UE . |