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.118 2024/06/22 21:28:35 tom Exp $
  32 .TH @TPUT@ 1 2024-06-22 "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\-v\fP] [\fB\-T\fP \fIterminal-type\fP]
  53 {\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
  54 .PP
  55 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
  56 .PP
  57 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fBinit\fP
  58 .PP
  59 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%reset\fP
  60 .PP
  61 \fB@TPUT@\fP [\fB\-v\fP] [\fB\-T\fP \fIterminal-type\fP] \fB\%longname\fP
  62 .PP
  63 \fB@TPUT@\fP [\fB\-v\fP] \fB\-S\fP
  64 .PP
  65 \fB@TPUT@\fP [\fB\-v\fP] \fB\-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 causes \fB\%@TPUT@\fP to operate verbosely,
 378 reporting warnings.
 379 .TP
 380 .B \-V
 381 reports the version of
 382 .I \%ncurses
 383 associated with \fB\%@TPUT@\fP,
 384 and exits with a successful status.
 385 .TP
 386 .B \-x
 387 prevents
 388 .RB \%\*(`` "@TPUT@ clear" \*(''
 389 from attempting to clear the scrollback buffer.
 390 .SH EXIT STATUS
 391 Normally,
 392 one should interpret \fB\%@TPUT@\fP's exit statuses as follows.
 393 .PP
 394 .if n .ne 3
 395 .if t .ne 2
 396 .TS
 397 Lb Lb
 398 Lb Lx.
 399 Status  Meaning When \-S Not Specified
 400 _
 401 0       Boolean or string capability present
 402 1       Boolean or numeric capability absent
 403 2       usage error or no terminal type specified
 404 3       unrecognized terminal type
 405 4       unrecognized capability code
 406 >4      system error (4 + \fBerrno\fP)
 407 .TE
 408 .PP
 409 When the
 410 .B \-S
 411 option is used,
 412 some statuses change meanings.
 413 .PP
 414 .if n .ne 4
 415 .if t .ne 3
 416 .TS
 417 Lb Lb
 418 Lb Lx.
 419 Status  Meaning When \-S Specified
 420 _
 421 0       all operands interpreted
 422 1       unused
 423 4       some operands not interpreted
 424 .TE
 425 .SH ENVIRONMENT
 426 \fB@TPUT@\fP reads one environment variable.
 427 .TP 8n \" "TERM" + 2n + adjustment for PDF
 428 .I TERM
 429 denotes the terminal type.
 430 Each terminal type is distinct,
 431 though many are similar.
 432 The
 433 .B \-T
 434 option overrides its value.
 435 .SH FILES
 436 .TP
 437 .I @DATADIR@/tabset
 438 tab stop initialization database
 439 .TP
 440 .I @TERMINFO@
 441 compiled terminal description database
 442 .SH PORTABILITY
 443 Over time
 444 .I \%ncurses
 445 \fB\%@TPUT@\fP
 446 has differed from that of System\ V in two important respects,
 447 one now mostly historical.
 448 .bP
 449 \%\*(``\fB@TPUT@\fP
 450 .IR cap-code \*(''
 451 writes to the standard output,
 452 which need not be a terminal device.
 453 However,
 454 the operands that manipulate terminal modes might not use the standard
 455 output.
 456 .IP
 457 System\ V
 458 .BR tput 's
 459 .B init
 460 and
 461 .B \%reset
 462 operands use logic from 4.1cBSD
 463 .BR tset ,
 464 manipulating terminal modes.
 465 It checks the same file descriptors
 466 (and
 467 .IR \%/dev/tty )
 468 for association with a terminal device as
 469 .I \%ncurses
 470 now does,
 471 and if none are,
 472 finally assumes a 1200 baud terminal.
 473 When updating terminal modes,
 474 it ignores errors.
 475 .IP
 476 Until
 477 .I \%ncurses
 478 6.1
 479 (see section \*(``HISTORY\*('' below),
 480 \fB\%@TPUT@\fP did not modify terminal modes.
 481 It now employs a scheme similar to System\ V,
 482 using functions shared with \fB\%@TSET@\fP
 483 (and ultimately based on 4.4BSD
 484 .BR tset ).
 485 If it is not able to open a terminal
 486 (for instance,
 487 when run by \fIcron\fP(1)),
 488 \fB\%@TPUT@\fP exits with an error status.
 489 .bP
 490 System\ V
 491 .B tput
 492 assumes that the type of a
 493 .I cap-code
 494 operand is numeric if all the characters of its value are decimal
 495 numbers;
 496 if they are not,
 497 it treats
 498 .I cap-code
 499 as a string capability.
 500 .IP
 501 Most implementations that provide support for
 502 .I cap-code
 503 operands use the \fB\%tparm\fP(3X) function to expand its parameters.
 504 That function expects a mixture of numeric and string parameters,
 505 requiring \fB\%@TPUT@\fP to know which type to use.
 506 .IP
 507 .I \%ncurses
 508 \fB\%@TPUT@\fP
 509 uses a table to determine the parameter types for
 510 the standard
 511 .I cap-code
 512 operands,
 513 and an internal function to analyze nonstandard
 514 .I cap-code
 515 operands.
 516 .IP
 517 While more reliable than System\ V's utility,
 518 a portability problem is introduced by this analysis.
 519 An OpenBSD developer adapted the internal library function from
 520 .I \%ncurses
 521 to port NetBSD's
 522 .IR termcap -based
 523 .B tput
 524 to
 525 .IR \%term\%info ,
 526 and modified it to interpret multiple
 527 .I cap-codes
 528 (and parameters)
 529 on the command line.
 530 Portable applications should not rely upon this feature;
 531 .I \%ncurses
 532 offers it to support applications written specifically for OpenBSD.
 533 .PP
 534 This implementation,
 535 unlike others,
 536 accepts both
 537 .I termcap
 538 and
 539 .I \%term\%info
 540 .I cap-codes
 541 if
 542 .I termcap
 543 support is compiled in.
 544 In that case,
 545 however,
 546 the predefined
 547 .I termcap
 548 and
 549 .I \%term\%info
 550 codes have two
 551 ambiguities;
 552 .I \%ncurses
 553 assumes the
 554 .I \%term\%info
 555 code.
 556 .bP
 557 The
 558 .I cap-code
 559 .B dl
 560 means
 561 .B \%delete_line
 562 to
 563 .I termcap
 564 but
 565 .B \%parm_delete_line
 566 to
 567 .IR \%term\%info .
 568 .I termcap
 569 uses the code
 570 .B DL
 571 for
 572 .BR \%parm_delete_line .
 573 .I \%term\%info
 574 uses the code
 575 .B dl1
 576 for
 577 .BR \%delete_line .
 578 .bP
 579 The
 580 .I cap-code
 581 .B ed
 582 means
 583 .B \%exit_delete_mode
 584 to
 585 .I termcap
 586 but
 587 .B \%clr_eos
 588 to
 589 .IR \%term\%info .
 590 .I termcap
 591 uses the code
 592 .B cd
 593 for
 594 .BR \%clr_eos .
 595 .I \%term\%info
 596 uses the code
 597 .B rmdc
 598 for
 599 .BR \%exit_delete_mode .
 600 .PP
 601 The
 602 .B \%longname
 603 operand,
 604 .B \-S
 605 option,
 606 and the parameter-substitution features used in the
 607 .B cup
 608 example below,
 609 were not supported in
 610 AT&T/USL
 611 .I curses
 612 before SVr4 (1989).
 613 Later,
 614 4.3BSD-Reno (1990) added support for
 615 .BR \%longname ,
 616 .\" longname was added in October 1989.
 617 and in 1994,
 618 NetBSD added support for the parameter-substitution features.
 619 .PP
 620 IEEE Std 1003.1/The Open Group Base Specifications Issue 7
 621 (POSIX.1-2008)
 622 documents only the
 623 .BR clear ,
 624 .BR init ,
 625 and
 626 .B \%reset
 627 operands.
 628 A few observations of interest arise from that selection.
 629 .bP
 630 .I \%ncurses
 631 supports
 632 .B clear
 633 as it does any other standard
 634 .IR cap-code .
 635 The others
 636 .RB ( init
 637 and
 638 .BR \%longname )
 639 do not correspond to terminal capabilities.
 640 .bP
 641 The
 642 .B tput
 643 on SVr4-based systems such as Solaris,
 644 IRIX64,
 645 and HP-UX,
 646 as well as others such as AIX and Tru64,
 647 also support standard
 648 .I cap-code
 649 operands.
 650 .bP
 651 A few platforms such as FreeBSD recognize
 652 .I termcap
 653 codes rather than
 654 .I \%term\%info
 655 capability codes in their respective
 656 .B tput
 657 commands.
 658 Since 2010,
 659 NetBSD's
 660 .B tput
 661 uses
 662 .I \%term\%info
 663 codes.
 664 Before that,
 665 it
 666 (like FreeBSD)
 667 recognized
 668 .I termcap
 669 codes.
 670 .IP
 671 Beginning in 2021,
 672 FreeBSD uses
 673 .I \%ncurses
 674 .BR tput ,
 675 configured for both
 676 .I \%term\%info
 677 (tested first)
 678 and
 679 .I termcap
 680 (as a fallback).
 681 .PP
 682 Because (apparently) all
 683 .I certified
 684 Unix systems support the full set of capability codes,
 685 the reason for documenting only a few may not be apparent.
 686 .bP
 687 X/Open Curses Issue 7 documents
 688 .B tput
 689 differently,
 690 with
 691 .I cap-code
 692 and the other features used in this implementation.
 693 .bP
 694 That is,
 695 there are two standards for
 696 .BR tput :
 697 POSIX (a subset) and X/Open Curses (the full implementation).
 698 POSIX documents a subset to avoid the complication of including
 699 X/Open Curses and the terminal capability database.
 700 .bP
 701 While it is certainly possible to write a
 702 .B tput
 703 program without using
 704 .IR curses ,
 705 no system with a
 706 .I curses
 707 implementation provides a
 708 .B tput
 709 utility that does not also support standard
 710 .IR cap-codes .
 711 .PP
 712 X/Open Curses Issue 7 (2009) is the first version to document utilities.
 713 However that part of X/Open Curses does not follow existing practice
 714 (that is,
 715 System\ V
 716 .I curses
 717 behavior).
 718 .bP
 719 It assigns exit status 4 to \*(``invalid operand\*('',
 720 which may have the same meaning as \*(``unknown capability\*(''.
 721 For instance,
 722 the source code for
 723 Solaris
 724 .I xcurses
 725 uses the term \*(``invalid\*('' in this case.
 726 .bP
 727 It assigns exit status 255 to a numeric variable that is not specified
 728 in the
 729 .I \%term\%info
 730 database.
 731 That likely is a documentation error,
 732 mistaking the \*(``\-1\*('' written to the standard output to indicate
 733 an absent or cancelled numeric capability for an (unsigned) exit status.
 734 .PP
 735 The various System\ V implementations
 736 (AIX,
 737 HP-UX,
 738 Solaris)
 739 use the same exit statuses as
 740 .IR \%ncurses .
 741 .PP
 742 NetBSD
 743 .I curses
 744 documents exit statuses that correspond to neither
 745 .I \%ncurses
 746 nor X/Open Curses.
 747 .SH HISTORY
 748 Bill Joy wrote a
 749 .B tput
 750 command during development of 4BSD in October 1980.
 751 This initial version only cleared the screen,
 752 and did not ship with official distributions.
 753 .\" It also exited with backwards exit status (1 on success, 0 on
 754 .\" failure), and was characterized by Bostic in 1988 as "pretty
 755 .\" unreasonable".
 756 .\" See Spinellis's "unix-history-repo" on GitHub.
 757 .PP
 758 System\ V developed a different
 759 .B tput
 760 command.
 761 .bP
 762 SVr2 (1984) provided a rudimentary
 763 .B tput
 764 that checked the parameter against each
 765 predefined capability and returned the corresponding value.
 766 This version of
 767 .B tput
 768 did not use \fB\%tparm\fP(3X) for parameterized capabilities.
 769 .bP
 770 SVr3 (1987) replaced that
 771 .\" SVr3 released in 1987, not 1985.
 772 .\" https://unix.org/what_is_unix/history_timeline.html
 773 with a more extensive program
 774 whose support for
 775 .B init
 776 and
 777 .B \%reset
 778 operands
 779 (more than half the program)
 780 incorporated the
 781 .B \%reset
 782 feature of BSD
 783 .B tset
 784 written by Eric Allman.
 785 .bP
 786 SVr4 (1989) added color initialization by using the
 787 .B \%orig_colors
 788 .RB ( oc )
 789 and
 790 .B \%orig_pair
 791 .RB ( op )
 792 capabilities in its
 793 .B init
 794 logic.
 795 .PP
 796 Keith Bostic refactored BSD
 797 .B tput
 798 for shipment in 4.3BSD-Tahoe (1988),
 799 then replaced it the next year with a new implementation based on
 800 System\ V
 801 .BR tput .
 802 Bostic's version similarly accepted some parameters named for
 803 .I \%term\%info
 804 (pseudo-)capabilities:
 805 .BR clear ,
 806 .BR init ,
 807 .BR \%longname ,
 808 and
 809 .BR \%reset .
 810 However,
 811 because he had only
 812 .I termcap
 813 available,
 814 it accepted
 815 .I termcap
 816 codes for other capabilities.
 817 Also,
 818 Bostic's BSD
 819 .B tput
 820 did not modify the terminal modes as the earlier BSD
 821 .B tset
 822 had done.
 823 .PP
 824 At the same time,
 825 Bostic added a shell script named \*(``clear\*('' that used
 826 .B tput
 827 to clear the screen.
 828 Both of these appeared in 4.4BSD,
 829 becoming the \*(``modern\*('' BSD implementation of
 830 .BR tput .
 831 .PP
 832 The origin of
 833 .I \%ncurses
 834 \fB\%@TPUT@\fP lies outside both System\ V and BSD,
 835 in Ross Ridge's
 836 .I \%mytinfo
 837 package,
 838 published on
 839 .I comp.sources.unix
 840 in December 1992.
 841 Ridge's program made more sophisticated use of the terminal capabilities
 842 than the BSD program.
 843 Eric Raymond used that
 844 .B tput
 845 program
 846 (and other parts of
 847 .IR \%mytinfo )
 848 in
 849 .I \%ncurses
 850 in June 1995.
 851 Incorporating the portions dealing with terminal capabilities
 852 almost without change,
 853 Raymond made improvements to the way command-line parameters
 854 were handled.
 855 .PP
 856 Before
 857 .I \%ncurses
 858 6.1 (2018),
 859 its \fB\%@TSET@\fP and \fB\%@TPUT@\fP utilities differed.
 860 .bP
 861 \fB\%@TSET@\fP was more effective,
 862 resetting the terminal modes and special characters.
 863 .bP
 864 On the other hand,
 865 \fB\%@TSET@\fP's repertoire of terminal capabilities for resetting the
 866 terminal was more limited;
 867 it had only equivalents of
 868 .B \%reset_1string
 869 .RB ( rs1 ),
 870 .B \%reset_2string
 871 .RB ( rs2 ),
 872 and
 873 .B \%reset_file
 874 .RB ( rf ),
 875 and not the tab stop and margin update features of \fB\%@TPUT@\fP.
 876 .PP
 877 The
 878 .B \%reset
 879 program is traditionally an alias for \fB\%@TSET@\fP due to its ability
 880 to reset terminal modes and special characters.
 881 .PP
 882 As of
 883 .I \%ncurses
 884 6.1,
 885 the \*(``reset\*('' features of the two programs are (mostly) the same.
 886 Two minor differences remain.
 887 .bP
 888 When issuing a reset,
 889 the \fB\%@TSET@\fP program
 890 checks whether the device appears to be a pseudoterminal
 891 (as might be used by a terminal emulator program),
 892 and,
 893 if it does not,
 894 waits one second in case it is communicating with a hardware terminal.
 895 .bP
 896 The two programs write the terminal initialization strings
 897 to different streams;
 898 that is,
 899 standard error for \fB\%@TSET@\fP and
 900 standard output for \fB\%@TPUT@\fP.
 901 .SH EXAMPLES
 902 .TP
 903 .B "@TPUT@ init"
 904 Initialize the terminal according to the type of
 905 terminal in the
 906 .I TERM
 907 environment variable.
 908 If the system does not reliably initialize the terminal upon login,
 909 this command can be included in
 910 .I \%$HOME/.profile
 911 after exporting the
 912 .I TERM
 913 environment variable.
 914 .TP
 915 .B "@TPUT@ \-T5620 reset"
 916 Reset an AT&T 5620 terminal,
 917 overriding the terminal type in the
 918 .I TERM
 919 environment variable.
 920 .TP
 921 .B "@TPUT@ cnorm"
 922 Set cursor to normal visibility.
 923 .TP
 924 .B "@TPUT@ home"
 925 Move the cursor to line 0,
 926 column 0:
 927 the upper left corner of the screen,
 928 usually known as the \*(``home\*('' cursor position.
 929 .TP
 930 .B "@TPUT@ clear"
 931 Clear the screen:
 932 write the
 933 .B \%clear_screen
 934 capability's value to the standard output stream.
 935 .TP
 936 .B "@TPUT@ cols"
 937 Report the number of columns used by the current terminal type.
 938 .TP
 939 .B "@TPUT@ \-Tadm3a cols"
 940 Report the number of columns used by an ADM-3A terminal.
 941 .TP
 942 .B "strong=\(ga@TPUT@ smso\(ga normal=\(ga@TPUT@ rmso\(ga"
 943 Set shell variables to capability values:
 944 .B strong
 945 and
 946 .BR normal ,
 947 to begin and end,
 948 respectively,
 949 stand-out mode for the terminal.
 950 One might use these to present a prompt.
 951 .IP
 952 .EX
 953 .RS 14
 954 printf "${strong}Username:${normal} "
 955 .RE
 956 .EE
 957 .TP
 958 .B "@TPUT@ hc"
 959 Indicate via exit status whether the terminal is a hard copy device.
 960 .TP
 961 .B "@TPUT@ cup 23 4"
 962 Move the cursor to line 23,
 963 column 4.
 964 .TP
 965 .B "@TPUT@ cup"
 966 Report the value of the
 967 .B \%cursor_address
 968 .RB ( cup )
 969 capability
 970 (used for cursor movement),
 971 with no parameters substituted.
 972 .TP
 973 .B "@TPUT@ longname"
 974 Report the
 975 .I \%term\%info
 976 database's description of the terminal type specified in the
 977 .I TERM
 978 environment variable.
 979 .TP
 980 .B "@TPUT@ \-S"
 981 Process multiple capabilities.
 982 The
 983 .B \-S
 984 option can be profitably used with a shell \*(``here document\*(''.
 985 .IP
 986 .EX
 987 .RB $\  "@TPUT@ \-S <<!"
 988 .RB >\  clear
 989 .RB >\  "cup 10 10"
 990 .RB >\  bold
 991 .RB >\  !
 992 .EE
 993 .IP
 994 The foregoing
 995 clears the screen,
 996 moves the cursor to position
 997 (10, 10)
 998 and turns on bold
 999 (extra bright)
1000 mode.
1001 .TP
1002 .B "@TPUT@ clear cup 10 10 bold"
1003 Perform the same actions as the foregoing
1004 .RB \%\*(`` "@TPUT@ \-S" \*(''
1005 example.
1006 .SH SEE ALSO
1007 \fB\%@CLEAR@\fP(1),
1008 \fB\%stty\fP(1),
1009 \fB\%@TABS@\fP(1),
1010 \fB\%@TSET@\fP(1),
1011 \fB\%curs_termcap\fP(3X),
1012 \fB\%terminfo\fP(5)