tput: Portable Terminal Control

The tput command allows shell scripts to do things like clear the screen, underline text, and center
text no matter how wide the screen is. To do these things, it translates the terminal-independent
name of a terminal capability into its actual value for the terminal type being used.

tput takes as an argument the name of a Unix System V terminfo capability, which it translates into
the equivalent termcap capability name (see section Capabilities, for a list of the equivalencies).
Terminfo is a database that is similar to termcap but which has different capability names and is
stored in a different format. The GNU tput command takes a terminfo name as an argument to make
it compatible with the Unix System V tput command.

There are three types of terminfo (and termcap) capabilities: string, Boolean, and numeric. String
capabilities either cause a special effect on the terminal when they are displayed or are the value
sent by a special key on the terminal (the latter type are probably of no use in shell scripts). Numeric
and Boolean capabilities give information about the terminal such as how many columns wide it is or
whether whether it has a meta key. See section Output and Exit Status, for more detailed
information on the three types of capabilities.

The format of the tput command is illustrated below.

tput [options] capability [parameter ...]

tput [options] longname

tput [options] init

tput [options] reset

GNU tput takes the following options:

[-T terminal-type] [--terminal=terminal-type]

[-t] [--termcap]

[-S] [--standard-input]

[-V] [--version]

Here is an example of how to clear the terminal screen using tput:

tput clear

Using tput

The format of the tput command is illustrated below.

tput [options] capability [parameter ...]

tput [options] longname

tput [options] init

tput [options] reset

GNU tput takes the following options:

[-T terminal-type] [--terminal=terminal-type]

[-t] [--termcap]

[-S] [--standard-input]

[-V] [--version]

Some string capabilities accept parameters, such as the number of lines to delete or the column to
move to. These parameters are specified on the command line following the capability name. They
are always numbers.

`-T termtype'

`--terminal=termtype'

This option indicates the type of terminal. By default, this value is taken from the `TERM'
environment variable.

`-t'

`--termcap'

GNU tput by default accepts termcap name if the capability a user specifies is not a terminfo name.
This option tells tput not to try terminfo names and look up only termcap names.

`-S'

`--standard-input'

This option tells tput to read a sequence of capabilities and parameters from the standard input.
Only string capabilities can be used in this mode.

`-V'

`--version'

This option displays the version of tput.

When `longname' is specified, tput displays the long descriptive name for the terminal type.
When `init' is specified, tput sends the initialization strings for the terminal. If the terminal's tab
width is other than 8, and it cannot be reset, the tab expansion in the tty driver is turned on.
Otherwise, tab width is reset to 8 and the tab expansion is turned off.

When `reset' is specified, tput sends the reset strings for the terminal and then follows the same
initialization sequence as tput `init'.

Below are some example uses of tput. See section Capabilities, for a complete list of the functions
that tput can cause terminals to perform. Note that not all terminals can perform any given function.
See section Yet More Examples, for some more complex samples of tput use.

The following command moves the cursor to row 10, column 30 of the screen:

tput cup 10 30

The following command makes the cursor invisible:

tputcivis

The following command makes the cursor visible again:

tputcnorm

The following command deletes 10 lines below and including the one on which the cursor is
positioned:

tput dl 10

Output and Exit Status

The tput command produces different kinds of output for each of the three types of terminal
capabilities: string, numeric, and Boolean.

If the terminfo capability given on the command line is a string capability, tput displays its value and
exits with a status of 0. If the capability is not defined for the terminal type being used, tput
produces no output and exits with a status of 1.

If the capability is a numeric capability, tput displays its value (an integer). If the capability is not
defined for the terminal type being used, tput displays the value `-1'. The exit status is always 0 for
numeric capabilities, unless an error occurs (see section Error Messages for a complete list of the
possible exit status values).

If the capability is a Boolean capability, tput produces no output and exits with status 0 if the
capability is defined for the terminal type being used, or status 1 if the capability is not defined. See
section `Definitions of the Terminal Capabilities' in Termcap, for a more detailed description of
termcap capabilities.

The values of numeric capabilities should be saved into shell variables so they can be used later
without having to run tput again. Here is how it can be done:

For the Bourne, Bourne-again, and Korn shells:

To set an environment variable: COLUMNS=`tput cols` export COLUMNS

To set a local variable: tabwidth=`tput it`

For the C shell:

To set an environment variable: setenv COLUMNS `tput cols`

To set a local variable: set tabwidth = `tput it`

The values of string capabilities can be saved in shell variables in the same way, then displayed later
using the echo command. Since echo is built into most shells, it runs more quickly than tput does.
However, using echo instead of tput to display string values can cause problems for capabilities that
use padding, because null padding characters cannot be passed as arguments to commands,
including echo.

Yet More Examples

Here are some more advanced examples of using tput; most involve some shell programming.
Because the C shell's flow control (decision making) constructs differ from those of the other shells,
these examples do not work under the C shell.

The following sequence of commands prints `I am infalible' and then crosses it out on terminals that
can overstrike, and prints `I am on strike' on terminals that cannot.

if tputos; then

echo 'I am infalible\r- -- ---------'

else
 echo 'I am on strike'

fi

The following example is a shell script that centers a line of text given as command line arguments.
An alternative approach would be to have tput send the `rep' terminfo capability to print the
multiple spaces instead of using the while loop.

COLUMNS=`tput cols` export COLUMNS # Get screen width.

echo "$@" | awk '

{ spaces = ('$COLUMNS' - length) / 2

while (spaces-- > 0) printf (" ")

print

}'

The following commands cause the terminal to save the current cursor position, print `Hello, World'
centered in the screen in reverse video, then return to the original cursor position.

COLUMNS=`tput cols`

LINES=`tput lines`

line=`expr $LINES / 2`

column=`expr \( $COLUMNS - 6 \) / 2`

tputsc

tput cup $line $column

tput rev

echo 'Hello, World'

tput sgr0

tputrc

The middle three lines of the above example can also be written using `--standard-input'.

tput --standard-input <<EOF

sc

cup $line $column

rev

EOF
Capabilities

1. Boolean Capabilities

Name TermcapDescription

Equiv.

am am Has automatic margins

bwbw `cub1' wraps from column 0 to last column

chts HC Cursor is hard to see

da da Display may be retained above screen

dbdb Display may be retained below screen

eoeo Can erase overstrikes with a blank

eslok es Using escape on status line is ok

gngn Generic line type (e.g., `dialup', `switch')

hchc Hardcopy terminal

hshs Has a status line

hzhz Hazeltine; cannot print tildes

in in Insert mode distinguishes nulls

km km Has a meta key (a shift that sets parity bit)

mc5i 5i Data sent to printer does not echo on screen

mir mi Safe to move while in insert mode

msgrms Safe to move in standout modes

npc NP No pad character is needed

nrrmc NR `smcup' does not reverse `rmcup'

nxonnx Padding does not work; xon/xoff is required

osos Overstrikes

ulul Underline character overstrikes

xenlxn Newline ignored after 80 columns (Concept)

xhpxs Standout is not erased by overwriting (HP)

xon xo Uses xon/xoffhandshaking

xsbxb Beehive (f1=escape, f2=ctrl-c)

xtxt Tabs are destructive, magic `smso' (t1061)

 2. Numeric Capabilities

Name TermcapDescription

Equiv.

cols co Number of columns in a line

it it Width of initial tab settings

lhlh Number of rows in each label

lines li Number of lines on screen or page

lmlm Lines of memory if > `lines'; 0 means varies

lwlw Number of columns in each label

nlabNl Number of labels on screen (start at 1)

pb pb Lowest baud rate where padding is needed

vtvt Virtual terminal number (CB/Unix)

wslws Number of columns in status line

xmc sg Number of blanks left by `smso' or `rmso'

3. String Capabilities

In the following table, `(P)' following an explanation means that the capability takes one or more
parameters (and is evaluated by the tparam function, or in the case of `cup', tgoto); `(*)' means that
padding may be based on the number of lines affected; and `#n' refers to the `n'th parameter.

NameTermcapDescription

Equiv.

acsc ac Graphic character set pairs aAbBcC - default vt100

bel bl Ring bell (beep)

blink mb Begin blinking mode

bold md Begin double intensity mode

cbtbt Back tab

civis vi Make cursor invisible

clear cl Clear screen (*)

cmdch CC Settable command character in prototype

cnormve Make cursor normal (undo `cvvis' & `civis)'

crcr Carriage return (*)

csr cs Change scrolling region to lines #1 through #2 (P)

cub LE Move cursor left #1 spaces (P)

cub1 le Move cursor left one space

cud DO Move cursor down #1 lines (P*)

cud1 do Move cursor down one line

cuf RI Move cursor right #1 spaces (P*)

cuf1 nd Move cursor right one space

cup cm Move cursor to row #1, column #2 of screen (P)

cuu UP Move cursor up #1 lines (P*)

cuu1 up Move cursor up one line

cvvis vs Make cursor very visible

dch DC Delete #1 characters (P*)

dch1 dc Delete one character (*)

dim mh Begin half intensity mode

dl DL Delete #1 lines (P*)

dl1 dl Delete one line (*)

dsl ds Disable status line

echec Erase #1 characters (P)

ed cd Clear to end of display (*)

elce Clear to end of line

el1 cb Clear to beginning of line, inclusive

enacseA Enable alternate character set

ff ff Form feed for hardcopy terminal (*)

flash vb Visible bell (must not move cursor)

fsl fs Return from status line

hdhd Move cursor down one-half line

home hoHome cursor (if no `cup')

hpach Move cursor to column #1 (P)

ht ta Tab to next 8 space hardware tab stop

htsst Set a tab in all rows, current column

hu hu Move cursor up one-half line

ich IC Insert #1 blank characters (P*)

ich1 ic Insert one blank character

if if Name of file containing initialization string

il AL Add #1 new blank lines (P*)

il1 al Add one new blank line (*)

ind sf Scroll forward (up) one line

indn SF Scroll forward #1 lines (P)

invismk Begin invisible text mode

ipip Insert pad after character inserted (*)

iprogiP Path of program for initialization

is1 i1 Terminal initialization string

is2 is Terminal initialization string

is3 i3 Terminal initialization string

kBEG&9 Shifted beginning key

kCAN&0 Shifted cancel key

kCMD *1 Shifted command key

kCPY *2 Shifted copy key

kCRT *3 Shifted create key

kDC *4 Shifted delete char key

kDL *5 Shifted delete line key

kEND *7 Shifted end key

kEOL *8 Shifted clear line key

kEXT *9 Shifted exit key

kFND *0 Shifted find key

kHLP #1 Shifted help key

kHOM #2 Shifted home key

kIC #3 Shifted input key

kLFT #4 Shifted left arrow key

kMOV %b Shifted move key

kMSG %a Shifted message key

kNXT %c Shifted next key

kOPT %d Shifted options key

kPRT %f Shifted print key

kPRV %e Shifted prevkey

kRDO %g Shifted redo key

kRES %j Shifted resume key

kRIT %i Shifted right arrow

kRPL %h Shifted replace key

kSAV !1 Shifted save key

kSPD !2 Shifted suspend key

kUND !3 Shifted undo key

ka1 K1 Upper left of keypad

ka3 K3 Upper right of keypad

kb2 K2 Center of keypad

kbeg @1 Beginning key

kbs kb Backspace key

kc1 K4 Lower left of keypad

kc3 K5 Lower right of keypad

kcan @2 Cancel key

kcbt kB Back tab key

kclo @3 Close key

kclrkC Clear screen or erase key

kcmd @4 Command key

kcpy @5 Copy key

kcrt @6 Create key

kctab kt Clear tab key

kcub1 kl Left arrow key

kcud1 kd Down arrow key

kcuf1 kr Right arrow key

kcuu1 ku Up arrow key

kdch1 kD Delete character key

kdl1 kL Delete line key

ked kS Clear to end of screen key

kelkE Clear to end of line key

kend @7 End key

kent @8 Enter/send key (unreliable)

kext @9 Exit key

kf0 k0 Function key f0

kf1 k1 Function key f1

kf10 k; Function key f10

kf11 F1 Function key f11

kf12 F2 Function key f12

kf13 F3 Function key f13

kf14 F4 Function key f14

kf15 F5 Function key f15

kf16 F6 Function key f16

kf17 F7 Function key f17

kf18 F8 Function key f18

kf19 F9 Function key f19

kf2 k2 Function key f2

kf20 FA Function key f20

kf21 FB Function key f21

kf22 FC Function key f22

kf23 FD Function key f23

kf24 FE Function key f24

kf25 FF Function key f25

kf26 FG Function key f26

kf27 FH Function key f27

kf28 FI Function key f28

kf29 FJ Function key f29

kf3 k3 Function key f3

kf30 FK Function key f30

kf31 FL Function key f31

kf32 FM Function key f32

kf33 FN Function key f13

kf34 FO Function key f34

kf35 FP Function key f35

kf36 FQ Function key f36

kf37 FR Function key f37

kf38 FS Function key f38

kf39 FT Function key f39

kf4 k4 Function key f4

kf40 FU Function key f40

kf41 FV Function key f41

kf42 FW Function key f42

kf43 FX Function key f43

kf44 FY Function key f44

kf45 FZ Function key f45

kf46 Fa Function key f46

kf47 Fb Function key f47

kf48 Fc Function key f48

kf49 Fd Function key f49

kf5 k5 Function key f5

kf50 Fe Function key f50

kf51 Ff Function key f51

kf52 Fg Function key f52

kf53 Fh Function key f53

kf54 Fi Function key f54

kf55 Fj Function key f55

kf56 Fk Function key f56

kf57 Fl Function key f57

kf58 Fm Function key f58

kf59 Fn Function key f59

kf6 k6 Function key f6

kf60 Fo Function key f60

kf61 Fp Function key f61

kf62 Fq Function key f62

kf63 Fr Function key f63

kf7 k7 Function key f7

kf8 k8 Function key f8

kf9 k9 Function key f9

kfnd @0 Find key

khlp %1 Help key

khomekhHome key

khtskT Set tab key

kich1 kIIns char/enter ins mode key

kil1 kA Insert line key

kind kF Scroll forward/down key

kllkHHome down key

kmov %4 Move key

kmrk %2 Mark key

kmsg %3 Message key

knpkN Next page key

knxt %5 Next object key

kopn %6 Open key

kopt %7 Options key

kppkP Previous page key

kprt %9 Print or copy key

kprv %8 Previous object key

krdo %0 Redo key

kref&1 Reference key

kres&5 Resume key

krfr&2 Refresh key

krikR Scroll backward/up key

krmirkMrmir or smir in insert mode

krpl&3 Replace key

krst&4 Restart key

ksav&6 Save key

kslt *6 Select key

kspd&7 Suspend key

ktbc ka Clear all tabs key

kund&8 Undo key

lf0 l0 Label on function key f0 if not `f0'

lf1 l1 Label on function key f1 if not `f1'

lf10 la Label on function key f10 if not `f10'

lf2 l2 Label on function key f2 if not `f2'

lf3 l3 Label on function key f3 if not `f3'

lf4 l4 Label on function key f4 if not `f4'

lf5 l5 Label on function key f5 if not `f5'

lf6 l6 Label on function key f6 if not `f6'

lf7 l7 Label on function key f7 if not `f7'

lf8 l8 Label on function key f8 if not `f8'

lf9 l9 Label on function key f9 if not `f9'

llll Go to last line, first column (if no `cup')

mc0 ps Print screen contents

mc4 pf Turn printer off

mc5 po Turn printer on

mc5p pO Turn printer on for #1 bytes (P)

mgc MC Clear left and right soft margins

mrcup CM Move cursor to row #1, column #2 of memory (P)

nelnw Newline (like cr followed by lf)

pad pc Pad character (rather than nul)

pfkey pk Program function key #1 to type string #2 (P)

pfloc pl Program function key #1 to execute string #2 (P)

pfxpx Program function key #1 to transmit string #2 (P)

plnpn Program label #1 to show string #2 (P)

protmp Begin protected mode

rcrc Restore cursor to position of last `sc'

rep rp Repeat character #1, #2 times (P*)

rev mr Begin reverse video mode

rf rf Name of file containing reset string

rfi RF Send next input character (for ptys)

risr Scroll backward (down) one line

rin SR Scroll backward #1 lines (P)

rmacs ae End alternate character set

rmam RA Turn off automatic margins

rmcupte String to end programs that use `cup'

rmdc ed End delete mode

rmirei End insert mode

rmkxke End keypad transmit mode

rmln LF Turn off soft labels

rmmmo End meta mode

rmprP Like `ip' but when in replace mode

rmso se End standout mode

rmulue End underscore mode

rmxon RX Turn off xon/xoffhandshaking

rs1 r1 Reset terminal to sane modes

rs2 r2 Reset terminal to sane modes

rs3 r3 Reset terminal to sane modes

scsc Save cursor position

sgrsa Define video attributes #1 through #9 (P)

sgr0 me Turn off all attributes

smacs as Begin alternate character set

smam SA Turn on automatic margins

smcupti String to begin programs that use `cup'

smdc dm Begin delete mode

smgl ML Set soft left margin to #1 (P)

smgr MR Set soft right margin to #1 (P)

smir im Begin insert mode

smkxks Begin keypad transmit mode

smln LO Turn on soft labels

smm mm Begin meta mode (8th bit set)

smso so Begin standout mode

smul us Begin underscore mode

smxon SX Turn on xon/xoffhandshaking

tbc ct Clear all tab stops

tslts Go to status line, column #1 (P)

ucuc Underscore one character and move past it

vpa cv Move cursor to row #1 (P)

wind wi Set window to lines #1-#2, columns #3-#4 (P)

xoffc XF xoff character

xonc XN xon character

Error Messages

tput displays various error messages if problems occur. In addition, it exits with one of the following
status values:

Normal status; the given capability is present.

The given Boolean or string capability is not present.

Usage error; tput was given invalid arguments.

The terminal type given (either in the `TERM' environment variable or by the `-T' switch) is unknown,
or the termcap database can not be read.

The given capability is unknown.