'\" t
.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.70 2021/09/04 19:02:50 tom Exp $
-.TH @TPUT@ 1 ""
-.ds d @TERMINFO@
-.ds n 1
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $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
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
+.ds d @TERMINFO@
.SH NAME
-\fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
+\fB\%@TPUT@\fP,
+\fB\%reset\fP \-
+initialize a terminal or query \fIterminfo\fR database
.SH SYNOPSIS
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparameters\fR]
-.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] [\fB\-x\fP] \fBclear\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fIcapname\fR [\fIparameters\fR]
.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] [\fB\-x\fR] \fBclear\fR
.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBinit\fR
.br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBreset\fR
.br
-\fB@TPUT@ \-S\fR \fB<<\fR
+\fB@TPUT@\fR [\fB\-T \fIterminal-type\fR] \fBlongname\fR
.br
-\fB@TPUT@ \-V\fR
+\fB@TPUT@ \-S\fP \fB<<\fP
.br
+\fB@TPUT@ \-V\fP
.SH DESCRIPTION
-The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
+The \fB@TPUT@\fP utility uses the \fBterminfo\fP database to make the
values of terminal-dependent capabilities and information available to
-the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
+the shell (see \fBsh\fP(1)), to initialize or reset the terminal, or
return the long name of the requested terminal type.
The result depends upon the capability's type:
.RS 3
.TP 5
string
-\fB@TPUT@\fR writes the string to the standard output.
+\fB@TPUT@\fP writes the string to the standard output.
No trailing newline is supplied.
.TP
integer
-\fB@TPUT@\fR writes the decimal value to the standard output,
+\fB@TPUT@\fP writes the decimal value to the standard output,
with a trailing newline.
.TP
boolean
-\fB@TPUT@\fR simply sets the exit code
-(\fB0\fR for TRUE if the terminal has the capability,
-\fB1\fR for FALSE if it does not),
+\fB@TPUT@\fP simply sets the exit code
+(\fB0\fP for TRUE if the terminal has the capability,
+\fB1\fP for FALSE if it does not),
and writes nothing to the standard output.
.RE
.PP
Before using a value returned on the standard output,
the application should test the exit code
-(e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
-(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
+(e.g., \fB$?\fP, see \fBsh\fP(1)) to be sure it is \fB0\fP.
+(See the \fBEXIT STATUS\fP and \fBDIAGNOSTICS\fP sections.)
For a complete list of capabilities
-and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
+and the \fIcapname\fP associated with each, see \fBterminfo\fP(5).
.SS Options
.TP
-\fB\-S\fR
-allows more than one capability per invocation of \fB@TPUT@\fR. The
-capabilities must be passed to \fB@TPUT@\fR from the standard input
+\fB\-S\fP
+allows more than one capability per invocation of \fB@TPUT@\fP. The
+capabilities must be passed to \fB@TPUT@\fP from the standard input
instead of from the command line (see example).
-Only one \fIcapname\fR is allowed per line.
-The \fB\-S\fR option changes the
-meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
-EXIT CODES section).
+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 STATUS section).
.IP
Because some capabilities may use
\fIstring\fP parameters rather than \fInumbers\fP,
-\fB@TPUT@\fR uses a table and the presence of parameters in its input
-to decide whether to use \fBtparm\fR(3X),
+\fB@TPUT@\fP uses a table and the presence of parameters in its input
+to decide whether to use \fBtparm\fP(3X),
and how to interpret the parameters.
.TP
-\fB\-T\fR\fItype\fR
-indicates the \fItype\fR of terminal.
+\fB\-T\fItype\fR
+indicates the \fItype\fP of terminal.
Normally this option is
unnecessary, because the default is taken from the environment
-variable \fBTERM\fR.
-If \fB\-T\fR is specified, then the shell
-variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
+variable \fITERM\fP.
+If \fB\-T\fP is specified, then the shell
+variables \fILINES\fP and \fI\%COLUMNS\fP will also be ignored.
.TP
-\fB\-V\fR
+\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.
The others are the names of \fIcapabilities\fP from the terminal database
-(see \fBterminfo\fR(5) for a list).
+(see \fBterminfo\fP(5) for a list).
Although \fBinit\fP and \fBreset\fP resemble capability names,
\fB@TPUT@\fP uses several capabilities to perform these special functions.
.TP
-\fIcapname\fR
+\fIcapname\fP
indicates the capability from the terminal database.
.IP
If the capability is a string that takes parameters, the arguments
.IP
Most parameters are numbers.
Only a few terminal capabilities require string parameters;
-\fB@TPUT@\fR uses a table to decide which to pass as strings.
-Normally \fB@TPUT@\fR uses \fBtparm\fR(3X) to perform the substitution.
+\fB@TPUT@\fP uses a table to decide which to pass as strings.
+Normally \fB@TPUT@\fP uses \fBtparm\fP(3X) to perform the substitution.
If no parameters are given for the capability,
-\fB@TPUT@\fR writes the string without performing the substitution.
+\fB@TPUT@\fP writes the string without performing the substitution.
.TP
-\fBinit\fR
+\fBinit\fP
If the terminal database is present and an entry for the user's
-terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
+terminal exists (see \fB\-T\fItype\fR, above), the following will
occur:
.RS
.TP 5
(1)
-first, \fB@TPUT@\fR retrieves the current terminal mode settings
+first, \fB@TPUT@\fP retrieves the current terminal mode settings
for your terminal.
It does this by successively testing
.RS
.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)
.TP
(4)
if present, the terminal's initialization strings will be
-output as detailed in the \fBterminfo\fR(5) section on
+output as detailed in the \fBterminfo\fP(5) section on
.IR "Tabs and Initialization" ,
.TP
(5)
contain the information needed for any of these activities,
that activity will silently be skipped.
.TP
-\fBreset\fR
+\fBreset\fP
This is similar to \fBinit\fP, with two differences:
.RS
.TP 5
(2)
Instead of putting out \fIinitialization\fP strings, the terminal's
\fIreset\fP strings will be output if present
-(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
+(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP, \fBrf\fP).
If the \fIreset\fP strings are not present, but \fIinitialization\fP
strings are, the \fIinitialization\fP strings will be output.
.RE
.IP
-Otherwise, \fBreset\fR acts identically to \fBinit\fR.
+Otherwise, \fBreset\fP acts identically to \fBinit\fP.
.TP
-\fBlongname\fR
+\fBlongname\fP
If the terminal database is present and an entry for the
-user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
+user's terminal exists (see \fB\-T\fItype\fR above), then the long name
of the terminal will be put out.
The long name is the last
name in the first line of the terminal's description in the
-\fBterminfo\fR database [see \fBterm\fR(5)].
+\fBterminfo\fP database [see \fBterm\fP(5)].
.SS Aliases
-\fB@TPUT@\fR handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
+\fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
commands specially:
it allows for the possibility that it is invoked by a link with those names.
.PP
-If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
-same effect as \fB@TPUT@ reset\fR.
-The \fB@TSET@\fR(\*n) utility also treats a link named \fBreset\fP specially.
+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(1) utility also treats a link named \fBreset\fP specially.
.PP
Before ncurses 6.1, the two utilities were different from each other:
.bP
redirecting their output to a file will capture only part of their actions.
The changes to the terminal modes are not affected by redirecting the output.
.PP
-If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
-same effect as \fB@TPUT@ init\fR.
+If \fB@TPUT@\fP is invoked by a link named \fBinit\fP, this has the
+same effect as \fB@TPUT@ init\fP.
Again, you are less likely to use that link because another program
named \fBinit\fP has a more well-established use.
.SS Terminal Size
-.PP
Besides the special commands (e.g., \fBclear\fP),
@TPUT@ treats certain terminfo capabilities specially:
\fBlines\fP and \fBcols\fP.
(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\fR
-Initialize the terminal according to the type of
-terminal in the environmental variable \fBTERM\fR. This
-command should be included in everyone's .profile after
-the environmental variable \fBTERM\fR has been exported, as
-illustrated on the \fBprofile\fR(5) manual page.
-.TP 5
-\fB@TPUT@ \-T5620 reset\fR
-Reset an AT&T 5620 terminal, overriding the type of
-terminal in the environmental variable \fBTERM\fR.
-.TP 5
-\fB@TPUT@ cup 0 0\fR
-Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
-(the upper left corner of the screen, usually known as the \*(``home\*(''
-cursor position).
-.TP 5
-\fB@TPUT@ clear\fR
-Echo the clear-screen sequence for the current terminal.
-.TP 5
-\fB@TPUT@ cols\fR
-Print the number of columns for the current terminal.
-.TP 5
-\fB@TPUT@ \-T450 cols\fR
-Print the number of columns for the 450 terminal.
-.TP 5
-\fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
-Set the shell variables \fBbold\fR, to begin stand-out mode
-sequence, and \fBoffbold\fR, to end standout mode sequence,
-for the current terminal.
-This might be followed by a
-prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
-.TP 5
-\fB@TPUT@ hc\fR
-Set exit code to indicate if the current terminal is a hard copy terminal.
-.TP 5
-\fB@TPUT@ cup 23 4\fR
-Send the sequence to move the cursor to row 23, column 4.
-.TP 5
-\fB@TPUT@ cup\fR
-Send the terminfo string for cursor-movement, with no parameters substituted.
-.TP 5
-\fB@TPUT@ longname\fR
-Print the long name from the \fBterminfo\fR database for the
-type of terminal specified in the environmental
-variable \fBTERM\fR.
-.PP
-.RS 5
-\fB@TPUT@ \-S <<!\fR
-.br
-\fB> clear\fR
-.br
-\fB> cup 10 10\fR
-.br
-\fB> bold\fR
-.br
-\fB> !\fR
-.RE
-.TP 5
-\&
-This example shows \fB@TPUT@\fR 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!\fR) on a line by itself.
-.SH FILES
-.TP
-\fB\*d\fR
-compiled terminal description database
-.TP
-\fB@DATADIR@/tabset/*\fR
-tab settings for some terminals, in a format
-appropriate to be output to the terminal (escape
-sequences that set margins and tabs); for more
-information, see the
-.IR "Tabs and Initialization" ,
-section of \fBterminfo\fR(5)
-.SH EXIT CODES
-If the \fB\-S\fR option is used,
-\fB@TPUT@\fR checks for errors from each line,
+.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
number of lines with errors.
-If no errors are found, the exit code is \fB0\fR.
+If no errors are found, the exit code is \fB0\fP.
No indication of which line failed can be given so
-exit code \fB1\fR will never appear.
-Exit codes \fB2\fR, \fB3\fR, and
-\fB4\fR retain their usual interpretation.
-If the \fB\-S\fR option is not used,
-the exit code depends on the type of \fIcapname\fR:
+exit code \fB1\fP will never appear.
+Exit codes \fB2\fP, \fB3\fP, and
+\fB4\fP retain their usual interpretation.
+If the \fB\-S\fP option is not used,
+the exit code depends on the type of \fIcapname\fP:
.RS 3
.TP
.I boolean
-a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
+a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE.
.TP
.I string
-a value of \fB0\fR is set if the
-\fIcapname\fR is defined for this terminal \fItype\fR (the value of
-\fIcapname\fR is returned on standard output);
-a value of \fB1\fR is set if \fIcapname\fR
-is not defined for this terminal \fItype\fR
+a value of \fB0\fP is set if the
+\fIcapname\fP is defined for this terminal \fItype\fP (the value of
+\fIcapname\fP is returned on standard output);
+a value of \fB1\fP is set if \fIcapname\fP
+is not defined for this terminal \fItype\fP
(nothing is written to standard output).
.TP
.I integer
-a value of \fB0\fR is always set,
-whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
-To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
+a value of \fB0\fP is always set,
+whether or not \fIcapname\fP is defined for this terminal \fItype\fP.
+To determine if \fIcapname\fP is defined for this terminal \fItype\fP,
the user must test the value written to standard output.
-A value of \fB\-1\fR
-means that \fIcapname\fR is not defined for this terminal \fItype\fR.
+A value of \fB\-1\fP
+means that \fIcapname\fP is not defined for this terminal \fItype\fP.
.TP
.I other
-\fBreset\fR or \fBinit\fR may fail to find their respective files.
-In that case, the exit code is set to 4 + \fBerrno\fR.
+\fBreset\fP or \fBinit\fP may fail to find their respective files.
+In that case, the exit code is set to 4 + \fBerrno\fP.
.RE
.PP
Any other exit code indicates an error; see the DIAGNOSTICS section.
.SH DIAGNOSTICS
-\fB@TPUT@\fR prints the following error messages and sets the corresponding exit
+\fB@TPUT@\fP prints the following error messages and sets the corresponding exit
codes.
.PP
.ne 15
l l.
exit code error message
=
-\fB0\fR T{
-(\fIcapname\fR is a numeric variable that is not specified in the
-\fBterminfo\fR(5) database for this terminal type, e.g.
-\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
+\fB0\fP T{
+(\fIcapname\fP is a numeric variable that is not specified in the
+\fBterminfo\fP(5) database for this terminal type, e.g.
+\fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP)
T}
-\fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
-\fB2\fR usage error
-\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
-\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
-\fB>4\fR error occurred in \-S
+\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 \fIorig_colors\fP and
-\fIorig_pairs\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 capabilities\fP
-(\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
-However (because he had only termcap available),
-it accepted \fItermcap names\fP 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
-.PP
This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
two important areas:
.bP
\fB@TPUT@\fP now uses a similar scheme,
using functions shared with \fB@TSET@\fP
(and ultimately based on the 4.4BSD \fBtset\fP).
-If it is not able to open a terminal, e.g., when running in \fBcron\fP,
+If it is not able to open a terminal, e.g., when running in \fBcron\fP(1),
\fB@TPUT@\fP will return an error.
.bP
AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if
all of the characters are numeric, or not.
.IP
-Most implementations which provide support for \fIcapname\fR operands
-use the \fItparm\fP function to expand parameters in it.
+Most implementations which provide support for \fIcapname\fP operands
+use the \fBtparm\fP function to expand parameters in it.
That function expects a mixture of numeric and string parameters,
requiring \fB@TPUT@\fP to know which type to use.
.IP
This implementation uses a table to determine the parameter types for
-the standard \fIcapname\fR operands, and an internal library
-function to analyze nonstandard \fIcapname\fR operands.
+the standard \fIcapname\fP operands, and an internal library
+function to analyze nonstandard \fIcapname\fP operands.
+.IP
+Besides providing more reliable operation than AT&T's utility,
+a portability problem is introduced by this analysis:
+An OpenBSD developer adapted the internal library function from ncurses
+to port NetBSD's termcap-based \fBtput\fP to terminfo.
+That had been modified to interpret multiple commands on a line.
+Portable applications should not rely upon this feature;
+ncurses provides it to support applications written
+specifically for OpenBSD.
.PP
This implementation (unlike others) can accept both \fItermcap\fP
and \fIterminfo\fP names for the \fIcapname\fP feature,
if
-\fItermcap\fR support is compiled in.
+\fItermcap\fP support is compiled in.
However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
ambiguities in this case (and the \fIterminfo\fP name is assumed):
.bP
The \fIterminfo\fP name \fBed\fP corresponds to
the \fItermcap\fP name \fBcd\fP (clear to end of screen).
.PP
-The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
-features used in the \fBcup\fR example,
+The \fBlongname\fP and \fB\-S\fP options, and the parameter-substitution
+features used in the \fBcup\fP example,
were not supported in BSD curses before 4.3reno (1989) or in
AT&T/USL curses before SVr4 (1988).
.PP
documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
There are a few interesting observations to make regarding that:
.bP
-In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
+In this implementation, \fBclear\fP is part of the \fIcapname\fP support.
The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
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\fR operands.
+provide support for \fIcapname\fP operands.
.bP
A few platforms such as FreeBSD recognize termcap names rather
than terminfo capability names in their respective \fBtput\fP commands.
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 SEE ALSO
-\fB@CLEAR@\fR(\*n),
-\fBstty\fR(1),
-\fB@TABS@\fR(\*n),
-\fB@TSET@\fR(\*n),
-\fBcurs_termcap\fR(3X),
-\fBterminfo\fR(5).
+.SH HISTORY
+The \fBtput\fP command was begun by Bill Joy in 1980.
+The initial version only cleared the screen.
.PP
-This describes \fBncurses\fR
-version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+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(1),
+\fB\%stty\fP(1),
+\fB\%@TABS@\fP(1),
+\fB\%@TSET@\fP(1),
+\fB\%curs_termcap\fP(3X),
+\fB\%terminfo\fP(5)