X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Ftput.1;h=5d61230db10ec9af79cb2d000eda794a6f38f3b3;hp=8e4a565842c403939dd104018cae08b112d0c232;hb=16fbf3f4f7d96b6ee6bf9159b22f26e05962aa3d;hpb=21b36e89c00f2188954d680bf9fea60328b4538c diff --git a/man/tput.1 b/man/tput.1 index 8e4a5658..5d61230d 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 2018-2021,2022 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.66 2021/03/06 15:56:23 tom Exp $ +.\" $Id: tput.1,v 1.76 2022/02/12 20:02:20 tom Exp $ .TH @TPUT@ 1 "" .ds d @TERMINFO@ .ds n 1 @@ -41,77 +41,77 @@ .el .IP \(bu 2 .. .SH NAME -\fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database +\fB@TPUT@\fP, \fBreset\fP \- initialize a terminal or query terminfo database .SH SYNOPSIS -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparameters\fR] +\fB@TPUT@\fR [\fB\-T\fItype\fR] \fIcapname\fR [\fIparameters\fR] .br -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] [\fB\-x\fP] \fBclear\fR +\fB@TPUT@\fR [\fB\-T\fItype\fR] [\fB\-x\fR] \fBclear\fR .br -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR +\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBinit\fR .br -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR +\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBreset\fR .br -\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR +\fB@TPUT@\fR [\fB\-T\fItype\fR] \fBlongname\fR .br -\fB@TPUT@ \-S\fR \fB<<\fR +\fB@TPUT@ \-S\fP \fB<<\fP .br -\fB@TPUT@ \-V\fR +\fB@TPUT@ \-V\fP .br .SH DESCRIPTION -The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the +The \fB@TPUT@\fP utility uses the \fBterminfo\fP database to make the values of terminal-dependent capabilities and information available to -the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or +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 -\fB@TPUT@\fR writes the string to the standard output. +\fB@TPUT@\fP writes the string to the standard output. No trailing newline is supplied. .TP integer -\fB@TPUT@\fR writes the decimal value to the standard output, +\fB@TPUT@\fP writes the decimal value to the standard output, with a trailing newline. .TP boolean -\fB@TPUT@\fR simply sets the exit code -(\fB0\fR for TRUE if the terminal has the capability, -\fB1\fR for FALSE if it does not), +\fB@TPUT@\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$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR. -(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.) +(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\fR associated with each, see \fBterminfo\fR(5). +and the \fIcapname\fP associated with each, see \fBterminfo\fP(5). .SS Options .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 +\fB\-S\fP +allows more than one capability per invocation of \fB@TPUT@\fP. The +capabilities must be passed to \fB@TPUT@\fP from the standard input instead of from the command line (see example). -Only one \fIcapname\fR is allowed per line. -The \fB\-S\fR option changes the -meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the +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, -\fB@TPUT@\fR uses a table and the presence of parameters in its input -to decide whether to use \fBtparm\fR(3X), +\fB@TPUT@\fP uses a table and the presence of parameters in its input +to decide whether to use \fBtparm\fP(3X), and how to interpret the parameters. .TP -\fB\-T\fR\fItype\fR -indicates the \fItype\fR of terminal. +\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\fR. -If \fB\-T\fR is specified, then the shell -variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored. +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\fR +\fB\-V\fP reports the version of ncurses which was used in this program, and exits. .TP .B \-x @@ -121,11 +121,11 @@ using the extended \*(``E3\*('' capability. 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). +(see \fBterminfo\fP(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 +\fIcapname\fP indicates the capability from the terminal database. .IP If the capability is a string that takes parameters, the arguments @@ -133,19 +133,19 @@ following the capability will be used as parameters for the string. .IP Most parameters are numbers. 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. +\fB@TPUT@\fP uses a table to decide which to pass as strings. +Normally \fB@TPUT@\fP uses \fBtparm\fP(3X) to perform the substitution. If no parameters are given for the capability, -\fB@TPUT@\fR writes the string without performing the substitution. +\fB@TPUT@\fP writes the string without performing the substitution. .TP -\fBinit\fR +\fBinit\fP 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 +terminal exists (see \fB\-T\fItype\fR, above), the following will occur: .RS .TP 5 (1) -first, \fB@TPUT@\fR retrieves the current terminal mode settings +first, \fB@TPUT@\fP retrieves the current terminal mode settings for your terminal. It does this by successively testing .RS @@ -185,7 +185,7 @@ standard tabs will be set (every 8 spaces). .TP (4) if present, the terminal's initialization strings will be -output as detailed in the \fBterminfo\fR(5) section on +output as detailed in the \fBterminfo\fP(5) section on .IR "Tabs and Initialization" , .TP (5) @@ -196,7 +196,7 @@ If an entry does not contain the information needed for any of these activities, that activity will silently be skipped. .TP -\fBreset\fR +\fBreset\fP This is similar to \fBinit\fP, with two differences: .RS .TP 5 @@ -217,28 +217,28 @@ reset any unset special characters to their default values (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). +(\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\fR acts identically to \fBinit\fR. +Otherwise, \fBreset\fP acts identically to \fBinit\fP. .TP -\fBlongname\fR +\fBlongname\fP 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 +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\fR database [see \fBterm\fR(5)]. +\fBterminfo\fP database [see \fBterm\fP(5)]. .SS Aliases -\fB@TPUT@\fR handles the \fBclear\fP, \fBinit\fP and \fBreset\fP +\fB@TPUT@\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 \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. +If \fB@TPUT@\fP is invoked by a link named \fBreset\fP, this has the +same effect as \fB@TPUT@ reset\fP. +The \fB@TSET@\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 @@ -268,8 +268,8 @@ standard output for \fB@TPUT@\fP). 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. +If \fB@TPUT@\fP is invoked by a link named \fBinit\fP, this has the +same effect as \fB@TPUT@ 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 @@ -295,124 +295,124 @@ If the \fB\-T\fP option is given relying upon the operating system (or finally, the terminal database). .SH EXAMPLES .TP 5 -\fB@TPUT@ init\fR +\fB@TPUT@ init\fP Initialize the terminal according to the type of -terminal in the environmental variable \fBTERM\fR. This +terminal in the environmental variable \fBTERM\fP. This command should be included in everyone's .profile after -the environmental variable \fBTERM\fR has been exported, as -illustrated on the \fBprofile\fR(5) manual page. +the environmental variable \fBTERM\fP has been exported, as +illustrated on the \fBprofile\fP(5) manual page. .TP 5 -\fB@TPUT@ \-T5620 reset\fR +\fB@TPUT@ \-T5620 reset\fP Reset an AT&T 5620 terminal, overriding the type of -terminal in the environmental variable \fBTERM\fR. +terminal in the environmental variable \fBTERM\fP. .TP 5 -\fB@TPUT@ cup 0 0\fR -Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR +\fB@TPUT@ 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 -\fB@TPUT@ clear\fR +\fB@TPUT@ clear\fP Echo the clear-screen sequence for the current terminal. .TP 5 -\fB@TPUT@ cols\fR +\fB@TPUT@ cols\fP Print the number of columns for the current terminal. .TP 5 -\fB@TPUT@ \-T450 cols\fR +\fB@TPUT@ \-T450 cols\fP Print the number of columns for the 450 terminal. .TP 5 -\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, +\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"\fR +prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fP .TP 5 -\fB@TPUT@ hc\fR +\fB@TPUT@ hc\fP Set exit code to indicate if the current terminal is a hard copy terminal. .TP 5 -\fB@TPUT@ cup 23 4\fR +\fB@TPUT@ cup 23 4\fP Send the sequence to move the cursor to row 23, column 4. .TP 5 -\fB@TPUT@ cup\fR +\fB@TPUT@ cup\fP Send the terminfo string for cursor-movement, with no parameters substituted. .TP 5 -\fB@TPUT@ longname\fR -Print the long name from the \fBterminfo\fR database for the +\fB@TPUT@ longname\fP +Print the long name from the \fBterminfo\fP database for the type of terminal specified in the environmental -variable \fBTERM\fR. +variable \fBTERM\fP. .PP .RS 5 -\fB@TPUT@ \-S < clear\fR +\fB> clear\fP .br -\fB> cup 10 10\fR +\fB> cup 10 10\fP .br -\fB> bold\fR +\fB> bold\fP .br -\fB> !\fR +\fB> !\fP .RE .TP 5 \& -This example shows \fB@TPUT@\fR processing several capabilities +This example shows \fB@TPUT@\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!\fR) on a line by itself. +The list is terminated by an exclamation mark (\fB!\fP) on a line by itself. .SH FILES .TP -\fB\*d\fR +\fB\*d\fP compiled terminal description database .TP -\fB@DATADIR@/tabset/*\fR +\fB@DATADIR@/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\fR(5) +section of \fBterminfo\fP(5) .SH EXIT CODES -If the \fB\-S\fR option is used, -\fB@TPUT@\fR checks for errors from each line, +If the \fB\-S\fP option is used, +\fB@TPUT@\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\fR. +If no errors are found, the exit code is \fB0\fP. No indication of which line failed can be given so -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: +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\fR is set for TRUE and \fB1\fR for FALSE. +a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE. .TP .I string -a value of \fB0\fR is set if the -\fIcapname\fR is defined for this terminal \fItype\fR (the value of -\fIcapname\fR is returned on standard output); -a value of \fB1\fR is set if \fIcapname\fR -is not defined for this terminal \fItype\fR +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\fR is always set, -whether or not \fIcapname\fR is defined for this terminal \fItype\fR. -To determine if \fIcapname\fR is defined for this terminal \fItype\fR, +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\fR -means that \fIcapname\fR is not defined for this terminal \fItype\fR. +A value of \fB\-1\fP +means that \fIcapname\fP is not defined for this terminal \fItype\fP. .TP .I other -\fBreset\fR or \fBinit\fR may fail to find their respective files. -In that case, the exit code is set to 4 + \fBerrno\fR. +\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 -\fB@TPUT@\fR prints the following error messages and sets the corresponding exit +\fB@TPUT@\fP prints the following error messages and sets the corresponding exit codes. .PP .ne 15 @@ -420,35 +420,46 @@ codes. l l. exit code error message = -\fB0\fR T{ -(\fIcapname\fR is a numeric variable that is not specified in the -\fBterminfo\fR(5) database for this terminal type, e.g. -\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR) +\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. +\fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP) T} -\fB1\fR no error message is printed, see the \fBEXIT CODES\fR section. -\fB2\fR usage error -\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database -\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR -\fB>4\fR error occurred in \-S +\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, -whose \fBinit\fP and \fBreset\fP subcommands +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(3X) 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 capabilities\fP +accepted some parameters named for \fIterminfo\fP capabilities (\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP). -However (because he had only termcap available), -it accepted \fItermcap names\fP for other capabilities. +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 @@ -491,25 +502,34 @@ Until changes made after ncurses 6.0, \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, +If it is not able to open a terminal, e.g., when running in \fBcron\fP(1), \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. +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 \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. +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\fR support is compiled in. +\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 @@ -525,23 +545,23 @@ the \fIterminfo\fP name \fBrmdc\fP (end delete mode). 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, +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) +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\fR support. +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\fR operands. +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. @@ -589,12 +609,12 @@ as ncurses. 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), -\fBcurs_termcap\fR(3X), -\fBterminfo\fR(5). +\fB@CLEAR@\fP(\*n), +\fBstty\fP(1), +\fB@TABS@\fP(\*n), +\fB@TSET@\fP(\*n), +\fBcurs_termcap\fP(3X), +\fBterminfo\fP(5). .PP -This describes \fBncurses\fR +This describes \fBncurses\fP version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).