Annotation of src/usr.bin/tset/tset.1, Revision 1.24
1.24 ! jmc 1: .\" $OpenBSD: tset.1,v 1.23 2022/03/31 17:27:28 naddy Exp $
1.1 deraadt 2: .\"
3: .\" Copyright (c) 1985, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.12 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
30: .\" @(#)tset.1 8.1 (Berkeley) 6/9/93
31: .\"
1.24 ! jmc 32: .Dd $Mdocdate: March 31 2022 $
1.1 deraadt 33: .Dt TSET 1
1.6 millert 34: .Os
1.1 deraadt 35: .Sh NAME
1.21 jmc 36: .Nm tset ,
37: .Nm reset
1.1 deraadt 38: .Nd terminal initialization
39: .Sh SYNOPSIS
40: .Nm tset
1.19 millert 41: .Op Fl cIQqrsVw
1.1 deraadt 42: .Op Fl
43: .Op Fl e Ar ch
44: .Op Fl i Ar ch
45: .Op Fl k Ar ch
46: .Op Fl m Ar mapping
47: .Op Ar terminal
48: .Nm reset
1.19 millert 49: .Op Fl cIQqrsVw
1.1 deraadt 50: .Op Fl
51: .Op Fl e Ar ch
52: .Op Fl i Ar ch
53: .Op Fl k Ar ch
54: .Op Fl m Ar mapping
55: .Op Ar terminal
56: .Sh DESCRIPTION
1.5 aaron 57: .Nm tset
1.1 deraadt 58: initializes terminals.
1.5 aaron 59: .Nm tset
1.1 deraadt 60: first determines the type of terminal that you are using.
1.5 aaron 61: This determination is done as follows, using the first terminal type found:
1.6 millert 62: .Bl -enum -offset indent
1.1 deraadt 63: .It
64: The
65: .Ar terminal
66: argument specified on the command line.
67: .It
68: The value of the
69: .Ev TERM
1.2 deraadt 70: environment variable.
1.1 deraadt 71: .It
72: The terminal type associated with the standard error output device in the
73: .Pa /etc/ttys
74: file.
75: .It
1.6 millert 76: The default terminal type,
77: .Dq unknown .
1.1 deraadt 78: .El
79: .Pp
1.7 aaron 80: If the terminal type was not specified on the command line, the
1.1 deraadt 81: .Fl m
1.19 millert 82: option mappings are then applied (see the
83: .Sx TERMINAL TYPE MAPPING
84: section below for more information).
1.7 aaron 85: Then, if the terminal type begins with a question mark
1.14 jmc 86: .Pq Ql \&? ,
1.7 aaron 87: the user is prompted for confirmation of the terminal type.
1.11 henning 88: An empty response confirms the type, or another type can be entered to
1.1 deraadt 89: specify a new type.
1.19 millert 90: Once the terminal type has been determined, the terminfo entry for the terminal
1.1 deraadt 91: is retrieved.
1.19 millert 92: If no terminfo entry is found for the type, the user is prompted for another
1.1 deraadt 93: terminal type.
94: .Pp
1.19 millert 95: Once the terminfo entry is retrieved, the window size, backspace, interrupt,
1.1 deraadt 96: and line kill characters (among many other things) are set and the terminal
97: and tab initialization strings are sent to the standard error output.
98: Finally, if the erase, interrupt and line kill characters have changed,
99: or are not set to their default values, their values are displayed to the
100: standard error output.
1.17 nicm 101: Use the
102: .Fl c
103: or
104: .Fl w
105: option to select only the window sizing versus the other initialization.
106: If neither option is given, both are assumed.
1.1 deraadt 107: .Pp
108: When invoked as
109: .Nm reset ,
110: .Nm tset
111: sets cooked and echo modes, turns off cbreak and raw modes, turns on
112: newline translation and resets any unset special characters to their
113: default values before doing the terminal initialization described above.
1.5 aaron 114: This is useful after a program dies leaving a terminal in an abnormal state.
1.1 deraadt 115: Note, you may have to type
1.7 aaron 116: .Dq <LF>reset<LF>
1.1 deraadt 117: (the line-feed character is normally control-J) to get the terminal
118: to work, as carriage-return may no longer work in the abnormal state.
119: Also, the terminal will often not echo the command.
120: .Pp
121: The options are as follows:
1.10 aaron 122: .Bl -tag -width Ds
1.1 deraadt 123: .It Fl
124: The terminal type is displayed to the standard output, and the terminal is
1.7 aaron 125: not initialized in any way.
126: This option has been deprecated in favor of the
1.6 millert 127: .Fl q
128: flag.
1.17 nicm 129: .It Fl c
130: Set control characters and modes.
1.5 aaron 131: .It Fl e Ar ch
1.1 deraadt 132: Set the erase character to
133: .Ar ch .
134: .It Fl I
135: Do not send the terminal or tab initialization strings to the terminal.
1.5 aaron 136: .It Fl i Ar ch
1.1 deraadt 137: Set the interrupt character to
138: .Ar ch .
1.5 aaron 139: .It Fl k Ar ch
1.1 deraadt 140: Set the line kill character to
141: .Ar ch .
1.5 aaron 142: .It Fl m Ar mapping
1.1 deraadt 143: Specify a mapping from a port type to a terminal.
1.19 millert 144: See the
145: .Sx TERMINAL TYPE MAPPING
146: section below for more information.
1.1 deraadt 147: .It Fl Q
148: Don't display any values for the erase, interrupt and line kill characters.
1.17 nicm 149: Normally
150: .Nm
151: displays the values for control characters which differ from the system's
152: default values.
1.6 millert 153: .It Fl q
154: The terminal type is displayed to the standard output, and the terminal is
155: not initialized in any way.
1.1 deraadt 156: .It Fl r
157: Print the terminal type to the standard error output.
158: .It Fl s
1.19 millert 159: Print the sequence of shell commands to initialize the environment variable
1.1 deraadt 160: .Ev TERM
161: to the standard output.
1.19 millert 162: See the
163: .Sx SETTING THE ENVIRONMENT
164: section below for details.
1.9 millert 165: .It Fl V
166: Report the version of ncurses which was used in this program, and exit.
1.17 nicm 167: .It Fl w
168: Resize the window to match the size deduced via
169: .Xr setupterm 3 .
170: Normally this has no effect, unless
171: .Xr setupterm 3
172: is not able to detect the window size.
1.1 deraadt 173: .El
174: .Pp
175: The arguments for the
176: .Fl e ,
1.7 aaron 177: .Fl i ,
1.1 deraadt 178: and
179: .Fl k
180: options may either be entered as actual characters or by using the
181: .Dq hat
1.7 aaron 182: notation, i.e., control-H may be specified as
183: .Dq ^H
1.1 deraadt 184: or
1.7 aaron 185: .Dq ^h .
1.1 deraadt 186: .Sh SETTING THE ENVIRONMENT
187: It is often desirable to enter the terminal type and information about
188: the terminal's capabilities into the shell's environment.
189: This is done using the
190: .Fl s
1.19 millert 191: option.
1.1 deraadt 192: .Pp
193: When the
194: .Fl s
195: option is specified, the commands to enter the information into the
196: shell's environment are written to the standard output.
197: If the
198: .Ev SHELL
1.6 millert 199: environment variable ends in
200: .Dq csh ,
201: the commands are for
1.5 aaron 202: .Xr csh 1 ,
1.1 deraadt 203: otherwise, they are for
1.5 aaron 204: .Xr sh 1 .
1.1 deraadt 205: Note, the
1.5 aaron 206: .Xr csh 1
1.1 deraadt 207: commands set and unset the shell variable
208: .Dq noglob ,
209: leaving it unset.
210: The following line in the
211: .Pa .login
212: or
213: .Pa .profile
214: files will initialize the environment correctly:
215: .Bd -literal -offset indent
216: eval \`tset -s options ... \`
217: .Ed
218: .Sh TERMINAL TYPE MAPPING
219: When the terminal is not hardwired into the system (or the current system
1.5 aaron 220: information is incorrect), the terminal type derived from the
1.1 deraadt 221: .Pa /etc/ttys
222: file or the
223: .Ev TERM
1.2 deraadt 224: environment variable is often something generic like
1.1 deraadt 225: .Dq network ,
226: .Dq dialup ,
227: or
228: .Dq unknown .
229: When
230: .Nm tset
231: is used in a startup script
232: .Pf ( Pa .profile
233: for
234: .Xr sh 1
235: users or
236: .Pa .login
237: for
238: .Xr csh 1
1.23 naddy 239: users), it is often desirable to provide information about the type of
1.1 deraadt 240: terminal used on such ports.
1.6 millert 241: .Pp
1.1 deraadt 242: The purpose of the
243: .Fl m
244: option is to
245: .Dq map
246: from some set of conditions to a terminal type, that is, to
247: tell
1.20 bentley 248: .Nm tset :
249: .Do
250: If I'm on this port at a particular speed, guess that I'm on that
251: kind of terminal
252: .Dc .
1.1 deraadt 253: .Pp
254: The argument to the
255: .Fl m
256: option consists of an optional port type, an optional operator, an optional
1.7 aaron 257: baud rate specification, an optional colon
1.8 aaron 258: .Pq Ql \&:
1.7 aaron 259: character, and a terminal type.
1.1 deraadt 260: The port type is a string (delimited by either the operator or the colon
261: character).
262: The operator may be any combination of:
1.7 aaron 263: .Ql > ,
264: .Ql < ,
265: .Ql @ ,
1.1 deraadt 266: and
1.14 jmc 267: .Ql \&! ;
1.7 aaron 268: .Ql >
1.1 deraadt 269: means greater than,
1.7 aaron 270: .Ql <
1.1 deraadt 271: means less than,
1.7 aaron 272: .Ql @
1.5 aaron 273: means equal to,
1.1 deraadt 274: and
1.14 jmc 275: .Ql \&!
1.1 deraadt 276: inverts the sense of the test.
277: The baud rate is specified as a number and is compared with the speed
1.24 ! jmc 278: of the standard error output (which should be the controlling terminal).
1.1 deraadt 279: The terminal type is a string.
280: .Pp
281: If the terminal type is not specified on the command line, the
282: .Fl m
283: mappings are applied to the terminal type.
284: If the port type and baud rate match the mapping, the terminal type specified
285: in the mapping replaces the current type.
286: If more than one mapping is specified, the first applicable mapping is used.
287: .Pp
288: For example, consider the following mapping:
1.7 aaron 289: .Dq dialup>9600:vt100 .
1.1 deraadt 290: The port type is
1.7 aaron 291: .Dq dialup ,
1.1 deraadt 292: the operator is
1.7 aaron 293: .Dq > ,
1.1 deraadt 294: the baud rate specification is
1.7 aaron 295: .Dq 9600 ,
1.1 deraadt 296: and the terminal type is
1.7 aaron 297: .Dq vt100 .
1.1 deraadt 298: The result of this mapping is to specify that if the terminal type is
1.7 aaron 299: .Dq dialup ,
1.1 deraadt 300: and the baud rate is greater than 9600 baud, a terminal type of
1.7 aaron 301: .Dq vt100
1.1 deraadt 302: will be used.
303: .Pp
304: If no port type is specified, the terminal type will match any port type,
305: for example,
1.7 aaron 306: .Dq -m dialup:vt100 -m :?xterm
1.1 deraadt 307: will cause any dialup port, regardless of baud rate, to match the terminal
308: type
1.7 aaron 309: .Dq vt100 ,
1.1 deraadt 310: and any non-dialup port type to match the terminal type
1.7 aaron 311: .Dq ?xterm .
1.1 deraadt 312: Note, because of the leading question mark, the user will be
313: queried on a default port as to whether they are actually using an
314: .Ar xterm
315: terminal.
316: .Pp
317: No whitespace characters are permitted in the
318: .Fl m
319: option argument.
1.5 aaron 320: Also, to avoid problems with meta-characters, it is suggested that the entire
1.1 deraadt 321: .Fl m
322: option argument be placed within single quote characters, and that
1.5 aaron 323: .Xr csh 1
1.7 aaron 324: users insert a backslash character
325: .Pq Ql \e
326: before any exclamation marks
1.14 jmc 327: .Pq Ql \&! .
1.1 deraadt 328: .Sh ENVIRONMENT
329: The
330: .Nm tset
331: command utilizes the
332: .Ev SHELL
333: and
334: .Ev TERM
335: environment variables.
336: .Sh FILES
1.22 nicm 337: .Bl -tag -width /usr/share/terminfo -compact
1.1 deraadt 338: .It Pa /etc/ttys
1.7 aaron 339: port name to terminal type mapping database
1.22 nicm 340: .It Pa /usr/share/terminfo
1.1 deraadt 341: terminal capability database
342: .El
343: .Sh SEE ALSO
344: .Xr csh 1 ,
345: .Xr sh 1 ,
346: .Xr stty 1 ,
347: .Xr tty 4 ,
1.19 millert 348: .Xr terminfo 5 ,
1.1 deraadt 349: .Xr ttys 5 ,
350: .Xr environ 7
1.13 jmc 351: .Sh STANDARDS
1.6 millert 352: The
353: .Nm tset
354: command now uses the
355: .Xr terminfo 5
356: database where previous versions used
357: .Xr termcap 5 .
1.19 millert 358: .Pp
359: Historic versions of the
360: .Xr termcap 3
361: library limited entries to 1023 bytes.
362: Modern
363: .Xr terminfo 3
364: entries are often much larger, making it impossible to
365: store the full entry in the
366: .Ev TERMCAP
367: environment variable.
368: Because of this, the
369: .Fl S
370: option is no longer supported (it prints an error message to the standard
371: error and exits) and the
1.6 millert 372: .Fl s
1.19 millert 373: option only sets
374: .Ev TERM ,
375: not
376: .Ev TERMCAP .
1.6 millert 377: .Pp
1.1 deraadt 378: The
379: .Fl A ,
380: .Fl E ,
381: .Fl h ,
1.5 aaron 382: .Fl u ,
1.1 deraadt 383: and
384: .Fl v
385: options have been deleted from the
386: .Nm tset
387: utility.
1.4 mickey 388: None of them were documented in
389: .Bx 4.3
390: and all are of limited utility at best.
1.1 deraadt 391: The
392: .Fl a ,
393: .Fl d
394: and
395: .Fl p
396: options are similarly not documented or useful, but were retained as they
397: appear to be in widespread use.
398: It is strongly recommended that any usage of these three options be
399: changed to use the
400: .Fl m
401: option instead.
402: The
403: .Fl n
404: option remains, but has no effect.
405: It is still permissible to specify the
406: .Fl e ,
407: .Fl i
408: and
409: .Fl k
410: options without arguments, although it is strongly recommended that such
411: usage be fixed to explicitly specify the character.
412: .Pp
413: Executing
414: .Nm tset
415: as
416: .Nm reset
417: no longer implies the
418: .Fl Q
419: option.
420: Also, the interaction between the
421: .Fl
422: option and the
423: .Ar terminal
424: argument in some historic implementations of
425: .Nm tset
426: has been removed.
427: .Pp
428: Finally, the
429: .Nm tset
430: implementation has been completely redone (as part of the addition to the
431: system of a
432: .St -p1003.1-88
433: compliant terminal interface) and will no longer compile on systems with
434: older terminal interfaces.
1.7 aaron 435: .Sh HISTORY
436: The
437: .Nm tset
1.18 schwarze 438: and
439: .Nm reset
440: utilities first appeared in
441: .Bx 1 .
442: .Sh AUTHORS
443: .An -nosplit
444: The original version of
445: .Nm tset
446: was written by
447: .An Eric P. Allman
448: in October 1977, and
449: .Nm reset
450: was originally written by
451: .An Kurt Shoens .
452: The current version also contains code by
453: .An Zeyd M. Ben-Halim ,
454: .An Eric S. Raymond ,
455: and
456: .An Thomas E. Dickey .