ncurses 6.2 - patch 20200425
[ncurses.git] / doc / html / man / tput.1.html
1 <!-- 
2   * t
3   ****************************************************************************
4   * Copyright 2018,2020 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.64 2020/04/25 21:52:49 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</TITLE>
39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
40 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 </HEAD>
42 <BODY>
43 <H1 class="no-header">tput 1</H1>
44 <PRE>
45 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>                     General Commands Manual                    <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
46
47
48
49
50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
51        <STRONG>tput</STRONG>, <STRONG>reset</STRONG> - initialize a terminal or query terminfo database
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <EM>capname</EM> [<EM>parameters</EM>]
56        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
57        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>init</STRONG>
58        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>reset</STRONG>
59        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>longname</STRONG>
60        <STRONG>tput</STRONG> <STRONG>-S</STRONG>  <STRONG>&lt;&lt;</STRONG>
61        <STRONG>tput</STRONG> <STRONG>-V</STRONG>
62
63
64 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
65        The  <STRONG>tput</STRONG> utility uses the <STRONG>terminfo</STRONG> database to make the values of ter-
66        minal-dependent capabilities and information  available  to  the  shell
67        (see  <STRONG>sh(1)</STRONG>),  to  initialize or reset the terminal, or return the long
68        name of the requested terminal type.  The result depends upon the capa-
69        bility's type:
70
71           string
72                <STRONG>tput</STRONG>  writes  the  string  to the standard output.  No trailing
73                newline is supplied.
74
75           integer
76                <STRONG>tput</STRONG> writes the decimal value to the standard  output,  with  a
77                trailing newline.
78
79           boolean
80                <STRONG>tput</STRONG>  simply sets the exit code (<STRONG>0</STRONG> for TRUE if the terminal has
81                the capability, <STRONG>1</STRONG> for FALSE if it does not), and writes nothing
82                to the standard output.
83
84        Before  using  a value returned on the standard output, the application
85        should test the exit code (e.g., <STRONG>$?</STRONG>, see <STRONG>sh(1)</STRONG>) to be  sure  it  is  <STRONG>0</STRONG>.
86        (See  the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> and <STRONG>DIAGNOSTICS</STRONG> sections.)  For a complete list of
87        capabilities and the <EM>capname</EM> associated with each, see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
88
89
90 </PRE><H3><a name="h3-Options">Options</a></H3><PRE>
91        <STRONG>-S</STRONG>     allows more than one capability per  invocation  of  <STRONG>tput</STRONG>.   The
92               capabilities  must  be  passed  to  <STRONG>tput</STRONG> from the standard input
93               instead of from the command line (see example).  Only  one  <EM>cap-</EM>
94               <EM>name</EM>  is allowed per line.  The <STRONG>-S</STRONG> option changes the meaning of
95               the <STRONG>0</STRONG> and <STRONG>1</STRONG> boolean and string exit codes (see  the  EXIT  CODES
96               section).
97
98               Because  some capabilities may use <EM>string</EM> parameters rather than
99               <EM>numbers</EM>, <STRONG>tput</STRONG> uses a table and the presence of parameters in its
100               input  to  decide whether to use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>, and how to interpret
101               the parameters.
102
103        <STRONG>-T</STRONG><EM>type</EM> indicates the <EM>type</EM> of terminal.  Normally this option is  unnec-
104               essary,  because the default is taken from the environment vari-
105               able <STRONG>TERM</STRONG>.  If <STRONG>-T</STRONG> is specified, then the shell  variables  <STRONG>LINES</STRONG>
106               and <STRONG>COLUMNS</STRONG> will also be ignored.
107
108        <STRONG>-V</STRONG>     reports  the  version of ncurses which was used in this program,
109               and exits.
110
111        <STRONG>-x</STRONG>     do not attempt to clear the terminal's scrollback  buffer  using
112               the extended "E3" capability.
113
114
115 </PRE><H3><a name="h3-Commands">Commands</a></H3><PRE>
116        A few commands (<STRONG>init</STRONG>, <STRONG>reset</STRONG> and <STRONG>longname</STRONG>) are special; they are defined
117        by the <STRONG>tput</STRONG> program.  The others are the names of <EM>capabilities</EM> from the
118        terminal  database  (see  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  for  a list).  Although <STRONG>init</STRONG> and
119        <STRONG>reset</STRONG> resemble capability names, <STRONG>tput</STRONG> uses several capabilities to per-
120        form these special functions.
121
122        <EM>capname</EM>
123               indicates the capability from the terminal database.
124
125               If  the  capability is a string that takes parameters, the argu-
126               ments following the capability will be used  as  parameters  for
127               the string.
128
129               Most  parameters  are numbers.  Only a few terminal capabilities
130               require string parameters; <STRONG>tput</STRONG> uses a table to decide which  to
131               pass  as  strings.   Normally <STRONG>tput</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the
132               substitution.  If no parameters are given  for  the  capability,
133               <STRONG>tput</STRONG> writes the string without performing the substitution.
134
135        <STRONG>init</STRONG>   If  the terminal database is present and an entry for the user's
136               terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above), the following will occur:
137
138               (1)  first, <STRONG>tput</STRONG> retrieves the current  terminal  mode  settings
139                    for your terminal.  It does this by successively testing
140
141                    <STRONG>o</STRONG>   the standard error,
142
143                    <STRONG>o</STRONG>   standard output,
144
145                    <STRONG>o</STRONG>   standard input and
146
147                    <STRONG>o</STRONG>   ultimately "/dev/tty"
148
149                    to  obtain  terminal settings.  Having retrieved these set-
150                    tings, <STRONG>tput</STRONG> remembers which file  descriptor  to  use  when
151                    updating settings.
152
153               (2)  if  the  window  size cannot be obtained from the operating
154                    system, but the terminal description (or environment, e.g.,
155                    <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> variables specify this), update the oper-
156                    ating system's notion of the window size.
157
158               (3)  the terminal modes will be updated:
159
160                    <STRONG>o</STRONG>   any delays (e.g., newline) specified in the entry  will
161                        be set in the tty driver,
162
163                    <STRONG>o</STRONG>   tabs  expansion  will  be turned on or off according to
164                        the specification in the entry, and
165
166                    <STRONG>o</STRONG>   if tabs are not expanded, standard  tabs  will  be  set
167                        (every 8 spaces).
168
169               (4)  if  present,  the terminal's initialization strings will be
170                    output as detailed in the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> section on  <EM>Tabs</EM>  <EM>and</EM>
171                    <EM>Initialization</EM>,
172
173               (5)  output is flushed.
174
175               If  an  entry does not contain the information needed for any of
176               these activities, that activity will silently be skipped.
177
178        <STRONG>reset</STRONG>  This is similar to <STRONG>init</STRONG>, with two differences:
179
180               (1)  before any other initialization, the terminal modes will be
181                    reset to a "sane" state:
182
183                    <STRONG>o</STRONG>   set cooked and echo modes,
184
185                    <STRONG>o</STRONG>   turn off cbreak and raw modes,
186
187                    <STRONG>o</STRONG>   turn on newline translation and
188
189                    <STRONG>o</STRONG>   reset  any  unset  special  characters to their default
190                        values
191
192               (2)  Instead of putting out <EM>initialization</EM> strings,  the  termi-
193                    nal's  <EM>reset</EM>  strings  will be output if present (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>,
194                    <STRONG>rs3</STRONG>, <STRONG>rf</STRONG>).  If the <EM>reset</EM> strings are not present,  but  <EM>ini-</EM>
195                    <EM>tialization</EM> strings are, the <EM>initialization</EM> strings will be
196                    output.
197
198               Otherwise, <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
199
200        <STRONG>longname</STRONG>
201               If the terminal database is present and an entry for the  user's
202               terminal  exists  (see  <STRONG>-T</STRONG><EM>type</EM> above), then the long name of the
203               terminal will be put out.  The long name is the last name in the
204               first  line  of the terminal's description in the <STRONG>terminfo</STRONG> data-
205               base [see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>].
206
207
208 </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
209        <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands  specially:  it  allows
210        for the possibility that it is invoked by a link with those names.
211
212        If  <STRONG>tput</STRONG>  is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
213        <STRONG>tput</STRONG> <STRONG>reset</STRONG>.  The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility also treats a link  named  <STRONG>reset</STRONG>  spe-
214        cially.
215
216        Before ncurses 6.1, the two utilities were different from each other:
217
218        <STRONG>o</STRONG>   <STRONG>tset</STRONG>  utility  reset the terminal modes and special characters (not
219            done with <STRONG>tput</STRONG>).
220
221        <STRONG>o</STRONG>   On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal  capabilities  for
222            resetting  the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
223            <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG> in contrast to the tab-stops and  mar-
224            gins which are set by this utility.
225
226        <STRONG>o</STRONG>   The  <STRONG>reset</STRONG>  program  is  usually an alias for <STRONG>tset</STRONG>, because of this
227            difference with resetting terminal modes and special characters.
228
229        With the changes made for ncurses 6.1, the <EM>reset</EM>  feature  of  the  two
230        programs is (mostly) the same.  A few differences remain:
231
232        <STRONG>o</STRONG>   The  <STRONG>tset</STRONG>  program waits one second when resetting, in case it hap-
233            pens to be a hardware terminal.
234
235        <STRONG>o</STRONG>   The two programs write the terminal initialization strings to  dif-
236            ferent  streams (i.e., the standard error for <STRONG>tset</STRONG> and the standard
237            output for <STRONG>tput</STRONG>).
238
239            <STRONG>Note:</STRONG> although these programs write to different streams, redirect-
240            ing their output to a file will capture only part of their actions.
241            The changes to the terminal modes are not affected  by  redirecting
242            the output.
243
244        If  <STRONG>tput</STRONG>  is  invoked by a link named <STRONG>init</STRONG>, this has the same effect as
245        <STRONG>tput</STRONG> <STRONG>init</STRONG>.  Again, you are less likely to use that link because another
246        program named <STRONG>init</STRONG> has a more well-established use.
247
248
249 </PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
250        Besides  the  special  commands (e.g., <STRONG>clear</STRONG>), tput treats certain ter-
251        minfo capabilities specially: <STRONG>lines</STRONG> and <STRONG>cols</STRONG>.  tput calls <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>
252        to obtain the terminal size:
253
254        <STRONG>o</STRONG>   first, it gets the size from the terminal database (which generally
255            is not provided for terminal emulators which do not  have  a  fixed
256            window size)
257
258        <STRONG>o</STRONG>   then  it  asks  the operating system for the terminal's size (which
259            generally works, unless connecting via a serial line which does not
260            support <EM>NAWS</EM>: negotiations about window size).
261
262        <STRONG>o</STRONG>   finally,  it  inspects  the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG>
263            which may override the terminal size.
264
265        If the <STRONG>-T</STRONG> option is given tput ignores  the  environment  variables  by
266        calling   <STRONG>use_tioctl(TRUE)</STRONG>,  relying  upon  the  operating  system  (or
267        finally, the terminal database).
268
269
270 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
271        <STRONG>tput</STRONG> <STRONG>init</STRONG>
272             Initialize the terminal according to the type of terminal  in  the
273             environmental  variable  <STRONG>TERM</STRONG>.  This command should be included in
274             everyone's .profile after the environmental variable <STRONG>TERM</STRONG> has been
275             exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
276
277        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
278             Reset  an  AT&amp;T  5620 terminal, overriding the type of terminal in
279             the environmental variable <STRONG>TERM</STRONG>.
280
281        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
282             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
283             left  corner  of  the  screen,  usually known as the "home" cursor
284             position).
285
286        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
287             Echo the clear-screen sequence for the current terminal.
288
289        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
290             Print the number of columns for the current terminal.
291
292        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
293             Print the number of columns for the 450 terminal.
294
295        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
296             Set the shell variables <STRONG>bold</STRONG>, to begin  stand-out  mode  sequence,
297             and <STRONG>offbold</STRONG>, to end standout mode sequence, for the current termi-
298             nal.  This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG> <STRONG>type</STRONG>
299             <STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
300
301        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
302             Set  exit  code to indicate if the current terminal is a hard copy
303             terminal.
304
305        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
306             Send the sequence to move the cursor to row 23, column 4.
307
308        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
309             Send the terminfo string for cursor-movement, with  no  parameters
310             substituted.
311
312        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
313             Print  the  long  name  from the <STRONG>terminfo</STRONG> database for the type of
314             terminal specified in the environmental variable <STRONG>TERM</STRONG>.
315
316             <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
317             <STRONG>&gt;</STRONG> <STRONG>clear</STRONG>
318             <STRONG>&gt;</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
319             <STRONG>&gt;</STRONG> <STRONG>bold</STRONG>
320             <STRONG>&gt;</STRONG> <STRONG>!</STRONG>
321
322             This example shows <STRONG>tput</STRONG> processing  several  capabilities  in  one
323             invocation.   It  clears  the screen, moves the cursor to position
324             10, 10 and turns on bold (extra bright) mode.  The list is  termi-
325             nated by an exclamation mark (<STRONG>!</STRONG>) on a line by itself.
326
327
328 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
329        <STRONG>/usr/share/terminfo</STRONG>
330               compiled terminal description database
331
332        <STRONG>/usr/share/tabset/*</STRONG>
333               tab  settings  for some terminals, in a format appropriate to be
334               output to the terminal (escape sequences that  set  margins  and
335               tabs);  for  more  information, see the <EM>Tabs</EM> <EM>and</EM> <EM>Initialization</EM>,
336               section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
337
338
339 </PRE><H2><a name="h2-EXIT-CODES">EXIT CODES</a></H2><PRE>
340        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
341        any  errors  are  found, will set the exit code to 4 plus the number of
342        lines with errors.  If no errors are found, the exit  code  is  <STRONG>0</STRONG>.   No
343        indication  of which line failed can be given so exit code <STRONG>1</STRONG> will never
344        appear.  Exit codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation.   If
345        the  <STRONG>-S</STRONG>  option  is not used, the exit code depends on the type of <EM>cap-</EM>
346        <EM>name</EM>:
347
348           <EM>boolean</EM>
349                  a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
350
351           <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>capname</EM> is defined for this termi-
352                  nal  <EM>type</EM>  (the value of <EM>capname</EM> is returned on standard out-
353                  put); a value of <STRONG>1</STRONG> is set if <EM>capname</EM> is not defined for  this
354                  terminal <EM>type</EM> (nothing is written to standard output).
355
356           <EM>integer</EM>
357                  a value of <STRONG>0</STRONG> is always set, whether or not <EM>capname</EM> is defined
358                  for this terminal <EM>type</EM>.  To determine if <EM>capname</EM>  is  defined
359                  for  this terminal <EM>type</EM>, the user must test the value written
360                  to standard output.  A value of <STRONG>-1</STRONG> means that <EM>capname</EM> is  not
361                  defined for this terminal <EM>type</EM>.
362
363           <EM>other</EM>  <STRONG>reset</STRONG>  or  <STRONG>init</STRONG>  may fail to find their respective files.  In
364                  that case, the exit code is set to 4 + <STRONG>errno</STRONG>.
365
366        Any other exit code indicates an error; see the DIAGNOSTICS section.
367
368
369 </PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
370        <STRONG>tput</STRONG> prints the following error messages  and  sets  the  corresponding
371        exit codes.
372
373        exit code   error message
374        ---------------------------------------------------------------------
375        <STRONG>0</STRONG>           (<EM>capname</EM>  is a numeric variable that is not specified in
376                    the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> database for this  terminal  type,  e.g.
377                    <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-T2621</STRONG> <STRONG>xmc</STRONG>)
378        <STRONG>1</STRONG>           no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> section.
379        <STRONG>2</STRONG>           usage error
380        <STRONG>3</STRONG>           unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
381        <STRONG>4</STRONG>           unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
382        <STRONG>&gt;4</STRONG>          error occurred in -S
383        ---------------------------------------------------------------------
384
385
386 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
387        The  <STRONG>tput</STRONG>  command  was begun by Bill Joy in 1980.  The initial version
388        only cleared the screen.
389
390        AT&amp;T System V provided a different <STRONG>tput</STRONG> command, whose <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>
391        subcommands  (more  than  half  the program) were incorporated from the
392        <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
393
394        Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with a new implemen-
395        tation based on the AT&amp;T System V program <STRONG>tput</STRONG>.  Like the AT&amp;T program,
396        Bostic's version accepted some parameters named for <EM>terminfo</EM>  <EM>capabili-</EM>
397        <EM>ties</EM>  (<STRONG>clear</STRONG>,  <STRONG>init</STRONG>, <STRONG>longname</STRONG> and <STRONG>reset</STRONG>).  However (because he had only
398        termcap available), it accepted <EM>termcap</EM> <EM>names</EM> for  other  capabilities.
399        Also,  Bostic's  BSD  <STRONG>tput</STRONG> did not modify the terminal I/O modes as the
400        earlier BSD <STRONG>tset</STRONG> had done.
401
402        At the same time, Bostic added a shell script named "clear", which used
403        <STRONG>tput</STRONG> to clear the screen.
404
405        Both of these appeared in 4.4BSD, becoming the "modern" BSD implementa-
406        tion of <STRONG>tput</STRONG>.
407
408        This implementation of <STRONG>tput</STRONG> began from a different source than AT&amp;T  or
409        BSD:  Ross  Ridge's  <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
410        December 1992.  Ridge's program made more sophisticated use of the ter-
411        minal  capabilities  than the BSD program.  Eric Raymond used that <STRONG>tput</STRONG>
412        program (and other parts of <EM>mytinfo</EM>) in ncurses in  June  1995.   Using
413        the  portions dealing with terminal capabilities almost without change,
414        Raymond made improvements to the way the command-line  parameters  were
415        handled.
416
417
418 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
419        This  implementation  of  <STRONG>tput</STRONG>  differs from AT&amp;T <STRONG>tput</STRONG> in two important
420        areas:
421
422        <STRONG>o</STRONG>   <STRONG>tput</STRONG> <EM>capname</EM> writes to the standard output.  That  need  not  be  a
423            regular terminal.  However, the subcommands which manipulate termi-
424            nal modes may not use the standard output.
425
426            The AT&amp;T implementation's <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>  commands  use  the  BSD
427            (4.1c)  <STRONG>tset</STRONG>  source, which manipulates terminal modes.  It succes-
428            sively tries standard output, standard error, standard input before
429            falling back to "/dev/tty" and finally just assumes a 1200Bd termi-
430            nal.  When updating terminal modes, it ignores errors.
431
432            Until changes made after ncurses 6.0, <STRONG>tput</STRONG> did not modify  terminal
433            modes.  <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
434            <STRONG>tset</STRONG> (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>).  If it is not  able
435            to open a terminal, e.g., when running in <STRONG>cron</STRONG>, <STRONG>tput</STRONG> will return an
436            error.
437
438        <STRONG>o</STRONG>   AT&amp;T <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by seeing if all
439            of the characters are numeric, or not.
440
441            Most implementations which provide support for <EM>capname</EM> operands use
442            the <EM>tparm</EM> function to  expand  parameters  in  it.   That  function
443            expects  a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
444            to know which type to use.
445
446            This implementation uses a table to determine the  parameter  types
447            for the standard <EM>capname</EM> operands, and an internal library function
448            to analyze nonstandard <EM>capname</EM> operands.
449
450        This implementation (unlike others) can accept both  <EM>termcap</EM>  and  <EM>ter-</EM>
451        <EM>minfo</EM> names for the <EM>capname</EM> feature, if <EM>termcap</EM> support is compiled in.
452        However, the predefined <EM>termcap</EM> and <EM>terminfo</EM> names have two ambiguities
453        in this case (and the <EM>terminfo</EM> name is assumed):
454
455        <STRONG>o</STRONG>   The  <EM>termcap</EM>  name  <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>dl1</STRONG> (delete
456            one line).
457            The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG>  (delete  a
458            given number of lines).
459
460        <STRONG>o</STRONG>   The  <EM>termcap</EM>  name  <STRONG>ed</STRONG>  corresponds  to the <EM>terminfo</EM> name <STRONG>rmdc</STRONG> (end
461            delete mode).
462            The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG>  (clear  to
463            end of screen).
464
465        The  <STRONG>longname</STRONG>  and  <STRONG>-S</STRONG> options, and the parameter-substitution features
466        used in the <STRONG>cup</STRONG> example,  were  not  supported  in  BSD  curses  before
467        4.3reno (1989) or in AT&amp;T/USL curses before SVr4 (1988).
468
469        IEEE   Std   1003.1/The   Open   Group   Base  Specifications  Issue  7
470        (POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG>  and  <STRONG>reset</STRONG>.
471        There are a few interesting observations to make regarding that:
472
473        <STRONG>o</STRONG>   In  this implementation, <STRONG>clear</STRONG> is part of the <EM>capname</EM> support.  The
474            others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal  capabili-
475            ties.
476
477        <STRONG>o</STRONG>   Other  implementations  of  <STRONG>tput</STRONG>  on  SVr4-based  systems  such  as
478            Solaris, IRIX64 and HPUX as well as others such as  AIX  and  Tru64
479            provide support for <EM>capname</EM> operands.
480
481        <STRONG>o</STRONG>   A few platforms such as FreeBSD recognize termcap names rather than
482            terminfo capability names in their respective <STRONG>tput</STRONG> commands.  Since
483            2010,  NetBSD's  <STRONG>tput</STRONG>  uses  terminfo names.  Before that, it (like
484            FreeBSD) recognized termcap names.
485
486        Because (apparently) <EM>all</EM> of the certified Unix systems support the full
487        set  of  capability names, the reasoning for documenting only a few may
488        not be apparent.
489
490        <STRONG>o</STRONG>   X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>capname</EM>  and
491            the other features used in this implementation.
492
493        <STRONG>o</STRONG>   That  is,  there  are  two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
494            X/Open Curses (the full implementation).  POSIX documents a  subset
495            to avoid the complication of including X/Open Curses and the termi-
496            nal capabilities database.
497
498        <STRONG>o</STRONG>   While it is certainly possible to  write  a  <STRONG>tput</STRONG>  program  without
499            using  curses,  none of the systems which have a curses implementa-
500            tion provide a <STRONG>tput</STRONG> utility which does not provide the <EM>capname</EM> fea-
501            ture.
502
503        X/Open  Curses  Issue  7 (2009) is the first version to document utili-
504        ties.  However that part of X/Open  Curses  does  not  follow  existing
505        practice (i.e., Unix features documented in SVID 3):
506
507        <STRONG>o</STRONG>   It  assigns exit code 4 to "invalid operand", which may be the same
508            as <EM>unknown</EM> <EM>capability</EM>.  For instance, the source code for  Solaris'
509            xcurses uses the term "invalid" in this case.
510
511        <STRONG>o</STRONG>   It  assigns  exit code 255 to a numeric variable that is not speci-
512            fied in the terminfo database.   That  likely  is  a  documentation
513            error,  confusing  the  <STRONG>-1</STRONG>  written  to  the standard output for an
514            absent or cancelled numeric value versus an (unsigned) exit code.
515
516        The various Unix systems (AIX, HPUX, Solaris) use the  same  exit-codes
517        as ncurses.
518
519        NetBSD curses documents different exit codes which do not correspond to
520        either ncurses or X/Open.
521
522
523 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
524        <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="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>.
525
526        This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200425).
527
528
529
530                                                                        <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
531 </PRE>
532 <div class="nav">
533 <ul>
534 <li><a href="#h2-NAME">NAME</a></li>
535 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
536 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
537 <ul>
538 <li><a href="#h3-Options">Options</a></li>
539 <li><a href="#h3-Commands">Commands</a></li>
540 <li><a href="#h3-Aliases">Aliases</a></li>
541 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
542 </ul>
543 </li>
544 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
545 <li><a href="#h2-FILES">FILES</a></li>
546 <li><a href="#h2-EXIT-CODES">EXIT CODES</a></li>
547 <li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
548 <li><a href="#h2-HISTORY">HISTORY</a></li>
549 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
550 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
551 </ul>
552 </div>
553 </BODY>
554 </HTML>