X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftput.1;h=64fb453016eb19223bd99b3c4e710275075acf03;hp=2f42daab516b2e408d0e05f50a2f6e5d438cdc7c;hb=fae162795e065e5901068152e91f2962b6b247f3;hpb=58552e8c761a70f8f0bd591fecdf576fa8216e3e diff --git a/man/tput.1 b/man/tput.1 index 2f42daab..64fb4530 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. * +.\" Copyright 2018,2020 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 * @@ -27,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.50 2017/01/07 23:03:28 tom Exp $ +.\" $Id: tput.1,v 1.65 2020/12/19 22:17:47 tom Exp $ .TH @TPUT@ 1 "" .ds d @TERMINFO@ .ds n 1 @@ -36,14 +37,15 @@ .ie \n(.g .ds '' \(rq .el .ds '' '' .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .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 [\fIparameters\fR] .br -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBclear\fR +\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 @@ -86,14 +88,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 @@ -103,31 +97,49 @@ 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 @@ -144,7 +156,7 @@ standard output, .bP standard input and .bP -ultimately \*(lq/dev/tty\*(rq +ultimately \*(``/dev/tty\*('' .RE .IP to obtain terminal settings. @@ -213,9 +225,10 @@ strings are, the \fIinitialization\fP strings will be output. 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 +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 @@ -233,20 +246,22 @@ Before ncurses 6.1, the two utilities were different from each other: (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 +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: +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 +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, @@ -257,6 +272,27 @@ 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. +.SS Terminal Size +.PP +Besides the special commands (e.g., \fBclear\fP), +@TPUT@ treats certain terminfo capabilities specially: +\fBlines\fP and \fBcols\fP. +@TPUT@ calls \fBsetupterm\fP(3X) 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 \fB@TPUT@ init\fR @@ -272,7 +308,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 \*(lqhome\*(rq +(the upper left corner of the screen, usually known as the \*(``home\*('' cursor position). .TP 5 \fB@TPUT@ clear\fR @@ -287,7 +323,8 @@ Print the number of columns for the 450 terminal. \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR Set the shell variables \fBbold\fR, to begin stand-out mode sequence, and \fBoffbold\fR, to end standout mode sequence, -for the current terminal. This might be followed by a +for the current terminal. +This might be followed by a prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR .TP 5 \fB@TPUT@ hc\fR @@ -317,7 +354,8 @@ variable \fBTERM\fR. .RE .TP 5 \& -This example shows \fB@TPUT@\fR processing several capabilities in one invocation. +This example shows \fB@TPUT@\fR processing several capabilities +in one invocation. It clears the screen, moves the cursor to position 10, 10 and turns on bold (extra bright) mode. @@ -341,7 +379,8 @@ 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\fR. No indication of which line failed can be given so -exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and +exit code \fB1\fR will never appear. +Exit codes \fB2\fR, \fB3\fR, and \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: @@ -401,11 +440,9 @@ 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 +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 @@ -415,11 +452,23 @@ 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, +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 \*(lqmodern\*(rq BSD implementation of \fBtput\fP. +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 .PP This implementation of \fBtput\fP differs from AT&T \fBtput\fP in @@ -433,11 +482,12 @@ may not use the standard output. 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 +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, \fB@TPUT@\fP did not modify terminal modes. +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). @@ -456,6 +506,25 @@ 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, were not supported in BSD curses before 4.3reno (1989) or in @@ -486,20 +555,43 @@ only a few may not be apparent. 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). +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, +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@CLEAR@\fR(\*n), \fBstty\fR(1), \fB@TABS@\fR(\*n), \fB@TSET@\fR(\*n), -\fBterminfo\fR(5), -\fBcurs_termcap\fR(3X). +\fBcurs_termcap\fR(3X), +\fBterminfo\fR(5). .PP This describes \fBncurses\fR version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).