]> ncurses.scripts.mit.edu Git - ncurses.git/blob - man/tput.1
ncurses 6.4 - patch 20231223
[ncurses.git] / man / tput.1
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
5 .\"                                                                          *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
7 .\" copy of this software and associated documentation files (the            *
8 .\" "Software"), to deal in the Software without restriction, including      *
9 .\" without limitation the rights to use, copy, modify, merge, publish,      *
10 .\" distribute, distribute with modifications, sublicense, and/or sell       *
11 .\" copies of the Software, and to permit persons to whom the Software is    *
12 .\" furnished to do so, subject to the following conditions:                 *
13 .\"                                                                          *
14 .\" The above copyright notice and this permission notice shall be included  *
15 .\" in all copies or substantial portions of the Software.                   *
16 .\"                                                                          *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
24 .\"                                                                          *
25 .\" Except as contained in this notice, the name(s) of the above copyright   *
26 .\" holders shall not be used in advertising or otherwise to promote the     *
27 .\" sale, use or other dealings in this Software without prior written       *
28 .\" authorization.                                                           *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp $
32 .TH @TPUT@ 1 2023-12-23 "ncurses 6.4" "User commands"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el   .ds `` ""
40 .ie t .ds '' ''
41 .el   .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n  .IP \(bu 4
46 .el    .IP \(bu 2
47 ..
48 .ds d @TERMINFO@
49 .SH NAME
50 \fB\%@TPUT@\fP,
51 \fB\%reset\fP \-
52 initialize a terminal or query \fI\%term\%info\fP database
53 .SH SYNOPSIS
54 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fIcap-code\fP [\fIparameter\fP .\|.\|.]
55 .PP
56 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
57 .PP
58 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
59 .PP
60 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBreset\fP
61 .PP
62 \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fBlongname\fP
63 .PP
64 \fB@TPUT@ \-S\fP
65 .PP
66 \fB@TPUT@ \-V\fP
67 .SH DESCRIPTION
68 \fB@TPUT@\fP uses the \fI\%term\%info\fP library and database to make
69 the values of terminal-specific capabilities and information available
70 to the shell,
71 to initialize or reset the terminal,
72 or report the long name of the current
73 (or specified)
74 terminal type.
75 When retrieving capability values,
76 the result depends upon the capability's type.
77 .TP 9 \" "Boolean" + 2n
78 Boolean
79 \fB@TPUT@\fP sets its exit status to
80 .B 0
81 if the terminal possesses
82 .I cap-code,
83 and
84 .B 1
85 if it does not.
86 .TP
87 integer
88 \fB@TPUT@\fP writes
89 .IR cap-code 's
90 decimal value to the standard output stream if defined
91 .RB ( \-1
92 if it is not)
93 followed by a newline.
94 .TP
95 string
96 \fB@TPUT@\fP writes
97 .IR cap-code 's
98 value to the standard output stream if defined,
99 without a trailing newline.
100 .PP
101 Before using a value returned on the standard output,
102 the application should test \fB@TPUT@\fP's exit status
103 (for example,
104 using \fB$?\fP in \fIsh\fP(1))
105 to be sure it is \fB0\fP;
106 see sections \*(``EXIT STATUS\*('' and \*(``DIAGNOSTICS\*('' below.
107 For a complete list of
108 .I cap-codes,
109 see \fB\%terminfo\fP(5).
110 .SS Options
111 .TP
112 \fB\-S\fP
113 allows more than one capability per invocation of \fB@TPUT@\fP.
114 The capabilities must be passed to \fB@TPUT@\fP from the standard input
115 instead of from the command line
116 (see example).
117 Only one \fIcap-code\fP is allowed per line.
118 The \fB\-S\fP option changes the
119 meaning of the \fB0\fP and \fB1\fP Boolean and string exit statuses
120 (see section \*(``EXIT STATUS\*('' below).
121 .IP
122 Because some capabilities may use
123 \fIstring\fP parameters rather than \fInumbers\fP,
124 \fB@TPUT@\fP uses a table and the presence of parameters in its input
125 to decide whether to use \fBtparm\fP(3X),
126 and how to interpret the parameters.
127 .TP
128 \fB\-T\fItype\fR
129 indicates the \fItype\fP of terminal.
130 Normally this option is
131 unnecessary, because the default is taken from the environment
132 variable \fITERM\fP.
133 If \fB\-T\fP is specified, then the shell
134 variables \fILINES\fP and \fI\%COLUMNS\fP will also be ignored.
135 .TP
136 \fB\-V\fP
137 reports the version of \fI\%ncurses\fP which was used in this program,
138 and exits.
139 .TP
140 .B \-x
141 prevents \fB\%@TPUT@\fP from attempting to clear the scrollback buffer.
142 .SS Commands
143 A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
144 special; they are defined by the \fB@TPUT@\fP program.
145 The others are the names of \fIcapabilities\fP from the terminal database
146 (see \fB\%terminfo\fP(5) for a list).
147 Although \fBinit\fP and \fBreset\fP resemble capability names,
148 \fB@TPUT@\fP uses several capabilities to perform these special functions.
149 .TP
150 \fIcap-code\fP
151 indicates the capability from the terminal database.
152 .IP
153 If the capability is a string that takes parameters, the arguments
154 following the capability will be used as parameters for the string.
155 .IP
156 Most parameters are numbers.
157 Only a few terminal capabilities require string parameters;
158 \fB@TPUT@\fP uses a table to decide which to pass as strings.
159 Normally \fB@TPUT@\fP uses \fBtparm\fP(3X) to perform the substitution.
160 If no parameters are given for the capability,
161 \fB@TPUT@\fP writes the string without performing the substitution.
162 .TP
163 \fBinit\fP
164 If the terminal database is present and an entry for the user's
165 terminal exists (see \fB\-T\fItype\fR, above), the following will
166 occur:
167 .RS
168 .TP 5
169 (1)
170 first, \fB@TPUT@\fP retrieves the current terminal mode settings
171 for your terminal.
172 It does this by successively testing
173 .RS
174 .bP
175 the standard error,
176 .bP
177 standard output,
178 .bP
179 standard input and
180 .bP
181 ultimately \*(``/dev/tty\*(''
182 .RE
183 .IP
184 to obtain terminal settings.
185 Having retrieved these settings, \fB@TPUT@\fP remembers which
186 file descriptor to use when updating settings.
187 .TP
188 (2)
189 if the window size cannot be obtained from the operating system,
190 but the terminal description
191 (or environment,
192 e.g.,
193 \fILINES\fP and \fI\%COLUMNS\fP variables specify this),
194 update the operating system's notion of the window size.
195 .TP
196 (3)
197 the terminal modes will be updated:
198 .RS
199 .bP
200 any delays (e.g., newline) specified in the entry will
201 be set in the tty driver,
202 .bP
203 tabs expansion will be turned on or off according to
204 the specification in the entry, and
205 .bP
206 if tabs are not expanded,
207 standard tabs will be set (every 8 spaces).
208 .RE
209 .TP
210 (4)
211 if present, the terminal's initialization strings will be
212 output as detailed in the \fB\%terminfo\fP(5) section on
213 .IR "Tabs and Initialization" ,
214 .TP
215 (5)
216 output is flushed.
217 .RE
218 .IP
219 If an entry does not
220 contain the information needed for any of these activities,
221 that activity will silently be skipped.
222 .TP
223 \fBreset\fP
224 This is similar to \fBinit\fP, with two differences:
225 .RS
226 .TP 5
227 (1)
228 before any other initialization,
229 the terminal modes will be reset to a \*(``sane\*('' state:
230 .RS
231 .bP
232 set cooked and echo modes,
233 .bP
234 turn off cbreak and raw modes,
235 .bP
236 turn on newline translation and
237 .bP
238 reset any unset special characters to their default values
239 .RE
240 .TP 5
241 (2)
242 Instead of putting out \fIinitialization\fP strings, the terminal's
243 \fIreset\fP strings will be output if present
244 (\fBrs1\fP, \fBrs2\fP, \fBrs3\fP, \fBrf\fP).
245 If the \fIreset\fP strings are not present, but \fIinitialization\fP
246 strings are, the \fIinitialization\fP strings will be output.
247 .RE
248 .IP
249 Otherwise, \fBreset\fP acts identically to \fBinit\fP.
250 .TP
251 .B longname
252 If the terminal database is present and an entry for the user's terminal
253 exists
254 (see
255 .B \-T
256 .I type
257 above),
258 \fB\%@TPUT@\fP reports the terminal's description
259 (or \*(``long name\*('')
260 to the standard output,
261 without a trailing newline.
262 See \fBterm\fP(5).
263 .SS Aliases
264 \fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
265 commands specially:
266 it allows for the possibility that it is invoked by a link with those names.
267 .PP
268 If \fB@TPUT@\fP is invoked by a link named \fBreset\fP, this has the
269 same effect as \fB@TPUT@ reset\fP.
270 The \fB@TSET@\fP(1) utility also treats a link named \fBreset\fP specially.
271 .PP
272 Before \fI\%ncurses\fP 6.1,
273 the two utilities were different from each other:
274 .bP
275 \fB@TSET@\fP utility reset the terminal modes and special characters
276 (not done with \fB@TPUT@\fP).
277 .bP
278 On the other hand, \fB@TSET@\fP's repertoire of terminal capabilities for
279 resetting the terminal was more limited,
280 i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
281 in contrast to the tab-stops and margins which are set by this utility.
282 .bP
283 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
284 because of this difference with resetting terminal modes and special characters.
285 .PP
286 With the changes made for \fI\%ncurses\fP 6.1,
287 the \fIreset\fP feature of the two programs is (mostly) the same.
288 A few differences remain:
289 .bP
290 The \fB@TSET@\fP program waits one second when resetting,
291 in case it happens to be a hardware terminal.
292 .bP
293 The two programs write the terminal initialization strings
294 to different streams (i.e., the standard error for \fB@TSET@\fP and the
295 standard output for \fB@TPUT@\fP).
296 .IP
297 \fBNote:\fP although these programs write to different streams,
298 redirecting their output to a file will capture only part of their actions.
299 The changes to the terminal modes are not affected by redirecting the output.
300 .PP
301 If \fB@TPUT@\fP is invoked by a link named \fBinit\fP, this has the
302 same effect as \fB@TPUT@ init\fP.
303 Again, you are less likely to use that link because another program
304 named \fBinit\fP has a more well-established use.
305 .SS "Terminal Size"
306 Besides the special commands (e.g., \fBclear\fP),
307 @TPUT@ treats certain terminfo capabilities specially:
308 \fBlines\fP and \fBcols\fP.
309 @TPUT@ calls \fBsetupterm\fP(3X) to obtain the terminal size:
310 .bP
311 first, it gets the size from the terminal database
312 (which generally is not provided for terminal emulators
313 which do not have a fixed window size)
314 .bP
315 then it asks the operating system for the terminal's size
316 (which generally works, unless connecting via a serial line which
317 does not support \fINAWS\fP: negotiations about window size).
318 .bP
319 finally, it inspects the environment variables \fILINES\fP and
320 \fI\%COLUMNS\fP which may override the terminal size.
321 .PP
322 If the \fB\-T\fP option is given
323 @TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP,
324 relying upon the operating system (or finally, the terminal database).
325 .SH EXIT STATUS
326 If the \fB\-S\fP option is used,
327 \fB@TPUT@\fP checks for errors from each line,
328 and if any errors are found, will set the exit status to 4 plus the
329 number of lines with errors.
330 If no errors are found, the exit status is \fB0\fP.
331 No indication of which line failed can be given so
332 exit status \fB1\fP will never appear.
333 Exit statuses \fB2\fP, \fB3\fP, and
334 \fB4\fP retain their usual interpretation.
335 If the \fB\-S\fP option is not used,
336 the exit status depends on the type of \fIcap-code\fP:
337 .RS 3
338 .TP
339 .I Boolean
340 a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE.
341 .TP
342 .I string
343 a value of \fB0\fP is set if the
344 \fIcap-code\fP is defined for this terminal \fItype\fP (the value of
345 \fIcap-code\fP is returned on standard output);
346 a value of \fB1\fP is set if \fIcap-code\fP
347 is not defined for this terminal \fItype\fP
348 (nothing is written to standard output).
349 .TP
350 .I integer
351 a value of \fB0\fP is always set,
352 whether or not \fIcap-code\fP is defined for this terminal \fItype\fP.
353 To determine if \fIcap-code\fP is defined for this terminal \fItype\fP,
354 the user must test the value written to standard output.
355 A value of \fB\-1\fP
356 means that \fIcap-code\fP is not defined for this terminal \fItype\fP.
357 .TP
358 .I other
359 \fBreset\fP or \fBinit\fP may fail to find their respective files.
360 In that case, the exit status is set to 4 + \fBerrno\fP.
361 .RE
362 .PP
363 Any other exit status indicates an error;
364 see section \*(``DIAGNOSTICS\*('' below.
365 .SH DIAGNOSTICS
366 \fB@TPUT@\fP prints the following error messages and sets the
367 corresponding exit statuses.
368 .PP
369 .ne 15
370 .TS
371 l l.
372 exit status     error message
373 =
374 \fB0\fP T{
375 (\fIcap-code\fP is a numeric variable that is not specified in the
376 \fB\%terminfo\fP(5) database for this terminal type, e.g.
377 \fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP)
378 T}
379 \fB1\fP no error message is printed, see the \fBEXIT STATUS\fP section.
380 \fB2\fP usage error
381 \fB3\fP unknown terminal \fItype\fP or no \fI\%term\%info\fP database
382 \fB4\fP unknown \fI\%term\%info\fP capability \fIcap-code\fP
383 \fB>4\fP        error occurred in \-S
384 =
385 .TE
386 .SH FILES
387 .TP
388 .I @DATADIR@/tabset
389 tab stop initialization database
390 .TP
391 .I \*d
392 compiled terminal description database
393 .SH PORTABILITY
394 This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
395 two important areas:
396 .bP
397 \fB@TPUT@\fP \fIcap-code\fP writes to the standard output.
398 That need not be a regular terminal.
399 However, the subcommands which manipulate terminal modes
400 may not use the standard output.
401 .IP
402 The AT&T implementation's \fBinit\fP and \fBreset\fP commands
403 use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
404 It successively tries standard output, standard error, standard input
405 before falling back to \*(``/dev/tty\*('' and finally just assumes
406 a 1200Bd terminal.
407 When updating terminal modes, it ignores errors.
408 .IP
409 Until changes made after \fI\%ncurses\fP 6.0,
410 \fB@TPUT@\fP did not modify terminal modes.
411 \fB@TPUT@\fP now uses a similar scheme,
412 using functions shared with \fB@TSET@\fP
413 (and ultimately based on the 4.4BSD \fBtset\fP).
414 If it is not able to open a terminal, e.g., when running in \fBcron\fP(1),
415 \fB@TPUT@\fP will return an error.
416 .bP
417 AT&T \fBtput\fP guesses the type of its \fIcap-code\fP operands by
418 seeing if all of the characters are numeric,
419 or not.
420 .IP
421 Most implementations which provide support for \fIcap-code\fP operands
422 use the \fBtparm\fP function to expand parameters in it.
423 That function expects a mixture of numeric and string parameters,
424 requiring \fB@TPUT@\fP to know which type to use.
425 .IP
426 This implementation uses a table to determine the parameter types for
427 the standard \fIcap-code\fP operands, and an internal library
428 function to analyze nonstandard \fIcap-code\fP operands.
429 .IP
430 Besides providing more reliable operation than AT&T's utility,
431 a portability problem is introduced by this analysis:
432 An OpenBSD developer adapted the internal library function from
433 \fI\%ncurses\fP to port NetBSD's termcap-based \fBtput\fP to terminfo.
434 That had been modified to interpret multiple commands on a line.
435 Portable applications should not rely upon this feature;
436 \fI\%ncurses\fP provides it to support applications written
437 specifically for OpenBSD.
438 .PP
439 This implementation (unlike others) can accept both \fItermcap\fP
440 and \fIterminfo\fP names for the \fIcap-code\fP feature,
441 if
442 \fItermcap\fP support is compiled in.
443 However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
444 ambiguities in this case (and the \fIterminfo\fP name is assumed):
445 .bP
446 The \fItermcap\fP name \fBdl\fP corresponds to
447 the \fIterminfo\fP name \fBdl1\fP (delete one line).
448 .br
449 The \fIterminfo\fP name \fBdl\fP corresponds to
450 the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
451 .bP
452 The \fItermcap\fP name \fBed\fP corresponds to
453 the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
454 .br
455 The \fIterminfo\fP name \fBed\fP corresponds to
456 the \fItermcap\fP name \fBcd\fP (clear to end of screen).
457 .PP
458 The \fBlongname\fP and \fB\-S\fP options, and the parameter-substitution
459 features used in the \fBcup\fP example,
460 were not supported in
461 AT&T/USL
462 .I curses
463 before SVr4 (1989).
464 Later, 4.3BSD-Reno (1990) added support for \fBlongname\fP,
465 .\" longname was added in October 1989.
466 and NetBSD (1994) added support for the parameter-substitution features.
467 .PP
468 IEEE Std 1003.1/The Open Group  Base Specifications Issue 7 (POSIX.1-2008)
469 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
470 There are a few interesting observations to make regarding that:
471 .bP
472 In this implementation,
473 \fBclear\fP is part of the \fIcap-code\fP support.
474 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
475 capabilities.
476 .bP
477 Other implementations of \fBtput\fP on
478 SVr4-based systems such as Solaris, IRIX64 and HP-UX
479 as well as others such as AIX and Tru64
480 provide support for \fIcap-code\fP operands.
481 .bP
482 A few platforms such as FreeBSD recognize termcap names rather
483 than terminfo capability names in their respective \fBtput\fP commands.
484 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
485 Before that, it (like FreeBSD) recognized termcap names.
486 .IP
487 Beginning in 2021, FreeBSD uses the \fI\%ncurses\fP \fBtput\fP,
488 configured for both terminfo (tested first) and termcap (as a fallback).
489 .PP
490 Because (apparently) \fIall\fP of the certified Unix systems
491 support the full set of capability names, the reasoning for documenting
492 only a few may not be apparent.
493 .bP
494 X/Open Curses Issue 7 documents \fBtput\fP differently,
495 with \fIcap-code\fP and the other features used in this implementation.
496 .bP
497 That is, there are two standards for \fBtput\fP:
498 POSIX (a subset) and X/Open Curses (the full implementation).
499 POSIX documents a subset to avoid the complication of including X/Open Curses
500 and the terminal capabilities database.
501 .bP
502 While it is certainly possible to write a \fBtput\fP program
503 without using
504 .I curses,
505 no system with a
506 .I curses
507 implementation provides a \fBtput\fP utility that does not also supply
508 the \fIcap-code\fP feature.
509 .PP
510 X/Open Curses Issue 7 (2009) is the first version to document utilities.
511 However that part of X/Open Curses does not follow existing practice
512 (that is,
513 System\ V
514 .I curses
515 behavior).
516 .bP
517 It assigns exit status 4 to \*(``invalid operand\*('',
518 which may be the same as \fIunknown capability\fP.
519 For instance, the source code for Solaris' xcurses uses the term
520 \*(``invalid\*('' in this case.
521 .bP
522 It assigns exit status 255 to a numeric variable that is not specified in
523 the terminfo database.
524 That likely is a documentation error,
525 confusing the \fB\-1\fP written to the standard output for an absent
526 or cancelled numeric value versus an (unsigned) exit status.
527 .PP
528 The various Unix systems (AIX, HP-UX, Solaris) use the same exit statuses
529 as \fI\%ncurses\fP.
530 .PP
531 NetBSD curses documents different exit statuses which do not correspond
532 to either \fI\%ncurses\fP or X/Open.
533 .SH HISTORY
534 The \fBtput\fP command was begun by Bill Joy in 1980.
535 The initial version only cleared the screen.
536 .PP
537 AT&T System V provided a different \fBtput\fP command:
538 .bP
539 SVr2 provided a rudimentary \fBtput\fP
540 which checked the parameter against each
541 predefined capability and returned the corresponding value.
542 This version of \fBtput\fP did not use \fBtparm\fP(3X) for
543 the capabilities which are parameterized.
544 .bP
545 SVr3 replaced that, a year later, by a more extensive program
546 whose \fBinit\fP and \fBreset\fP subcommands
547 (more than half the program) were incorporated from
548 the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
549 .bP
550 SVr4 added color initialization using the \fBorig_colors\fP and
551 \fBorig_pair\fP capabilities in the \fBinit\fP subcommand.
552 .PP
553 Keith Bostic replaced the BSD \fBtput\fP command in 1989
554 with a new implementation
555 based on the AT&T System V program \fBtput\fP.
556 Like the AT&T program, Bostic's version
557 accepted some parameters named for \fIterminfo\fP capabilities
558 (\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
559 However (because he had only \fItermcap\fP available),
560 it accepted \fItermcap\fP names for other capabilities.
561 Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
562 as the earlier BSD \fBtset\fP had done.
563 .PP
564 At the same time, Bostic added a shell script named \*(``clear\*('',
565 which used \fBtput\fP to clear the screen.
566 .PP
567 Both of these appeared in 4.4BSD,
568 becoming the \*(``modern\*('' BSD implementation of \fBtput\fP.
569 .PP
570 This implementation of \fBtput\fP began from a different source than
571 AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on
572 \fIcomp.sources.unix\fP in December 1992.
573 Ridge's program made more sophisticated use of the terminal capabilities
574 than the BSD program.
575 Eric Raymond used that \fBtput\fP program
576 (and other parts of \fImytinfo\fP) in \fI\%ncurses\fP in June 1995.
577 Using the portions dealing with terminal capabilities
578 almost without change,
579 Raymond made improvements to the way the command-line parameters
580 were handled.
581 .SH EXAMPLES
582 .TP 5
583 \fB@TPUT@ init\fP
584 Initialize the terminal according to the type of
585 terminal in the environment variable \fITERM\fP.
586 This command should be included in everyone's .profile after
587 the environment variable \fITERM\fP has been exported,
588 as illustrated on the \fBprofile\fP(5) manual page.
589 .TP 5
590 \fB@TPUT@ \-T5620 reset\fP
591 Reset an AT&T 5620 terminal, overriding the type of
592 terminal in the environment variable \fITERM\fP.
593 .TP 5
594 \fB@TPUT@ cup 0 0\fP
595 Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
596 (the upper left corner of the screen, usually known as the \*(``home\*(''
597 cursor position).
598 .TP 5
599 \fB@TPUT@ clear\fP
600 Echo the clear-screen sequence for the current terminal.
601 .TP 5
602 \fB@TPUT@ cols\fP
603 Print the number of columns for the current terminal.
604 .TP 5
605 \fB@TPUT@ \-T450 cols\fP
606 Print the number of columns for the 450 terminal.
607 .TP 5
608 \fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
609 Set the shell variables \fBbold\fP, to begin stand-out mode
610 sequence, and \fBoffbold\fP, to end standout mode sequence,
611 for the current terminal.
612 This might be followed by a
613 prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
614 .TP 5
615 \fB@TPUT@ hc\fP
616 Set exit status to indicate if the current terminal is a hard copy terminal.
617 .TP 5
618 \fB@TPUT@ cup 23 4\fP
619 Send the sequence to move the cursor to row 23, column 4.
620 .TP 5
621 \fB@TPUT@ cup\fP
622 Send the terminfo string for cursor-movement, with no parameters substituted.
623 .TP 5
624 \fB@TPUT@ longname\fP
625 Print the long name from the \fI\%term\%info\fP database for the
626 type of terminal specified in the environment
627 variable \fITERM\fP.
628 .TP 5
629 \fB@TPUT@ \-S\fP
630 The \fB\-S\fP option can be profitably used with a shell
631 \*(``here document\*(''.
632 .IP
633 .EX
634 $ \fB@TPUT@ \-S <<!\fP
635 > \fBclear\fP
636 > \fBcup 10 10\fP
637 > \fBbold\fP
638 > \fB!\fP
639 .EE
640 .IP
641 We see \fB@TPUT@\fP processing several capabilities in one invocation.
642 It clears the screen,
643 moves the cursor to position
644 (10, 10)
645 and turns on bold
646 (extra bright)
647 mode.
648 .IP
649 The same sequence of commands can be combined using the OpenBSD feature:
650 .IP
651 .EX
652 $ \fB@TPUT@ \fBclear\fP \fBcup 10 10\fP \fBbold\fP
653 .EE
654 .SH SEE ALSO
655 \fB\%@CLEAR@\fP(1),
656 \fB\%stty\fP(1),
657 \fB\%@TABS@\fP(1),
658 \fB\%@TSET@\fP(1),
659 \fB\%curs_termcap\fP(3X),
660 \fB\%terminfo\fP(5)