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.97 2023/12/31 00:16:41 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-30 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-30 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               A terminfo entry begins with one  or  more  names  by  which  an
 204               application  can refer to the entry, before the list of terminal
 205               capabilities.   The  names  are  separated  by  "|"  characters.
 206               X/Open  states  that  the  last name is the "long name" and also
 207               that it may include blanks.
 208
 209               <STRONG>tic</STRONG>  warns  if  the  last  name  does  not  include  blanks,  to
 210               accommodate  old terminfo entries which treated the long name as
 211               an optional feature.  The long name is often referred to as  the
 212               description field.
 213
 214               If  the terminal database is present and an entry for the user's
 215               terminal exists (see <STRONG>-T</STRONG> <EM>type</EM> above), <STRONG>tput</STRONG> reports the terminal's
 216               description  (or  "long name") to the standard output, without a
 217               trailing newline.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 218
 219
 220 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
 221        <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands  specially:  it  allows
 222        for the possibility that it is invoked by a link with those names.
 223
 224        If  <STRONG>tput</STRONG>  is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
 225        <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>
 226        specially.
 227
 228        Before <EM>ncurses</EM> 6.1, the two utilities were different from each other:
 229
 230        <STRONG>o</STRONG>   <STRONG>tset</STRONG>  utility  reset the terminal modes and special characters (not
 231            done with <STRONG>tput</STRONG>).
 232
 233        <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal  capabilities  for
 234            resetting  the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
 235            <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG>  in  contrast  to  the  tab-stops  and
 236            margins which are set by this utility.
 237
 238        <STRONG>o</STRONG>   The  <STRONG>reset</STRONG>  program  is  usually an alias for <STRONG>tset</STRONG>, because of this
 239            difference with resetting terminal modes and special characters.
 240
 241        With the changes made for <EM>ncurses</EM> 6.1, the <EM>reset</EM>  feature  of  the  two
 242        programs is (mostly) the same.  A few differences remain:
 243
 244        <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program  waits  one  second  when  resetting, in case it
 245            happens to be a hardware terminal.
 246
 247        <STRONG>o</STRONG>   The two programs  write  the  terminal  initialization  strings  to
 248            different  streams  (i.e.,  the  standard  error  for  <STRONG>tset</STRONG> and the
 249            standard output for <STRONG>tput</STRONG>).
 250
 251            <STRONG>Note:</STRONG>  although  these  programs  write   to   different   streams,
 252            redirecting  their output to a file will capture only part of their
 253            actions.  The changes to the terminal modes  are  not  affected  by
 254            redirecting the output.
 255
 256        If  <STRONG>tput</STRONG>  is  invoked by a link named <STRONG>init</STRONG>, this has the same effect as
 257        <STRONG>tput</STRONG> <STRONG>init</STRONG>.  Again, you are less likely to use that link because another
 258        program named <STRONG>init</STRONG> has a more well-established use.
 259
 260
 261 </PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
 262        Besides  the  special  commands  (e.g.,  <STRONG>clear</STRONG>),  tput  treats  certain
 263        terminfo  capabilities  specially:  <STRONG>lines</STRONG>   and   <STRONG>cols</STRONG>.    tput   calls
 264        <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the terminal size:
 265
 266        <STRONG>o</STRONG>   first, it gets the size from the terminal database (which generally
 267            is not provided for terminal emulators which do not  have  a  fixed
 268            window size)
 269
 270        <STRONG>o</STRONG>   then  it  asks  the operating system for the terminal's size (which
 271            generally works, unless connecting via a serial line which does not
 272            support <EM>NAWS</EM>: negotiations about window size).
 273
 274        <STRONG>o</STRONG>   finally,  it  inspects  the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM>
 275            which may override the terminal size.
 276
 277        If the <STRONG>-T</STRONG> option is given tput ignores  the  environment  variables  by
 278        calling   <STRONG>use_tioctl(TRUE)</STRONG>,  relying  upon  the  operating  system  (or
 279        finally, the terminal database).
 280
 281
 282 </PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
 283        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
 284        any  errors are found, will set the exit status to 4 plus the number of
 285        lines with errors.  If no errors are found, the exit status is  <STRONG>0</STRONG>.   No
 286        indication  of  which  line  failed  can be given so exit status <STRONG>1</STRONG> will
 287        never  appear.   Exit  statuses  <STRONG>2</STRONG>,  <STRONG>3</STRONG>,  and  <STRONG>4</STRONG>  retain   their   usual
 288        interpretation.   If the <STRONG>-S</STRONG> option is not used, the exit status depends
 289        on the type of <EM>cap-code</EM>:
 290
 291           <EM>Boolean</EM>
 292                  a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
 293
 294           <EM>string</EM> a value of <STRONG>0</STRONG> is set if  the  <EM>cap-code</EM>  is  defined  for  this
 295                  terminal  <EM>type</EM> (the value of <EM>cap-code</EM> is returned on standard
 296                  output); a value of <STRONG>1</STRONG> is set if <EM>cap-code</EM> is not  defined  for
 297                  this terminal <EM>type</EM> (nothing is written to standard output).
 298
 299           <EM>integer</EM>
 300                  a  value  of  <STRONG>0</STRONG>  is  always  set,  whether or not <EM>cap-code</EM> is
 301                  defined for this terminal <EM>type</EM>.  To determine if <EM>cap-code</EM>  is
 302                  defined  for this terminal <EM>type</EM>, the user must test the value
 303                  written to standard output.  A value of <STRONG>-1</STRONG>  means  that  <EM>cap-</EM>
 304                  <EM>code</EM> is not defined for this terminal <EM>type</EM>.
 305
 306           <EM>other</EM>  <STRONG>reset</STRONG>  or  <STRONG>init</STRONG>  may fail to find their respective files.  In
 307                  that case, the exit status is set to 4 + <STRONG>errno</STRONG>.
 308
 309        Any other exit status indicates an  error;  see  section  "DIAGNOSTICS"
 310        below.
 311
 312
 313 </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
 314        <STRONG>tput</STRONG>  prints  the  following  error messages and sets the corresponding
 315        exit statuses.
 316
 317        exit status   error message
 318        ------------------------------------------------------------------------
 319        <STRONG>0</STRONG>             (<EM>cap-code</EM> is a numeric variable that is not specified  in
 320                      the  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  database  for  this terminal type, e.g.
 321                      <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-Thp2621</STRONG> <STRONG>xmc</STRONG>)
 322        <STRONG>1</STRONG>             no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>STATUS</STRONG> section.
 323        <STRONG>2</STRONG>             usage error
 324        <STRONG>3</STRONG>             unknown terminal <EM>type</EM> or no <EM>terminfo</EM> database
 325        <STRONG>4</STRONG>             unknown <EM>terminfo</EM> capability <EM>cap-code</EM>
 326        <STRONG>&gt;4</STRONG>            error occurred in -S
 327        ------------------------------------------------------------------------
 328
 329
 330 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 331        <EM>/usr/share/tabset</EM>
 332               tab stop initialization database
 333
 334        <EM>/usr/share/terminfo</EM>
 335               compiled terminal description database
 336
 337
 338 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 339        This implementation of <STRONG>tput</STRONG> differs from AT&amp;T  <STRONG>tput</STRONG>  in  two  important
 340        areas:
 341
 342        <STRONG>o</STRONG>   <STRONG>tput</STRONG>  <EM>cap-code</EM>  writes  to the standard output.  That need not be a
 343            regular  terminal.   However,  the  subcommands  which   manipulate
 344            terminal modes may not use the standard output.
 345
 346            The  AT&amp;T  implementation's  <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  commands use the BSD
 347            (4.1c)  <STRONG>tset</STRONG>  source,  which  manipulates   terminal   modes.    It
 348            successively  tries standard output, standard error, standard input
 349            before falling back to "/dev/tty" and finally just assumes a 1200Bd
 350            terminal.  When updating terminal modes, it ignores errors.
 351
 352            Until  changes made after <EM>ncurses</EM> 6.0, <STRONG>tput</STRONG> did not modify terminal
 353            modes.  <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
 354            <STRONG>tset</STRONG>  (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>).  If it is not able
 355            to open a terminal, e.g., when running in <STRONG>cron(1)</STRONG>, <STRONG>tput</STRONG> will return
 356            an error.
 357
 358        <STRONG>o</STRONG>   AT&amp;T  <STRONG>tput</STRONG>  guesses  the type of its <EM>cap-code</EM> operands by seeing if
 359            all of the characters are numeric, or not.
 360
 361            Most implementations which provide support  for  <EM>cap-code</EM>  operands
 362            use  the  <STRONG>tparm</STRONG> function to expand parameters in it.  That function
 363            expects a mixture of numeric and string parameters, requiring  <STRONG>tput</STRONG>
 364            to know which type to use.
 365
 366            This  implementation  uses a table to determine the parameter types
 367            for  the  standard  <EM>cap-code</EM>  operands,  and  an  internal  library
 368            function to analyze nonstandard <EM>cap-code</EM> operands.
 369
 370            Besides  providing  more  reliable operation than AT&amp;T's utility, a
 371            portability problem is introduced  by  this  analysis:  An  OpenBSD
 372            developer  adapted  the  internal  library function from <EM>ncurses</EM> to
 373            port NetBSD's  termcap-based  <STRONG>tput</STRONG>  to  terminfo.   That  had  been
 374            modified  to  interpret  multiple  commands  on  a  line.  Portable
 375            applications should not rely upon this feature; <EM>ncurses</EM> provides it
 376            to support applications written specifically for OpenBSD.
 377
 378        This  implementation  (unlike  others)  can  accept  both  <EM>termcap</EM>  and
 379        <EM>terminfo</EM> names for the <EM>cap-code</EM> feature, if <EM>termcap</EM> support is compiled
 380        in.   However,  the  predefined  <EM>termcap</EM>  and  <EM>terminfo</EM>  names have two
 381        ambiguities in this case (and the <EM>terminfo</EM> name is assumed):
 382
 383        <STRONG>o</STRONG>   The <EM>termcap</EM> name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM>  name  <STRONG>dl1</STRONG>  (delete
 384            one line).
 385            The  <EM>terminfo</EM>  name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG> (delete a
 386            given number of lines).
 387
 388        <STRONG>o</STRONG>   The <EM>termcap</EM> name <STRONG>ed</STRONG> corresponds to  the  <EM>terminfo</EM>  name  <STRONG>rmdc</STRONG>  (end
 389            delete mode).
 390            The  <EM>terminfo</EM>  name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG> (clear to
 391            end of screen).
 392
 393        The <STRONG>longname</STRONG> and <STRONG>-S</STRONG> options, and  the  parameter-substitution  features
 394        used  in  the <STRONG>cup</STRONG> example, were not supported in AT&amp;T/USL <EM>curses</EM> before
 395        SVr4 (1989).  Later, 4.3BSD-Reno (1990) added support for <STRONG>longname</STRONG>, and
 396        NetBSD (1994) added support for the parameter-substitution features.
 397
 398        IEEE   Std   1003.1/The   Open   Group   Base  Specifications  Issue  7
 399        (POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>.
 400        There are a few interesting observations to make regarding that:
 401
 402        <STRONG>o</STRONG>   In this implementation, <STRONG>clear</STRONG> is part of the <EM>cap-code</EM> support.  The
 403            others  (<STRONG>init</STRONG>  and  <STRONG>longname</STRONG>)  do  not   correspond   to   terminal
 404            capabilities.
 405
 406        <STRONG>o</STRONG>   Other  implementations  of  <STRONG>tput</STRONG>  on  SVr4-based  systems  such  as
 407            Solaris, IRIX64 and HP-UX as well as others such as AIX  and  Tru64
 408            provide support for <EM>cap-code</EM> operands.
 409
 410        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize termcap names rather than
 411            terminfo capability names in their respective <STRONG>tput</STRONG> commands.  Since
 412            2010,  NetBSD's  <STRONG>tput</STRONG>  uses  terminfo names.  Before that, it (like
 413            FreeBSD) recognized termcap names.
 414
 415            Beginning in 2021, FreeBSD uses the <EM>ncurses</EM>  <STRONG>tput</STRONG>,  configured  for
 416            both terminfo (tested first) and termcap (as a fallback).
 417
 418        Because (apparently) <EM>all</EM> of the certified Unix systems support the full
 419        set of capability names, the reasoning for documenting only a  few  may
 420        not be apparent.
 421
 422        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
 423            the other features used in this implementation.
 424
 425        <STRONG>o</STRONG>   That is, there are two standards for <STRONG>tput</STRONG>:  POSIX  (a  subset)  and
 426            X/Open  Curses (the full implementation).  POSIX documents a subset
 427            to avoid the  complication  of  including  X/Open  Curses  and  the
 428            terminal capabilities database.
 429
 430        <STRONG>o</STRONG>   While  it  is  certainly  possible  to write a <STRONG>tput</STRONG> program without
 431            using <EM>curses,</EM> no system with a  <EM>curses</EM>  implementation  provides  a
 432            <STRONG>tput</STRONG> utility that does not also supply the <EM>cap-code</EM> feature.
 433
 434        X/Open  Curses  Issue  7  (2009)  is  the  first  version  to  document
 435        utilities.  However that part of X/Open Curses does not follow existing
 436        practice (that is, System V <EM>curses</EM> behavior).
 437
 438        <STRONG>o</STRONG>   It  assigns  exit  status  4 to "invalid operand", which may be the
 439            same as <EM>unknown</EM> <EM>capability</EM>.  For  instance,  the  source  code  for
 440            Solaris' xcurses uses the term "invalid" in this case.
 441
 442        <STRONG>o</STRONG>   It  assigns  exit  status  255  to  a  numeric variable that is not
 443            specified in the terminfo database.  That likely is a documentation
 444            error,  confusing  the  <STRONG>-1</STRONG>  written  to  the standard output for an
 445            absent or cancelled numeric value versus an (unsigned) exit status.
 446
 447        The various Unix systems  (AIX,  HP-UX,  Solaris)  use  the  same  exit
 448        statuses as <EM>ncurses</EM>.
 449
 450        NetBSD curses documents different exit statuses which do not correspond
 451        to either <EM>ncurses</EM> or X/Open.
 452
 453
 454 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 455        The <STRONG>tput</STRONG> command was begun by Bill Joy in 1980.   The  initial  version
 456        only cleared the screen.
 457
 458        AT&amp;T System V provided a different <STRONG>tput</STRONG> command:
 459
 460        <STRONG>o</STRONG>   SVr2  provided  a  rudimentary  <STRONG>tput</STRONG>  which  checked  the parameter
 461            against each predefined capability and returned  the  corresponding
 462            value.   This  version  of  <STRONG>tput</STRONG>  did  not  use  <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>  for the
 463            capabilities which are parameterized.
 464
 465        <STRONG>o</STRONG>   SVr3 replaced that, a year later, by a more extensive program whose
 466            <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  subcommands  (more  than  half  the program) were
 467            incorporated from the <STRONG>reset</STRONG> feature of BSD  <STRONG>tset</STRONG>  written  by  Eric
 468            Allman.
 469
 470        <STRONG>o</STRONG>   SVr4 added color initialization using the <STRONG>orig_colors</STRONG> and <STRONG>orig_pair</STRONG>
 471            capabilities in the <STRONG>init</STRONG> subcommand.
 472
 473        Keith Bostic  replaced  the  BSD  <STRONG>tput</STRONG>  command  in  1989  with  a  new
 474        implementation  based on the AT&amp;T System V program <STRONG>tput</STRONG>.  Like the AT&amp;T
 475        program, Bostic's version accepted some parameters named  for  <EM>terminfo</EM>
 476        capabilities  (<STRONG>clear</STRONG>,  <STRONG>init</STRONG>,  <STRONG>longname</STRONG> and <STRONG>reset</STRONG>).  However (because he
 477        had only <EM>termcap</EM>  available),  it  accepted  <EM>termcap</EM>  names  for  other
 478        capabilities.   Also, Bostic's BSD <STRONG>tput</STRONG> did not modify the terminal I/O
 479        modes as the earlier BSD <STRONG>tset</STRONG> had done.
 480
 481        At the same time, Bostic added a shell script named "clear", which used
 482        <STRONG>tput</STRONG> to clear the screen.
 483
 484        Both   of   these   appeared  in  4.4BSD,  becoming  the  "modern"  BSD
 485        implementation of <STRONG>tput</STRONG>.
 486
 487        This implementation of <STRONG>tput</STRONG> began from a different source than AT&amp;T  or
 488        BSD:  Ross  Ridge's  <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
 489        December 1992.  Ridge's program made  more  sophisticated  use  of  the
 490        terminal  capabilities  than  the  BSD program.  Eric Raymond used that
 491        <STRONG>tput</STRONG> program (and other parts of <EM>mytinfo</EM>)  in  <EM>ncurses</EM>  in  June  1995.
 492        Using  the  portions  dealing with terminal capabilities almost without
 493        change,  Raymond  made  improvements  to  the  way   the   command-line
 494        parameters were handled.
 495
 496
 497 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 498        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 499             Initialize  the  terminal according to the type of terminal in the
 500             environment variable <EM>TERM</EM>.  This command  should  be  included  in
 501             everyone's  .profile  after the environment variable <EM>TERM</EM> has been
 502             exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
 503
 504        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 505             Reset an AT&amp;T 5620 terminal, overriding the type  of  terminal  in
 506             the environment variable <EM>TERM</EM>.
 507
 508        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
 509             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
 510             left corner of the screen, usually  known  as  the  "home"  cursor
 511             position).
 512
 513        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 514             Echo the clear-screen sequence for the current terminal.
 515
 516        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 517             Print the number of columns for the current terminal.
 518
 519        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
 520             Print the number of columns for the 450 terminal.
 521
 522        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
 523             Set  the  shell  variables <STRONG>bold</STRONG>, to begin stand-out mode sequence,
 524             and <STRONG>offbold</STRONG>, to  end  standout  mode  sequence,  for  the  current
 525             terminal.  This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG>
 526             <STRONG>type</STRONG> <STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
 527
 528        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 529             Set exit status to indicate if the current terminal is a hard copy
 530             terminal.
 531
 532        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 533             Send the sequence to move the cursor to row 23, column 4.
 534
 535        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 536             Send  the  terminfo string for cursor-movement, with no parameters
 537             substituted.
 538
 539        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 540             Print the long name from the <EM>terminfo</EM> database  for  the  type  of
 541             terminal specified in the environment variable <EM>TERM</EM>.
 542
 543        <STRONG>tput</STRONG> <STRONG>-S</STRONG>
 544             The <STRONG>-S</STRONG> option can be profitably used with a shell "here document".
 545
 546             $ <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 547             &gt; <STRONG>clear</STRONG>
 548             &gt; <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 549             &gt; <STRONG>bold</STRONG>
 550             &gt; <STRONG>!</STRONG>
 551
 552             We see <STRONG>tput</STRONG> processing several capabilities in one invocation.  It
 553             clears the screen, moves the cursor to position (10, 10) and turns
 554             on bold (extra bright) mode.
 555
 556        <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
 557             Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
 558
 559
 560 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 561        <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>
 562
 563
 564
 565 ncurses 6.4                       2023-12-30                           <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
 566 </PRE>
 567 <div class="nav">
 568 <ul>
 569 <li><a href="#h2-NAME">NAME</a></li>
 570 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 571 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 572 <ul>
 573 <li><a href="#h3-Options">Options</a></li>
 574 <li><a href="#h3-Commands">Commands</a></li>
 575 <li><a href="#h3-Aliases">Aliases</a></li>
 576 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
 577 </ul>
 578 </li>
 579 <li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
 580 <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
 581 <li><a href="#h2-FILES">FILES</a></li>
 582 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 583 <li><a href="#h2-HISTORY">HISTORY</a></li>
 584 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 585 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 586 </ul>
 587 </div>
 588 </BODY>
 589 </HTML>