Debian Codegraph @

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