X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Ftput.1.html;h=4ebb0d7081ede38a5cf34bb24de1e6986bf7e38b;hb=725169bda4d3b4c3fde0d4a94f76d017812c7ea6;hp=4376be4580af386b6c243c8bbc4ce471ec36885b;hpb=f9994a48d2f74b613a0adb19d3917f724d4d1312;p=ncurses.git diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html index 4376be45..4ebb0d70 100644 --- a/doc/html/man/tput.1.html +++ b/doc/html/man/tput.1.html @@ -1,7 +1,7 @@
--tput(1) General Commands Manual tput(1) +tput(1) User commands tput(1)
- tput, reset - initialize a terminal or query terminfo database + tput - initialize a terminal, exercise its capabilities, or query term- + info database
- tput [-Ttype] capname [parameters] - tput [-Ttype] [-x] clear - tput [-Ttype] init - tput [-Ttype] reset - tput [-Ttype] longname - tput -S << - tput -V + tput [-T terminal-type] {cap-code [parameter ...]} ... + tput [-T terminal-type] [-x] clear -
- The tput utility uses the terminfo database to make the values of - terminal-dependent capabilities and information available to the shell - (see sh(1)), to initialize or reset the terminal, or return the long - name of the requested terminal type. The result depends upon the - capability's type: + tput [-T terminal-type] init - string - tput writes the string to the standard output. No trailing - newline is supplied. + tput [-T terminal-type] reset - integer - tput writes the decimal value to the standard output, with a - trailing newline. + tput [-T terminal-type] longname - boolean - tput simply sets the exit code (0 for TRUE if the terminal has - the capability, 1 for FALSE if it does not), and writes nothing - to the standard output. - - Before using a value returned on the standard output, the application - should test the exit code (e.g., $?, see sh(1)) to be sure it is 0. - (See the EXIT CODES and DIAGNOSTICS sections.) For a complete list of - capabilities and the capname associated with each, see terminfo(5). + tput -S + tput -V -
- -S allows more than one capability per invocation of tput. The - capabilities must be passed to tput from the standard input - instead of from the command line (see example). Only one - capname is allowed per line. The -S option changes the meaning - of the 0 and 1 boolean and string exit codes (see the EXIT CODES - section). - Because some capabilities may use string parameters rather than - numbers, tput uses a table and the presence of parameters in its - input to decide whether to use tparm(3x), and how to interpret - the parameters. +
+ tput uses the terminfo library and database to make terminal-specific + capabilities and information available to the shell, to initialize or + reset the terminal, or to report a description of the current (or + specified) terminal type. Terminal capabilities are accessed by cap- + code. - -Ttype indicates the type of terminal. Normally this option is - unnecessary, because the default is taken from the environment - variable TERM. If -T is specified, then the shell variables - LINES and COLUMNS will also be ignored. + terminfo(5) discusses terminal capabilities at length and presents a + complete list of cap-codes. - -V reports the version of ncurses which was used in this program, - and exits. + When retrieving capability values, the result depends upon the + capability's type. - -x do not attempt to clear the terminal's scrollback buffer using - the extended "E3" capability. + Boolean tput sets its exit status to 0 if the terminal possesses cap- + code, and 1 if it does not. + numeric tput writes cap-code's decimal value to the standard output + stream if defined (-1 if it is not) followed by a newline. -
- A few commands (init, reset and longname) are special; they are defined - by the tput program. The others are the names of capabilities from the - terminal database (see terminfo(5) for a list). Although init and - reset resemble capability names, tput uses several capabilities to - perform these special functions. + string tput writes cap-code's value to the standard output stream if + defined, without a trailing newline. - capname - indicates the capability from the terminal database. + Before using a value returned on the standard output, the application + should test tput's exit status to be sure it is 0; see section "EXIT + STATUS" below. - If the capability is a string that takes parameters, the - arguments following the capability will be used as parameters - for the string. - Most parameters are numbers. Only a few terminal capabilities - require string parameters; tput uses a table to decide which to - pass as strings. Normally tput uses tparm(3x) to perform the - substitution. If no parameters are given for the capability, - tput writes the string without performing the substitution. +
+ Generally, an operand is a cap-code, a capability code from the + terminal database, or a parameter thereto. Three others are specially + recognized by tput: init, reset, and longname. Although these resemble + capability codes, they in fact receive special handling; we term them + "pseudo-capabilities". - init If the terminal database is present and an entry for the user's - terminal exists (see -Ttype, above), the following will occur: + cap-code indicates a capability from the terminal database. - (1) first, tput retrieves the current terminal mode settings - for your terminal. It does this by successively testing + If the capability is of string type and takes parameters, + the arguments following the capability will be used as its + parameters. - o the standard error, + Most parameters are numeric. Only a few terminal + capabilities require string parameters; tput uses a table to + decide which to pass as strings. Normally tput uses + tparm(3x) to perform the substitution. If no parameters are + given for the capability, tput writes the string without + performing the substitution. - o standard output, + init initializes the terminal. If the terminal database is + present and an entry for the user's terminal type exists, + the following occur. - o standard input and + (1) tput retrieves the terminal's mode settings. It + successively tests the file descriptors corresponding + to - o ultimately "/dev/tty" + o the standard error stream, - to obtain terminal settings. Having retrieved these - settings, tput remembers which file descriptor to use when - updating settings. + o the standard output stream, - (2) if the window size cannot be obtained from the operating - system, but the terminal description (or environment, e.g., - LINES and COLUMNS variables specify this), update the - operating system's notion of the window size. + o the standard input stream, and - (3) the terminal modes will be updated: + o /dev/tty - o any delays (e.g., newline) specified in the entry will - be set in the tty driver, + to obtain terminal settings. Having retrieved them, + tput remembers which descriptor to use for further + updates. - o tabs expansion will be turned on or off according to - the specification in the entry, and + (2) If the terminal dimensions cannot be obtained from the + operating system, but the environment or terminal type + database entry describes them, tput updates the + operating system's notion of them. - o if tabs are not expanded, standard tabs will be set - (every 8 spaces). + (3) tput updates the terminal modes. - (4) if present, the terminal's initialization strings will be - output as detailed in the terminfo(5) section on Tabs and - Initialization, + o Any delays specified in the entry (for example, + when a newline is sent) are set in the terminal + driver. - (5) output is flushed. + o Tab expansion is turned on or off per the + specification in the entry, and - If an entry does not contain the information needed for any of - these activities, that activity will silently be skipped. + o if tabs are not expanded, standard tabs (every 8 + spaces) are set. - reset This is similar to init, with two differences: + (4) If initialization capabilities, detailed in subsection + "Tabs and Initialization" of terminfo(5), are present, + tput writes them to the standard output stream. - (1) before any other initialization, the terminal modes will be - reset to a "sane" state: + (5) tput flushes the standard output stream. - o set cooked and echo modes, + If an entry lacks the information needed for an activity + above, that activity is silently skipped. - o turn off cbreak and raw modes, + reset re-initializes the terminal. A reset differs from + initialization in two ways. - o turn on newline translation and + (1) tput sets the the terminal modes to a "sane" state, - o reset any unset special characters to their default - values + o enabling cooked and echo modes, - (2) Instead of putting out initialization strings, the - terminal's reset strings will be output if present (rs1, - rs2, rs3, rf). If the reset strings are not present, but - initialization strings are, the initialization strings will - be output. + o disabling cbreak and raw modes, - Otherwise, reset acts identically to init. + o enabling newline translation, and - longname - If the terminal database is present and an entry for the user's - terminal exists (see -Ttype above), then the long name of the - terminal will be put out. The long name is the last name in the - first line of the terminal's description in the terminfo - database [see term(5)]. + o setting any unset special characters to their + default values. + (2) If any reset capabilities are defined for the terminal + type, tput writes them to the output stream. + Otherwise, tput uses any defined initialization + capabilities. Reset capabilities are detailed in + subsection "Tabs and Initialization" of terminfo(5). -
- tput handles the clear, init and reset commands specially: it allows - for the possibility that it is invoked by a link with those names. + longname A terminfo entry begins with one or more names by which an + application can refer to the entry, before the list of + terminal capabilities. The names are separated by "|" + characters. X/Open Curses terms the last name the "long + name", and indicates that it may include blanks. - If tput is invoked by a link named reset, this has the same effect as - tput reset. The tset(1) utility also treats a link named reset - specially. + tic warns if the last name does not include blanks, to + accommodate old terminfo entries that treated the long name + as an optional feature. The long name is often referred to + as the description field. - Before ncurses 6.1, the two utilities were different from each other: + If the terminal database is present and an entry for the + user's terminal type exists, tput reports its description to + the standard output stream, without a trailing newline. See + terminfo(5). - o tset utility reset the terminal modes and special characters (not - done with tput). + Note: Redirecting the output of "tput init" or "tput reset" to a file + will capture only part of their actions. Changes to the terminal modes + are not affected by file descriptor redirection, since the terminal + modes are altered via ioctl(2). - o On the other hand, tset's repertoire of terminal capabilities for - resetting the terminal was more limited, i.e., only reset_1string, - reset_2string and reset_file in contrast to the tab-stops and - margins which are set by this utility. - o The reset program is usually an alias for tset, because of this - difference with resetting terminal modes and special characters. - - With the changes made for ncurses 6.1, the reset feature of the two - programs is (mostly) the same. A few differences remain: +
+ If tput is invoked via link with any of the names clear, init, or + reset, it operates as if run with the corresponding (pseudo-)capability + operand. For example, executing a link named reset that points to tput + has the same effect as "tput reset". - o The tset program waits one second when resetting, in case it - happens to be a hardware terminal. + This feature was introduced by ncurses 5.2 in 2000. It is rarely used: - o The two programs write the terminal initialization strings to - different streams (i.e., the standard error for tset and the - standard output for tput). + clear is a separate program, which is both smaller and more frequently + executed. - Note: although these programs write to different streams, - redirecting their output to a file will capture only part of their - actions. The changes to the terminal modes are not affected by - redirecting the output. + init has the same name as another program in widespread use. - If tput is invoked by a link named init, this has the same effect as - tput init. Again, you are less likely to use that link because another - program named init has a more well-established use. + reset is provided by the tset(1) utility (also via a link named + reset).
- Besides the special commands (e.g., clear), tput treats certain - terminfo capabilities specially: lines and cols. tput calls - setupterm(3x) to obtain the terminal size: + Besides the pseudo-capabilities (such as init), tput treats the lines + and cols cap-codes specially: it may call setupterm(3x) to obtain the + terminal size. - o first, it gets the size from the terminal database (which generally - is not provided for terminal emulators which do not have a fixed - window size) + o First, tput attempts to obtain these capabilities from the terminal + database. This generally fails for terminal emulators, which lack + a fixed window size and thus omit the capabilities. - o then it asks the operating system for the terminal's size (which - generally works, unless connecting via a serial line which does not - support NAWS: negotiations about window size). + o It then asks the operating system for the terminal's size, which + generally works, unless the connection is via a serial line that + does not support "NAWS": negotiations about window size. - o finally, it inspects the environment variables LINES and COLUMNS + o Finally, it inspects the environment variables LINES and COLUMNS, which may override the terminal size. - If the -T option is given tput ignores the environment variables by - calling use_tioctl(TRUE), relying upon the operating system (or - finally, the terminal database). + If the -T option is given, tput ignores the environment variables by + calling use_tioctl(TRUE), relying upon the operating system (or, + ultimately, the terminal database). -
- tput init - Initialize the terminal according to the type of terminal in the - environmental variable TERM. This command should be included in - everyone's .profile after the environmental variable TERM has been - exported, as illustrated on the profile(5) manual page. +
+ -S retrieves more than one capability per invocation of tput. + The capabilities must be passed to tput from the standard + input stream instead of from the command line (see section + "EXAMPLES" below). Only one cap-code is allowed per line. + The -S option changes the meanings of the 0 and 1 exit + statuses (see section "EXIT STATUS" below). - tput -T5620 reset - Reset an AT&T 5620 terminal, overriding the type of terminal in - the environmental variable TERM. + Some capabilities use string parameters rather than numeric + ones. tput employs a built-in table and the presence of + parameters in its input to decide how to interpret them, and + whether to use tparm(3x). - tput cup 0 0 - Send the sequence to move the cursor to row 0, column 0 (the upper - left corner of the screen, usually known as the "home" cursor - position). + -T type indicates the terminal's type. Normally this option is + unnecessary, because a default is taken from the TERM + environment variable. If specified, the environment variables + LINES and COLUMNS are also ignored. - tput clear - Echo the clear-screen sequence for the current terminal. + -V reports the version of ncurses associated with tput, and exits + with a successful status. - tput cols - Print the number of columns for the current terminal. + -x prevents "tput clear" from attempting to clear the scrollback + buffer. - tput -T450 cols - Print the number of columns for the 450 terminal. - bold=`tput smso` offbold=`tput rmso` - Set the shell variables bold, to begin stand-out mode sequence, - and offbold, to end standout mode sequence, for the current - terminal. This might be followed by a prompt: echo "${bold}Please - type in your name: ${offbold}\c" +
+ Normally, one should interpret tput's exit statuses as follows. - tput hc - Set exit code to indicate if the current terminal is a hard copy - terminal. + Status Meaning When -S Not Specified + ------------------------------------------------------------------------ + 0 Boolean or string capability present + 1 Boolean or numeric capability absent + 2 usage error or no terminal type specified + 3 unrecognized terminal type + 4 unrecognized capability code + >4 system error (4 + errno) - tput cup 23 4 - Send the sequence to move the cursor to row 23, column 4. + When the -S option is used, some statuses change meanings. - tput cup - Send the terminfo string for cursor-movement, with no parameters - substituted. + Status Meaning When -S Specified + ------------------------------------------------------------------------ + 0 all operands interpreted + 1 unused + 4 some operands not interpreted - tput longname - Print the long name from the terminfo database for the type of - terminal specified in the environmental variable TERM. - tput -S <<! - > clear - > cup 10 10 - > bold - > ! +
+ tput reads one environment variable. - This example shows tput processing several capabilities in one - invocation. It clears the screen, moves the cursor to position - 10, 10 and turns on bold (extra bright) mode. The list is - terminated by an exclamation mark (!) on a line by itself. + TERM denotes the terminal type. Each terminal type is distinct, + though many are similar. The -T option overrides its value.
- /usr/share/terminfo + /usr/share/tabset + tab stop initialization database + + /usr/share/terminfo compiled terminal description database - /usr/share/tabset/* - tab settings for some terminals, in a format appropriate to be - output to the terminal (escape sequences that set margins and - tabs); for more information, see the Tabs and Initialization, - section of terminfo(5) +
+ Over time ncurses tput has differed from that of System V in two + important respects, one now mostly historical. -
- If the -S option is used, tput checks for errors from each line, and if - any errors are found, will set the exit code to 4 plus the number of - lines with errors. If no errors are found, the exit code is 0. No - indication of which line failed can be given so exit code 1 will never - appear. Exit codes 2, 3, and 4 retain their usual interpretation. If - the -S option is not used, the exit code depends on the type of - capname: + o "tput cap-code" writes to the standard output, which need not be a + terminal device. However, the operands that manipulate terminal + modes might not use the standard output. - boolean - a value of 0 is set for TRUE and 1 for FALSE. + System V tput's init and reset operands use logic from 4.1cBSD + tset, manipulating terminal modes. It checks the same file + descriptors (and /dev/tty) for association with a terminal device + as ncurses now does, and if none are, finally assumes a 1200 baud + terminal. When updating terminal modes, it ignores errors. - string a value of 0 is set if the capname is defined for this - terminal type (the value of capname is returned on standard - output); a value of 1 is set if capname is not defined for - this terminal type (nothing is written to standard output). + Until ncurses 6.1 (see section "HISTORY" below), tput did not + modify terminal modes. It now employs a scheme similar to + System V, using functions shared with tset (and ultimately based on + 4.4BSD tset). If it is not able to open a terminal (for instance, + when run by cron(1)), tput exits with an error status. - integer - a value of 0 is always set, whether or not capname is defined - for this terminal type. To determine if capname is defined - for this terminal type, the user must test the value written - to standard output. A value of -1 means that capname is not - defined for this terminal type. + o System V tput assumes that the type of a cap-code operand is + numeric if all the characters of its value are decimal numbers; if + they are not, it treats cap-code as a string capability. - other reset or init may fail to find their respective files. In - that case, the exit code is set to 4 + errno. + Most implementations that provide support for cap-code operands use + the tparm(3x) function to expand its parameters. That function + expects a mixture of numeric and string parameters, requiring tput + to know which type to use. - Any other exit code indicates an error; see the DIAGNOSTICS section. + ncurses tput uses a table to determine the parameter types for the + standard cap-code operands, and an internal function to analyze + nonstandard cap-code operands. + + While more reliable than System V's utility, a portability problem + is introduced by this analysis. An OpenBSD developer adapted the + internal library function from ncurses to port NetBSD's termcap- + based tput to terminfo, and modified it to interpret multiple cap- + codes (and parameters) on the command line. Portable applications + should not rely upon this feature; ncurses offers it to support + applications written specifically for OpenBSD. + + This implementation, unlike others, accepts both termcap and terminfo + cap-codes if termcap support is compiled in. In that case, however, + the predefined termcap and terminfo codes have two ambiguities; ncurses + assumes the terminfo code. + + o The cap-code dl means delete_line to termcap but parm_delete_line + to terminfo. termcap uses the code DL for parm_delete_line. term- + info uses the code dch1 for delete_line. + + o The cap-code ed means exit_delete_mode to termcap but clr_eos to + terminfo. termcap uses the code cd for clr_eos. terminfo uses the + code rmdc for exit_delete_mode. + + The longname operand, -S option, and the parameter-substitution + features used in the cup example below, were not supported in AT&T/USL + curses before SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for + longname, and in 1994, NetBSD added support for the parameter- + substitution features. + + IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + (POSIX.1-2008) documents only the clear, init, and reset operands. A + few observations of interest arise from that selection. + + o ncurses supports clear as it does any other standard cap-code. The + others (init and longname) do not correspond to terminal + capabilities. + o The tput on SVr4-based systems such as Solaris, IRIX64, and HP-UX, + as well as others such as AIX and Tru64, also support standard cap- + code operands. -
- tput prints the following error messages and sets the corresponding - exit codes. + o A few platforms such as FreeBSD recognize termcap codes rather than + terminfo capability codes in their respective tput commands. Since + 2010, NetBSD's tput uses terminfo codes. Before that, it (like + FreeBSD) recognized termcap codes. - exit code error message - --------------------------------------------------------------------- - 0 (capname is a numeric variable that is not specified in - the terminfo(5) database for this terminal type, e.g. - tput -T450 lines and tput -Thp2621 xmc) - 1 no error message is printed, see the EXIT CODES section. - 2 usage error - 3 unknown terminal type or no terminfo database - 4 unknown terminfo capability capname - >4 error occurred in -S - --------------------------------------------------------------------- + Beginning in 2021, FreeBSD uses ncurses tput, configured for both + terminfo (tested first) and termcap (as a fallback). + Because (apparently) all certified Unix systems support the full set of + capability codes, the reason for documenting only a few may not be + apparent. -
- The tput command was begun by Bill Joy in 1980. The initial version - only cleared the screen. + o X/Open Curses Issue 7 documents tput differently, with cap-code and + the other features used in this implementation. - AT&T System V provided a different tput command: + o That is, there are two standards for tput: POSIX (a subset) and + X/Open Curses (the full implementation). POSIX documents a subset + to avoid the complication of including X/Open Curses and the + terminal capability database. - o SVr2 provided a rudimentary tput which checked the parameter - against each predefined capability and returned the corresponding - value. This version of tput did not use tparm(3x) for the - capabilities which are parameterized. + o While it is certainly possible to write a tput program without + using curses, no system with a curses implementation provides a + tput utility that does not also support standard cap-codes. - o SVr3 replaced that, a year later, by a more extensive program whose - init and reset subcommands (more than half the program) were - incorporated from the reset feature of BSD tset written by Eric - Allman. + X/Open Curses Issue 7 (2009) is the first version to document + utilities. However that part of X/Open Curses does not follow existing + practice (that is, System V curses behavior). - o SVr4 added color initialization using the orig_colors and - orig_pairs capabilities in the init subcommand. + o It assigns exit status 4 to "invalid operand", which may have the + same meaning as "unknown capability". For instance, the source + code for Solaris xcurses uses the term "invalid" in this case. - Keith Bostic replaced the BSD tput command in 1989 with a new - implementation based on the AT&T System V program tput. Like the AT&T - program, Bostic's version accepted some parameters named for terminfo - capabilities (clear, init, longname and reset). However (because he - had only termcap available), it accepted termcap names for other - capabilities. Also, Bostic's BSD tput did not modify the terminal I/O - modes as the earlier BSD tset had done. + o It assigns exit status 255 to a numeric variable that is not + specified in the terminfo database. That likely is a documentation + error, mistaking the "-1" written to the standard output to + indicate an absent or cancelled numeric capability for an + (unsigned) exit status. - At the same time, Bostic added a shell script named "clear", which used - tput to clear the screen. + The various System V implementations (AIX, HP-UX, Solaris) use the same + exit statuses as ncurses. - Both of these appeared in 4.4BSD, becoming the "modern" BSD - implementation of tput. + NetBSD curses documents exit statuses that correspond to neither + ncurses nor X/Open Curses. - This implementation of tput began from a different source than AT&T or - BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in - December 1992. Ridge's program made more sophisticated use of the - terminal capabilities than the BSD program. Eric Raymond used that - tput program (and other parts of mytinfo) in ncurses in June 1995. - Using the portions dealing with terminal capabilities almost without - change, Raymond made improvements to the way the command-line - parameters were handled. +
+ Bill Joy wrote a tput command during development of 4BSD in October + 1980. This initial version only cleared the screen, and did not ship + with official distributions. -
- This implementation of tput differs from AT&T tput in two important - areas: + System V developed a different tput command. - o tput capname writes to the standard output. That need not be a - regular terminal. However, the subcommands which manipulate - terminal modes may not use the standard output. + o SVr2 (1984) provided a rudimentary tput that checked the parameter + against each predefined capability and returned the corresponding + value. This version of tput did not use tparm(3x) for + parameterized capabilities. + + o SVr3 (1987) replaced that with a more extensive program whose + support for init and reset operands (more than half the program) + incorporated the reset feature of BSD tset written by Eric Allman. + + o SVr4 (1989) added color initialization by using the orig_colors + (oc) and orig_pair (op) capabilities in its init logic. + + Keith Bostic refactored BSD tput for shipment in 4.3BSD-Tahoe (1988), + then replaced it the next year with a new implementation based on + System V tput. Bostic's version similarly accepted some parameters + named for terminfo (pseudo-)capabilities: clear, init, longname, and + reset. However, because he had only termcap available, it accepted + termcap codes for other capabilities. Also, Bostic's BSD tput did not + modify the terminal modes as the earlier BSD tset had done. + + At the same time, Bostic added a shell script named "clear" that used + tput to clear the screen. Both of these appeared in 4.4BSD, becoming + the "modern" BSD implementation of tput. + + The origin of ncurses tput lies outside both System V and BSD, in Ross + Ridge's mytinfo package, published on comp.sources.unix in December + 1992. Ridge's program made more sophisticated use of the terminal + capabilities than the BSD program. Eric Raymond used that tput program + (and other parts of mytinfo) in ncurses in June 1995. Incorporating + the portions dealing with terminal capabilities almost without change, + Raymond made improvements to the way command-line parameters were + handled. + + Before ncurses 6.1 (2018), its tset and tput utilities differed. + + o tset was more effective, resetting the terminal modes and special + characters. - The AT&T implementation's init and reset commands use the BSD - (4.1c) tset source, which manipulates terminal modes. It - successively tries standard output, standard error, standard input - before falling back to "/dev/tty" and finally just assumes a 1200Bd - terminal. When updating terminal modes, it ignores errors. + o On the other hand, tset's repertoire of terminal capabilities for + resetting the terminal was more limited; it had only equivalents of + reset_1string (rs1), reset_2string (rs2), and reset_file (rf), and + not the tab stop and margin update features of tput. - Until changes made after ncurses 6.0, tput did not modify terminal - modes. tput now uses a similar scheme, using functions shared with - tset (and ultimately based on the 4.4BSD tset). If it is not able - to open a terminal, e.g., when running in cron, tput will return an - error. + The reset program is traditionally an alias for tset due to its ability + to reset terminal modes and special characters. - o AT&T tput guesses the type of its capname operands by seeing if all - of the characters are numeric, or not. + As of ncurses 6.1, the "reset" features of the two programs are + (mostly) the same. Two minor differences remain. - Most implementations which provide support for capname operands use - the tparm function to expand parameters in it. That function - expects a mixture of numeric and string parameters, requiring tput - to know which type to use. + o The tset program waits one second when resetting, in case the + terminal happens to be a hardware device. - This implementation uses a table to determine the parameter types - for the standard capname operands, and an internal library function - to analyze nonstandard capname operands. - - Besides providing more reliable operation than AT&T's utility, a - portability problem is introduced by this analysis: An OpenBSD - developer adapted the internal library function from ncurses to - port NetBSD's termcap-based tput to terminfo. That had been - modified to interpret multiple commands on a line. Portable - applications should not rely upon this feature; ncurses provides it - to support applications written specifically for OpenBSD. - - This implementation (unlike others) can accept both termcap and - terminfo names for the capname feature, if termcap support is compiled - in. However, the predefined termcap and terminfo names have two - ambiguities in this case (and the terminfo name is assumed): - - o The termcap name dl corresponds to the terminfo name dl1 (delete - one line). - The terminfo name dl corresponds to the termcap name DL (delete a - given number of lines). - - o The termcap name ed corresponds to the terminfo name rmdc (end - delete mode). - The terminfo name ed corresponds to the termcap name cd (clear to - end of screen). - - The longname and -S options, and the parameter-substitution features - used in the cup example, were not supported in BSD curses before - 4.3reno (1989) or in AT&T/USL curses before SVr4 (1988). - - IEEE Std 1003.1/The Open Group Base Specifications Issue 7 - (POSIX.1-2008) documents only the operands for clear, init and reset. - There are a few interesting observations to make regarding that: - - o In this implementation, clear is part of the capname support. The - others (init and longname) do not correspond to terminal - capabilities. + o The two programs write the terminal initialization strings to + different streams; that is, standard error for tset and standard + output for tput. - o Other implementations of tput on SVr4-based systems such as - Solaris, IRIX64 and HPUX as well as others such as AIX and Tru64 - provide support for capname operands. - o A few platforms such as FreeBSD recognize termcap names rather than - terminfo capability names in their respective tput commands. Since - 2010, NetBSD's tput uses terminfo names. Before that, it (like - FreeBSD) recognized termcap names. +
+ tput init + Initialize the terminal according to the type of terminal in the + TERM environment variable. If the system does not reliably + initialize the terminal upon login, this command can be included + in $HOME/.profile after exporting the TERM environment variable. - Beginning in 2021, FreeBSD uses the ncurses tput, configured for - both terminfo (tested first) and termcap (as a fallback). + tput -T5620 reset + Reset an AT&T 5620 terminal, overriding the terminal type in the + TERM environment variable. - Because (apparently) all of the certified Unix systems support the full - set of capability names, the reasoning for documenting only a few may - not be apparent. + tput cnorm + Set cursor to normal visibility. - o X/Open Curses Issue 7 documents tput differently, with capname and - the other features used in this implementation. + tput home + Move the cursor to row 0, column 0: the upper left corner of the + screen, usually known as the "home" cursor position. - o That is, there are two standards for tput: POSIX (a subset) and - X/Open Curses (the full implementation). POSIX documents a subset - to avoid the complication of including X/Open Curses and the - terminal capabilities database. + tput clear + Clear the screen: write the clear_screen capability's value to + the standard output stream. - o While it is certainly possible to write a tput program without - using curses, none of the systems which have a curses - implementation provide a tput utility which does not provide the - capname feature. + tput cols + Report the number of columns used by the current terminal type. - X/Open Curses Issue 7 (2009) is the first version to document - utilities. However that part of X/Open Curses does not follow existing - practice (i.e., Unix features documented in SVID 3): + tput -Tadm3a cols + Report the number of columns used by an ADM-3A terminal. - o It assigns exit code 4 to "invalid operand", which may be the same - as unknown capability. For instance, the source code for Solaris' - xcurses uses the term "invalid" in this case. + strong=`tput smso` normal=`tput rmso` + Set shell variables to capability values: strong and normal, to + begin and end, respectively, stand-out mode for the terminal. + One might use these to present a prompt. - o It assigns exit code 255 to a numeric variable that is not - specified in the terminfo database. That likely is a documentation - error, confusing the -1 written to the standard output for an - absent or cancelled numeric value versus an (unsigned) exit code. + printf "${strong}Username:${normal} " - The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes - as ncurses. + tput hc + Indicate via exit status whether the terminal is a hard copy + device. - NetBSD curses documents different exit codes which do not correspond to - either ncurses or X/Open. + tput cup 23 4 + Move the cursor to row 23, column 4. + tput cup + Report the value of the cursor_address (cup) capability (used + for cursor movement), with no parameters substituted. -
- clear(1), stty(1), tabs(1), tset(1), curs_termcap(3x), terminfo(5). + tput longname + Report the terminfo database's description of the terminal type + specified in the TERM environment variable. + + tput -S + Process multiple capabilities. The -S option can be profitably + used with a shell "here document". - This describes ncurses version 6.2 (patch 20211002). + $ tput -S <<! + > clear + > cup 10 10 + > bold + > ! + The foregoing clears the screen, moves the cursor to position + (10, 10) and turns on bold (extra bright) mode. + tput clear cup 10 10 bold + Perform the same actions as the foregoing "tput -S" example. - tput(1) + +
+ clear(1), stty(1), tabs(1), tset(1), curs_termcap(3x), terminfo(5) + + + +ncurses 6.4 2024-03-23 tput(1)