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.109 2024/03/23 20:42:29 tom Exp $
32 .TH @TPUT@ 1 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
51 initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
53 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
54 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
56 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
58 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
60 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
62 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
68 \fB\%@TPUT@\fP uses the
70 library and database to make terminal-specific capabilities and
71 information available to the shell,
72 to initialize or reset the terminal,
74 to report a description of the current
77 Terminal capabilities are accessed by
80 \fB\%terminfo\fP(5) discusses terminal capabilities at length
81 and presents a complete list of
84 When retrieving capability values,
85 the result depends upon the capability's type.
86 .TP 9 \" "Boolean" + 2n
88 \fB\%@TPUT@\fP sets its exit status to
90 if the terminal possesses
99 decimal value to the standard output stream if defined
102 followed by a newline.
105 \fB\%@TPUT@\fP writes
107 value to the standard output stream if defined,
108 without a trailing newline.
110 Before using a value returned on the standard output,
111 the application should test \fB\%@TPUT@\fP's exit status
113 see section \*(``EXIT STATUS\*('' below.
118 a capability code from the terminal database,
119 or a parameter thereto.
120 Three others are specially recognized by \fB\%@TPUT@\fP:
125 Although these resemble capability codes,
126 they in fact receive special handling;
127 we term them \*(``pseudo-capabilities\*(''.
128 .TP 11n \" "longname" + 2n + adjustment for PDF
130 indicates a capability from the terminal database.
132 If the capability is of string type and takes parameters,
133 the arguments following the capability will be used as its parameters.
135 Most parameters are numeric.
136 Only a few terminal capabilities require string parameters;
137 \fB\%@TPUT@\fP uses a table to decide which to pass as strings.
138 Normally \fB\%@TPUT@\fP uses \fB\%tparm\fP(3X) to perform the
140 If no parameters are given for the capability,
141 \fB\%@TPUT@\fP writes the string without performing the substitution.
144 initializes the terminal.
145 If the terminal database is present
146 and an entry for the user's terminal type exists,
151 \fB\%@TPUT@\fP retrieves the terminal's mode settings.
152 It successively tests the file descriptors corresponding to
155 the standard error stream,
157 the standard output stream,
159 the standard input stream,
165 to obtain terminal settings.
166 Having retrieved them,
167 \fB\%@TPUT@\fP remembers which descriptor to use for further updates.
170 If the terminal dimensions cannot be obtained from the operating system,
171 but the environment or terminal type database entry describes them,
172 \fB\%@TPUT@\fP updates the operating system's notion of them.
175 \fB\%@TPUT@\fP updates the terminal modes.
178 Any delays specified in the entry
180 when a newline is sent)
181 are set in the terminal driver.
183 Tab expansion is turned on or off per the specification in the entry,
186 if tabs are not expanded,
193 If initialization capabilities,
194 detailed in subsection \*(``Tabs and Initialization\*('' of
197 \fB\%@TPUT@\fP writes them to the standard output stream.
200 \fB\%@TPUT@\fP flushes the standard output stream.
203 If an entry lacks the information needed for an activity above,
204 that activity is silently skipped.
207 re-initializes the terminal.
208 A reset differs from initialization in two ways.
212 \fB\%@TPUT@\fP sets the the terminal modes to a \*(``sane\*('' state,
215 enabling cooked and echo modes,
217 disabling cbreak and raw modes,
219 enabling newline translation,
222 setting any unset special characters to their default values.
226 If any reset capabilities are defined for the terminal type,
227 \fB\%@TPUT@\fP writes them to the output stream.
229 \fB\%@TPUT@\fP uses any defined initialization capabilities.
230 Reset capabilities are detailed in subsection
231 \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
237 entry begins with one or more names by which an application
238 can refer to the entry,
239 before the list of terminal capabilities.
240 The names are separated by \*(``|\*('' characters.
241 X/Open Curses terms the last name the \*(``long name\*('',
242 and indicates that it may include blanks.
244 \fB\%@TIC@\fP warns if the last name does not include blanks,
247 entries that treated the long name as an optional feature.
248 The long name is often referred to as the description field.
250 If the terminal database is present and an entry for the user's terminal
252 \fB\%@TPUT@\fP reports its description to the standard output stream,
253 without a trailing newline.
254 See \fB\%terminfo\fP(5).
257 Redirecting the output of
258 .RB \%\*(`` "@TPUT@ init" \*(''
260 .RB \%\*(`` "@TPUT@ reset" \*(''
261 to a file will capture only part of their actions.
262 Changes to the terminal modes are not affected by file descriptor
264 since the terminal modes are altered via \fB\%ioctl\fP(2).
266 If \fB\%@TPUT@\fP is invoked via link with any of the names
271 it operates as if run with the corresponding (pseudo-)capability
274 executing a link named
276 that points to \fB\%@TPUT@\fP has the same effect as
277 .RB \%\*(`` "@TPUT@ \%reset" \*(''.
279 This feature was introduced by
285 is a separate program,
286 which is both smaller and more frequently executed.
289 has the same name as another program in widespread use.
293 by the \fB\%@TSET@\fP(1) utility (also via a link named
296 Besides the pseudo-capabilities
299 \fB\%@TPUT@\fP treats the
305 it may call \fB\%setupterm\fP(3X) to obtain the terminal size.
308 \fB\%@TPUT@\fP attempts to obtain these capabilities from the terminal
310 This generally fails for terminal emulators,
311 which lack a fixed window size and thus omit the capabilities.
313 It then asks the operating system for the terminal's size,
314 which generally works,
315 unless the connection is via a serial line that
316 does not support \*(``NAWS\*('': negotiations about window size.
319 it inspects the environment variables
323 which may override the terminal size.
328 \fB\%@TPUT@\fP ignores the environment variables by calling
329 .BR \%use_tioctl(TRUE) ,
330 relying upon the operating system
333 the terminal database).
335 .TP 9n \" "-T type" + 2n
337 retrieves more than one capability per invocation of \fB\%@TPUT@\fP.
338 The capabilities must be passed to \fB\%@TPUT@\fP from the standard
339 input stream instead of from the command line
340 (see section \*(``EXAMPLES\*('' below).
346 option changes the meanings of the
351 (see section \*(``EXIT STATUS\*('' below).
353 Some capabilities use string parameters rather than numeric ones.
354 \fB\%@TPUT@\fP employs a built-in table and the presence of parameters
355 in its input to decide how to interpret them,
356 and whether to use \fB\%tparm\fP(3X).
359 indicates the terminal's
361 Normally this option is unnecessary,
362 because a default is taken from the
364 environment variable.
366 the environment variables
373 reports the version of
375 associated with \fB\%@TPUT@\fP,
376 and exits with a successful status.
380 .RB \%\*(`` "@TPUT@ clear" \*(''
381 from attempting to clear the scrollback buffer.
384 one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
391 Status Meaning When \-S Not Specified
393 0 Boolean or string capability present
394 1 Boolean or numeric capability absent
395 2 usage error or no terminal type specified
396 3 unrecognized terminal type
397 4 unrecognized capability code
398 >4 system error (4 + \fBerrno\fP)
404 some statuses change meanings.
411 Status Meaning When \-S Specified
413 0 all operands interpreted
415 4 some operands not interpreted
418 \fB@TPUT@\fP reads one environment variable.
419 .TP 8n \" "TERM" + 2n + adjustment for PDF
421 denotes the terminal type.
422 Each terminal type is distinct,
423 though many are similar.
426 option overrides its value.
430 tab stop initialization database
433 compiled terminal description database
438 has differed from that of System\ V in two important respects,
439 one now mostly historical.
443 writes to the standard output,
444 which need not be a terminal device.
446 the operands that manipulate terminal modes might not use the standard
454 operands use logic from 4.1cBSD
456 manipulating terminal modes.
457 It checks the same file descriptors
460 for association with a terminal device as
464 finally assumes a 1200 baud terminal.
465 When updating terminal modes,
471 (see section \*(``HISTORY\*('' below),
472 \fB\%@TPUT@\fP did not modify terminal modes.
473 It now employs a scheme similar to System\ V,
474 using functions shared with \fB\%@TSET@\fP
475 (and ultimately based on 4.4BSD
477 If it is not able to open a terminal
479 when run by \fIcron\fP(1)),
480 \fB\%@TPUT@\fP exits with an error status.
484 assumes that the type of a
486 operand is numeric if all the characters of its value are decimal
491 as a string capability.
493 Most implementations that provide support for
495 operands use the \fB\%tparm\fP(3X) function to expand its parameters.
496 That function expects a mixture of numeric and string parameters,
497 requiring \fB\%@TPUT@\fP to know which type to use.
501 uses a table to determine the parameter types for
505 and an internal function to analyze nonstandard
509 While more reliable than System\ V's utility,
510 a portability problem is introduced by this analysis.
511 An OpenBSD developer adapted the internal library function from
518 and modified it to interpret multiple
522 Portable applications should not rely upon this feature;
524 offers it to support applications written specifically for OpenBSD.
535 support is compiled in.
557 .B \%parm_delete_line
564 .BR \%parm_delete_line .
575 .B \%exit_delete_mode
591 .BR \%exit_delete_mode .
598 and the parameter-substitution features used in the
601 were not supported in
606 4.3BSD-Reno (1990) added support for
608 .\" longname was added in October 1989.
610 NetBSD added support for the parameter-substitution features.
612 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
620 A few observations of interest arise from that selection.
625 as it does any other standard
631 do not correspond to terminal capabilities.
635 on SVr4-based systems such as Solaris,
638 as well as others such as AIX and Tru64,
639 also support standard
643 A few platforms such as FreeBSD recognize
647 capability codes in their respective
674 Because (apparently) all
676 Unix systems support the full set of capability codes,
677 the reason for documenting only a few may not be apparent.
679 X/Open Curses Issue 7 documents
684 and the other features used in this implementation.
687 there are two standards for
689 POSIX (a subset) and X/Open Curses (the full implementation).
690 POSIX documents a subset to avoid the complication of including
691 X/Open Curses and the terminal capability database.
693 While it is certainly possible to write a
695 program without using
699 implementation provides a
701 utility that does not also support standard
704 X/Open Curses Issue 7 (2009) is the first version to document utilities.
705 However that part of X/Open Curses does not follow existing practice
711 It assigns exit status 4 to \*(``invalid operand\*('',
712 which may have the same meaning as \*(``unknown capability\*(''.
717 uses the term \*(``invalid\*('' in this case.
719 It assigns exit status 255 to a numeric variable that is not specified
723 That likely is a documentation error,
724 mistaking the \*(``\-1\*('' written to the standard output to indicate
725 an absent or cancelled numeric capability for an (unsigned) exit status.
727 The various System\ V implementations
731 use the same exit statuses as
736 documents exit statuses that correspond to neither
742 command during development of 4BSD in October 1980.
743 This initial version only cleared the screen,
744 and did not ship with official distributions.
745 .\" It also exited with backwards exit status (1 on success, 0 on
746 .\" failure), and was characterized by Bostic in 1988 as "pretty
748 .\" See Spinellis's "unix-history-repo" on GitHub.
750 System\ V developed a different
754 SVr2 (1984) provided a rudimentary
756 that checked the parameter against each
757 predefined capability and returned the corresponding value.
760 did not use \fB\%tparm\fP(3X) for parameterized capabilities.
762 SVr3 (1987) replaced that
763 .\" SVr3 released in 1987, not 1985.
764 .\" https://unix.org/what_is_unix/history_timeline.html
765 with a more extensive program
771 (more than half the program)
776 written by Eric Allman.
778 SVr4 (1989) added color initialization by using the
788 Keith Bostic refactored BSD
790 for shipment in 4.3BSD-Tahoe (1988),
791 then replaced it the next year with a new implementation based on
794 Bostic's version similarly accepted some parameters named for
796 (pseudo-)capabilities:
808 codes for other capabilities.
812 did not modify the terminal modes as the earlier BSD
817 Bostic added a shell script named \*(``clear\*('' that used
820 Both of these appeared in 4.4BSD,
821 becoming the \*(``modern\*('' BSD implementation of
826 \fB\%@TPUT@\fP lies outside both System\ V and BSD,
833 Ridge's program made more sophisticated use of the terminal capabilities
834 than the BSD program.
835 Eric Raymond used that
843 Incorporating the portions dealing with terminal capabilities
844 almost without change,
845 Raymond made improvements to the way command-line parameters
851 its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
853 \fB\%@TSET@\fP was more effective,
854 resetting the terminal modes and special characters.
857 \fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
858 terminal was more limited;
859 it had only equivalents of
867 and not the tab stop and margin update features of \fB\%@TPUT@\fP.
871 program is traditionally an alias for \fB\%@TSET@\fP due to its ability
872 to reset terminal modes and special characters.
877 the \*(``reset\*('' features of the two programs are (mostly) the same.
878 Two minor differences remain.
880 The \fB\%@TSET@\fP program waits one second when resetting,
881 in case the terminal happens to be a hardware device.
883 The two programs write the terminal initialization strings
884 to different streams;
886 standard error for \fB\%@TSET@\fP and
887 standard output for \fB\%@TPUT@\fP.
891 Initialize the terminal according to the type of
894 environment variable.
895 If the system does not reliably initialize the terminal upon login,
896 this command can be included in
900 environment variable.
902 .B "@TPUT@ \-T5620 reset"
903 Reset an AT&T 5620 terminal,
904 overriding the terminal type in the
906 environment variable.
909 Set cursor to normal visibility.
912 Move the cursor to row 0,
914 the upper left corner of the screen,
915 usually known as the \*(``home\*('' cursor position.
921 capability's value to the standard output stream.
924 Report the number of columns used by the current terminal type.
926 .B "@TPUT@ \-Tadm3a cols"
927 Report the number of columns used by an ADM-3A terminal.
929 .B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
930 Set shell variables to capability values:
936 stand-out mode for the terminal.
937 One might use these to present a prompt.
941 printf "${strong}Username:${normal} "
946 Indicate via exit status whether the terminal is a hard copy device.
949 Move the cursor to row 23,
953 Report the value of the
957 (used for cursor movement),
958 with no parameters substituted.
963 database's description of the terminal type specified in the
965 environment variable.
968 Process multiple capabilities.
971 option can be profitably used with a shell \*(``here document\*(''.
974 .RB $\ "@TPUT@ \-S <<!"
983 moves the cursor to position
989 .B "@TPUT@ clear cup 10 10 bold"
990 Perform the same actions as the foregoing
991 .RB \%\*(`` "@TPUT@ \-S" \*(''
998 \fB\%curs_termcap\fP(3X),