tput
Section: User commands (1)
Updated: 202-1-11
Index
Return to Main Contents
NAME
tput -
initialize a terminal, exercise its capabilities, or query
terminfo database
SYNOPSIS
tput [
-v] [
-T termina-type]
{
ca-code [
parameter ...]} ...
tput [-v] [-T termina-type] [-x] clear
tput [-v] [-T termina-type] init
tput [-v] [-T termina-type] reset
tput [-v] [-T termina-type] longname
tput [-v] -S
tput [-v] -V
DESCRIPTION
tput
uses the
terminfo
library and database to make termina-specific capabilities and
information available to the shell,
to initialize or reset the terminal,
or
to report a description of the current
(or specified)
terminal type.
Terminal capabilities are accessed by
ca-code.
terminfo(5) discusses terminal capabilities at length
and presents a complete list of standardized
ca-codes.
user_caps(5) presents other widely used
but no-standard capabilities.
When retrieving capability values,
the result depends upon the capability's type.
- Boolean
-
tput
sets its exit status to
0
if the terminal possesses
ca-code,
and
1
if it does not.
- numeric
-
tput
writes
ca-code's
decimal value to the standard output stream if defined
(-1
if it is not)
followed by a newline.
- string
-
tput
writes
ca-code's
value to the standard output stream if defined,
without a trailing newline.
Before using a value returned on the standard output,
the application should test
tput's
exit status
to be sure it is 0;
see section "
EXIT STATUS"
below.
Operands
Generally,
an operand is a
ca-code,
a capability code from the terminal database,
or a parameter thereto.
Three others are specially recognized by
tput:
init,
reset,
and
longname.
Although these resemble capability codes,
they in fact receive special handling;
we term them "
pseud-capabilities"
.
- ca-code
-
indicates a capability from the terminal database.
-
If
ca-code
is of string type and takes parameters,
tput
interprets arguments following
ca-code
as the parameters,
up to the (fixed) quantity the capability requires.
-
Most parameters are numeric.
Only a few terminal capabilities require string parameters;
tput
uses a table to decide which to pass as strings.
Normally
tput
uses tparm(3X) to perform the
substitution.
If no parameters are given for the capability,
tput
writes the string without performing the substitution.
- init
-
initializes the terminal.
If the terminal database is present
and an entry for the user's terminal type exists,
the following occur.
-
- (1)
-
tput
retrieves the terminal's mode settings.
It successively tests the file descriptors corresponding to
-
.IP * 4
the standard error stream,
.IP * 4
the standard output stream,
.IP * 4
the standard input stream,
and
.IP * 4
/dev/tty
-
to obtain terminal settings.
Having retrieved them,
tput
remembers which descriptor to use for further updates.
- (2)
-
If the terminal dimensions cannot be obtained from the operating system,
but the environment or terminal type database entry describes them,
tput
updates the operating system's notion of them.
- (3)
-
tput
updates the terminal modes.
-
.IP * 4
Tab expansion is turned on or off per the specification in the entry,
and
.IP * 4
if tabs are not expanded,
standard tabs
(every 8 spaces)
are set.
- (4)
-
If initialization capabilities,
detailed in subsection "
Tabs and Initialization"
of
terminfo(5),
are present,
tput
writes them to the standard output stream.
- (5)
-
tput
flushes the standard output stream.
-
If an entry lacks the information needed for an activity above,
that activity is silently skipped.
- reset
-
r-initializes the terminal.
A reset differs from initialization in two ways.
-
- (1)
-
tput
sets the terminal modes to a "
sane"
state,
-
.IP * 4
enabling canonical ("
cooked"
) and echo modes,
.IP * 4
disabling cbreak and raw modes,
.IP * 4
enabling newline translation,
and
.IP * 4
setting any special input characters to their default values.
- (2)
-
If any reset capabilities are defined for the terminal type,
tput
writes them to the output stream.
Otherwise,
tput
uses any defined initialization capabilities.
Reset capabilities are detailed in subsection
"
Tabs and Initialization"
of terminfo(5).
- longname
-
A
terminfo
entry begins with one or more names by which an application
can refer to the entry,
before the list of terminal capabilities.
The names are separated by "
|"
characters.
X/Open Curses terms the last name the "
long name"
,
and indicates that it may include blanks.
-
tic
warns if the last name does not include blanks,
to accommodate old
terminfo
entries that treated the long name as an optional feature.
The long name is often referred to as the description field.
-
If the terminal database is present and an entry for the user's terminal
type exists,
tput
reports its description to the standard output stream,
without a trailing newline.
See terminfo(5).
Note:
Redirecting the output of
"
tput init
"
or
"
tput reset
"
to a file will capture only part of their actions.
Changes to the terminal modes are not affected by file descriptor
redirection,
since the terminal modes are altered via ioctl(2).
Aliases
If
tput
is invoked via link with any of the names
clear,
init,
or
reset,
it operates as if run with the corresponding (pseud-)capability
operand.
For example,
executing a link named
reset
that points to
tput
has the same effect as
"
tput reset
"
.
This feature was introduced by
ncurses
5.2 in 2000.
It is rarely used.
- clear
-
is a separate program,
which is both smaller and more frequently executed.
- init
-
has the same name as another program in widespread use.
- reset
-
is provided
by the tset(1) utility (also via a link named
reset).
Terminal Size
Besides the pseud-capabilities
(such as
init),
tput
treats the
lines
and
cols
ca-codes
specially:
it may call
setupterm(3X) to obtain the terminal size.
.IP * 4
First,
tput
attempts to obtain these capabilities from the terminal
database.
This generally fails for terminal emulators,
which lack a fixed window size and thus omit the capabilities.
.IP * 4
It then asks the operating system for the terminal's size,
which generally works,
unless the connection is via a serial line that
does not support "
NAWS"
: negotiations about window size.
.IP * 4
Finally,
it inspects the environment variables
LINES
and
COLUMNS,
which may override the terminal size.
If the
-T
option is given,
tput
ignores the environment variables by calling
use_tioctl(TRUE),
relying upon the operating system
(or,
ultimately,
the terminal database).
OPTIONS
- -S
-
retrieves more than one capability per invocation of
tput.
The capabilities must be passed to
tput
from the standard
input stream instead of from the command line
(see section "
EXAMPLES"
below).
Only one
ca-code
is allowed per line.
The
-S
option changes the meanings of the
0
and
1
exit statuses
(see section "
EXIT STATUS"
below).
-
Some capabilities use string parameters rather than numeric ones.
tput
employs a buil-in table and the presence of parameters
in its input to decide how to interpret them,
and whether to use tparm(3X).
- -T type
-
indicates the terminal's
type.
Normally this option is unnecessary,
because a default is taken from the
TERM
environment variable.
If specified,
the environment variables
LINES
and
COLUMNS
are also ignored.
- -v
-
causes
tput
to operate verbosely,
reporting warnings.
- -V
-
reports the version of
ncurses
associated with
tput,
and exits with a successful status.
- -x
-
prevents
"
tput clear
"
from attempting to clear the scrollback buffer.
EXIT STATUS
Normally,
one should interpret
tput's
exit statuses as follows.
| Status | Meaning When-S Not Specified
|
|
| 0 | Boolean or string capability present
|
| 1 | Boolean or numeric capability absent
|
| 2 | usage error or no terminal type specified
|
| 3 | unrecognized terminal type
|
| 4 | unrecognized capability code
|
| >4 | system error (4 + errno)
|
When the
-S
option is used,
some statuses change meanings.
| Status | Meaning When-S Specified
|
|
| 0 | all operands interpreted
|
| 1 | unused
|
| 4 | some operands not interpreted
|
ENVIRONMENT
tput
reads up to three environment variables
if the
-T
option is not specified.
- COLUMNS
-
specifies the width of the screen in characters.
- LINES
-
specifies the height of the screen in characters.
- TERM
-
denotes the terminal type.
Each terminal type is distinct,
though many are similar.
FILES
- /usr/share/tabset
-
tab stop initialization database
- /usr/share/terminfo
-
compiled terminal description database
PORTABILITY
Over time
ncurses
tput
has differed from that of System V in two important respects,
one now mostly historical.
.IP * 4
"
tput
ca-code"
writes to the standard output,
which need not be a terminal device.
However,
the operands that manipulate terminal modes might not use the standard
output.
-
System V
tput's
init
and
reset
operands use logic from 4.1cBSD
tset,
manipulating terminal modes.
It checks the same file descriptors
(and
/dev/tty)
for association with a terminal device as
ncurses
now does,
and if none are,
finally assumes a 1200 baud terminal.
When updating terminal modes,
it ignores errors.
-
Until
ncurses
6.1
(see section "
HISTORY"
below),
tput
did not modify terminal modes.
It now employs a scheme similar to System V,
using functions shared with
tset
(and ultimately based on 4.4BSD
tset).
If it is not able to open a terminal
(for instance,
when run by cron(1)),
tput
exits with an error status.
.IP * 4
System V
tput
assumes that the type of a
ca-code
operand is numeric if all the characters of its value are decimal
numbers;
if they are not,
it treats
ca-code
as a string capability.
-
Most implementations that provide support for
ca-code
operands use the tparm(3X) function to expand its parameters.
That function expects a mixture of numeric and string parameters,
requiring
tput
to know which type to use.
-
ncurses
tput
uses a table to determine the parameter types for
the standard
ca-code
operands,
and an internal function to analyze nonstandard
ca-code
operands.
-
While more reliable than System V'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
tput
to
terminfo,
and modified it to interpret multiple
ca-codes
(and parameters)
on the command line.
Portable applications should not rely upon this feature;
ncurses
offers it to support applications written specifically for OpenBSD.
ncurses's
implementation of
tput,
unlike others,
accepts both
termcap
and
terminfo
ca-codes
if
termcap
support is compiled in.
In that case,
however,
termcap
and
terminfo
codes have two
ambiguities;
ncurses
assumes the
terminfo
code.
.IP * 4
The
ca-code
dl
means
delete_line
to
termcap
but
parm_delete_line
to
terminfo.
termcap
uses the code
DL
for
parm_delete_line.
terminfo
uses the code
dl1
for
delete_line.
.IP * 4
The
ca-code
ed
means
exit_delete_mode
to
termcap
but
clr_eos
to
terminfo.
termcap
uses the code
cd
for
clr_eos.
terminfo
uses the code
rmdc
for
exit_delete_mode.
The
longname
operand,
-S
option,
and the paramete-substitution features used in the
cup
example below,
were not supported in
AT&T/USL
curses
before SVr4 (1989).
Later,
4.3BS-Reno (1990) added support for
longname,
and in 1994,
NetBSD added support for the paramete-substitution features.
IEEE Std 1003.1/The Open Group Base Specifications Issue 7
(POSIX.-2008)
documents only the
clear,
init,
and
reset
operands.
A few observations of interest arise from that selection.
.IP * 4
ncurses
supports
clear
as it does any other standard
ca-code.
The others
(init
and
longname)
do not correspond to terminal capabilities.
.IP * 4
The
tput
on SVr-based systems such as Solaris,
IRIX64,
and H-UX,
as well as others such as AIX and Tru64,
also support standard
ca-code
operands.
.IP * 4
A few platforms such as FreeBSD recognize
termcap
codes rather than
terminfo
capability codes in their respective
tput
commands.
Since 2010,
NetBSD's
tput
uses
terminfo
codes.
Before that,
it
(like FreeBSD)
recognized
termcap
codes.
-
Beginning in 2021,
FreeBSD uses
ncurses
tput,
configured for both
terminfo
(tested first)
and
termcap
(as a fallback).
Because (apparently) all
certified
Unix systems support the full set of capability codes,
the reason for documenting only a few may not be apparent.
.IP * 4
X/Open Curses Issue 7 documents
tput
differently,
with
ca-code
and the other features used in this implementation.
.IP * 4
That is,
there are two standards for
tput:
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 capability database.
.IP * 4
While it is certainly possible to write a
tput
program without using
curses,
no system with a
curses
implementation provides a
tput
utility that does not also support standard
ca-codes.
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
(that is,
System V
curses
behavior).
.IP * 4
It assigns exit status 4 to "
invalid operand"
,
which may have the same meaning as "
unknown capability"
.
For instance,
the source code for
Solaris
xcurses
uses the term "
invalid"
in this case.
.IP * 4
It assigns exit status 255 to a numeric variable that is not specified
in the
terminfo
database.
That likely is a documentation error,
mistaking the "
-1"
written to the standard output to indicate
an absent or canceled numeric capability for an (unsigned) exit status.
The various System V implementations
(AIX,
H-UX,
Solaris)
use the same exit statuses as
ncurses.
NetBSD
curses
documents exit statuses that correspond to neither
ncurses
nor X/Open Curses.
HISTORY
Bill Joy wrote a
tput
command during development of 4BSD in October 1980.
This initial version only cleared the screen,
and did not ship with official distributions.
System V developed a different
tput
command.
.IP * 4
SVr2 (1984) provided a rudimentary
tput
that checked the parameter against each
capability name and returned the corresponding value.
This version of
tput
did not use tparm(3X) for parameterized capabilities.
.IP * 4
SVr3 (1987) replaced that
with a more extensive program
whose support for
init
and
reset
operands
(more than half the program)
incorporated the
reset
feature of BSD
tset
written by Eric Allman.
.IP * 4
SVr4 (1989) added color initialization by using the
orig_colors
(oc)
and
orig_pair
(op)
capabilities in its
init
logic.
Keith Bostic refactored BSD
tput
for shipment in 4.3BS-Reno (1990),
making it follow the interface of System V
tput
by accepting some parameters named for
terminfo
(pseud-)capabilities:
clear,
init,
longname,
and
reset.
However,
because he had only
termcap
available,
it accepted
termcap
codes for other capabilities.
Also,
Bostic's BSD
tput
did not modify the terminal modes as the earlier BSD
tset
had done.
At the same time,
Bostic added a shell script named "
clear"
that used
tput
to clear the screen.
These became the "
modern"
BSD implementation of
tput.
The origin of
ncurses
tput
lies outside both System V and BSD,
in Ross Ridge's
mytinfo
package,
published on
comp.sources.unix
in December 1992.
Ridge's program made more sophisticated use of the terminal capabilities
than the BSD program.
Eric Raymond used that
tput
program
(and other parts of
mytinfo)
in
ncurses
in June 1995.
Incorporating the portions dealing with terminal capabilities
almost without change,
Raymond made improvements to the way comman-line parameters
were handled.
Before
ncurses
6.1 (2018),
its
tset
and
tput
utilities differed.
.IP * 4
tset
was more effective,
resetting the terminal's modes and special input characters.
.IP * 4
On the other hand,
tset's
repertoire of terminal capabilities for resetting the
terminal was more limited;
it had only equivalents of
reset_1string
(rs1),
reset_2string
(rs2),
and
reset_file
(rf),
and not the tab stop and margin update features of
tput.
The
reset
program is traditionally an alias for
tset
due to its ability
to reset the terminal's modes and special input characters.
As of
ncurses
6.1,
the "
reset"
features of the two programs are (mostly) the same.
Two minor differences remain.
.IP * 4
When issuing a reset,
the
tset
program
checks whether the device appears to be a pseudoterminal
(as might be used by a terminal emulator program),
and,
if it does not,
waits one second in case it is communicating with a hardware terminal.
.IP * 4
The two programs write the terminal initialization strings
to different streams;
that is,
standard error for
tset
and
standard output for
tput.
EXAMPLES
- tput init
-
Initialize the terminal according to the type of
terminal in the
TERM
environment variable.
If the system does not reliably initialize the terminal upon login,
this command can be included in
$HOME/.profile
after exporting the
TERM
environment variable.
- tput -T5620 reset
-
Reset an AT&T 5620 terminal,
overriding the terminal type in the
TERM
environment variable.
- tput cnorm
-
Set cursor to normal visibility.
- tput home
-
Move the cursor to line 0,
column 0:
the upper left corner of the screen,
usually known as the "
home"
cursor position.
- tput clear
-
Clear the screen:
write the
clear_screen
capability's value to the standard output stream.
- tput cols
-
Report the number of columns used by the current terminal type.
- tput -Tadm3a cols
-
Report the number of columns used by an AD-3A terminal.
- strong=`tput smso` normal=`tput rmso`
-
Set shell variables to capability values:
strong
and
normal,
to begin and end,
respectively,
stan-out mode for the terminal.
One might use these to present a prompt.
-
-
printf "${strong}Username:${normal} "
- tput hc
-
Indicate via exit status whether the terminal is a hard copy device.
- tput cup 23 4
-
Move the cursor to line 23,
column 4.
- tput cup
-
Report the value of the
cursor_address
(cup)
capability
(used for cursor movement),
with no parameters substituted.
- tput longname
-
Report the
terminfo
database's description of the terminal type specified in the
TERM
environment variable.
- tput -S
-
Process multiple capabilities.
The
-S
option can be profitably used with a shell "
here document"
.
-
$ tput -S <<!
> clear
> cup 10 10
> bold
> !
-
The foregoing
clears the screen,
moves the cursor to position
(10, 10)
and turns on bold
(extra bright)
mode.
- tput clear cup 10 10 bold
-
Perform the same actions as the foregoing
"
tput -S
"
example.
SEE ALSO
clear(1),
stty(1),
tabs(1),
tset(1),
curs_termcap(3X),
terminfo(5),
user_caps(5)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Operands
-
- Aliases
-
- Terminal Size
-
- OPTIONS
-
- EXIT STATUS
-
- ENVIRONMENT
-
- FILES
-
- PORTABILITY
-
- HISTORY
-
- EXAMPLES
-
- SEE ALSO
-
|
|
- Running on 
-
:
