ncurses 5.3
[ncurses.git] / doc / html / man / tput.1.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   * t
4   ****************************************************************************
5   * Copyright (c) 1998-2000,2002 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.18 2002/10/12 13:53:20 tom Exp @
32 -->
33 <HTML>
34 <HEAD>
35 <TITLE>tput 1</TITLE>
36 <link rev=made href="mailto:bug-ncurses@gnu.org">
37 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
38 </HEAD>
39 <BODY>
40 <H1>tput 1</H1>
41 <HR>
42 <PRE>
43 <!-- Manpage converted by man2html 3.0.1 -->
44
45 </PRE>
46 <H2>NAME</H2><PRE>
47        <STRONG>tput</STRONG>,  <STRONG>reset</STRONG>  -  initialize  a  terminal or query terminfo
48        database
49
50
51 </PRE>
52 <H2>SYNOPSIS</H2><PRE>
53        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <EM>capname</EM> [<EM>parms</EM> ... ]
54        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>init</STRONG>
55        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>reset</STRONG>
56        <STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>longname</STRONG>
57        <STRONG>tput</STRONG> <STRONG>-S</STRONG>  <STRONG>&lt;&lt;</STRONG>
58        <STRONG>tput</STRONG> <STRONG>-V</STRONG>
59
60
61 </PRE>
62 <H2>DESCRIPTION</H2><PRE>
63        The <STRONG>tput</STRONG> utility uses the <STRONG>terminfo</STRONG> database  to  make  the
64        values  of terminal-dependent capabilities and information
65        available to the shell (see <STRONG><A HREF="sh.1.html">sh(1)</A></STRONG>), to initialize or reset
66        the  terminal,  or  return  the long name of the requested
67        terminal type.  <STRONG>tput</STRONG> outputs a  string  if  the  attribute
68        (<EM>cap</EM>ability  <EM>name</EM>) is of type string, or an integer if the
69        attribute is of type integer.  If the attribute is of type
70        boolean, <STRONG>tput</STRONG> simply sets the exit code (<STRONG>0</STRONG> for TRUE if the
71        terminal has the capability, <STRONG>1</STRONG> for FALSE if it does  not),
72        and  produces no output.  Before using a value returned on
73        standard output, the user should test the exit  code  [<STRONG>$?</STRONG>,
74        see  <STRONG><A HREF="sh.1.html">sh(1)</A></STRONG>]  to  be sure it is <STRONG>0</STRONG>.  (See the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> and
75        <STRONG>DIAGNOSTICS</STRONG> sections.)  For a complete list  of  capabili-
76        ties  and  the  <EM>capname</EM>  associated  with  each,  see <STRONG>ter-</STRONG>
77        <STRONG><A HREF="terminfo.1.html">minfo(1)</A></STRONG>.
78
79        <STRONG>-T</STRONG><EM>type</EM> indicates the  <EM>type</EM>  of  terminal.   Normally  this
80               option is unnecessary, because the default is taken
81               from the environment variable <STRONG>TERM</STRONG>.  If <STRONG>-T</STRONG> is spec-
82               ified,  then  the shell variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG>
83               will be ignored,and the operating system  will  not
84               be queried for the actual screen size.
85
86        <EM>capname</EM>
87               indicates the attribute from the <STRONG>terminfo</STRONG> database.
88               When <STRONG>termcap</STRONG> support is compiled  in,  the  <STRONG>termcap</STRONG>
89               name for the attribute is also accepted.
90
91        <EM>parms</EM>  If the attribute is a string that takes parameters,
92               the arguments <EM>parms</EM> will be instantiated  into  the
93               string.   An all-numeric argument will be passed to
94               the attribute as a number.
95
96               Only a few  terminfo  capabilities  require  string
97               parameters;  <STRONG>tput</STRONG>  uses  a table to decide which to
98               pass as strings.  Normally <STRONG>tput</STRONG> uses <STRONG>tparm</STRONG> (3x)  to
99               perform  the  substitution.   If  no parameters are
100               given for the attribute,  <STRONG>tput</STRONG>  writes  the  string
101               without performing the substitution.
102
103        <STRONG>-S</STRONG>     allows  more  than one capability per invocation of
104               <STRONG>tput</STRONG>.  The capabilities must be passed to <STRONG>tput</STRONG> from
105               the standard input instead of from the command line
106               (see example).  Only one  <EM>capname</EM>  is  allowed  per
107               line.   The  <STRONG>-S</STRONG> option changes the meaning of the <STRONG>0</STRONG>
108               and <STRONG>1</STRONG> boolean and string exit codes (see  the  EXIT
109               CODES section).
110
111               Again, <STRONG>tput</STRONG> uses a table and the presence of param-
112               eters in its input to decide whether to  use  <STRONG>tparm</STRONG>
113               (3x), and how to interpret the parameters.
114
115        <STRONG>-V</STRONG>     reports  the  version  of ncurses which was used in
116               this program, and exits.
117
118        <STRONG>init</STRONG>   If the <STRONG>terminfo</STRONG> database is present  and  an  entry
119               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above),
120               the following will occur: (1) if present, the  ter-
121               minal's initialization strings will be output (<STRONG>is1</STRONG>,
122               <STRONG>is2</STRONG>, <STRONG>is3</STRONG>, <STRONG>if</STRONG>, <STRONG>iprog</STRONG>), (2) any  delays  (e.g.,  new-
123               line) specified in the entry will be set in the tty
124               driver, (3) tabs expansion will be turned on or off
125               according  to  the  specification in the entry, and
126               (4) if tabs are not expanded, standard tabs will be
127               set (every 8 spaces).  If an entry does not contain
128               the information needed for any of  the  four  above
129               activities, that activity will silently be skipped.
130
131        <STRONG>reset</STRONG>  Instead of putting out initialization strings,  the
132               terminal's  reset strings will be output if present
133               (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, <STRONG>rf</STRONG>).  If the reset strings are  not
134               present,  but  initialization strings are, the ini-
135               tialization strings  will  be  output.   Otherwise,
136               <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
137
138        <STRONG>longname</STRONG>
139               If  the  <STRONG>terminfo</STRONG>  database is present and an entry
140               for the user's terminal exists (see <STRONG>-T</STRONG><EM>type</EM>  above),
141               then the long name of the terminal will be put out.
142               The long name is the last name in the first line of
143               the terminal's description in the <STRONG>terminfo</STRONG> database
144               [see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>].
145
146        If <STRONG>tput</STRONG> is invoked by a link named  <STRONG>reset</STRONG>,  this  has  the
147        same effect as <STRONG>tput</STRONG> <STRONG>reset</STRONG>.  See <STRONG>tset</STRONG> for comparison, which
148        has similar behavior.
149
150
151 </PRE>
152 <H2>EXAMPLES</H2><PRE>
153        <STRONG>tput</STRONG> <STRONG>init</STRONG>
154             Initialize the terminal according to the type of ter-
155             minal  in the environmental variable <STRONG>TERM</STRONG>.  This com-
156             mand should be included in everyone's .profile  after
157             the environmental variable <STRONG>TERM</STRONG> has been exported, as
158             illustrated on the <STRONG><A HREF="profile.5.html">profile(5)</A></STRONG> manual page.
159
160        <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
161             Reset an AT&amp;T 5620 terminal, overriding the  type  of
162             terminal in the environmental variable <STRONG>TERM</STRONG>.
163
164        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
165             Send the sequence to move the cursor to row <STRONG>0</STRONG>, column
166             <STRONG>0</STRONG> (the upper left corner of the screen, usually known
167             as the "home" cursor position).
168
169        <STRONG>tput</STRONG> <STRONG>clear</STRONG>
170             Echo the clear-screen sequence for the current termi-
171             nal.
172
173        <STRONG>tput</STRONG> <STRONG>cols</STRONG>
174             Print the number of columns for the current terminal.
175
176        <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
177             Print the number of columns for the 450 terminal.
178
179        <STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
180             Set the shell variables <STRONG>bold</STRONG>, to begin stand-out mode
181             sequence, and <STRONG>offbold</STRONG>, to end standout mode sequence,
182             for  the current terminal.  This might be followed by
183             a prompt: <STRONG>echo</STRONG>  <STRONG>"${bold}Please</STRONG>  <STRONG>type</STRONG>  <STRONG>in</STRONG>  <STRONG>your</STRONG>  <STRONG>name:</STRONG>
184             <STRONG>${offbold}\c"</STRONG>
185
186        <STRONG>tput</STRONG> <STRONG>hc</STRONG>
187             Set  exit code to indicate if the current terminal is
188             a hard copy terminal.
189
190        <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
191             Send the sequence to move the cursor to row 23,  col-
192             umn 4.
193
194        <STRONG>tput</STRONG> <STRONG>cup</STRONG>
195             Send the terminfo string for cursor-movement, with no
196             parameters substituted.
197
198        <STRONG>tput</STRONG> <STRONG>longname</STRONG>
199             Print the long name from the  <STRONG>terminfo</STRONG>  database  for
200             the  type  of terminal specified in the environmental
201             variable <STRONG>TERM</STRONG>.
202
203             <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
204             <STRONG>&gt;</STRONG> <STRONG>clear</STRONG>
205             <STRONG>&gt;</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
206             <STRONG>&gt;</STRONG> <STRONG>bold</STRONG>
207             <STRONG>&gt;</STRONG> <STRONG>!</STRONG>
208
209             This example shows <STRONG>tput</STRONG> processing several  capabili-
210             ties  in one invocation.  It clears the screen, moves
211             the cursor to position  10,  10  and  turns  on  bold
212             (extra  bright)  mode.   The list is terminated by an
213             exclamation mark (<STRONG>!</STRONG>) on a line by itself.
214
215
216 </PRE>
217 <H2>FILES</H2><PRE>
218        <STRONG>/usr/share/terminfo</STRONG>
219               compiled terminal description database
220
221        <STRONG>/usr/include/curses.h</STRONG>
222               <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> header file
223
224        <STRONG>/usr/include/term.h</STRONG>
225               <STRONG>terminfo</STRONG> header file
226
227        <STRONG>/usr/share/tabset/*</STRONG>
228               tab settings for some terminals, in a format appro-
229               priate   to  be  output  to  the  terminal  (escape
230               sequences that set  margins  and  tabs);  for  more
231               information, see the "Tabs and Initialization" sec-
232               tion of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
233
234
235 </PRE>
236 <H2>EXIT CODES</H2><PRE>
237        If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each
238        line,  and if any errors are found, will set the exit code
239        to 4 plus the number of lines with errors.  If  no  errors
240        are  found,  the  exit  code is <STRONG>0</STRONG>.  No indication of which
241        line failed can be given so exit code <STRONG>1</STRONG> will never appear.
242        Exit  codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation.
243        If the <STRONG>-S</STRONG> option is not used, the exit code depends on the
244        type of <EM>capname</EM>:
245
246             <EM>boolean</EM>
247                    a  value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
248
249             <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>capname</EM> is  defined
250                    for  this  terminal <EM>type</EM> (the value of <EM>capname</EM>
251                    is returned on standard output); a value of  <STRONG>1</STRONG>
252                    is set if <EM>capname</EM> is not defined for this ter-
253                    minal <EM>type</EM> (nothing  is  written  to  standard
254                    output).
255
256             <EM>integer</EM>
257                    a  value  of  <STRONG>0</STRONG>  is always set, whether or not
258                    <EM>capname</EM> is defined for this terminal <EM>type</EM>.  To
259                    determine  if <EM>capname</EM> is defined for this ter-
260                    minal <EM>type</EM>, the user must test the value writ-
261                    ten  to  standard output.  A value of <STRONG>-1</STRONG> means
262                    that <EM>capname</EM> is not defined for this  terminal
263                    <EM>type</EM>.
264
265             <EM>other</EM>  <STRONG>reset</STRONG>  or  <STRONG>init</STRONG> may fail to find their respec-
266                    tive files.  In that case, the  exit  code  is
267                    set to 4 + <STRONG>errno</STRONG>.
268
269        Any  other  exit code indicates an error; see the DIAGNOS-
270        TICS section.
271
272
273
274 </PRE>
275 <H2>DIAGNOSTICS</H2><PRE>
276        <STRONG>tput</STRONG> prints the following error messages and sets the cor-
277        responding exit codes.
278
279        exit code   error message
280        ---------------------------------------------------------------------
281        <STRONG>0</STRONG>           (<EM>capname</EM>  is a numeric variable that is not specified in
282                    the <STRONG><A HREF="terminfo.1.html">terminfo(1)</A></STRONG> database for this  terminal  type,  e.g.
283                    <STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-T2621</STRONG> <STRONG>xmc</STRONG>)
284        <STRONG>1</STRONG>           no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> section.
285        <STRONG>2</STRONG>           usage error
286        <STRONG>3</STRONG>           unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
287        <STRONG>4</STRONG>           unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
288        <STRONG>&gt;4</STRONG>          error occurred in -S
289        ---------------------------------------------------------------------
290
291
292 </PRE>
293 <H2>PORTABILITY</H2><PRE>
294        The  <STRONG>longname</STRONG>  and <STRONG>-S</STRONG> options, and the parameter-substitu-
295        tion features used in the <STRONG>cup</STRONG> example, are  not  supported
296        in BSD curses or in AT&amp;T/USL curses before SVr4.
297
298
299 </PRE>
300 <H2>SEE ALSO</H2><PRE>
301        <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG><A HREF="stty.1.html">stty(1)</A></STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333 </PRE>
334 <HR>
335 <ADDRESS>
336 Man(1) output converted with
337 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
338 </ADDRESS>
339 </BODY>
340 </HTML>