.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.87 2023/10/14 19:29:06 tom Exp $
-.TH @TPUT@ 1 2023-10-14 "ncurses 6.4" "User commands"
+.\" $Id: tput.1,v 1.91 2023/12/02 20:49:04 tom Exp $
+.TH @TPUT@ 1 2023-12-02 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds n 1
.ds d @TERMINFO@
.SH NAME
\fB\%@TPUT@\fP,
\fB\%reset\fP \-
initialize a terminal or query \fIterminfo\fR database
.SH SYNOPSIS
-\fB@TPUT@\fR [\fB\-T\fItype\fR] \fIcapname\fR [\fIparameters\fR]
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fIcapname\fR [\fIparameters\fR]
.br
-\fB@TPUT@\fR [\fB\-T\fItype\fR] [\fB\-x\fR] \fBclear\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] [\fB\-x\fR] \fBclear\fR
.br
-\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBinit\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBinit\fR
.br
-\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBreset\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBreset\fR
.br
-\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBlongname\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBlongname\fR
.br
\fB@TPUT@ \-S\fP \fB<<\fP
.br
Before using a value returned on the standard output,
the application should test the exit code
(e.g., \fB$?\fP, see \fBsh\fP(1)) to be sure it is \fB0\fP.
-(See the \fBEXIT CODES\fP and \fBDIAGNOSTICS\fP sections.)
+(See the \fBEXIT STATUS\fP and \fBDIAGNOSTICS\fP sections.)
For a complete list of capabilities
and the \fIcapname\fP associated with each, see \fBterminfo\fP(5).
.SS Options
Only one \fIcapname\fP is allowed per line.
The \fB\-S\fP option changes the
meaning of the \fB0\fP and \fB1\fP boolean and string exit codes (see the
-EXIT CODES section).
+EXIT STATUS section).
.IP
Because some capabilities may use
\fIstring\fP parameters rather than \fInumbers\fP,
indicates the \fItype\fP of terminal.
Normally this option is
unnecessary, because the default is taken from the environment
-variable \fBTERM\fP.
+variable \fITERM\fP.
If \fB\-T\fP is specified, then the shell
-variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored.
+variables \fILINES\fP and \fI\%COLUMNS\fP will also be ignored.
.TP
\fB\-V\fP
reports the version of ncurses which was used in this program, and exits.
.TP
.B \-x
-do not attempt to clear the terminal's scrollback buffer
-using the extended \*(``E3\*('' capability.
+prevents \fB\%@TPUT@\fP from attempting to clear the scrollback buffer.
.SS Commands
A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
special; they are defined by the \fB@TPUT@\fP program.
.TP
(2)
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),
+but the terminal description
+(or environment,
+e.g.,
+\fILINES\fP and \fI\%COLUMNS\fP variables specify this),
update the operating system's notion of the window size.
.TP
(3)
.PP
If \fB@TPUT@\fP is invoked by a link named \fBreset\fP, this has the
same effect as \fB@TPUT@ reset\fP.
-The \fB@TSET@\fP(\*n) utility also treats a link named \fBreset\fP specially.
+The \fB@TSET@\fP(1) utility also treats a link named \fBreset\fP specially.
.PP
Before ncurses 6.1, the two utilities were different from each other:
.bP
(which generally works, unless connecting via a serial line which
does not support \fINAWS\fP: negotiations about window size).
.bP
-finally, it inspects the environment variables \fBLINES\fP and \fBCOLUMNS\fP
-which may override the terminal size.
+finally, it inspects the environment variables \fILINES\fP and
+\fI\%COLUMNS\fP which may override the terminal size.
.PP
If the \fB\-T\fP option is given
@TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP,
relying upon the operating system (or finally, the terminal database).
-.SH EXAMPLES
-.TP 5
-\fB@TPUT@ init\fP
-Initialize the terminal according to the type of
-terminal in the environmental variable \fBTERM\fP. This
-command should be included in everyone's .profile after
-the environmental variable \fBTERM\fP has been exported, as
-illustrated on the \fBprofile\fP(5) manual page.
-.TP 5
-\fB@TPUT@ \-T5620 reset\fP
-Reset an AT&T 5620 terminal, overriding the type of
-terminal in the environmental variable \fBTERM\fP.
-.TP 5
-\fB@TPUT@ cup 0 0\fP
-Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
-(the upper left corner of the screen, usually known as the \*(``home\*(''
-cursor position).
-.TP 5
-\fB@TPUT@ clear\fP
-Echo the clear-screen sequence for the current terminal.
-.TP 5
-\fB@TPUT@ cols\fP
-Print the number of columns for the current terminal.
-.TP 5
-\fB@TPUT@ \-T450 cols\fP
-Print the number of columns for the 450 terminal.
-.TP 5
-\fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
-Set the shell variables \fBbold\fP, to begin stand-out mode
-sequence, and \fBoffbold\fP, to end standout mode sequence,
-for the current terminal.
-This might be followed by a
-prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
-.TP 5
-\fB@TPUT@ hc\fP
-Set exit code to indicate if the current terminal is a hard copy terminal.
-.TP 5
-\fB@TPUT@ cup 23 4\fP
-Send the sequence to move the cursor to row 23, column 4.
-.TP 5
-\fB@TPUT@ cup\fP
-Send the terminfo string for cursor-movement, with no parameters substituted.
-.TP 5
-\fB@TPUT@ longname\fP
-Print the long name from the \fBterminfo\fP database for the
-type of terminal specified in the environmental
-variable \fBTERM\fP.
-.PP
-.RS 5
-\fB@TPUT@ \-S <<!\fP
-.br
-\fB> clear\fP
-.br
-\fB> cup 10 10\fP
-.br
-\fB> bold\fP
-.br
-\fB> !\fP
-.RE
-.TP 5
-\&
-This example shows \fB@TPUT@\fP processing several capabilities
-in one invocation.
-It clears the screen,
-moves the cursor to position 10, 10
-and turns on bold (extra bright) mode.
-The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
-.SH FILES
-.TP
-.I @DATADIR@/tabset
-tab stop initialization database
-.TP
-.I \*d
-compiled terminal description database
-.SH EXIT CODES
+.SH EXIT STATUS
If the \fB\-S\fP option is used,
\fB@TPUT@\fP checks for errors from each line,
and if any errors are found, will set the exit code to 4 plus the
\fBterminfo\fP(5) database for this terminal type, e.g.
\fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP)
T}
-\fB1\fP no error message is printed, see the \fBEXIT CODES\fP section.
+\fB1\fP no error message is printed, see the \fBEXIT STATUS\fP section.
\fB2\fP usage error
\fB3\fP unknown terminal \fItype\fP or no \fBterminfo\fP database
\fB4\fP unknown \fBterminfo\fP capability \fIcapname\fP
\fB>4\fP error occurred in \-S
=
.TE
-.SH HISTORY
-The \fBtput\fP command was begun by Bill Joy in 1980.
-The initial version only cleared the screen.
-.PP
-AT&T System V provided a different \fBtput\fP command:
-.bP
-SVr2 provided a rudimentary \fBtput\fP
-which checked the parameter against each
-predefined capability and returned the corresponding value.
-This version of \fBtput\fP did not use \fBtparm\fP(3X) for
-the capabilities which are parameterized.
-.bP
-SVr3 replaced that, a year later, by a more extensive program
-whose \fBinit\fP and \fBreset\fP subcommands
-(more than half the program) were incorporated from
-the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
-.bP
-SVr4 added color initialization using the \fBorig_colors\fP and
-\fBorig_pair\fP capabilities in the \fBinit\fP subcommand.
-.PP
-Keith Bostic replaced the BSD \fBtput\fP command in 1989
-with a new implementation
-based on the AT&T System V program \fBtput\fP.
-Like the AT&T program, Bostic's version
-accepted some parameters named for \fIterminfo\fP capabilities
-(\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
-However (because he had only \fItermcap\fP available),
-it accepted \fItermcap\fP names for other capabilities.
-Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
-as the earlier BSD \fBtset\fP had done.
-.PP
-At the same time, Bostic added a shell script named \*(``clear\*('',
-which used \fBtput\fP to clear the screen.
-.PP
-Both of these appeared in 4.4BSD,
-becoming the \*(``modern\*('' BSD implementation of \fBtput\fP.
-.PP
-This implementation of \fBtput\fP began from a different source than
-AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on
-\fIcomp.sources.unix\fP in December 1992.
-Ridge's program made more sophisticated use of the terminal capabilities
-than the BSD program.
-Eric Raymond used that \fBtput\fP program
-(and other parts of \fImytinfo\fP) in ncurses in June 1995.
-Using the portions dealing with terminal capabilities
-almost without change,
-Raymond made improvements to the way the command-line parameters
-were handled.
+.SH FILES
+.TP
+.I @DATADIR@/tabset
+tab stop initialization database
+.TP
+.I \*d
+compiled terminal description database
.SH PORTABILITY
This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
two important areas:
capabilities.
.bP
Other implementations of \fBtput\fP on
-SVr4-based systems such as Solaris, IRIX64 and HPUX
+SVr4-based systems such as Solaris, IRIX64 and HP-UX
as well as others such as AIX and Tru64
provide support for \fIcapname\fP operands.
.bP
confusing the \fB\-1\fP written to the standard output for an absent
or cancelled numeric value versus an (unsigned) exit code.
.PP
-The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes
+The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes
as ncurses.
.PP
NetBSD curses documents different exit codes which do not correspond
to either ncurses or X/Open.
+.SH HISTORY
+The \fBtput\fP command was begun by Bill Joy in 1980.
+The initial version only cleared the screen.
+.PP
+AT&T System V provided a different \fBtput\fP command:
+.bP
+SVr2 provided a rudimentary \fBtput\fP
+which checked the parameter against each
+predefined capability and returned the corresponding value.
+This version of \fBtput\fP did not use \fBtparm\fP(3X) for
+the capabilities which are parameterized.
+.bP
+SVr3 replaced that, a year later, by a more extensive program
+whose \fBinit\fP and \fBreset\fP subcommands
+(more than half the program) were incorporated from
+the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
+.bP
+SVr4 added color initialization using the \fBorig_colors\fP and
+\fBorig_pair\fP capabilities in the \fBinit\fP subcommand.
+.PP
+Keith Bostic replaced the BSD \fBtput\fP command in 1989
+with a new implementation
+based on the AT&T System V program \fBtput\fP.
+Like the AT&T program, Bostic's version
+accepted some parameters named for \fIterminfo\fP capabilities
+(\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
+However (because he had only \fItermcap\fP available),
+it accepted \fItermcap\fP names for other capabilities.
+Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
+as the earlier BSD \fBtset\fP had done.
+.PP
+At the same time, Bostic added a shell script named \*(``clear\*('',
+which used \fBtput\fP to clear the screen.
+.PP
+Both of these appeared in 4.4BSD,
+becoming the \*(``modern\*('' BSD implementation of \fBtput\fP.
+.PP
+This implementation of \fBtput\fP began from a different source than
+AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on
+\fIcomp.sources.unix\fP in December 1992.
+Ridge's program made more sophisticated use of the terminal capabilities
+than the BSD program.
+Eric Raymond used that \fBtput\fP program
+(and other parts of \fImytinfo\fP) in ncurses in June 1995.
+Using the portions dealing with terminal capabilities
+almost without change,
+Raymond made improvements to the way the command-line parameters
+were handled.
+.SH EXAMPLES
+.TP 5
+\fB@TPUT@ init\fP
+Initialize the terminal according to the type of
+terminal in the environmental variable \fITERM\fP.
+This command should be included in everyone's .profile after
+the environmental variable \fITERM\fP has been exported,
+as illustrated on the \fBprofile\fP(5) manual page.
+.TP 5
+\fB@TPUT@ \-T5620 reset\fP
+Reset an AT&T 5620 terminal, overriding the type of
+terminal in the environmental variable \fITERM\fP.
+.TP 5
+\fB@TPUT@ cup 0 0\fP
+Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
+(the upper left corner of the screen, usually known as the \*(``home\*(''
+cursor position).
+.TP 5
+\fB@TPUT@ clear\fP
+Echo the clear-screen sequence for the current terminal.
+.TP 5
+\fB@TPUT@ cols\fP
+Print the number of columns for the current terminal.
+.TP 5
+\fB@TPUT@ \-T450 cols\fP
+Print the number of columns for the 450 terminal.
+.TP 5
+\fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
+Set the shell variables \fBbold\fP, to begin stand-out mode
+sequence, and \fBoffbold\fP, to end standout mode sequence,
+for the current terminal.
+This might be followed by a
+prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
+.TP 5
+\fB@TPUT@ hc\fP
+Set exit code to indicate if the current terminal is a hard copy terminal.
+.TP 5
+\fB@TPUT@ cup 23 4\fP
+Send the sequence to move the cursor to row 23, column 4.
+.TP 5
+\fB@TPUT@ cup\fP
+Send the terminfo string for cursor-movement, with no parameters substituted.
+.TP 5
+\fB@TPUT@ longname\fP
+Print the long name from the \fBterminfo\fP database for the
+type of terminal specified in the environmental
+variable \fITERM\fP.
+.PP
+.RS 5
+\fB@TPUT@ \-S <<!\fP
+.br
+\fB> clear\fP
+.br
+\fB> cup 10 10\fP
+.br
+\fB> bold\fP
+.br
+\fB> !\fP
+.RE
+.TP 5
+\&
+This example shows \fB@TPUT@\fP processing several capabilities
+in one invocation.
+It clears the screen,
+moves the cursor to position 10, 10
+and turns on bold (extra bright) mode.
+The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
.SH SEE ALSO
-\fB\%@CLEAR@\fP(\*n),
+\fB\%@CLEAR@\fP(1),
\fB\%stty\fP(1),
-\fB\%@TABS@\fP(\*n),
-\fB\%@TSET@\fP(\*n),
+\fB\%@TABS@\fP(1),
+\fB\%@TSET@\fP(1),
\fB\%curs_termcap\fP(3X),
\fB\%terminfo\fP(5)