+ tput, reset - initialize a terminal or query terminfo
+ database
-
-
DESCRIPTION
- 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. tput outputs a string if the attribute
- (capability name) is of type string, or an integer if the
- attribute is of type integer. If the attribute is of type
- boolean, tput simply sets the exit code (0 for TRUE if the
- terminal has the capability, 1 for FALSE if it does not),
- and produces no output. Before using a value returned on
- standard output, the user should test the exit code [$?,
- see sh(1)] to be sure it is 0. (See the EXITCODES and
- DIAGNOSTICS sections.) For a complete list of capabili-
- ties and the capname associated with each, see ter-
- minfo(5).
-
- -Ttype indicates the type of terminal. Normally this
+
+
+ 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:
+
+ string
+ tput writes the string to the standard output. No
+ trailing newline is supplied.
+
+ integer
+ tput writes the decimal value to the standard out-
+ put, with a trailing newline.
+
+ 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 out-
+ put.
+
+ 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 EXITCODES and DIAG-
+ NOSTICS sections.) For a complete list of capabilities
+ and the capname associated with each, see terminfo(5).
+
+
+
+ -Ttype indicates the type of terminal. Normally this
option is unnecessary, because the default is taken
- from the environment variable TERM. If -T is spec-
- ified, then the shell variables LINES and COLUMNS
- will be ignored,and the operating system will not
- be queried for the actual screen size.
-
- capname
- indicates the attribute from the terminfo database.
- When termcap support is compiled in, the termcap
- name for the attribute is also accepted.
-
- parms If the attribute is a string that takes parameters,
- the arguments parms will be instantiated into the
- string. An all numeric argument will be passed to
- the attribute as a number.
-
- -S allows more than one capability per invocation of
- tput. The capabilities must be passed to tput from
+ from the environment variable TERM. If -T is spec-
+ ified, then the shell variables LINES and COLUMNS
+ will also be ignored.
+
+ -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
+ (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).
- init If the terminfo database is present and an entry
- for the user's terminal exists (see -Ttype, above),
- the following will occur: (1) if present, the ter-
- minal's initialization strings will be output (is1,
- is2, is3, if, iprog), (2) any delays (e.g., new-
- line) specified in the entry will be set in the tty
- driver, (3) tabs expansion will be turned on or off
- according to the specification in the entry, and
- (4) if tabs are not expanded, standard tabs will be
- set (every 8 spaces). If an entry does not contain
- the information needed for any of the four above
- 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.
-
- longname
- If the terminfo database is present and an entry
- for the user's terminal exists (see -Ttype above),
+ 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.
+
+ -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 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 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 substitu-
+ tion.
+
+ init If the terminal database is present and an entry
+ for the user's terminal exists (see -Ttype, above),
+ the following will occur:
+
+ (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"
+
+ to obtain terminal settings. Having retrieved
+ these settings, tput remembers which file
+ descriptor to use when updating settings.
+
+ (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 TabsandInitialization,
+
+ (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 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 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)].
+ the terminal's description in the terminfo database
+ [see term(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.
+
+ If tput is invoked by a link named reset, this has the
+ same effect as tputreset. The tset(1) utility also
+ treats a link named reset specially.
+
+ Before ncurses 6.1, the two utilities were different from
+ each other:
+
+ otset utility reset the terminal modes and special
+ characters (not done with tput).
+
+ o On the other hand, tset's repertoire of terminal capa-
+ bilities 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 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 tputinit. Again, you are less likely to use
+ that link because another program named init has a more
+ well-established use.
+
+
+
+ tputinit
Initialize the terminal according to the type of ter-
- minal in the environmental variable TERM. This com-
+ 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(4) manual page.
+ the environmental variable TERM has been exported, as
+ illustrated on the profile(5) manual page.
- tput-T5620reset
+ tput-T5620reset
Reset an AT&T 5620 terminal, overriding the type of
- terminal in the environmental variable TERM.
+ terminal in the environmental variable TERM.
- tputcup00
- Send the sequence to move the cursor to row 0, column
- 0 (the upper left corner of the screen, usually known
+ tputcup00
+ 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).
- tputclear
+ tputclear
Echo the clear-screen sequence for the current termi-
nal.
- tputcols
+ tputcols
Print the number of columns for the current terminal.
- tput-T450cols
+ tput-T450cols
Print the number of columns for the 450 terminal.
+ bold=`tputsmso`offbold=`tputrmso`
+ 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}Pleasetypeinyourname:
+ ${offbold}\c"
- bold=`tputsmso`offbold=`tputrmso`
- 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}Pleasetypeinyourname:
- ${offbold}\c"
-
- tputhc
- Set exit code to indicate if the current terminal is
+ tputhc
+ Set exit code to indicate if the current terminal is
a hard copy terminal.
- tputcup234
- Send the sequence to move the cursor to row 23, col-
+ tputcup234
+ Send the sequence to move the cursor to row 23, col-
umn 4.
- tputlongname
- Print the long name from the terminfo database for
+ tputcup
+ Send the terminfo string for cursor-movement, with no
+ parameters substituted.
+
+ tputlongname
+ Print the long name from the terminfo database for
the type of terminal specified in the environmental
- variable TERM.
+ variable TERM.
- tput-S<<!
- >clear
- >cup1010
- >bold
- >!
+ tput-S<<!
+ >clear
+ >cup1010
+ >bold
+ >!
- This example shows tput processing several capabili-
- ties in one invocation. This example 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.
+ 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.
-
+ /usr/share/terminfo
compiled terminal description database
- /usr/include/curses.h
- curses(3x) header file
-
- /usr/include/term.h
- terminfo header file
-
- @DATADIR@/tabset/*
+ /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-
- tion of terminfo(4)
-
-
-
- If capname is of type boolean, a value of 0 is set for
- TRUE and 1 for FALSE unless the -S option is used.
-
- If capname is of type 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 (a
- null value is returned on standard output).
-
- If capname is of type boolean or string and the -S option
- is used, a value of 0 is returned to indicate that all
- lines were successful. 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 capname is of type 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 of standard output. A value
- of -1 means that capname is not defined for this terminal
- type.
+ information, see the TabsandInitialization, 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 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:
+
+ 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
+ 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
+ capname is not defined for this terminal type.
+
+ otherreset 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-
TICS section.
-
-
DIAGNOSTICS
- tput prints the following error messages and sets the cor-
+
+ tput prints the following error messages and sets the cor-
responding exit 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-T450lines and tput-T2621xmc)
- 1 no error message is printed, see the EXITCODES section.
- 2 usage error
- 3 unknown terminal type or no terminfo database
- 4 unknown terminfo capability capname
-
-
-
-
PORTABILITY
- The longname and -S options, and the parameter-substitu-
- tion features used in the cup example, are not supported
- in BSD curses or in AT&T/USL curses before SVr4.
-
-
-
-
-
-
-
-
-
-
-
+ ---------------------------------------------------------------------
+ 0 (capname is a numeric variable that is not specified in
+ the terminfo(5) database for this terminal type, e.g.
+ tput-T450lines and tput-T2621xmc)
+ 1 no error message is printed, see the EXITCODES section.
+ 2 usage error
+ 3 unknown terminal type or no terminfo database
+ 4 unknown terminfo capability capname
+ >4 error occurred in -S
+ ---------------------------------------------------------------------
+
+
+
+ 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)
+ were incorporated from the reset feature of BSD tset writ-
+ 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 terminfocapabilities (clear,
+ init, longname and reset). However (because he had only
+ termcap available), it accepted termcapnames 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
+ "clear", which used tput to clear the screen.
+
+ 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
+ important areas:
+
+ otputcapname writes to the standard output. That need
+ 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 BSD (4.1c) tset source, which manipulates terminal
+ 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
+ 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
+ will return an error.
+
+ 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
+ in it. That function expects a mixture of numeric and
+ string parameters, requiring tput to know which type
+ to use.
+
+ 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.
+
+ 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
+ to make regarding that:
+
+ 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-
+ 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)
+ recognized termcap names.
+
+ 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-
+ 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
+ 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
+ does not provide the capname feature.
+
+
+