man/tset.1

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