doc/html/man/tput.1.html

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