'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc. *
+.\" Copyright (c) 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.30 2011/12/17 23:32:08 tom Exp $
+.\" $Id: tput.1,v 1.52 2017/01/21 17:38:30 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
+..
.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 [\fIparms\fR ... ]
+\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
the shell (see \fBsh\fR(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
+.RS 3
.TP 5
string
\fB@TPUT@\fR writes the string to the standard output.
(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
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
+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 be ignored,and the
-operating system will not be queried for the actual screen size.
-.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.
-.TP
-\fIparms\fR
-If the capability is a string that takes parameters, the arguments
-\fIparms\fR will be instantiated into the string.
-.IP
-Most parameters are numbers.
-Only a few terminfo 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.
+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
EXIT CODES section).
.IP
Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
-to decide whether to use \fBtparm\fR (3X),
+to decide whether to use \fBtparm\fR(3X),
and how to interpret the parameters.
.TP
\fB\-V\fR
reports the version of ncurses which was used in this program, and exits.
+.SS Commands
+.TP
+\fIcapname\fR
+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 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
-.TP
+.TP 5
(1)
-if present, the terminal's initialization strings will be
-output as detailed in the \fBterminfo\fR(5) section on
-.IR "Tabs and Initialization" ,
+first, \fB@TPUT@\fR retrieves the current terminal mode settings
+for your terminal.
+It does this by successively testing
+.RS
+.bP
+the standard error,
+.bP
+standard output,
+.bP
+standard input and
+.bP
+ultimately \*(lq/dev/tty\*(rq
+.RE
+.IP
+to obtain terminal settings.
+Having retrieved these settings, \fB@TPUT@\fP remembers which
+file descriptor to use when updating settings.
.TP
(2)
-any delays (e.g., newline) specified in the entry will
-be set in the tty driver,
+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),
+update the operating system's notion of the window size.
.TP
(3)
+the terminal modes will be updated:
+.RS
+.bP
+any delays (e.g., newline) specified in the entry will
+be set in the tty driver,
+.bP
tabs expansion will be turned on or off according to
the specification in the entry, and
-.TP
-(4)
+.bP
if tabs are not expanded,
standard tabs will be set (every 8 spaces).
.RE
+.TP
+(4)
+if present, the terminal's initialization strings will be
+output as detailed in the \fBterminfo\fR(5) section on
+.IR "Tabs and Initialization" ,
+.TP
+(5)
+output is flushed.
+.RE
.IP
If an entry does not
-contain the information needed for any of the four above activities,
+contain the information needed for any of these activities,
that activity will silently be skipped.
.TP
\fBreset\fR
-Instead of putting out initialization strings, the terminal's
-reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
-If the reset strings are not present, but initialization
-strings are, the initialization strings will be output.
+This is similar to \fBinit\fP, with two differences:
+.RS
+.TP 5
+(1)
+before any other initialization,
+the terminal modes will be reset to a \*(``sane\*('' state:
+.RS
+.bP
+set cooked and echo modes,
+.bP
+turn off cbreak and raw modes,
+.bP
+turn on newline translation and
+.bP
+reset any unset special characters to their default values
+.RE
+.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).
+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.
.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
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 \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.
-See \fB@TSET@\fR for comparison, which has similar behavior.
+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
+\fB@TSET@\fP utility reset the terminal modes and special characters
+(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
+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:
+.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
+standard output for \fB@TPUT@\fP).
+.IP
+\fBNote:\fP although these programs write to different streams,
+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.
+Again, you are less likely to use that link because another program
+named \fBinit\fP has a more well-established use.
.SH EXAMPLES
.TP 5
\fB@TPUT@ init\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
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,
\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:
-.RS 5
+.RS 3
.TP
.I boolean
a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
\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.
+.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
+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, 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
-X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
+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.
+There are a few interesting observations to make regarding that:
+.bP
In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
-Other implementations of \fB@TPUT@\fP on
+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
as well as others such as AIX and Tru64
provide support for \fIcapname\fR operands.
-A few platforms such as FreeBSD and NetBSD recognize termcap names rather
-than terminfo capability names in their respective \fB@TPUT@\fP commands.
+.bP
+A few platforms such as FreeBSD recognize termcap names rather
+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
+Because (apparently) \fIall\fP of the certified Unix systems
+support the full set of capability names, the reasoning for documenting
+only a few may not be apparent.
+.bP
+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).
+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,
+none of the systems which have a curses implementation provide
+a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
.SH SEE ALSO
-\fB@CLEAR@\fR(1),
+\fB@CLEAR@\fR(\*n),
\fBstty\fR(1),
-\fBtabs\fR(\*n),
-\fBterminfo\fR(5).
+\fB@TABS@\fR(\*n),
+\fB@TSET@\fR(\*n),
+\fBterminfo\fR(5),
+\fBcurs_termcap\fR(3X).
.PP
This describes \fBncurses\fR
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
projects / ncurses.git / blobdiff