Annotation of src/usr.bin/tset/tset.1, Revision 1.25
1.25 ! nicm 1: .\" $OpenBSD: tset.1,v 1.24 2022/10/13 21:37:05 jmc Exp $
1.1 deraadt 2: .\"
1.25 ! nicm 3: .\"***************************************************************************
! 4: .\" Copyright 2018-2022,2023 Thomas E. Dickey *
! 5: .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
! 6: .\" *
! 7: .\" Permission is hereby granted, free of charge, to any person obtaining a *
! 8: .\" copy of this software and associated documentation files (the *
! 9: .\" "Software"), to deal in the Software without restriction, including *
! 10: .\" without limitation the rights to use, copy, modify, merge, publish, *
! 11: .\" distribute, distribute with modifications, sublicense, and/or sell *
! 12: .\" copies of the Software, and to permit persons to whom the Software is *
! 13: .\" furnished to do so, subject to the following conditions: *
! 14: .\" *
! 15: .\" The above copyright notice and this permission notice shall be included *
! 16: .\" in all copies or substantial portions of the Software. *
! 17: .\" *
! 18: .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
! 19: .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
! 20: .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
! 21: .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
! 22: .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
! 23: .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
! 24: .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
! 25: .\" *
! 26: .\" Except as contained in this notice, the name(s) of the above copyright *
! 27: .\" holders shall not be used in advertising or otherwise to promote the *
! 28: .\" sale, use or other dealings in this Software without prior written *
! 29: .\" authorization. *
! 30: .\"***************************************************************************
1.1 deraadt 31: .\"
1.25 ! nicm 32:
! 33: .TH tset 1 2023-07-01 "ncurses 6.4" "User commands"
! 34: .ie \n(.g .ds `` \(lq
! 35: .el .ds `` ``
! 36: .ie \n(.g .ds '' \(rq
! 37: .el .ds '' ''
! 38: .de bP
! 39: .ie n .IP \(bu 4
! 40: .el .IP \(bu 2
! 41: ..
! 42: .SH NAME
! 43: \fBtset\fP, \fB?\fP \- terminal initialization
! 44: .SH SYNOPSIS
! 45: \fBtset\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal\fP]
! 46: .br
! 47: \fB?\fP [\fB\-IQVcqrsw\fP] [\fB\-\fP] [\fB\-e\fP \fIch\fP] [\fB\-i\fP \fIch\fP] [\fB\-k\fP \fIch\fP] [\fB\-m\fP \fImapping\fP] [\fIterminal\fP]
! 48: .SH DESCRIPTION
! 49: .SS tset - initialization
! 50: This program initializes terminals.
! 51: .PP
! 52: First, \fBtset\fP retrieves the current terminal mode settings
! 53: for your terminal.
! 54: It does this by successively testing
! 55: .bP
! 56: the standard error,
! 57: .bP
! 58: standard output,
! 59: .bP
! 60: standard input and
! 61: .bP
! 62: ultimately \*(``/dev/tty\*(''
! 63: .PP
! 64: to obtain terminal settings.
! 65: Having retrieved these settings, \fBtset\fP remembers which
! 66: file descriptor to use when updating settings.
! 67: .PP
! 68: Next, \fBtset\fP determines the type of terminal that you are using.
! 69: This determination is done as follows, using the first terminal type found.
! 70: .PP
! 71: 1. The \fBterminal\fP argument specified on the command line.
! 72: .PP
! 73: 2. The value of the \fBTERM\fP environmental variable.
! 74: .PP
! 75: 3. (BSD systems only.) The terminal type associated with the standard
! 76: error output device in the \fI/etc/ttys\fP file.
! 77: (On System\-V-like UNIXes and systems using that convention,
! 78: \fBgetty\fP(1) does this job by setting
! 79: \fBTERM\fP according to the type passed to it by \fI/etc/inittab\fP.)
! 80: .PP
! 81: 4. The default terminal type, \*(``unknown\*('',
! 82: is not suitable for curses applications.
! 83: .PP
! 84: If the terminal type was not specified on the command-line, the \fB\-m\fP
! 85: option mappings are then applied (see the section
! 86: .B TERMINAL TYPE MAPPING
! 87: for more information).
! 88: Then, if the terminal type begins with a question mark (\*(``?\*(''), the
! 89: user is prompted for confirmation of the terminal type.
! 90: An empty
! 91: response confirms the type, or, another type can be entered to specify
! 92: a new type.
! 93: Once the terminal type has been determined,
! 94: the terminal description for the terminal is retrieved.
! 95: If no terminal description is found
! 96: for the type, the user is prompted for another terminal type.
! 97: .PP
! 98: Once the terminal description is retrieved,
! 99: .bP
! 100: if the \*(``\fB\-w\fP\*('' option is enabled, \fBtset\fP may update
! 101: the terminal's window size.
! 102: .IP
! 103: If the window size cannot be obtained from the operating system,
! 104: but the terminal description (or environment, e.g., \fBLINES\fP
! 105: and \fBCOLUMNS\fP variables specify this),
! 106: use this to set the operating system's notion of the window size.
! 107: .bP
! 108: if the \*(``\fB\-c\fP\*('' option is enabled,
! 109: the backspace, interrupt and line kill characters
! 110: (among many other things) are set
! 111: .bP
! 112: unless the \*(``\fB\-I\fP\*('' option is enabled,
! 113: the terminal
! 114: and tab \fIinitialization\fP strings are sent to the standard error output,
! 115: and \fBtset\fP waits one second (in case a hardware reset was issued).
! 116: .bP
1.1 deraadt 117: Finally, if the erase, interrupt and line kill characters have changed,
118: or are not set to their default values, their values are displayed to the
119: standard error output.
1.25 ! nicm 120: .SS reset - reinitialization
! 121: When invoked as \fB?\fP, \fBtset\fP sets the terminal
! 122: modes to \*(``sane\*('' values:
! 123: .bP
! 124: sets cooked and echo modes,
! 125: .bP
! 126: turns off cbreak and raw modes,
! 127: .bP
! 128: turns on newline translation and
! 129: .bP
! 130: resets any unset special characters to their default values
! 131: .PP
! 132: before
! 133: doing the terminal initialization described above.
! 134: Also, rather than using the terminal \fIinitialization\fP strings,
! 135: it uses the terminal \fIreset\fP strings.
! 136: .PP
! 137: The \fB?\fP command is useful
! 138: after a program dies leaving a terminal in an abnormal state:
! 139: .bP
! 140: you may have to type
! 141: .sp
! 142: \fI<LF>\fB?\fI<LF>\fR
! 143: .sp
1.1 deraadt 144: (the line-feed character is normally control-J) to get the terminal
145: to work, as carriage-return may no longer work in the abnormal state.
1.25 ! nicm 146: .bP
1.1 deraadt 147: Also, the terminal will often not echo the command.
1.25 ! nicm 148: .SH OPTIONS
1.1 deraadt 149: The options are as follows:
1.25 ! nicm 150: .TP 5
! 151: .B \-c
1.17 nicm 152: Set control characters and modes.
1.25 ! nicm 153: .TP 5
! 154: .BI \-e\ ch
! 155: Set the erase character to \fIch\fP.
! 156: .TP
! 157: .B \-I
1.1 deraadt 158: Do not send the terminal or tab initialization strings to the terminal.
1.25 ! nicm 159: .TP
! 160: .BI \-i\ ch
! 161: Set the interrupt character to \fIch\fP.
! 162: .TP
! 163: .BI \-k\ ch
! 164: Set the line kill character to \fIch\fP.
! 165: .TP
! 166: .BI \-m\ mapping
1.1 deraadt 167: Specify a mapping from a port type to a terminal.
1.25 ! nicm 168: See the section
! 169: .B TERMINAL TYPE MAPPING
! 170: for more information.
! 171: .TP
! 172: .B \-Q
! 173: Do not display any values for the erase, interrupt and line kill characters.
! 174: Normally \fBtset\fP displays the values for control characters which
! 175: differ from the system's default values.
! 176: .TP
! 177: .B \-q
1.6 millert 178: The terminal type is displayed to the standard output, and the terminal is
179: not initialized in any way.
1.25 ! nicm 180: The option \*(``\-\*('' by itself is equivalent but archaic.
! 181: .TP
! 182: .B \-r
1.1 deraadt 183: Print the terminal type to the standard error output.
1.25 ! nicm 184: .TP
! 185: .B \-s
1.19 millert 186: Print the sequence of shell commands to initialize the environment variable
1.25 ! nicm 187: \fBTERM\fP to the standard output.
! 188: See the section
! 189: .B SETTING THE ENVIRONMENT
! 190: for details.
! 191: .TP
! 192: .B \-V
! 193: reports the version of ncurses which was used in this program, and exits.
! 194: .TP
! 195: .B \-w
! 196: Resize the window to match the size deduced via \fBsetupterm\fP(3).
! 197: Normally this has no effect,
! 198: unless \fBsetupterm\fP is not able to detect the window size.
! 199: .PP
! 200: The arguments for the \fB\-e\fP, \fB\-i\fP, and \fB\-k\fP
! 201: options may either be entered as actual characters
! 202: or by using the \*(``hat\*(''
! 203: notation, i.e., control-h may be specified as \*(``^H\*('' or \*(``^h\*(''.
! 204: .PP
! 205: If neither \fB\-c\fP or \fB\-w\fP is given, both options are assumed.
! 206: .
! 207: .SH SETTING THE ENVIRONMENT
1.1 deraadt 208: It is often desirable to enter the terminal type and information about
209: the terminal's capabilities into the shell's environment.
1.25 ! nicm 210: This is done using the \fB\-s\fP option.
! 211: .PP
! 212: When the \fB\-s\fP option is specified, the commands to enter the information
! 213: into the shell's environment are written to the standard output.
! 214: If
! 215: the \fBSHELL\fP environmental variable ends in \*(``csh\*('', the commands
! 216: are for \fBcsh\fP, otherwise, they are for \fBsh\fP(1).
! 217: Note, the \fBcsh\fP commands set and unset the shell variable
! 218: \fBnoglob\fP, leaving it unset.
! 219: The following line in the \fB.login\fP
! 220: or \fB.profile\fP files will initialize the environment correctly:
! 221: .sp
! 222: eval \`tset \-s options ... \`
! 223: .
! 224: .SH TERMINAL TYPE MAPPING
! 225: When the terminal is not hardwired into the system (or the current
! 226: system information is incorrect) the terminal type derived from the
! 227: \fI/etc/ttys\fP file or the \fBTERM\fP environmental variable is often
! 228: something generic like \fBnetwork\fP, \fBdialup\fP, or \fBunknown\fP.
! 229: When \fBtset\fP is used in a startup script it is often desirable to
! 230: provide information about the type of terminal used on such ports.
! 231: .PP
! 232: The \fB\-m\fP options maps
1.1 deraadt 233: from some set of conditions to a terminal type, that is, to
1.25 ! nicm 234: tell \fBtset\fP
! 235: \*(``If I'm on this port at a particular speed,
! 236: guess that I'm on that kind of terminal\*(''.
! 237: .PP
! 238: The argument to the \fB\-m\fP option consists of an optional port type, an
! 239: optional operator, an optional baud rate specification, an optional
! 240: colon (\*(``:\*('') character and a terminal type.
! 241: The port type is a
! 242: string (delimited by either the operator or the colon character).
! 243: The operator may be any combination of
! 244: \*(``>\*('',
! 245: \*(``<\*('',
! 246: \*(``@\*('',
! 247: and \*(``!\*('';
! 248: \*(``>\*('' means greater than,
! 249: \*(``<\*('' means less than,
! 250: \*(``@\*('' means equal to and
! 251: \*(``!\*('' inverts the sense of the test.
1.1 deraadt 252: The baud rate is specified as a number and is compared with the speed
1.25 ! nicm 253: of the standard error output (which should be the control terminal).
1.1 deraadt 254: The terminal type is a string.
1.25 ! nicm 255: .PP
! 256: If the terminal type is not specified on the command line, the \fB\-m\fP
1.1 deraadt 257: mappings are applied to the terminal type.
1.25 ! nicm 258: If the port type and baud
! 259: rate match the mapping, the terminal type specified in the mapping
! 260: replaces the current type.
! 261: If more than one mapping is specified, the
! 262: first applicable mapping is used.
! 263: .PP
! 264: For example, consider the following mapping: \fBdialup>9600:vt100\fP.
! 265: The port type is dialup , the operator is >, the baud rate
! 266: specification is 9600, and the terminal type is vt100.
! 267: The result of
! 268: this mapping is to specify that if the terminal type is \fBdialup\fP,
1.1 deraadt 269: and the baud rate is greater than 9600 baud, a terminal type of
1.25 ! nicm 270: \fBvt100\fP will be used.
! 271: .PP
! 272: If no baud rate is specified, the terminal type will match any baud rate.
! 273: If no port type is specified, the terminal type will match any port type.
! 274: For example, \fB\-m dialup:vt100 \-m :?xterm\fP
1.1 deraadt 275: will cause any dialup port, regardless of baud rate, to match the terminal
1.25 ! nicm 276: type vt100, and any non-dialup port type to match the terminal type ?xterm.
1.1 deraadt 277: Note, because of the leading question mark, the user will be
1.25 ! nicm 278: queried on a default port as to whether they are actually using an xterm
1.1 deraadt 279: terminal.
1.25 ! nicm 280: .PP
! 281: No whitespace characters are permitted in the \fB\-m\fP option argument.
! 282: Also, to avoid problems with meta-characters, it is suggested that the
! 283: entire \fB\-m\fP option argument be placed within single quote characters,
! 284: and that \fBcsh\fP users insert a backslash character (\*(``\e\*('') before
! 285: any exclamation marks (\*(``!\*('').
! 286: .SH HISTORY
! 287: A \fBreset\fP command appeared in 1BSD (March 1978), written by Kurt Shoens.
! 288: This program set the \fIerase\fP and \fIkill\fP characters
! 289: to \fB^H\fP (backspace) and \fB@\fP respectively.
! 290: Mark Horton improved that in 3BSD (October 1979), adding
! 291: \fIintr\fP, \fIquit\fP, \fIstart\fP/\fIstop\fP and \fIeof\fP characters
! 292: as well as changing the program to avoid modifying any user settings.
! 293: That version of \fBreset\fP did not use the termcap database.
! 294: .PP
! 295: A separate \fBtset\fP command was provided in 1BSD by Eric Allman,
! 296: using the termcap database.
! 297: Allman's comments in the source code indicate
! 298: that he began work in October 1977,
! 299: continuing development over the next few years.
! 300: .PP
! 301: According to comments in the source code,
! 302: the \fBtset\fP program was modified in September 1980,
! 303: to use logic copied from the 3BSD \*(``reset\*(''
! 304: when it was invoked as \fBreset\fP.
! 305: This version appeared in 4.1cBSD, late in 1982.
! 306: .PP
! 307: Other developers (e.g., Keith Bostic and Jim Bloom)
! 308: continued to modify \fBtset\fP until 4.4BSD was released in 1993.
! 309: .PP
! 310: The \fBncurses\fP implementation
! 311: was lightly adapted from the 4.4BSD sources for a terminfo environment by Eric
! 312: S. Raymond <esr@snark.thyrsus.com>.
! 313: .SH COMPATIBILITY
! 314: Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
! 315: (POSIX.1-2008) nor
! 316: X/Open Curses Issue 7 documents \fBtset\fP or \fB?\fP.
! 317: .PP
! 318: The AT&T \fBtput\fP utility (AIX, HPUX, Solaris)
! 319: incorporated the terminal-mode manipulation as well as termcap-based features
! 320: such as resetting tabstops from \fBtset\fP in BSD (4.1c),
! 321: presumably with the intention of making \fBtset\fP obsolete.
! 322: However, each of those systems still provides \fBtset\fP.
! 323: In fact, the commonly-used \fBreset\fP utility
! 324: is always an alias for \fBtset\fP.
! 325: .PP
! 326: The \fBtset\fP utility provides for backward-compatibility with BSD
! 327: environments (under most modern UNIXes, \fB/etc/inittab\fP and \fBgetty\fP(1)
! 328: can set \fBTERM\fP appropriately for each dial-up line; this obviates what was
! 329: \fBtset\fP's most important use).
! 330: This implementation behaves like 4.4BSD
! 331: \fBtset\fP, with a few exceptions specified here.
! 332: .PP
! 333: A few options are different
! 334: because the \fBTERMCAP\fP variable
! 335: is no longer supported under terminfo-based \fBncurses\fP:
! 336: .bP
! 337: The \fB\-S\fP option of BSD \fBtset\fP no longer works;
! 338: it prints an error message to the standard error and dies.
! 339: .bP
! 340: The \fB\-s\fP option only sets \fBTERM\fP, not \fBTERMCAP\fP.
! 341: .PP
! 342: There was an undocumented 4.4BSD feature
! 343: that invoking \fBtset\fP via a link named
! 344: \*(``TSET\*('' (or via any other name beginning with an upper-case letter)
! 345: set the terminal to use upper-case only.
! 346: This feature has been omitted.
! 347: .PP
! 348: The \fB\-A\fP, \fB\-E\fP, \fB\-h\fP, \fB\-u\fP and \fB\-v\fP
! 349: options were deleted from the \fBtset\fP
! 350: utility in 4.4BSD.
! 351: None of them were documented in 4.3BSD and all are
! 352: of limited utility at best.
! 353: The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options are similarly
! 354: not documented or useful, but were retained as they appear to be in
! 355: widespread use.
! 356: It is strongly recommended that any usage of these
! 357: three options be changed to use the \fB\-m\fP option instead.
! 358: The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP options
! 359: are therefore omitted from the usage summary above.
! 360: .PP
! 361: Very old systems, e.g., 3BSD, used a different terminal driver which
! 362: was replaced in 4BSD in the early 1980s.
! 363: To accommodate these older systems, the 4BSD \fBtset\fP provided a
! 364: \fB\-n\fP option to specify that the new terminal driver should be used.
! 365: This implementation does not provide that choice.
! 366: .PP
! 367: It is still permissible to specify the \fB\-e\fP, \fB\-i\fP,
! 368: and \fB\-k\fP options without arguments,
! 369: although it is strongly recommended that such usage be fixed to
! 370: explicitly specify the character.
! 371: .PP
! 372: As of 4.4BSD,
! 373: executing \fBtset\fP as \fB?\fP no longer implies the \fB\-Q\fP option.
! 374: Also, the interaction between the \- option and the \fIterminal\fP
! 375: argument in some historic implementations of \fBtset\fP has been removed.
! 376: .PP
! 377: The \fB\-c\fP and \fB\-w\fP options are not found in earlier implementations.
! 378: However, a different window size-change feature was provided in 4.4BSD.
! 379: .bP
! 380: In 4.4BSD, \fBtset\fP uses the window size from the termcap description
! 381: to set the window size if \fBtset\fP is not able to obtain the window
! 382: size from the operating system.
! 383: .bP
! 384: In ncurses, \fBtset\fP obtains the window size using
! 385: \fBsetupterm\fP, which may be from
! 386: the operating system,
! 387: the \fBLINES\fP and \fBCOLUMNS\fP environment variables or
! 388: the terminal description.
! 389: .PP
! 390: Obtaining the window size from the terminal description is common to
! 391: both implementations, but considered obsolescent.
! 392: Its only practical use is for hardware terminals.
! 393: Generally speaking, a window size would be unset only if there were
! 394: some problem obtaining the value from the operating system
! 395: (and \fBsetupterm\fP would still fail).
! 396: For that reason, the \fBLINES\fP and \fBCOLUMNS\fP environment variables
! 397: may be useful for working around window-size problems.
! 398: Those have the drawback that if the window is resized,
! 399: those variables must be recomputed and reassigned.
! 400: To do this more easily, use the \fBresize\fP(1) program.
! 401: .SH ENVIRONMENT
! 402: The \fBtset\fP command uses these environment variables:
! 403: .TP 5
! 404: SHELL
! 405: tells \fBtset\fP whether to initialize \fBTERM\fP using \fBsh\fP(1) or
! 406: \fBcsh\fP(1) syntax.
! 407: .TP 5
! 408: TERM
! 409: Denotes your terminal type.
! 410: Each terminal type is distinct, though many are similar.
! 411: .TP 5
! 412: TERMCAP
! 413: may denote the location of a termcap database.
! 414: If it is not an absolute pathname, e.g., begins with a \*(``/\*('',
! 415: \fBtset\fP removes the variable from the environment before looking
! 416: for the terminal description.
! 417: .SH FILES
! 418: .TP 5
! 419: /etc/ttys
! 420: system port name to terminal type mapping database (BSD versions only).
! 421: .TP
! 422: /usr/share/terminfo
1.1 deraadt 423: terminal capability database
1.25 ! nicm 424: .SH SEE ALSO
! 425: .hy 0
! 426: \fBcsh\fP(1),
! 427: \fBsh\fP(1),
! 428: \fBstty\fP(1),
! 429: \fBterminfo\fP(3),
! 430: \fBtty\fP(4),
! 431: \fBterminfo\fP(5),
! 432: \fBttys\fP(5),
! 433: \fBenviron\fP(7)
! 434: .hy
! 435: .PP
! 436: This describes \fBncurses\fP
! 437: version 6.4 (patch 20230826).
![[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