tput - change terminal characteristics

This command is only helpful for users accessing the POSIX shellvia rlogin.

You can use tput to

• indicate one capability of a terminal (Format 1)

• list a number of capabilities of a terminal (Format 2)

• initialize a terminal (Format 3)

• reset a terminal (Format 4)

• display the long name of a terminal (Format 5)

• clear the screen (Format 6).

Syntax

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

Indicating one capability of a terminal

Format 1:

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

tput indicates capabilities of a terminal as defined in the terminfo database.

-T type

type indicates the type of terminal whose capabilities are to be queried. If the -T type option is specified, the shell variables LINES and COLUMNS and the layer size will not be referenced.

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

capname

(capability name) capname is the alias (abbreviated form) of a terminal capability as defined in the terminfo source file. To find out whether your terminal has a particular capability (attribute), you specify the appropriate alias capname.

Depending on the type of attribute, tput responds as follows:

• Boolean type attribute: tput simply sets an exit status (0 for true is the terminal has the attribute, 1 for false if it does not). In the POSIX shell you can inspect the exit status with echo $?.

• string type attribute: tput returns the appropriate string.

• integer type attribute: tput returns an integer.

If capname is an attribute for which no value is assigned to the specified terminal type in the terminfo database, tput returns -1.

parameter

If the capname attribute is a string that takes parameters, you can enter the parameters in parameter. capname and parameter are passed to tput as a compound string. An all numeric parameter is passed as a number.

Listing a number of capabilities of a terminal

Format 2:

tput -S

tput can be used to list multiple capabilities of the user’s terminal. You pass the capabilities from standard input rather than from the command line (see Example 4). Only one terminal capability is permitted per line. If the -T type option is specified, the shell variables LINES and COLUMNS will not be referenced. The meanings of the exit statuses 0 and 1 change (see Error on "tput change terminal characteristics").

capname

(capability name) capname is the alias (abbreviated form) of a terminal capability as defined in the terminfo source file. To find out whether your terminal has a particular capability (attribute), you specify the appropriate alias capname. Depending on the type of attribute, tput responds as follows:

• Boolean type attribute: tput simply sets an exit status (0 for true is the terminal has the attribute, 1 for false if it does not). In the POSIX shell you can inspect the exit status with echo $?.

• string type attribute: tput returns the appropriate string.

• integer type attribute: tput returns an integer.

• simple input redirection is possible:

  tput -S < filename

  Each line in filename is assumed to contain an entry in the form
  capname[ parameter].

  If only tput -S is specified, CTRL+D or @@d must be used to indicate the end of input.

If capname is an attribute for which no value is assigned to the specified terminal type in the terminfo database, tput returns -1.

parameter

If the capname attribute is a string that takes parameters, you can enter the parameters in parameter. capname and parameter are passed to tput as a compound string. An all numeric parameter is passed as a number.

Initializing a terminal

Format 3:

tput[ -T typ] init

If the terminfo database contains an entry for the user’s terminal, tput initializes the terminal in accordance with the terminal type specified in -T type. tput performs the following individual activities:

• If present, the terminal’s initialization strings are output (capname is1, is2, is3, if, iprog)

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

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

• If tabs are not expanded, the standard tabs are set (every 8 spaces).

If the terminfo entry does not contain the information needed for any of these activities, that activity is silently skipped.

-T type

This indicates the type of terminal whose capabilities you want to use to initialize your terminal.

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

Resetting a terminal

Format 4:

tput[ -T typ] reset

tput outputs the terminal’s reset strings (capname rs1, rs2, rs2, rf). If the reset strings are not present but initialization strings are, the initialization strings are output. Otherwise, reset behaves identically to init.

-T type

This indicates the type of terminal whose capabilities you want to use to reset your terminal.

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

Displaying the long name of a terminal

Format 5:

tput[ -T typ] longname

If the terminfo database is present and contains an entry for the user’s terminal (see Format 1, -T type option), the long name of the terminal is output. This name is the last name in the first line of the description of the terminal in the terminfo database.

Clearing the screen

Format 6:

tput[ -T typ] clear

tput outputs the clear-screen sequence.

-T type

This indicates the type of terminal whose capabilities you want to use to reset your terminal.

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

Exit status

When capname is of type boolean and the -S option is not set:

0	if the specified terminal type has the capability
1	if the specified terminal type does not have the capability

When capname is of type string and the -S option is not set:

0	if the capname capability is defined for the terminal type
1	if the capname capability is not defined for the terminal type (nothing is written to standard output)

When capname is of type boolean or string and the -S option is set:

0	if all lines could be processed succesfully
1	exit status 1 can never occur as no indication of which line failed can be given

When capname is of type integer:

0	The exit status is always 0. You can test the value of the standard output to determine whether capname is defined for the specified terminal type or not. -1 on standard output indicates that capname is not defined.

Error situations are indicated by an exit status of 2, 3 or 4.

Error

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

tput: unknown terminal type

terminal type type unknown or no terminfo database present, exit status 3

tput: unknown terminfo capability capname

Self-explanatory, exit status 4

Variable

TERM

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

File

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

Directory containing binary versions of the terminal type descriptions.

/usr/include/curses.h

curses() header file

/usr/include/term.h

terminfo() header file

/usr/lib/tabset/*

Information on tab handling

Locale

The following environment variables affect the execution 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

Initializing a terminal

$ tput init

A sequence of control characters that initializes the screen is passed to the user’s terminal. The sequence used is the one appropriate to the terminal type defined in the TERM environment variable.

Example 2

Displaying the number of columns for the current terminal:

$ tput cols

80

Example 3

Indicating whether the current terminal is a hardcopy terminal:

$ tput hc

$ echo $?

1

Since hc is a Boolean type value, tput simply returns an exit status, which you can inspect with echo $?. The returned value of 1 indicates that the terminal is not a hardcopy terminal.

Example 4

Displaying several capabilities in one tput invocation

$ tput -S <<here
> clear

> cup 10 10

> bold

> here

The screen is cleared, the cursor moved to position 10,10 and bold (extra bright) mode turned on. The list is terminated by here in the last line.

Example 5

The file input has the following contents:

cols
lines

Using this file as input to tput for terminals of types 97801 and 97808 would, for example, produce the following result:

$ tput -S < input

89

24

$

See also

stty, tabs