ncurses 6.0 - patch 20161029
[ncurses.git] / man / tput.1
index 750051ba840941a3172bf1fbb100b8d9861ecf86..6aafe816534377410ea71711855d4565c9fdd42f 100644 (file)
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: tput.1,v 1.36 2016/04/02 23:41:08 tom Exp $
+.\" $Id: tput.1,v 1.46 2016/10/22 19:57:25 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 '' ''
 .de bP
 .IP \(bu 4
 ..
@@ -39,6 +43,8 @@
 .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
+.br
 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
 .br
 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
@@ -162,21 +168,25 @@ 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
-\fB@TPUT@\fR handles the \fBinit\fP and \fBreset\fP commands specially:
+\fB@TPUT@\fR 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:
+The \fB@TSET@\fR(\*n) utility also treats a link named \fBreset\fP specially.
+.PP
+Before ncurses 6.1, the two utilities were different from each other:
 .bP
-That utility resets the terminal modes and special characters (not done here).
+\fB@TSET@\fP utility reset the terminal modes and special characters
+(not done with \fB@TPUT@\fP).
 .bP
-On the other hand, @TSET@'s repertoire of terminal capabilities for
-resetting the terminal is more limited, i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
+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
 in contrast to the tab-stops and margins which are set by this utility.
 .bP
-The \fBreset\fP program is usually an alias for @TSET@,
-due to the resetting of terminal modes and special characters.
+The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
+because of this difference with resetting terminal modes and special characters.
 .PP
 If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
 same effect as \fB@TPUT@ init\fR.
@@ -197,7 +207,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 "home"
+(the upper left corner of the screen, usually known as the \*(lqhome\*(rq
 cursor position).
 .TP 5
 \fB@TPUT@ clear\fR
@@ -256,7 +266,8 @@ compiled terminal description database
 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 "Tabs and Initialization"
+information, see the
+.IR "Tabs and Initialization" ,
 section of \fBterminfo\fR(5)
 .SH EXIT CODES
 If the \fB\-S\fR option is used,
@@ -317,11 +328,73 @@ T}
 \fB>4\fR       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,
+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.
+Later the corresponding source code for \fIreset\fP
+was removed from the BSD \fBtset\fP
+(in June 1993, released in 4.4BSD-Lite a year later).
+.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 \*(lqclear\*(rq,
+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.
 .SH PORTABILITY
 .PP
+This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
+two important areas:
+.bP
+\fB@TPUT@\fP \fIcapname\fP writes to the standard output.
+That need not be a regular terminal.
+However, the subcommands which manipulate terminal modes
+may not use the standard output.
+.IP
+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
+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.
+\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,
+\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.
+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.
+.PP
 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
-features used in the \fBcup\fR example, are not supported in BSD curses or in
-AT&T/USL curses before SVr4.
+features used in the \fBcup\fR example,
+were not supported in BSD curses before 4.3reno (1989) or in
+AT&T/USL curses before SVr4 (1988).
 .PP
 IEEE Std 1003.1/The Open Group  Base Specifications Issue 7 (POSIX.1-2008) 
 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
@@ -331,13 +404,13 @@ In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
 capabilities.
 .bP
-Other implementations of \fB@TPUT@\fP on
+Other implementations of \fBtput\fP on
 SVr4-based systems such as Solaris, IRIX64 and HPUX
 as well as others such as AIX and Tru64
 provide support for \fIcapname\fR operands.
 .bP
 A few platforms such as FreeBSD recognize termcap names rather
-than terminfo capability names in their respective \fB@TPUT@\fP commands.
+than terminfo capability names in their respective \fBtput\fP commands.
 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
 Before that, it (like FreeBSD) recognized termcap names.
 .PP
@@ -355,16 +428,6 @@ and the terminal capabilities database.
 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
-Most implementations which provide support for \fIcapname\fR operands
-use the \fItparm\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.
-This implementation uses a table to determine that for
-the standard \fIcapname\fR operands, and an internal library
-function to analyze nonstandard \fIcapname\fR operands.
-Other implementations may simply guess that an operand containing only digits
-is intended to be a number.
 .SH SEE ALSO
 \fB@CLEAR@\fR(\*n),
 \fBstty\fR(1),