X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Ftput.1.html;h=db32031e47a9213d234c9a522d7bcb440f1d0ce3;hp=000d45a94ced11d6ed3e5db56c59dd268054b6d4;hb=a8e3f06ac309504143cd56ac9ec55889bfdf4914;hpb=f06e14af5e11df95d6542964bf1b349d2843bb11 diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html index 000d45a9..db32031e 100644 --- a/doc/html/man/tput.1.html +++ b/doc/html/man/tput.1.html @@ -1,7 +1,7 @@ @@ -107,61 +107,109 @@ Again, tput uses a table and the presence of param- eters in its input to decide whether to use - tparm(3x), and how to interpret the parameters. + tparm(3x), and how to interpret the parameters. -V reports the version of ncurses which was used in this program, and exits.
+ 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 ter- + minfo(5) for a list). Although init and reset resemble + capability names, tput uses several capabilities to per- + form these special functions. + capname - indicates the capability from the terminfo data- - base. When termcap support is compiled in, the - termcap name for the capability is also accepted. + indicates the capability from the terminal data- + base. If the capability is a string that takes parame- ters, the arguments following the capability will be used as parameters for the string. - Most parameters are numbers. Only a few terminfo + 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. + tput uses tparm(3x) to perform the substitution. If no parameters are given for the capability, tput writes the string without performing the substitu- tion. - init If the terminfo database is present and an entry + init If the terminal database is present and an entry for the user's terminal exists (see -Ttype, above), the following will occur: - (1) if present, the terminal's initialization - strings will be output as detailed in the ter- - minfo(5) section on Tabs and Initialization, + (1) first, tput retrieves the current terminal + mode settings for your terminal. It does this + by successively testing + + o the standard error, + + o standard output, + + o standard input and + + o ultimately "/dev/tty" - (2) any delays (e.g., newline) specified in the - entry will be set in the tty driver, + to obtain terminal settings. Having retrieved + these settings, tput remembers which file + descriptor to use when updating settings. - (3) tabs expansion will be turned on or off - according to the specification in the entry, - and + (2) if the window size cannot be obtained from the + operating system, but the terminal description + (or environment, e.g., LINES and COLUMNS vari- + ables specify this), update the operating sys- + tem's notion of the window size. + + (3) the terminal modes will be updated: + + o any delays (e.g., newline) specified in + the entry will be set in the tty driver, + + o tabs expansion will be turned on or off + according to the specification in the + entry, and + + o if tabs are not expanded, standard tabs + will be set (every 8 spaces). + + (4) if present, the terminal's initialization + strings will be output as detailed in the ter- + minfo(5) section on Tabs and Initialization, - (4) if tabs are not expanded, standard tabs will - be set (every 8 spaces). + (5) output is flushed. If an entry does not contain the information needed for any of these activities, that activity will silently be skipped. - reset 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 ini- - tialization strings will be output. Otherwise, - reset acts identically to init. + reset This is similar to init, with two differences: + + (1) before any other initialization, the terminal + modes will be reset to a "sane" state: + + o set cooked and echo modes, + + o turn off cbreak and raw modes, + + o turn on newline translation and + + o reset any unset special characters to + their default values + + (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. + + Otherwise, reset acts identically to init. longname - If the terminfo database is present and an entry + 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 @@ -194,22 +242,39 @@ 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 differ- + ences remain: + + o The tset program waits one second when resetting, in + case it happens to be a hardware terminal. + + 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). + + Note: although these programs write to different + streams, redirecting their output to a file will cap- + ture only part of their actions. The changes to the + terminal modes are not affected by redirecting the + output. + 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 + effect as tput init. Again, you are less likely to use + that link because another program named init has a more well-established use.
tput init Initialize the terminal according to the type of ter- - minal in the environmental variable TERM. This com- - mand should be included in everyone's .profile after + minal in the environmental variable TERM. This com- + mand should be included in everyone's .profile after the environmental variable TERM has been exported, as illustrated on the profile(5) manual page. tput -T5620 reset - Reset an AT&T 5620 terminal, overriding the type of + Reset an AT&T 5620 terminal, overriding the type of terminal in the environmental variable TERM. tput cup 0 0 @@ -230,16 +295,16 @@ 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: + for the current terminal. This might be followed by + a prompt: echo "${bold}Please type in your name: ${offbold}\c" tput hc - Set exit code to indicate if the current terminal is + Set exit code to indicate if the current terminal is a hard copy terminal. tput cup 23 4 - Send the sequence to move the cursor to row 23, col- + Send the sequence to move the cursor to row 23, col- umn 4. tput cup @@ -247,8 +312,8 @@ parameters substituted. tput longname - Print the long name from the terminfo database for - the type of terminal specified in the environmental + Print the long name from the terminfo database for + the type of terminal specified in the environmental variable TERM. tput -S <<! @@ -257,10 +322,10 @@ > bold > ! - This example shows tput processing several capabili- - ties 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 + This example shows tput processing several capabili- + ties 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. @@ -270,44 +335,44 @@ /usr/share/tabset/* tab settings for some terminals, in a format appro- - priate to be output to the terminal (escape - sequences that set margins and tabs); for more - information, see the Tabs and Initialization, sec- + priate to be output to the terminal (escape + sequences that set margins and tabs); for more + information, see the Tabs and Initialization, sec- tion of terminfo(5)
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, 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. + 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: boolean a value of 0 is set for TRUE and 1 for FALSE. - 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 + 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). integer - a value of 0 is always set, whether or not cap- - name is defined for this terminal type. To - determine if capname is defined for this termi- - nal type, the user must test the value written - to standard output. A value of -1 means that + a value of 0 is always set, whether or not cap- + name is defined for this terminal type. To + determine if capname is defined for this termi- + nal 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. - other reset or init may fail to find their respective - files. In that case, the exit code is set to 4 + other reset or init may fail to find their respective + files. In that case, the exit code is set to 4 + errno. - Any other exit code indicates an error; see the DIAGNOS- + Any other exit code indicates an error; see the DIAGNOS- TICS section. @@ -317,8 +382,8 @@ 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. + 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 -T2621 xmc) 1 no error message is printed, see the EXIT CODES section. 2 usage error @@ -329,119 +394,143 @@
- The tput command was begun by Bill Joy in 1980. The ini- + The tput command was begun by Bill Joy in 1980. The ini- tial version only cleared the screen. - AT&T System V provided a different tput command, whose - init and reset subcommands (more than half the program) + AT&T System V provided a different tput command, whose + init and reset subcommands (more than half the program) were incorporated from the reset feature of BSD tset writ- - ten by Eric Allman. Later the corresponding source code - for reset was removed from the BSD tset (in June 1993, - released in 4.4BSD-Lite a year later). - - 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 + ten by Eric Allman. + + 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. - At the same time, Bostic added a shell script named + At the same time, Bostic added a shell script named "clear", which used tput to clear the screen. - Both of these appeared in 4.4BSD, becoming the "modern" + Both of these appeared in 4.4BSD, becoming the "modern" BSD implementation of tput. + 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 the 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. +
- This implementation of tput differs from AT&T tput in two + This implementation of tput differs from AT&T tput in two important areas: 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 stan- + not be a regular terminal. However, the subcommands + which manipulate terminal modes may not use the stan- dard output. - The AT&T implementation's init and reset commands use + 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, stan- - dard error, standard input before falling back to + modes. It successively tries standard output, stan- + dard error, standard input before falling back to "/dev/tty" and finally just assumes a 1200Bd terminal. When updating terminal modes, it ignores errors. - Until changes made after ncurses 6.0, tput did not + 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 ulti- - mately based on the 4.4BSD tset). If it is not able - to open a terminal, e.g., when running in cron, tput + scheme, using functions shared with tset (and ulti- + mately 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. - o AT&T tput guesses the type of its capname operands by + o AT&T tput guesses the type of its capname operands by seeing if all of the characters are numeric, or not. Most implementations which provide support for capname - operands use the tparm function to expand parameters + 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 + string parameters, requiring tput to know which type to use. - This implementation uses a table to determine the + This implementation uses a table to determine the parameter types for the standard capname operands, and - an internal library function to analyze nonstandard + an internal library function to analyze nonstandard capname operands. - The longname and -S options, and the parameter-substitu- - tion features used in the cup example, were not supported - in BSD curses before 4.3reno (1989) or in AT&T/USL curses + This implementation (unlike others) can accept both term- + cap 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-substitu- + tion 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 + 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 + o In this implementation, clear is part of the capname support. The others (init and longname) do not corre- spond to terminal capabilities. - 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 op- + 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 op- erands. - 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) + 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. - Because (apparently) all of the certified Unix systems - support the full set of capability names, the reasoning + 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. o X/Open Curses Issue 7 documents tput differently, with - capname and the other features used in this implemen- + capname and the other features used in this implemen- tation. - 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 + 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. 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 + curses implementation provide a tput utility which does not provide the capname feature.
- clear(1), stty(1), tabs(1), tset(1), terminfo(5), + clear(1), stty(1), tabs(1), tset(1), terminfo(5), curs_termcap(3x). - This describes ncurses version 6.0 (patch 20161022). + This describes ncurses version 6.0 (patch 20170422).