| .\"*************************************************************************** |
| .\" Copyright 2018-2020,2021 Thomas E. Dickey * |
| .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| .\" * |
| .\" Permission is hereby granted, free of charge, to any person obtaining a * |
| .\" copy of this software and associated documentation files (the * |
| .\" "Software"), to deal in the Software without restriction, including * |
| .\" without limitation the rights to use, copy, modify, merge, publish, * |
| .\" distribute, distribute with modifications, sublicense, and/or sell * |
| .\" copies of the Software, and to permit persons to whom the Software is * |
| .\" furnished to do so, subject to the following conditions: * |
| .\" * |
| .\" The above copyright notice and this permission notice shall be included * |
| .\" in all copies or substantial portions of the Software. * |
| .\" * |
| .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| .\" * |
| .\" Except as contained in this notice, the name(s) of the above copyright * |
| .\" holders shall not be used in advertising or otherwise to promote the * |
| .\" sale, use or other dealings in this Software without prior written * |
| .\" authorization. * |
| .\"*************************************************************************** |
| .\" |
| .\" $Id: tset.1,v 1.58 2021/09/18 21:21:55 tom Exp $ |
| .TH @TSET@ 1 "" |
| .ie \n(.g .ds `` \(lq |
| .el .ds `` `` |
| .ie \n(.g .ds '' \(rq |
| .el .ds '' '' |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .SH NAME |
| \fB@TSET@\fR, \fB@RESET@\fR \- terminal initialization |
| .SH SYNOPSIS |
| \fB@TSET@\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR] |
| .br |
| \fB@RESET@\fR [\fB\-IQVcqrsw\fR] [\fB\-\fR] [\fB\-e\fR \fIch\fR] [\fB\-i\fR \fIch\fR] [\fB\-k\fR \fIch\fR] [\fB\-m\fR \fImapping\fR] [\fIterminal\fR] |
| .SH DESCRIPTION |
| .SS tset - initialization |
| This program initializes terminals. |
| .PP |
| First, \fB@TSET@\fR retrieves the current terminal mode settings |
| for your terminal. |
| It does this by successively testing |
| .bP |
| the standard error, |
| .bP |
| standard output, |
| .bP |
| standard input and |
| .bP |
| ultimately \*(``/dev/tty\*('' |
| .PP |
| to obtain terminal settings. |
| Having retrieved these settings, \fB@TSET@\fP remembers which |
| file descriptor to use when updating settings. |
| .PP |
| Next, \fB@TSET@\fP determines the type of terminal that you are using. |
| This determination is done as follows, using the first terminal type found. |
| .PP |
| 1. The \fBterminal\fR argument specified on the command line. |
| .PP |
| 2. The value of the \fBTERM\fR environmental variable. |
| .PP |
| 3. (BSD systems only.) The terminal type associated with the standard |
| error output device in the \fI/etc/ttys\fR file. |
| (On System\-V-like UNIXes and systems using that convention, |
| \fIgetty\fR does this job by setting |
| \fBTERM\fR according to the type passed to it by \fI/etc/inittab\fR.) |
| .PP |
| 4. The default terminal type, \*(``unknown\*(''. |
| .PP |
| If the terminal type was not specified on the command-line, the \fB\-m\fR |
| option mappings are then applied (see the section |
| .B TERMINAL TYPE MAPPING |
| for more information). |
| Then, if the terminal type begins with a question mark (\*(``?\*(''), the |
| user is prompted for confirmation of the terminal type. |
| An empty |
| response confirms the type, or, another type can be entered to specify |
| a new type. |
| Once the terminal type has been determined, |
| the terminal description for the terminal is retrieved. |
| If no terminal description is found |
| for the type, the user is prompted for another terminal type. |
| .PP |
| Once the terminal description is retrieved, |
| .bP |
| if the \*(``\fB\-w\fP\*('' option is enabled, \fB@TSET@\fP may update |
| the terminal's window size. |
| .IP |
| If the window size cannot be obtained from the operating system, |
| but the terminal description (or environment, e.g., \fBLINES\fP |
| and \fBCOLUMNS\fP variables specify this), |
| use this to set the operating system's notion of the window size. |
| .bP |
| if the \*(``\fB\-c\fP\*('' option is enabled, |
| the backspace, interrupt and line kill characters |
| (among many other things) are set |
| .bP |
| unless the \*(``\fB\-I\fP\*('' option is enabled, |
| the terminal |
| and tab \fIinitialization\fP strings are sent to the standard error output, |
| and \fB@TSET@\fP waits one second (in case a hardware reset was issued). |
| .bP |
| Finally, if the erase, interrupt and line kill characters have changed, |
| or are not set to their default values, their values are displayed to the |
| standard error output. |
| .SS reset - reinitialization |
| .PP |
| When invoked as \fB@RESET@\fR, \fB@TSET@\fR sets the terminal |
| modes to \*(``sane\*('' values: |
| .bP |
| sets cooked and echo modes, |
| .bP |
| turns off cbreak and raw modes, |
| .bP |
| turns on newline translation and |
| .bP |
| resets any unset special characters to their default values |
| .PP |
| before |
| doing the terminal initialization described above. |
| Also, rather than using the terminal \fIinitialization\fP strings, |
| it uses the terminal \fIreset\fP strings. |
| .PP |
| The \fB@RESET@\fP command is useful |
| after a program dies leaving a terminal in an abnormal state: |
| .bP |
| you may have to type |
| .sp |
| \fI<LF>\fP\fB@RESET@\fP\fI<LF>\fP |
| .sp |
| (the line-feed character is normally control-J) to get the terminal |
| to work, as carriage-return may no longer work in the abnormal state. |
| .bP |
| Also, the terminal will often not echo the command. |
| .SH OPTIONS |
| .PP |
| The options are as follows: |
| .TP 5 |
| .B \-c |
| Set control characters and modes. |
| .TP 5 |
| .BI \-e\ ch |
| Set the erase character to \fIch\fR. |
| .TP |
| .B \-I |
| Do not send the terminal or tab initialization strings to the terminal. |
| .TP |
| .BI \-i\ ch |
| Set the interrupt character to \fIch\fR. |
| .TP |
| .BI \-k\ ch |
| Set the line kill character to \fIch\fR. |
| .TP |
| .BI \-m\ mapping |
| Specify a mapping from a port type to a terminal. |
| See the section |
| .B TERMINAL TYPE MAPPING |
| for more information. |
| .TP |
| .B \-Q |
| Do not display any values for the erase, interrupt and line kill characters. |
| Normally \fB@TSET@\fR displays the values for control characters which |
| differ from the system's default values. |
| .TP |
| .B \-q |
| The terminal type is displayed to the standard output, and the terminal is |
| not initialized in any way. |
| The option \*(``\-\*('' by itself is equivalent but archaic. |
| .TP |
| .B \-r |
| Print the terminal type to the standard error output. |
| .TP |
| .B \-s |
| Print the sequence of shell commands to initialize the environment variable |
| \fBTERM\fR to the standard output. |
| See the section |
| .B SETTING THE ENVIRONMENT |
| for details. |
| .TP |
| .B \-V |
| reports the version of ncurses which was used in this program, and exits. |
| .TP |
| .B \-w |
| Resize the window to match the size deduced via \fBsetupterm\fP(3X). |
| Normally this has no effect, |
| unless \fBsetupterm\fP is not able to detect the window size. |
| .PP |
| The arguments for the \fB\-e\fR, \fB\-i\fR, and \fB\-k\fR |
| options may either be entered as actual characters |
| or by using the \*(``hat\*('' |
| notation, i.e., control-h may be specified as \*(``^H\*('' or \*(``^h\*(''. |
| .PP |
| If neither \fB\-c\fP or \fB\-w\fP is given, both options are assumed. |
| . |
| .SH SETTING THE ENVIRONMENT |
| It is often desirable to enter the terminal type and information about |
| the terminal's capabilities into the shell's environment. |
| This is done using the \fB\-s\fR option. |
| .PP |
| When the \fB\-s\fR option is specified, the commands to enter the information |
| into the shell's environment are written to the standard output. |
| If |
| the \fBSHELL\fR environmental variable ends in \*(``csh\*('', the commands |
| are for \fBcsh\fR, otherwise, they are for \fBsh\fR. |
| Note, the \fBcsh\fR commands set and unset the shell variable |
| \fBnoglob\fR, leaving it unset. |
| The following line in the \fB.login\fR |
| or \fB.profile\fR files will initialize the environment correctly: |
| .sp |
| eval \`@TSET@ \-s options ... \` |
| . |
| .SH TERMINAL TYPE MAPPING |
| When the terminal is not hardwired into the system (or the current |
| system information is incorrect) the terminal type derived from the |
| \fI/etc/ttys\fR file or the \fBTERM\fR environmental variable is often |
| something generic like \fBnetwork\fR, \fBdialup\fR, or \fBunknown\fR. |
| When \fB@TSET@\fR is used in a startup script it is often desirable to |
| provide information about the type of terminal used on such ports. |
| .PP |
| The \fB\-m\fR options maps |
| from some set of conditions to a terminal type, that is, to |
| tell \fB@TSET@\fR |
| \*(``If I'm on this port at a particular speed, |
| guess that I'm on that kind of terminal\*(''. |
| .PP |
| The argument to the \fB\-m\fR option consists of an optional port type, an |
| optional operator, an optional baud rate specification, an optional |
| colon (\*(``:\*('') character and a terminal type. |
| The port type is a |
| string (delimited by either the operator or the colon character). |
| The operator may be any combination of |
| \*(``>\*('', |
| \*(``<\*('', |
| \*(``@\*('', |
| and \*(``!\*(''; |
| \*(``>\*('' means greater than, |
| \*(``<\*('' means less than, |
| \*(``@\*('' means equal to and |
| \*(``!\*('' inverts the sense of the test. |
| The baud rate is specified as a number and is compared with the speed |
| of the standard error output (which should be the control terminal). |
| The terminal type is a string. |
| .PP |
| If the terminal type is not specified on the command line, the \fB\-m\fR |
| mappings are applied to the terminal type. |
| If the port type and baud |
| rate match the mapping, the terminal type specified in the mapping |
| replaces the current type. |
| If more than one mapping is specified, the |
| first applicable mapping is used. |
| .PP |
| For example, consider the following mapping: \fBdialup>9600:vt100\fR. |
| The port type is dialup , the operator is >, the baud rate |
| specification is 9600, and the terminal type is vt100. |
| The result of |
| this mapping is to specify that if the terminal type is \fBdialup\fR, |
| and the baud rate is greater than 9600 baud, a terminal type of |
| \fBvt100\fR will be used. |
| .PP |
| If no baud rate is specified, the terminal type will match any baud rate. |
| If no port type is specified, the terminal type will match any port type. |
| For example, \fB\-m dialup:vt100 \-m :?xterm\fR |
| will cause any dialup port, regardless of baud rate, to match the terminal |
| type vt100, and any non-dialup port type to match the terminal type ?xterm. |
| Note, because of the leading question mark, the user will be |
| queried on a default port as to whether they are actually using an xterm |
| terminal. |
| .PP |
| No whitespace characters are permitted in the \fB\-m\fR option argument. |
| Also, to avoid problems with meta-characters, it is suggested that the |
| entire \fB\-m\fR option argument be placed within single quote characters, |
| and that \fBcsh\fR users insert a backslash character (\*(``\e\*('') before |
| any exclamation marks (\*(``!\*(''). |
| .SH HISTORY |
| .PP |
| A \fBreset\fP command appeared in 1BSD (March 1978), written by Kurt Shoens. |
| This program set the \fIerase\fP and \fIkill\fP characters |
| to \fB^H\fP (backspace) and \fB@\fP respectively. |
| Mark Horton improved that in 3BSD (October 1979), adding |
| \fIintr\fP, \fIquit\fP, \fIstart\fP/\fIstop\fP and \fIeof\fP characters |
| as well as changing the program to avoid modifying any user settings. |
| That version of \fBreset\fP did not use the termcap database. |
| .PP |
| A separate \fBtset\fP command was provided in 1BSD by Eric Allman, |
| using the termcap database. |
| Allman's comments in the source code indicate |
| that he began work in October 1977, |
| continuing development over the next few years. |
| .PP |
| According to comments in the source code, |
| the \fBtset\fP program was modified in September 1980, |
| to use logic copied from the 3BSD \*(``reset\*('' |
| when it was invoked as \fBreset\fP. |
| This version appeared in 4.1cBSD, late in 1982. |
| .PP |
| Other developers (e.g., Keith Bostic and Jim Bloom) |
| continued to modify \fBtset\fP until 4.4BSD was released in 1993. |
| .PP |
| The \fBncurses\fR implementation |
| was lightly adapted from the 4.4BSD sources for a terminfo environment by Eric |
| S. Raymond <esr@snark.thyrsus.com>. |
| .SH COMPATIBILITY |
| .PP |
| Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 |
| (POSIX.1-2008) nor |
| X/Open Curses Issue 7 documents \fB@TSET@\fP or \fB@RESET@\fP. |
| .PP |
| The AT&T \fBtput\fP utility (AIX, HPUX, Solaris) |
| incorporated the terminal-mode manipulation as well as termcap-based features |
| such as resetting tabstops from \fBtset\fP in BSD (4.1c), |
| presumably with the intention of making \fBtset\fP obsolete. |
| However, each of those systems still provides \fBtset\fP. |
| In fact, the commonly-used \fBreset\fP utility |
| is always an alias for \fBtset\fP. |
| .PP |
| The \fB@TSET@\fR utility provides for backward-compatibility with BSD |
| environments (under most modern UNIXes, \fB/etc/inittab\fR and \fBgetty\fR(1) |
| can set \fBTERM\fR appropriately for each dial-up line; this obviates what was |
| \fB@TSET@\fR's most important use). |
| This implementation behaves like 4.4BSD |
| \fBtset\fP, with a few exceptions specified here. |
| .PP |
| A few options are different |
| because the \fBTERMCAP\fR variable |
| is no longer supported under terminfo-based \fBncurses\fR: |
| .bP |
| The \fB\-S\fR option of BSD \fBtset\fP no longer works; |
| it prints an error message to the standard error and dies. |
| .bP |
| The \fB\-s\fR option only sets \fBTERM\fR, not \fBTERMCAP\fP. |
| .PP |
| There was an undocumented 4.4BSD feature |
| that invoking \fBtset\fP via a link named |
| \*(``TSET\*('' (or via any other name beginning with an upper-case letter) |
| set the terminal to use upper-case only. |
| This feature has been omitted. |
| .PP |
| The \fB\-A\fR, \fB\-E\fR, \fB\-h\fR, \fB\-u\fR and \fB\-v\fR |
| options were deleted from the \fB@TSET@\fR |
| utility in 4.4BSD. |
| None of them were documented in 4.3BSD and all are |
| of limited utility at best. |
| The \fB\-a\fR, \fB\-d\fR, and \fB\-p\fR options are similarly |
| not documented or useful, but were retained as they appear to be in |
| widespread use. |
| It is strongly recommended that any usage of these |
| three options be changed to use the \fB\-m\fR option instead. |
| The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fR options |
| are therefore omitted from the usage summary above. |
| .PP |
| Very old systems, e.g., 3BSD, used a different terminal driver which |
| was replaced in 4BSD in the early 1980s. |
| To accommodate these older systems, the 4BSD \fB@TSET@\fP provided a |
| \fB\-n\fP option to specify that the new terminal driver should be used. |
| This implementation does not provide that choice. |
| .PP |
| It is still permissible to specify the \fB\-e\fR, \fB\-i\fR, |
| and \fB\-k\fR options without arguments, |
| although it is strongly recommended that such usage be fixed to |
| explicitly specify the character. |
| .PP |
| As of 4.4BSD, |
| executing \fB@TSET@\fR as \fB@RESET@\fR no longer implies the \fB\-Q\fR option. |
| Also, the interaction between the \- option and the \fIterminal\fR |
| argument in some historic implementations of \fB@TSET@\fR has been removed. |
| .PP |
| The \fB\-c\fP and \fB\-w\fP options are not found in earlier implementations. |
| However, a different window size-change feature was provided in 4.4BSD. |
| .bP |
| In 4.4BSD, \fBtset\fP uses the window size from the termcap description |
| to set the window size if \fBtset\fP is not able to obtain the window |
| size from the operating system. |
| .bP |
| In ncurses, \fB@TSET@\fR obtains the window size using |
| \fBsetupterm\fP, which may be from |
| the operating system, |
| the \fBLINES\fP and \fBCOLUMNS\fP environment variables or |
| the terminal description. |
| .PP |
| Obtaining the window size from the terminal description is common to |
| both implementations, but considered obsolescent. |
| Its only practical use is for hardware terminals. |
| Generally speaking, a window size would be unset only if there were |
| some problem obtaining the value from the operating system |
| (and \fBsetupterm\fP would still fail). |
| For that reason, the \fBLINES\fP and \fBCOLUMNS\fP environment variables |
| may be useful for working around window-size problems. |
| Those have the drawback that if the window is resized, |
| those variables must be recomputed and reassigned. |
| To do this more easily, use the \fBresize\fP(1) program. |
| .SH ENVIRONMENT |
| The \fB@TSET@\fR command uses these environment variables: |
| .TP 5 |
| SHELL |
| tells \fB@TSET@\fP whether to initialize \fBTERM\fP using \fBsh\fP or |
| \fBcsh\fP syntax. |
| .TP 5 |
| TERM |
| Denotes your terminal type. |
| Each terminal type is distinct, though many are similar. |
| .TP 5 |
| TERMCAP |
| may denote the location of a termcap database. |
| If it is not an absolute pathname, e.g., begins with a \*(``/\*('', |
| \fB@TSET@\fP removes the variable from the environment before looking |
| for the terminal description. |
| .SH FILES |
| .TP 5 |
| /etc/ttys |
| system port name to terminal type mapping database (BSD versions only). |
| .TP |
| @TERMINFO@ |
| terminal capability database |
| .SH SEE ALSO |
| .hy 0 |
| \fBcsh\fP(1), |
| \fBsh\fP(1), |
| \fBstty\fP(1), |
| \fBcurs_terminfo\fP(3X), |
| \fBtty\fP(4), |
| \fBterminfo\fP(5), |
| \fBttys\fP(5), |
| \fBenviron\fP(7) |
| .hy |
| .PP |
| This describes \fBncurses\fR |
| version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). |