X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftput.1;h=0f984a743056c85da3fd859ce65bbfe8d5b6a756;hp=750051ba840941a3172bf1fbb100b8d9861ecf86;hb=5c2245b6fc619f8d96ce940281dfbf13b5b8900b;hpb=092f1e4b79bca1d1cd3e24baa7abc3ad4cea8420 diff --git a/man/tput.1 b/man/tput.1 index 750051ba..0f984a74 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2012,2016 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 * @@ -27,10 +27,14 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.36 2016/04/02 23:41:08 tom Exp $ +.\" $Id: tput.1,v 1.55 2017/08/19 14:26:42 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] [\fB\-x\fP] \fBclear\fR +.br \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR .br \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR @@ -80,14 +86,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 @@ -97,86 +95,173 @@ 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 .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 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 \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 +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. @@ -197,7 +282,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 +341,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 +403,101 @@ 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. +.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. +.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 the \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 +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 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 +507,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 +531,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),