man/tput.1

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc.              *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: tput.1,v 1.32 2012/07/14 21:06:45 tom Exp $
  31 .TH @TPUT@ 1 ""
  32 .ds d @TERMINFO@
  33 .ds n 1
  34 .SH NAME
  35 \fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
  36 .SH SYNOPSIS
  37 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ]
  38 .br
  39 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
  40 .br
  41 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
  42 .br
  43 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
  44 .br
  45 \fB@TPUT@ \-S\fR  \fB<<\fR
  46 .br
  47 \fB@TPUT@ \-V\fR
  48 .br
  49 .SH DESCRIPTION
  50 The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
  51 values of terminal-dependent capabilities and information available to
  52 the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
  53 return the long name of the requested terminal type.
  54 The result depends upon the capability's type:
  55 .RS
  56 .TP 5
  57 string
  58 \fB@TPUT@\fR writes the string to the standard output.
  59 No trailing newline is supplied.
  60 .TP
  61 integer
  62 \fB@TPUT@\fR writes the decimal value to the standard output,
  63 with a trailing newline.
  64 .TP
  65 boolean
  66 \fB@TPUT@\fR simply sets the exit code
  67 (\fB0\fR for TRUE if the terminal has the capability,
  68 \fB1\fR for FALSE if it does not),
  69 and writes nothing to the standard output.
  70 .RE
  71 .PP
  72 Before using a value returned on the standard output,
  73 the application should test the exit code
  74 (e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
  75 (See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
  76 For a complete list of capabilities
  77 and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
  78 .TP
  79 \fB\-T\fR\fItype\fR
  80 indicates the \fItype\fR of terminal.
  81 Normally this option is
  82 unnecessary, because the default is taken from the environment
  83 variable \fBTERM\fR.
  84 If \fB\-T\fR is specified, then the shell
  85 variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
  86 .TP
  87 \fIcapname\fR
  88 indicates the capability from the \fBterminfo\fR database.  When
  89 \fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
  90 the capability is also accepted.
  91 .TP
  92 \fIparms\fR
  93 If the capability is a string that takes parameters, the arguments
  94 \fIparms\fR will be instantiated into the string.
  95 .IP
  96 Most parameters are numbers.
  97 Only a few terminfo capabilities require string parameters;
  98 \fB@TPUT@\fR uses a table to decide which to pass as strings.
  99 Normally \fB@TPUT@\fR uses \fBtparm\fR (3X) to perform the substitution.
 100 If no parameters are given for the capability,
 101 \fB@TPUT@\fR writes the string without performing the substitution.
 102 .TP
 103 \fB\-S\fR
 104 allows more than one capability per invocation of \fB@TPUT@\fR.  The
 105 capabilities must be passed to \fB@TPUT@\fR from the standard input
 106 instead of from the command line (see example).
 107 Only one \fIcapname\fR is allowed per line.
 108 The \fB\-S\fR option changes the
 109 meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
 110 EXIT CODES section).
 111 .IP
 112 Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
 113 to decide whether to use \fBtparm\fR (3X),
 114 and how to interpret the parameters.
 115 .TP
 116 \fB\-V\fR
 117 reports the version of ncurses which was used in this program, and exits.
 118 .TP
 119 \fBinit\fR
 120 If the \fBterminfo\fR database is present and an entry for the user's
 121 terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
 122 occur:
 123 .RS
 124 .TP
 125 (1)
 126 if present, the terminal's initialization strings will be
 127 output as detailed in the \fBterminfo\fR(5) section on
 128 .IR "Tabs and Initialization" ,
 129 .TP
 130 (2)
 131 any delays (e.g., newline) specified in the entry will
 132 be set in the tty driver,
 133 .TP
 134 (3)
 135 tabs expansion will be turned on or off according to
 136 the specification in the entry, and
 137 .TP
 138 (4)
 139 if tabs are not expanded,
 140 standard tabs will be set (every 8 spaces).
 141 .RE
 142 .IP
 143 If an entry does not
 144 contain the information needed for any of the four above activities,
 145 that activity will silently be skipped.
 146 .TP
 147 \fBreset\fR
 148 Instead of putting out initialization strings, the terminal's
 149 reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
 150 If the reset strings are not present, but initialization
 151 strings are, the initialization strings will be output.
 152 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
 153 .TP
 154 \fBlongname\fR
 155 If the \fBterminfo\fR database is present and an entry for the
 156 user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
 157 of the terminal will be put out.  The long name is the last
 158 name in the first line of the terminal's description in the
 159 \fBterminfo\fR database [see \fBterm\fR(5)].
 160 .PP
 161 If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
 162 same effect as \fB@TPUT@ reset\fR.
 163 See \fB@TSET@\fR for comparison, which has similar behavior.
 164 .SH EXAMPLES
 165 .TP 5
 166 \fB@TPUT@ init\fR
 167 Initialize the terminal according to the type of
 168 terminal in the environmental variable \fBTERM\fR.  This
 169 command should be included in everyone's .profile after
 170 the environmental variable \fBTERM\fR has been exported, as
 171 illustrated on the \fBprofile\fR(5) manual page.
 172 .TP 5
 173 \fB@TPUT@ \-T5620 reset\fR
 174 Reset an AT&T 5620 terminal, overriding the type of
 175 terminal in the environmental variable \fBTERM\fR.
 176 .TP 5
 177 \fB@TPUT@ cup 0 0\fR
 178 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
 179 (the upper left corner of the screen, usually known as the "home"
 180 cursor position).
 181 .TP 5
 182 \fB@TPUT@ clear\fR
 183 Echo the clear-screen sequence for the current terminal.
 184 .TP 5
 185 \fB@TPUT@ cols\fR
 186 Print the number of columns for the current terminal.
 187 .TP 5
 188 \fB@TPUT@ \-T450 cols\fR
 189 Print the number of columns for the 450 terminal.
 190 .TP 5
 191 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
 192 Set the shell variables \fBbold\fR, to begin stand-out mode
 193 sequence, and \fBoffbold\fR, to end standout mode sequence,
 194 for the current terminal.  This might be followed by a
 195 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
 196 .TP 5
 197 \fB@TPUT@ hc\fR
 198 Set exit code to indicate if the current terminal is a hard copy terminal.
 199 .TP 5
 200 \fB@TPUT@ cup 23 4\fR
 201 Send the sequence to move the cursor to row 23, column 4.
 202 .TP 5
 203 \fB@TPUT@ cup\fR
 204 Send the terminfo string for cursor-movement, with no parameters substituted.
 205 .TP 5
 206 \fB@TPUT@ longname\fR
 207 Print the long name from the \fBterminfo\fR database for the
 208 type of terminal specified in the environmental
 209 variable \fBTERM\fR.
 210 .PP
 211 .RS 5
 212 \fB@TPUT@ \-S <<!\fR
 213 .br
 214 \fB> clear\fR
 215 .br
 216 \fB> cup 10 10\fR
 217 .br
 218 \fB> bold\fR
 219 .br
 220 \fB> !\fR
 221 .RE
 222 .TP 5
 223 \&
 224 This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
 225 It clears the screen,
 226 moves the cursor to position 10, 10
 227 and turns on bold (extra bright) mode.
 228 The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
 229 .SH FILES
 230 .TP
 231 \fB\*d\fR
 232 compiled terminal description database
 233 .TP
 234 \fB@DATADIR@/tabset/*\fR
 235 tab settings for some terminals, in a format
 236 appropriate to be output to the terminal (escape
 237 sequences that set margins and tabs); for more
 238 information, see the "Tabs and Initialization"
 239 section of \fBterminfo\fR(5)
 240 .SH EXIT CODES
 241 If the \fB\-S\fR option is used,
 242 \fB@TPUT@\fR checks for errors from each line,
 243 and if any errors are found, will set the exit code to 4 plus the
 244 number of lines with errors.
 245 If no errors are found, the exit code is \fB0\fR.
 246 No indication of which line failed can be given so
 247 exit code \fB1\fR will never appear.  Exit codes \fB2\fR, \fB3\fR, and
 248 \fB4\fR retain their usual interpretation.
 249 If the \fB\-S\fR option is not used,
 250 the exit code depends on the type of \fIcapname\fR:
 251 .RS 5
 252 .TP
 253 .I boolean
 254 a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
 255 .TP
 256 .I string
 257 a value of \fB0\fR is set if the
 258 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
 259 \fIcapname\fR is returned on standard output);
 260 a value of \fB1\fR is set if \fIcapname\fR
 261 is not defined for this terminal \fItype\fR
 262 (nothing is written to standard output).
 263 .TP
 264 .I integer
 265 a value of \fB0\fR is always set,
 266 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
 267 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
 268 the user must test the value written to standard output.
 269 A value of \fB\-1\fR
 270 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
 271 .TP
 272 .I other
 273 \fBreset\fR or \fBinit\fR may fail to find their respective files.
 274 In that case, the exit code is set to 4 + \fBerrno\fR.
 275 .RE
 276 .PP
 277 Any other exit code indicates an error; see the DIAGNOSTICS section.
 278 .SH DIAGNOSTICS
 279 \fB@TPUT@\fR prints the following error messages and sets the corresponding exit
 280 codes.
 281 .PP
 282 .ne 15
 283 .TS
 284 l l.
 285 exit code       error message
 286 =
 287 \fB0\fR T{
 288 (\fIcapname\fR is a numeric variable that is not specified in the
 289 \fBterminfo\fR(5) database for this terminal type, e.g.
 290 \fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
 291 T}
 292 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
 293 \fB2\fR usage error
 294 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
 295 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
 296 \fB>4\fR        error occurred in \-S
 297 =
 298 .TE
 299 .SH PORTABILITY
 300 .PP
 301 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
 302 features used in the \fBcup\fR example, are not supported in BSD curses or in
 303 AT&T/USL curses before SVr4.
 304 .PP
 305 X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
 306 In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
 307 Other implementations of \fB@TPUT@\fP on
 308 SVr4-based systems such as Solaris, IRIX64 and HPUX
 309 as well as others such as AIX and Tru64
 310 provide support for \fIcapname\fR operands.
 311 .PP
 312 A few platforms such as FreeBSD and NetBSD recognize termcap names rather
 313 than terminfo capability names in their respective \fB@TPUT@\fP commands.
 314 .PP
 315 Most implementations which provide support for \fIcapname\fR operands
 316 use the \fItparm\fP function to expand parameters in it.
 317 That function expects a mixture of numeric and string parameters,
 318 requiring \fB@TPUT@\fP to know which type to use.
 319 This implementation uses a table to determine that for
 320 the standard \fIcapname\fR operands, and an internal library
 321 function to analyze nonstandard \fIcapname\fR operands.
 322 Other implementations may simply guess that an operand containing only digits
 323 is intended to be a number.
 324 .SH SEE ALSO
 325 \fB@CLEAR@\fR(1),
 326 \fBstty\fR(1),
 327 \fBtabs\fR(\*n),
 328 \fBterminfo\fR(5),
 329 \fBcurs_termcap\fR(3X).
 330 .PP
 331 This describes \fBncurses\fR
 332 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).