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.113 2024/04/20 19:58:50 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-04-20 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 2024-04-20 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> - 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>-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  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>       reports the version of <EM>ncurses</EM> associated with <STRONG>tput</STRONG>, and exits
 263                 with a successful status.
 264
 265        <STRONG>-x</STRONG>       prevents  "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" from attempting to clear the scrollback
 266                 buffer.
 267
 268
 269 </PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
 270        Normally, one should interpret <STRONG>tput</STRONG>'s exit statuses as follows.
 271
 272        <STRONG>Status</STRONG>   <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Not</STRONG> <STRONG>Specified</STRONG>
 273        ------------------------------------------------------------------------
 274        <STRONG>0</STRONG>        Boolean or string capability present
 275        <STRONG>1</STRONG>        Boolean or numeric capability absent
 276        <STRONG>2</STRONG>        usage error or no terminal type specified
 277        <STRONG>3</STRONG>        unrecognized terminal type
 278        <STRONG>4</STRONG>        unrecognized capability code
 279        <STRONG>&gt;4</STRONG>       system error (4 + <STRONG>errno</STRONG>)
 280
 281        When the <STRONG>-S</STRONG> option is used, some statuses change meanings.
 282
 283        <STRONG>Status</STRONG>   <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Specified</STRONG>
 284        ------------------------------------------------------------------------
 285        <STRONG>0</STRONG>        all operands interpreted
 286        <STRONG>1</STRONG>        unused
 287        <STRONG>4</STRONG>        some operands not interpreted
 288
 289
 290 </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
 291        <STRONG>tput</STRONG> reads one environment variable.
 292
 293        <EM>TERM</EM>    denotes the terminal type.  Each  terminal  type  is  distinct,
 294                though many are similar.  The <STRONG>-T</STRONG> option overrides its value.
 295
 296
 297 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 298        <EM>/usr/share/tabset</EM>
 299               tab stop initialization database
 300
 301        <EM>/usr/share/terminfo</EM>
 302               compiled terminal description database
 303
 304
 305 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 306        Over  time  <EM>ncurses</EM>  <STRONG>tput</STRONG>  has  differed  from  that of System V in two
 307        important respects, one now mostly historical.
 308
 309        <STRONG>o</STRONG>   "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be  a
 310            terminal  device.   However,  the operands that manipulate terminal
 311            modes might not use the standard output.
 312
 313            System V <STRONG>tput</STRONG>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG>  operands  use  logic  from  4.1cBSD
 314            <STRONG>tset</STRONG>,  manipulating  terminal  modes.   It  checks  the  same  file
 315            descriptors (and <EM>/dev/tty</EM>) for association with a  terminal  device
 316            as  <EM>ncurses</EM>  now does, and if none are, finally assumes a 1200 baud
 317            terminal.  When updating terminal modes, it ignores errors.
 318
 319            Until <EM>ncurses</EM> 6.1 (see  section  "HISTORY"  below),  <STRONG>tput</STRONG>  did  not
 320            modify  terminal  modes.   It  now  employs  a  scheme  similar  to
 321            System V, using functions shared with <STRONG>tset</STRONG> (and ultimately based on
 322            4.4BSD  <STRONG>tset</STRONG>).  If it is not able to open a terminal (for instance,
 323            when run by <STRONG>cron(1)</STRONG>), <STRONG>tput</STRONG> exits with an error status.
 324
 325        <STRONG>o</STRONG>   System V <STRONG>tput</STRONG> assumes that  the  type  of  a  <EM>cap-code</EM>  operand  is
 326            numeric  if all the characters of its value are decimal numbers; if
 327            they are not, it treats <EM>cap-code</EM> as a string capability.
 328
 329            Most implementations that provide support for <EM>cap-code</EM> operands use
 330            the  <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>  function  to  expand its parameters.  That function
 331            expects a mixture of numeric and string parameters, requiring  <STRONG>tput</STRONG>
 332            to know which type to use.
 333
 334            <EM>ncurses</EM>  <STRONG>tput</STRONG> uses a table to determine the parameter types for the
 335            standard <EM>cap-code</EM> operands, and an  internal  function  to  analyze
 336            nonstandard <EM>cap-code</EM> operands.
 337
 338            While  more reliable than System V's utility, a portability problem
 339            is introduced by this analysis.  An OpenBSD developer  adapted  the
 340            internal  library  function  from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>-
 341            based <STRONG>tput</STRONG> to <EM>terminfo</EM>, and modified it to interpret multiple  <EM>cap-</EM>
 342            <EM>codes</EM>  (and parameters) on the command line.  Portable applications
 343            should not rely upon this feature; <EM>ncurses</EM>  offers  it  to  support
 344            applications written specifically for OpenBSD.
 345
 346        This  implementation,  unlike others, accepts both <EM>termcap</EM> and <EM>terminfo</EM>
 347        <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in.  In  that  case,  however,
 348        the predefined <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM>
 349        assumes the <EM>terminfo</EM> code.
 350
 351        <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>
 352            to <EM>terminfo</EM>.  <EM>termcap</EM> uses the code <STRONG>DL</STRONG> for <STRONG>parm_delete_line</STRONG>.  <EM>term-</EM>
 353            <EM>info</EM> uses the code <STRONG>dl1</STRONG> for <STRONG>delete_line</STRONG>.
 354
 355        <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
 356            <EM>terminfo</EM>.  <EM>termcap</EM> uses the code <STRONG>cd</STRONG> for <STRONG>clr_eos</STRONG>.  <EM>terminfo</EM> uses the
 357            code <STRONG>rmdc</STRONG> for <STRONG>exit_delete_mode</STRONG>.
 358
 359        The  <STRONG>longname</STRONG>  operand,  <STRONG>-S</STRONG>  option,  and  the   parameter-substitution
 360        features  used in the <STRONG>cup</STRONG> example below, were not supported in AT&amp;T/USL
 361        <EM>curses</EM> before SVr4 (1989).  Later, 4.3BSD-Reno (1990) added support for
 362        <STRONG>longname</STRONG>,  and  in  1994,  NetBSD  added  support  for  the  parameter-
 363        substitution features.
 364
 365        IEEE  Std  1003.1/The  Open   Group   Base   Specifications   Issue   7
 366        (POSIX.1-2008)  documents  only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands.  A
 367        few observations of interest arise from that selection.
 368
 369        <STRONG>o</STRONG>   <EM>ncurses</EM> supports <STRONG>clear</STRONG> as it does any other standard <EM>cap-code</EM>.  The
 370            others   (<STRONG>init</STRONG>   and   <STRONG>longname</STRONG>)  do  not  correspond  to  terminal
 371            capabilities.
 372
 373        <STRONG>o</STRONG>   The <STRONG>tput</STRONG> on SVr4-based systems such as Solaris, IRIX64, and  HP-UX,
 374            as well as others such as AIX and Tru64, also support standard <EM>cap-</EM>
 375            <EM>code</EM> operands.
 376
 377        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize <EM>termcap</EM> codes rather than
 378            <EM>terminfo</EM> capability codes in their respective <STRONG>tput</STRONG> commands.  Since
 379            2010, NetBSD's <STRONG>tput</STRONG> uses <EM>terminfo</EM> codes.   Before  that,  it  (like
 380            FreeBSD) recognized <EM>termcap</EM> codes.
 381
 382            Beginning  in  2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both
 383            <EM>terminfo</EM> (tested first) and <EM>termcap</EM> (as a fallback).
 384
 385        Because (apparently) all <EM>certified</EM> Unix systems support the full set of
 386        capability  codes,  the  reason  for  documenting only a few may not be
 387        apparent.
 388
 389        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
 390            the other features used in this implementation.
 391
 392        <STRONG>o</STRONG>   That  is,  there  are  two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
 393            X/Open Curses (the full implementation).  POSIX documents a  subset
 394            to  avoid  the  complication  of  including  X/Open  Curses and the
 395            terminal capability database.
 396
 397        <STRONG>o</STRONG>   While it is certainly possible to  write  a  <STRONG>tput</STRONG>  program  without
 398            using  <EM>curses</EM>,  no  system  with a <EM>curses</EM> implementation provides a
 399            <STRONG>tput</STRONG> utility that does not also support standard <EM>cap-codes</EM>.
 400
 401        X/Open  Curses  Issue  7  (2009)  is  the  first  version  to  document
 402        utilities.  However that part of X/Open Curses does not follow existing
 403        practice (that is, System V <EM>curses</EM> behavior).
 404
 405        <STRONG>o</STRONG>   It assigns exit status 4 to "invalid operand", which may  have  the
 406            same  meaning  as  "unknown  capability".  For instance, the source
 407            code for Solaris <EM>xcurses</EM> uses the term "invalid" in this case.
 408
 409        <STRONG>o</STRONG>   It assigns exit status 255  to  a  numeric  variable  that  is  not
 410            specified in the <EM>terminfo</EM> database.  That likely is a documentation
 411            error, mistaking  the  "-1"  written  to  the  standard  output  to
 412            indicate   an   absent  or  cancelled  numeric  capability  for  an
 413            (unsigned) exit status.
 414
 415        The various System V implementations (AIX, HP-UX, Solaris) use the same
 416        exit statuses as <EM>ncurses</EM>.
 417
 418        NetBSD  <EM>curses</EM>  documents  exit  statuses  that  correspond  to neither
 419        <EM>ncurses</EM> nor X/Open Curses.
 420
 421
 422 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 423        Bill Joy wrote a <STRONG>tput</STRONG> command during development  of  4BSD  in  October
 424        1980.   This  initial version only cleared the screen, and did not ship
 425        with official distributions.
 426
 427        System V developed a different <STRONG>tput</STRONG> command.
 428
 429        <STRONG>o</STRONG>   SVr2 (1984) provided a rudimentary <STRONG>tput</STRONG> that checked the  parameter
 430            against  each  predefined capability and returned the corresponding
 431            value.   This  version  of  <STRONG>tput</STRONG>  did   not   use   <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>   for
 432            parameterized capabilities.
 433
 434        <STRONG>o</STRONG>   SVr3  (1987)  replaced  that  with  a  more extensive program whose
 435            support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than  half  the  program)
 436            incorporated the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
 437
 438        <STRONG>o</STRONG>   SVr4  (1989)  added  color  initialization by using the <STRONG>orig_colors</STRONG>
 439            (<STRONG>oc</STRONG>) and <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) capabilities in its <STRONG>init</STRONG> logic.
 440
 441        Keith Bostic refactored BSD <STRONG>tput</STRONG> for shipment in  4.3BSD-Tahoe  (1988),
 442        then  replaced  it  the  next  year  with a new implementation based on
 443        System V <STRONG>tput</STRONG>.  Bostic's version  similarly  accepted  some  parameters
 444        named  for  <EM>terminfo</EM>  (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG>, and
 445        <STRONG>reset</STRONG>.  However, because he had only  <EM>termcap</EM>  available,  it  accepted
 446        <EM>termcap</EM>  codes for other capabilities.  Also, Bostic's BSD <STRONG>tput</STRONG> did not
 447        modify the terminal modes as the earlier BSD <STRONG>tset</STRONG> had done.
 448
 449        At the same time, Bostic added a shell script named "clear"  that  used
 450        <STRONG>tput</STRONG>  to  clear the screen.  Both of these appeared in 4.4BSD, becoming
 451        the "modern" BSD implementation of <STRONG>tput</STRONG>.
 452
 453        The origin of <EM>ncurses</EM> <STRONG>tput</STRONG> lies outside both System V and BSD, in  Ross
 454        Ridge's  <EM>mytinfo</EM>  package,  published  on <EM>comp.sources.unix</EM> in December
 455        1992.  Ridge's program made more  sophisticated  use  of  the  terminal
 456        capabilities than the BSD program.  Eric Raymond used that <STRONG>tput</STRONG> program
 457        (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in  June  1995.   Incorporating
 458        the  portions dealing with terminal capabilities almost without change,
 459        Raymond made improvements  to  the  way  command-line  parameters  were
 460        handled.
 461
 462        Before <EM>ncurses</EM> 6.1 (2018), its <STRONG>tset</STRONG> and <STRONG>tput</STRONG> utilities differed.
 463
 464        <STRONG>o</STRONG>   <STRONG>tset</STRONG>  was  more effective, resetting the terminal modes and special
 465            characters.
 466
 467        <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal  capabilities  for
 468            resetting the terminal was more limited; it had only equivalents of
 469            <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>),  and
 470            not the tab stop and margin update features of <STRONG>tput</STRONG>.
 471
 472        The <STRONG>reset</STRONG> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability
 473        to reset terminal modes and special characters.
 474
 475        As of <EM>ncurses</EM> 6.1,  the  "reset"  features  of  the  two  programs  are
 476        (mostly) the same.  Two minor differences remain.
 477
 478        <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program  waits  one  second  when resetting, in case the
 479            terminal happens to be a hardware device.
 480
 481        <STRONG>o</STRONG>   The two programs  write  the  terminal  initialization  strings  to
 482            different  streams;  that  is, standard error for <STRONG>tset</STRONG> and standard
 483            output for <STRONG>tput</STRONG>.
 484
 485
 486 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 487        <STRONG>tput</STRONG> <STRONG>init</STRONG>
 488               Initialize the terminal according to the type of terminal in the
 489               <EM>TERM</EM>  environment  variable.   If  the  system does not reliably
 490               initialize the terminal upon login, this command can be included
 491               in <EM>$HOME/.profile</EM> after exporting the <EM>TERM</EM> environment variable.
 492
 493        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
 494               Reset an AT&amp;T 5620 terminal, overriding the terminal type in the
 495               <EM>TERM</EM> environment variable.
 496
 497        <STRONG>tput</STRONG> <STRONG>cnorm</STRONG>
 498               Set cursor to normal visibility.
 499
 500        <STRONG>tput</STRONG> <STRONG>home</STRONG>
 501               Move the cursor to row 0, column 0: the upper left corner of the
 502               screen, usually known as the "home" cursor position.
 503
 504        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
 505               Clear  the  screen: write the <STRONG>clear_screen</STRONG> capability's value to
 506               the standard output stream.
 507
 508        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
 509               Report the number of columns used by the current terminal type.
 510
 511        <STRONG>tput</STRONG> <STRONG>-Tadm3a</STRONG> <STRONG>cols</STRONG>
 512               Report the number of columns used by an ADM-3A terminal.
 513
 514        <STRONG>strong=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>normal=`tput</STRONG> <STRONG>rmso`</STRONG>
 515               Set shell variables to capability values: <STRONG>strong</STRONG> and <STRONG>normal</STRONG>,  to
 516               begin  and  end,  respectively, stand-out mode for the terminal.
 517               One might use these to present a prompt.
 518
 519                      printf "${strong}Username:${normal} "
 520
 521        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
 522               Indicate via exit status whether the terminal  is  a  hard  copy
 523               device.
 524
 525        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
 526               Move the cursor to row 23, column 4.
 527
 528        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
 529               Report  the  value  of the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability (used
 530               for cursor movement), with no parameters substituted.
 531
 532        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
 533               Report the <EM>terminfo</EM> database's description of the terminal  type
 534               specified in the <EM>TERM</EM> environment variable.
 535
 536        <STRONG>tput</STRONG> <STRONG>-S</STRONG>
 537               Process  multiple capabilities.  The <STRONG>-S</STRONG> option can be profitably
 538               used with a shell "here document".
 539
 540               $ <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
 541               &gt; <STRONG>clear</STRONG>
 542               &gt; <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
 543               &gt; <STRONG>bold</STRONG>
 544               &gt; <STRONG>!</STRONG>
 545
 546               The foregoing clears the screen, moves the  cursor  to  position
 547               (10, 10) and turns on bold (extra bright) mode.
 548
 549        <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
 550               Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
 551
 552
 553 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 554        <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>
 555
 556
 557
 558 ncurses 6.4                       2024-04-20                           <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
 559 </PRE>
 560 <div class="nav">
 561 <ul>
 562 <li><a href="#h2-NAME">NAME</a></li>
 563 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 564 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 565 <ul>
 566 <li><a href="#h3-Operands">Operands</a></li>
 567 <li><a href="#h3-Aliases">Aliases</a></li>
 568 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
 569 </ul>
 570 </li>
 571 <li><a href="#h2-OPTIONS">OPTIONS</a></li>
 572 <li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
 573 <li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a></li>
 574 <li><a href="#h2-FILES">FILES</a></li>
 575 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 576 <li><a href="#h2-HISTORY">HISTORY</a></li>
 577 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 578 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 579 </ul>
 580 </div>
 581 </BODY>
 582 </HTML>