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