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