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.91 2023/12/02 20:49:04 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 2023-12-02 ncurses 6.4 User commands</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">tput 1 2023-12-02 ncurses 6.4 User commands</H1>
  44 <PRE>
  45 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>                          User commands                         <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 <EM>terminfo</EM> database
  52
  53
  54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  55        <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <EM>capname</EM> [<EM>parameters</EM>]
  56        <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
  57        <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG>
  58        <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG>
  59        <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-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>STATUS</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
  96               STATUS 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 <EM>TERM</EM>.  If <STRONG>-T</STRONG> is specified,  then  the  shell  variables
 106               <EM>LINES</EM> and <EM>COLUMNS</EM> 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>     prevents <STRONG>tput</STRONG> from attempting to clear the scrollback buffer.
 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
 119        perform 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
 125               arguments  following  the  capability will be used as parameters
 126               for 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
 149                    settings,  <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                    <EM>LINES</EM> and  <EM>COLUMNS</EM>  variables  specify  this),  update  the
 155                    operating 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
 192                    terminal's <EM>reset</EM> strings will be output  if  present  (<STRONG>rs1</STRONG>,
 193                    <STRONG>rs2</STRONG>,  <STRONG>rs3</STRONG>,  <STRONG>rf</STRONG>).  If the <EM>reset</EM> strings are not present, but
 194                    <EM>initialization</EM> strings are, the <EM>initialization</EM> strings will
 195                    be 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>
 204               database [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>
 213        specially.
 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
 223            margins 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
 232            happens to be a hardware terminal.
 233
 234        <STRONG>o</STRONG>   The  two  programs  write  the  terminal  initialization strings to
 235            different streams (i.e.,  the  standard  error  for  <STRONG>tset</STRONG>  and  the
 236            standard output for <STRONG>tput</STRONG>).
 237
 238            <STRONG>Note:</STRONG>   although   these   programs  write  to  different  streams,
 239            redirecting their output to a file will capture only part of  their
 240            actions.   The  changes  to  the terminal modes are not affected by
 241            redirecting 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
 250        terminfo   capabilities   specially:   <STRONG>lines</STRONG>   and  <STRONG>cols</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  <EM>LINES</EM>  and  <EM>COLUMNS</EM>
 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-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
 270        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
 271        any errors are found, will set the exit code to 4 plus  the  number  of
 272        lines  with  errors.   If  no errors are found, the exit code is <STRONG>0</STRONG>.  No
 273        indication of which line failed can be given so exit code <STRONG>1</STRONG> will  never
 274        appear.   Exit codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation.  If
 275        the <STRONG>-S</STRONG> option is not used,  the  exit  code  depends  on  the  type  of
 276        <EM>capname</EM>:
 277
 278           <EM>boolean</EM>
 279                  a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
 280
 281           <EM>string</EM> a  value  of  <STRONG>0</STRONG>  is  set  if  the <EM>capname</EM> is defined for this
 282                  terminal <EM>type</EM> (the value of <EM>capname</EM> is returned  on  standard
 283                  output);  a  value  of <STRONG>1</STRONG> is set if <EM>capname</EM> is not defined for
 284                  this terminal <EM>type</EM> (nothing is written to standard output).
 285
 286           <EM>integer</EM>
 287                  a value of <STRONG>0</STRONG> is always set, whether or not <EM>capname</EM> is defined
 288                  for  this  terminal <EM>type</EM>.  To determine if <EM>capname</EM> is defined
 289                  for this terminal <EM>type</EM>, the user must test the value  written
 290                  to  standard output.  A value of <STRONG>-1</STRONG> means that <EM>capname</EM> is not
 291                  defined for this terminal <EM>type</EM>.
 292
 293           <EM>other</EM>  <STRONG>reset</STRONG> or <STRONG>init</STRONG> may fail to find their  respective  files.   In
 294                  that case, the exit code is set to 4 + <STRONG>errno</STRONG>.
 295
 296        Any other exit code indicates an error; see the DIAGNOSTICS section.
 297
 298
 299 </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
 300        <STRONG>tput</STRONG>  prints  the  following  error messages and sets the corresponding
 301        exit codes.
 302
 303        exit code   error message
 304        ----------------------------------------------------------------------
 305        <STRONG>0</STRONG>           (<EM>capname</EM> is a numeric variable that is not  specified  in
 306                    the  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  database  for  this terminal type, e.g.
 307                    <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-Thp2621</STRONG> <STRONG>xmc</STRONG>)
 308        <STRONG>1</STRONG>           no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>STATUS</STRONG> section.
 309        <STRONG>2</STRONG>           usage error
 310        <STRONG>3</STRONG>           unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
 311        <STRONG>4</STRONG>           unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
 312        <STRONG>&gt;4</STRONG>          error occurred in -S
 313        ----------------------------------------------------------------------
 314
 315
 316 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 317        <EM>/usr/share/tabset</EM>
 318               tab stop initialization database
 319
 320        <EM>/usr/share/terminfo</EM>
 321               compiled terminal description database
 322
 323
 324 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 325        This implementation of <STRONG>tput</STRONG> differs from AT&amp;T  <STRONG>tput</STRONG>  in  two  important
 326        areas:
 327
 328        <STRONG>o</STRONG>   <STRONG>tput</STRONG>  <EM>capname</EM>  writes  to  the standard output.  That need not be a
 329            regular  terminal.   However,  the  subcommands  which   manipulate
 330            terminal modes may not use the standard output.
 331
 332            The  AT&amp;T  implementation's  <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  commands use the BSD
 333            (4.1c)  <STRONG>tset</STRONG>  source,  which  manipulates   terminal   modes.    It
 334            successively  tries standard output, standard error, standard input
 335            before falling back to "/dev/tty" and finally just assumes a 1200Bd
 336            terminal.  When updating terminal modes, it ignores errors.
 337
 338            Until  changes made after ncurses 6.0, <STRONG>tput</STRONG> did not modify terminal
 339            modes.  <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
 340            <STRONG>tset</STRONG>  (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>).  If it is not able
 341            to open a terminal, e.g., when running in <STRONG>cron(1)</STRONG>, <STRONG>tput</STRONG> will return
 342            an error.
 343
 344        <STRONG>o</STRONG>   AT&amp;T <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by seeing if all
 345            of the characters are numeric, or not.
 346
 347            Most implementations which provide support for <EM>capname</EM> operands use
 348            the  <STRONG>tparm</STRONG>  function  to  expand  parameters  in it.  That function
 349            expects a mixture of numeric and string parameters, requiring  <STRONG>tput</STRONG>
 350            to know which type to use.
 351
 352            This  implementation  uses a table to determine the parameter types
 353            for the standard <EM>capname</EM> operands, and an internal library function
 354            to analyze nonstandard <EM>capname</EM> operands.
 355
 356            Besides  providing  more  reliable operation than AT&amp;T's utility, a
 357            portability problem is introduced  by  this  analysis:  An  OpenBSD
 358            developer  adapted  the  internal  library function from ncurses to
 359            port NetBSD's  termcap-based  <STRONG>tput</STRONG>  to  terminfo.   That  had  been
 360            modified  to  interpret  multiple  commands  on  a  line.  Portable
 361            applications should not rely upon this feature; ncurses provides it
 362            to support applications written specifically for OpenBSD.
 363
 364        This  implementation  (unlike  others)  can  accept  both  <EM>termcap</EM>  and
 365        <EM>terminfo</EM> names for the <EM>capname</EM> feature, if <EM>termcap</EM> support is  compiled
 366        in.   However,  the  predefined  <EM>termcap</EM>  and  <EM>terminfo</EM>  names have two
 367        ambiguities in this case (and the <EM>terminfo</EM> name is assumed):
 368
 369        <STRONG>o</STRONG>   The <EM>termcap</EM> name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM>  name  <STRONG>dl1</STRONG>  (delete
 370            one line).
 371            The  <EM>terminfo</EM>  name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG> (delete a
 372            given number of lines).
 373
 374        <STRONG>o</STRONG>   The <EM>termcap</EM> name <STRONG>ed</STRONG> corresponds to  the  <EM>terminfo</EM>  name  <STRONG>rmdc</STRONG>  (end
 375            delete mode).
 376            The  <EM>terminfo</EM>  name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG> (clear to
 377            end of screen).
 378
 379        The <STRONG>longname</STRONG> and <STRONG>-S</STRONG> options, and  the  parameter-substitution  features
 380        used  in  the  <STRONG>cup</STRONG>  example,  were  not  supported in BSD curses before
 381        4.3reno (1989) or in AT&amp;T/USL curses before SVr4 (1988).
 382
 383        IEEE  Std  1003.1/The  Open  Group    Base   Specifications   Issue   7
 384        (POSIX.1-2008)  documents  only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG>.
 385        There are a few interesting observations to make regarding that:
 386
 387        <STRONG>o</STRONG>   In this implementation, <STRONG>clear</STRONG> is part of the <EM>capname</EM> support.   The
 388            others   (<STRONG>init</STRONG>   and   <STRONG>longname</STRONG>)  do  not  correspond  to  terminal
 389            capabilities.
 390
 391        <STRONG>o</STRONG>   Other  implementations  of  <STRONG>tput</STRONG>  on  SVr4-based  systems  such  as
 392            Solaris,  IRIX64  and HP-UX as well as others such as AIX and Tru64
 393            provide support for <EM>capname</EM> operands.
 394
 395        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize termcap names rather than
 396            terminfo capability names in their respective <STRONG>tput</STRONG> commands.  Since
 397            2010, NetBSD's <STRONG>tput</STRONG> uses terminfo names.   Before  that,  it  (like
 398            FreeBSD) recognized termcap names.
 399
 400            Beginning  in  2021,  FreeBSD uses the ncurses <STRONG>tput</STRONG>, configured for
 401            both terminfo (tested first) and termcap (as a fallback).
 402
 403        Because (apparently) <EM>all</EM> of the certified Unix systems support the full
 404        set  of  capability names, the reasoning for documenting only a few may
 405        not be apparent.
 406
 407        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>capname</EM>  and
 408            the other features used in this implementation.
 409
 410        <STRONG>o</STRONG>   That  is,  there  are  two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
 411            X/Open Curses (the full implementation).  POSIX documents a  subset
 412            to  avoid  the  complication  of  including  X/Open  Curses and the
 413            terminal capabilities database.
 414
 415        <STRONG>o</STRONG>   While it is certainly possible to  write  a  <STRONG>tput</STRONG>  program  without
 416            using   curses,   none   of   the   systems  which  have  a  curses
 417            implementation provide a <STRONG>tput</STRONG> utility which does  not  provide  the
 418            <EM>capname</EM> feature.
 419
 420        X/Open  Curses  Issue  7  (2009)  is  the  first  version  to  document
 421        utilities.  However that part of X/Open Curses does not follow existing
 422        practice (i.e., Unix features documented in SVID 3):
 423
 424        <STRONG>o</STRONG>   It  assigns exit code 4 to "invalid operand", which may be the same
 425            as <EM>unknown</EM> <EM>capability</EM>.  For instance, the source code for  Solaris'
 426            xcurses uses the term "invalid" in this case.
 427
 428        <STRONG>o</STRONG>   It  assigns  exit  code  255  to  a  numeric  variable  that is not
 429            specified in the terminfo database.  That likely is a documentation
 430            error,  confusing  the  <STRONG>-1</STRONG>  written  to  the standard output for an
 431            absent or cancelled numeric value versus an (unsigned) exit code.
 432
 433        The various Unix systems (AIX, HP-UX, Solaris) use the same  exit-codes
 434        as ncurses.
 435
 436        NetBSD curses documents different exit codes which do not correspond to
 437        either ncurses or X/Open.
 438
 439
 440 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 441        The <STRONG>tput</STRONG> command was begun by Bill Joy in 1980.   The  initial  version
 442        only cleared the screen.
 443
 444        AT&amp;T System V provided a different <STRONG>tput</STRONG> command:
 445
 446        <STRONG>o</STRONG>   SVr2  provided  a  rudimentary  <STRONG>tput</STRONG>  which  checked  the parameter
 447            against each predefined capability and returned  the  corresponding
 448            value.   This  version  of  <STRONG>tput</STRONG>  did  not  use  <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>  for the
 449            capabilities which are parameterized.
 450
 451        <STRONG>o</STRONG>   SVr3 replaced that, a year later, by a more extensive program whose
 452            <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  subcommands  (more  than  half  the program) were
 453            incorporated from the <STRONG>reset</STRONG> feature of BSD  <STRONG>tset</STRONG>  written  by  Eric
 454            Allman.
 455
 456        <STRONG>o</STRONG>   SVr4 added color initialization using the <STRONG>orig_colors</STRONG> and <STRONG>orig_pair</STRONG>
 457            capabilities in the <STRONG>init</STRONG> subcommand.
 458
 459        Keith Bostic  replaced  the  BSD  <STRONG>tput</STRONG>  command  in  1989  with  a  new
 460        implementation  based on the AT&amp;T System V program <STRONG>tput</STRONG>.  Like the AT&amp;T
 461        program, Bostic's version accepted some parameters named  for  <EM>terminfo</EM>
 462        capabilities  (<STRONG>clear</STRONG>,  <STRONG>init</STRONG>,  <STRONG>longname</STRONG> and <STRONG>reset</STRONG>).  However (because he
 463        had only <EM>termcap</EM>  available),  it  accepted  <EM>termcap</EM>  names  for  other
 464        capabilities.   Also, Bostic's BSD <STRONG>tput</STRONG> did not modify the terminal I/O
 465        modes as the earlier BSD <STRONG>tset</STRONG> had done.
 466
 467        At the same time, Bostic added a shell script named "clear", which used
 468        <STRONG>tput</STRONG> to clear the screen.
 469
 470        Both   of   these   appeared  in  4.4BSD,  becoming  the  "modern"  BSD
 471        implementation of <STRONG>tput</STRONG>.
 472
 473        This implementation of <STRONG>tput</STRONG> began from a different source than AT&amp;T  or
 474        BSD:  Ross  Ridge's  <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
 475        December 1992.  Ridge's program made  more  sophisticated  use  of  the
 476        terminal  capabilities  than  the  BSD program.  Eric Raymond used that
 477        <STRONG>tput</STRONG> program (and other parts of <EM>mytinfo</EM>)  in  ncurses  in  June  1995.
 478        Using  the  portions  dealing with terminal capabilities almost without
 479        change,  Raymond  made  improvements  to  the  way   the   command-line
 480        parameters were handled.
 481
 482
 483 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 484        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 485             Initialize  the  terminal according to the type of terminal in the
 486             environmental variable <EM>TERM</EM>.  This command should be  included  in
 487             everyone's .profile after the environmental variable <EM>TERM</EM> has been
 488             exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
 489
 490        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 491             Reset an AT&amp;T 5620 terminal, overriding the type  of  terminal  in
 492             the environmental variable <EM>TERM</EM>.
 493
 494        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
 495             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
 496             left corner of the screen, usually  known  as  the  "home"  cursor
 497             position).
 498
 499        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 500             Echo the clear-screen sequence for the current terminal.
 501
 502        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 503             Print the number of columns for the current terminal.
 504
 505        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
 506             Print the number of columns for the 450 terminal.
 507
 508        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
 509             Set  the  shell  variables <STRONG>bold</STRONG>, to begin stand-out mode sequence,
 510             and <STRONG>offbold</STRONG>, to  end  standout  mode  sequence,  for  the  current
 511             terminal.  This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG>
 512             <STRONG>type</STRONG> <STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
 513
 514        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 515             Set exit code to indicate if the current terminal is a  hard  copy
 516             terminal.
 517
 518        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 519             Send the sequence to move the cursor to row 23, column 4.
 520
 521        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 522             Send  the  terminfo string for cursor-movement, with no parameters
 523             substituted.
 524
 525        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 526             Print the long name from the <STRONG>terminfo</STRONG> database  for  the  type  of
 527             terminal specified in the environmental variable <EM>TERM</EM>.
 528
 529             <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 530             <STRONG>&gt;</STRONG> <STRONG>clear</STRONG>
 531             <STRONG>&gt;</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 532             <STRONG>&gt;</STRONG> <STRONG>bold</STRONG>
 533             <STRONG>&gt;</STRONG> <STRONG>!</STRONG>
 534
 535             This  example  shows  <STRONG>tput</STRONG>  processing several capabilities in one
 536             invocation.  It clears the screen, moves the  cursor  to  position
 537             10,  10  and  turns  on  bold  (extra  bright)  mode.  The list is
 538             terminated by an exclamation mark (<STRONG>!</STRONG>) on a line by itself.
 539
 540
 541 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 542        <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>
 543
 544
 545
 546 ncurses 6.4                       2023-12-02                           <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
 547 </PRE>
 548 <div class="nav">
 549 <ul>
 550 <li><a href="#h2-NAME">NAME</a></li>
 551 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 552 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 553 <ul>
 554 <li><a href="#h3-Options">Options</a></li>
 555 <li><a href="#h3-Commands">Commands</a></li>
 556 <li><a href="#h3-Aliases">Aliases</a></li>
 557 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
 558 </ul>
 559 </li>
 560 <li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
 561 <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
 562 <li><a href="#h2-FILES">FILES</a></li>
 563 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 564 <li><a href="#h2-HISTORY">HISTORY</a></li>
 565 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 566 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 567 </ul>
 568 </div>
 569 </BODY>
 570 </HTML>