mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-06 17:18:32 +00:00
465 lines
18 KiB
Groff
465 lines
18 KiB
Groff
.\"***************************************************************************
|
|
.\" Copyright 2018-2023,2024 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.85 2024/04/27 17:57:47 tom Exp $
|
|
.TH @TSET@ 1 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
|
|
.ie \n(.g \{\
|
|
.ds `` \(lq
|
|
.ds '' \(rq
|
|
.ds ^ \(ha
|
|
.\}
|
|
.el \{\
|
|
.ie t .ds `` ``
|
|
.el .ds `` ""
|
|
.ie t .ds '' ''
|
|
.el .ds '' ""
|
|
.ds ^ ^
|
|
.\}
|
|
.
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.
|
|
.ds d @TERMINFO@
|
|
.SH NAME
|
|
\fB\%@TSET@\fP,
|
|
\fB\%@RESET@\fP \-
|
|
initialize or reset terminal state
|
|
.SH SYNOPSIS
|
|
\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]
|
|
.br
|
|
\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]
|
|
.SH DESCRIPTION
|
|
.SS "\fItset\fP \(em initialization"
|
|
This program initializes terminals.
|
|
.PP
|
|
First, \fB@TSET@\fP 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\fP argument specified on the command line.
|
|
.PP
|
|
2. The value of the \fITERM\fP environment variable.
|
|
.PP
|
|
3. (BSD systems only.) The terminal type associated with the standard
|
|
error output device in the \fI/etc/ttys\fP file.
|
|
(On System\ V hosts and systems using that convention,
|
|
\fI\%getty\fP(8) does this job by setting
|
|
\fITERM\fP according to the type passed to it by \fI\%/etc/inittab\fP.)
|
|
.PP
|
|
4. The default terminal type, \*(``unknown\*('',
|
|
is not suitable for curses applications.
|
|
.PP
|
|
If the terminal type was not specified on the command-line, the \fB\-m\fP
|
|
option mappings are then applied;
|
|
see subsection \*(``Terminal Type Mapping\*(''.
|
|
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.,
|
|
\fILINES\fP and \fI\%COLUMNS\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 "\fIreset\fP \(em reinitialization"
|
|
When invoked as \fB@RESET@\fP, \fB@TSET@\fP 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>\fB@RESET@\fI<LF>\fR
|
|
.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.
|
|
.SS "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\fP option.
|
|
.PP
|
|
When the \fB\-s\fP option is specified, the commands to enter the information
|
|
into the shell's environment are written to the standard output.
|
|
If the \fISHELL\fP environment variable ends in \*(``csh\*('',
|
|
the commands
|
|
are for \fIcsh\fP(1),
|
|
otherwise,
|
|
they are for \fIsh\fP(1).
|
|
The \fIcsh\fP commands set and unset the shell variable \fBnoglob\fP,
|
|
leaving it unset.
|
|
The following line in the \fB.login\fP
|
|
or \fB.profile\fP files will initialize the environment correctly:
|
|
.sp
|
|
eval \(ga@TSET@ \-s options ... \(ga
|
|
.
|
|
.SS "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\fP file or the \fITERM\fP environment variable is often
|
|
something generic like \fBnetwork\fP, \fBdialup\fP, or \fBunknown\fP.
|
|
When \fB@TSET@\fP 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\fP options maps
|
|
from some set of conditions to a terminal type, that is, to
|
|
tell \fB@TSET@\fP
|
|
\*(``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\fP 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\fP
|
|
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\fP.
|
|
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\fP,
|
|
and the baud rate is greater than 9600 baud, a terminal type of
|
|
\fBvt100\fP 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\fP
|
|
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\fP option argument.
|
|
Also, to avoid problems with meta-characters, it is suggested that the
|
|
entire \fB\-m\fP option argument be placed within single quote characters,
|
|
and that \fIcsh\fP users insert a backslash character (\*(``\e\*('')
|
|
before any exclamation marks (\*(``!\*('').
|
|
.SH OPTIONS
|
|
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\fP.
|
|
.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\fP.
|
|
.TP
|
|
.BI \-k\ ch
|
|
Set the line kill character to \fIch\fP.
|
|
.TP
|
|
.BI \-m\ mapping
|
|
Specify a mapping from a port type to a terminal;
|
|
see subsection \*(``Terminal Type Mapping\*(''.
|
|
.TP
|
|
.B \-Q
|
|
Do not display any values for the erase, interrupt and line kill characters.
|
|
Normally \fB@TSET@\fP 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
|
|
\fITERM\fP to the standard output;
|
|
see subsection \*(``Setting the Environment\*(''.
|
|
.TP
|
|
.B \-V
|
|
reports the version of \fI\%ncurses\fP 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\fP, \fB\-i\fP, and \fB\-k\fP
|
|
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 ENVIRONMENT
|
|
The \fB@TSET@\fP command uses these environment variables:
|
|
.TP 5
|
|
.I SHELL
|
|
tells \fB@TSET@\fP whether to initialize \fITERM\fP using \fIsh\fP(1) or
|
|
\fIcsh\fP(1) syntax.
|
|
.TP 5
|
|
.I TERM
|
|
Denotes your terminal type.
|
|
Each terminal type is distinct, though many are similar.
|
|
.TP 5
|
|
.I 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
|
|
.I /etc/ttys
|
|
system port name to terminal type mapping database (BSD versions only).
|
|
.TP
|
|
.I \*d
|
|
compiled terminal description database directory
|
|
.SH PORTABILITY
|
|
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, HP-UX, 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@\fP utility provides backward compatibility with BSD
|
|
environments;
|
|
under most modern Unices,
|
|
\fI\%/etc/inittab\fP and \fI\%getty\fP(8) can set \fITERM\fP
|
|
appropriately for each dial-up line,
|
|
obviating what was \fB\%@TSET@\fP's most important use.
|
|
This implementation behaves like 4.4BSD \fBtset\fP,
|
|
with a few exceptions we shall consider now.
|
|
.PP
|
|
A few options are different
|
|
because the \fI\%TERMCAP\fP variable
|
|
is no longer supported under terminfo-based \fI\%ncurses\fP:
|
|
.bP
|
|
The \fB\-S\fP option of BSD \fBtset\fP no longer works;
|
|
it prints an error message to the standard error and dies.
|
|
.bP
|
|
The \fB\-s\fP option only sets \fITERM\fP,
|
|
not \fI\%TERMCAP\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\fP, \fB\-E\fP, \fB\-h\fP, \fB\-u\fP and \fB\-v\fP
|
|
options were deleted from the \fB@TSET@\fP
|
|
utility in 4.4BSD.
|
|
None of them were documented in 4.3BSD and all are
|
|
of limited utility at best.
|
|
The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP 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\fP option instead.
|
|
The \fB\-a\fP, \fB\-d\fP, and \fB\-p\fP 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\fP, \fB\-i\fP,
|
|
and \fB\-k\fP 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@\fP as \fB@RESET@\fP no longer implies the \fB\-Q\fP option.
|
|
Also, the interaction between the \- option and the \fIterminal\fP
|
|
argument in some historic implementations of \fB@TSET@\fP 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 \fI\%ncurses\fP, \fB@TSET@\fP obtains the window size using
|
|
\fB\%setupterm\fP(3X), which may be from
|
|
the operating system,
|
|
the \fILINES\fP and \fICOLUMNS\fP environment variables or
|
|
the terminal description.
|
|
.PP
|
|
Obtaining the window size from a terminal's type description is common
|
|
to both implementations,
|
|
but considered obsolescent.
|
|
Its only practical use is for hardware terminals.
|
|
Generally,
|
|
the window size will remain uninitialized only if there were a problem
|
|
obtaining the value from the operating system
|
|
(and \fB\%setupterm\fP would still fail).
|
|
The \fILINES\fP and \fI\%COLUMNS\fP environment variables
|
|
may thus be useful for working around window-size problems,
|
|
but have the drawback that if the window is resized,
|
|
their values must be recomputed and reassigned.
|
|
The \fI\%resize\fP(1) program distributed with
|
|
\fI\%xterm\fP(1) assists this activity.
|
|
.SH HISTORY
|
|
A \fB\%reset\fP command written by Kurt Shoens appeared in 1BSD
|
|
(March 1978).
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/reset.c
|
|
It set the \fIerase\fP and \fIkill\fP characters
|
|
to \fB\*^H\fP (backspace) and \fB@\fP respectively.
|
|
Mark Horton improved this \fB\%reset\fP 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.
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
|
|
.\" reset.c
|
|
That version of \fB\%reset\fP did not use \fI\%termcap\fP.
|
|
.PP
|
|
Eric Allman wrote a distinct \fBtset\fP command for 1BSD,
|
|
using a forerunner of \fI\%termcap\fP called \fI\%ttycap\fP.
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/tset.c
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
|
|
Allman's comments in the source code indicate
|
|
that he began work in October 1977,
|
|
continuing development over the next few years.
|
|
By late 1979,
|
|
it had migrated to \fI\%termcap\fP and handled the \fI\%TERMCAP\fP
|
|
variable.
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
|
|
.\" tset/tset.c
|
|
Later comments indicate that \fBtset\fP was modified in September 1980
|
|
to use logic copied from the 3BSD \*(``reset\*('' program when it was
|
|
invoked as \fB\%reset\fP.
|
|
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2.9BSD/usr/src/ucb/\
|
|
.\" tset/tset.c
|
|
This version appeared in 4.1cBSD, \" and backported to 2.9BSD
|
|
late in 1982.
|
|
Other developers such as Keith Bostic and Jim Bloom continued to modify
|
|
\fBtset\fP until 4.4BSD was released in 1993.
|
|
.PP
|
|
The \fI\%ncurses\fP implementation was lightly adapted from the 4.4BSD
|
|
sources to use the \fI\%terminfo\fP API by Eric S.\& Raymond
|
|
<esr@snark.thyrsus.com>.
|
|
.SH SEE ALSO
|
|
\fB\%csh\fP(1),
|
|
\fB\%sh\fP(1),
|
|
\fB\%stty\fP(1),
|
|
\fB\%curs_terminfo\fP(3X),
|
|
\fB\%tty\fP(4),
|
|
\fB\%terminfo\fP(5),
|
|
\fB\%ttys\fP(5),
|
|
\fB\%environ\fP(7)
|