X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftput.1;h=64fb453016eb19223bd99b3c4e710275075acf03;hp=72e08311af469a12e785c9a1adf871f0beb361e5;hb=fae162795e065e5901068152e91f2962b6b247f3;hpb=06078d3fa68db669ed37178c01873546b4b28745 diff --git a/man/tput.1 b/man/tput.1 index 72e08311..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.56 2017/11/18 23:51:17 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 @@ -155,7 +156,7 @@ standard output, .bP standard input and .bP -ultimately \*(lq/dev/tty\*(rq +ultimately \*(``/dev/tty\*('' .RE .IP to obtain terminal settings. @@ -226,7 +227,8 @@ Otherwise, \fBreset\fR acts identically to \fBinit\fR. \fBlongname\fR 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 @@ -244,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, @@ -268,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 @@ -283,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 @@ -298,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 @@ -328,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. @@ -352,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: @@ -413,7 +441,8 @@ 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 +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 @@ -423,18 +452,18 @@ 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 the \fBtput\fP 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, @@ -453,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). @@ -525,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@).