aboutsummaryrefslogtreecommitdiff
path: root/man/tput.1
diff options
context:
space:
mode:
authorRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
committerRong-En Fan <rafan@FreeBSD.org>2008-11-09 09:06:04 +0000
commita388f199193767bacbb38b172ab89cb84369736c (patch)
treea1816f5667d2280b970ca44e407bac8cc4496c0a /man/tput.1
parentaa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff)
downloadsrc-a388f199193767bacbb38b172ab89cb84369736c.tar.gz
src-a388f199193767bacbb38b172ab89cb84369736c.zip
- Flatten the vendor area
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=184786
Diffstat (limited to 'man/tput.1')
-rw-r--r--man/tput.1325
1 files changed, 325 insertions, 0 deletions
diff --git a/man/tput.1 b/man/tput.1
new file mode 100644
index 000000000000..bada0b1595ed
--- /dev/null
+++ b/man/tput.1
@@ -0,0 +1,325 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998-2005,2006 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.27 2006/12/24 18:11:31 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 be ignored,and the
+operating system will not be queried for the actual screen size.
+.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 \fBtset\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
+\fBtput\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 \fBtput\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.
+A few platforms such as FreeBSD and NetBSD recognize termcap names rather
+than terminfo capability names in their respective \fBtput\fP commands.
+.SH SEE ALSO
+\fB@CLEAR@\fR(1),
+\fBstty\fR(1),
+\fBtabs\fR(\*n),
+\fBterminfo\fR(5).
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: