mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-25 11:37:56 +00:00
333 lines
12 KiB
Groff
333 lines
12 KiB
Groff
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright (c) 1998-2011,2012 Free Software Foundation, Inc. *
|
|
.\" *
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|
.\" copy of this software and associated documentation files (the *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" sale, use or other dealings in this Software without prior written *
|
|
.\" authorization. *
|
|
.\"***************************************************************************
|
|
.\"
|
|
.\" $Id: tput.1,v 1.32 2012/07/14 21:06:45 tom Exp $
|
|
.TH @TPUT@ 1 ""
|
|
.ds d @TERMINFO@
|
|
.ds n 1
|
|
.SH NAME
|
|
\fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
|
|
.SH SYNOPSIS
|
|
\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparms\fR ... ]
|
|
.br
|
|
\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
|
|
.br
|
|
\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
|
|
.br
|
|
\fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
|
|
.br
|
|
\fB@TPUT@ \-S\fR \fB<<\fR
|
|
.br
|
|
\fB@TPUT@ \-V\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
|
|
values of terminal-dependent capabilities and information available to
|
|
the shell (see \fBsh\fR(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:
|
|
.RS
|
|
.TP 5
|
|
string
|
|
\fB@TPUT@\fR writes the string to the standard output.
|
|
No trailing newline is supplied.
|
|
.TP
|
|
integer
|
|
\fB@TPUT@\fR writes the decimal value to the standard output,
|
|
with a trailing newline.
|
|
.TP
|
|
boolean
|
|
\fB@TPUT@\fR simply sets the exit code
|
|
(\fB0\fR for TRUE if the terminal has the capability,
|
|
\fB1\fR for FALSE if it does not),
|
|
and writes nothing to the standard output.
|
|
.RE
|
|
.PP
|
|
Before using a value returned on the standard output,
|
|
the application should test the exit code
|
|
(e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
|
|
(See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
|
|
For a complete list of capabilities
|
|
and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
|
|
.TP
|
|
\fB\-T\fR\fItype\fR
|
|
indicates the \fItype\fR of terminal.
|
|
Normally this option is
|
|
unnecessary, because the default is taken from the environment
|
|
variable \fBTERM\fR.
|
|
If \fB\-T\fR is specified, then the shell
|
|
variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
|
|
.TP
|
|
\fIcapname\fR
|
|
indicates the capability from the \fBterminfo\fR database. When
|
|
\fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
|
|
the capability is also accepted.
|
|
.TP
|
|
\fIparms\fR
|
|
If the capability is a string that takes parameters, the arguments
|
|
\fIparms\fR will be instantiated into the string.
|
|
.IP
|
|
Most parameters are numbers.
|
|
Only a few terminfo capabilities require string parameters;
|
|
\fB@TPUT@\fR uses a table to decide which to pass as strings.
|
|
Normally \fB@TPUT@\fR uses \fBtparm\fR (3X) to perform the substitution.
|
|
If no parameters are given for the capability,
|
|
\fB@TPUT@\fR writes the string without performing the substitution.
|
|
.TP
|
|
\fB\-S\fR
|
|
allows more than one capability per invocation of \fB@TPUT@\fR. The
|
|
capabilities must be passed to \fB@TPUT@\fR from the standard input
|
|
instead of from the command line (see example).
|
|
Only one \fIcapname\fR is allowed per line.
|
|
The \fB\-S\fR option changes the
|
|
meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
|
|
EXIT CODES section).
|
|
.IP
|
|
Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
|
|
to decide whether to use \fBtparm\fR (3X),
|
|
and how to interpret the parameters.
|
|
.TP
|
|
\fB\-V\fR
|
|
reports the version of ncurses which was used in this program, and exits.
|
|
.TP
|
|
\fBinit\fR
|
|
If the \fBterminfo\fR database is present and an entry for the user's
|
|
terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
|
|
occur:
|
|
.RS
|
|
.TP
|
|
(1)
|
|
if present, the terminal's initialization strings will be
|
|
output as detailed in the \fBterminfo\fR(5) section on
|
|
.IR "Tabs and Initialization" ,
|
|
.TP
|
|
(2)
|
|
any delays (e.g., newline) specified in the entry will
|
|
be set in the tty driver,
|
|
.TP
|
|
(3)
|
|
tabs expansion will be turned on or off according to
|
|
the specification in the entry, and
|
|
.TP
|
|
(4)
|
|
if tabs are not expanded,
|
|
standard tabs will be set (every 8 spaces).
|
|
.RE
|
|
.IP
|
|
If an entry does not
|
|
contain the information needed for any of the four above activities,
|
|
that activity will silently be skipped.
|
|
.TP
|
|
\fBreset\fR
|
|
Instead of putting out initialization strings, the terminal's
|
|
reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
|
|
If the reset strings are not present, but initialization
|
|
strings are, the initialization strings will be output.
|
|
Otherwise, \fBreset\fR acts identically to \fBinit\fR.
|
|
.TP
|
|
\fBlongname\fR
|
|
If the \fBterminfo\fR database is present and an entry for the
|
|
user's terminal exists (see \fB\-T\fR\fItype\fR 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
|
|
\fBterminfo\fR database [see \fBterm\fR(5)].
|
|
.PP
|
|
If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
|
|
same effect as \fB@TPUT@ reset\fR.
|
|
See \fB@TSET@\fR for comparison, which has similar behavior.
|
|
.SH EXAMPLES
|
|
.TP 5
|
|
\fB@TPUT@ init\fR
|
|
Initialize the terminal according to the type of
|
|
terminal in the environmental variable \fBTERM\fR. This
|
|
command should be included in everyone's .profile after
|
|
the environmental variable \fBTERM\fR has been exported, as
|
|
illustrated on the \fBprofile\fR(5) manual page.
|
|
.TP 5
|
|
\fB@TPUT@ \-T5620 reset\fR
|
|
Reset an AT&T 5620 terminal, overriding the type of
|
|
terminal in the environmental variable \fBTERM\fR.
|
|
.TP 5
|
|
\fB@TPUT@ cup 0 0\fR
|
|
Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
|
|
(the upper left corner of the screen, usually known as the "home"
|
|
cursor position).
|
|
.TP 5
|
|
\fB@TPUT@ clear\fR
|
|
Echo the clear-screen sequence for the current terminal.
|
|
.TP 5
|
|
\fB@TPUT@ cols\fR
|
|
Print the number of columns for the current terminal.
|
|
.TP 5
|
|
\fB@TPUT@ \-T450 cols\fR
|
|
Print the number of columns for the 450 terminal.
|
|
.TP 5
|
|
\fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
|
|
Set the shell variables \fBbold\fR, to begin stand-out mode
|
|
sequence, and \fBoffbold\fR, to end standout mode sequence,
|
|
for the current terminal. This might be followed by a
|
|
prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
|
|
.TP 5
|
|
\fB@TPUT@ hc\fR
|
|
Set exit code to indicate if the current terminal is a hard copy terminal.
|
|
.TP 5
|
|
\fB@TPUT@ cup 23 4\fR
|
|
Send the sequence to move the cursor to row 23, column 4.
|
|
.TP 5
|
|
\fB@TPUT@ cup\fR
|
|
Send the terminfo string for cursor-movement, with no parameters substituted.
|
|
.TP 5
|
|
\fB@TPUT@ longname\fR
|
|
Print the long name from the \fBterminfo\fR database for the
|
|
type of terminal specified in the environmental
|
|
variable \fBTERM\fR.
|
|
.PP
|
|
.RS 5
|
|
\fB@TPUT@ \-S <<!\fR
|
|
.br
|
|
\fB> clear\fR
|
|
.br
|
|
\fB> cup 10 10\fR
|
|
.br
|
|
\fB> bold\fR
|
|
.br
|
|
\fB> !\fR
|
|
.RE
|
|
.TP 5
|
|
\&
|
|
This example shows \fB@TPUT@\fR 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 (\fB!\fR) on a line by itself.
|
|
.SH FILES
|
|
.TP
|
|
\fB\*d\fR
|
|
compiled terminal description database
|
|
.TP
|
|
\fB@DATADIR@/tabset/*\fR
|
|
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 \fBterminfo\fR(5)
|
|
.SH EXIT CODES
|
|
If the \fB\-S\fR option is used,
|
|
\fB@TPUT@\fR 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 \fB0\fR.
|
|
No indication of which line failed can be given so
|
|
exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
|
|
\fB4\fR retain their usual interpretation.
|
|
If the \fB\-S\fR option is not used,
|
|
the exit code depends on the type of \fIcapname\fR:
|
|
.RS 5
|
|
.TP
|
|
.I boolean
|
|
a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
|
|
.TP
|
|
.I string
|
|
a value of \fB0\fR is set if the
|
|
\fIcapname\fR is defined for this terminal \fItype\fR (the value of
|
|
\fIcapname\fR is returned on standard output);
|
|
a value of \fB1\fR is set if \fIcapname\fR
|
|
is not defined for this terminal \fItype\fR
|
|
(nothing is written to standard output).
|
|
.TP
|
|
.I integer
|
|
a value of \fB0\fR is always set,
|
|
whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
|
|
To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
|
|
the user must test the value written to standard output.
|
|
A value of \fB\-1\fR
|
|
means that \fIcapname\fR is not defined for this terminal \fItype\fR.
|
|
.TP
|
|
.I other
|
|
\fBreset\fR or \fBinit\fR may fail to find their respective files.
|
|
In that case, the exit code is set to 4 + \fBerrno\fR.
|
|
.RE
|
|
.PP
|
|
Any other exit code indicates an error; see the DIAGNOSTICS section.
|
|
.SH DIAGNOSTICS
|
|
\fB@TPUT@\fR prints the following error messages and sets the corresponding exit
|
|
codes.
|
|
.PP
|
|
.ne 15
|
|
.TS
|
|
l l.
|
|
exit code error message
|
|
=
|
|
\fB0\fR T{
|
|
(\fIcapname\fR is a numeric variable that is not specified in the
|
|
\fBterminfo\fR(5) database for this terminal type, e.g.
|
|
\fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
|
|
T}
|
|
\fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
|
|
\fB2\fR usage error
|
|
\fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
|
|
\fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
|
|
\fB>4\fR error occurred in \-S
|
|
=
|
|
.TE
|
|
.SH PORTABILITY
|
|
.PP
|
|
The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
|
|
features used in the \fBcup\fR example, are not supported in BSD curses or in
|
|
AT&T/USL curses before SVr4.
|
|
.PP
|
|
X/Open documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
|
|
In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
|
|
Other implementations of \fB@TPUT@\fP on
|
|
SVr4-based systems such as Solaris, IRIX64 and HPUX
|
|
as well as others such as AIX and Tru64
|
|
provide support for \fIcapname\fR operands.
|
|
.PP
|
|
A few platforms such as FreeBSD and NetBSD recognize termcap names rather
|
|
than terminfo capability names in their respective \fB@TPUT@\fP commands.
|
|
.PP
|
|
Most implementations which provide support for \fIcapname\fR operands
|
|
use the \fItparm\fP function to expand parameters in it.
|
|
That function expects a mixture of numeric and string parameters,
|
|
requiring \fB@TPUT@\fP to know which type to use.
|
|
This implementation uses a table to determine that for
|
|
the standard \fIcapname\fR operands, and an internal library
|
|
function to analyze nonstandard \fIcapname\fR operands.
|
|
Other implementations may simply guess that an operand containing only digits
|
|
is intended to be a number.
|
|
.SH SEE ALSO
|
|
\fB@CLEAR@\fR(1),
|
|
\fBstty\fR(1),
|
|
\fBtabs\fR(\*n),
|
|
\fBterminfo\fR(5),
|
|
\fBcurs_termcap\fR(3X).
|
|
.PP
|
|
This describes \fBncurses\fR
|
|
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
|