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