doc/html/man/tput.1.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright (c) 1998-2017,2018 Free Software Foundation, Inc.              *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: tput.1,v 1.62 2018/09/30 20:31:59 Sven.Joachim Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>tput 1</TITLE>
  38 <link rev=made href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">tput 1</H1>
  43 <PRE>
  44 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>                     General Commands Manual                    <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>tput</STRONG>, <STRONG>reset</STRONG> - initialize a terminal or query terminfo database
  51
  52
  53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  54        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <EM>capname</EM> [<EM>parameters</EM>]
  55        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
  56        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>init</STRONG>
  57        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>reset</STRONG>
  58        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>longname</STRONG>
  59        <STRONG>tput</STRONG> <STRONG>-S</STRONG>  <STRONG>&lt;&lt;</STRONG>
  60        <STRONG>tput</STRONG> <STRONG>-V</STRONG>
  61
  62
  63 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  64        The  <STRONG>tput</STRONG> utility uses the <STRONG>terminfo</STRONG> database to make the values of ter-
  65        minal-dependent capabilities and information  available  to  the  shell
  66        (see  <STRONG>sh(1)</STRONG>),  to  initialize or reset the terminal, or return the long
  67        name of the requested terminal type.  The result depends upon the capa-
  68        bility's type:
  69
  70           string
  71                <STRONG>tput</STRONG>  writes  the  string  to the standard output.  No trailing
  72                newline is supplied.
  73
  74           integer
  75                <STRONG>tput</STRONG> writes the decimal value to the standard  output,  with  a
  76                trailing newline.
  77
  78           boolean
  79                <STRONG>tput</STRONG>  simply sets the exit code (<STRONG>0</STRONG> for TRUE if the terminal has
  80                the capability, <STRONG>1</STRONG> for FALSE if it does not), and writes nothing
  81                to the standard output.
  82
  83        Before  using  a value returned on the standard output, the application
  84        should test the exit code (e.g., <STRONG>$?</STRONG>, see <STRONG>sh(1)</STRONG>) to be  sure  it  is  <STRONG>0</STRONG>.
  85        (See  the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> and <STRONG>DIAGNOSTICS</STRONG> sections.)  For a complete list of
  86        capabilities and the <EM>capname</EM> associated with each, see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
  87
  88
  89 </PRE><H3><a name="h3-Options">Options</a></H3><PRE>
  90        <STRONG>-S</STRONG>     allows more than one capability per  invocation  of  <STRONG>tput</STRONG>.   The
  91               capabilities  must  be  passed  to  <STRONG>tput</STRONG> from the standard input
  92               instead of from the command line (see example).  Only  one  <EM>cap-</EM>
  93               <EM>name</EM>  is allowed per line.  The <STRONG>-S</STRONG> option changes the meaning of
  94               the <STRONG>0</STRONG> and <STRONG>1</STRONG> boolean and string exit codes (see  the  EXIT  CODES
  95               section).
  96
  97               Because  some capabilities may use <EM>string</EM> parameters rather than
  98               <EM>numbers</EM>, <STRONG>tput</STRONG> uses a table and the presence of parameters in its
  99               input  to  decide whether to use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>, and how to interpret
 100               the parameters.
 101
 102        <STRONG>-T</STRONG><EM>type</EM> indicates the <EM>type</EM> of terminal.  Normally this option is  unnec-
 103               essary,  because the default is taken from the environment vari-
 104               able <STRONG>TERM</STRONG>.  If <STRONG>-T</STRONG> is specified, then the shell  variables  <STRONG>LINES</STRONG>
 105               and <STRONG>COLUMNS</STRONG> will also be ignored.
 106
 107        <STRONG>-V</STRONG>     reports  the  version of ncurses which was used in this program,
 108               and exits.
 109
 110        <STRONG>-x</STRONG>     do not attempt to clear the terminal's scrollback  buffer  using
 111               the extended "E3" capability.
 112
 113
 114 </PRE><H3><a name="h3-Commands">Commands</a></H3><PRE>
 115        A few commands (<STRONG>init</STRONG>, <STRONG>reset</STRONG> and <STRONG>longname</STRONG>) are special; they are defined
 116        by the <STRONG>tput</STRONG> program.  The others are the names of <EM>capabilities</EM> from the
 117        terminal  database  (see  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  for  a list).  Although <STRONG>init</STRONG> and
 118        <STRONG>reset</STRONG> resemble capability names, <STRONG>tput</STRONG> uses several capabilities to per-
 119        form these special functions.
 120
 121        <EM>capname</EM>
 122               indicates the capability from the terminal database.
 123
 124               If  the  capability is a string that takes parameters, the argu-
 125               ments following the capability will be used  as  parameters  for
 126               the string.
 127
 128               Most  parameters  are numbers.  Only a few terminal capabilities
 129               require string parameters; <STRONG>tput</STRONG> uses a table to decide which  to
 130               pass  as  strings.   Normally <STRONG>tput</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the
 131               substitution.  If no parameters are given  for  the  capability,
 132               <STRONG>tput</STRONG> writes the string without performing the substitution.
 133
 134        <STRONG>init</STRONG>   If  the terminal database is present and an entry for the user's
 135               terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above), the following will occur:
 136
 137               (1)  first, <STRONG>tput</STRONG> retrieves the current  terminal  mode  settings
 138                    for your terminal.  It does this by successively testing
 139
 140                    <STRONG>o</STRONG>   the standard error,
 141
 142                    <STRONG>o</STRONG>   standard output,
 143
 144                    <STRONG>o</STRONG>   standard input and
 145
 146                    <STRONG>o</STRONG>   ultimately "/dev/tty"
 147
 148                    to  obtain  terminal settings.  Having retrieved these set-
 149                    tings, <STRONG>tput</STRONG> remembers which file  descriptor  to  use  when
 150                    updating settings.
 151
 152               (2)  if  the  window  size cannot be obtained from the operating
 153                    system, but the terminal description (or environment, e.g.,
 154                    <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> variables specify this), update the oper-
 155                    ating system's notion of the window size.
 156
 157               (3)  the terminal modes will be updated:
 158
 159                    <STRONG>o</STRONG>   any delays (e.g., newline) specified in the entry  will
 160                        be set in the tty driver,
 161
 162                    <STRONG>o</STRONG>   tabs  expansion  will  be turned on or off according to
 163                        the specification in the entry, and
 164
 165                    <STRONG>o</STRONG>   if tabs are not expanded, standard  tabs  will  be  set
 166                        (every 8 spaces).
 167
 168               (4)  if  present,  the terminal's initialization strings will be
 169                    output as detailed in the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> section on  <EM>Tabs</EM>  <EM>and</EM>
 170                    <EM>Initialization</EM>,
 171
 172               (5)  output is flushed.
 173
 174               If  an  entry does not contain the information needed for any of
 175               these activities, that activity will silently be skipped.
 176
 177        <STRONG>reset</STRONG>  This is similar to <STRONG>init</STRONG>, with two differences:
 178
 179               (1)  before any other initialization, the terminal modes will be
 180                    reset to a "sane" state:
 181
 182                    <STRONG>o</STRONG>   set cooked and echo modes,
 183
 184                    <STRONG>o</STRONG>   turn off cbreak and raw modes,
 185
 186                    <STRONG>o</STRONG>   turn on newline translation and
 187
 188                    <STRONG>o</STRONG>   reset  any  unset  special  characters to their default
 189                        values
 190
 191               (2)  Instead of putting out <EM>initialization</EM> strings,  the  termi-
 192                    nal's  <EM>reset</EM>  strings  will be output if present (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>,
 193                    <STRONG>rs3</STRONG>, <STRONG>rf</STRONG>).  If the <EM>reset</EM> strings are not present,  but  <EM>ini-</EM>
 194                    <EM>tialization</EM> strings are, the <EM>initialization</EM> strings will be
 195                    output.
 196
 197               Otherwise, <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
 198
 199        <STRONG>longname</STRONG>
 200               If the terminal database is present and an entry for the  user's
 201               terminal  exists  (see  <STRONG>-T</STRONG><EM>type</EM> above), then the long name of the
 202               terminal will be put out.  The long name is the last name in the
 203               first  line  of the terminal's description in the <STRONG>terminfo</STRONG> data-
 204               base [see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>].
 205
 206
 207 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
 208        <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands  specially:  it  allows
 209        for the possibility that it is invoked by a link with those names.
 210
 211        If  <STRONG>tput</STRONG>  is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
 212        <STRONG>tput</STRONG> <STRONG>reset</STRONG>.  The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility also treats a link  named  <STRONG>reset</STRONG>  spe-
 213        cially.
 214
 215        Before ncurses 6.1, the two utilities were different from each other:
 216
 217        <STRONG>o</STRONG>   <STRONG>tset</STRONG>  utility  reset the terminal modes and special characters (not
 218            done with <STRONG>tput</STRONG>).
 219
 220        <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal  capabilities  for
 221            resetting  the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
 222            <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG> in contrast to the tab-stops and  mar-
 223            gins which are set by this utility.
 224
 225        <STRONG>o</STRONG>   The  <STRONG>reset</STRONG>  program  is  usually an alias for <STRONG>tset</STRONG>, because of this
 226            difference with resetting terminal modes and special characters.
 227
 228        With the changes made for ncurses 6.1, the <EM>reset</EM>  feature  of  the  two
 229        programs is (mostly) the same.  A few differences remain:
 230
 231        <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program waits one second when resetting, in case it hap-
 232            pens to be a hardware terminal.
 233
 234        <STRONG>o</STRONG>   The two programs write the terminal initialization strings to  dif-
 235            ferent  streams (i.e., the standard error for <STRONG>tset</STRONG> and the standard
 236            output for <STRONG>tput</STRONG>).
 237
 238            <STRONG>Note:</STRONG> although these programs write to different streams, redirect-
 239            ing their output to a file will capture only part of their actions.
 240            The changes to the terminal modes are not affected  by  redirecting
 241            the output.
 242
 243        If  <STRONG>tput</STRONG>  is  invoked by a link named <STRONG>init</STRONG>, this has the same effect as
 244        <STRONG>tput</STRONG> <STRONG>init</STRONG>.  Again, you are less likely to use that link because another
 245        program named <STRONG>init</STRONG> has a more well-established use.
 246
 247
 248 </PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
 249        Besides  the  special  commands (e.g., <STRONG>clear</STRONG>), tput treats certain ter-
 250        minfo  capabilities  specially:  <STRONG>lines</STRONG>   and   <STRONG>columns</STRONG>.    tput   calls
 251        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the terminal size:
 252
 253        <STRONG>o</STRONG>   first, it gets the size from the terminal database (which generally
 254            is not provided for terminal emulators which do not  have  a  fixed
 255            window size)
 256
 257        <STRONG>o</STRONG>   then  it  asks  the operating system for the terminal's size (which
 258            generally works, unless connecting via a serial line which does not
 259            support <EM>NAWS</EM>: negotiations about window size).
 260
 261        <STRONG>o</STRONG>   finally,  it  inspects  the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG>
 262            which may override the terminal size.
 263
 264        If the <STRONG>-T</STRONG> option is given tput ignores  the  environment  variables  by
 265        calling   <STRONG>use_tioctl(TRUE)</STRONG>,  relying  upon  the  operating  system  (or
 266        finally, the terminal database).
 267
 268
 269 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 270        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 271             Initialize the terminal according to the type of terminal  in  the
 272             environmental  variable  <STRONG>TERM</STRONG>.  This command should be included in
 273             everyone's .profile after the environmental variable <STRONG>TERM</STRONG> has been
 274             exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
 275
 276        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 277             Reset  an  AT&amp;T  5620 terminal, overriding the type of terminal in
 278             the environmental variable <STRONG>TERM</STRONG>.
 279
 280        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
 281             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
 282             left  corner  of  the  screen,  usually known as the "home" cursor
 283             position).
 284
 285        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 286             Echo the clear-screen sequence for the current terminal.
 287
 288        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 289             Print the number of columns for the current terminal.
 290
 291        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
 292             Print the number of columns for the 450 terminal.
 293
 294        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
 295             Set the shell variables <STRONG>bold</STRONG>, to begin  stand-out  mode  sequence,
 296             and <STRONG>offbold</STRONG>, to end standout mode sequence, for the current termi-
 297             nal.  This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG> <STRONG>type</STRONG>
 298             <STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
 299
 300        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 301             Set  exit  code to indicate if the current terminal is a hard copy
 302             terminal.
 303
 304        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 305             Send the sequence to move the cursor to row 23, column 4.
 306
 307        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 308             Send the terminfo string for cursor-movement, with  no  parameters
 309             substituted.
 310
 311        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 312             Print  the  long  name  from the <STRONG>terminfo</STRONG> database for the type of
 313             terminal specified in the environmental variable <STRONG>TERM</STRONG>.
 314
 315             <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 316             <STRONG>&gt;</STRONG> <STRONG>clear</STRONG>
 317             <STRONG>&gt;</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 318             <STRONG>&gt;</STRONG> <STRONG>bold</STRONG>
 319             <STRONG>&gt;</STRONG> <STRONG>!</STRONG>
 320
 321             This example shows <STRONG>tput</STRONG> processing  several  capabilities  in  one
 322             invocation.   It  clears  the screen, moves the cursor to position
 323             10, 10 and turns on bold (extra bright) mode.  The list is  termi-
 324             nated by an exclamation mark (<STRONG>!</STRONG>) on a line by itself.
 325
 326
 327 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 328        <STRONG>/usr/share/terminfo</STRONG>
 329               compiled terminal description database
 330
 331        <STRONG>/usr/share/tabset/*</STRONG>
 332               tab  settings  for some terminals, in a format appropriate to be
 333               output to the terminal (escape sequences that  set  margins  and
 334               tabs);  for  more  information, see the <EM>Tabs</EM> <EM>and</EM> <EM>Initialization</EM>,
 335               section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 336
 337
 338 </PRE><H2><a name="h2-EXIT-CODES">EXIT CODES</a></H2><PRE>
 339        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
 340        any  errors  are  found, will set the exit code to 4 plus the number of
 341        lines with errors.  If no errors are found, the exit  code  is  <STRONG>0</STRONG>.   No
 342        indication  of which line failed can be given so exit code <STRONG>1</STRONG> will never
 343        appear.  Exit codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation.   If
 344        the  <STRONG>-S</STRONG>  option  is not used, the exit code depends on the type of <EM>cap-</EM>
 345        <EM>name</EM>:
 346
 347           <EM>boolean</EM>
 348                  a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
 349
 350           <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>capname</EM> is defined for this termi-
 351                  nal  <EM>type</EM>  (the value of <EM>capname</EM> is returned on standard out-
 352                  put); a value of <STRONG>1</STRONG> is set if <EM>capname</EM> is not defined for  this
 353                  terminal <EM>type</EM> (nothing is written to standard output).
 354
 355           <EM>integer</EM>
 356                  a value of <STRONG>0</STRONG> is always set, whether or not <EM>capname</EM> is defined
 357                  for this terminal <EM>type</EM>.  To determine if <EM>capname</EM>  is  defined
 358                  for  this terminal <EM>type</EM>, the user must test the value written
 359                  to standard output.  A value of <STRONG>-1</STRONG> means that <EM>capname</EM> is  not
 360                  defined for this terminal <EM>type</EM>.
 361
 362           <EM>other</EM>  <STRONG>reset</STRONG>  or  <STRONG>init</STRONG>  may fail to find their respective files.  In
 363                  that case, the exit code is set to 4 + <STRONG>errno</STRONG>.
 364
 365        Any other exit code indicates an error; see the DIAGNOSTICS section.
 366
 367
 368 </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
 369        <STRONG>tput</STRONG> prints the following error messages  and  sets  the  corresponding
 370        exit codes.
 371
 372        exit code   error message
 373        ---------------------------------------------------------------------
 374        <STRONG>0</STRONG>           (<EM>capname</EM>  is a numeric variable that is not specified in
 375                    the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> database for this  terminal  type,  e.g.
 376                    <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-T2621</STRONG> <STRONG>xmc</STRONG>)
 377        <STRONG>1</STRONG>           no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> section.
 378        <STRONG>2</STRONG>           usage error
 379        <STRONG>3</STRONG>           unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
 380        <STRONG>4</STRONG>           unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
 381        <STRONG>&gt;4</STRONG>          error occurred in -S
 382        ---------------------------------------------------------------------
 383
 384
 385 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 386        The  <STRONG>tput</STRONG>  command  was begun by Bill Joy in 1980.  The initial version
 387        only cleared the screen.
 388
 389        AT&amp;T System V provided a different <STRONG>tput</STRONG> command, whose <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>
 390        subcommands  (more  than  half  the program) were incorporated from the
 391        <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
 392
 393        Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with a new implemen-
 394        tation based on the AT&amp;T System V program <STRONG>tput</STRONG>.  Like the AT&amp;T program,
 395        Bostic's version accepted some parameters named for <EM>terminfo</EM>  <EM>capabili-</EM>
 396        <EM>ties</EM>  (<STRONG>clear</STRONG>,  <STRONG>init</STRONG>, <STRONG>longname</STRONG> and <STRONG>reset</STRONG>).  However (because he had only
 397        termcap available), it accepted <EM>termcap</EM> <EM>names</EM> for  other  capabilities.
 398        Also,  Bostic's  BSD  <STRONG>tput</STRONG> did not modify the terminal I/O modes as the
 399        earlier BSD <STRONG>tset</STRONG> had done.
 400
 401        At the same time, Bostic added a shell script named "clear", which used
 402        <STRONG>tput</STRONG> to clear the screen.
 403
 404        Both of these appeared in 4.4BSD, becoming the "modern" BSD implementa-
 405        tion of <STRONG>tput</STRONG>.
 406
 407        This implementation of <STRONG>tput</STRONG> began from a different source than AT&amp;T  or
 408        BSD:  Ross  Ridge's  <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
 409        December 1992.  Ridge's program made more sophisticated use of the ter-
 410        minal  capabilities  than the BSD program.  Eric Raymond used that <STRONG>tput</STRONG>
 411        program (and other parts of <EM>mytinfo</EM>) in ncurses in  June  1995.   Using
 412        the  portions dealing with terminal capabilities almost without change,
 413        Raymond made improvements to the way the command-line  parameters  were
 414        handled.
 415
 416
 417 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 418        This  implementation  of  <STRONG>tput</STRONG>  differs from AT&amp;T <STRONG>tput</STRONG> in two important
 419        areas:
 420
 421        <STRONG>o</STRONG>   <STRONG>tput</STRONG> <EM>capname</EM> writes to the standard output.  That  need  not  be  a
 422            regular terminal.  However, the subcommands which manipulate termi-
 423            nal modes may not use the standard output.
 424
 425            The AT&amp;T implementation's <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  commands  use  the  BSD
 426            (4.1c)  <STRONG>tset</STRONG>  source, which manipulates terminal modes.  It succes-
 427            sively tries standard output, standard error, standard input before
 428            falling back to "/dev/tty" and finally just assumes a 1200Bd termi-
 429            nal.  When updating terminal modes, it ignores errors.
 430
 431            Until changes made after ncurses 6.0, <STRONG>tput</STRONG> did not modify  terminal
 432            modes.  <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
 433            <STRONG>tset</STRONG> (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>).  If it is not  able
 434            to open a terminal, e.g., when running in <STRONG>cron</STRONG>, <STRONG>tput</STRONG> will return an
 435            error.
 436
 437        <STRONG>o</STRONG>   AT&amp;T <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by seeing if all
 438            of the characters are numeric, or not.
 439
 440            Most implementations which provide support for <EM>capname</EM> operands use
 441            the <EM>tparm</EM> function to  expand  parameters  in  it.   That  function
 442            expects  a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
 443            to know which type to use.
 444
 445            This implementation uses a table to determine the  parameter  types
 446            for the standard <EM>capname</EM> operands, and an internal library function
 447            to analyze nonstandard <EM>capname</EM> operands.
 448
 449        This implementation (unlike others) can accept both  <EM>termcap</EM>  and  <EM>ter-</EM>
 450        <EM>minfo</EM> names for the <EM>capname</EM> feature, if <EM>termcap</EM> support is compiled in.
 451        However, the predefined <EM>termcap</EM> and <EM>terminfo</EM> names have two ambiguities
 452        in this case (and the <EM>terminfo</EM> name is assumed):
 453
 454        <STRONG>o</STRONG>   The  <EM>termcap</EM>  name  <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>dl1</STRONG> (delete
 455            one line).
 456            The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG>  (delete  a
 457            given number of lines).
 458
 459        <STRONG>o</STRONG>   The  <EM>termcap</EM>  name  <STRONG>ed</STRONG>  corresponds  to the <EM>terminfo</EM> name <STRONG>rmdc</STRONG> (end
 460            delete mode).
 461            The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG>  (clear  to
 462            end of screen).
 463
 464        The  <STRONG>longname</STRONG>  and  <STRONG>-S</STRONG> options, and the parameter-substitution features
 465        used in the <STRONG>cup</STRONG> example,  were  not  supported  in  BSD  curses  before
 466        4.3reno (1989) or in AT&amp;T/USL curses before SVr4 (1988).
 467
 468        IEEE   Std   1003.1/The   Open   Group   Base  Specifications  Issue  7
 469        (POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>.
 470        There are a few interesting observations to make regarding that:
 471
 472        <STRONG>o</STRONG>   In  this implementation, <STRONG>clear</STRONG> is part of the <EM>capname</EM> support.  The
 473            others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal  capabili-
 474            ties.
 475
 476        <STRONG>o</STRONG>   Other  implementations  of  <STRONG>tput</STRONG>  on  SVr4-based  systems  such  as
 477            Solaris, IRIX64 and HPUX as well as others such as  AIX  and  Tru64
 478            provide support for <EM>capname</EM> operands.
 479
 480        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize termcap names rather than
 481            terminfo capability names in their respective <STRONG>tput</STRONG> commands.  Since
 482            2010,  NetBSD's  <STRONG>tput</STRONG>  uses  terminfo names.  Before that, it (like
 483            FreeBSD) recognized termcap names.
 484
 485        Because (apparently) <EM>all</EM> of the certified Unix systems support the full
 486        set  of  capability names, the reasoning for documenting only a few may
 487        not be apparent.
 488
 489        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>capname</EM>  and
 490            the other features used in this implementation.
 491
 492        <STRONG>o</STRONG>   That  is,  there  are  two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
 493            X/Open Curses (the full implementation).  POSIX documents a  subset
 494            to avoid the complication of including X/Open Curses and the termi-
 495            nal capabilities database.
 496
 497        <STRONG>o</STRONG>   While it is certainly possible to  write  a  <STRONG>tput</STRONG>  program  without
 498            using  curses,  none of the systems which have a curses implementa-
 499            tion provide a <STRONG>tput</STRONG> utility which does not provide the <EM>capname</EM> fea-
 500            ture.
 501
 502        X/Open  Curses  Issue  7 (2009) is the first version to document utili-
 503        ties.  However that part of X/Open  Curses  does  not  follow  existing
 504        practice (i.e., Unix features documented in SVID 3):
 505
 506        <STRONG>o</STRONG>   It  assigns exit code 4 to "invalid operand", which may be the same
 507            as <EM>unknown</EM> <EM>capability</EM>.  For instance, the source code for  Solaris'
 508            xcurses uses the term "invalid" in this case.
 509
 510        <STRONG>o</STRONG>   It  assigns  exit code 255 to a numeric variable that is not speci-
 511            fied in the terminfo database.   That  likely  is  a  documentation
 512            error,  confusing  the  <STRONG>-1</STRONG>  written  to  the standard output for an
 513            absent or cancelled numeric value versus an (unsigned) exit code.
 514
 515        The various Unix systems (AIX, HPUX, Solaris) use the  same  exit-codes
 516        as ncurses.
 517
 518        NetBSD curses documents different exit codes which do not correspond to
 519        either ncurses or X/Open.
 520
 521
 522 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 523        <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>.
 524
 525        This describes <STRONG>ncurses</STRONG> version 6.1 (patch 20190112).
 526
 527
 528
 529                                                                        <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
 530 </PRE>
 531 <div class="nav">
 532 <ul>
 533 <li><a href="#h2-NAME">NAME</a></li>
 534 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 535 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 536 <ul>
 537 <li><a href="#h3-Options">Options</a></li>
 538 <li><a href="#h3-Commands">Commands</a></li>
 539 <li><a href="#h3-Aliases">Aliases</a></li>
 540 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
 541 </ul>
 542 </li>
 543 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 544 <li><a href="#h2-FILES">FILES</a></li>
 545 <li><a href="#h2-EXIT-CODES">EXIT CODES</a></li>
 546 <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
 547 <li><a href="#h2-HISTORY">HISTORY</a></li>
 548 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 549 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 550 </ul>
 551 </div>
 552 </BODY>
 553 </HTML>