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