.\" 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.89 2023/11/25 14:32:36 tom Exp $
+.TH @TPUT@ 1 2023-11-25 "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,
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.
.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
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 \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 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)
projects / ncurses.git / blobdiff