| blob | 973a35b08845d9fe4ee32ae10210d765489bc5d1 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH TPUT 1 "Feb 1, 1995"
11 .SH NAME
12 tput \- initialize a terminal or query terminfo database
13 .SH SYNOPSIS
14 .LP
15 .nf
16 \fBtput\fR [\fB-T\fR \fItype\fR] \fIcapname\fR [\fIparm\fR]...
17 .fi
19 .LP
20 .nf
21 \fBtput\fR \fB-S\fR <<
22 .fi
24 .SH DESCRIPTION
25 .sp
26 .LP
27 The \fBtput\fR utility uses the \fBterminfo\fR database to make the values of
28 terminal-dependent capabilities and information available to the shell (see
29 \fBsh\fR(1)); to clear, initialize or reset the terminal; or to return the long
30 name of the requested terminal type. \fBtput\fR outputs a string if the
31 capability attribute (\fIcapname\fR) is of type string, or an integer if the
32 attribute is of type integer. If the attribute is of type boolean, \fBtput\fR
33 simply sets the exit status (\fB0\fR for \fBTRUE\fR if the terminal has the
34 capability, \fB1\fR for \fBFALSE\fR if it does not), and produces no output.
35 Before using a value returned on standard output, the user should test the exit
36 status (\fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR. See the EXIT
37 STATUS section.
38 .SH OPTIONS
39 .sp
40 .LP
41 The following options are supported:
42 .sp
43 .ne 2
44 .na
45 \fB\fB-T\fR\fItype\fR \fR
46 .ad
47 .RS 11n
48 Indicates the \fItype\fR of terminal. Normally this option is unnecessary,
49 because the default is taken from the environment variable \fBTERM\fR. If
50 \fB-T\fR is specified, then the shell variables \fBLINES\fR and \fBCOLUMNS\fR
51 and the layer size will not be referenced.
52 .RE
54 .sp
55 .ne 2
56 .na
57 \fB\fB-S\fR \fR
58 .ad
59 .RS 11n
60 Allows more than one capability per invocation of \fBtput\fR. The capabilities
61 must be passed to \fBtput\fR from the standard input instead of from the
62 command line (see the example in the EXAMPLES section). Only one \fIcapname\fR
63 is allowed per line. The \fB-S\fR option changes the meaning of the \fB0\fR and
64 \fB1\fR boolean and string exit statuses (see the EXAMPLES section).
65 .RE
67 .SH OPERANDS
68 .sp
69 .LP
70 The following operands are supported:
71 .sp
72 .ne 2
73 .na
74 \fB\fIcapname\fR \fR
75 .ad
76 .RS 12n
77 Indicates the capability attribute from the \fBterminfo\fR database. See
78 \fBterminfo\fR(4) for a complete list of capabilities and the \fIcapname\fR
79 associated with each.
80 .sp
81 The following strings will be supported as operands by the implementation in
82 the "C" locale:
83 .sp
84 .ne 2
85 .na
86 \fB\fBclear\fR \fR
87 .ad
88 .RS 13n
89 Display the clear-screen sequence.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fBinit\fR \fR
96 .ad
97 .RS 13n
98 If the \fBterminfo\fR database is present and an entry for the user's terminal
99 exists (see \fB-T\fR\fItype\fR, above), the following will occur:
100 .RS +4
101 .TP
102 1.
103 if present, the terminal's initialization strings will be output (\fBis1\fR,
104 \fBis2\fR, \fBis3\fR, \fBif\fR, \fBiprog\fR),
105 .RE
106 .RS +4
107 .TP
108 2.
109 any delays (for instance, newline) specified in the entry will be set in the
110 tty driver,
111 .RE
112 .RS +4
113 .TP
114 3.
115 tabs expansion will be turned on or off according to the specification in
116 the entry, and
117 .RE
118 .RS +4
119 .TP
120 4.
121 if tabs are not expanded, standard tabs will be set (every 8 spaces). If an
122 entry does not contain the information needed for any of the four above
123 activities, that activity will silently be skipped.
124 .RE
125 .RE
127 .sp
128 .ne 2
129 .na
130 \fB\fBreset\fR \fR
131 .ad
132 .RS 13n
133 Instead of putting out initialization strings, the terminal's reset strings
134 will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR). If the
135 reset strings are not present, but initialization strings are, the
136 initialization strings will be output. Otherwise, \fBreset\fR acts identically
137 to \fBinit\fR.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fBlongname\fR \fR
144 .ad
145 .RS 13n
146 If the \fBterminfo\fR database is present and an entry for the user's terminal
147 exists (see \fB-T\fR\fItype\fR above), then the long name of the terminal will
148 be put out. The long name is the last name in the first line of the terminal's
149 description in the \fBterminfo\fR database (see \fBterm\fR(5)).
150 .RE
152 .RE
154 .sp
155 .ne 2
156 .na
157 \fB\fIparm\fR \fR
158 .ad
159 .RS 12n
160 If the attribute is a string that takes parameters, the argument \fIparm\fR
161 will be instantiated into the string. An all numeric argument will be passed to
162 the attribute as a number.
163 .RE
165 .SH EXAMPLES
166 .LP
167 \fBExample 1 \fRInitializing the terminal according to TERM
168 .sp
169 .LP
170 This example initializes the terminal according to the type of terminal in the
171 environment variable \fBTERM\fR. This command should be included in
172 everyone's .profile after the environment variable \fBTERM\fR has been exported, as
173 illustrated on the \fBprofile\fR(4) manual page.
175 .sp
176 .in +2
177 .nf
178 example% \fBtput init\fR
179 .fi
180 .in -2
181 .sp
183 .LP
184 \fBExample 2 \fRResetting a terminal
185 .sp
186 .LP
187 This example resets an AT&T 5620 terminal, overriding the type of terminal in
188 the environment variable \fBTERM\fR:
190 .sp
191 .in +2
192 .nf
193 example% \fBtput -T5620 reset\fR
194 .fi
195 .in -2
196 .sp
198 .LP
199 \fBExample 3 \fRMoving the cursor
200 .sp
201 .LP
202 The following example sends the sequence to move the cursor to row \fB0\fR,
203 column \fB0\fR (the upper left corner of the screen, usually known as the
204 "home" cursor position).
206 .sp
207 .in +2
208 .nf
209 example% \fBtput cup 0 0\fR
210 .fi
211 .in -2
212 .sp
214 .sp
215 .LP
216 This next example sends the sequence to move the cursor to row \fB23\fR, column
217 \fB4\fR.
219 .sp
220 .in +2
221 .nf
222 example% \fBtput cup 23 4\fR
223 .fi
224 .in -2
225 .sp
227 .LP
228 \fBExample 4 \fREchoing the clear-screen sequence
229 .sp
230 .LP
231 This example echos the clear-screen sequence for the current terminal.
233 .sp
234 .in +2
235 .nf
236 example% \fBtput clear\fR
237 .fi
238 .in -2
239 .sp
241 .LP
242 \fBExample 5 \fRPrinting the number of columns
243 .sp
244 .LP
245 This command prints the number of columns for the current terminal.
247 .sp
248 .in +2
249 .nf
250 example% \fBtput cols\fR
251 .fi
252 .in -2
253 .sp
255 .sp
256 .LP
257 The following command prints the number of columns for the 450 terminal.
259 .sp
260 .in +2
261 .nf
262 example% \fBtput -T450 cols\fR
263 .fi
264 .in -2
265 .sp
267 .LP
268 \fBExample 6 \fRSetting shell variables
269 .sp
270 .LP
271 This example sets the shell variables \fBbold\fR, to begin stand-out mode
272 sequence, and \fBoffbold\fR, to end standout mode sequence, for the current
273 terminal. This might be followed by a prompt:
275 .sp
276 .in +2
277 .nf
278 \fBecho "${bold}Please type in your name: ${offbold}\ec"\fR
279 example% \fBbold='tput smso'\fR
280 example% \fBoffbold='tput rmso'\fR
281 .fi
282 .in -2
283 .sp
285 .LP
286 \fBExample 7 \fRSetting the exit status
287 .sp
288 .LP
289 This example sets the exit status to indicate if the current terminal is a
290 hardcopy terminal.
292 .sp
293 .in +2
294 .nf
295 example% \fBtput hc\fR
296 .fi
297 .in -2
298 .sp
300 .LP
301 \fBExample 8 \fRPrinting the long name from terminfo
302 .sp
303 .LP
304 This command prints the long name from the \fBterminfo\fR database for the type
305 of terminal specified in the environment variable \fBTERM\fR.
307 .sp
308 .in +2
309 .nf
310 example% \fBtput longname\fR
311 .fi
312 .in -2
313 .sp
315 .LP
316 \fBExample 9 \fRProcessing several capabilities with one invocation
317 .sp
318 .LP
319 This example shows \fBtput\fR processing several capabilities in one
320 invocation. This example clears the screen, moves the cursor to position
321 \fB10\fR, \fB10\fR and turns on \fBbold\fR (extra bright) mode. The list is
322 terminated by an exclamation mark (\fB!\fR) on a line by itself.
324 .sp
325 .in +2
326 .nf
327 example% \fBtput -S <<!
328 > clear
329 > cup 10 10
330 > bold
331 > !\fR
332 .fi
333 .in -2
334 .sp
336 .SH ENVIRONMENT VARIABLES
337 .sp
338 .LP
339 See \fBenviron\fR(5) for descriptions of the following environment variables
340 that affect the execution of \fBtput\fR: \fBLANG\fR, \fBLC_ALL\fR,
341 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
342 .sp
343 .ne 2
344 .na
345 \fB\fBTERM\fR \fR
346 .ad
347 .RS 9n
348 Determine the terminal type. If this variable is unset or null, and if the
349 \fB-T\fR option is not specified, an unspecified default terminal type will be
350 used.
351 .RE
353 .SH EXIT STATUS
354 .sp
355 .LP
356 The following exit values are returned:
357 .sp
358 .ne 2
359 .na
360 \fB\fB0\fR \fR
361 .ad
362 .RS 10n
363 .RS +4
364 .TP
365 .ie t \(bu
366 .el o
367 If \fIcapname\fR is of type boolean and \fB-S\fR is not specified, indicates
368 \fBTRUE\fR.
369 .RE
370 .RS +4
371 .TP
372 .ie t \(bu
373 .el o
374 If \fIcapname\fR is of type string and \fB-S\fR is not specified, indicates
375 \fIcapname\fR is defined for this terminal type.
376 .RE
377 .RS +4
378 .TP
379 .ie t \(bu
380 .el o
381 If \fIcapname\fR is of type boolean or string and \fB-S\fR is specified,
382 indicates that all lines were successful.
383 .RE
384 .RS +4
385 .TP
386 .ie t \(bu
387 .el o
388 \fIcapname\fR is of type integer.
389 .RE
390 .RS +4
391 .TP
392 .ie t \(bu
393 .el o
394 The requested string was written successfully.
395 .RE
396 .RE
398 .sp
399 .ne 2
400 .na
401 \fB\fB1\fR \fR
402 .ad
403 .RS 10n
404 .RS +4
405 .TP
406 .ie t \(bu
407 .el o
408 If \fIcapname\fR is of type boolean and \fB-S\fR is not specified, indicates
409 \fBFALSE\fR.
410 .RE
411 .RS +4
412 .TP
413 .ie t \(bu
414 .el o
415 If \fIcapname\fR is of type string and \fB-S\fR is not specified, indicates
416 that \fIcapname\fR is not defined for this terminal type.
417 .RE
418 .RE
420 .sp
421 .ne 2
422 .na
423 \fB\fB2\fR \fR
424 .ad
425 .RS 10n
426 Usage error.
427 .RE
429 .sp
430 .ne 2
431 .na
432 \fB\fB3\fR \fR
433 .ad
434 .RS 10n
435 No information is available about the specified terminal type.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fB4\fR \fR
442 .ad
443 .RS 10n
444 The specified operand is invalid.
445 .RE
447 .sp
448 .ne 2
449 .na
450 \fB\fB>4\fR \fR
451 .ad
452 .RS 10n
453 An error occurred.
454 .RE
456 .sp
457 .ne 2
458 .na
459 \fB\fB\(mi1\fR \fR
460 .ad
461 .RS 10n
462 \fIcapname\fR is a numeric variable that is not specified in the \fBterminfo\fR
463 database. For instance, \fBtput\fR \fB-T450\fR lines and \fBtput\fR
464 \fB-T2621\fR xmc.
465 .RE
467 .SH FILES
468 .sp
469 .ne 2
470 .na
471 \fB\fB/usr/include/curses.h\fR \fR
472 .ad
473 .sp .6
474 .RS 4n
475 \fBcurses\fR(3CURSES) header
476 .RE
478 .sp
479 .ne 2
480 .na
481 \fB\fB/usr/include/term.h\fR \fR
482 .ad
483 .sp .6
484 .RS 4n
485 \fBterminfo\fR header
486 .RE
488 .sp
489 .ne 2
490 .na
491 \fB\fB/usr/lib/tabset/*\fR \fR
492 .ad
493 .sp .6
494 .RS 4n
495 Tab settings for some terminals, in a format appropriate to be output to the
496 terminal (escape sequences that set margins and tabs). For more information,
497 see the "Tabs and Initialization" section of \fBterminfo\fR(4)
498 .RE
500 .sp
501 .ne 2
502 .na
503 \fB\fB/usr/share/lib/terminfo/?/*\fR \fR
504 .ad
505 .sp .6
506 .RS 4n
507 compiled terminal description database
508 .RE
510 .SH ATTRIBUTES
511 .sp
512 .LP
513 See \fBattributes\fR(5) for descriptions of the following attributes:
514 .sp
516 .sp
517 .TS
518 box;
519 c | c
520 l | l .
521 ATTRIBUTE TYPE ATTRIBUTE VALUE
522 _
523 Interface Stability Standard
524 .TE
526 .SH SEE ALSO
527 .sp
528 .LP
529 \fBclear\fR(1), \fBsh\fR(1), \fBstty\fR(1), \fBtabs\fR(1),
530 \fBcurses\fR(3CURSES), \fBprofile\fR(4), \fBterminfo\fR(4),
531 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5), \fBterm\fR(5)