- The tput utility uses the terminfo database to make the values of ter-
- minal-dependent capabilities and information available to the shell
+ The tput utility uses the terminfo database to make the values of
+ terminal-dependent capabilities and information available to the shell
(see sh(1)), to initialize or reset the terminal, or return the long
- name of the requested terminal type. The result depends upon the capa-
- bility's type:
+ name of the requested terminal type. The result depends upon the
+ capability's type:
string
tput writes the string to the standard output. No trailing
@@ -89,9 +90,9 @@
-S allows more than one capability per invocation of tput. The
capabilities must be passed to tput from the standard input
- instead of from the command line (see example). Only one cap-
- name is allowed per line. The -S option changes the meaning of
- the 0 and 1 boolean and string exit codes (see the EXIT CODES
+ instead of from the command line (see example). Only one
+ capname is allowed per line. The -S option changes the meaning
+ of the 0 and 1 boolean and string exit codes (see the EXIT CODES
section).
Because some capabilities may use string parameters rather than
@@ -99,10 +100,10 @@
input to decide whether to use tparm(3x), and how to interpret
the parameters.
- -Ttype indicates the type of terminal. Normally this option is unnec-
- essary, because the default is taken from the environment vari-
- able TERM. If -T is specified, then the shell variables LINES
- and COLUMNS will also be ignored.
+ -Ttype indicates the type of terminal. Normally this option is
+ unnecessary, because the default is taken from the environment
+ variable TERM. If -T is specified, then the shell variables
+ LINES and COLUMNS will also be ignored.
-V reports the version of ncurses which was used in this program,
and exits.
@@ -115,15 +116,15 @@
A few commands (init, reset and longname) are special; they are defined
by the tput program. The others are the names of capabilities from the
terminal database (see terminfo(5) for a list). Although init and
- reset resemble capability names, tput uses several capabilities to per-
- form these special functions.
+ reset resemble capability names, tput uses several capabilities to
+ perform these special functions.
capname
indicates the capability from the terminal database.
- If the capability is a string that takes parameters, the argu-
- ments following the capability will be used as parameters for
- the string.
+ 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; tput uses a table to decide which to
@@ -145,14 +146,14 @@
o ultimately "/dev/tty"
- to obtain terminal settings. Having retrieved these set-
- tings, tput remembers which file descriptor to use when
+ to obtain terminal settings. Having retrieved these
+ settings, tput 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.,
- LINES and COLUMNS variables specify this), update the oper-
- ating system's notion of the window size.
+ LINES and COLUMNS variables specify this), update the
+ operating system's notion of the window size.
(3) the terminal modes will be updated:
@@ -188,11 +189,11 @@
o reset any unset special characters to their default
values
- (2) Instead of putting out initialization strings, the termi-
- nal's reset strings will be output if present (rs1, rs2,
- rs3, rf). If the reset strings are not present, but ini-
- tialization strings are, the initialization strings will be
- output.
+ (2) Instead of putting out initialization strings, the
+ terminal's reset strings will be output if present (rs1,
+ rs2, rs3, rf). If the reset strings are not present, but
+ initialization strings are, the initialization strings will
+ be output.
Otherwise, reset acts identically to init.
@@ -200,8 +201,8 @@
If the terminal database is present and an entry for the user's
terminal exists (see -Ttype 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 terminfo data-
- base [see term(5)].
+ first line of the terminal's description in the terminfo
+ database [see term(5)].
@@ -209,8 +210,8 @@
for the possibility that it is invoked by a link with those names.
If tput is invoked by a link named reset, this has the same effect as
- tputreset. The tset(1) utility also treats a link named reset spe-
- cially.
+ tputreset. The tset(1) utility also treats a link named reset
+ specially.
Before ncurses 6.1, the two utilities were different from each other:
@@ -219,8 +220,8 @@
o On the other hand, tset's repertoire of terminal capabilities for
resetting the terminal was more limited, i.e., only reset_1string,
- reset_2string and reset_file in contrast to the tab-stops and mar-
- gins which are set by this utility.
+ reset_2string and reset_file in contrast to the tab-stops and
+ margins which are set by this utility.
o The reset program is usually an alias for tset, because of this
difference with resetting terminal modes and special characters.
@@ -228,37 +229,58 @@
With the changes made for ncurses 6.1, the reset feature of the two
programs is (mostly) the same. A few differences remain:
- o The tset program waits one second when resetting, in case it hap-
- pens to be a hardware terminal.
+ o The tset program waits one second when resetting, in case it
+ happens to be a hardware terminal.
- o The two programs write the terminal initialization strings to dif-
- ferent streams (i.e.,. the standard error for tset and the standard
- output for tput).
+ o The two programs write the terminal initialization strings to
+ different streams (i.e., the standard error for tset and the
+ standard output for tput).
- Note: although these programs write to different streams, redirect-
- ing 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.
+ Note: 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 tput is invoked by a link named init, this has the same effect as
tputinit. Again, you are less likely to use that link because another
program named init has a more well-established use.
+
+ Besides the special commands (e.g., clear), tput treats certain
+ terminfo capabilities specially: lines and cols. tput calls
+ setupterm(3x) to obtain the terminal size:
+
+ o 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)
+
+ o then it asks the operating system for the terminal's size (which
+ generally works, unless connecting via a serial line which does not
+ support NAWS: negotiations about window size).
+
+ o 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
+ finally, the terminal database).
+
+
tputinit
- Initialize the terminal according to the type of terminal in the
- environmental variable TERM. This command should be included in
+ Initialize the terminal according to the type of terminal in the
+ environmental variable TERM. This command should be included in
everyone's .profile after the environmental variable TERM has been
exported, as illustrated on the profile(5) manual page.
tput-T5620reset
- Reset an AT&T 5620 terminal, overriding the type of terminal in
+ Reset an AT&T 5620 terminal, overriding the type of terminal in
the environmental variable TERM.
tputcup00
Send the sequence to move the cursor to row 0, column 0 (the upper
- left corner of the screen, usually known as the "home" cursor
+ left corner of the screen, usually known as the "home" cursor
position).
tputclear
@@ -271,24 +293,24 @@
Print the number of columns for the 450 terminal.
bold=`tputsmso`offbold=`tputrmso`
- Set the shell variables bold, to begin stand-out mode sequence,
- and offbold, to end standout mode sequence, for the current termi-
- nal. This might be followed by a prompt: echo"${bold}Pleasetype
- inyourname:${offbold}\c"
+ Set the shell variables bold, to begin stand-out mode sequence,
+ and offbold, to end standout mode sequence, for the current
+ terminal. This might be followed by a prompt: echo"${bold}Please
+ typeinyourname:${offbold}\c"tputhc
- Set exit code to indicate if the current terminal is a hard copy
+ Set exit code to indicate if the current terminal is a hard copy
terminal.
tputcup234
Send the sequence to move the cursor to row 23, column 4.
tputcup
- Send the terminfo string for cursor-movement, with no parameters
+ Send the terminfo string for cursor-movement, with no parameters
substituted.
tputlongname
- Print the long name from the terminfo database for the type of
+ Print the long name from the terminfo database for the type of
terminal specified in the environmental variable TERM.
tput-S<<!
@@ -297,10 +319,10 @@
>bold>!
- This example shows tput 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 termi-
- nated by an exclamation mark (!) on a line by itself.
+ This example shows tput 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.
@@ -308,51 +330,51 @@
compiled terminal description database
/usr/share/tabset/*
- 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 TabsandInitialization,
+ 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 TabsandInitialization,
section of terminfo(5)
If the -S option is used, tput 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 0. No
- indication of which line failed can be given so exit code 1 will never
- appear. Exit codes 2, 3, and 4 retain their usual interpretation. If
- the -S option is not used, the exit code depends on the type of cap-
- name:
+ 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 0. No
+ indication of which line failed can be given so exit code 1 will never
+ appear. Exit codes 2, 3, and 4 retain their usual interpretation. If
+ the -S option is not used, the exit code depends on the type of
+ capname:
boolean
a value of 0 is set for TRUE and 1 for FALSE.
- string a value of 0 is set if the capname is defined for this termi-
- nal type (the value of capname is returned on standard out-
- put); a value of 1 is set if capname is not defined for this
- terminal type (nothing is written to standard output).
+ string a value of 0 is set if the capname is defined for this
+ terminal type (the value of capname is returned on standard
+ output); a value of 1 is set if capname is not defined for
+ this terminal type (nothing is written to standard output).
integer
a value of 0 is always set, whether or not capname is defined
- for this terminal type. To determine if capname is defined
- for this terminal type, the user must test the value written
- to standard output. A value of -1 means that capname is not
+ for this terminal type. To determine if capname is defined
+ for this terminal type, the user must test the value written
+ to standard output. A value of -1 means that capname is not
defined for this terminal type.
- otherreset or init may fail to find their respective files. In
+ otherreset or init may fail to find their respective files. In
that case, the exit code is set to 4 + errno.
Any other exit code indicates an error; see the DIAGNOSTICS section.
- tput prints the following error messages and sets the corresponding
+ tput prints the following error messages and sets the corresponding
exit codes.
exit code error message
---------------------------------------------------------------------
- 0 (capname is a numeric variable that is not specified in
- the terminfo(5) database for this terminal type, e.g.
- tput-T450lines and tput-T2621xmc)
+ 0 (capname is a numeric variable that is not specified in
+ the terminfo(5) database for this terminal type, e.g.
+ tput-T450lines and tput-Thp2621xmc)
1 no error message is printed, see the EXITCODES section.
2 usage error
3 unknown terminal type or no terminfo database
@@ -362,35 +384,46 @@
- The tput command was begun by Bill Joy in 1980. The initial version
+ The tput command was begun by Bill Joy in 1980. The initial version
only cleared the screen.
- AT&T System V provided a different tput command, whose init and reset
- subcommands (more than half the program) were incorporated from the
- reset feature of BSD tset written by Eric Allman.
+ AT&T System V provided a different tput command:
+
+ o SVr2 provided a rudimentary tput which checked the parameter
+ against each predefined capability and returned the corresponding
+ value. This version of tput did not use tparm(3x) for the
+ capabilities which are parameterized.
+
+ o SVr3 replaced that, a year later, by a more extensive program whose
+ init and reset subcommands (more than half the program) were
+ incorporated from the reset feature of BSD tset written by Eric
+ Allman.
- Keith Bostic replaced the BSD tput command in 1989 with a new implemen-
- tation based on the AT&T System V program tput. Like the AT&T program,
- Bostic's version accepted some parameters named for terminfocapabili-
- ties (clear, init, longname and reset). However (because he had only
- termcap available), it accepted termcapnames for other capabilities.
- Also, Bostic's BSD tput did not modify the terminal I/O modes as the
- earlier BSD tset had done.
+ o SVr4 added color initialization using the orig_colors and
+ orig_pairs capabilities in the init subcommand.
+
+ Keith Bostic replaced the BSD tput command in 1989 with a new
+ implementation based on the AT&T System V program tput. Like the AT&T
+ program, Bostic's version accepted some parameters named for terminfo
+ capabilities (clear, init, longname and reset). However (because he
+ had only termcap available), it accepted termcapnames for other
+ capabilities. Also, Bostic's BSD tput did not modify the terminal I/O
+ modes as the earlier BSD tset had done.
At the same time, Bostic added a shell script named "clear", which used
tput to clear the screen.
- Both of these appeared in 4.4BSD, becoming the "modern" BSD implementa-
- tion of tput.
+ Both of these appeared in 4.4BSD, becoming the "modern" BSD
+ implementation of tput.
This implementation of tput began from a different source than AT&T or
BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in
- December 1992. Ridge's program made more sophisticated use of the ter-
- minal capabilities than the BSD program. Eric Raymond used the tput
- program (and other parts of mytinfo) 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.
+ 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.
+ Using the portions dealing with terminal capabilities almost without
+ change, Raymond made improvements to the way the command-line
+ parameters were handled.
@@ -398,14 +431,14 @@
areas:
otputcapname writes to the standard output. That need not be a
- regular terminal. However, the subcommands which manipulate termi-
- nal modes may not use the standard output.
+ regular terminal. However, the subcommands which manipulate
+ terminal modes may not use the standard output.
The AT&T implementation's init and reset commands use the BSD
- (4.1c) tset source, which manipulates terminal modes. It succes-
- sively tries standard output, standard error, standard input before
- falling back to "/dev/tty" and finally just assumes a 1200Bd termi-
- nal. When updating terminal modes, it ignores errors.
+ (4.1c) tset 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, tput did not modify terminal
modes. tput now uses a similar scheme, using functions shared with
@@ -425,10 +458,18 @@
for the standard capname operands, and an internal library function
to analyze nonstandard capname operands.
- This implementation (unlike others) can accept both termcap and ter-
- minfo names for the capname feature, if termcap support is compiled in.
- However, the predefined termcap and terminfo names have two ambiguities
- in this case (and the terminfo name is assumed):
+ 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 tput 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 termcap and
+ terminfo names for the capname feature, if termcap support is compiled
+ in. However, the predefined termcap and terminfo names have two
+ ambiguities in this case (and the terminfo name is assumed):
o The termcap name dl corresponds to the terminfo name dl1 (delete
one line).
@@ -449,8 +490,8 @@
There are a few interesting observations to make regarding that:
o In this implementation, clear is part of the capname support. The
- others (init and longname) do not correspond to terminal capabili-
- ties.
+ others (init and longname) do not correspond to terminal
+ capabilities.
o Other implementations of tput on SVr4-based systems such as
Solaris, IRIX64 and HPUX as well as others such as AIX and Tru64
@@ -461,28 +502,50 @@
2010, NetBSD's tput uses terminfo names. Before that, it (like
FreeBSD) recognized termcap names.
+ Beginning in 2021, FreeBSD uses the ncurses tput, configured for
+ both terminfo (tested first) and termcap (as a fallback).
+
Because (apparently) all of the certified Unix systems support the full
- set of capability names, the reasoning for documenting only a few may
+ set of capability names, the reasoning for documenting only a few may
not be apparent.
- o X/Open Curses Issue 7 documents tput differently, with capname and
+ o X/Open Curses Issue 7 documents tput differently, with capname and
the other features used in this implementation.
- o 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 termi-
- nal capabilities database.
+ o 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 capabilities database.
+
+ o While it is certainly possible to write a tput program without
+ using curses, none of the systems which have a curses
+ implementation provide a tput utility which does not provide the
+ capname 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):
+
+ o It assigns exit code 4 to "invalid operand", which may be the same
+ as unknowncapability. For instance, the source code for Solaris'
+ xcurses uses the term "invalid" in this case.
+
+ o 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 -1 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.
- o While it is certainly possible to write a tput program without
- using curses, none of the systems which have a curses implementa-
- tion provide a tput utility which does not provide the capname fea-
- ture.
+ NetBSD curses documents different exit codes which do not correspond to
+ either ncurses or X/Open.