   This file documents the the GNU `tput' command for translating
terminal capability names into escape and control codes for a particular
terminal.

   Copyright (C) 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.

`tput': Portable Terminal Control for Shell Scripts
***************************************************

   The `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.

   `tput' takes as an argument the name of a Unix System V terminfo
capability, which it translates into the equivalent termcap capability
name (see 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.  See Output, for more detailed
information on the three types of capabilities.

   The format of the `tput' command is illustrated below, with the
optional portions in square brackets, `[...]':

     tput [-T TERMINAL-TYPE] [+terminal=TERMINAL-TYPE] CAPABILITY [PARAMETER ...]

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

     tput clear

Using the `tput' Command
========================

   The format of the `tput' command is illustrated below, with the
optional portions in square brackets, `[...]':

     tput [-T TERMINAL-TYPE] [+terminal=TERMINAL-TYPE] CAPABILITY [PARAMETER ...]

   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.

   Below are some example uses of `tput'.  See 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 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:

     tput civis

   The following command makes the cursor visible again:

     tput cnorm

   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 Notes. 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
Definitions of the Terminal Capabilities (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 tput os; 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`
     tput sc
     tput cup $line $column
     tput rev
     echo 'Hello, World'
     tput sgr0
     tput rc

Capabilities
============

Boolean Capabilities
--------------------

     Name    Termcap Description
             Equiv.

     am      am      Has automatic margins
     bw      bw      `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., `dialup', `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      `smcup' does not reverse `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 `smso' (t1061)

Numeric Capabilities
--------------------

     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 > `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 `smso' or `rmso'

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.

     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 `cvvis' & `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 `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      `rmir' 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'
     ll      ll      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)
     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 `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 `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 `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 `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

Error Messages
==============

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

0
     Normal status; the given capability is present.

1
     The given Boolean or string capability is not present.

2
     Usage error; `tput' was given invalid arguments.

3
     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.

4
     The given capability is unknown.

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
`tput' command takes a terminfo name as an argument to make it
compatible with the Unix System V `tput' command; there is no
equivalent command, using termcap, in Berkeley Unix.

Bugs
----

   The `longname', `init', and `reset' options of the System V `tput'
command are not implemented; however, the `tset' command can perform
the latter two functions.

Author
------

   David MacKenzie wrote the GNU `tput' command.