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