2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: tput.1,v 1.102 2024/01/13 22:47:16 tom Exp $
32 .TH @TPUT@ 1 2024-01-13 "ncurses 6.4" "User commands"
53 initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
55 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
56 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
58 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
60 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
62 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
64 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
70 \fB\%@TPUT@\fP uses the
72 library and database to make terminal-specific capabilities and
73 information available to the shell,
74 to initialize or reset the terminal,
76 to report a description of the current
79 Terminal capabilities are accessed by
82 \fB\%terminfo\fP(5) discusses terminal capabilities at length
83 and presents a complete list of
86 When retrieving capability values,
87 the result depends upon the capability's type.
88 .TP 9 \" "Boolean" + 2n
90 \fB\%@TPUT@\fP sets its exit status to
92 if the terminal possesses
101 decimal value to the standard output stream if defined
104 followed by a newline.
107 \fB\%@TPUT@\fP writes
109 value to the standard output stream if defined,
110 without a trailing newline.
112 Before using a value returned on the standard output,
113 the application should test \fB\%@TPUT@\fP's exit status
115 see section \*(``EXIT STATUS\*('' below.
120 a capability code from the terminal database,
121 or a parameter thereto.
122 Three others are specially recognized by \fB\%@TPUT@\fP:
127 Although these resemble capability codes,
128 they in fact receive special handling;
129 we term them \*(``pseudo-capabilities\*(''.
130 .TP 11n \" "longname" + 2n + adjustment for PDF
132 indicates a capability from the terminal database.
134 If the capability is of string type and takes parameters,
135 the arguments following the capability will be used as its parameters.
137 Most parameters are numeric.
138 Only a few terminal capabilities require string parameters;
139 \fB\%@TPUT@\fP uses a table to decide which to pass as strings.
140 Normally \fB\%@TPUT@\fP uses \fB\%tparm\fP(3X) to perform the
142 If no parameters are given for the capability,
143 \fB\%@TPUT@\fP writes the string without performing the substitution.
146 initializes the terminal.
147 If the terminal database is present
148 and an entry for the user's terminal type exists,
153 \fB\%@TPUT@\fP retrieves the terminal's mode settings.
154 It successively tests the file descriptors corresponding to
157 the standard error stream,
159 the standard output stream,
161 the standard input stream,
167 to obtain terminal settings.
168 Having retrieved them,
169 \fB\%@TPUT@\fP remembers which descriptor to use for further updates.
172 If the terminal dimensions cannot be obtained from the operating system,
173 but the environment or terminal type database entry describes them,
174 \fB\%@TPUT@\fP updates the operating system's notion of them.
177 \fB\%@TPUT@\fP updates the terminal modes.
180 Any delays specified in the entry
182 when a newline is sent)
183 are set in the terminal driver.
185 Tab expansion is turned on or off per the specification in the entry,
188 if tabs are not expanded,
195 If initialization capabilities,
196 detailed in subsection \*(``Tabs and Initialization\*('' of
199 \fB\%@TPUT@\fP writes them to the standard output stream.
202 \fB\%@TPUT@\fP flushes the standard output stream.
205 If an entry lacks the information needed for an activity above,
206 that activity is silently skipped.
209 re-initializes the terminal.
210 A reset differs from initialization in two ways.
214 \fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
217 enabling cooked and echo modes,
219 disabling cbreak and raw modes,
221 enabling newline translation,
224 setting any unset special characters to their default values.
228 If any reset capabilities are defined for the terminal type,
229 \fB\%@TPUT@\fP writes them to the output stream.
231 \fB\%@TPUT@\fP uses any defined initialization capabilities.
232 Reset capabilities are detailed in subsection
233 \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
239 entry begins with one or more names by which an application
240 can refer to the entry,
241 before the list of terminal capabilities.
242 The names are separated by \*(``|\*('' characters.
243 X/Open Curses terms the last name the \*(``long name\*('',
244 and indicates that it may include blanks.
246 \fB\%@TIC@\fP warns if the last name does not include blanks,
249 entries that treated the long name as an optional feature.
250 The long name is often referred to as the description field.
252 If the terminal database is present and an entry for the user's terminal
254 \fB\%@TPUT@\fP reports its description to the standard output stream,
255 without a trailing newline.
256 See \fB\%terminfo\fP(5).
259 Redirecting the output of
260 .RB \%\*(`` "@TPUT@ init" \*(''
262 .RB \%\*(`` "@TPUT@ reset" \*(''
263 to a file will capture only part of their actions.
264 Changes to the terminal modes are not affected by file descriptor
266 since the terminal modes are altered via \fB\%ioctl\fP(2).
268 If \fB\%@TPUT@\fP is invoked via link with any of the names
273 it operates as if run with the corresponding (pseudo-)capability
276 executing a link named
278 that points to \fB\%@TPUT@\fP has the same effect as
279 .RB \%\*(`` "@TPUT@ \%reset" \*(''.
280 (The \fB\%@TSET@\fP(1) utility also treats a link named
284 If \fB\%@TPUT@\fP is invoked by a link named
286 this has the same effect as
287 .RB \%\*(`` "@TPUT@ init" \*(''.
288 Such a link is seldom employed because another program of that name
289 is in widespread use.
291 Besides the pseudo-capabilities
294 \fB\%@TPUT@\fP treats the
300 it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
303 \fB\%@TPUT@\fP attempts to obtain these capabilities from the terminal
305 This generally fails for terminal emulators,
306 which lack a fixed window size and thus omit the capabilities.
308 It then asks the operating system for the terminal's size,
309 which generally works,
310 unless the connection is via a serial line that
311 does not support \*(``NAWS\*('': negotiations about window size.
314 it inspects the environment variables
318 which may override the terminal size.
323 \fB\%@TPUT@\fP ignores the environment variables by calling
324 .BR \%use_tioctl(TRUE) ,
325 relying upon the operating system
328 the terminal database).
330 .TP 9n \" "-T type" + 2n
332 retrieves more than one capability per invocation of \fB\%@TPUT@\fP.
333 The capabilities must be passed to \fB\%@TPUT@\fP from the standard
334 input stream instead of from the command line
335 (see section \*(``EXAMPLES\*('' below).
341 option changes the meanings of the
346 (see section \*(``EXIT STATUS\*('' below).
348 Some capabilities use string parameters rather than numeric ones.
349 \fB\%@TPUT@\fP employs a built-in table and the presence of parameters
350 in its input to decide how to interpret them,
351 and whether to use \fB\%tparm\fP(3X).
354 indicates the terminal's
356 Normally this option is unnecessary,
357 because a default is taken from the
359 environment variable.
361 the environment variables
368 reports the version of
370 associated with \fB\%@TPUT@\fP,
371 and exits with a successful status.
375 .RB \%\*(`` "@TPUT@ clear" \*(''
376 from attempting to clear the scrollback buffer.
379 one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
386 Status Meaning When \-S Not Specified
388 0 Boolean or string capability present
389 1 Boolean or numeric capability absent
390 2 usage error or no terminal type specified
391 3 unrecognized terminal type
392 4 unrecognized capability code
393 >4 system error (4 + \fBerrno\fP)
399 some statuses change meanings.
406 Status Meaning When \-S Specified
408 0 all operands interpreted
410 4 some operands not interpreted
413 \fB@TPUT@\fP command reads one environment variable.
414 .TP 8n \" "TERM" + 2n + adjustment for PDF
416 denotes the terminal type.
417 Each terminal type is distinct,
418 though many are similar.
421 option overrides its value.
425 tab stop initialization database
428 compiled terminal description database
433 has differed from that of System\ V in two important respects,
434 one now mostly historical.
438 writes to the standard output,
439 which need not be a terminal device.
441 the operands that manipulate terminal modes might not use the standard
449 operands use logic from 4.1cBSD
451 manipulating terminal modes.
452 It checks the same file descriptors
455 for association with a terminal device as
459 finally assumes a 1200 baud terminal.
460 When updating terminal modes,
466 (see section \*(``HISTORY\*('' below),
467 \fB\%@TPUT@\fP did not modify terminal modes.
468 It now employs a scheme similar to System\ V,
469 using functions shared with \fB\%@TSET@\fP
470 (and ultimately based on 4.4BSD
472 If it is not able to open a terminal
474 when run by \fIcron\fP(1)),
475 \fB\%@TPUT@\fP exits with an error status.
479 assumes that the type of a
481 operand is numeric if all the characters of its value are decimal
486 as a string capability.
488 Most implementations that provide support for
490 operands use the \fB\%tparm\fP(3X) function to expand its parameters.
491 That function expects a mixture of numeric and string parameters,
492 requiring \fB\%@TPUT@\fP to know which type to use.
496 uses a table to determine the parameter types for
500 and an internal function to analyze nonstandard
504 While more reliable than System\ V's utility,
505 a portability problem is introduced by this analysis.
506 An OpenBSD developer adapted the internal library function from
513 and modified it to interpret multiple
517 Portable applications should not rely upon this feature;
519 offers it to support applications written specifically for OpenBSD.
530 support is compiled in.
552 .B \%parm_delete_line
559 .BR \%parm_delete_line .
570 .B \%exit_delete_mode
586 .BR \%exit_delete_mode .
593 and the parameter-substitution features used in the
596 were not supported in
601 4.3BSD-Reno (1990) added support for
603 .\" longname was added in October 1989.
605 NetBSD added support for the parameter-substitution features.
607 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
615 A few observations of interest arise from that selection.
620 as it does any other standard
626 do not correspond to terminal capabilities.
630 on SVr4-based systems such as Solaris,
633 as well as others such as AIX and Tru64,
634 also support standard
638 A few platforms such as FreeBSD recognize
642 capability names in their respective
669 Because (apparently) all
671 Unix systems support the full set of capability codes,
672 the reason for documenting only a few may not be apparent.
674 X/Open Curses Issue 7 documents
679 and the other features used in this implementation.
682 there are two standards for
684 POSIX (a subset) and X/Open Curses (the full implementation).
685 POSIX documents a subset to avoid the complication of including
686 X/Open Curses and the terminal capability database.
688 While it is certainly possible to write a
690 program without using
694 implementation provides a
696 utility that does not also support standard
699 X/Open Curses Issue 7 (2009) is the first version to document utilities.
700 However that part of X/Open Curses does not follow existing practice
706 It assigns exit status 4 to \*(``invalid operand\*('',
707 which may have the same meaning as \*(``unknown capability\*(''.
712 uses the term \*(``invalid\*('' in this case.
714 It assigns exit status 255 to a numeric variable that is not specified
718 That likely is a documentation error,
719 mistaking the \*(``\-1\*('' written to the standard output to indicate
720 an absent or cancelled numeric capability for an (unsigned) exit status.
722 The various System\ V implementations
726 use the same exit statuses as
731 documents exit statuses that correspond to neither
737 command during development of 4BSD in October 1980.
738 This initial version only cleared the screen,
739 and did not ship with official distributions.
740 .\" It also exited with backwards exit status (1 on success, 0 on
741 .\" failure), and was characterized by Bostic in 1988 as "pretty
743 .\" See Spinellis's "unix-history-repo" on GitHub.
745 System\ V developed a different
749 SVr2 (1984) provided a rudimentary
751 that checked the parameter against each
752 predefined capability and returned the corresponding value.
755 did not use \fB\%tparm\fP(3X) for parameterized capabilities.
757 SVr3 (1987) replaced that
758 .\" SVr3 released in 1987, not 1985.
759 .\" https://unix.org/what_is_unix/history_timeline.html
760 with a more extensive program
766 (more than half the program)
771 written by Eric Allman.
773 SVr4 (1989) added color initialization by using the
783 Keith Bostic refactored BSD
785 for shipment in 4.3BSD-Tahoe (1988),
786 then replaced it the next year with a new implementation based on
789 Bostic's version similarly accepted some parameters named for
791 (pseudo-)capabilities:
803 names for other capabilities.
807 did not modify the terminal modes as the earlier BSD
812 Bostic added a shell script named \*(``clear\*('' that used
815 Both of these appeared in 4.4BSD,
816 becoming the \*(``modern\*('' BSD implementation of
821 \fB\%@TPUT@\fP lies outside both System\ V and BSD,
828 Ridge's program made more sophisticated use of the terminal capabilities
829 than the BSD program.
830 Eric Raymond used that
838 Incorporating the portions dealing with terminal capabilities
839 almost without change,
840 Raymond made improvements to the way command-line parameters
846 its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
848 \fB\%@TSET@\fP was more effective,
849 resetting the terminal modes and special characters.
852 \fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
853 terminal was more limited;
854 it had only equivalents of
862 and not the tab stop and margin update features of \fB\%@TPUT@\fP.
866 program is traditionally an alias for \fB\%@TSET@\fP due to its ability
867 to reset terminal modes and special characters.
872 the \*(``reset\*('' features of the two programs are (mostly) the same.
873 Two minor differences remain.
875 The \fB\%@TSET@\fP program waits one second when resetting,
876 in case the terminal happens to be a hardware device.
878 The two programs write the terminal initialization strings
879 to different streams;
881 standard error for \fB\%@TSET@\fP and
882 standard output for \fB\%@TPUT@\fP.
886 Initialize the terminal according to the type of
889 environment variable.
890 If the system does not reliably initialize the terminal upon login,
891 this command can be included in
895 environment variable.
897 .B "@TPUT@ \-T5620 reset"
898 Reset an AT&T 5620 terminal,
899 overriding the terminal type in the
901 environment variable.
904 Set cursor to normal visibility.
907 Move the cursor to row 0,
909 the upper left corner of the screen,
910 usually known as the \*(``home\*('' cursor position.
916 capability's value to the standard output stream.
919 Report the number of columns used by the current terminal type.
921 .B "@TPUT@ \-Tadm3a cols"
922 Report the number of columns used by an ADM-3A terminal.
924 .B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
925 Set shell variables to capability values:
931 stand-out mode for the terminal.
932 One might use these to present a prompt.
936 printf "${strong}Username:${normal} "
941 Indicate via exit status whether the terminal is a hard copy device.
944 Move the cursor to row 23,
948 Report the value of the
952 (used for cursor movement),
953 with no parameters substituted.
958 database's description of the terminal type specified in the
960 environment variable.
963 Process multiple capabilities.
966 option can be profitably used with a shell \*(``here document\*(''.
969 .RB $\ "@TPUT@ \-S <<!"
978 moves the cursor to position
984 .B "@TPUT@ clear cup 10 10 bold"
985 Perform the same actions as the foregoing
986 .RB \%\*(`` "@TPUT@ \-S" \*(''
993 \fB\%curs_termcap\fP(3X),