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