man/tput.1

   1 '\" t
   2 .TH tput 1 ""
   3 .ds d @DATADIR@/terminfo
   4 .ds n 5
   5 .SH NAME
   6 \fBtput\fR - initialize a terminal or query terminfo database
   7 .SH SYNOPSIS
   8 \fBtput\fR [\fB-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ]
   9 .br
  10 \fBtput\fR [\fB-T\fR\fItype\fR] \fBinit\fR
  11 .br
  12 \fBtput\fR [\fB-T\fR\fItype\fR] \fBreset\fR
  13 .br
  14 \fBtput\fR [\fB-T\fR\fItype\fR] \fBlongname\fR
  15 .br
  16 \fBtput -S\fR  \fB<<\fR
  17 .br
  18 .SH DESCRIPTION
  19 The \fBtput\fR utility uses the \fBterminfo\fR database to make the
  20 values of terminal-dependent capabilities and information available to
  21 the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
  22 return the long name of the requested terminal type.  \fBtput\fR
  23 outputs a string if the attribute (\fIcap\fRability \fIname\fR) is of
  24 type string, or an integer if the attribute is of type integer.  If
  25 the attribute is of type boolean, \fBtput\fR simply sets the exit code
  26 (\fB0\fR for TRUE if the terminal has the capability, \fB1\fR for
  27 FALSE if it does not), and produces no output.  Before using a value
  28 returned on standard output, the user should test the exit code
  29 [\fB$?\fR, see \fBsh\fR(1)] to be sure it is \fB0\fR.  (See the \fBEXIT
  30 CODES\fR and \fBDIAGNOSTICS\fR sections.)  For a complete list of capabilities
  31 and the \fIcapname\fR associated with each, see \fBterminfo\fR(\*n).
  32 .TP
  33 \fB-T\fR\fItype\fR
  34 indicates the \fItype\fR of terminal.  Normally this option is
  35 unnecessary, because the default is taken from the environment
  36 variable \fBTERM\fR.  If \fB-T\fR is specified, then the shell
  37 variables \fBLINES\fR and \fBCOLUMNS\fR will be ignored,and the
  38 operating system will not be queried for the actual screen size.
  39 .TP
  40 \fIcapname\fR
  41 indicates the attribute from the \fBterminfo\fR database.
  42 .TP
  43 \fIparms\fR
  44 If the attribute is a string that takes parameters, the arguments
  45 \fIparms\fR will be instantiated into the string.  An all numeric
  46 argument will be passed to the attribute as a number.
  47 .TP
  48 \fB-S\fR
  49 allows more than one capability per invocation of \fBtput\fR.  The
  50 capabilities must be passed to \fBtput\fR from the standard input
  51 instead of from the command line (see example).  Only one
  52 \fIcapname\fR is allowed per line.  The \fB-S\fR option changes the
  53 meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
  54 EXIT CODES section).
  55 .TP
  56 \fBinit\fR
  57 If the \fBterminfo\fR database is present and an entry for the user's
  58 terminal exists (see \fB-T\fR\fItype\fR, above), the following will
  59 occur: (1) if present, the terminal's initialization strings will be
  60 output (\fBis1\fR, \fBis2\fR, \fBis3\fR, \fBif\fR, \fBiprog\fR), (2)
  61 any delays (e.g., newline) specified in the entry will be set in the
  62 tty driver, (3) tabs expansion will be turned on or off according to
  63 the specification in the entry, and (4) if tabs are not expanded,
  64 standard tabs will be set (every 8 spaces).  If an entry does not
  65 contain the information needed for any of the four above activities,
  66 that activity will silently be skipped.
  67 .TP
  68 \fBreset\fR
  69 Instead of putting out initialization strings, the terminal's
  70 reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
  71 If the reset strings are not present, but initialization
  72 strings are, the initialization strings will be output.
  73 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
  74 .TP
  75 \fBlongname\fR
  76 If the \fBterminfo\fR database is present and an entry for the
  77 user's terminal exists (see \fB-T\fR\fItype\fR above), then the long name
  78 of the terminal will be put out.  The long name is the last
  79 name in the first line of the terminal's description in the
  80 \fBterminfo\fR database [see \fBterm\fR(5)].
  81 .SH EXAMPLES
  82 .TP 5
  83 \fBtput init\fR
  84 Initialize the terminal according to the type of
  85 terminal in the environmental variable \fBTERM\fR.  This
  86 command should be included in everyone's .profile after
  87 the environmental variable \fBTERM\fR has been exported, as
  88 illustrated on the \fBprofile\fR(4) manual page.
  89 .TP 5
  90 \fBtput -T5620 reset\fR
  91 Reset an AT&T 5620 terminal, overriding the type of
  92 terminal in the environmental variable \fBTERM\fR.
  93 .TP 5
  94 \fBtput cup 0 0\fR
  95 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
  96 (the upper left corner of the screen, usually known as the "home"
  97 cursor position).
  98 .TP 5
  99 \fBtput clear\fR
 100 Echo the clear-screen sequence for the current terminal.
 101 .TP 5
 102 \fBtput cols\fR
 103 Print the number of columns for the current terminal.
 104 .TP 5
 105 \fBtput -T450 cols\fR
 106 Print the number of columns for the 450 terminal.
 107 .TP 5
 108 \fBbold=`tput smso` offbold=`tput rmso`\fR
 109 Set the shell variables \fBbold\fR, to begin stand-out mode
 110 sequence, and \fBoffbold\fR, to end standout mode sequence,
 111 for the current terminal.  This might be followed by a
 112 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
 113 .TP 5
 114 \fBtput hc\fR
 115 Set exit code to indicate if the current terminal is a hard copy terminal.
 116 .TP 5
 117 \fBtput cup 23 4\fR
 118 Send the sequence to move the cursor to row 23, column 4.
 119 .TP 5
 120 \fBtput longname\fR
 121 Print the long name from the \fBterminfo\fR database for the
 122 type of terminal specified in the environmental
 123 variable \fBTERM\fR.
 124 .TP 0
 125 \fBtput -S <<!\fR
 126 .br
 127 \fB> clear\fR
 128 .br
 129 \fB> cup 10 10\fR
 130 .br
 131 \fB> bold\fR
 132 .br
 133 \fB> !\fR
 134 .TP 5
 135 \&
 136 This example shows tput processing several capabilities in one
 137 invocation.  This example clears the screen, moves the cursor to
 138 position 10, 10 and turns on bold (extra bright) mode.  The list is
 139 terminated by an exclamation mark (\fB!\fR) on a line by itself.
 140 .SH FILES
 141 .TP
 142 \fB\*d\fR
 143 compiled terminal description database
 144 .TP
 145 \fB/usr/include/curses.h\fR
 146 \fBcurses\fR(3X) header file
 147 .TP
 148 \fB/usr/include/term.h\fR
 149 \fBterminfo\fR header file
 150 .TP
 151 \fB@DATADIR@/tabset/*\fR
 152 tab settings for some terminals, in a format
 153 appropriate to be output to the terminal (escape
 154 sequences that set margins and tabs); for more
 155 information, see the "Tabs and Initialization"
 156 section of \fBterminfo\fR(4)
 157 .SH SEE ALSO
 158 \fBclear\fR(1), \fBstty\fR(1), \fBtabs\fR(\*n).  \fBprofile\fR(\*n),
 159 \fBterminfo\fR(4) in the \fISystem\fR \fIAdministrator\fR'\fIs\fR
 160 \fIReference\fR \fIManual\fR.  Chapter 10 of the
 161 \fIProgrammer\fR'\fIs\fR \fIGuide\fR.
 162 .SH EXIT CODES
 163 If \fIcapname\fR is of type boolean, a value of \fB0\fR is set for
 164 TRUE and \fB1\fR for FALSE unless the \fB-S\fR option is used.
 165
 166 If \fIcapname\fR is of type string, a value of \fB0\fR is set if the
 167 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
 168 \fIcapname\fR is returned on standard output); a value of \fB1\fR is
 169 set if \fIcapname\fR is not defined for this terminal \fItype\fR (a
 170 null value is returned on standard output).
 171
 172 If \fIcapname\fR is of type boolean or string and the \fB-S\fR option
 173 is used, a value of \fB0\fR is returned to indicate that all lines
 174 were successful.  No indication of which line failed can be given so
 175 exit code \fB1\fR will never appear.  Exit codes \fB2\fR, \fB3\fR, and
 176 \fB4\fR retain their usual interpretation.
 177
 178 If \fIcapname\fR is of type integer, a value of \fB0\fR is always set,
 179 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
 180 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
 181 the user must test the value of standard output.  A value of \fB-1\fR
 182 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
 183
 184 Any other exit code indicates an error; see the DIAGNOSTICS section.
 185 .SH DIAGNOSTICS
 186 \fBtput\fR prints the following error messages and sets the corresponding exit
 187 codes.
 188
 189 .TS
 190 l l.
 191 exit code       error message
 192 \fB0\fR (\fIcapname\fR is a numeric variable that is not specified in the
 193         \fBterminfo\fR(\*n) database for this terminal type, e.g.
 194         \fBtput -T450 lines\fR and \fBtput -T2621 xmc\fR)
 195 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
 196 \fB2\fR usage error
 197 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
 198 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
 199 .TE
 200 .SH PORTABILITY
 201 The \fBlongname\fR and \fB-S\fR options, and the parameter-substitution
 202 features used in the \fBcup\fR example, are not supported in BSD curses or in
 203 AT&T/USL curses before SVr4.
 204 .\"#
 205 .\"# The following sets edit modes for GNU EMACS
 206 .\"# Local Variables:
 207 .\"# mode:nroff
 208 .\"# fill-column:79
 209 .\"# End: