a1b81bcb08c5879111bd74e2c63a5e4ce87c0eef
[ncurses.git] / man / tput.1
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc.              *
4 .\"                                                                          *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
6 .\" copy of this software and associated documentation files (the            *
7 .\" "Software"), to deal in the Software without restriction, including      *
8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
10 .\" copies of the Software, and to permit persons to whom the Software is    *
11 .\" furnished to do so, subject to the following conditions:                 *
12 .\"                                                                          *
13 .\" The above copyright notice and this permission notice shall be included  *
14 .\" in all copies or substantial portions of the Software.                   *
15 .\"                                                                          *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23 .\"                                                                          *
24 .\" Except as contained in this notice, the name(s) of the above copyright   *
25 .\" holders shall not be used in advertising or otherwise to promote the     *
26 .\" sale, use or other dealings in this Software without prior written       *
27 .\" authorization.                                                           *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: tput.1,v 1.32 2012/07/14 21:06:45 tom Exp $
31 .TH @TPUT@ 1 ""
32 .ds d @TERMINFO@
33 .ds n 1
34 .SH NAME
35 \fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
36 .SH SYNOPSIS
37 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ]
38 .br
39 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
40 .br
41 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
42 .br
43 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
44 .br
45 \fB@TPUT@ \-S\fR  \fB<<\fR
46 .br
47 \fB@TPUT@ \-V\fR
48 .br
49 .SH DESCRIPTION
50 The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
51 values of terminal-dependent capabilities and information available to
52 the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
53 return the long name of the requested terminal type.
54 The result depends upon the capability's type:
55 .RS
56 .TP 5
57 string
58 \fB@TPUT@\fR writes the string to the standard output.
59 No trailing newline is supplied.
60 .TP
61 integer
62 \fB@TPUT@\fR writes the decimal value to the standard output,
63 with a trailing newline.
64 .TP
65 boolean
66 \fB@TPUT@\fR simply sets the exit code
67 (\fB0\fR for TRUE if the terminal has the capability,
68 \fB1\fR for FALSE if it does not),
69 and writes nothing to the standard output.
70 .RE
71 .PP
72 Before using a value returned on the standard output,
73 the application should test the exit code
74 (e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
75 (See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
76 For a complete list of capabilities
77 and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
78 .TP
79 \fB\-T\fR\fItype\fR
80 indicates the \fItype\fR of terminal.
81 Normally this option is
82 unnecessary, because the default is taken from the environment
83 variable \fBTERM\fR.
84 If \fB\-T\fR is specified, then the shell
85 variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
86 .TP
87 \fIcapname\fR
88 indicates the capability from the \fBterminfo\fR database.  When
89 \fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
90 the capability is also accepted.
91 .TP
92 \fIparms\fR
93 If the capability is a string that takes parameters, the arguments
94 \fIparms\fR will be instantiated into the string.
95 .IP
96 Most parameters are numbers.
97 Only a few terminfo capabilities require string parameters;
98 \fB@TPUT@\fR uses a table to decide which to pass as strings.
99 Normally \fB@TPUT@\fR uses \fBtparm\fR (3X) to perform the substitution.
100 If no parameters are given for the capability,
101 \fB@TPUT@\fR writes the string without performing the substitution.
102 .TP
103 \fB\-S\fR
104 allows more than one capability per invocation of \fB@TPUT@\fR.  The
105 capabilities must be passed to \fB@TPUT@\fR from the standard input
106 instead of from the command line (see example).
107 Only one \fIcapname\fR is allowed per line.
108 The \fB\-S\fR option changes the
109 meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
110 EXIT CODES section).
111 .IP
112 Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
113 to decide whether to use \fBtparm\fR (3X),
114 and how to interpret the parameters.
115 .TP
116 \fB\-V\fR
117 reports the version of ncurses which was used in this program, and exits.
118 .TP
119 \fBinit\fR
120 If the \fBterminfo\fR database is present and an entry for the user's
121 terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
122 occur:
123 .RS
124 .TP
125 (1)
126 if present, the terminal's initialization strings will be
127 output as detailed in the \fBterminfo\fR(5) section on
128 .IR "Tabs and Initialization" ,
129 .TP
130 (2)
131 any delays (e.g., newline) specified in the entry will
132 be set in the tty driver,
133 .TP
134 (3)
135 tabs expansion will be turned on or off according to
136 the specification in the entry, and
137 .TP
138 (4)
139 if tabs are not expanded,
140 standard tabs will be set (every 8 spaces).
141 .RE
142 .IP
143 If an entry does not
144 contain the information needed for any of the four above activities,
145 that activity will silently be skipped.
146 .TP
147 \fBreset\fR
148 Instead of putting out initialization strings, the terminal's
149 reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
150 If the reset strings are not present, but initialization
151 strings are, the initialization strings will be output.
152 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
153 .TP
154 \fBlongname\fR
155 If the \fBterminfo\fR database is present and an entry for the
156 user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
157 of the terminal will be put out.  The long name is the last
158 name in the first line of the terminal's description in the
159 \fBterminfo\fR database [see \fBterm\fR(5)].
160 .PP
161 If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
162 same effect as \fB@TPUT@ reset\fR.
163 See \fB@TSET@\fR for comparison, which has similar behavior.
164 .SH EXAMPLES
165 .TP 5
166 \fB@TPUT@ init\fR
167 Initialize the terminal according to the type of
168 terminal in the environmental variable \fBTERM\fR.  This
169 command should be included in everyone's .profile after
170 the environmental variable \fBTERM\fR has been exported, as
171 illustrated on the \fBprofile\fR(5) manual page.
172 .TP 5
173 \fB@TPUT@ \-T5620 reset\fR
174 Reset an AT&T 5620 terminal, overriding the type of
175 terminal in the environmental variable \fBTERM\fR.
176 .TP 5
177 \fB@TPUT@ cup 0 0\fR
178 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
179 (the upper left corner of the screen, usually known as the "home"
180 cursor position).
181 .TP 5
182 \fB@TPUT@ clear\fR
183 Echo the clear-screen sequence for the current terminal.
184 .TP 5
185 \fB@TPUT@ cols\fR
186 Print the number of columns for the current terminal.
187 .TP 5
188 \fB@TPUT@ \-T450 cols\fR
189 Print the number of columns for the 450 terminal.
190 .TP 5
191 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
192 Set the shell variables \fBbold\fR, to begin stand-out mode
193 sequence, and \fBoffbold\fR, to end standout mode sequence,
194 for the current terminal.  This might be followed by a
195 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
196 .TP 5
197 \fB@TPUT@ hc\fR
198 Set exit code to indicate if the current terminal is a hard copy terminal.
199 .TP 5
200 \fB@TPUT@ cup 23 4\fR
201 Send the sequence to move the cursor to row 23, column 4.
202 .TP 5
203 \fB@TPUT@ cup\fR
204 Send the terminfo string for cursor-movement, with no parameters substituted.
205 .TP 5
206 \fB@TPUT@ longname\fR
207 Print the long name from the \fBterminfo\fR database for the
208 type of terminal specified in the environmental
209 variable \fBTERM\fR.
210 .PP
211 .RS 5
212 \fB@TPUT@ \-S <<!\fR
213 .br
214 \fB> clear\fR
215 .br
216 \fB> cup 10 10\fR
217 .br
218 \fB> bold\fR
219 .br
220 \fB> !\fR
221 .RE
222 .TP 5
223 \&
224 This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
225 It clears the screen,
226 moves the cursor to position 10, 10
227 and turns on bold (extra bright) mode.
228 The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
229 .SH FILES
230 .TP
231 \fB\*d\fR
232 compiled terminal description database
233 .TP
234 \fB@DATADIR@/tabset/*\fR
235 tab settings for some terminals, in a format
236 appropriate to be output to the terminal (escape
237 sequences that set margins and tabs); for more
238 information, see the "Tabs and Initialization"
239 section of \fBterminfo\fR(5)
240 .SH EXIT CODES
241 If the \fB\-S\fR option is used,
242 \fB@TPUT@\fR checks for errors from each line,
243 and if any errors are found, will set the exit code to 4 plus the
244 number of lines with errors.
245 If no errors are found, the exit code is \fB0\fR.
246 No indication of which line failed can be given so
247 exit code \fB1\fR will never appear.  Exit codes \fB2\fR, \fB3\fR, and
248 \fB4\fR retain their usual interpretation.
249 If the \fB\-S\fR option is not used,
250 the exit code depends on the type of \fIcapname\fR:
251 .RS 5
252 .TP
253 .I boolean
254 a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
255 .TP
256 .I string
257 a value of \fB0\fR is set if the
258 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
259 \fIcapname\fR is returned on standard output);
260 a value of \fB1\fR is set if \fIcapname\fR
261 is not defined for this terminal \fItype\fR
262 (nothing is written to standard output).
263 .TP
264 .I integer
265 a value of \fB0\fR is always set,
266 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
267 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
268 the user must test the value written to standard output.
269 A value of \fB\-1\fR
270 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
271 .TP
272 .I other
273 \fBreset\fR or \fBinit\fR may fail to find their respective files.
274 In that case, the exit code is set to 4 + \fBerrno\fR.
275 .RE
276 .PP
277 Any other exit code indicates an error; see the DIAGNOSTICS section.
278 .SH DIAGNOSTICS
279 \fB@TPUT@\fR prints the following error messages and sets the corresponding exit
280 codes.
281 .PP
282 .ne 15
283 .TS
284 l l.
285 exit code       error message
286 =
287 \fB0\fR T{
288 (\fIcapname\fR is a numeric variable that is not specified in the
289 \fBterminfo\fR(5) database for this terminal type, e.g.
290 \fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
291 T}
292 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
293 \fB2\fR usage error
294 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
295 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
296 \fB>4\fR        error occurred in \-S
297 =
298 .TE
299 .SH PORTABILITY
300 .PP
301 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
302 features used in the \fBcup\fR example, are not supported in BSD curses or in
303 AT&T/USL curses before SVr4.
304 .PP
305 X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
306 In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
307 Other implementations of \fB@TPUT@\fP on
308 SVr4-based systems such as Solaris, IRIX64 and HPUX
309 as well as others such as AIX and Tru64
310 provide support for \fIcapname\fR operands.
311 .PP
312 A few platforms such as FreeBSD and NetBSD recognize termcap names rather
313 than terminfo capability names in their respective \fB@TPUT@\fP commands.
314 .PP
315 Most implementations which provide support for \fIcapname\fR operands
316 use the \fItparm\fP function to expand parameters in it.
317 That function expects a mixture of numeric and string parameters,
318 requiring \fB@TPUT@\fP to know which type to use.
319 This implementation uses a table to determine that for
320 the standard \fIcapname\fR operands, and an internal library
321 function to analyze nonstandard \fIcapname\fR operands.
322 Other implementations may simply guess that an operand containing only digits
323 is intended to be a number.
324 .SH SEE ALSO
325 \fB@CLEAR@\fR(1),
326 \fBstty\fR(1),
327 \fBtabs\fR(\*n),
328 \fBterminfo\fR(5),
329 \fBcurs_termcap\fR(3X).
330 .PP
331 This describes \fBncurses\fR
332 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).