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.118 2024/06/22 21:28:35 tom Exp $
32 .TH @TPUT@ 1 2024-06-22 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
50 initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
52 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP]
53 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
55 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
57 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
59 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
61 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
63 \fB@TPUT@\fP [\fB\-v\fP] \fB\-S\fP
65 \fB@TPUT@\fP [\fB\-v\fP] \fB\-V\fP
67 \fB\%@TPUT@\fP uses the
69 library and database to make terminal-specific capabilities and
70 information available to the shell,
71 to initialize or reset the terminal,
73 to report a description of the current
76 Terminal capabilities are accessed by
79 \fB\%terminfo\fP(5) discusses terminal capabilities at length
80 and presents a complete list of
83 When retrieving capability values,
84 the result depends upon the capability's type.
85 .TP 9 \" "Boolean" + 2n
87 \fB\%@TPUT@\fP sets its exit status to
89 if the terminal possesses
98 decimal value to the standard output stream if defined
101 followed by a newline.
104 \fB\%@TPUT@\fP writes
106 value to the standard output stream if defined,
107 without a trailing newline.
109 Before using a value returned on the standard output,
110 the application should test \fB\%@TPUT@\fP's exit status
112 see section \*(``EXIT STATUS\*('' below.
117 a capability code from the terminal database,
118 or a parameter thereto.
119 Three others are specially recognized by \fB\%@TPUT@\fP:
124 Although these resemble capability codes,
125 they in fact receive special handling;
126 we term them \*(``pseudo-capabilities\*(''.
127 .TP 11n \" "longname" + 2n + adjustment for PDF
129 indicates a capability from the terminal database.
133 is of string type and takes parameters,
134 \fB\%@TPUT@\fP interprets arguments following
137 up to the (fixed) quantity the capability requires.
139 Most parameters are numeric.
140 Only a few terminal capabilities require string parameters;
141 \fB\%@TPUT@\fP uses a table to decide which to pass as strings.
142 Normally \fB\%@TPUT@\fP uses \fB\%tparm\fP(3X) to perform the
144 If no parameters are given for the capability,
145 \fB\%@TPUT@\fP writes the string without performing the substitution.
148 initializes the terminal.
149 If the terminal database is present
150 and an entry for the user's terminal type exists,
155 \fB\%@TPUT@\fP retrieves the terminal's mode settings.
156 It successively tests the file descriptors corresponding to
159 the standard error stream,
161 the standard output stream,
163 the standard input stream,
169 to obtain terminal settings.
170 Having retrieved them,
171 \fB\%@TPUT@\fP remembers which descriptor to use for further updates.
174 If the terminal dimensions cannot be obtained from the operating system,
175 but the environment or terminal type database entry describes them,
176 \fB\%@TPUT@\fP updates the operating system's notion of them.
179 \fB\%@TPUT@\fP updates the terminal modes.
182 Any delays specified in the entry
184 when a newline is sent)
185 are set in the terminal driver.
187 Tab expansion is turned on or off per the specification in the entry,
190 if tabs are not expanded,
197 If initialization capabilities,
198 detailed in subsection \*(``Tabs and Initialization\*('' of
201 \fB\%@TPUT@\fP writes them to the standard output stream.
204 \fB\%@TPUT@\fP flushes the standard output stream.
207 If an entry lacks the information needed for an activity above,
208 that activity is silently skipped.
211 re-initializes the terminal.
212 A reset differs from initialization in two ways.
216 \fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
219 enabling cooked and echo modes,
221 disabling cbreak and raw modes,
223 enabling newline translation,
226 setting any unset special characters to their default values.
230 If any reset capabilities are defined for the terminal type,
231 \fB\%@TPUT@\fP writes them to the output stream.
233 \fB\%@TPUT@\fP uses any defined initialization capabilities.
234 Reset capabilities are detailed in subsection
235 \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
241 entry begins with one or more names by which an application
242 can refer to the entry,
243 before the list of terminal capabilities.
244 The names are separated by \*(``|\*('' characters.
245 X/Open Curses terms the last name the \*(``long name\*('',
246 and indicates that it may include blanks.
248 \fB\%@TIC@\fP warns if the last name does not include blanks,
251 entries that treated the long name as an optional feature.
252 The long name is often referred to as the description field.
254 If the terminal database is present and an entry for the user's terminal
256 \fB\%@TPUT@\fP reports its description to the standard output stream,
257 without a trailing newline.
258 See \fB\%terminfo\fP(5).
261 Redirecting the output of
262 .RB \%\*(`` "@TPUT@ init" \*(''
264 .RB \%\*(`` "@TPUT@ reset" \*(''
265 to a file will capture only part of their actions.
266 Changes to the terminal modes are not affected by file descriptor
268 since the terminal modes are altered via \fB\%ioctl\fP(2).
270 If \fB\%@TPUT@\fP is invoked via link with any of the names
275 it operates as if run with the corresponding (pseudo-)capability
278 executing a link named
280 that points to \fB\%@TPUT@\fP has the same effect as
281 .RB \%\*(`` "@TPUT@ \%reset" \*(''.
283 This feature was introduced by
289 is a separate program,
290 which is both smaller and more frequently executed.
293 has the same name as another program in widespread use.
297 by the \fB\%@TSET@\fP(1) utility (also via a link named
300 Besides the pseudo-capabilities
303 \fB\%@TPUT@\fP treats the
309 it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
312 \fB\%@TPUT@\fP attempts to obtain these capabilities from the terminal
314 This generally fails for terminal emulators,
315 which lack a fixed window size and thus omit the capabilities.
317 It then asks the operating system for the terminal's size,
318 which generally works,
319 unless the connection is via a serial line that
320 does not support \*(``NAWS\*('': negotiations about window size.
323 it inspects the environment variables
327 which may override the terminal size.
332 \fB\%@TPUT@\fP ignores the environment variables by calling
333 .BR \%use_tioctl(TRUE) ,
334 relying upon the operating system
337 the terminal database).
339 .TP 9n \" "-T type" + 2n
341 retrieves more than one capability per invocation of \fB\%@TPUT@\fP.
342 The capabilities must be passed to \fB\%@TPUT@\fP from the standard
343 input stream instead of from the command line
344 (see section \*(``EXAMPLES\*('' below).
350 option changes the meanings of the
355 (see section \*(``EXIT STATUS\*('' below).
357 Some capabilities use string parameters rather than numeric ones.
358 \fB\%@TPUT@\fP employs a built-in table and the presence of parameters
359 in its input to decide how to interpret them,
360 and whether to use \fB\%tparm\fP(3X).
363 indicates the terminal's
365 Normally this option is unnecessary,
366 because a default is taken from the
368 environment variable.
370 the environment variables
377 causes \fB\%@TPUT@\fP to operate verbosely,
381 reports the version of
383 associated with \fB\%@TPUT@\fP,
384 and exits with a successful status.
388 .RB \%\*(`` "@TPUT@ clear" \*(''
389 from attempting to clear the scrollback buffer.
392 one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
399 Status Meaning When \-S Not Specified
401 0 Boolean or string capability present
402 1 Boolean or numeric capability absent
403 2 usage error or no terminal type specified
404 3 unrecognized terminal type
405 4 unrecognized capability code
406 >4 system error (4 + \fBerrno\fP)
412 some statuses change meanings.
419 Status Meaning When \-S Specified
421 0 all operands interpreted
423 4 some operands not interpreted
426 \fB@TPUT@\fP reads one environment variable.
427 .TP 8n \" "TERM" + 2n + adjustment for PDF
429 denotes the terminal type.
430 Each terminal type is distinct,
431 though many are similar.
434 option overrides its value.
438 tab stop initialization database
441 compiled terminal description database
446 has differed from that of System\ V in two important respects,
447 one now mostly historical.
451 writes to the standard output,
452 which need not be a terminal device.
454 the operands that manipulate terminal modes might not use the standard
462 operands use logic from 4.1cBSD
464 manipulating terminal modes.
465 It checks the same file descriptors
468 for association with a terminal device as
472 finally assumes a 1200 baud terminal.
473 When updating terminal modes,
479 (see section \*(``HISTORY\*('' below),
480 \fB\%@TPUT@\fP did not modify terminal modes.
481 It now employs a scheme similar to System\ V,
482 using functions shared with \fB\%@TSET@\fP
483 (and ultimately based on 4.4BSD
485 If it is not able to open a terminal
487 when run by \fIcron\fP(1)),
488 \fB\%@TPUT@\fP exits with an error status.
492 assumes that the type of a
494 operand is numeric if all the characters of its value are decimal
499 as a string capability.
501 Most implementations that provide support for
503 operands use the \fB\%tparm\fP(3X) function to expand its parameters.
504 That function expects a mixture of numeric and string parameters,
505 requiring \fB\%@TPUT@\fP to know which type to use.
509 uses a table to determine the parameter types for
513 and an internal function to analyze nonstandard
517 While more reliable than System\ V's utility,
518 a portability problem is introduced by this analysis.
519 An OpenBSD developer adapted the internal library function from
526 and modified it to interpret multiple
530 Portable applications should not rely upon this feature;
532 offers it to support applications written specifically for OpenBSD.
543 support is compiled in.
565 .B \%parm_delete_line
572 .BR \%parm_delete_line .
583 .B \%exit_delete_mode
599 .BR \%exit_delete_mode .
606 and the parameter-substitution features used in the
609 were not supported in
614 4.3BSD-Reno (1990) added support for
616 .\" longname was added in October 1989.
618 NetBSD added support for the parameter-substitution features.
620 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
628 A few observations of interest arise from that selection.
633 as it does any other standard
639 do not correspond to terminal capabilities.
643 on SVr4-based systems such as Solaris,
646 as well as others such as AIX and Tru64,
647 also support standard
651 A few platforms such as FreeBSD recognize
655 capability codes in their respective
682 Because (apparently) all
684 Unix systems support the full set of capability codes,
685 the reason for documenting only a few may not be apparent.
687 X/Open Curses Issue 7 documents
692 and the other features used in this implementation.
695 there are two standards for
697 POSIX (a subset) and X/Open Curses (the full implementation).
698 POSIX documents a subset to avoid the complication of including
699 X/Open Curses and the terminal capability database.
701 While it is certainly possible to write a
703 program without using
707 implementation provides a
709 utility that does not also support standard
712 X/Open Curses Issue 7 (2009) is the first version to document utilities.
713 However that part of X/Open Curses does not follow existing practice
719 It assigns exit status 4 to \*(``invalid operand\*('',
720 which may have the same meaning as \*(``unknown capability\*(''.
725 uses the term \*(``invalid\*('' in this case.
727 It assigns exit status 255 to a numeric variable that is not specified
731 That likely is a documentation error,
732 mistaking the \*(``\-1\*('' written to the standard output to indicate
733 an absent or cancelled numeric capability for an (unsigned) exit status.
735 The various System\ V implementations
739 use the same exit statuses as
744 documents exit statuses that correspond to neither
750 command during development of 4BSD in October 1980.
751 This initial version only cleared the screen,
752 and did not ship with official distributions.
753 .\" It also exited with backwards exit status (1 on success, 0 on
754 .\" failure), and was characterized by Bostic in 1988 as "pretty
756 .\" See Spinellis's "unix-history-repo" on GitHub.
758 System\ V developed a different
762 SVr2 (1984) provided a rudimentary
764 that checked the parameter against each
765 predefined capability and returned the corresponding value.
768 did not use \fB\%tparm\fP(3X) for parameterized capabilities.
770 SVr3 (1987) replaced that
771 .\" SVr3 released in 1987, not 1985.
772 .\" https://unix.org/what_is_unix/history_timeline.html
773 with a more extensive program
779 (more than half the program)
784 written by Eric Allman.
786 SVr4 (1989) added color initialization by using the
796 Keith Bostic refactored BSD
798 for shipment in 4.3BSD-Tahoe (1988),
799 then replaced it the next year with a new implementation based on
802 Bostic's version similarly accepted some parameters named for
804 (pseudo-)capabilities:
816 codes for other capabilities.
820 did not modify the terminal modes as the earlier BSD
825 Bostic added a shell script named \*(``clear\*('' that used
828 Both of these appeared in 4.4BSD,
829 becoming the \*(``modern\*('' BSD implementation of
834 \fB\%@TPUT@\fP lies outside both System\ V and BSD,
841 Ridge's program made more sophisticated use of the terminal capabilities
842 than the BSD program.
843 Eric Raymond used that
851 Incorporating the portions dealing with terminal capabilities
852 almost without change,
853 Raymond made improvements to the way command-line parameters
859 its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
861 \fB\%@TSET@\fP was more effective,
862 resetting the terminal modes and special characters.
865 \fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
866 terminal was more limited;
867 it had only equivalents of
875 and not the tab stop and margin update features of \fB\%@TPUT@\fP.
879 program is traditionally an alias for \fB\%@TSET@\fP due to its ability
880 to reset terminal modes and special characters.
885 the \*(``reset\*('' features of the two programs are (mostly) the same.
886 Two minor differences remain.
888 When issuing a reset,
889 the \fB\%@TSET@\fP program
890 checks whether the device appears to be a pseudoterminal
891 (as might be used by a terminal emulator program),
894 waits one second in case it is communicating with a hardware terminal.
896 The two programs write the terminal initialization strings
897 to different streams;
899 standard error for \fB\%@TSET@\fP and
900 standard output for \fB\%@TPUT@\fP.
904 Initialize the terminal according to the type of
907 environment variable.
908 If the system does not reliably initialize the terminal upon login,
909 this command can be included in
913 environment variable.
915 .B "@TPUT@ \-T5620 reset"
916 Reset an AT&T 5620 terminal,
917 overriding the terminal type in the
919 environment variable.
922 Set cursor to normal visibility.
925 Move the cursor to line 0,
927 the upper left corner of the screen,
928 usually known as the \*(``home\*('' cursor position.
934 capability's value to the standard output stream.
937 Report the number of columns used by the current terminal type.
939 .B "@TPUT@ \-Tadm3a cols"
940 Report the number of columns used by an ADM-3A terminal.
942 .B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
943 Set shell variables to capability values:
949 stand-out mode for the terminal.
950 One might use these to present a prompt.
954 printf "${strong}Username:${normal} "
959 Indicate via exit status whether the terminal is a hard copy device.
962 Move the cursor to line 23,
966 Report the value of the
970 (used for cursor movement),
971 with no parameters substituted.
976 database's description of the terminal type specified in the
978 environment variable.
981 Process multiple capabilities.
984 option can be profitably used with a shell \*(``here document\*(''.
987 .RB $\ "@TPUT@ \-S <<!"
996 moves the cursor to position
1002 .B "@TPUT@ clear cup 10 10 bold"
1003 Perform the same actions as the foregoing
1004 .RB \%\*(`` "@TPUT@ \-S" \*(''
1011 \fB\%curs_termcap\fP(3X),