doc/html/man/tput.1.html

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