Debian Codegraph @

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