=================================================================== RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/tput/tput.1,v retrieving revision 1.26 retrieving revision 1.27 diff -u -r1.26 -r1.27 --- src/usr.bin/tput/tput.1 2022/12/22 19:53:24 1.26 +++ src/usr.bin/tput/tput.1 2023/10/17 09:52:11 1.27 @@ -1,188 +1,618 @@ -.\" $OpenBSD: tput.1,v 1.26 2022/12/22 19:53:24 kn Exp $ -.\" $NetBSD: tput.1,v 1.4 1994/12/07 08:49:10 jtc Exp $ +'\" t +.\" $OpenBSD: tput.1,v 1.27 2023/10/17 09:52:11 nicm 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. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 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 -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)tput.1 8.2 (Berkeley) 3/19/94 -.\" -.Dd $Mdocdate: December 22 2022 $ -.Dt TPUT 1 -.Os -.Sh NAME -.Nm tput , -.Nm clear -.Nd terminal capability interface -.Sh SYNOPSIS -.Nm tput -.Op Fl T Ar term -.Ar attribute -.Op Ar attribute-arg ... -.Ar ... -.Nm tput -.Op Fl T Ar term -.Fl S -.Nm clear -.Op Fl T Ar term -.Sh DESCRIPTION -The -.Nm -utility makes terminal-dependent information available to users or shell -applications. -When invoked as -.Nm clear , -it provides the same functionality as -.Nm tput Cm clear . -.Pp -The options are as follows: -.Bl -tag -width Ds -.It Fl S -The attributes are read from stdin instead of the command line. -.It Fl T -The terminal name as found in the -.Xr terminfo 5 -database; for example, -.Dq vt100 -or -.Dq xterm . -If not specified, -.Nm -retrieves the -.Ev TERM -variable from the environment. -.El -.Pp -.Nm -outputs a string if the -.Ar attribute -is of type string or a number if it is of type integer. -If the -.Ar attribute -is of type boolean, -.Nm -exits 0 if the terminal has the capability or 1 if it -does not. -Each -.Ar attribute -should be a string defined in either -.Xr terminfo 5 -or -.Xr termcap 5 . -.Pp -If the -.Ar attribute -is of type string and takes arguments (e.g., cursor movement, -the -.Xr terminfo 5 -.Dq cup -sequence) the arguments are taken from the command line immediately -following the attribute. -.Pp -The following special attributes are available: -.Bl -tag -width Ar -.It clear -Clear the screen (the -.Xr terminfo 5 -.Dq clear -sequence). -.It init -Print the -.Xr terminfo 5 -initialization strings for the specified terminal. -.It longname -Print the descriptive name of the user's terminal type. -.It reset -Reset the terminal (using the -.Xr terminfo 5 -reset sequences). -.El -.Sh ENVIRONMENT -.Bl -tag -width Ds -.It Ev TERM -Determine the terminal type. -.El -.Sh EXIT STATUS -The exit value of -.Nm -is based on the last attribute specified. -If the attribute is of type string or of type integer, the exit -value is as follows: -.Pp -.Bl -tag -offset indent -width Ds -compact -.It 0 -The requested string was written successfully. -.It 2 -Usage error. -.It 3 -Unknown terminal type. -.It 4 -Unknown attribute name. -.It >4 -An error occurred. -.El -.Pp -If the attribute is of type boolean, -.Nm -exits with a value of 0 if the terminal has this attribute or -1 if it does not. -.Sh EXAMPLES -Clear the screen and go to line 5 column 10: -.Pp -.Dl $ tput clear cup 5 10 -.Pp -Go to line 6 column 11 and delete 6 characters: -.Pp -.Dl $ tput cup 6 11 dch 6 -.Sh SEE ALSO -.Xr terminfo 3 , -.Xr terminfo 5 -.Sh STANDARDS -The -.Nm -utility is compliant with the -.St -p1003.1-2008 -specification. -.Pp -The flag -.Op Fl S -and the attribute -.Cm longname -are extensions to that specification. -.Sh HISTORY -The -.Nm clear -utility first appeared in -.Bx 2 . -The -.Nm -utility first appeared in -.At V.2 -and was reimplemented for -.Bx 4.3 Reno . -.Sh BUGS -.Nm -can't really distinguish between different types of attributes. + +.TH tput 1 2023-07-01 "ncurses 6.4" "User commands" +.ds d /usr/share/terminfo +.ds n 1 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBtput\fP, \fBreset\fP \- initialize a terminal or query terminfo database +.SH SYNOPSIS +\fBtput\fR [\fB\-T\fItype\fR] \fIcapname\fR [\fIparameters\fR] +.br +\fBtput\fR [\fB\-T\fItype\fR] [\fB\-x\fR] \fBclear\fR +.br +\fBtput\fR [\fB\-T\fItype\fR] \fBinit\fR +.br +\fBtput\fR [\fB\-T\fItype\fR] \fBreset\fR +.br +\fBtput\fR [\fB\-T\fItype\fR] \fBlongname\fR +.br +\fBtput \-S\fP \fB<<\fP +.br +\fBtput \-V\fP +.SH DESCRIPTION +The \fBtput\fP utility uses the \fBterminfo\fP database to make the +values of terminal-dependent capabilities and information available to +the shell (see \fBsh\fP(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 3 +.TP 5 +string +\fBtput\fP writes the string to the standard output. +No trailing newline is supplied. +.TP +integer +\fBtput\fP writes the decimal value to the standard output, +with a trailing newline. +.TP +boolean +\fBtput\fP simply sets the exit code +(\fB0\fP for TRUE if the terminal has the capability, +\fB1\fP for FALSE if it does not), +and writes nothing to the standard output. +.RE +.PP +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.) +For a complete list of capabilities +and the \fIcapname\fP associated with each, see \fBterminfo\fP(5). +.SS Options +.TP +\fB\-S\fP +allows more than one capability per invocation of \fBtput\fP. The +capabilities must be passed to \fBtput\fP from the standard input +instead of from the command line (see example). +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). +.IP +Because some capabilities may use +\fIstring\fP parameters rather than \fInumbers\fP, +\fBtput\fP uses a table and the presence of parameters in its input +to decide whether to use \fBtparm\fP(3), +and how to interpret the parameters. +.TP +\fB\-T\fItype\fR +indicates the \fItype\fP of terminal. +Normally this option is +unnecessary, because the default is taken from the environment +variable \fBTERM\fP. +If \fB\-T\fP is specified, then the shell +variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored. +.TP +\fB\-V\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. +.SS Commands +A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are +special; they are defined by the \fBtput\fP program. +The others are the names of \fIcapabilities\fP from the terminal database +(see \fBterminfo\fP(5) for a list). +Although \fBinit\fP and \fBreset\fP resemble capability names, +\fBtput\fP uses several capabilities to perform these special functions. +.TP +\fIcapname\fP +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; +\fBtput\fP uses a table to decide which to pass as strings. +Normally \fBtput\fP uses \fBtparm\fP(3) to perform the substitution. +If no parameters are given for the capability, +\fBtput\fP writes the string without performing the substitution. +.TP +\fBinit\fP +If the terminal database is present and an entry for the user's +terminal exists (see \fB\-T\fItype\fR, above), the following will +occur: +.RS +.TP 5 +(1) +first, \fBtput\fP 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 \*(``/dev/tty\*('' +.RE +.IP +to obtain terminal settings. +Having retrieved these settings, \fBtput\fP remembers which +file descriptor to use when updating settings. +.TP +(2) +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 +.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\fP(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 these activities, +that activity will silently be skipped. +.TP +\fBreset\fP +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\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 < 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).