Debian Codegraph @

upstream/debian-trixie/man1/tput.1

raw
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2024,2025 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.132 2025/02/15 19:35:19 tom Exp $
32 .TH tput 1 2025-02-15 "ncurses 6.5" "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 .SH NAME
49 \fB\%tput\fP \-
50 initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
51 .SH SYNOPSIS
52 \fBtput\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP]
53 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
54 .PP
55 \fBtput\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
56 .PP
57 \fBtput\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
58 .PP
59 \fBtput\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
60 .PP
61 \fBtput\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
62 .PP
63 \fBtput\fP [\fB\-v\fP] \fB\-S\fP
64 .PP
65 \fBtput\fP [\fB\-v\fP] \fB\-V\fP
66 .SH DESCRIPTION
67 .B \%tput
68 uses the
69 .I \%term\%info
70 library and database to make terminal-specific capabilities and
71 information available to the shell,
72 to initialize or reset the terminal,
73 or
74 to report a description of the current
75 (or specified)
76 terminal type.
77 Terminal capabilities are accessed by
78 .IR cap-code .
79 .PP
80 \fB\%terminfo\fP(5) discusses terminal capabilities at length
81 and presents a complete list of
82 .IR cap-codes .
83 .PP
84 When retrieving capability values,
85 the result depends upon the capability's type.
86 .TP 9 \" "Boolean" + 2n
87 Boolean
88 .B \%tput
89 sets its exit status to
90 .B 0
91 if the terminal possesses
92 .IR cap-code ,
93 and
94 .B 1
95 if it does not.
96 .TP
97 numeric
98 .B \%tput
99 writes
100 .IR cap-code 's
101 decimal value to the standard output stream if defined
102 .RB ( \-1
103 if it is not)
104 followed by a newline.
105 .TP
106 string
107 .B \%tput
108 writes
109 .IR cap-code 's
110 value to the standard output stream if defined,
111 without a trailing newline.
112 .PP
113 Before using a value returned on the standard output,
114 the application should test
115 .B \%tput "'s"
116 exit status
117 to be sure it is 0;
118 see section \*(``EXIT STATUS\*('' below.
119 .SS Operands
120 Generally,
121 an operand is a
122 .IR cap-code ,
123 a capability code from the terminal database,
124 or a parameter thereto.
125 Three others are specially recognized by
126 .BR \%tput ":"
127 .BR init ,
128 .BR \%reset ,
129 and
130 .BR \%longname .
131 Although these resemble capability codes,
132 they in fact receive special handling;
133 we term them \*(``pseudo-capabilities\*(''.
134 .TP 11n \" "longname" + 2n + adjustment for PDF
135 .I cap-code
136 indicates a capability from the terminal database.
137 .IP
138 If
139 .I cap-code
140 is of string type and takes parameters,
141 .B \%tput
142 interprets arguments following
143 .I cap-code
144 as the parameters,
145 up to the (fixed) quantity the capability requires.
146 .IP
147 Most parameters are numeric.
148 Only a few terminal capabilities require string parameters;
149 .B \%tput
150 uses a table to decide which to pass as strings.
151 Normally
152 .B \%tput
153 uses \fB\%tparm\fP(3NCURSES) to perform the
154 substitution.
155 If no parameters are given for the capability,
156 .B \%tput
157 writes the string without performing the substitution.
158 .TP
159 .B init
160 initializes the terminal.
161 If the terminal database is present
162 and an entry for the user's terminal type exists,
163 the following occur.
164 .RS
165 .TP 5
166 (1)
167 .B \%tput
168 retrieves the terminal's mode settings.
169 It successively tests the file descriptors corresponding to
170 .RS
171 .bP
172 the standard error stream,
173 .bP
174 the standard output stream,
175 .bP
176 the standard input stream,
177 and
178 .bP
179 .I \%/dev/tty
180 .RE
181 .IP
182 to obtain terminal settings.
183 Having retrieved them,
184 .B \%tput
185 remembers which descriptor to use for further updates.
186 .TP
187 (2)
188 If the terminal dimensions cannot be obtained from the operating system,
189 but the environment or terminal type database entry describes them,
190 .B \%tput
191 updates the operating system's notion of them.
192 .TP
193 (3)
194 .B \%tput
195 updates the terminal modes.
196 .RS
197 .bP
198 Any delays specified in the entry
199 (for example,
200 when a newline is sent)
201 are set in the terminal driver.
202 .bP
203 Tab expansion is turned on or off per the specification in the entry,
204 and
205 .bP
206 if tabs are not expanded,
207 standard tabs
208 (every 8 spaces)
209 are set.
210 .RE
211 .TP
212 (4)
213 If initialization capabilities,
214 detailed in subsection \*(``Tabs and Initialization\*('' of
215 \fB\%terminfo\fP(5),
216 are present,
217 .B \%tput
218 writes them to the standard output stream.
219 .TP
220 (5)
221 .B \%tput
222 flushes the standard output stream.
223 .RE
224 .IP
225 If an entry lacks the information needed for an activity above,
226 that activity is silently skipped.
227 .TP
228 .B reset
229 re-initializes the terminal.
230 A reset differs from initialization in two ways.
231 .RS
232 .TP 5
233 (1)
234 .B \%tput
235 sets the terminal modes to a \*(``sane\*('' state,
236 .RS
237 .bP
238 enabling canonical (\*(``cooked\*('') and echo modes,
239 .bP
240 disabling cbreak and raw modes,
241 .bP
242 enabling newline translation,
243 and
244 .bP
245 setting any special input characters to their default values.
246 .RE
247 .TP 5
248 (2)
249 If any reset capabilities are defined for the terminal type,
250 .B \%tput
251 writes them to the output stream.
252 Otherwise,
253 .B \%tput
254 uses any defined initialization capabilities.
255 Reset capabilities are detailed in subsection
256 \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
257 .RE
258 .TP
259 .B longname
260 A
261 .I \%term\%info
262 entry begins with one or more names by which an application
263 can refer to the entry,
264 before the list of terminal capabilities.
265 The names are separated by \*(``|\*('' characters.
266 X/Open Curses terms the last name the \*(``long name\*('',
267 and indicates that it may include blanks.
268 .IP
269 \fB\%tic\fP warns if the last name does not include blanks,
270 to accommodate old
271 .I \%term\%info
272 entries that treated the long name as an optional feature.
273 The long name is often referred to as the description field.
274 .IP
275 If the terminal database is present and an entry for the user's terminal
276 type exists,
277 .B \%tput
278 reports its description to the standard output stream,
279 without a trailing newline.
280 See \fB\%terminfo\fP(5).
281 .PP
282 .I Note:
283 Redirecting the output of
284 .RB \%\*(`` "tput init" \*(''
285 or
286 .RB \%\*(`` "tput reset" \*(''
287 to a file will capture only part of their actions.
288 Changes to the terminal modes are not affected by file descriptor
289 redirection,
290 since the terminal modes are altered via \fI\%ioctl\fP(2).
291 .SS Aliases
292 If
293 .B \%tput
294 is invoked via link with any of the names
295 .BR clear ,
296 .BR init ,
297 or
298 .BR \%reset ,
299 it operates as if run with the corresponding (pseudo-)capability
300 operand.
301 For example,
302 executing a link named
303 .B \%reset
304 that points to
305 .B \%tput
306 has the same effect as
307 .RB \%\*(`` "tput \%reset" \*(''.
308 .PP
309 This feature was introduced by
310 .I \%ncurses
311 5.2 in 2000.
312 It is rarely used.
313 .TP
314 .B \%clear
315 is a separate program,
316 which is both smaller and more frequently executed.
317 .TP
318 .B init
319 has the same name as another program in widespread use.
320 .TP
321 .B \%reset
322 is provided
323 by the \fB\%tset\fP(1) utility (also via a link named
324 .BR \%reset ")."
325 .SS "Terminal Size"
326 Besides the pseudo-capabilities
327 (such as
328 .BR init ),
329 .B \%tput
330 treats the
331 .B lines
332 and
333 .B cols
334 .I cap-codes
335 specially:
336 it may call \fB\%setupterm\fP(3NCURSES) to obtain the terminal size.
337 .bP
338 First,
339 .B \%tput
340 attempts to obtain these capabilities from the terminal
341 database.
342 This generally fails for terminal emulators,
343 which lack a fixed window size and thus omit the capabilities.
344 .bP
345 It then asks the operating system for the terminal's size,
346 which generally works,
347 unless the connection is via a serial line that
348 does not support \*(``NAWS\*('': negotiations about window size.
349 .bP
350 Finally,
351 it inspects the environment variables
352 .I LINES
353 and
354 .IR \%COLUMNS ,
355 which may override the terminal size.
356 .PP
357 If the
358 .B \-T
359 option is given,
360 .B \%tput
361 ignores the environment variables by calling
362 .BR \%use_tioctl(TRUE) ,
363 relying upon the operating system
364 (or,
365 ultimately,
366 the terminal database).
367 .SH OPTIONS
368 .TP 9n \" "-T type" + 2n
369 .B \-S
370 retrieves more than one capability per invocation of
371 .BR \%tput "."
372 The capabilities must be passed to
373 .B \%tput
374 from the standard
375 input stream instead of from the command line
376 (see section \*(``EXAMPLES\*('' below).
377 Only one
378 .I cap-code
379 is allowed per line.
380 The
381 .B \-S
382 option changes the meanings of the
383 .B 0
384 and
385 .B 1
386 exit statuses
387 (see section \*(``EXIT STATUS\*('' below).
388 .IP
389 Some capabilities use string parameters rather than numeric ones.
390 .B \%tput
391 employs a built-in table and the presence of parameters
392 in its input to decide how to interpret them,
393 and whether to use \fB\%tparm\fP(3NCURSES).
394 .TP
395 .BI \-T\ type
396 indicates the terminal's
397 .IR type .
398 Normally this option is unnecessary,
399 because a default is taken from the
400 .I TERM
401 environment variable.
402 If specified,
403 the environment variables
404 .I LINES
405 and
406 .I \%COLUMNS
407 are also ignored.
408 .TP
409 .B \-v
410 causes
411 .B \%tput
412 to operate verbosely,
413 reporting warnings.
414 .TP
415 .B \-V
416 reports the version of
417 .I \%ncurses
418 associated with
419 .BR \%tput ","
420 and exits with a successful status.
421 .TP
422 .B \-x
423 prevents
424 .RB \%\*(`` "tput clear" \*(''
425 from attempting to clear the scrollback buffer.
426 .SH EXIT STATUS
427 Normally,
428 one should interpret
429 .BR \%tput "'s"
430 exit statuses as follows.
431 .PP
432 .if n .ne 3
433 .if t .ne 2
434 .TS
435 Lb Lb
436 Lb Lx.
437 Status Meaning When \-S Not Specified
438 _
439 0 Boolean or string capability present
440 1 Boolean or numeric capability absent
441 2 usage error or no terminal type specified
442 3 unrecognized terminal type
443 4 unrecognized capability code
444 >4 system error (4 + \fBerrno\fP)
445 .TE
446 .PP
447 When the
448 .B \-S
449 option is used,
450 some statuses change meanings.
451 .PP
452 .if n .ne 4
453 .if t .ne 3
454 .TS
455 Lb Lb
456 Lb Lx.
457 Status Meaning When \-S Specified
458 _
459 0 all operands interpreted
460 1 unused
461 4 some operands not interpreted
462 .TE
463 .SH ENVIRONMENT
464 .B \%tput
465 reads up to three environment variables
466 if the
467 .B \-T
468 option is not specified.
469 .TP 9n \" "COLUMNS" + 2n
470 .I COLUMNS
471 specifies the width of the screen in characters.
472 .TP
473 .I LINES
474 specifies the height of the screen in characters.
475 .TP
476 .I TERM
477 denotes the terminal type.
478 Each terminal type is distinct,
479 though many are similar.
480 .SH FILES
481 .TP
482 .I /usr/share/tabset
483 tab stop initialization database
484 .TP
485 .I /etc/terminfo
486 compiled terminal description database
487 .SH PORTABILITY
488 Over time
489 .I \%ncurses
490 .B \%tput
491 has differed from that of System\ V in two important respects,
492 one now mostly historical.
493 .bP
494 .RB \%\*(`` tput
495 .IR cap-code \*(''
496 writes to the standard output,
497 which need not be a terminal device.
498 However,
499 the operands that manipulate terminal modes might not use the standard
500 output.
501 .IP
502 System\ V
503 .IR tput 's
504 .B init
505 and
506 .B \%reset
507 operands use logic from 4.1cBSD
508 .IR tset ,
509 manipulating terminal modes.
510 It checks the same file descriptors
511 (and
512 .IR \%/dev/tty )
513 for association with a terminal device as
514 .I \%ncurses
515 now does,
516 and if none are,
517 finally assumes a 1200 baud terminal.
518 When updating terminal modes,
519 it ignores errors.
520 .IP
521 Until
522 .I \%ncurses
523 6.1
524 (see section \*(``HISTORY\*('' below),
525 .B \%tput
526 did not modify terminal modes.
527 It now employs a scheme similar to System\ V,
528 using functions shared with
529 .B \%tset
530 (and ultimately based on 4.4BSD
531 .IR tset ).
532 If it is not able to open a terminal
533 (for instance,
534 when run by \fIcron\fP(1)),
535 .B \%tput
536 exits with an error status.
537 .bP
538 System\ V
539 .I tput
540 assumes that the type of a
541 .I cap-code
542 operand is numeric if all the characters of its value are decimal
543 numbers;
544 if they are not,
545 it treats
546 .I cap-code
547 as a string capability.
548 .IP
549 Most implementations that provide support for
550 .I cap-code
551 operands use the \fB\%tparm\fP(3NCURSES) function to expand its parameters.
552 That function expects a mixture of numeric and string parameters,
553 requiring
554 .B \%tput
555 to know which type to use.
556 .IP
557 .I \%ncurses
558 .B \%tput
559 uses a table to determine the parameter types for
560 the standard
561 .I cap-code
562 operands,
563 and an internal function to analyze nonstandard
564 .I cap-code
565 operands.
566 .IP
567 While more reliable than System\ V's utility,
568 a portability problem is introduced by this analysis.
569 An OpenBSD developer adapted the internal library function from
570 .I \%ncurses
571 to port NetBSD's
572 .IR termcap -based
573 .I tput
574 to
575 .IR \%term\%info ,
576 and modified it to interpret multiple
577 .I cap-codes
578 (and parameters)
579 on the command line.
580 Portable applications should not rely upon this feature;
581 .I \%ncurses
582 offers it to support applications written specifically for OpenBSD.
583 .PP
584 This implementation,
585 unlike others,
586 accepts both
587 .I termcap
588 and
589 .I \%term\%info
590 .I cap-codes
591 if
592 .I termcap
593 support is compiled in.
594 In that case,
595 however,
596 the predefined
597 .I termcap
598 and
599 .I \%term\%info
600 codes have two
601 ambiguities;
602 .I \%ncurses
603 assumes the
604 .I \%term\%info
605 code.
606 .bP
607 The
608 .I cap-code
609 .B dl
610 means
611 .B \%delete_line
612 to
613 .I termcap
614 but
615 .B \%parm_delete_line
616 to
617 .IR \%term\%info .
618 .I termcap
619 uses the code
620 .B DL
621 for
622 .BR \%parm_delete_line .
623 .I \%term\%info
624 uses the code
625 .B dl1
626 for
627 .BR \%delete_line .
628 .bP
629 The
630 .I cap-code
631 .B ed
632 means
633 .B \%exit_delete_mode
634 to
635 .I termcap
636 but
637 .B \%clr_eos
638 to
639 .IR \%term\%info .
640 .I termcap
641 uses the code
642 .B cd
643 for
644 .BR \%clr_eos .
645 .I \%term\%info
646 uses the code
647 .B rmdc
648 for
649 .BR \%exit_delete_mode .
650 .PP
651 The
652 .B \%longname
653 operand,
654 .B \-S
655 option,
656 and the parameter-substitution features used in the
657 .B cup
658 example below,
659 were not supported in
660 AT&T/USL
661 .I curses
662 before SVr4 (1989).
663 Later,
664 4.3BSD-Reno (1990) added support for
665 .BR \%longname ,
666 .\" longname was added in October 1989.
667 and in 1994,
668 NetBSD added support for the parameter-substitution features.
669 .PP
670 IEEE Std 1003.1/The Open Group Base Specifications Issue\ 7
671 (POSIX.1-2008)
672 documents only the
673 .BR clear ,
674 .BR init ,
675 and
676 .B \%reset
677 operands.
678 A few observations of interest arise from that selection.
679 .bP
680 .I \%ncurses
681 supports
682 .B clear
683 as it does any other standard
684 .IR cap-code .
685 The others
686 .RB ( init
687 and
688 .BR \%longname )
689 do not correspond to terminal capabilities.
690 .bP
691 The
692 .I tput
693 on SVr4-based systems such as Solaris,
694 IRIX64,
695 and HP-UX,
696 as well as others such as AIX and Tru64,
697 also support standard
698 .I cap-code
699 operands.
700 .bP
701 A few platforms such as FreeBSD recognize
702 .I termcap
703 codes rather than
704 .I \%term\%info
705 capability codes in their respective
706 .I tput
707 commands.
708 Since 2010,
709 NetBSD's
710 .I tput
711 uses
712 .I \%term\%info
713 codes.
714 Before that,
715 it
716 (like FreeBSD)
717 recognized
718 .I termcap
719 codes.
720 .IP
721 Beginning in 2021,
722 FreeBSD uses
723 .I \%ncurses
724 .BR tput ,
725 configured for both
726 .I \%term\%info
727 (tested first)
728 and
729 .I termcap
730 (as a fallback).
731 .PP
732 Because (apparently) all
733 .I certified
734 Unix systems support the full set of capability codes,
735 the reason for documenting only a few may not be apparent.
736 .bP
737 X/Open Curses Issue\ 7 documents
738 .B tput
739 differently,
740 with
741 .I cap-code
742 and the other features used in this implementation.
743 .bP
744 That is,
745 there are two standards for
746 .IR tput :
747 POSIX (a subset) and X/Open Curses (the full implementation).
748 POSIX documents a subset to avoid the complication of including
749 X/Open Curses and the terminal capability database.
750 .bP
751 While it is certainly possible to write a
752 .I tput
753 program without using
754 .IR curses ,
755 no system with a
756 .I curses
757 implementation provides a
758 .I tput
759 utility that does not also support standard
760 .IR cap-codes .
761 .PP
762 X/Open Curses Issue\ 7 (2009) is the first version to document utilities.
763 However that part of X/Open Curses does not follow existing practice
764 (that is,
765 System\ V
766 .I curses
767 behavior).
768 .bP
769 It assigns exit status 4 to \*(``invalid operand\*('',
770 which may have the same meaning as \*(``unknown capability\*(''.
771 For instance,
772 the source code for
773 Solaris
774 .I xcurses
775 uses the term \*(``invalid\*('' in this case.
776 .bP
777 It assigns exit status 255 to a numeric variable that is not specified
778 in the
779 .I \%term\%info
780 database.
781 That likely is a documentation error,
782 mistaking the \*(``\-1\*('' written to the standard output to indicate
783 an absent or canceled numeric capability for an (unsigned) exit status.
784 .PP
785 The various System\ V implementations
786 (AIX,
787 HP-UX,
788 Solaris)
789 use the same exit statuses as
790 .IR \%ncurses .
791 .PP
792 NetBSD
793 .I curses
794 documents exit statuses that correspond to neither
795 .I \%ncurses
796 nor X/Open Curses.
797 .SH HISTORY
798 Bill Joy wrote a
799 .I tput
800 command during development of 4BSD in October 1980.
801 This initial version only cleared the screen,
802 and did not ship with official distributions.
803 .\" It also exited with backwards exit status (1 on success, 0 on
804 .\" failure), and was characterized by Bostic in 1988 as "pretty
805 .\" unreasonable".
806 .\" See Spinellis's "unix-history-repo" on GitHub.
807 .PP
808 System\ V developed a different
809 .I tput
810 command.
811 .bP
812 SVr2 (1984) provided a rudimentary
813 .I tput
814 that checked the parameter against each
815 predefined capability and returned the corresponding value.
816 This version of
817 .I tput
818 did not use \fB\%tparm\fP(3NCURSES) for parameterized capabilities.
819 .bP
820 SVr3 (1987) replaced that
821 .\" SVr3 released in 1987, not 1985.
822 .\" https://unix.org/what_is_unix/history_timeline.html
823 with a more extensive program
824 whose support for
825 .B init
826 and
827 .B \%reset
828 operands
829 (more than half the program)
830 incorporated the
831 .B \%reset
832 feature of BSD
833 .I tset
834 written by Eric Allman.
835 .bP
836 SVr4 (1989) added color initialization by using the
837 .B \%orig_colors
838 .RB ( oc )
839 and
840 .B \%orig_pair
841 .RB ( op )
842 capabilities in its
843 .B init
844 logic.
845 .PP
846 Keith Bostic refactored BSD
847 .I tput
848 for shipment in 4.3BSD-Tahoe (1988),
849 then replaced it the next year with a new implementation based on
850 System\ V
851 .IR tput .
852 Bostic's version similarly accepted some parameters named for
853 .I \%term\%info
854 (pseudo-)capabilities:
855 .BR clear ,
856 .BR init ,
857 .BR \%longname ,
858 and
859 .BR \%reset .
860 However,
861 because he had only
862 .I termcap
863 available,
864 it accepted
865 .I termcap
866 codes for other capabilities.
867 Also,
868 Bostic's BSD
869 .I tput
870 did not modify the terminal modes as the earlier BSD
871 .I tset
872 had done.
873 .PP
874 At the same time,
875 Bostic added a shell script named \*(``clear\*('' that used
876 .I tput
877 to clear the screen.
878 Both of these appeared in 4.4BSD,
879 becoming the \*(``modern\*('' BSD implementation of
880 .IR tput .
881 .PP
882 The origin of
883 .I \%ncurses
884 .B \%tput
885 lies outside both System\ V and BSD,
886 in Ross Ridge's
887 .I \%mytinfo
888 package,
889 published on
890 .I comp.sources.unix
891 in December 1992.
892 Ridge's program made more sophisticated use of the terminal capabilities
893 than the BSD program.
894 Eric Raymond used that
895 .I tput
896 program
897 (and other parts of
898 .IR \%mytinfo )
899 in
900 .I \%ncurses
901 in June 1995.
902 Incorporating the portions dealing with terminal capabilities
903 almost without change,
904 Raymond made improvements to the way command-line parameters
905 were handled.
906 .PP
907 Before
908 .I \%ncurses
909 6.1 (2018),
910 its
911 .B \%tset
912 and
913 .B \%tput
914 utilities differed.
915 .bP
916 .B \%tset
917 was more effective,
918 resetting the terminal's modes and special input characters.
919 .bP
920 On the other hand,
921 .BR \%tset "'s"
922 repertoire of terminal capabilities for resetting the
923 terminal was more limited;
924 it had only equivalents of
925 .B \%reset_1string
926 .RB ( rs1 ),
927 .B \%reset_2string
928 .RB ( rs2 ),
929 and
930 .B \%reset_file
931 .RB ( rf ),
932 and not the tab stop and margin update features of
933 .BR \%tput "."
934 .PP
935 The
936 .I \%reset
937 program is traditionally an alias for
938 .B \%tset
939 due to its ability
940 to reset the terminal's modes and special input characters.
941 .PP
942 As of
943 .I \%ncurses
944 6.1,
945 the \*(``reset\*('' features of the two programs are (mostly) the same.
946 Two minor differences remain.
947 .bP
948 When issuing a reset,
949 the
950 .B \%tset
951 program
952 checks whether the device appears to be a pseudoterminal
953 (as might be used by a terminal emulator program),
954 and,
955 if it does not,
956 waits one second in case it is communicating with a hardware terminal.
957 .bP
958 The two programs write the terminal initialization strings
959 to different streams;
960 that is,
961 standard error for
962 .B \%tset
963 and
964 standard output for
965 .BR \%tput "."
966 .SH EXAMPLES
967 .TP
968 .B "tput init"
969 Initialize the terminal according to the type of
970 terminal in the
971 .I TERM
972 environment variable.
973 If the system does not reliably initialize the terminal upon login,
974 this command can be included in
975 .I \%$HOME/.profile
976 after exporting the
977 .I TERM
978 environment variable.
979 .TP
980 .B "tput \-T5620 reset"
981 Reset an AT&T 5620 terminal,
982 overriding the terminal type in the
983 .I TERM
984 environment variable.
985 .TP
986 .B "tput cnorm"
987 Set cursor to normal visibility.
988 .TP
989 .B "tput home"
990 Move the cursor to line 0,
991 column 0:
992 the upper left corner of the screen,
993 usually known as the \*(``home\*('' cursor position.
994 .TP
995 .B "tput clear"
996 Clear the screen:
997 write the
998 .B \%clear_screen
999 capability's value to the standard output stream.
1000 .TP
1001 .B "tput cols"
1002 Report the number of columns used by the current terminal type.
1003 .TP
1004 .B "tput \-Tadm3a cols"
1005 Report the number of columns used by an ADM-3A terminal.
1006 .TP
1007 .B "strong=\(gatput smso\(ga normal=\(gatput rmso\(ga"
1008 Set shell variables to capability values:
1009 .B strong
1010 and
1011 .BR normal ,
1012 to begin and end,
1013 respectively,
1014 stand-out mode for the terminal.
1015 One might use these to present a prompt.
1016 .IP
1017 .EX
1018 .RS 14
1019 printf "${strong}Username:${normal} "
1020 .RE
1021 .EE
1022 .TP
1023 .B "tput hc"
1024 Indicate via exit status whether the terminal is a hard copy device.
1025 .TP
1026 .B "tput cup 23 4"
1027 Move the cursor to line 23,
1028 column 4.
1029 .TP
1030 .B "tput cup"
1031 Report the value of the
1032 .B \%cursor_address
1033 .RB ( cup )
1034 capability
1035 (used for cursor movement),
1036 with no parameters substituted.
1037 .TP
1038 .B "tput longname"
1039 Report the
1040 .I \%term\%info
1041 database's description of the terminal type specified in the
1042 .I TERM
1043 environment variable.
1044 .TP
1045 .B "tput \-S"
1046 Process multiple capabilities.
1047 The
1048 .B \-S
1049 option can be profitably used with a shell \*(``here document\*(''.
1050 .IP
1051 .EX
1052 .RB $\ "tput \-S <<!"
1053 .RB >\ clear
1054 .RB >\ "cup 10 10"
1055 .RB >\ bold
1056 .RB >\ !
1057 .EE
1058 .IP
1059 The foregoing
1060 clears the screen,
1061 moves the cursor to position
1062 (10, 10)
1063 and turns on bold
1064 (extra bright)
1065 mode.
1066 .TP
1067 .B "tput clear cup 10 10 bold"
1068 Perform the same actions as the foregoing
1069 .RB \%\*(`` "tput \-S" \*(''
1070 example.
1071 .SH SEE ALSO
1072 \fB\%clear\fP(1),
1073 \fB\%stty\fP(1),
1074 \fB\%tabs\fP(1),
1075 \fB\%tset\fP(1),
1076 \fB\%termcap\fP(3NCURSES),
1077 \fB\%terminfo\fP(5)