.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.102 2024/01/13 22:47:16 tom Exp $
-.TH @TPUT@ 1 2024-01-13 "ncurses 6.4" "User commands"
+.\" $Id: tput.1,v 1.116 2024/06/08 20:50:34 tom Exp $
+.TH @TPUT@ 1 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds d @TERMINFO@
.SH NAME
-\fB\%@TPUT@\fP,
-\fB\%init\fP,
-\fB\%reset\fP \-
+\fB\%@TPUT@\fP \-
initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
.SH SYNOPSIS
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
+\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP]
{\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
.PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
+\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
.PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
+\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
.PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
+\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
.PP
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
+\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
.PP
-\fB@TPUT@ \-S\fP
+\fB@TPUT@\fP [\fB\-v\fP] \fB\-S\fP
.PP
-\fB@TPUT@ \-V\fP
+\fB@TPUT@\fP [\fB\-v\fP] \fB\-V\fP
.SH DESCRIPTION
\fB\%@TPUT@\fP uses the
.I \%term\%info
.PP
\fB\%terminfo\fP(5) discusses terminal capabilities at length
and presents a complete list of
-.I cap-codes.
+.IR cap-codes .
.PP
When retrieving capability values,
the result depends upon the capability's type.
\fB\%@TPUT@\fP sets its exit status to
.B 0
if the terminal possesses
-.I cap-code,
+.IR cap-code ,
and
.B 1
if it does not.
.SS Operands
Generally,
an operand is a
-.I cap-code,
+.IR cap-code ,
a capability code from the terminal database,
or a parameter thereto.
Three others are specially recognized by \fB\%@TPUT@\fP:
.I cap-code
indicates a capability from the terminal database.
.IP
-If the capability is of string type and takes parameters,
-the arguments following the capability will be used as its parameters.
+If
+.I cap-code
+is of string type and takes parameters,
+\fB\%@TPUT@\fP interprets arguments following
+.I cap-code
+as the parameters,
+up to the (fixed) quantity the capability requires.
.IP
Most parameters are numeric.
Only a few terminal capabilities require string parameters;
.B \%reset
that points to \fB\%@TPUT@\fP has the same effect as
.RB \%\*(`` "@TPUT@ \%reset" \*(''.
-(The \fB\%@TSET@\fP(1) utility also treats a link named
-.B \%reset
-specially.)
.PP
-If \fB\%@TPUT@\fP is invoked by a link named
-.BR \%init ,
-this has the same effect as
-.RB \%\*(`` "@TPUT@ init" \*(''.
-Such a link is seldom employed because another program of that name
-is in widespread use.
+This feature was introduced by
+.I \%ncurses
+5.2 in 2000.
+It is rarely used:
+.TP
+.B \%clear
+is a separate program,
+which is both smaller and more frequently executed.
+.TP
+.B init
+has the same name as another program in widespread use.
+.TP
+.B \%reset
+is provided
+by the \fB\%@TSET@\fP(1) utility (also via a link named
+.BR \%reset ")."
.SS "Terminal Size"
Besides the pseudo-capabilities
(such as
it inspects the environment variables
.I LINES
and
-.I \%COLUMNS,
+.IR \%COLUMNS ,
which may override the terminal size.
.PP
If the
.TP
.BI \-T\ type
indicates the terminal's
-.I type.
+.IR type .
Normally this option is unnecessary,
because a default is taken from the
.I TERM
.I \%COLUMNS
are also ignored.
.TP
+.B \-v
+causes \fB\%@TPUT@\fP to operate verbosely,
+reporting warnings.
+.TP
.B \-V
reports the version of
.I \%ncurses
4 some operands not interpreted
.TE
.SH ENVIRONMENT
-\fB@TPUT@\fP command reads one environment variable.
+\fB@TPUT@\fP reads one environment variable.
.TP 8n \" "TERM" + 2n + adjustment for PDF
.I TERM
denotes the terminal type.
.I @DATADIR@/tabset
tab stop initialization database
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH PORTABILITY
Over time
.IR termcap -based
.B tput
to
-.I \%term\%info,
+.IR \%term\%info ,
and modified it to interpret multiple
.I cap-codes
(and parameters)
but
.B \%parm_delete_line
to
-.I \%term\%info.
+.IR \%term\%info .
.I termcap
uses the code
.B DL
.BR \%parm_delete_line .
.I \%term\%info
uses the code
-.B dch1
+.B dl1
for
.BR \%delete_line .
.bP
but
.B \%clr_eos
to
-.I \%term\%info.
+.IR \%term\%info .
.I termcap
uses the code
.B cd
supports
.B clear
as it does any other standard
-.I cap-code.
+.IR cap-code .
The others
.RB ( init
and
.bP
A few platforms such as FreeBSD recognize
.I termcap
-names rather than
+codes rather than
.I \%term\%info
-capability names in their respective
+capability codes in their respective
.B tput
commands.
Since 2010,
.B tput
uses
.I \%term\%info
-names.
+codes.
Before that,
it
(like FreeBSD)
recognized
.I termcap
-names.
+codes.
.IP
Beginning in 2021,
FreeBSD uses
While it is certainly possible to write a
.B tput
program without using
-.I curses,
+.IR curses ,
no system with a
.I curses
implementation provides a
.B tput
utility that does not also support standard
-.I cap-codes.
+.IR cap-codes .
.PP
X/Open Curses Issue 7 (2009) is the first version to document utilities.
However that part of X/Open Curses does not follow existing practice
HP-UX,
Solaris)
use the same exit statuses as
-.I \%ncurses.
+.IR \%ncurses .
.PP
NetBSD
.I curses
available,
it accepted
.I termcap
-names for other capabilities.
+codes for other capabilities.
Also,
Bostic's BSD
.B tput
Set cursor to normal visibility.
.TP
.B "@TPUT@ home"
-Move the cursor to row 0,
+Move the cursor to line 0,
column 0:
the upper left corner of the screen,
usually known as the \*(``home\*('' cursor position.
Indicate via exit status whether the terminal is a hard copy device.
.TP
.B "@TPUT@ cup 23 4"
-Move the cursor to row 23,
+Move the cursor to line 23,
column 4.
.TP
.B "@TPUT@ cup"