doc/html/man/tput.1.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright 2018-2023,2024 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.116 2024/06/08 20:50:34 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 2024-06-08 ncurses 6.5 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 2024-06-08 ncurses 6.5 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> - initialize a terminal, exercise its capabilities, or query <EM>term-</EM>
  52        <EM>info</EM> database
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ...
  57
  58        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
  59
  60        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG>
  61
  62        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG>
  63
  64        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>longname</STRONG>
  65
  66        <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] <STRONG>-S</STRONG>
  67
  68        <STRONG>tput</STRONG> [<STRONG>-v</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  terminal-specific
  73        capabilities  and  information available to the shell, to initialize or
  74        reset the terminal, or to report  a  description  of  the  current  (or
  75        specified)  terminal  type.  Terminal capabilities are accessed by <EM>cap-</EM>
  76        <EM>code</EM>.
  77
  78        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> discusses terminal capabilities at length  and  presents  a
  79        complete list of <EM>cap-codes</EM>.
  80
  81        When   retrieving  capability  values,  the  result  depends  upon  the
  82        capability's type.
  83
  84        Boolean  <STRONG>tput</STRONG> sets its exit status to <STRONG>0</STRONG> if the terminal possesses  <EM>cap-</EM>
  85                 <EM>code</EM>, and <STRONG>1</STRONG> if it does not.
  86
  87        numeric  <STRONG>tput</STRONG>  writes  <EM>cap-code</EM>'s  decimal value to the standard output
  88                 stream if defined (<STRONG>-1</STRONG> if it is not) followed by a newline.
  89
  90        string   <STRONG>tput</STRONG> writes <EM>cap-code</EM>'s value to the standard output stream  if
  91                 defined, without a trailing newline.
  92
  93        Before  using  a value returned on the standard output, the application
  94        should test <STRONG>tput</STRONG>'s exit status to be sure it is 0;  see  section  "EXIT
  95        STATUS" below.
  96
  97
  98 </PRE><H3><a name="h3-Operands">Operands</a></H3><PRE>
  99        Generally,  an  operand  is  a  <EM>cap-code</EM>,  a  capability  code from the
 100        terminal database, or a parameter thereto.  Three others are  specially
 101        recognized by <STRONG>tput</STRONG>: <STRONG>init</STRONG>, <STRONG>reset</STRONG>, and <STRONG>longname</STRONG>.  Although these resemble
 102        capability codes, they in fact receive special handling; we  term  them
 103        "pseudo-capabilities".
 104
 105        <EM>cap-code</EM>   indicates a capability from the terminal database.
 106
 107                   If  <EM>cap-code</EM>  is  of  string type and takes parameters, <STRONG>tput</STRONG>
 108                   interprets arguments following <EM>cap-code</EM> as  the  parameters,
 109                   up to the (fixed) quantity the capability requires.
 110
 111                   Most   parameters   are   numeric.    Only  a  few  terminal
 112                   capabilities require string parameters; <STRONG>tput</STRONG> uses a table to
 113                   decide  which  to  pass  as  strings.   Normally  <STRONG>tput</STRONG>  uses
 114                   <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the substitution.  If no parameters are
 115                   given  for  the  capability,  <STRONG>tput</STRONG> writes the string without
 116                   performing the substitution.
 117
 118        <STRONG>init</STRONG>       initializes the  terminal.   If  the  terminal  database  is
 119                   present  and  an  entry for the user's terminal type exists,
 120                   the following occur.
 121
 122                   (1)  <STRONG>tput</STRONG>  retrieves  the  terminal's  mode  settings.    It
 123                        successively  tests  the file descriptors corresponding
 124                        to
 125
 126                        <STRONG>o</STRONG>   the standard error stream,
 127
 128                        <STRONG>o</STRONG>   the standard output stream,
 129
 130                        <STRONG>o</STRONG>   the standard input stream, and
 131
 132                        <STRONG>o</STRONG>   <EM>/dev/tty</EM>
 133
 134                        to obtain terminal settings.   Having  retrieved  them,
 135                        <STRONG>tput</STRONG>  remembers  which  descriptor  to  use for further
 136                        updates.
 137
 138                   (2)  If the terminal dimensions cannot be obtained from  the
 139                        operating  system, but the environment or terminal type
 140                        database  entry  describes  them,  <STRONG>tput</STRONG>   updates   the
 141                        operating system's notion of them.
 142
 143                   (3)  <STRONG>tput</STRONG> updates the terminal modes.
 144
 145                        <STRONG>o</STRONG>   Any  delays  specified  in  the entry (for example,
 146                            when a newline is sent) are  set  in  the  terminal
 147                            driver.
 148
 149                        <STRONG>o</STRONG>   Tab   expansion   is  turned  on  or  off  per  the
 150                            specification in the entry, and
 151
 152                        <STRONG>o</STRONG>   if tabs are not expanded, standard  tabs  (every  8
 153                            spaces) are set.
 154
 155                   (4)  If  initialization capabilities, detailed in subsection
 156                        "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, are  present,
 157                        <STRONG>tput</STRONG> writes them to the standard output stream.
 158
 159                   (5)  <STRONG>tput</STRONG> flushes the standard output stream.
 160
 161                   If  an  entry  lacks  the information needed for an activity
 162                   above, that activity is silently skipped.
 163
 164        <STRONG>reset</STRONG>      re-initializes  the  terminal.    A   reset   differs   from
 165                   initialization in two ways.
 166
 167                   (1)  <STRONG>tput</STRONG> sets the the terminal modes to a "sane" state,
 168
 169                        <STRONG>o</STRONG>   enabling cooked and echo modes,
 170
 171                        <STRONG>o</STRONG>   disabling cbreak and raw modes,
 172
 173                        <STRONG>o</STRONG>   enabling newline translation, and
 174
 175                        <STRONG>o</STRONG>   setting  any  unset  special  characters  to  their
 176                            default values.
 177
 178                   (2)  If any reset capabilities are defined for the  terminal
 179                        type,   <STRONG>tput</STRONG>   writes   them   to  the  output  stream.
 180                        Otherwise,  <STRONG>tput</STRONG>  uses   any   defined   initialization
 181                        capabilities.    Reset  capabilities  are  detailed  in
 182                        subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 183
 184        <STRONG>longname</STRONG>   A <EM>terminfo</EM> entry begins with one or more names by  which  an
 185                   application  can  refer  to  the  entry,  before the list of
 186                   terminal capabilities.   The  names  are  separated  by  "|"
 187                   characters.   X/Open  Curses  terms  the last name the "long
 188                   name", and indicates that it may include blanks.
 189
 190                   <STRONG>tic</STRONG> warns if the last  name  does  not  include  blanks,  to
 191                   accommodate  old <EM>terminfo</EM> entries that treated the long name
 192                   as an optional feature.  The long name is often referred  to
 193                   as the description field.
 194
 195                   If  the  terminal  database  is present and an entry for the
 196                   user's terminal type exists, <STRONG>tput</STRONG> reports its description to
 197                   the standard output stream, without a trailing newline.  See
 198                   <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 199
 200        <EM>Note:</EM> Redirecting the output of "<STRONG>tput</STRONG> <STRONG>init</STRONG>" or "<STRONG>tput</STRONG> <STRONG>reset</STRONG>" to  a  file
 201        will capture only part of their actions.  Changes to the terminal modes
 202        are not affected by file descriptor  redirection,  since  the  terminal
 203        modes are altered via <STRONG>ioctl(2)</STRONG>.
 204
 205
 206 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
 207        If  <STRONG>tput</STRONG>  is  invoked  via  link  with any of the names <STRONG>clear</STRONG>, <STRONG>init</STRONG>, or
 208        <STRONG>reset</STRONG>, it operates as if run with the corresponding (pseudo-)capability
 209        operand.  For example, executing a link named <STRONG>reset</STRONG> that points to <STRONG>tput</STRONG>
 210        has the same effect as "<STRONG>tput</STRONG> <STRONG>reset</STRONG>".
 211
 212        This feature was introduced by <EM>ncurses</EM> 5.2 in 2000.  It is rarely used:
 213
 214        <STRONG>clear</STRONG>  is a separate program, which is both smaller and more frequently
 215               executed.
 216
 217        <STRONG>init</STRONG>   has the same name as another program in widespread use.
 218
 219        <STRONG>reset</STRONG>  is  provided  by  the  <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>  utility  (also  via a link named
 220               <STRONG>reset</STRONG>).
 221
 222
 223 </PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
 224        Besides the pseudo-capabilities (such as <STRONG>init</STRONG>), <STRONG>tput</STRONG> treats  the  <STRONG>lines</STRONG>
 225        and  <STRONG>cols</STRONG>  <EM>cap-codes</EM> specially: it may call <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the
 226        terminal size.
 227
 228        <STRONG>o</STRONG>   First, <STRONG>tput</STRONG> attempts to obtain these capabilities from the terminal
 229            database.   This generally fails for terminal emulators, which lack
 230            a fixed window size and thus omit the capabilities.
 231
 232        <STRONG>o</STRONG>   It then asks the operating system for the  terminal's  size,  which
 233            generally  works,  unless  the connection is via a serial line that
 234            does not support "NAWS": negotiations about window size.
 235
 236        <STRONG>o</STRONG>   Finally, it inspects the environment variables <EM>LINES</EM>  and  <EM>COLUMNS</EM>,
 237            which may override the terminal size.
 238
 239        If  the  <STRONG>-T</STRONG>  option is given, <STRONG>tput</STRONG> ignores the environment variables by
 240        calling  <STRONG>use_tioctl(TRUE)</STRONG>,  relying  upon  the  operating  system  (or,
 241        ultimately, the terminal database).
 242
 243
 244 </PRE><H2><a name="h2-OPTIONS">OPTIONS</a></H2><PRE>
 245        <STRONG>-S</STRONG>       retrieves  more  than  one  capability per invocation of <STRONG>tput</STRONG>.
 246                 The capabilities must be passed  to  <STRONG>tput</STRONG>  from  the  standard
 247                 input  stream  instead  of  from the command line (see section
 248                 "EXAMPLES" below).  Only one <EM>cap-code</EM>  is  allowed  per  line.
 249                 The  <STRONG>-S</STRONG>  option  changes  the  meanings  of  the  <STRONG>0</STRONG> and <STRONG>1</STRONG> exit
 250                 statuses (see section "EXIT STATUS" below).
 251
 252                 Some capabilities use string parameters  rather  than  numeric
 253                 ones.   <STRONG>tput</STRONG>  employs  a  built-in  table  and the presence of
 254                 parameters in its input to decide how to interpret  them,  and
 255                 whether to use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>.
 256
 257        <STRONG>-T</STRONG> <EM>type</EM>  indicates  the  terminal's  <EM>type</EM>.   Normally  this  option  is
 258                 unnecessary,  because  a  default  is  taken  from  the   <EM>TERM</EM>
 259                 environment variable.  If specified, the environment variables
 260                 <EM>LINES</EM> and <EM>COLUMNS</EM> are also ignored.
 261
 262        <STRONG>-v</STRONG>       causes <STRONG>tput</STRONG> to operate verbosely, reporting warnings.
 263
 264        <STRONG>-V</STRONG>       reports the version of <EM>ncurses</EM> associated with <STRONG>tput</STRONG>, and exits
 265                 with a successful status.
 266
 267        <STRONG>-x</STRONG>       prevents  "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" from attempting to clear the scrollback
 268                 buffer.
 269
 270
 271 </PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
 272        Normally, one should interpret <STRONG>tput</STRONG>'s exit statuses as follows.
 273
 274        <STRONG>Status</STRONG>   <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Not</STRONG> <STRONG>Specified</STRONG>
 275        ------------------------------------------------------------------------
 276        <STRONG>0</STRONG>        Boolean or string capability present
 277        <STRONG>1</STRONG>        Boolean or numeric capability absent
 278        <STRONG>2</STRONG>        usage error or no terminal type specified
 279        <STRONG>3</STRONG>        unrecognized terminal type
 280        <STRONG>4</STRONG>        unrecognized capability code
 281        <STRONG>&gt;4</STRONG>       system error (4 + <STRONG>errno</STRONG>)
 282
 283        When the <STRONG>-S</STRONG> option is used, some statuses change meanings.
 284
 285        <STRONG>Status</STRONG>   <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Specified</STRONG>
 286        ------------------------------------------------------------------------
 287        <STRONG>0</STRONG>        all operands interpreted
 288        <STRONG>1</STRONG>        unused
 289        <STRONG>4</STRONG>        some operands not interpreted
 290
 291
 292 </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
 293        <STRONG>tput</STRONG> reads one environment variable.
 294
 295        <EM>TERM</EM>    denotes the terminal type.  Each  terminal  type  is  distinct,
 296                though many are similar.  The <STRONG>-T</STRONG> option overrides its value.
 297
 298
 299 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 300        <EM>/usr/share/tabset</EM>
 301               tab stop initialization database
 302
 303        <EM>/usr/share/terminfo</EM>
 304               compiled terminal description database
 305
 306
 307 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 308        Over  time  <EM>ncurses</EM>  <STRONG>tput</STRONG>  has  differed  from  that of System V in two
 309        important respects, one now mostly historical.
 310
 311        <STRONG>o</STRONG>   "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be  a
 312            terminal  device.   However,  the operands that manipulate terminal
 313            modes might not use the standard output.
 314
 315            System V <STRONG>tput</STRONG>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG>  operands  use  logic  from  4.1cBSD
 316            <STRONG>tset</STRONG>,  manipulating  terminal  modes.   It  checks  the  same  file
 317            descriptors (and <EM>/dev/tty</EM>) for association with a  terminal  device
 318            as  <EM>ncurses</EM>  now does, and if none are, finally assumes a 1200 baud
 319            terminal.  When updating terminal modes, it ignores errors.
 320
 321            Until <EM>ncurses</EM> 6.1 (see  section  "HISTORY"  below),  <STRONG>tput</STRONG>  did  not
 322            modify  terminal  modes.   It  now  employs  a  scheme  similar  to
 323            System V, using functions shared with <STRONG>tset</STRONG> (and ultimately based on
 324            4.4BSD  <STRONG>tset</STRONG>).  If it is not able to open a terminal (for instance,
 325            when run by <STRONG>cron(1)</STRONG>), <STRONG>tput</STRONG> exits with an error status.
 326
 327        <STRONG>o</STRONG>   System V <STRONG>tput</STRONG> assumes that  the  type  of  a  <EM>cap-code</EM>  operand  is
 328            numeric  if all the characters of its value are decimal numbers; if
 329            they are not, it treats <EM>cap-code</EM> as a string capability.
 330
 331            Most implementations that provide support for <EM>cap-code</EM> operands use
 332            the  <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>  function  to  expand its parameters.  That function
 333            expects a mixture of numeric and string parameters, requiring  <STRONG>tput</STRONG>
 334            to know which type to use.
 335
 336            <EM>ncurses</EM>  <STRONG>tput</STRONG> uses a table to determine the parameter types for the
 337            standard <EM>cap-code</EM> operands, and an  internal  function  to  analyze
 338            nonstandard <EM>cap-code</EM> operands.
 339
 340            While  more reliable than System V's utility, a portability problem
 341            is introduced by this analysis.  An OpenBSD developer  adapted  the
 342            internal  library  function  from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>-
 343            based <STRONG>tput</STRONG> to <EM>terminfo</EM>, and modified it to interpret multiple  <EM>cap-</EM>
 344            <EM>codes</EM>  (and parameters) on the command line.  Portable applications
 345            should not rely upon this feature; <EM>ncurses</EM>  offers  it  to  support
 346            applications written specifically for OpenBSD.
 347
 348        This  implementation,  unlike others, accepts both <EM>termcap</EM> and <EM>terminfo</EM>
 349        <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in.  In  that  case,  however,
 350        the predefined <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM>
 351        assumes the <EM>terminfo</EM> code.
 352
 353        <STRONG>o</STRONG>   The <EM>cap-code</EM> <STRONG>dl</STRONG> means <STRONG>delete_line</STRONG> to <EM>termcap</EM>  but  <STRONG>parm_delete_line</STRONG>
 354            to <EM>terminfo</EM>.  <EM>termcap</EM> uses the code <STRONG>DL</STRONG> for <STRONG>parm_delete_line</STRONG>.  <EM>term-</EM>
 355            <EM>info</EM> uses the code <STRONG>dl1</STRONG> for <STRONG>delete_line</STRONG>.
 356
 357        <STRONG>o</STRONG>   The <EM>cap-code</EM> <STRONG>ed</STRONG> means <STRONG>exit_delete_mode</STRONG> to <EM>termcap</EM>  but  <STRONG>clr_eos</STRONG>  to
 358            <EM>terminfo</EM>.  <EM>termcap</EM> uses the code <STRONG>cd</STRONG> for <STRONG>clr_eos</STRONG>.  <EM>terminfo</EM> uses the
 359            code <STRONG>rmdc</STRONG> for <STRONG>exit_delete_mode</STRONG>.
 360
 361        The  <STRONG>longname</STRONG>  operand,  <STRONG>-S</STRONG>  option,  and  the   parameter-substitution
 362        features  used in the <STRONG>cup</STRONG> example below, were not supported in AT&amp;T/USL
 363        <EM>curses</EM> before SVr4 (1989).  Later, 4.3BSD-Reno (1990) added support for
 364        <STRONG>longname</STRONG>,  and  in  1994,  NetBSD  added  support  for  the  parameter-
 365        substitution features.
 366
 367        IEEE  Std  1003.1/The  Open   Group   Base   Specifications   Issue   7
 368        (POSIX.1-2008)  documents  only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands.  A
 369        few observations of interest arise from that selection.
 370
 371        <STRONG>o</STRONG>   <EM>ncurses</EM> supports <STRONG>clear</STRONG> as it does any other standard <EM>cap-code</EM>.  The
 372            others   (<STRONG>init</STRONG>   and   <STRONG>longname</STRONG>)  do  not  correspond  to  terminal
 373            capabilities.
 374
 375        <STRONG>o</STRONG>   The <STRONG>tput</STRONG> on SVr4-based systems such as Solaris, IRIX64, and  HP-UX,
 376            as well as others such as AIX and Tru64, also support standard <EM>cap-</EM>
 377            <EM>code</EM> operands.
 378
 379        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize <EM>termcap</EM> codes rather than
 380            <EM>terminfo</EM> capability codes in their respective <STRONG>tput</STRONG> commands.  Since
 381            2010, NetBSD's <STRONG>tput</STRONG> uses <EM>terminfo</EM> codes.   Before  that,  it  (like
 382            FreeBSD) recognized <EM>termcap</EM> codes.
 383
 384            Beginning  in  2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both
 385            <EM>terminfo</EM> (tested first) and <EM>termcap</EM> (as a fallback).
 386
 387        Because (apparently) all <EM>certified</EM> Unix systems support the full set of
 388        capability  codes,  the  reason  for  documenting only a few may not be
 389        apparent.
 390
 391        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
 392            the other features used in this implementation.
 393
 394        <STRONG>o</STRONG>   That  is,  there  are  two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
 395            X/Open Curses (the full implementation).  POSIX documents a  subset
 396            to  avoid  the  complication  of  including  X/Open  Curses and the
 397            terminal capability database.
 398
 399        <STRONG>o</STRONG>   While it is certainly possible to  write  a  <STRONG>tput</STRONG>  program  without
 400            using  <EM>curses</EM>,  no  system  with a <EM>curses</EM> implementation provides a
 401            <STRONG>tput</STRONG> utility that does not also support standard <EM>cap-codes</EM>.
 402
 403        X/Open  Curses  Issue  7  (2009)  is  the  first  version  to  document
 404        utilities.  However that part of X/Open Curses does not follow existing
 405        practice (that is, System V <EM>curses</EM> behavior).
 406
 407        <STRONG>o</STRONG>   It assigns exit status 4 to "invalid operand", which may  have  the
 408            same  meaning  as  "unknown  capability".  For instance, the source
 409            code for Solaris <EM>xcurses</EM> uses the term "invalid" in this case.
 410
 411        <STRONG>o</STRONG>   It assigns exit status 255  to  a  numeric  variable  that  is  not
 412            specified in the <EM>terminfo</EM> database.  That likely is a documentation
 413            error, mistaking  the  "-1"  written  to  the  standard  output  to
 414            indicate   an   absent  or  cancelled  numeric  capability  for  an
 415            (unsigned) exit status.
 416
 417        The various System V implementations (AIX, HP-UX, Solaris) use the same
 418        exit statuses as <EM>ncurses</EM>.
 419
 420        NetBSD  <EM>curses</EM>  documents  exit  statuses  that  correspond  to neither
 421        <EM>ncurses</EM> nor X/Open Curses.
 422
 423
 424 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 425        Bill Joy wrote a <STRONG>tput</STRONG> command during development  of  4BSD  in  October
 426        1980.   This  initial version only cleared the screen, and did not ship
 427        with official distributions.
 428
 429        System V developed a different <STRONG>tput</STRONG> command.
 430
 431        <STRONG>o</STRONG>   SVr2 (1984) provided a rudimentary <STRONG>tput</STRONG> that checked the  parameter
 432            against  each  predefined capability and returned the corresponding
 433            value.   This  version  of  <STRONG>tput</STRONG>  did   not   use   <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>   for
 434            parameterized capabilities.
 435
 436        <STRONG>o</STRONG>   SVr3  (1987)  replaced  that  with  a  more extensive program whose
 437            support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than  half  the  program)
 438            incorporated the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
 439
 440        <STRONG>o</STRONG>   SVr4  (1989)  added  color  initialization by using the <STRONG>orig_colors</STRONG>
 441            (<STRONG>oc</STRONG>) and <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) capabilities in its <STRONG>init</STRONG> logic.
 442
 443        Keith Bostic refactored BSD <STRONG>tput</STRONG> for shipment in  4.3BSD-Tahoe  (1988),
 444        then  replaced  it  the  next  year  with a new implementation based on
 445        System V <STRONG>tput</STRONG>.  Bostic's version  similarly  accepted  some  parameters
 446        named  for  <EM>terminfo</EM>  (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG>, and
 447        <STRONG>reset</STRONG>.  However, because he had only  <EM>termcap</EM>  available,  it  accepted
 448        <EM>termcap</EM>  codes for other capabilities.  Also, Bostic's BSD <STRONG>tput</STRONG> did not
 449        modify the terminal modes as the earlier BSD <STRONG>tset</STRONG> had done.
 450
 451        At the same time, Bostic added a shell script named "clear"  that  used
 452        <STRONG>tput</STRONG>  to  clear the screen.  Both of these appeared in 4.4BSD, becoming
 453        the "modern" BSD implementation of <STRONG>tput</STRONG>.
 454
 455        The origin of <EM>ncurses</EM> <STRONG>tput</STRONG> lies outside both System V and BSD, in  Ross
 456        Ridge's  <EM>mytinfo</EM>  package,  published  on <EM>comp.sources.unix</EM> in December
 457        1992.  Ridge's program made more  sophisticated  use  of  the  terminal
 458        capabilities than the BSD program.  Eric Raymond used that <STRONG>tput</STRONG> program
 459        (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in  June  1995.   Incorporating
 460        the  portions dealing with terminal capabilities almost without change,
 461        Raymond made improvements  to  the  way  command-line  parameters  were
 462        handled.
 463
 464        Before <EM>ncurses</EM> 6.1 (2018), its <STRONG>tset</STRONG> and <STRONG>tput</STRONG> utilities differed.
 465
 466        <STRONG>o</STRONG>   <STRONG>tset</STRONG>  was  more effective, resetting the terminal modes and special
 467            characters.
 468
 469        <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal  capabilities  for
 470            resetting the terminal was more limited; it had only equivalents of
 471            <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>),  and
 472            not the tab stop and margin update features of <STRONG>tput</STRONG>.
 473
 474        The <STRONG>reset</STRONG> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability
 475        to reset terminal modes and special characters.
 476
 477        As of <EM>ncurses</EM> 6.1,  the  "reset"  features  of  the  two  programs  are
 478        (mostly) the same.  Two minor differences remain.
 479
 480        <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program  waits  one  second  when resetting, in case the
 481            terminal happens to be a hardware device.
 482
 483        <STRONG>o</STRONG>   The two programs  write  the  terminal  initialization  strings  to
 484            different  streams;  that  is, standard error for <STRONG>tset</STRONG> and standard
 485            output for <STRONG>tput</STRONG>.
 486
 487
 488 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 489        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 490               Initialize the terminal according to the type of terminal in the
 491               <EM>TERM</EM>  environment  variable.   If  the  system does not reliably
 492               initialize the terminal upon login, this command can be included
 493               in <EM>$HOME/.profile</EM> after exporting the <EM>TERM</EM> environment variable.
 494
 495        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 496               Reset an AT&amp;T 5620 terminal, overriding the terminal type in the
 497               <EM>TERM</EM> environment variable.
 498
 499        <STRONG>tput</STRONG> <STRONG>cnorm</STRONG>
 500               Set cursor to normal visibility.
 501
 502        <STRONG>tput</STRONG> <STRONG>home</STRONG>
 503               Move the cursor to line 0, column 0: the upper  left  corner  of
 504               the screen, usually known as the "home" cursor position.
 505
 506        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 507               Clear  the  screen: write the <STRONG>clear_screen</STRONG> capability's value to
 508               the standard output stream.
 509
 510        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 511               Report the number of columns used by the current terminal type.
 512
 513        <STRONG>tput</STRONG> <STRONG>-Tadm3a</STRONG> <STRONG>cols</STRONG>
 514               Report the number of columns used by an ADM-3A terminal.
 515
 516        <STRONG>strong=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>normal=`tput</STRONG> <STRONG>rmso`</STRONG>
 517               Set shell variables to capability values: <STRONG>strong</STRONG> and <STRONG>normal</STRONG>,  to
 518               begin  and  end,  respectively, stand-out mode for the terminal.
 519               One might use these to present a prompt.
 520
 521                      printf "${strong}Username:${normal} "
 522
 523        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 524               Indicate via exit status whether the terminal  is  a  hard  copy
 525               device.
 526
 527        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 528               Move the cursor to line 23, column 4.
 529
 530        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 531               Report  the  value  of the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability (used
 532               for cursor movement), with no parameters substituted.
 533
 534        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 535               Report the <EM>terminfo</EM> database's description of the terminal  type
 536               specified in the <EM>TERM</EM> environment variable.
 537
 538        <STRONG>tput</STRONG> <STRONG>-S</STRONG>
 539               Process  multiple capabilities.  The <STRONG>-S</STRONG> option can be profitably
 540               used with a shell "here document".
 541
 542               $ <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 543               &gt; <STRONG>clear</STRONG>
 544               &gt; <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 545               &gt; <STRONG>bold</STRONG>
 546               &gt; <STRONG>!</STRONG>
 547
 548               The foregoing clears the screen, moves the  cursor  to  position
 549               (10, 10) and turns on bold (extra bright) mode.
 550
 551        <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
 552               Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
 553
 554
 555 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 556        <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>
 557
 558
 559
 560 ncurses 6.5                       2024-06-08                           <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
 561 </PRE>
 562 <div class="nav">
 563 <ul>
 564 <li><a href="#h2-NAME">NAME</a></li>
 565 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 566 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 567 <ul>
 568 <li><a href="#h3-Operands">Operands</a></li>
 569 <li><a href="#h3-Aliases">Aliases</a></li>
 570 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
 571 </ul>
 572 </li>
 573 <li><a href="#h2-OPTIONS">OPTIONS</a></li>
 574 <li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
 575 <li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a></li>
 576 <li><a href="#h2-FILES">FILES</a></li>
 577 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 578 <li><a href="#h2-HISTORY">HISTORY</a></li>
 579 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 580 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 581 </ul>
 582 </div>
 583 </BODY>
 584 </HTML>