ncurses 4.1
[ncurses.git] / 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: