man/tput.1

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