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