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