\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename tput.info
@settitle @code{tput}: Portable Terminal Control for Shell Scripts
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents the the GNU @code{tput} command for translating
terminal capability names into escape and control codes for a particular
terminal.

Copyright @copyright{} 1989-1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@titlepage
@title The GNU @code{tput} Command
@subtitle Portable Terminal Control for Shell Scripts

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989-1991 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end titlepage

@node	  Top, 	      ,      (dir),     (dir)
@comment  node-name,  next,  previous,  up
@chapter @code{tput}: Portable Terminal Control for Shell Scripts

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

@code{tput} takes as an argument the name of a Unix System V terminfo
capability, which it translates into the equivalent termcap capability
name (@pxref{Capabilities}, for a list of the equivalencies).

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.  @xref{Output}, for more detailed
information on the three types of capabilities.

The format of the @code{tput} command is illustrated below, with the
optional portions in square brackets, @samp{[@dots{}]}:

@example
tput [-T @var{terminal-type}] [+terminal=@var{terminal-type}] @var{capability} [@var{parameter} @dots{}]
@end example

Here is an example of how to clear the terminal screen using @code{tput}:

@example
tput clear
@end example

@menu
* Using tput::     Using the @code{tput} command.
* Output::	   Output and exit status.
* More Examples::  More examples of using @code{tput}.
* Capabilities::   Summary of terminfo capabilities.
* Error Messages:: Error messages produced by @code{tput}.
* Notes::          Miscellaneous information about @code{tput}.
@end menu

@node Using tput, Output, , Top
@c node-name, next, previous, up
@section Using the @code{tput} Command

The format of the @code{tput} command is illustrated below, with the
optional portions in square brackets, @samp{[@dots{}]}:

@example
tput [-T @var{terminal-type}] [+terminal=@var{terminal-type}] @var{capability} [@var{parameter} @dots{}]
@end example

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.

@table @samp
@item -T @var{termtype}
@itemx +terminal=@var{termtype}
This option indicates the type of terminal.  By default, this value is
taken from the @samp{TERM} environment variable.
@end table

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

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

@example
tput cup 10 30
@end example

The following command makes the cursor invisible:

@example
tput civis
@end example

The following command makes the cursor visible again:

@example
tput cnorm
@end example

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

@example
tput dl 10
@end example

@node Output, More Examples, Using tput, Top
@comment  node-name,  next,  previous,  up
@section Output and Exit Status

The @code{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, @code{tput} displays its value and exits with a status of 0.
If the capability is not defined for the terminal type being used,
@code{tput} produces no output and exits with a status of 1.

If the capability is a numeric capability, @code{tput} displays its
value (an integer).  If the capability is not defined for the terminal
type being used, @code{tput} displays the value @samp{-1}.  The exit
status is always 0 for numeric capabilities, unless an error occurs
(@pxref{Notes} for a complete list of the possible exit status
values).@refill

If the capability is a Boolean capability, @code{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.
@xref{Capabilities,,Definitions of the Terminal Capabilities,termcap,Termcap},
for a more detailed description of termcap capabilities.@refill

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

@example
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`
@end example

@noindent
The values of string capabilities can be saved in shell variables in the
same way, then displayed later using the @code{echo} command. Since
@code{echo} is built into most shells, it runs more quickly than
@code{tput} does.  However, using @code{echo} instead of @code{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 @code{echo}.

@node More Examples, Capabilities, Output, Top
@c node-name, next, previous, up
@section Yet More Examples

Here are some more advanced examples of using @code{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 @samp{I am infalible} and
then crosses it out on terminals that can overstrike, and prints
@samp{I am on strike} on terminals that cannot.

@example
if tput os; then
    echo 'I am infalible\r- -- ---------'
else
    echo 'I am on strike'
fi
@end example

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 @code{tput} send the @samp{rep} terminfo capability to print the
multiple spaces instead of using the @code{while} loop.

@example
COLUMNS=`tput cols` export COLUMNS # Get screen width.
echo "$@@" | awk '
@{ spaces = ('$COLUMNS' - length) / 2
  while (spaces-- > 0) printf (" ")
  print
@}'
@end example

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

@example
COLUMNS=`tput cols`
LINES=`tput lines`
line=`expr $LINES / 2`
column=`expr \( $COLUMNS - 6 \) / 2`
tput sc
tput cup $line $column
tput rev
echo 'Hello, World'
tput sgr0
tput rc
@end example

@node Capabilities, Error Messages, More Examples, Top
@c node-name, next, previous, up
@section Capabilities

@subsection Boolean Capabilities

@example
Name    Termcap Description
        Equiv.

am      am      Has automatic margins
bw      bw      @samp{cub1} wraps from column 0 to last column
chts    HC      Cursor is hard to see
da      da      Display may be retained above screen
db      db      Display may be retained below screen
eo      eo      Can erase overstrikes with a blank
eslok   es      Using escape on status line is ok
gn      gn      Generic line type (e.g., @samp{dialup}, @samp{switch})
hc      hc      Hardcopy terminal
hs      hs      Has a status line
hz      hz      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
msgr    ms      Safe to move in standout modes
npc     NP      No pad character is needed
nrrmc   NR      @samp{smcup} does not reverse @samp{rmcup}
nxon    nx      Padding does not work; xon/xoff is required
os      os      Overstrikes
ul      ul      Underline character overstrikes
xenl    xn      Newline ignored after 80 columns (Concept)
xhp     xs      Standout is not erased by overwriting (HP)
xon     xo      Uses xon/xoff handshaking
xsb     xb      Beehive (f1=escape, f2=ctrl-c)
xt      xt      Tabs are destructive, magic @samp{smso} (t1061)
@end example

@subsection Numeric Capabilities

@example
Name    Termcap Description
        Equiv.

cols    co      Number of columns in a line
it      it      Width of initial tab settings
lh      lh      Number of rows in each label
lines   li      Number of lines on screen or page
lm      lm      Lines of memory if > @samp{lines}; 0 means varies
lw      lw      Number of columns in each label
nlab    Nl      Number of labels on screen (start at 1)
pb      pb      Lowest baud rate where padding is needed
vt      vt      Virtual terminal number (CB/Unix)
wsl     ws      Number of columns in status line
xmc     sg      Number of blanks left by @samp{smso} or @samp{rmso}
@end example

@subsection String Capabilities

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

@example
Name    Termcap Description
        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
cbt     bt      Back tab
civis   vi      Make cursor invisible
clear   cl      Clear screen (*)
cmdch   CC      Settable command character in prototype
cnorm   ve      Make cursor normal (undo @samp{cvvis} & @samp{civis)}
cr      cr      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
ech     ec      Erase #1 characters (P)
ed      cd      Clear to end of display (*)
el      ce      Clear to end of line
el1     cb      Clear to beginning of line, inclusive
enacs   eA      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
hd      hd      Move cursor down one-half line
home    ho      Home cursor (if no @samp{cup})
hpa     ch      Move cursor to column #1 (P)
ht      ta      Tab to next 8 space hardware tab stop
hts     st      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)
invis   mk      Begin invisible text mode
ip      ip      Insert pad after character inserted (*)
iprog   iP      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 prev key
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
kclr    kC      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
kel     kE      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
khome   kh      Home key
khts    kT      Set tab key
kich1   kI      Ins char/enter ins mode key
kil1    kA      Insert line key
kind    kF      Scroll forward/down key
kll     kH      Home down key
kmov    %4      Move key
kmrk    %2      Mark key
kmsg    %3      Message key
knp     kN      Next page key
knxt    %5      Next object key
kopn    %6      Open key
kopt    %7      Options key
kpp     kP      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
kri     kR      Scroll backward/up key
krmir   kM      @code{rmir} or @code{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 @samp{f0}
lf1     l1      Label on function key f1 if not @samp{f1}
lf10    la      Label on function key f10 if not @samp{f10}
lf2     l2      Label on function key f2 if not @samp{f2}
lf3     l3      Label on function key f3 if not @samp{f3}
lf4     l4      Label on function key f4 if not @samp{f4}
lf5     l5      Label on function key f5 if not @samp{f5}
lf6     l6      Label on function key f6 if not @samp{f6}
lf7     l7      Label on function key f7 if not @samp{f7}
lf8     l8      Label on function key f8 if not @samp{f8}
lf9     l9      Label on function key f9 if not @samp{f9}
ll      ll      Go to last line, first column (if no @samp{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)
nel     nw      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)
pfx     px      Program function key #1 to transmit string #2 (P)
pln     pn      Program label #1 to show string #2 (P)
prot    mp      Begin protected mode
rc      rc      Restore cursor to position of last @samp{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)
ri      sr      Scroll backward (down) one line
rin     SR      Scroll backward #1 lines (P)
rmacs   ae      End alternate character set
rmam    RA      Turn off automatic margins
rmcup   te      String to end programs that use @samp{cup}
rmdc    ed      End delete mode
rmir    ei      End insert mode
rmkx    ke      End keypad transmit mode
rmln    LF      Turn off soft labels
rmm     mo      End meta mode
rmp     rP      Like @samp{ip} but when in replace mode
rmso    se      End standout mode
rmul    ue      End underscore mode
rmxon   RX      Turn off xon/xoff handshaking
rs1     r1      Reset terminal to sane modes
rs2     r2      Reset terminal to sane modes
rs3     r3      Reset terminal to sane modes
sc      sc      Save cursor position
sgr     sa      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
smcup   ti      String to begin programs that use @samp{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
smkx    ks      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/xoff handshaking
tbc     ct      Clear all tab stops
tsl     ts      Go to status line, column #1 (P)
uc      uc      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
@end example

@node Error Messages, Notes, Capabilities, Top
@c node-name, next, previous, up
@section Error Messages

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

@table @asis
@item 0
Normal status; the given capability is present.

@item 1
The given Boolean or string capability is not present.

@item 2
Usage error; @code{tput} was given invalid arguments.

@item 3
The terminal type given (either in the @samp{TERM} environment variable
or by the @samp{-T} switch) is unknown, or the termcap database can not
be read. 

@item 4
The given capability is unknown.
@end table

@node Notes, , Error Messages, Top
@c node-name, next, previous, up
@section Notes

Terminfo is a database that is similar to termcap but which has
different capability names and is stored in a different format.  The GNU
@code{tput} command takes a terminfo name as an argument to make it
compatible with the Unix System V @code{tput} command; there is no
equivalent command, using termcap, in Berkeley Unix.

@subsection Bugs

The @samp{longname}, @samp{init}, and @samp{reset} options of the
System V @code{tput} command are not implemented; however, the @code{tset}
command can perform the latter two functions.@refill

@subsection Author

David MacKenzie wrote the GNU @code{tput} command.

@bye
