doc/html/man/tput.1.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   * t
   4   ****************************************************************************
   5   * Copyright (c) 1998-2000,2002 Free Software Foundation, Inc.              *
   6   *                                                                          *
   7   * Permission is hereby granted, free of charge, to any person obtaining a  *
   8   * copy of this software and associated documentation files (the            *
   9   * "Software"), to deal in the Software without restriction, including      *
  10   * without limitation the rights to use, copy, modify, merge, publish,      *
  11   * distribute, distribute with modifications, sublicense, and/or sell       *
  12   * copies of the Software, and to permit persons to whom the Software is    *
  13   * furnished to do so, subject to the following conditions:                 *
  14   *                                                                          *
  15   * The above copyright notice and this permission notice shall be included  *
  16   * in all copies or substantial portions of the Software.                   *
  17   *                                                                          *
  18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  19   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  20   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  21   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  22   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  23   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  24   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  25   *                                                                          *
  26   * Except as contained in this notice, the name(s) of the above copyright   *
  27   * holders shall not be used in advertising or otherwise to promote the     *
  28   * sale, use or other dealings in this Software without prior written       *
  29   * authorization.                                                           *
  30   ****************************************************************************
  31   * @Id: tput.1,v 1.18 2002/10/12 13:53:20 tom Exp @
  32 -->
  33 <HTML>
  34 <HEAD>
  35 <TITLE>tput 1</TITLE>
  36 <link rev=made href="mailto:bug-ncurses@gnu.org">
  37 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  38 </HEAD>
  39 <BODY>
  40 <H1>tput 1</H1>
  41 <HR>
  42 <PRE>
  43 <!-- Manpage converted by man2html 3.0.1 -->
  44
  45 </PRE>
  46 <H2>NAME</H2><PRE>
  47        <STRONG>tput</STRONG>,  <STRONG>reset</STRONG>  -  initialize  a  terminal or query terminfo
  48        database
  49
  50
  51 </PRE>
  52 <H2>SYNOPSIS</H2><PRE>
  53        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <EM>capname</EM> [<EM>parms</EM> ... ]
  54        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>init</STRONG>
  55        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>reset</STRONG>
  56        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>longname</STRONG>
  57        <STRONG>tput</STRONG> <STRONG>-S</STRONG>  <STRONG>&lt;&lt;</STRONG>
  58        <STRONG>tput</STRONG> <STRONG>-V</STRONG>
  59
  60
  61 </PRE>
  62 <H2>DESCRIPTION</H2><PRE>
  63        The <STRONG>tput</STRONG> utility uses the <STRONG>terminfo</STRONG> database  to  make  the
  64        values  of terminal-dependent capabilities and information
  65        available to the shell (see <STRONG><A HREF="sh.1.html">sh(1)</A></STRONG>), to initialize or reset
  66        the  terminal,  or  return  the long name of the requested
  67        terminal type.  <STRONG>tput</STRONG> outputs a  string  if  the  attribute
  68        (<EM>cap</EM>ability  <EM>name</EM>) is of type string, or an integer if the
  69        attribute is of type integer.  If the attribute is of type
  70        boolean, <STRONG>tput</STRONG> simply sets the exit code (<STRONG>0</STRONG> for TRUE if the
  71        terminal has the capability, <STRONG>1</STRONG> for FALSE if it does  not),
  72        and  produces no output.  Before using a value returned on
  73        standard output, the user should test the exit  code  [<STRONG>$?</STRONG>,
  74        see  <STRONG><A HREF="sh.1.html">sh(1)</A></STRONG>]  to  be sure it is <STRONG>0</STRONG>.  (See the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> and
  75        <STRONG>DIAGNOSTICS</STRONG> sections.)  For a complete list  of  capabili-
  76        ties  and  the  <EM>capname</EM>  associated  with  each,  see <STRONG>ter-</STRONG>
  77        <STRONG><A HREF="terminfo.1.html">minfo(1)</A></STRONG>.
  78
  79        <STRONG>-T</STRONG><EM>type</EM> indicates the  <EM>type</EM>  of  terminal.   Normally  this
  80               option is unnecessary, because the default is taken
  81               from the environment variable <STRONG>TERM</STRONG>.  If <STRONG>-T</STRONG> is spec-
  82               ified,  then  the shell variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG>
  83               will be ignored,and the operating system  will  not
  84               be queried for the actual screen size.
  85
  86        <EM>capname</EM>
  87               indicates the attribute from the <STRONG>terminfo</STRONG> database.
  88               When <STRONG>termcap</STRONG> support is compiled  in,  the  <STRONG>termcap</STRONG>
  89               name for the attribute is also accepted.
  90
  91        <EM>parms</EM>  If the attribute is a string that takes parameters,
  92               the arguments <EM>parms</EM> will be instantiated  into  the
  93               string.   An all-numeric argument will be passed to
  94               the attribute as a number.
  95
  96               Only a few  terminfo  capabilities  require  string
  97               parameters;  <STRONG>tput</STRONG>  uses  a table to decide which to
  98               pass as strings.  Normally <STRONG>tput</STRONG> uses <STRONG>tparm</STRONG> (3x)  to
  99               perform  the  substitution.   If  no parameters are
 100               given for the attribute,  <STRONG>tput</STRONG>  writes  the  string
 101               without performing the substitution.
 102
 103        <STRONG>-S</STRONG>     allows  more  than one capability per invocation of
 104               <STRONG>tput</STRONG>.  The capabilities must be passed to <STRONG>tput</STRONG> from
 105               the standard input instead of from the command line
 106               (see example).  Only one  <EM>capname</EM>  is  allowed  per
 107               line.   The  <STRONG>-S</STRONG> option changes the meaning of the <STRONG>0</STRONG>
 108               and <STRONG>1</STRONG> boolean and string exit codes (see  the  EXIT
 109               CODES section).
 110
 111               Again, <STRONG>tput</STRONG> uses a table and the presence of param-
 112               eters in its input to decide whether to  use  <STRONG>tparm</STRONG>
 113               (3x), and how to interpret the parameters.
 114
 115        <STRONG>-V</STRONG>     reports  the  version  of ncurses which was used in
 116               this program, and exits.
 117
 118        <STRONG>init</STRONG>   If the <STRONG>terminfo</STRONG> database is present  and  an  entry
 119               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above),
 120               the following will occur: (1) if present, the  ter-
 121               minal's initialization strings will be output (<STRONG>is1</STRONG>,
 122               <STRONG>is2</STRONG>, <STRONG>is3</STRONG>, <STRONG>if</STRONG>, <STRONG>iprog</STRONG>), (2) any  delays  (e.g.,  new-
 123               line) specified in the entry will be set in the tty
 124               driver, (3) tabs expansion will be turned on or off
 125               according  to  the  specification in the entry, and
 126               (4) if tabs are not expanded, standard tabs will be
 127               set (every 8 spaces).  If an entry does not contain
 128               the information needed for any of  the  four  above
 129               activities, that activity will silently be skipped.
 130
 131        <STRONG>reset</STRONG>  Instead of putting out initialization strings,  the
 132               terminal's  reset strings will be output if present
 133               (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, <STRONG>rf</STRONG>).  If the reset strings are  not
 134               present,  but  initialization strings are, the ini-
 135               tialization strings  will  be  output.   Otherwise,
 136               <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
 137
 138        <STRONG>longname</STRONG>
 139               If  the  <STRONG>terminfo</STRONG>  database is present and an entry
 140               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>  above),
 141               then the long name of the terminal will be put out.
 142               The long name is the last name in the first line of
 143               the terminal's description in the <STRONG>terminfo</STRONG> database
 144               [see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>].
 145
 146        If <STRONG>tput</STRONG> is invoked by a link named  <STRONG>reset</STRONG>,  this  has  the
 147        same effect as <STRONG>tput</STRONG> <STRONG>reset</STRONG>.  See <STRONG>tset</STRONG> for comparison, which
 148        has similar behavior.
 149
 150
 151 </PRE>
 152 <H2>EXAMPLES</H2><PRE>
 153        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 154             Initialize the terminal according to the type of ter-
 155             minal  in the environmental variable <STRONG>TERM</STRONG>.  This com-
 156             mand should be included in everyone's .profile  after
 157             the environmental variable <STRONG>TERM</STRONG> has been exported, as
 158             illustrated on the <STRONG><A HREF="profile.5.html">profile(5)</A></STRONG> manual page.
 159
 160        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 161             Reset an AT&amp;T 5620 terminal, overriding the  type  of
 162             terminal in the environmental variable <STRONG>TERM</STRONG>.
 163
 164        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
 165             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column
 166             <STRONG>0</STRONG> (the upper left corner of the screen, usually known
 167             as the "home" cursor position).
 168
 169        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 170             Echo the clear-screen sequence for the current termi-
 171             nal.
 172
 173        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 174             Print the number of columns for the current terminal.
 175
 176        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
 177             Print the number of columns for the 450 terminal.
 178
 179        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
 180             Set the shell variables <STRONG>bold</STRONG>, to begin stand-out mode
 181             sequence, and <STRONG>offbold</STRONG>, to end standout mode sequence,
 182             for  the current terminal.  This might be followed by
 183             a prompt: <STRONG>echo</STRONG>  <STRONG>"${bold}Please</STRONG>  <STRONG>type</STRONG>  <STRONG>in</STRONG>  <STRONG>your</STRONG>  <STRONG>name:</STRONG>
 184             <STRONG>${offbold}\c"</STRONG>
 185
 186        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 187             Set  exit code to indicate if the current terminal is
 188             a hard copy terminal.
 189
 190        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 191             Send the sequence to move the cursor to row 23,  col-
 192             umn 4.
 193
 194        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 195             Send the terminfo string for cursor-movement, with no
 196             parameters substituted.
 197
 198        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 199             Print the long name from the  <STRONG>terminfo</STRONG>  database  for
 200             the  type  of terminal specified in the environmental
 201             variable <STRONG>TERM</STRONG>.
 202
 203             <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 204             <STRONG>&gt;</STRONG> <STRONG>clear</STRONG>
 205             <STRONG>&gt;</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 206             <STRONG>&gt;</STRONG> <STRONG>bold</STRONG>
 207             <STRONG>&gt;</STRONG> <STRONG>!</STRONG>
 208
 209             This example shows <STRONG>tput</STRONG> processing several  capabili-
 210             ties  in one invocation.  It clears the screen, moves
 211             the cursor to position  10,  10  and  turns  on  bold
 212             (extra  bright)  mode.   The list is terminated by an
 213             exclamation mark (<STRONG>!</STRONG>) on a line by itself.
 214
 215
 216 </PRE>
 217 <H2>FILES</H2><PRE>
 218        <STRONG>/usr/share/terminfo</STRONG>
 219               compiled terminal description database
 220
 221        <STRONG>/usr/include/curses.h</STRONG>
 222               <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> header file
 223
 224        <STRONG>/usr/include/term.h</STRONG>
 225               <STRONG>terminfo</STRONG> header file
 226
 227        <STRONG>/usr/share/tabset/*</STRONG>
 228               tab settings for some terminals, in a format appro-
 229               priate   to  be  output  to  the  terminal  (escape
 230               sequences that set  margins  and  tabs);  for  more
 231               information, see the "Tabs and Initialization" sec-
 232               tion of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 233
 234
 235 </PRE>
 236 <H2>EXIT CODES</H2><PRE>
 237        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each
 238        line,  and if any errors are found, will set the exit code
 239        to 4 plus the number of lines with errors.  If  no  errors
 240        are  found,  the  exit  code is <STRONG>0</STRONG>.  No indication of which
 241        line failed can be given so exit code <STRONG>1</STRONG> will never appear.
 242        Exit  codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation.
 243        If the <STRONG>-S</STRONG> option is not used, the exit code depends on the
 244        type of <EM>capname</EM>:
 245
 246             <EM>boolean</EM>
 247                    a  value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
 248
 249             <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>capname</EM> is  defined
 250                    for  this  terminal <EM>type</EM> (the value of <EM>capname</EM>
 251                    is returned on standard output); a value of  <STRONG>1</STRONG>
 252                    is set if <EM>capname</EM> is not defined for this ter-
 253                    minal <EM>type</EM> (nothing  is  written  to  standard
 254                    output).
 255
 256             <EM>integer</EM>
 257                    a  value  of  <STRONG>0</STRONG>  is always set, whether or not
 258                    <EM>capname</EM> is defined for this terminal <EM>type</EM>.  To
 259                    determine  if <EM>capname</EM> is defined for this ter-
 260                    minal <EM>type</EM>, the user must test the value writ-
 261                    ten  to  standard output.  A value of <STRONG>-1</STRONG> means
 262                    that <EM>capname</EM> is not defined for this  terminal
 263                    <EM>type</EM>.
 264
 265             <EM>other</EM>  <STRONG>reset</STRONG>  or  <STRONG>init</STRONG> may fail to find their respec-
 266                    tive files.  In that case, the  exit  code  is
 267                    set to 4 + <STRONG>errno</STRONG>.
 268
 269        Any  other  exit code indicates an error; see the DIAGNOS-
 270        TICS section.
 271
 272
 273
 274 </PRE>
 275 <H2>DIAGNOSTICS</H2><PRE>
 276        <STRONG>tput</STRONG> prints the following error messages and sets the cor-
 277        responding exit codes.
 278
 279        exit code   error message
 280        ---------------------------------------------------------------------
 281        <STRONG>0</STRONG>           (<EM>capname</EM>  is a numeric variable that is not specified in
 282                    the <STRONG><A HREF="terminfo.1.html">terminfo(1)</A></STRONG> database for this  terminal  type,  e.g.
 283                    <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-T2621</STRONG> <STRONG>xmc</STRONG>)
 284        <STRONG>1</STRONG>           no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> section.
 285        <STRONG>2</STRONG>           usage error
 286        <STRONG>3</STRONG>           unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
 287        <STRONG>4</STRONG>           unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
 288        <STRONG>&gt;4</STRONG>          error occurred in -S
 289        ---------------------------------------------------------------------
 290
 291
 292 </PRE>
 293 <H2>PORTABILITY</H2><PRE>
 294        The  <STRONG>longname</STRONG>  and <STRONG>-S</STRONG> options, and the parameter-substitu-
 295        tion features used in the <STRONG>cup</STRONG> example, are  not  supported
 296        in BSD curses or in AT&amp;T/USL curses before SVr4.
 297
 298
 299 </PRE>
 300 <H2>SEE ALSO</H2><PRE>
 301        <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG><A HREF="stty.1.html">stty(1)</A></STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333 </PRE>
 334 <HR>
 335 <ADDRESS>
 336 Man(1) output converted with
 337 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 338 </ADDRESS>
 339 </BODY>
 340 </HTML>