3 ****************************************************************************
4 * Copyright 2018-2023,2024 Thomas E. Dickey *
5 * Copyright 1998-2016,2017 Free Software Foundation, Inc. *
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: *
15 * The above copyright notice and this permission notice shall be included *
16 * in all copies or substantial portions of the Software. *
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. *
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 *
30 ****************************************************************************
31 * @Id: tput.1,v 1.118 2024/06/22 21:28:35 tom Exp @
33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
38 <TITLE>tput 1 2024-06-22 ncurses 6.5 User commands</TITLE>
39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
43 <H1 class="no-header">tput 1 2024-06-22 ncurses 6.5 User commands</H1>
45 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> User commands <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
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
55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
56 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ...
58 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
60 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG>
62 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG>
64 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>longname</STRONG>
66 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] <STRONG>-S</STRONG>
68 <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] <STRONG>-V</STRONG>
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>
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>.
81 When retrieving capability values, the result depends upon the
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.
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.
90 string <STRONG>tput</STRONG> writes <EM>cap-code</EM>'s value to the standard output stream if
91 defined, without a trailing newline.
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
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".
105 <EM>cap-code</EM> indicates a capability from the terminal database.
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.
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.
118 <STRONG>init</STRONG> initializes the terminal. If the terminal database is
119 present and an entry for the user's terminal type exists,
122 (1) <STRONG>tput</STRONG> retrieves the terminal's mode settings. It
123 successively tests the file descriptors corresponding
126 <STRONG>o</STRONG> the standard error stream,
128 <STRONG>o</STRONG> the standard output stream,
130 <STRONG>o</STRONG> the standard input stream, and
132 <STRONG>o</STRONG> <EM>/dev/tty</EM>
134 to obtain terminal settings. Having retrieved them,
135 <STRONG>tput</STRONG> remembers which descriptor to use for further
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.
143 (3) <STRONG>tput</STRONG> updates the terminal modes.
145 <STRONG>o</STRONG> Any delays specified in the entry (for example,
146 when a newline is sent) are set in the terminal
149 <STRONG>o</STRONG> Tab expansion is turned on or off per the
150 specification in the entry, and
152 <STRONG>o</STRONG> if tabs are not expanded, standard tabs (every 8
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.
159 (5) <STRONG>tput</STRONG> flushes the standard output stream.
161 If an entry lacks the information needed for an activity
162 above, that activity is silently skipped.
164 <STRONG>reset</STRONG> re-initializes the terminal. A reset differs from
165 initialization in two ways.
167 (1) <STRONG>tput</STRONG> sets the the terminal modes to a "sane" state,
169 <STRONG>o</STRONG> enabling cooked and echo modes,
171 <STRONG>o</STRONG> disabling cbreak and raw modes,
173 <STRONG>o</STRONG> enabling newline translation, and
175 <STRONG>o</STRONG> setting any unset special characters to their
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>.
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.
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.
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>.
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>.
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>".
212 This feature was introduced by <EM>ncurses</EM> 5.2 in 2000. It is rarely used:
214 <STRONG>clear</STRONG> is a separate program, which is both smaller and more frequently
217 <STRONG>init</STRONG> has the same name as another program in widespread use.
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>).
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
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.
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.
236 <STRONG>o</STRONG> Finally, it inspects the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM>,
237 which may override the terminal size.
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).
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).
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>.
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.
262 <STRONG>-v</STRONG> causes <STRONG>tput</STRONG> to operate verbosely, reporting warnings.
264 <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> associated with <STRONG>tput</STRONG>, and exits
265 with a successful status.
267 <STRONG>-x</STRONG> prevents "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" from attempting to clear the scrollback
271 </PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
272 Normally, one should interpret <STRONG>tput</STRONG>'s exit statuses as follows.
274 <STRONG>Status</STRONG> <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Not</STRONG> <STRONG>Specified</STRONG>
275 ------------------------------------------------------------------------
276 <STRONG>0</STRONG> Boolean or string capability present
277 <STRONG>1</STRONG> Boolean or numeric capability absent
278 <STRONG>2</STRONG> usage error or no terminal type specified
279 <STRONG>3</STRONG> unrecognized terminal type
280 <STRONG>4</STRONG> unrecognized capability code
281 <STRONG>>4</STRONG> system error (4 + <STRONG>errno</STRONG>)
283 When the <STRONG>-S</STRONG> option is used, some statuses change meanings.
285 <STRONG>Status</STRONG> <STRONG>Meaning</STRONG> <STRONG>When</STRONG> <STRONG>-S</STRONG> <STRONG>Specified</STRONG>
286 ------------------------------------------------------------------------
287 <STRONG>0</STRONG> all operands interpreted
288 <STRONG>1</STRONG> unused
289 <STRONG>4</STRONG> some operands not interpreted
292 </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
293 <STRONG>tput</STRONG> reads one environment variable.
295 <EM>TERM</EM> denotes the terminal type. Each terminal type is distinct,
296 though many are similar. The <STRONG>-T</STRONG> option overrides its value.
299 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
300 <EM>/usr/share/tabset</EM>
301 tab stop initialization database
303 <EM>/usr/share/terminfo</EM>
304 compiled terminal description database
307 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
308 Over time <EM>ncurses</EM> <STRONG>tput</STRONG> has differed from that of System V in two
309 important respects, one now mostly historical.
311 <STRONG>o</STRONG> "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be a
312 terminal device. However, the operands that manipulate terminal
313 modes might not use the standard output.
315 System V <STRONG>tput</STRONG>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands use logic from 4.1cBSD
316 <STRONG>tset</STRONG>, manipulating terminal modes. It checks the same file
317 descriptors (and <EM>/dev/tty</EM>) for association with a terminal device
318 as <EM>ncurses</EM> now does, and if none are, finally assumes a 1200 baud
319 terminal. When updating terminal modes, it ignores errors.
321 Until <EM>ncurses</EM> 6.1 (see section "HISTORY" below), <STRONG>tput</STRONG> did not
322 modify terminal modes. It now employs a scheme similar to
323 System V, using functions shared with <STRONG>tset</STRONG> (and ultimately based on
324 4.4BSD <STRONG>tset</STRONG>). If it is not able to open a terminal (for instance,
325 when run by <STRONG>cron(1)</STRONG>), <STRONG>tput</STRONG> exits with an error status.
327 <STRONG>o</STRONG> System V <STRONG>tput</STRONG> assumes that the type of a <EM>cap-code</EM> operand is
328 numeric if all the characters of its value are decimal numbers; if
329 they are not, it treats <EM>cap-code</EM> as a string capability.
331 Most implementations that provide support for <EM>cap-code</EM> operands use
332 the <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> function to expand its parameters. That function
333 expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
334 to know which type to use.
336 <EM>ncurses</EM> <STRONG>tput</STRONG> uses a table to determine the parameter types for the
337 standard <EM>cap-code</EM> operands, and an internal function to analyze
338 nonstandard <EM>cap-code</EM> operands.
340 While more reliable than System V's utility, a portability problem
341 is introduced by this analysis. An OpenBSD developer adapted the
342 internal library function from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>-
343 based <STRONG>tput</STRONG> to <EM>terminfo</EM>, and modified it to interpret multiple <EM>cap-</EM>
344 <EM>codes</EM> (and parameters) on the command line. Portable applications
345 should not rely upon this feature; <EM>ncurses</EM> offers it to support
346 applications written specifically for OpenBSD.
348 This implementation, unlike others, accepts both <EM>termcap</EM> and <EM>terminfo</EM>
349 <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in. In that case, however,
350 the predefined <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM>
351 assumes the <EM>terminfo</EM> code.
353 <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>
354 to <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>DL</STRONG> for <STRONG>parm_delete_line</STRONG>. <EM>term-</EM>
355 <EM>info</EM> uses the code <STRONG>dl1</STRONG> for <STRONG>delete_line</STRONG>.
357 <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
358 <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>cd</STRONG> for <STRONG>clr_eos</STRONG>. <EM>terminfo</EM> uses the
359 code <STRONG>rmdc</STRONG> for <STRONG>exit_delete_mode</STRONG>.
361 The <STRONG>longname</STRONG> operand, <STRONG>-S</STRONG> option, and the parameter-substitution
362 features used in the <STRONG>cup</STRONG> example below, were not supported in AT&T/USL
363 <EM>curses</EM> before SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for
364 <STRONG>longname</STRONG>, and in 1994, NetBSD added support for the parameter-
365 substitution features.
367 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
368 (POSIX.1-2008) documents only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands. A
369 few observations of interest arise from that selection.
371 <STRONG>o</STRONG> <EM>ncurses</EM> supports <STRONG>clear</STRONG> as it does any other standard <EM>cap-code</EM>. The
372 others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal
375 <STRONG>o</STRONG> The <STRONG>tput</STRONG> on SVr4-based systems such as Solaris, IRIX64, and HP-UX,
376 as well as others such as AIX and Tru64, also support standard <EM>cap-</EM>
377 <EM>code</EM> operands.
379 <STRONG>o</STRONG> A few platforms such as FreeBSD recognize <EM>termcap</EM> codes rather than
380 <EM>terminfo</EM> capability codes in their respective <STRONG>tput</STRONG> commands. Since
381 2010, NetBSD's <STRONG>tput</STRONG> uses <EM>terminfo</EM> codes. Before that, it (like
382 FreeBSD) recognized <EM>termcap</EM> codes.
384 Beginning in 2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both
385 <EM>terminfo</EM> (tested first) and <EM>termcap</EM> (as a fallback).
387 Because (apparently) all <EM>certified</EM> Unix systems support the full set of
388 capability codes, the reason for documenting only a few may not be
391 <STRONG>o</STRONG> X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
392 the other features used in this implementation.
394 <STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
395 X/Open Curses (the full implementation). POSIX documents a subset
396 to avoid the complication of including X/Open Curses and the
397 terminal capability database.
399 <STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without
400 using <EM>curses</EM>, no system with a <EM>curses</EM> implementation provides a
401 <STRONG>tput</STRONG> utility that does not also support standard <EM>cap-codes</EM>.
403 X/Open Curses Issue 7 (2009) is the first version to document
404 utilities. However that part of X/Open Curses does not follow existing
405 practice (that is, System V <EM>curses</EM> behavior).
407 <STRONG>o</STRONG> It assigns exit status 4 to "invalid operand", which may have the
408 same meaning as "unknown capability". For instance, the source
409 code for Solaris <EM>xcurses</EM> uses the term "invalid" in this case.
411 <STRONG>o</STRONG> It assigns exit status 255 to a numeric variable that is not
412 specified in the <EM>terminfo</EM> database. That likely is a documentation
413 error, mistaking the "-1" written to the standard output to
414 indicate an absent or cancelled numeric capability for an
415 (unsigned) exit status.
417 The various System V implementations (AIX, HP-UX, Solaris) use the same
418 exit statuses as <EM>ncurses</EM>.
420 NetBSD <EM>curses</EM> documents exit statuses that correspond to neither
421 <EM>ncurses</EM> nor X/Open Curses.
424 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
425 Bill Joy wrote a <STRONG>tput</STRONG> command during development of 4BSD in October
426 1980. This initial version only cleared the screen, and did not ship
427 with official distributions.
429 System V developed a different <STRONG>tput</STRONG> command.
431 <STRONG>o</STRONG> SVr2 (1984) provided a rudimentary <STRONG>tput</STRONG> that checked the parameter
432 against each predefined capability and returned the corresponding
433 value. This version of <STRONG>tput</STRONG> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for
434 parameterized capabilities.
436 <STRONG>o</STRONG> SVr3 (1987) replaced that with a more extensive program whose
437 support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than half the program)
438 incorporated the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
440 <STRONG>o</STRONG> SVr4 (1989) added color initialization by using the <STRONG>orig_colors</STRONG>
441 (<STRONG>oc</STRONG>) and <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) capabilities in its <STRONG>init</STRONG> logic.
443 Keith Bostic refactored BSD <STRONG>tput</STRONG> for shipment in 4.3BSD-Tahoe (1988),
444 then replaced it the next year with a new implementation based on
445 System V <STRONG>tput</STRONG>. Bostic's version similarly accepted some parameters
446 named for <EM>terminfo</EM> (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG>, and
447 <STRONG>reset</STRONG>. However, because he had only <EM>termcap</EM> available, it accepted
448 <EM>termcap</EM> codes for other capabilities. Also, Bostic's BSD <STRONG>tput</STRONG> did not
449 modify the terminal modes as the earlier BSD <STRONG>tset</STRONG> had done.
451 At the same time, Bostic added a shell script named "clear" that used
452 <STRONG>tput</STRONG> to clear the screen. Both of these appeared in 4.4BSD, becoming
453 the "modern" BSD implementation of <STRONG>tput</STRONG>.
455 The origin of <EM>ncurses</EM> <STRONG>tput</STRONG> lies outside both System V and BSD, in Ross
456 Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in December
457 1992. Ridge's program made more sophisticated use of the terminal
458 capabilities than the BSD program. Eric Raymond used that <STRONG>tput</STRONG> program
459 (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995. Incorporating
460 the portions dealing with terminal capabilities almost without change,
461 Raymond made improvements to the way command-line parameters were
464 Before <EM>ncurses</EM> 6.1 (2018), its <STRONG>tset</STRONG> and <STRONG>tput</STRONG> utilities differed.
466 <STRONG>o</STRONG> <STRONG>tset</STRONG> was more effective, resetting the terminal modes and special
469 <STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for
470 resetting the terminal was more limited; it had only equivalents of
471 <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>), and
472 not the tab stop and margin update features of <STRONG>tput</STRONG>.
474 The <STRONG>reset</STRONG> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability
475 to reset terminal modes and special characters.
477 As of <EM>ncurses</EM> 6.1, the "reset" features of the two programs are
478 (mostly) the same. Two minor differences remain.
480 <STRONG>o</STRONG> When issuing a reset, the <STRONG>tset</STRONG> program checks whether the device
481 appears to be a pseudoterminal (as might be used by a terminal
482 emulator program), and, if it does not, waits one second in case it
483 is communicating with a hardware terminal.
485 <STRONG>o</STRONG> The two programs write the terminal initialization strings to
486 different streams; that is, standard error for <STRONG>tset</STRONG> and standard
487 output for <STRONG>tput</STRONG>.
490 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
491 <STRONG>tput</STRONG> <STRONG>init</STRONG>
492 Initialize the terminal according to the type of terminal in the
493 <EM>TERM</EM> environment variable. If the system does not reliably
494 initialize the terminal upon login, this command can be included
495 in <EM>$HOME/.profile</EM> after exporting the <EM>TERM</EM> environment variable.
497 <STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
498 Reset an AT&T 5620 terminal, overriding the terminal type in the
499 <EM>TERM</EM> environment variable.
501 <STRONG>tput</STRONG> <STRONG>cnorm</STRONG>
502 Set cursor to normal visibility.
504 <STRONG>tput</STRONG> <STRONG>home</STRONG>
505 Move the cursor to line 0, column 0: the upper left corner of
506 the screen, usually known as the "home" cursor position.
508 <STRONG>tput</STRONG> <STRONG>clear</STRONG>
509 Clear the screen: write the <STRONG>clear_screen</STRONG> capability's value to
510 the standard output stream.
512 <STRONG>tput</STRONG> <STRONG>cols</STRONG>
513 Report the number of columns used by the current terminal type.
515 <STRONG>tput</STRONG> <STRONG>-Tadm3a</STRONG> <STRONG>cols</STRONG>
516 Report the number of columns used by an ADM-3A terminal.
518 <STRONG>strong=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>normal=`tput</STRONG> <STRONG>rmso`</STRONG>
519 Set shell variables to capability values: <STRONG>strong</STRONG> and <STRONG>normal</STRONG>, to
520 begin and end, respectively, stand-out mode for the terminal.
521 One might use these to present a prompt.
523 printf "${strong}Username:${normal} "
525 <STRONG>tput</STRONG> <STRONG>hc</STRONG>
526 Indicate via exit status whether the terminal is a hard copy
529 <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
530 Move the cursor to line 23, column 4.
532 <STRONG>tput</STRONG> <STRONG>cup</STRONG>
533 Report the value of the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability (used
534 for cursor movement), with no parameters substituted.
536 <STRONG>tput</STRONG> <STRONG>longname</STRONG>
537 Report the <EM>terminfo</EM> database's description of the terminal type
538 specified in the <EM>TERM</EM> environment variable.
540 <STRONG>tput</STRONG> <STRONG>-S</STRONG>
541 Process multiple capabilities. The <STRONG>-S</STRONG> option can be profitably
542 used with a shell "here document".
544 $ <STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG><<!</STRONG>
545 > <STRONG>clear</STRONG>
546 > <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
547 > <STRONG>bold</STRONG>
548 > <STRONG>!</STRONG>
550 The foregoing clears the screen, moves the cursor to position
551 (10, 10) and turns on bold (extra bright) mode.
553 <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
554 Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
557 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
558 <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>
562 ncurses 6.5 2024-06-22 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
566 <li><a href="#h2-NAME">NAME</a></li>
567 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
568 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
570 <li><a href="#h3-Operands">Operands</a></li>
571 <li><a href="#h3-Aliases">Aliases</a></li>
572 <li><a href="#h3-Terminal-Size">Terminal Size</a></li>
575 <li><a href="#h2-OPTIONS">OPTIONS</a></li>
576 <li><a href="#h2-EXIT-STATUS">EXIT STATUS</a></li>
577 <li><a href="#h2-ENVIRONMENT">ENVIRONMENT</a></li>
578 <li><a href="#h2-FILES">FILES</a></li>
579 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
580 <li><a href="#h2-HISTORY">HISTORY</a></li>
581 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
582 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>