ncurses 6.2 - patch 20210213
[ncurses.git] / man / tput.1
index d17ffd1d4a53aaecca099ccfa9299dac03932df2..64fb453016eb19223bd99b3c4e710275075acf03 100644 (file)
@@ -1,6 +1,7 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018,2020 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            *
@@ -27,7 +28,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: tput.1,v 1.51 2017/01/14 20:49:40 tom Exp $
+.\" $Id: tput.1,v 1.65 2020/12/19 22:17:47 tom Exp $
 .TH @TPUT@ 1 ""
 .ds d @TERMINFO@
 .ds n 1
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
 .de bP
-.IP \(bu 4
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
 ..
 .SH NAME
 \fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
 .SH SYNOPSIS
 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparameters\fR]
 .br
-\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBclear\fR
+\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] [\fB\-x\fP] \fBclear\fR
 .br
 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
 .br
@@ -86,14 +88,6 @@ For a complete list of capabilities
 and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
 .SS Options
 .TP
-\fB\-T\fR\fItype\fR
-indicates the \fItype\fR 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.
-.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
@@ -103,31 +97,49 @@ 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).
 .IP
-Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
+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),
 and how to interpret the parameters.
 .TP
+\fB\-T\fR\fItype\fR
+indicates the \fItype\fR 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.
+.TP
 \fB\-V\fR
 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.
 .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).
+Although \fBinit\fP and \fBreset\fP resemble capability names,
+\fB@TPUT@\fP uses several capabilities to perform these special functions.
 .TP
 \fIcapname\fR
-indicates the capability from the \fBterminfo\fR database.  When
-\fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
-the capability is also accepted.
+indicates the capability from the terminal database.
 .IP
 If the capability is a string that takes parameters, the arguments
 following the capability will be used as parameters for the string.
 .IP
 Most parameters are numbers.
-Only a few terminfo capabilities require string parameters;
+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.
 If no parameters are given for the capability,
 \fB@TPUT@\fR writes the string without performing the substitution.
 .TP
 \fBinit\fR
-If the \fBterminfo\fR database is present and an entry for the user's
+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
 occur:
 .RS
@@ -144,7 +156,7 @@ standard output,
 .bP
 standard input and
 .bP
-ultimately \*(lq/dev/tty\*(rq
+ultimately \*(``/dev/tty\*(''
 .RE
 .IP
 to obtain terminal settings.
@@ -213,9 +225,10 @@ strings are, the \fIinitialization\fP strings will be output.
 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
 .TP
 \fBlongname\fR
-If the \fBterminfo\fR database is present and an entry for the
+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
-of the terminal will be put out.  The long name is the last
+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)].
 .SS Aliases
@@ -233,20 +246,22 @@ Before ncurses 6.1, the two utilities were different from each other:
 (not done with \fB@TPUT@\fP).
 .bP
 On the other hand, \fB@TSET@\fP's repertoire of terminal capabilities for
-resetting the terminal was more limited, i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
+resetting the terminal was more limited,
+i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
 in contrast to the tab-stops and margins which are set by this utility.
 .bP
 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
 because of this difference with resetting terminal modes and special characters.
 .PP
 With the changes made for ncurses 6.1, the \fIreset\fP feature of the
-two programs is (mostly) the same.  A few differences remain:
+two programs is (mostly) the same.
+A few differences remain:
 .bP
 The \fB@TSET@\fP program waits one second when resetting,
 in case it happens to be a hardware terminal.
 .bP
 The two programs write the terminal initialization strings
-to different streams (i.e.,. the standard error for \fB@TSET@\fP and the
+to different streams (i.e., the standard error for \fB@TSET@\fP and the
 standard output for \fB@TPUT@\fP).
 .IP
 \fBNote:\fP although these programs write to different streams,
@@ -257,6 +272,27 @@ If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
 same effect as \fB@TPUT@ init\fR.
 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.
+@TPUT@ calls \fBsetupterm\fP(3X) to obtain the terminal size:
+.bP
+first, it gets the size from the terminal database
+(which generally is not provided for terminal emulators
+which do not have a fixed window size)
+.bP
+then it asks the operating system for the terminal's size
+(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.
+.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
@@ -272,7 +308,7 @@ 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 \*(lqhome\*(rq
+(the upper left corner of the screen, usually known as the \*(``home\*(''
 cursor position).
 .TP 5
 \fB@TPUT@ clear\fR
@@ -287,7 +323,8 @@ Print the number of columns for the 450 terminal.
 \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
+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
@@ -317,7 +354,8 @@ variable \fBTERM\fR.
 .RE
 .TP 5
 \&
-This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
+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.
@@ -341,7 +379,8 @@ 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.
 No indication of which line failed can be given so
-exit code \fB1\fR will never appear.  Exit codes \fB2\fR, \fB3\fR, and
+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:
@@ -402,7 +441,8 @@ 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.
 .PP
-Keith Bostic replaced the BSD \fBtput\fP command in 1989 with a new implementation
+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
@@ -412,11 +452,23 @@ 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 \*(lqclear\*(rq,
+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 \*(lqmodern\*(rq BSD implementation of \fBtput\fP.
+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 PORTABILITY
 .PP
 This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
@@ -430,11 +482,12 @@ may not use the standard output.
 The AT&T implementation's \fBinit\fP and \fBreset\fP commands
 use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
 It successively tries standard output, standard error, standard input
-before falling back to \*(lq/dev/tty\*(rq and finally just assumes
+before falling back to \*(``/dev/tty\*('' and finally just assumes
 a 1200Bd terminal.
 When updating terminal modes, it ignores errors.
 .IP
-Until changes made after ncurses 6.0, \fB@TPUT@\fP did not modify terminal modes.
+Until changes made after ncurses 6.0,
+\fB@TPUT@\fP did not modify terminal modes.
 \fB@TPUT@\fP now uses a similar scheme,
 using functions shared with \fB@TSET@\fP
 (and ultimately based on the 4.4BSD \fBtset\fP).
@@ -453,6 +506,25 @@ 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.
 .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.
+However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
+ambiguities in this case (and the \fIterminfo\fP name is assumed):
+.bP
+The \fItermcap\fP name \fBdl\fP corresponds to
+the \fIterminfo\fP name \fBdl1\fP (delete one line).
+.br
+The \fIterminfo\fP name \fBdl\fP corresponds to
+the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
+.bP
+The \fItermcap\fP name \fBed\fP corresponds to
+the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
+.br
+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,
 were not supported in BSD curses before 4.3reno (1989) or in
@@ -483,20 +555,43 @@ only a few may not be apparent.
 X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
 and the other features used in this implementation.
 .bP
-That is, there are two standards for \fBtput\fP: POSIX (a subset) and X/Open Curses (the full implementation).
+That is, there are two standards for \fBtput\fP:
+POSIX (a subset) and X/Open Curses (the full implementation).
 POSIX documents a subset to avoid the complication of including X/Open Curses
 and the terminal capabilities database.
 .bP
-While it is certainly possible to write a \fBtput\fP program without using curses,
+While it is certainly possible to write a \fBtput\fP program
+without using curses,
 none of the systems which have a curses implementation provide
 a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
+.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
+(i.e., Unix features documented in SVID 3):
+.bP
+It assigns exit code 4 to \*(``invalid operand\*('',
+which may be the same as \fIunknown capability\fP.
+For instance, the source code for Solaris' xcurses uses the term
+\*(``invalid\*('' in this case.
+.bP
+It assigns exit code 255 to a numeric variable that is not specified in
+the terminfo database.
+That likely is a documentation error,
+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
+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),
-\fBterminfo\fR(5),
-\fBcurs_termcap\fR(3X).
+\fBcurs_termcap\fR(3X),
+\fBterminfo\fR(5).
 .PP
 This describes \fBncurses\fR
 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).