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