Gitiles
Code Review Sign In
gerrit.omnirom.org / android_external_libncurses / refs/heads/android-16 / . / doc / html / man / tput.1.html
blob: ed8fe3805afb3451d40075c48bc3d978f00212ad [file] [log] [blame]
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]1<!--
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]2 * t
3 ****************************************************************************
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]4 * Copyright 2018-2023,2024 Thomas E. Dickey *
5 * Copyright 1998-2016,2017 Free Software Foundation, Inc. *
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]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 ****************************************************************************
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]31 * @Id: tput.1,v 1.113 2024/04/20 19:58:50 tom Exp @
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]32-->
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]34<HTML>
35<HEAD>
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
38<TITLE>tput 1 2024-04-20 ncurses 6.5 User commands</TITLE>
39<link rel="author" href="mailto:bug-ncurses@gnu.org">
40
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]41</HEAD>
42<BODY>
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]43<H1 class="no-header">tput 1 2024-04-20 ncurses 6.5 User commands</H1>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]44<PRE>
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]45<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> User commands <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]46
47
48
49
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
51 <STRONG>tput</STRONG> - initialize a terminal, exercise its capabilities, or query <EM>term-</EM>
52 <EM>info</EM> database
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]53
54
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]55</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56 <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ...
57
58 <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
59
60 <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG>
61
62 <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG>
63
64 <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>longname</STRONG>
65
66 <STRONG>tput</STRONG> <STRONG>-S</STRONG>
67
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]68 <STRONG>tput</STRONG> <STRONG>-V</STRONG>
69
70
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]71</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
72 <STRONG>tput</STRONG> uses the <EM>terminfo</EM> library and database to make terminal-specific
73 capabilities and information available to the shell, to initialize or
74 reset the terminal, or to report a description of the current (or
75 specified) terminal type. Terminal capabilities are accessed by <EM>cap-</EM>
76 <EM>code</EM>.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]77
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]78 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> discusses terminal capabilities at length and presents a
79 complete list of <EM>cap-codes</EM>.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]80
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]81 When retrieving capability values, the result depends upon the
82 capability's type.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]83
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]84 Boolean <STRONG>tput</STRONG> sets its exit status to <STRONG>0</STRONG> if the terminal possesses <EM>cap-</EM>
85 <EM>code</EM>, and <STRONG>1</STRONG> if it does not.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]86
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]87 numeric <STRONG>tput</STRONG> writes <EM>cap-code</EM>'s decimal value to the standard output
88 stream if defined (<STRONG>-1</STRONG> if it is not) followed by a newline.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]89
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]90 string <STRONG>tput</STRONG> writes <EM>cap-code</EM>'s value to the standard output stream if
91 defined, without a trailing newline.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]92
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]93 Before using a value returned on the standard output, the application
94 should test <STRONG>tput</STRONG>'s exit status to be sure it is 0; see section "EXIT
95 STATUS" below.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]96
97
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]98</PRE><H3><a name="h3-Operands">Operands</a></H3><PRE>
99 Generally, an operand is a <EM>cap-code</EM>, a capability code from the
100 terminal database, or a parameter thereto. Three others are specially
101 recognized by <STRONG>tput</STRONG>: <STRONG>init</STRONG>, <STRONG>reset</STRONG>, and <STRONG>longname</STRONG>. Although these resemble
102 capability codes, they in fact receive special handling; we term them
103 "pseudo-capabilities".
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]104
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]105 <EM>cap-code</EM> indicates a capability from the terminal database.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]106
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]107 If <EM>cap-code</EM> is of string type and takes parameters, <STRONG>tput</STRONG>
108 interprets arguments following <EM>cap-code</EM> as the parameters,
109 up to the (fixed) quantity the capability requires.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]110
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]111 Most parameters are numeric. Only a few terminal
112 capabilities require string parameters; <STRONG>tput</STRONG> uses a table to
113 decide which to pass as strings. Normally <STRONG>tput</STRONG> uses
114 <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the substitution. If no parameters are
115 given for the capability, <STRONG>tput</STRONG> writes the string without
116 performing the substitution.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]117
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]118 <STRONG>init</STRONG> initializes the terminal. If the terminal database is
119 present and an entry for the user's terminal type exists,
120 the following occur.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]121
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]122 (1) <STRONG>tput</STRONG> retrieves the terminal's mode settings. It
123 successively tests the file descriptors corresponding
124 to
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]125
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]126 <STRONG>o</STRONG> the standard error stream,
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]127
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]128 <STRONG>o</STRONG> the standard output stream,
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]129
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]130 <STRONG>o</STRONG> the standard input stream, and
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]131
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]132 <STRONG>o</STRONG> <EM>/dev/tty</EM>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]133
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]134 to obtain terminal settings. Having retrieved them,
135 <STRONG>tput</STRONG> remembers which descriptor to use for further
136 updates.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]137
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]138 (2) If the terminal dimensions cannot be obtained from the
139 operating system, but the environment or terminal type
140 database entry describes them, <STRONG>tput</STRONG> updates the
141 operating system's notion of them.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]142
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]143 (3) <STRONG>tput</STRONG> updates the terminal modes.
144
145 <STRONG>o</STRONG> Any delays specified in the entry (for example,
146 when a newline is sent) are set in the terminal
147 driver.
148
149 <STRONG>o</STRONG> Tab expansion is turned on or off per the
150 specification in the entry, and
151
152 <STRONG>o</STRONG> if tabs are not expanded, standard tabs (every 8
153 spaces) are set.
154
155 (4) If initialization capabilities, detailed in subsection
156 "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, are present,
157 <STRONG>tput</STRONG> writes them to the standard output stream.
158
159 (5) <STRONG>tput</STRONG> flushes the standard output stream.
160
161 If an entry lacks the information needed for an activity
162 above, that activity is silently skipped.
163
164 <STRONG>reset</STRONG> re-initializes the terminal. A reset differs from
165 initialization in two ways.
166
167 (1) <STRONG>tput</STRONG> sets the the terminal modes to a "sane" state,
168
169 <STRONG>o</STRONG> enabling cooked and echo modes,
170
171 <STRONG>o</STRONG> disabling cbreak and raw modes,
172
173 <STRONG>o</STRONG> enabling newline translation, and
174
175 <STRONG>o</STRONG> setting any unset special characters to their
176 default values.
177
178 (2) If any reset capabilities are defined for the terminal
179 type, <STRONG>tput</STRONG> writes them to the output stream.
180 Otherwise, <STRONG>tput</STRONG> uses any defined initialization
181 capabilities. Reset capabilities are detailed in
182 subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
183
184 <STRONG>longname</STRONG> A <EM>terminfo</EM> entry begins with one or more names by which an
185 application can refer to the entry, before the list of
186 terminal capabilities. The names are separated by "|"
187 characters. X/Open Curses terms the last name the "long
188 name", and indicates that it may include blanks.
189
190 <STRONG>tic</STRONG> warns if the last name does not include blanks, to
191 accommodate old <EM>terminfo</EM> entries that treated the long name
192 as an optional feature. The long name is often referred to
193 as the description field.
194
195 If the terminal database is present and an entry for the
196 user's terminal type exists, <STRONG>tput</STRONG> reports its description to
197 the standard output stream, without a trailing newline. See
198 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
199
200 <EM>Note:</EM> Redirecting the output of "<STRONG>tput</STRONG> <STRONG>init</STRONG>" or "<STRONG>tput</STRONG> <STRONG>reset</STRONG>" to a file
201 will capture only part of their actions. Changes to the terminal modes
202 are not affected by file descriptor redirection, since the terminal
203 modes are altered via <STRONG>ioctl(2)</STRONG>.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]204
205
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]206</PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
207 If <STRONG>tput</STRONG> is invoked via link with any of the names <STRONG>clear</STRONG>, <STRONG>init</STRONG>, or
208 <STRONG>reset</STRONG>, it operates as if run with the corresponding (pseudo-)capability
209 operand. For example, executing a link named <STRONG>reset</STRONG> that points to <STRONG>tput</STRONG>
210 has the same effect as "<STRONG>tput</STRONG> <STRONG>reset</STRONG>".
211
212 This feature was introduced by <EM>ncurses</EM> 5.2 in 2000. It is rarely used:
213
214 <STRONG>clear</STRONG> is a separate program, which is both smaller and more frequently
215 executed.
216
217 <STRONG>init</STRONG> has the same name as another program in widespread use.
218
219 <STRONG>reset</STRONG> is provided by the <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility (also via a link named
220 <STRONG>reset</STRONG>).
221
222
223</PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
224 Besides the pseudo-capabilities (such as <STRONG>init</STRONG>), <STRONG>tput</STRONG> treats the <STRONG>lines</STRONG>
225 and <STRONG>cols</STRONG> <EM>cap-codes</EM> specially: it may call <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the
226 terminal size.
227
228 <STRONG>o</STRONG> First, <STRONG>tput</STRONG> attempts to obtain these capabilities from the terminal
229 database. This generally fails for terminal emulators, which lack
230 a fixed window size and thus omit the capabilities.
231
232 <STRONG>o</STRONG> It then asks the operating system for the terminal's size, which
233 generally works, unless the connection is via a serial line that
234 does not support "NAWS": negotiations about window size.
235
236 <STRONG>o</STRONG> Finally, it inspects the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM>,
237 which may override the terminal size.
238
239 If the <STRONG>-T</STRONG> option is given, <STRONG>tput</STRONG> ignores the environment variables by
240 calling <STRONG>use_tioctl(TRUE)</STRONG>, relying upon the operating system (or,
241 ultimately, the terminal database).
242
243
244</PRE><H2><a name="h2-OPTIONS">OPTIONS</a></H2><PRE>
245 <STRONG>-S</STRONG> retrieves more than one capability per invocation of <STRONG>tput</STRONG>.
246 The capabilities must be passed to <STRONG>tput</STRONG> from the standard
247 input stream instead of from the command line (see section
248 "EXAMPLES" below). Only one <EM>cap-code</EM> is allowed per line.
249 The <STRONG>-S</STRONG> option changes the meanings of the <STRONG>0</STRONG> and <STRONG>1</STRONG> exit
250 statuses (see section "EXIT STATUS" below).
251
252 Some capabilities use string parameters rather than numeric
253 ones. <STRONG>tput</STRONG> employs a built-in table and the presence of
254 parameters in its input to decide how to interpret them, and
255 whether to use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>.
256
257 <STRONG>-T</STRONG> <EM>type</EM> indicates the terminal's <EM>type</EM>. Normally this option is
258 unnecessary, because a default is taken from the <EM>TERM</EM>
259 environment variable. If specified, the environment variables
260 <EM>LINES</EM> and <EM>COLUMNS</EM> are also ignored.
261
262 <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> associated with <STRONG>tput</STRONG>, and exits
263 with a successful status.
264
265 <STRONG>-x</STRONG> prevents "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" from attempting to clear the scrollback
266 buffer.
267
268
269</PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
270 Normally, one should interpret <STRONG>tput</STRONG>'s exit statuses as follows.
271
272 <STRONG>Status</STRONG> <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Not</STRONG> <STRONG>Specified</STRONG>
273 ------------------------------------------------------------------------
274 <STRONG>0</STRONG> Boolean or string capability present
275 <STRONG>1</STRONG> Boolean or numeric capability absent
276 <STRONG>2</STRONG> usage error or no terminal type specified
277 <STRONG>3</STRONG> unrecognized terminal type
278 <STRONG>4</STRONG> unrecognized capability code
279 <STRONG>&gt;4</STRONG> system error (4 + <STRONG>errno</STRONG>)
280
281 When the <STRONG>-S</STRONG> option is used, some statuses change meanings.
282
283 <STRONG>Status</STRONG> <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Specified</STRONG>
284 ------------------------------------------------------------------------
285 <STRONG>0</STRONG> all operands interpreted
286 <STRONG>1</STRONG> unused
287 <STRONG>4</STRONG> some operands not interpreted
288
289
290</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
291 <STRONG>tput</STRONG> reads one environment variable.
292
293 <EM>TERM</EM> denotes the terminal type. Each terminal type is distinct,
294 though many are similar. The <STRONG>-T</STRONG> option overrides its value.
295
296
297</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
298 <EM>/usr/share/tabset</EM>
299 tab stop initialization database
300
301 <EM>/usr/share/terminfo</EM>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]302 compiled terminal description database
303
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]304
305</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
306 Over time <EM>ncurses</EM> <STRONG>tput</STRONG> has differed from that of System V in two
307 important respects, one now mostly historical.
308
309 <STRONG>o</STRONG> "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be a
310 terminal device. However, the operands that manipulate terminal
311 modes might not use the standard output.
312
313 System V <STRONG>tput</STRONG>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands use logic from 4.1cBSD
314 <STRONG>tset</STRONG>, manipulating terminal modes. It checks the same file
315 descriptors (and <EM>/dev/tty</EM>) for association with a terminal device
316 as <EM>ncurses</EM> now does, and if none are, finally assumes a 1200 baud
317 terminal. When updating terminal modes, it ignores errors.
318
319 Until <EM>ncurses</EM> 6.1 (see section "HISTORY" below), <STRONG>tput</STRONG> did not
320 modify terminal modes. It now employs a scheme similar to
321 System V, using functions shared with <STRONG>tset</STRONG> (and ultimately based on
322 4.4BSD <STRONG>tset</STRONG>). If it is not able to open a terminal (for instance,
323 when run by <STRONG>cron(1)</STRONG>), <STRONG>tput</STRONG> exits with an error status.
324
325 <STRONG>o</STRONG> System V <STRONG>tput</STRONG> assumes that the type of a <EM>cap-code</EM> operand is
326 numeric if all the characters of its value are decimal numbers; if
327 they are not, it treats <EM>cap-code</EM> as a string capability.
328
329 Most implementations that provide support for <EM>cap-code</EM> operands use
330 the <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> function to expand its parameters. That function
331 expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
332 to know which type to use.
333
334 <EM>ncurses</EM> <STRONG>tput</STRONG> uses a table to determine the parameter types for the
335 standard <EM>cap-code</EM> operands, and an internal function to analyze
336 nonstandard <EM>cap-code</EM> operands.
337
338 While more reliable than System V's utility, a portability problem
339 is introduced by this analysis. An OpenBSD developer adapted the
340 internal library function from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>-
341 based <STRONG>tput</STRONG> to <EM>terminfo</EM>, and modified it to interpret multiple <EM>cap-</EM>
342 <EM>codes</EM> (and parameters) on the command line. Portable applications
343 should not rely upon this feature; <EM>ncurses</EM> offers it to support
344 applications written specifically for OpenBSD.
345
346 This implementation, unlike others, accepts both <EM>termcap</EM> and <EM>terminfo</EM>
347 <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in. In that case, however,
348 the predefined <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM>
349 assumes the <EM>terminfo</EM> code.
350
351 <STRONG>o</STRONG> The <EM>cap-code</EM> <STRONG>dl</STRONG> means <STRONG>delete_line</STRONG> to <EM>termcap</EM> but <STRONG>parm_delete_line</STRONG>
352 to <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>DL</STRONG> for <STRONG>parm_delete_line</STRONG>. <EM>term-</EM>
353 <EM>info</EM> uses the code <STRONG>dl1</STRONG> for <STRONG>delete_line</STRONG>.
354
355 <STRONG>o</STRONG> The <EM>cap-code</EM> <STRONG>ed</STRONG> means <STRONG>exit_delete_mode</STRONG> to <EM>termcap</EM> but <STRONG>clr_eos</STRONG> to
356 <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>cd</STRONG> for <STRONG>clr_eos</STRONG>. <EM>terminfo</EM> uses the
357 code <STRONG>rmdc</STRONG> for <STRONG>exit_delete_mode</STRONG>.
358
359 The <STRONG>longname</STRONG> operand, <STRONG>-S</STRONG> option, and the parameter-substitution
360 features used in the <STRONG>cup</STRONG> example below, were not supported in AT&amp;T/USL
361 <EM>curses</EM> before SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for
362 <STRONG>longname</STRONG>, and in 1994, NetBSD added support for the parameter-
363 substitution features.
364
365 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
366 (POSIX.1-2008) documents only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands. A
367 few observations of interest arise from that selection.
368
369 <STRONG>o</STRONG> <EM>ncurses</EM> supports <STRONG>clear</STRONG> as it does any other standard <EM>cap-code</EM>. The
370 others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal
371 capabilities.
372
373 <STRONG>o</STRONG> The <STRONG>tput</STRONG> on SVr4-based systems such as Solaris, IRIX64, and HP-UX,
374 as well as others such as AIX and Tru64, also support standard <EM>cap-</EM>
375 <EM>code</EM> operands.
376
377 <STRONG>o</STRONG> A few platforms such as FreeBSD recognize <EM>termcap</EM> codes rather than
378 <EM>terminfo</EM> capability codes in their respective <STRONG>tput</STRONG> commands. Since
379 2010, NetBSD's <STRONG>tput</STRONG> uses <EM>terminfo</EM> codes. Before that, it (like
380 FreeBSD) recognized <EM>termcap</EM> codes.
381
382 Beginning in 2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both
383 <EM>terminfo</EM> (tested first) and <EM>termcap</EM> (as a fallback).
384
385 Because (apparently) all <EM>certified</EM> Unix systems support the full set of
386 capability codes, the reason for documenting only a few may not be
387 apparent.
388
389 <STRONG>o</STRONG> X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
390 the other features used in this implementation.
391
392 <STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
393 X/Open Curses (the full implementation). POSIX documents a subset
394 to avoid the complication of including X/Open Curses and the
395 terminal capability database.
396
397 <STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without
398 using <EM>curses</EM>, no system with a <EM>curses</EM> implementation provides a
399 <STRONG>tput</STRONG> utility that does not also support standard <EM>cap-codes</EM>.
400
401 X/Open Curses Issue 7 (2009) is the first version to document
402 utilities. However that part of X/Open Curses does not follow existing
403 practice (that is, System V <EM>curses</EM> behavior).
404
405 <STRONG>o</STRONG> It assigns exit status 4 to "invalid operand", which may have the
406 same meaning as "unknown capability". For instance, the source
407 code for Solaris <EM>xcurses</EM> uses the term "invalid" in this case.
408
409 <STRONG>o</STRONG> It assigns exit status 255 to a numeric variable that is not
410 specified in the <EM>terminfo</EM> database. That likely is a documentation
411 error, mistaking the "-1" written to the standard output to
412 indicate an absent or cancelled numeric capability for an
413 (unsigned) exit status.
414
415 The various System V implementations (AIX, HP-UX, Solaris) use the same
416 exit statuses as <EM>ncurses</EM>.
417
418 NetBSD <EM>curses</EM> documents exit statuses that correspond to neither
419 <EM>ncurses</EM> nor X/Open Curses.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]420
421
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]422</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
423 Bill Joy wrote a <STRONG>tput</STRONG> command during development of 4BSD in October
424 1980. This initial version only cleared the screen, and did not ship
425 with official distributions.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]426
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]427 System V developed a different <STRONG>tput</STRONG> command.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]428
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]429 <STRONG>o</STRONG> SVr2 (1984) provided a rudimentary <STRONG>tput</STRONG> that checked the parameter
430 against each predefined capability and returned the corresponding
431 value. This version of <STRONG>tput</STRONG> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for
432 parameterized capabilities.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]433
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]434 <STRONG>o</STRONG> SVr3 (1987) replaced that with a more extensive program whose
435 support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than half the program)
436 incorporated the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]437
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]438 <STRONG>o</STRONG> SVr4 (1989) added color initialization by using the <STRONG>orig_colors</STRONG>
439 (<STRONG>oc</STRONG>) and <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) capabilities in its <STRONG>init</STRONG> logic.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]440
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]441 Keith Bostic refactored BSD <STRONG>tput</STRONG> for shipment in 4.3BSD-Tahoe (1988),
442 then replaced it the next year with a new implementation based on
443 System V <STRONG>tput</STRONG>. Bostic's version similarly accepted some parameters
444 named for <EM>terminfo</EM> (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG>, and
445 <STRONG>reset</STRONG>. However, because he had only <EM>termcap</EM> available, it accepted
446 <EM>termcap</EM> codes for other capabilities. Also, Bostic's BSD <STRONG>tput</STRONG> did not
447 modify the terminal modes as the earlier BSD <STRONG>tset</STRONG> had done.
448
449 At the same time, Bostic added a shell script named "clear" that used
450 <STRONG>tput</STRONG> to clear the screen. Both of these appeared in 4.4BSD, becoming
451 the "modern" BSD implementation of <STRONG>tput</STRONG>.
452
453 The origin of <EM>ncurses</EM> <STRONG>tput</STRONG> lies outside both System V and BSD, in Ross
454 Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in December
455 1992. Ridge's program made more sophisticated use of the terminal
456 capabilities than the BSD program. Eric Raymond used that <STRONG>tput</STRONG> program
457 (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995. Incorporating
458 the portions dealing with terminal capabilities almost without change,
459 Raymond made improvements to the way command-line parameters were
460 handled.
461
462 Before <EM>ncurses</EM> 6.1 (2018), its <STRONG>tset</STRONG> and <STRONG>tput</STRONG> utilities differed.
463
464 <STRONG>o</STRONG> <STRONG>tset</STRONG> was more effective, resetting the terminal modes and special
465 characters.
466
467 <STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for
468 resetting the terminal was more limited; it had only equivalents of
469 <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>), and
470 not the tab stop and margin update features of <STRONG>tput</STRONG>.
471
472 The <STRONG>reset</STRONG> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability
473 to reset terminal modes and special characters.
474
475 As of <EM>ncurses</EM> 6.1, the "reset" features of the two programs are
476 (mostly) the same. Two minor differences remain.
477
478 <STRONG>o</STRONG> The <STRONG>tset</STRONG> program waits one second when resetting, in case the
479 terminal happens to be a hardware device.
480
481 <STRONG>o</STRONG> The two programs write the terminal initialization strings to
482 different streams; that is, standard error for <STRONG>tset</STRONG> and standard
483 output for <STRONG>tput</STRONG>.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]484
485
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]486</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
487 <STRONG>tput</STRONG> <STRONG>init</STRONG>
488 Initialize the terminal according to the type of terminal in the
489 <EM>TERM</EM> environment variable. If the system does not reliably
490 initialize the terminal upon login, this command can be included
491 in <EM>$HOME/.profile</EM> after exporting the <EM>TERM</EM> environment variable.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]492
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]493 <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
494 Reset an AT&amp;T 5620 terminal, overriding the terminal type in the
495 <EM>TERM</EM> environment variable.
496
497 <STRONG>tput</STRONG> <STRONG>cnorm</STRONG>
498 Set cursor to normal visibility.
499
500 <STRONG>tput</STRONG> <STRONG>home</STRONG>
501 Move the cursor to row 0, column 0: the upper left corner of the
502 screen, usually known as the "home" cursor position.
503
504 <STRONG>tput</STRONG> <STRONG>clear</STRONG>
505 Clear the screen: write the <STRONG>clear_screen</STRONG> capability's value to
506 the standard output stream.
507
508 <STRONG>tput</STRONG> <STRONG>cols</STRONG>
509 Report the number of columns used by the current terminal type.
510
511 <STRONG>tput</STRONG> <STRONG>-Tadm3a</STRONG> <STRONG>cols</STRONG>
512 Report the number of columns used by an ADM-3A terminal.
513
514 <STRONG>strong=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>normal=`tput</STRONG> <STRONG>rmso`</STRONG>
515 Set shell variables to capability values: <STRONG>strong</STRONG> and <STRONG>normal</STRONG>, to
516 begin and end, respectively, stand-out mode for the terminal.
517 One might use these to present a prompt.
518
519 printf "${strong}Username:${normal} "
520
521 <STRONG>tput</STRONG> <STRONG>hc</STRONG>
522 Indicate via exit status whether the terminal is a hard copy
523 device.
524
525 <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
526 Move the cursor to row 23, column 4.
527
528 <STRONG>tput</STRONG> <STRONG>cup</STRONG>
529 Report the value of the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability (used
530 for cursor movement), with no parameters substituted.
531
532 <STRONG>tput</STRONG> <STRONG>longname</STRONG>
533 Report the <EM>terminfo</EM> database's description of the terminal type
534 specified in the <EM>TERM</EM> environment variable.
535
536 <STRONG>tput</STRONG> <STRONG>-S</STRONG>
537 Process multiple capabilities. The <STRONG>-S</STRONG> option can be profitably
538 used with a shell "here document".
539
540 $ <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG>&lt;&lt;!</STRONG>
541 &gt; <STRONG>clear</STRONG>
542 &gt; <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
543 &gt; <STRONG>bold</STRONG>
544 &gt; <STRONG>!</STRONG>
545
546 The foregoing clears the screen, moves the cursor to position
547 (10, 10) and turns on bold (extra bright) mode.
548
549 <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
550 Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]551
552
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]553</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
554 <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="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]555
556
557
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]558ncurses 6.5 2024-04-20 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]559</PRE>
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]560<div class="nav">
561<ul>
562<li><a href="#h2-NAME">NAME</a></li>
563<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]564<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
565<ul>
566<li><a href="#h3-Operands">Operands</a></li>
567<li><a href="#h3-Aliases">Aliases</a></li>
568<li><a href="#h3-Terminal-Size">Terminal Size</a></li>
569</ul>
570</li>
571<li><a href="#h2-OPTIONS">OPTIONS</a></li>
572<li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
573<li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a></li>
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]574<li><a href="#h2-FILES">FILES</a></li>
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]575<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
micky3879b9f5e72025-07-08 18:04:53 -0400[diff] [blame]576<li><a href="#h2-HISTORY">HISTORY</a></li>
577<li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
Steve Kondikae271bc2015-11-15 02:50:53 +0100[diff] [blame]578<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
579</ul>
580</div>
Amit Daniel Kachhape6a01f52011-07-20 11:45:59 +0530[diff] [blame]581</BODY>
582</HTML>