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