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