tput(1) User commands tput(1) #
tput(1) User commands tput(1)
NNAAMMEE #
ttppuutt, rreesseett - initialize a terminal or query terminfo database
SSYYNNOOPPSSIISS #
ttppuutt [--TT_t_y_p_e] _c_a_p_n_a_m_e [_p_a_r_a_m_e_t_e_r_s]
ttppuutt [--TT_t_y_p_e] [--xx] cclleeaarr
ttppuutt [--TT_t_y_p_e] iinniitt
ttppuutt [--TT_t_y_p_e] rreesseett
ttppuutt [--TT_t_y_p_e] lloonnggnnaammee
ttppuutt --SS <<<<
ttppuutt --VV
DDEESSCCRRIIPPTTIIOONN #
The ttppuutt utility uses the tteerrmmiinnffoo database to make the values of
terminal-dependent capabilities and information available to the shell
(see sshh(1)), to initialize or reset the terminal, or return the long name
of the requested terminal type. The result depends upon the capability's
type:
string
ttppuutt writes the string to the standard output. No trailing
newline is supplied.
integer
ttppuutt writes the decimal value to the standard output, with a
trailing newline.
boolean
ttppuutt simply sets the exit code (00 for TRUE if the terminal has
the capability, 11 for FALSE if it does not), and writes nothing
to the standard output.
Before using a value returned on the standard output, the application
should test the exit code (e.g., $$??, see sshh(1)) to be sure it is 00. (See
the EEXXIITT CCOODDEESS and DDIIAAGGNNOOSSTTIICCSS sections.) For a complete list of
capabilities and the _c_a_p_n_a_m_e associated with each, see tteerrmmiinnffoo(5).
OOppttiioonnss --SS allows more than one capability per invocation of ttppuutt. The capabilities must be passed to ttppuutt from the standard input instead of from the command line (see example). Only one _c_a_p_n_a_m_e is allowed per line. The --SS option changes the meaning of the 00 and 11 boolean and string exit codes (see the EXIT CODES section).
Because some capabilities may use _s_t_r_i_n_g parameters rather than
_n_u_m_b_e_r_s, ttppuutt uses a table and the presence of parameters in its
input to decide whether to use ttppaarrmm(3), and how to interpret the
parameters.
--TT_t_y_p_e indicates the _t_y_p_e of terminal. Normally this option is
unnecessary, because the default is taken from the environment
variable TTEERRMM. If --TT is specified, then the shell variables LLIINNEESS
and CCOOLLUUMMNNSS will also be ignored.
--VV reports the version of ncurses which was used in this program, and
exits.
--xx do not attempt to clear the terminal's scrollback buffer using the
extended “E3” capability.
CCoommmmaannddss A few commands (iinniitt, rreesseett and lloonnggnnaammee) are special; they are defined by the ttppuutt program. The others are the names of _c_a_p_a_b_i_l_i_t_i_e_s from the terminal database (see tteerrmmiinnffoo(5) for a list). Although iinniitt and rreesseett resemble capability names, ttppuutt uses several capabilities to perform these special functions.
_c_a_p_n_a_m_e
indicates the capability from the terminal database.
If the capability is a string that takes parameters, the arguments
following the capability will be used as parameters for the
string.
Most parameters are numbers. Only a few terminal capabilities
require string parameters; ttppuutt uses a table to decide which to
pass as strings. Normally ttppuutt uses ttppaarrmm(3) to perform the
substitution. If no parameters are given for the capability, ttppuutt
writes the string without performing the substitution.
iinniitt If the terminal database is present and an entry for the user's
terminal exists (see --TT_t_y_p_e, above), the following will occur:
(1) first, ttppuutt retrieves the current terminal mode settings for
your terminal. It does this by successively testing
• the standard error,
• standard output,
• standard input and
• ultimately “/dev/tty”
to obtain terminal settings. Having retrieved these
settings, ttppuutt remembers which file descriptor to use when
updating settings.
(2) if the window size cannot be obtained from the operating
system, but the terminal description (or environment, e.g.,
LLIINNEESS and CCOOLLUUMMNNSS variables specify this), update the
operating system's notion of the window size.
(3) the terminal modes will be updated:
• any delays (e.g., newline) specified in the entry will be
set in the tty driver,
• tabs expansion will be turned on or off according to the
specification in the entry, and
• if tabs are not expanded, standard tabs will be set
(every 8 spaces).
(4) if present, the terminal's initialization strings will be
output as detailed in the tteerrmmiinnffoo(5) section on _T_a_b_s _a_n_d
_I_n_i_t_i_a_l_i_z_a_t_i_o_n,
(5) output is flushed.
If an entry does not contain the information needed for any of
these activities, that activity will silently be skipped.
rreesseett This is similar to iinniitt, with two differences:
(1) before any other initialization, the terminal modes will be
reset to a “sane” state:
• set cooked and echo modes,
• turn off cbreak and raw modes,
• turn on newline translation and
• reset any unset special characters to their default
values
(2) Instead of putting out _i_n_i_t_i_a_l_i_z_a_t_i_o_n strings, the terminal's
_r_e_s_e_t strings will be output if present (rrss11, rrss22, rrss33, rrff).
If the _r_e_s_e_t strings are not present, but _i_n_i_t_i_a_l_i_z_a_t_i_o_n
strings are, the _i_n_i_t_i_a_l_i_z_a_t_i_o_n strings will be output.
Otherwise, rreesseett acts identically to iinniitt.
lloonnggnnaammee
If the terminal database is present and an entry for the user's
terminal exists (see --TT_t_y_p_e above), then the long name of the
terminal will be put out. The long name is the last name in the
first line of the terminal's description in the tteerrmmiinnffoo database
[see tteerrmm(5)].
AAlliiaasseess ttppuutt handles the cclleeaarr, iinniitt and rreesseett commands specially: it allows for the possibility that it is invoked by a link with those names.
If ttppuutt is invoked by a link named rreesseett, this has the same effect as
ttppuutt rreesseett. The ttsseett(1) utility also treats a link named rreesseett
specially.
Before ncurses 6.1, the two utilities were different from each other:
• ttsseett utility reset the terminal modes and special characters (not
done with ttppuutt).
• On the other hand, ttsseett's repertoire of terminal capabilities for
resetting the terminal was more limited, i.e., only rreesseett__11ssttrriinngg,
rreesseett__22ssttrriinngg and rreesseett__ffiillee in contrast to the tab-stops and margins
which are set by this utility.
• The rreesseett program is usually an alias for ttsseett, because of this
difference with resetting terminal modes and special characters.
With the changes made for ncurses 6.1, the _r_e_s_e_t feature of the two
programs is (mostly) the same. A few differences remain:
• The ttsseett program waits one second when resetting, in case it happens
to be a hardware terminal.
• The two programs write the terminal initialization strings to
different streams (i.e., the standard error for ttsseett and the standard
output for ttppuutt).
NNoottee:: although these programs write to different streams, redirecting
their output to a file will capture only part of their actions. The
changes to the terminal modes are not affected by redirecting the
output.
If ttppuutt is invoked by a link named iinniitt, this has the same effect as ttppuutt
iinniitt. Again, you are less likely to use that link because another
program named iinniitt has a more well-established use.
TTeerrmmiinnaall SSiizzee Besides the special commands (e.g., cclleeaarr), tput treats certain terminfo capabilities specially: lliinneess and ccoollss. tput calls sseettuupptteerrmm(3) to obtain the terminal size:
• first, it gets the size from the terminal database (which generally
is not provided for terminal emulators which do not have a fixed
window size)
• then it asks the operating system for the terminal's size (which
generally works, unless connecting via a serial line which does not
support _N_A_W_S: negotiations about window size).
• finally, it inspects the environment variables LLIINNEESS and CCOOLLUUMMNNSS
which may override the terminal size.
If the --TT option is given tput ignores the environment variables by
calling uussee__ttiiooccttll((TTRRUUEE)), relying upon the operating system (or finally,
the terminal database).
EEXXAAMMPPLLEESS #
ttppuutt iinniitt
Initialize the terminal according to the type of terminal in the
environmental variable TTEERRMM. This command should be included in
everyone's .profile after the environmental variable TTEERRMM has been
exported, as illustrated on the pprrooffiillee(5) manual page.
ttppuutt --TT55662200 rreesseett
Reset an AT&T 5620 terminal, overriding the type of terminal in the
environmental variable TTEERRMM.
ttppuutt ccuupp 00 00
Send the sequence to move the cursor to row 00, column 00 (the upper
left corner of the screen, usually known as the “home” cursor
position).
ttppuutt cclleeaarr
Echo the clear-screen sequence for the current terminal.
ttppuutt ccoollss
Print the number of columns for the current terminal.
ttppuutt --TT445500 ccoollss
Print the number of columns for the 450 terminal.
bboolldd==``ttppuutt ssmmssoo`` ooffffbboolldd==``ttppuutt rrmmssoo``
Set the shell variables bboolldd, to begin stand-out mode sequence, and
ooffffbboolldd, to end standout mode sequence, for the current terminal.
This might be followed by a prompt: eecchhoo ""$${{bboolldd}}PPlleeaassee ttyyppee iinn yyoouurr
nnaammee:: $${{ooffffbboolldd}}\\cc""
ttppuutt hhcc
Set exit code to indicate if the current terminal is a hard copy
terminal.
ttppuutt ccuupp 2233 44
Send the sequence to move the cursor to row 23, column 4.
ttppuutt ccuupp
Send the terminfo string for cursor-movement, with no parameters
substituted.
ttppuutt lloonnggnnaammee
Print the long name from the tteerrmmiinnffoo database for the type of
terminal specified in the environmental variable TTEERRMM.
ttppuutt --SS <<<<!!
>> cclleeaarr
>> ccuupp 1100 1100
>> bboolldd
>> !!
This example shows ttppuutt processing several capabilities in one
invocation. It clears the screen, moves the cursor to position 10,
10 and turns on bold (extra bright) mode. The list is terminated by
an exclamation mark (!!) on a line by itself.
FFIILLEESS #
//uussrr//sshhaarree//tteerrmmiinnffoo
compiled terminal description database
//uussrr//sshhaarree//ttaabbsseett//**
tab settings for some terminals, in a format appropriate to be
output to the terminal (escape sequences that set margins and
tabs); for more information, see the _T_a_b_s _a_n_d _I_n_i_t_i_a_l_i_z_a_t_i_o_n,
section of tteerrmmiinnffoo(5)
EEXXIITT CCOODDEESS #
If the --SS option is used, ttppuutt checks for errors from each line, and if
any errors are found, will set the exit code to 4 plus the number of
lines with errors. If no errors are found, the exit code is 00. No
indication of which line failed can be given so exit code 11 will never
appear. Exit codes 22, 33, and 44 retain their usual interpretation. If
the --SS option is not used, the exit code depends on the type of _c_a_p_n_a_m_e:
_b_o_o_l_e_a_n
a value of 00 is set for TRUE and 11 for FALSE.
_s_t_r_i_n_g a value of 00 is set if the _c_a_p_n_a_m_e is defined for this terminal
_t_y_p_e (the value of _c_a_p_n_a_m_e is returned on standard output); a
value of 11 is set if _c_a_p_n_a_m_e is not defined for this terminal
_t_y_p_e (nothing is written to standard output).
_i_n_t_e_g_e_r
a value of 00 is always set, whether or not _c_a_p_n_a_m_e is defined
for this terminal _t_y_p_e. To determine if _c_a_p_n_a_m_e is defined for
this terminal _t_y_p_e, the user must test the value written to
standard output. A value of --11 means that _c_a_p_n_a_m_e is not
defined for this terminal _t_y_p_e.
_o_t_h_e_r rreesseett or iinniitt may fail to find their respective files. In that
case, the exit code is set to 4 + eerrrrnnoo.
Any other exit code indicates an error; see the DIAGNOSTICS section.
DDIIAAGGNNOOSSTTIICCSS #
ttppuutt prints the following error messages and sets the corresponding exit
codes.
exit code error message
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
00 (_c_a_p_n_a_m_e is a numeric variable that is not specified in
the tteerrmmiinnffoo(5) database for this terminal type, e.g.
ttppuutt --TT445500 lliinneess and ttppuutt --TThhpp22662211 xxmmcc)
11 no error message is printed, see the EEXXIITT CCOODDEESS section.
22 usage error
33 unknown terminal _t_y_p_e or no tteerrmmiinnffoo database
44 unknown tteerrmmiinnffoo capability _c_a_p_n_a_m_e
>>44 error occurred in -S
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HHIISSTTOORRYY #
The ttppuutt command was begun by Bill Joy in 1980. The initial version only
cleared the screen.
AT&T System V provided a different ttppuutt command:
• SVr2 provided a rudimentary ttppuutt which checked the parameter against
each predefined capability and returned the corresponding value.
This version of ttppuutt did not use ttppaarrmm(3) for the capabilities which
are parameterized.
• SVr3 replaced that, a year later, by a more extensive program whose
iinniitt and rreesseett subcommands (more than half the program) were
incorporated from the rreesseett feature of BSD ttsseett written by Eric
Allman.
• SVr4 added color initialization using the oorriigg__ccoolloorrss and oorriigg__ppaaiirr
capabilities in the iinniitt subcommand.
Keith Bostic replaced the BSD ttppuutt command in 1989 with a new
implementation based on the AT&T System V program ttppuutt. Like the AT&T
program, Bostic's version accepted some parameters named for _t_e_r_m_i_n_f_o
capabilities (cclleeaarr, iinniitt, lloonnggnnaammee and rreesseett). However (because he had
only _t_e_r_m_c_a_p available), it accepted _t_e_r_m_c_a_p names for other
capabilities. Also, Bostic's BSD ttppuutt did not modify the terminal I/O
modes as the earlier BSD ttsseett had done.
At the same time, Bostic added a shell script named “clear”, which used
ttppuutt to clear the screen.
Both of these appeared in 4.4BSD, becoming the “modern” BSD
implementation of ttppuutt.
This implementation of ttppuutt began from a different source than AT&T or
BSD: Ross Ridge's _m_y_t_i_n_f_o package, published on _c_o_m_p_._s_o_u_r_c_e_s_._u_n_i_x in
December 1992. Ridge's program made more sophisticated use of the
terminal capabilities than the BSD program. Eric Raymond used that ttppuutt
program (and other parts of _m_y_t_i_n_f_o) in ncurses in June 1995. Using the
portions dealing with terminal capabilities almost without change,
Raymond made improvements to the way the command-line parameters were
handled.
PPOORRTTAABBIILLIITTYY #
This implementation of ttppuutt differs from AT&T ttppuutt in two important
areas:
• ttppuutt _c_a_p_n_a_m_e writes to the standard output. That need not be a
regular terminal. However, the subcommands which manipulate terminal
modes may not use the standard output.
The AT&T implementation's iinniitt and rreesseett commands use the BSD (4.1c)
ttsseett source, which manipulates terminal modes. It successively tries
standard output, standard error, standard input before falling back
to “/dev/tty” and finally just assumes a 1200Bd terminal. When
updating terminal modes, it ignores errors.
Until changes made after ncurses 6.0, ttppuutt did not modify terminal
modes. ttppuutt now uses a similar scheme, using functions shared with
ttsseett (and ultimately based on the 4.4BSD ttsseett). If it is not able to
open a terminal, e.g., when running in ccrroonn(1), ttppuutt will return an
error.
• AT&T ttppuutt guesses the type of its _c_a_p_n_a_m_e operands by seeing if all
of the characters are numeric, or not.
Most implementations which provide support for _c_a_p_n_a_m_e operands use
the ttppaarrmm function to expand parameters in it. That function expects
a mixture of numeric and string parameters, requiring ttppuutt to know
which type to use.
This implementation uses a table to determine the parameter types for
the standard _c_a_p_n_a_m_e operands, and an internal library function to
analyze nonstandard _c_a_p_n_a_m_e operands.
Besides providing more reliable operation than AT&T's utility, a
portability problem is introduced by this analysis: An OpenBSD
developer adapted the internal library function from ncurses to port
NetBSD's termcap-based ttppuutt to terminfo. That had been modified to
interpret multiple commands on a line. Portable applications should
not rely upon this feature; ncurses provides it to support
applications written specifically for OpenBSD.
This implementation (unlike others) can accept both _t_e_r_m_c_a_p and _t_e_r_m_i_n_f_o
names for the _c_a_p_n_a_m_e feature, if _t_e_r_m_c_a_p support is compiled in.
However, the predefined _t_e_r_m_c_a_p and _t_e_r_m_i_n_f_o names have two ambiguities
in this case (and the _t_e_r_m_i_n_f_o name is assumed):
• The _t_e_r_m_c_a_p name ddll corresponds to the _t_e_r_m_i_n_f_o name ddll11 (delete one
line).
The _t_e_r_m_i_n_f_o name ddll corresponds to the _t_e_r_m_c_a_p name DDLL (delete a
given number of lines).
• The _t_e_r_m_c_a_p name eedd corresponds to the _t_e_r_m_i_n_f_o name rrmmddcc (end delete
mode).
The _t_e_r_m_i_n_f_o name eedd corresponds to the _t_e_r_m_c_a_p name ccdd (clear to end
of screen).
The lloonnggnnaammee and --SS options, and the parameter-substitution features used
in the ccuupp example, were not supported in BSD curses before 4.3reno
(1989) or in AT&T/USL curses before SVr4 (1988).
IEEE Std 1003.1/The Open Group Base Specifications Issue 7
(POSIX.1-2008) documents only the operands for cclleeaarr, iinniitt and rreesseett.
There are a few interesting observations to make regarding that:
• In this implementation, cclleeaarr is part of the _c_a_p_n_a_m_e support. The
others (iinniitt and lloonnggnnaammee) do not correspond to terminal
capabilities.
• Other implementations of ttppuutt on SVr4-based systems such as Solaris,
IRIX64 and HPUX as well as others such as AIX and Tru64 provide
support for _c_a_p_n_a_m_e operands.
• A few platforms such as FreeBSD recognize termcap names rather than
terminfo capability names in their respective ttppuutt commands. Since
2010, NetBSD's ttppuutt uses terminfo names. Before that, it (like
FreeBSD) recognized termcap names.
Beginning in 2021, FreeBSD uses the ncurses ttppuutt, configured for both
terminfo (tested first) and termcap (as a fallback).
Because (apparently) _a_l_l of the certified Unix systems support the full
set of capability names, the reasoning for documenting only a few may not
be apparent.
• X/Open Curses Issue 7 documents ttppuutt differently, with _c_a_p_n_a_m_e and
the other features used in this implementation.
• That is, there are two standards for ttppuutt: POSIX (a subset) and
X/Open Curses (the full implementation). POSIX documents a subset to
avoid the complication of including X/Open Curses and the terminal
capabilities database.
• While it is certainly possible to write a ttppuutt program without using
curses, none of the systems which have a curses implementation
provide a ttppuutt utility which does not provide the _c_a_p_n_a_m_e feature.
X/Open Curses Issue 7 (2009) is the first version to document utilities.
However that part of X/Open Curses does not follow existing practice
(i.e., Unix features documented in SVID 3):
• It assigns exit code 4 to “invalid operand”, which may be the same as
_u_n_k_n_o_w_n _c_a_p_a_b_i_l_i_t_y. For instance, the source code for Solaris'
xcurses uses the term “invalid” in this case.
• It assigns exit code 255 to a numeric variable that is not specified
in the terminfo database. That likely is a documentation error,
confusing the --11 written to the standard output for an absent or
cancelled numeric value versus an (unsigned) exit code.
The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes as
ncurses.
NetBSD curses documents different exit codes which do not correspond to
either ncurses or X/Open.
SSEEEE AALLSSOO #
??(1), ssttttyy(1), ??(1), ttsseett(1), tteerrmmccaapp(3), tteerrmmiinnffoo(5).
This describes nnccuurrsseess version 6.4 (patch 20230826).
ncurses 6.4 2023-07-01 tput(1)