X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Ftput.1;h=60aeb72db834a8ca9f83392a17810a3065b4275d;hb=ebe7300d4d5ea549c342500379498fab4b77ea87;hp=0cf0b129fa66a163c00cdd841ca2eb397b38a6d8;hpb=bf2c36c4930ac5bb04cd2b1ba209cd09b6f510ab;p=ncurses.git diff --git a/man/tput.1 b/man/tput.1 index 0cf0b129..60aeb72d 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.102 2024/01/13 22:47:16 tom Exp $ -.TH @TPUT@ 1 2024-01-13 "ncurses 6.4" "User commands" +.\" $Id: tput.1,v 1.118 2024/06/22 21:28:35 tom Exp $ +.TH @TPUT@ 1 2024-06-22 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -45,27 +45,24 @@ .ie n .IP \(bu 4 .el .IP \(bu 2 .. -.ds d @TERMINFO@ .SH NAME -\fB\%@TPUT@\fP, -\fB\%init\fP, -\fB\%reset\fP \- +\fB\%@TPUT@\fP \- initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database .SH SYNOPSIS -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] +\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|. .PP -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP +\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP .PP -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP +\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP .PP -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP +\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP .PP -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP +\fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP .PP -\fB@TPUT@ \-S\fP +\fB@TPUT@\fP [\fB\-v\fP] \fB\-S\fP .PP -\fB@TPUT@ \-V\fP +\fB@TPUT@\fP [\fB\-v\fP] \fB\-V\fP .SH DESCRIPTION \fB\%@TPUT@\fP uses the .I \%term\%info @@ -81,7 +78,7 @@ Terminal capabilities are accessed by .PP \fB\%terminfo\fP(5) discusses terminal capabilities at length and presents a complete list of -.I cap-codes. +.IR cap-codes . .PP When retrieving capability values, the result depends upon the capability's type. @@ -90,7 +87,7 @@ Boolean \fB\%@TPUT@\fP sets its exit status to .B 0 if the terminal possesses -.I cap-code, +.IR cap-code , and .B 1 if it does not. @@ -116,7 +113,7 @@ see section \*(``EXIT STATUS\*('' below. .SS Operands Generally, an operand is a -.I cap-code, +.IR cap-code , a capability code from the terminal database, or a parameter thereto. Three others are specially recognized by \fB\%@TPUT@\fP: @@ -131,8 +128,13 @@ we term them \*(``pseudo-capabilities\*(''. .I cap-code indicates a capability from the terminal database. .IP -If the capability is of string type and takes parameters, -the arguments following the capability will be used as its parameters. +If +.I cap-code +is of string type and takes parameters, +\fB\%@TPUT@\fP interprets arguments following +.I cap-code +as the parameters, +up to the (fixed) quantity the capability requires. .IP Most parameters are numeric. Only a few terminal capabilities require string parameters; @@ -277,16 +279,23 @@ executing a link named .B \%reset that points to \fB\%@TPUT@\fP has the same effect as .RB \%\*(`` "@TPUT@ \%reset" \*(''. -(The \fB\%@TSET@\fP(1) utility also treats a link named -.B \%reset -specially.) .PP -If \fB\%@TPUT@\fP is invoked by a link named -.BR \%init , -this has the same effect as -.RB \%\*(`` "@TPUT@ init" \*(''. -Such a link is seldom employed because another program of that name -is in widespread use. +This feature was introduced by +.I \%ncurses +5.2 in 2000. +It is rarely used: +.TP +.B \%clear +is a separate program, +which is both smaller and more frequently executed. +.TP +.B init +has the same name as another program in widespread use. +.TP +.B \%reset +is provided +by the \fB\%@TSET@\fP(1) utility (also via a link named +.BR \%reset ")." .SS "Terminal Size" Besides the pseudo-capabilities (such as @@ -314,7 +323,7 @@ Finally, it inspects the environment variables .I LINES and -.I \%COLUMNS, +.IR \%COLUMNS , which may override the terminal size. .PP If the @@ -352,7 +361,7 @@ and whether to use \fB\%tparm\fP(3X). .TP .BI \-T\ type indicates the terminal's -.I type. +.IR type . Normally this option is unnecessary, because a default is taken from the .I TERM @@ -364,6 +373,10 @@ and .I \%COLUMNS are also ignored. .TP +.B \-v +causes \fB\%@TPUT@\fP to operate verbosely, +reporting warnings. +.TP .B \-V reports the version of .I \%ncurses @@ -410,7 +423,7 @@ _ 4 some operands not interpreted .TE .SH ENVIRONMENT -\fB@TPUT@\fP command reads one environment variable. +\fB@TPUT@\fP reads one environment variable. .TP 8n \" "TERM" + 2n + adjustment for PDF .I TERM denotes the terminal type. @@ -424,7 +437,7 @@ option overrides its value. .I @DATADIR@/tabset tab stop initialization database .TP -.I \*d +.I @TERMINFO@ compiled terminal description database .SH PORTABILITY Over time @@ -509,7 +522,7 @@ to port NetBSD's .IR termcap -based .B tput to -.I \%term\%info, +.IR \%term\%info , and modified it to interpret multiple .I cap-codes (and parameters) @@ -551,7 +564,7 @@ to but .B \%parm_delete_line to -.I \%term\%info. +.IR \%term\%info . .I termcap uses the code .B DL @@ -559,7 +572,7 @@ for .BR \%parm_delete_line . .I \%term\%info uses the code -.B dch1 +.B dl1 for .BR \%delete_line . .bP @@ -573,7 +586,7 @@ to but .B \%clr_eos to -.I \%term\%info. +.IR \%term\%info . .I termcap uses the code .B cd @@ -618,7 +631,7 @@ A few observations of interest arise from that selection. supports .B clear as it does any other standard -.I cap-code. +.IR cap-code . The others .RB ( init and @@ -637,9 +650,9 @@ operands. .bP A few platforms such as FreeBSD recognize .I termcap -names rather than +codes rather than .I \%term\%info -capability names in their respective +capability codes in their respective .B tput commands. Since 2010, @@ -647,13 +660,13 @@ NetBSD's .B tput uses .I \%term\%info -names. +codes. Before that, it (like FreeBSD) recognized .I termcap -names. +codes. .IP Beginning in 2021, FreeBSD uses @@ -688,13 +701,13 @@ X/Open Curses and the terminal capability database. While it is certainly possible to write a .B tput program without using -.I curses, +.IR curses , no system with a .I curses implementation provides a .B tput utility that does not also support standard -.I cap-codes. +.IR cap-codes . .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 @@ -724,7 +737,7 @@ The various System\ V implementations HP-UX, Solaris) use the same exit statuses as -.I \%ncurses. +.IR \%ncurses . .PP NetBSD .I curses @@ -800,7 +813,7 @@ because he had only available, it accepted .I termcap -names for other capabilities. +codes for other capabilities. Also, Bostic's BSD .B tput @@ -872,8 +885,13 @@ As of the \*(``reset\*('' features of the two programs are (mostly) the same. Two minor differences remain. .bP -The \fB\%@TSET@\fP program waits one second when resetting, -in case the terminal happens to be a hardware device. +When issuing a reset, +the \fB\%@TSET@\fP program +checks whether the device appears to be a pseudoterminal +(as might be used by a terminal emulator program), +and, +if it does not, +waits one second in case it is communicating with a hardware terminal. .bP The two programs write the terminal initialization strings to different streams; @@ -904,7 +922,7 @@ environment variable. Set cursor to normal visibility. .TP .B "@TPUT@ home" -Move the cursor to row 0, +Move the cursor to line 0, column 0: the upper left corner of the screen, usually known as the \*(``home\*('' cursor position. @@ -941,7 +959,7 @@ printf "${strong}Username:${normal} " Indicate via exit status whether the terminal is a hard copy device. .TP .B "@TPUT@ cup 23 4" -Move the cursor to row 23, +Move the cursor to line 23, column 4. .TP .B "@TPUT@ cup"