tput - initialize terminal or query terminfo database

This command is only useful if access to the POSIX shell is via ssh or rlogin from a character terminal.

You can use tput to

• output one capability of a terminal (Format 1)

• output multiple capabilities of a terminal (Format 2)

• initialize a terminal (Format 3)

• reset a terminal (Format 4)

• output the long name of a terminal type (Format 5)

• clear the screen (Format 6).

Syntax

Format 1:	tput[ -T type] capname[ parameter...]
Format 2:	tput[ -T type] -S
Format 3:	tput[ -T type] init
Format 4:	tput[ -T type] reset
Format 5:	tput[ -T type] longname
Format 6:	tput[ -T type] clear

Output one capability of a terminal

Format 1:

tput[ -T type] capname[ parameter...]

One capability of a terminal is output. These capabilities are defined in the terminfo database.

Depending on the type of capability, tput outputs the following:

• Boolean type capability:
  tput just sets returns the exit status (0 for true if the terminal has the capability, 1 for false if it does not).
  In the POSIX shell, the exit status can be displayed with echo $?.
• Numeric type capability:
  tput outputs an integer value.
  If no value is assigned to the  capability for the specified terminal type, tput outputs -1.
• String type capability:
  tput outputs the respective string (control character sequence) to the terminal. By this, the cursor or the terminal's screen can be manipulated according to the capability's meaning.
  If no value is assigned to the  capability for the specified terminal type, tput returns the exit status  1.

The "Terminal capabilities" section of the "POSIX Commands" manual provides an overview of the capabilities of the "xterm" terminal type and the corresponding terminfo names (see column "terminfo name").

-T type

type specifies the type of terminal whose capability should be output.

-T type not specified
type defaults to the value of the environment variable TERM.

capname

(capability name)

capname is the short name of a terminal capability, as shown in the terminfo name column in the "Terminal capabilities" section of the "POSIX Commands" manual. To output a particular terminal capability, the corresponding short name capname must be specified.

parameter

If the capname capability is a string which takes parameters, then these parameters are specified after capname.

Output of multiple capabilities of a terminal

Format 2:

tput[ -T type] -S

This format of tput can output multiple properties of the terminal. The short names of the capabilities and, if applicable, the parameters are read from standard input. Only one capability may be specified per input line. If the standard input is read from the terminal, the input must be terminated with CTRL+D.

The input lines have the format:

capname[ parameter...]

-T type, capname, parameter

See Format 1.

Initializing a terminal

Format 3:

tput[ -T type] init

If the terminfo database contains an entry for the terminal type, tput initializes the terminal accordingly by performing the following steps:

• If present, the terminal’s initialization strings are output. The short names of these capabilities are is1, is2, is3, if and iprog.

• Any delays (e.g. for newline) specified in the terminal entry are set in the terminal driver.

• Tabs expansion is turned on or off according to the specification in the terminal entry.

• If no tab expansion is specified in the terminal entry, the standard tabs (at every eighth character) are set.

If the terminfo entry does not contain the information for one of the steps, this step is skipped without an error message.

-T type

See Format 1.

Resetting a terminal

Format 4:

tput[ -T type] reset

If the terminfo database contains an entry for the terminal type, tput outputs the strings for resetting the terminal. The short names of these capabilities are rs1, rs2, rs3 and rf. If no strings are defined for resetting, but there are for initialization, the initialization strings are output.

-T type

See Format 1.

Output the long name of a terminal type

Format 5:

tput[ -T type] longname

If the terminfo database contains an entry for the terminal type, tput outputs the long name of the terminal type.

-T type

See Format 1.

Clear the screen

Format 6:

tput[ -T type] clear

If the terminfo database contains an entry for the terminal type, tput outputs the clear-screen control character sequence.

-T type

See Format 1.

Exit status

Capability of type boolean:

0	The specified terminal type has the capability.
1	The specified terminal type does not have the capability.

Capability of type string:

0	The capability is defined for the terminal type.
1	The capability is not defined for the terminal type. Nothing is written to standard output.

Capability of type integer:

0	The exit status is always 0. Output -1 on standard output indicates that the capability is not defined for the terminal type.

Format 2 (tput -S):

0	All lines were processed without errors.

Error situations:

2	Incorrect call, e.g. no specification of the terminal type.
3	Incorrect configuration, e.g. terminal type unknown.
4	Specification of an unknown terminal capability.

Error

Depending on the exit status, tput issues one of the following error messages:

tput: Unknown terminal "type"
The terminal type is unknown or no terminfo database is present.
Exit status 3

tput: Unknown terminfo capability 'capname'
The specified terminal capability is unknown.
Exit status 4

Variable

TERM

Default value used for the type of terminal when -T type is not specified.

File

/etc/termcap

File with all properties of all terminals in readable format.

/usr/share/lib/terminfo/?/*

Files with all properties of one terminal each in binary (compiled) format.

Locale

The following environment variables affect the message output of tput:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

Emit an acoustic signal

$ tput bel

The terminal emits an acoustic signal. Depending on the terminal's settings, a visual signal may also be emitted, or no signal at all.

Example 2

Output the number of columns of the current terminal

$ tput cols
80

The terminal has (currently) 80 columns.

Example 3

Check whether the current terminal is a hardcopy terminal

$ tput hc
$ echo $?
1

Since hc is a Boolean value, tput only returns an exit status. This exit status is queried with echo $?. The exit status is 1, so the current terminal is not a hardcopy terminal.

Example 4

Output of multiple terminal properties with one tput call

The file geom has the following contents:

cols
lines

$ tput -S <geom
120
42
$

The terminal has 120 columns (capability cols) and 42 lines (capability lines).

Example 5

Output of text in an alternative display mode

$ echo "This is the $(tput smul)underline$(tput rmul) mode."
This is the underline mode.
$

Output of the smul capability turns underlined mode on, and output of the rmul capability turns it off.

See also

stty, tabs