Annotation of src/usr.bin/tset/tset.1, Revision 1.1
1.1 ! deraadt 1: .\" $NetBSD: tset.1,v 1.4 1994/12/07 05:08:13 jtc Exp $
! 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
! 75: environmental variable.
! 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
! 188: environmental variable ends in ``csh'', the commands are for the
! 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
! 225: environmental variable is often something generic like
! 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.