606f7770a45968a2b7e4ae01f7a0b86b851540d6
[ncurses.git] / doc / html / man / tput.1.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>tput</B> - initialize a terminal or query terminfo database
9
10
11 </PRE>
12 <H2>SYNOPSIS</H2><PRE>
13        <B>tput</B> [<B>-T</B><I>type</I>] <I>capname</I> [<I>parms</I> ... ]
14        <B>tput</B> [<B>-T</B><I>type</I>] <B>init</B>
15        <B>tput</B> [<B>-T</B><I>type</I>] <B>reset</B>
16        <B>tput</B> [<B>-T</B><I>type</I>] <B>longname</B>
17        <B>tput</B> <B>-S</B>  <B>&lt;&lt;</B>
18
19
20 </PRE>
21 <H2>DESCRIPTION</H2><PRE>
22        The  <B>tput</B>  utility  uses the <B>terminfo</B> database to make the
23        values of terminal-dependent capabilities and  information
24        available to the shell (see <B><A HREF="sh.1.html">sh(1)</A></B>), to initialize or reset
25        the terminal, or return the long  name  of  the  requested
26        terminal  type.   <B>tput</B>  outputs  a string if the attribute
27        (<I>cap</I>ability <I>name</I>) is of type string, or an integer if  the
28        attribute is of type integer.  If the attribute is of type
29        boolean, <B>tput</B> simply sets the exit code (<B>0</B> for TRUE if the
30        terminal  has the capability, <B>1</B> for FALSE if it does not),
31        and produces no output.  Before using a value returned  on
32        standard  output,  the user should test the exit code [<B>$?</B>,
33        see <B><A HREF="sh.1.html">sh(1)</A></B>] to be sure it is <B>0</B>.  (See the  <B>EXIT</B>  <B>CODES</B>  and
34        <B>DIAGNOSTICS</B>  sections.)   For a complete list of capabili-
35        ties and  the  <I>capname</I>  associated  with  each,  see  <B>ter-</B>
36        <B><A HREF="minfo.5.html">minfo(5)</A></B>.
37
38        <B>-T</B><I>type</I> indicates  the  <I>type</I>  of  terminal.   Normally this
39               option is unnecessary, because the default is taken
40               from the environment variable <B>TERM</B>.  If <B>-T</B> is spec-
41               ified, then the shell variables <B>LINES</B>  and  <B>COLUMNS</B>
42               will  be  ignored,and the operating system will not
43               be queried for the actual screen size.
44
45        <I>capname</I>
46               indicates the attribute from the <B>terminfo</B> database.
47               When  <B>termcap</B>  support  is compiled in, the <B>termcap</B>
48               name for the attribute is also accepted.
49
50        <I>parms</I>  If the attribute is a string that takes parameters,
51               the  arguments  <I>parms</I> will be instantiated into the
52               string.  An all numeric argument will be passed  to
53               the attribute as a number.
54
55        <B>-S</B>     allows  more  than one capability per invocation of
56               <B>tput</B>.  The capabilities must be passed to <B>tput</B> from
57               the standard input instead of from the command line
58               (see example).  Only one  <I>capname</I>  is  allowed  per
59               line.   The  <B>-S</B> option changes the meaning of the <B>0</B>
60               and <B>1</B> boolean and string exit codes (see  the  EXIT
61               CODES section).
62
63        <B>init</B>   If  the  <B>terminfo</B>  database is present and an entry
64               for the user's terminal exists (see <B>-T</B><I>type</I>, above),
65               the  following will occur: (1) if present, the ter-
66               minal's initialization strings will be output (<B>is1</B>,
67               <B>is2</B>,  <B>is3</B>,  <B>if</B>,  <B>iprog</B>), (2) any delays (e.g., new-
68               line) specified in the entry will be set in the tty
69               driver, (3) tabs expansion will be turned on or off
70               according to the specification in  the  entry,  and
71               (4) if tabs are not expanded, standard tabs will be
72               set (every 8 spaces).  If an entry does not contain
73               the  information  needed  for any of the four above
74               activities, that activity will silently be skipped.
75
76        <B>reset</B>  Instead  of putting out initialization strings, the
77               terminal's reset strings will be output if  present
78               (<B>rs1</B>,  <B>rs2</B>, <B>rs3</B>, <B>rf</B>).  If the reset strings are not
79               present, but initialization strings are,  the  ini-
80               tialization  strings  will  be  output.  Otherwise,
81               <B>reset</B> acts identically to <B>init</B>.
82
83        <B>longname</B>
84               If the <B>terminfo</B> database is present  and  an  entry
85               for  the user's terminal exists (see <B>-T</B><I>type</I> above),
86               then the long name of the terminal will be put out.
87               The long name is the last name in the first line of
88               the terminal's description in the <B>terminfo</B> database
89               [see <B><A HREF="term.5.html">term(5)</A></B>].
90
91
92 </PRE>
93 <H2>EXAMPLES</H2><PRE>
94        <B>tput</B> <B>init</B>
95             Initialize the terminal according to the type of ter-
96             minal in the environmental variable <B>TERM</B>.  This  com-
97             mand  should be included in everyone's .profile after
98             the environmental variable <B>TERM</B> has been exported, as
99             illustrated on the <B><A HREF="profile.4.html">profile(4)</A></B> manual page.
100
101        <B>tput</B> <B>-T5620</B> <B>reset</B>
102             Reset  an  AT&amp;T 5620 terminal, overriding the type of
103             terminal in the environmental variable <B>TERM</B>.
104
105        <B>tput</B> <B>cup</B> <B>0</B> <B>0</B>
106             Send the sequence to move the cursor to row <B>0</B>, column
107             <B>0</B> (the upper left corner of the screen, usually known
108             as the "home" cursor position).
109
110        <B>tput</B> <B>clear</B>
111             Echo the clear-screen sequence for the current termi-
112             nal.
113
114        <B>tput</B> <B>cols</B>
115             Print the number of columns for the current terminal.
116
117        <B>tput</B> <B>-T450</B> <B>cols</B>
118             Print the number of columns for the 450 terminal.
119
120
121        <B>bold=`tput</B> <B>smso`</B> <B>offbold=`tput</B> <B>rmso`</B>
122             Set the shell variables <B>bold</B>, to begin stand-out mode
123             sequence, and <B>offbold</B>, to end standout mode sequence,
124             for the current terminal.  This might be followed  by
125             a  prompt:  <B>echo</B>  <B>"${bold}Please</B>  <B>type</B>  <B>in</B> <B>your</B> <B>name:</B>
126             <B>${offbold}\c"</B>
127
128        <B>tput</B> <B>hc</B>
129             Set exit code to indicate if the current terminal  is
130             a hard copy terminal.
131
132        <B>tput</B> <B>cup</B> <B>23</B> <B>4</B>
133             Send  the sequence to move the cursor to row 23, col-
134             umn 4.
135
136        <B>tput</B> <B>longname</B>
137             Print the long name from the  <B>terminfo</B>  database  for
138             the  type  of terminal specified in the environmental
139             variable <B>TERM</B>.
140
141        <B>tput</B> <B>-S</B> <B>&lt;&lt;!</B>
142        <B>&gt;</B> <B>clear</B>
143        <B>&gt;</B> <B>cup</B> <B>10</B> <B>10</B>
144        <B>&gt;</B> <B>bold</B>
145        <B>&gt;</B> <B>!</B>
146
147             This example shows tput processing several  capabili-
148             ties  in  one  invocation.   This  example clears the
149             screen, moves the cursor to position 10, 10 and turns
150             on  bold (extra bright) mode.  The list is terminated
151             by an exclamation mark (<B>!</B>) on a line by itself.
152
153
154 </PRE>
155 <H2>FILES</H2><PRE>
156        <B>@DATADIR@/terminfo</B>
157               compiled terminal description database
158
159        <B>/usr/include/curses.h</B>
160               <B><A HREF="ncurses.3x.html">curses(3x)</A></B> header file
161
162        <B>/usr/include/term.h</B>
163               <B>terminfo</B> header file
164
165        <B>@DATADIR@/tabset/*</B>
166               tab settings for some terminals, in a format appro-
167               priate   to  be  output  to  the  terminal  (escape
168               sequences that set  margins  and  tabs);  for  more
169               information, see the "Tabs and Initialization" sec-
170               tion of <B><A HREF="terminfo.4.html">terminfo(4)</A></B>
171
172
173 </PRE>
174 <H2>SEE ALSO</H2><PRE>
175        <B><A HREF="clear.1.html">clear(1)</A></B>, <B><A HREF="stty.1.html">stty(1)</A></B>, <B><A HREF="tabs.5.html">tabs(5)</A></B>.   <B><A HREF="profile.5.html">profile(5)</A></B>,  <B><A HREF="terminfo.4.html">terminfo(4)</A></B>  in
176        the  <I>System</I>  <I>Administrator</I>'<I>s</I> <I>Reference</I> <I>Manual</I>.  Chapter 10
177        of the <I>Programmer</I>'<I>s</I> <I>Guide</I>.
178
179
180 </PRE>
181 <H2>EXIT CODES</H2><PRE>
182        If <I>capname</I> is of type boolean, a value of  <B>0</B>  is  set  for
183        TRUE and <B>1</B> for FALSE unless the <B>-S</B> option is used.
184
185        If  <I>capname</I>  is of type string, a value of <B>0</B> is set if the
186        <I>capname</I> is defined for this terminal <I>type</I>  (the  value  of
187        <I>capname</I>  is  returned on standard output); a value of <B>1</B> is
188        set if <I>capname</I> is not defined for this  terminal  <I>type</I>  (a
189        null value is returned on standard output).
190
191        If  <I>capname</I> is of type boolean or string and the <B>-S</B> option
192        is used, a value of <B>0</B> is returned  to  indicate  that  all
193        lines were successful.  No indication of which line failed
194        can be given so exit code <B>1</B> will never appear.  Exit codes
195        <B>2</B>, <B>3</B>, and <B>4</B> retain their usual interpretation.
196
197        If <I>capname</I> is of type integer, a value of <B>0</B> is always set,
198        whether or not <I>capname</I> is defined for this terminal  <I>type</I>.
199        To determine if <I>capname</I> is defined for this terminal <I>type</I>,
200        the user must test the value of standard output.  A  value
201        of  <B>-1</B> means that <I>capname</I> is not defined for this terminal
202        <I>type</I>.
203
204        Any other exit code indicates an error; see  the  DIAGNOS-
205        TICS section.
206
207
208 </PRE>
209 <H2>DIAGNOSTICS</H2><PRE>
210        <B>tput</B> prints the following error messages and sets the cor-
211        responding exit codes.
212
213        exit code   error message
214        <B>0</B>           (<I>capname</I> is a numeric variable that is not specified in the
215                    <B><A HREF="terminfo.5.html">terminfo(5)</A></B> database for this terminal type, e.g.
216                    <B>tput</B> <B>-T450</B> <B>lines</B> and <B>tput</B> <B>-T2621</B> <B>xmc</B>)
217        <B>1</B>           no error message is printed, see the <B>EXIT</B> <B>CODES</B> section.
218        <B>2</B>           usage error
219        <B>3</B>           unknown terminal <I>type</I> or no <B>terminfo</B> database
220        <B>4</B>           unknown <B>terminfo</B> capability <I>capname</I>
221
222
223 </PRE>
224 <H2>PORTABILITY</H2><PRE>
225        The <B>longname</B> and <B>-S</B> options, and  the  parameter-substitu-
226        tion  features  used in the <B>cup</B> example, are not supported
227        in BSD curses or in AT&amp;T/USL curses before SVr4.
228
229
230
231
232
233
234
235
236
237
238
239 </PRE>
240 <HR>
241 <ADDRESS>
242 Man(1) output converted with
243 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
244 </ADDRESS>
245 </BODY>
246 </HTML>