version 1.26, 2022/12/22 19:53:24 |
version 1.27, 2023/10/17 09:52:11 |
|
|
|
'\" t |
.\" $OpenBSD$ |
.\" $OpenBSD$ |
.\" $NetBSD: tput.1,v 1.4 1994/12/07 08:49:10 jtc Exp $ |
.\"*************************************************************************** |
|
.\" Copyright 2018-2022,2023 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 * |
|
.\" "Software"), to deal in the Software without restriction, including * |
|
.\" without limitation the rights to use, copy, modify, merge, publish, * |
|
.\" distribute, distribute with modifications, sublicense, and/or sell * |
|
.\" copies of the Software, and to permit persons to whom the Software is * |
|
.\" furnished to do so, subject to the following conditions: * |
|
.\" * |
|
.\" The above copyright notice and this permission notice shall be included * |
|
.\" in all copies or substantial portions of the Software. * |
|
.\" * |
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
|
.\" * |
|
.\" Except as contained in this notice, the name(s) of the above copyright * |
|
.\" holders shall not be used in advertising or otherwise to promote the * |
|
.\" sale, use or other dealings in this Software without prior written * |
|
.\" authorization. * |
|
.\"*************************************************************************** |
.\" |
.\" |
.\" Copyright (c) 1989, 1990, 1993 |
|
.\" The Regents of the University of California. All rights reserved. |
.TH tput 1 2023-07-01 "ncurses 6.4" "User commands" |
.\" |
.ds d /usr/share/terminfo |
.\" Redistribution and use in source and binary forms, with or without |
.ds n 1 |
.\" modification, are permitted provided that the following conditions |
.ie \n(.g .ds `` \(lq |
.\" are met: |
.el .ds `` `` |
.\" 1. Redistributions of source code must retain the above copyright |
.ie \n(.g .ds '' \(rq |
.\" notice, this list of conditions and the following disclaimer. |
.el .ds '' '' |
.\" 2. Redistributions in binary form must reproduce the above copyright |
.de bP |
.\" notice, this list of conditions and the following disclaimer in the |
.ie n .IP \(bu 4 |
.\" documentation and/or other materials provided with the distribution. |
.el .IP \(bu 2 |
.\" 3. Neither the name of the University nor the names of its contributors |
.. |
.\" may be used to endorse or promote products derived from this software |
.SH NAME |
.\" without specific prior written permission. |
\fBtput\fP, \fBreset\fP \- initialize a terminal or query terminfo database |
.\" |
.SH SYNOPSIS |
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
\fBtput\fR [\fB\-T\fItype\fR] \fIcapname\fR [\fIparameters\fR] |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
.br |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
\fBtput\fR [\fB\-T\fItype\fR] [\fB\-x\fR] \fBclear\fR |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
.br |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
\fBtput\fR [\fB\-T\fItype\fR] \fBinit\fR |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
.br |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
\fBtput\fR [\fB\-T\fItype\fR] \fBreset\fR |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
.br |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
\fBtput\fR [\fB\-T\fItype\fR] \fBlongname\fR |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
.br |
.\" SUCH DAMAGE. |
\fBtput \-S\fP \fB<<\fP |
.\" |
.br |
.\" @(#)tput.1 8.2 (Berkeley) 3/19/94 |
\fBtput \-V\fP |
.\" |
.SH DESCRIPTION |
.Dd $Mdocdate$ |
The \fBtput\fP utility uses the \fBterminfo\fP database to make the |
.Dt TPUT 1 |
values of terminal-dependent capabilities and information available to |
.Os |
the shell (see \fBsh\fP(1)), to initialize or reset the terminal, or |
.Sh NAME |
return the long name of the requested terminal type. |
.Nm tput , |
The result depends upon the capability's type: |
.Nm clear |
.RS 3 |
.Nd terminal capability interface |
.TP 5 |
.Sh SYNOPSIS |
string |
.Nm tput |
\fBtput\fP writes the string to the standard output. |
.Op Fl T Ar term |
No trailing newline is supplied. |
.Ar attribute |
.TP |
.Op Ar attribute-arg ... |
integer |
.Ar ... |
\fBtput\fP writes the decimal value to the standard output, |
.Nm tput |
with a trailing newline. |
.Op Fl T Ar term |
.TP |
.Fl S |
boolean |
.Nm clear |
\fBtput\fP simply sets the exit code |
.Op Fl T Ar term |
(\fB0\fP for TRUE if the terminal has the capability, |
.Sh DESCRIPTION |
\fB1\fP for FALSE if it does not), |
The |
and writes nothing to the standard output. |
.Nm |
.RE |
utility makes terminal-dependent information available to users or shell |
.PP |
applications. |
Before using a value returned on the standard output, |
When invoked as |
the application should test the exit code |
.Nm clear , |
(e.g., \fB$?\fP, see \fBsh\fP(1)) to be sure it is \fB0\fP. |
it provides the same functionality as |
(See the \fBEXIT CODES\fP and \fBDIAGNOSTICS\fP sections.) |
.Nm tput Cm clear . |
For a complete list of capabilities |
.Pp |
and the \fIcapname\fP associated with each, see \fBterminfo\fP(5). |
The options are as follows: |
.SS Options |
.Bl -tag -width Ds |
.TP |
.It Fl S |
\fB\-S\fP |
The attributes are read from stdin instead of the command line. |
allows more than one capability per invocation of \fBtput\fP. The |
.It Fl T |
capabilities must be passed to \fBtput\fP from the standard input |
The terminal name as found in the |
instead of from the command line (see example). |
.Xr terminfo 5 |
Only one \fIcapname\fP is allowed per line. |
database; for example, |
The \fB\-S\fP option changes the |
.Dq vt100 |
meaning of the \fB0\fP and \fB1\fP boolean and string exit codes (see the |
or |
EXIT CODES section). |
.Dq xterm . |
.IP |
If not specified, |
Because some capabilities may use |
.Nm |
\fIstring\fP parameters rather than \fInumbers\fP, |
retrieves the |
\fBtput\fP uses a table and the presence of parameters in its input |
.Ev TERM |
to decide whether to use \fBtparm\fP(3), |
variable from the environment. |
and how to interpret the parameters. |
.El |
.TP |
.Pp |
\fB\-T\fItype\fR |
.Nm |
indicates the \fItype\fP of terminal. |
outputs a string if the |
Normally this option is |
.Ar attribute |
unnecessary, because the default is taken from the environment |
is of type string or a number if it is of type integer. |
variable \fBTERM\fP. |
If the |
If \fB\-T\fP is specified, then the shell |
.Ar attribute |
variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored. |
is of type boolean, |
.TP |
.Nm |
\fB\-V\fP |
exits 0 if the terminal has the capability or 1 if it |
reports the version of ncurses which was used in this program, and exits. |
does not. |
.TP |
Each |
.B \-x |
.Ar attribute |
do not attempt to clear the terminal's scrollback buffer |
should be a string defined in either |
using the extended \*(``E3\*('' capability. |
.Xr terminfo 5 |
.SS Commands |
or |
A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are |
.Xr termcap 5 . |
special; they are defined by the \fBtput\fP program. |
.Pp |
The others are the names of \fIcapabilities\fP from the terminal database |
If the |
(see \fBterminfo\fP(5) for a list). |
.Ar attribute |
Although \fBinit\fP and \fBreset\fP resemble capability names, |
is of type string and takes arguments (e.g., cursor movement, |
\fBtput\fP uses several capabilities to perform these special functions. |
the |
.TP |
.Xr terminfo 5 |
\fIcapname\fP |
.Dq cup |
indicates the capability from the terminal database. |
sequence) the arguments are taken from the command line immediately |
.IP |
following the attribute. |
If the capability is a string that takes parameters, the arguments |
.Pp |
following the capability will be used as parameters for the string. |
The following special attributes are available: |
.IP |
.Bl -tag -width Ar |
Most parameters are numbers. |
.It clear |
Only a few terminal capabilities require string parameters; |
Clear the screen (the |
\fBtput\fP uses a table to decide which to pass as strings. |
.Xr terminfo 5 |
Normally \fBtput\fP uses \fBtparm\fP(3) to perform the substitution. |
.Dq clear |
If no parameters are given for the capability, |
sequence). |
\fBtput\fP writes the string without performing the substitution. |
.It init |
.TP |
Print the |
\fBinit\fP |
.Xr terminfo 5 |
If the terminal database is present and an entry for the user's |
initialization strings for the specified terminal. |
terminal exists (see \fB\-T\fItype\fR, above), the following will |
.It longname |
occur: |
Print the descriptive name of the user's terminal type. |
.RS |
.It reset |
.TP 5 |
Reset the terminal (using the |
(1) |
.Xr terminfo 5 |
first, \fBtput\fP retrieves the current terminal mode settings |
reset sequences). |
for your terminal. |
.El |
It does this by successively testing |
.Sh ENVIRONMENT |
.RS |
.Bl -tag -width Ds |
.bP |
.It Ev TERM |
the standard error, |
Determine the terminal type. |
.bP |
.El |
standard output, |
.Sh EXIT STATUS |
.bP |
The exit value of |
standard input and |
.Nm |
.bP |
is based on the last attribute specified. |
ultimately \*(``/dev/tty\*('' |
If the attribute is of type string or of type integer, the exit |
.RE |
value is as follows: |
.IP |
.Pp |
to obtain terminal settings. |
.Bl -tag -offset indent -width Ds -compact |
Having retrieved these settings, \fBtput\fP remembers which |
.It 0 |
file descriptor to use when updating settings. |
The requested string was written successfully. |
.TP |
.It 2 |
(2) |
Usage error. |
if the window size cannot be obtained from the operating system, |
.It 3 |
but the terminal description (or environment, e.g., \fBLINES\fP |
Unknown terminal type. |
and \fBCOLUMNS\fP variables specify this), |
.It 4 |
update the operating system's notion of the window size. |
Unknown attribute name. |
.TP |
.It >4 |
(3) |
An error occurred. |
the terminal modes will be updated: |
.El |
.RS |
.Pp |
.bP |
If the attribute is of type boolean, |
any delays (e.g., newline) specified in the entry will |
.Nm |
be set in the tty driver, |
exits with a value of 0 if the terminal has this attribute or |
.bP |
1 if it does not. |
tabs expansion will be turned on or off according to |
.Sh EXAMPLES |
the specification in the entry, and |
Clear the screen and go to line 5 column 10: |
.bP |
.Pp |
if tabs are not expanded, |
.Dl $ tput clear cup 5 10 |
standard tabs will be set (every 8 spaces). |
.Pp |
.RE |
Go to line 6 column 11 and delete 6 characters: |
.TP |
.Pp |
(4) |
.Dl $ tput cup 6 11 dch 6 |
if present, the terminal's initialization strings will be |
.Sh SEE ALSO |
output as detailed in the \fBterminfo\fP(5) section on |
.Xr terminfo 3 , |
.IR "Tabs and Initialization" , |
.Xr terminfo 5 |
.TP |
.Sh STANDARDS |
(5) |
The |
output is flushed. |
.Nm |
.RE |
utility is compliant with the |
.IP |
.St -p1003.1-2008 |
If an entry does not |
specification. |
contain the information needed for any of these activities, |
.Pp |
that activity will silently be skipped. |
The flag |
.TP |
.Op Fl S |
\fBreset\fP |
and the attribute |
This is similar to \fBinit\fP, with two differences: |
.Cm longname |
.RS |
are extensions to that specification. |
.TP 5 |
.Sh HISTORY |
(1) |
The |
before any other initialization, |
.Nm clear |
the terminal modes will be reset to a \*(``sane\*('' state: |
utility first appeared in |
.RS |
.Bx 2 . |
.bP |
The |
set cooked and echo modes, |
.Nm |
.bP |
utility first appeared in |
turn off cbreak and raw modes, |
.At V.2 |
.bP |
and was reimplemented for |
turn on newline translation and |
.Bx 4.3 Reno . |
.bP |
.Sh BUGS |
reset any unset special characters to their default values |
.Nm |
.RE |
can't really distinguish between different types of attributes. |
.TP 5 |
|
(2) |
|
Instead of putting out \fIinitialization\fP strings, the terminal's |
|
\fIreset\fP strings will be output if present |
|
(\fBrs1\fP, \fBrs2\fP, \fBrs3\fP, \fBrf\fP). |
|
If the \fIreset\fP strings are not present, but \fIinitialization\fP |
|
strings are, the \fIinitialization\fP strings will be output. |
|
.RE |
|
.IP |
|
Otherwise, \fBreset\fP acts identically to \fBinit\fP. |
|
.TP |
|
\fBlongname\fP |
|
If the terminal database is present and an entry for the |
|
user's terminal exists (see \fB\-T\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\fP database [see \fBterm\fP(5)]. |
|
.SS Aliases |
|
\fBtput\fP 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 \fBtput\fP is invoked by a link named \fBreset\fP, this has the |
|
same effect as \fBtput reset\fP. |
|
The \fBtset\fP(\*n) utility also treats a link named \fBreset\fP specially. |
|
.PP |
|
Before ncurses 6.1, the two utilities were different from each other: |
|
.bP |
|
\fBtset\fP utility reset the terminal modes and special characters |
|
(not done with \fBtput\fP). |
|
.bP |
|
On the other hand, \fBtset\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 \fBtset\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 \fBtset\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 \fBtset\fP and the |
|
standard output for \fBtput\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 \fBtput\fP is invoked by a link named \fBinit\fP, this has the |
|
same effect as \fBtput init\fP. |
|
Again, you are less likely to use that link because another program |
|
named \fBinit\fP has a more well-established use. |
|
.SS Terminal Size |
|
Besides the special commands (e.g., \fBclear\fP), |
|
tput treats certain terminfo capabilities specially: |
|
\fBlines\fP and \fBcols\fP. |
|
tput calls \fBsetupterm\fP(3) 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 |
|
\fBtput 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 |
|
\fBtput \-T5620 reset\fP |
|
Reset an AT&T 5620 terminal, overriding the type of |
|
terminal in the environmental variable \fBTERM\fP. |
|
.TP 5 |
|
\fBtput 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 |
|
\fBtput clear\fP |
|
Echo the clear-screen sequence for the current terminal. |
|
.TP 5 |
|
\fBtput cols\fP |
|
Print the number of columns for the current terminal. |
|
.TP 5 |
|
\fBtput \-T450 cols\fP |
|
Print the number of columns for the 450 terminal. |
|
.TP 5 |
|
\fBbold=`tput smso` offbold=`tput rmso`\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}\\c"\fP |
|
.TP 5 |
|
\fBtput hc\fP |
|
Set exit code to indicate if the current terminal is a hard copy terminal. |
|
.TP 5 |
|
\fBtput cup 23 4\fP |
|
Send the sequence to move the cursor to row 23, column 4. |
|
.TP 5 |
|
\fBtput cup\fP |
|
Send the terminfo string for cursor-movement, with no parameters substituted. |
|
.TP 5 |
|
\fBtput 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 |
|
\fBtput \-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 \fBtput\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 |
|
\fB\*d\fP |
|
compiled terminal description database |
|
.TP |
|
\fB/usr/share/tabset/*\fP |
|
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 |
|
.IR "Tabs and Initialization" , |
|
section of \fBterminfo\fP(5) |
|
.SH EXIT CODES |
|
If the \fB\-S\fP option is used, |
|
\fBtput\fP checks for errors from each line, |
|
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\fP. |
|
No indication of which line failed can be given so |
|
exit code \fB1\fP will never appear. |
|
Exit codes \fB2\fP, \fB3\fP, and |
|
\fB4\fP retain their usual interpretation. |
|
If the \fB\-S\fP option is not used, |
|
the exit code depends on the type of \fIcapname\fP: |
|
.RS 3 |
|
.TP |
|
.I boolean |
|
a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE. |
|
.TP |
|
.I string |
|
a value of \fB0\fP is set if the |
|
\fIcapname\fP is defined for this terminal \fItype\fP (the value of |
|
\fIcapname\fP is returned on standard output); |
|
a value of \fB1\fP is set if \fIcapname\fP |
|
is not defined for this terminal \fItype\fP |
|
(nothing is written to standard output). |
|
.TP |
|
.I integer |
|
a value of \fB0\fP is always set, |
|
whether or not \fIcapname\fP is defined for this terminal \fItype\fP. |
|
To determine if \fIcapname\fP is defined for this terminal \fItype\fP, |
|
the user must test the value written to standard output. |
|
A value of \fB\-1\fP |
|
means that \fIcapname\fP is not defined for this terminal \fItype\fP. |
|
.TP |
|
.I other |
|
\fBreset\fP or \fBinit\fP may fail to find their respective files. |
|
In that case, the exit code is set to 4 + \fBerrno\fP. |
|
.RE |
|
.PP |
|
Any other exit code indicates an error; see the DIAGNOSTICS section. |
|
.SH DIAGNOSTICS |
|
\fBtput\fP prints the following error messages and sets the corresponding exit |
|
codes. |
|
.PP |
|
.ne 15 |
|
.TS |
|
l l. |
|
exit code error message |
|
= |
|
\fB0\fP T{ |
|
(\fIcapname\fP is a numeric variable that is not specified in the |
|
\fBterminfo\fP(5) database for this terminal type, e.g. |
|
\fBtput \-T450 lines\fP and \fBtput \-Thp2621 xmc\fP) |
|
T} |
|
\fB1\fP no error message is printed, see the \fBEXIT CODES\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(3) 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 PORTABILITY |
|
This implementation of \fBtput\fP differs from AT&T \fBtput\fP in |
|
two important areas: |
|
.bP |
|
\fBtput\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 \*(``/dev/tty\*('' and finally just assumes |
|
a 1200Bd terminal. |
|
When updating terminal modes, it ignores errors. |
|
.IP |
|
Until changes made after ncurses 6.0, |
|
\fBtput\fP did not modify terminal modes. |
|
\fBtput\fP now uses a similar scheme, |
|
using functions shared with \fBtset\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(1), |
|
\fBtput\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\fP operands |
|
use the \fBtparm\fP function to expand parameters in it. |
|
That function expects a mixture of numeric and string parameters, |
|
requiring \fBtput\fP to know which type to use. |
|
.IP |
|
This implementation uses a table to determine the parameter types for |
|
the standard \fIcapname\fP operands, and an internal library |
|
function to analyze nonstandard \fIcapname\fP operands. |
|
.IP |
|
Besides providing more reliable operation than AT&T's utility, |
|
a portability problem is introduced by this analysis: |
|
An OpenBSD developer adapted the internal library function from ncurses |
|
to port NetBSD's termcap-based \fBtput\fP to terminfo. |
|
That had been modified to interpret multiple commands on a line. |
|
Portable applications should not rely upon this feature; |
|
ncurses provides it to support applications written |
|
specifically for OpenBSD. |
|
.PP |
|
This implementation (unlike others) can accept both \fItermcap\fP |
|
and \fIterminfo\fP names for the \fIcapname\fP feature, |
|
if |
|
\fItermcap\fP 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\fP and \fB\-S\fP options, and the parameter-substitution |
|
features used in the \fBcup\fP 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. |
|
There are a few interesting observations to make regarding that: |
|
.bP |
|
In this implementation, \fBclear\fP is part of the \fIcapname\fP support. |
|
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\fP operands. |
|
.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. |
|
.IP |
|
Beginning in 2021, FreeBSD uses the ncurses \fBtput\fP, |
|
configured for both terminfo (tested first) and termcap (as a fallback). |
|
.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. |
|
.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?\fP(\*n), |
|
\fBstty\fP(1), |
|
\fB?\fP(\*n), |
|
\fBtset\fP(\*n), |
|
\fBtermcap\fP(3), |
|
\fBterminfo\fP(5). |
|
.PP |
|
This describes \fBncurses\fP |
|
version 6.4 (patch 20230826). |