path: root/usr/src/man/man1/tput.1

'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1992, X/Open Company Limited  All Rights Reserved  Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at 
.\" http://www.opengroup.org/bookstore/.
.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
.\"  This notice shall appear on any product containing this material.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH tput 1 "1 Feb 1995" "SunOS 5.11" "User Commands"
.SH NAME
tput \- initialize a terminal or query terminfo database
.SH SYNOPSIS
.LP
.nf
\fBtput\fR [\fB-T\fR \fItype\fR] \fIcapname\fR [\fIparm\fR]...
.fi

.LP
.nf
\fBtput\fR \fB-S\fR <<
.fi

.SH DESCRIPTION
.sp
.LP
The \fBtput\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 clear, initialize or reset the terminal; or to return the long
name of the requested terminal type. \fBtput\fR outputs a string if the
capability attribute (\fIcapname\fR) is of type string, or an integer if the
attribute is of type integer. If the attribute is of type boolean, \fBtput\fR
simply sets the exit status (\fB0\fR for \fBTRUE\fR if the terminal has the
capability, \fB1\fR for \fBFALSE\fR if it does not), and produces no output.
Before using a value returned on standard output, the user should test the exit
status (\fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR. See the EXIT
STATUS section.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-T\fR\fItype\fR \fR
.ad
.RS 11n
.rt  
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
and the layer size will not be referenced.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-S\fR \fR
.ad
.RS 11n
.rt  
Allows more than one capability per invocation of \fBtput\fR. The capabilities
must be passed to \fBtput\fR from the standard input instead of from the
command line (see the example in the EXAMPLES section). 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 statuses (see the EXAMPLES section).
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIcapname\fR \fR
.ad
.RS 12n
.rt  
Indicates the capability attribute from the \fBterminfo\fR database. See
\fBterminfo\fR(4) for a complete list of capabilities and the \fIcapname\fR
associated with each.
.sp
The following strings will be supported as operands by the implementation in
the "C" locale:
.sp
.ne 2
.mk
.na
\fB\fBclear\fR \fR
.ad
.RS 13n
.rt  
Display the clear-screen sequence.
.RE

.sp
.ne 2
.mk
.na
\fB\fBinit\fR \fR
.ad
.RS 13n
.rt  
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 +4
.TP
1.
if present, the terminal's initialization strings will be output (\fBis1\fR,
\fBis2\fR, \fBis3\fR, \fBif\fR, \fBiprog\fR),
.RE
.RS +4
.TP
2.
any delays (for instance, newline) specified in the entry will be set in the
tty driver,
.RE
.RS +4
.TP
3.
tabs expansion will be turned on or off according to the specification in
the entry, and
.RE
.RS +4
.TP
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.
.RE
.RE

.sp
.ne 2
.mk
.na
\fB\fBreset\fR \fR
.ad
.RS 13n
.rt  
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.
.RE

.sp
.ne 2
.mk
.na
\fB\fBlongname\fR \fR
.ad
.RS 13n
.rt  
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)).
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIparm\fR \fR
.ad
.RS 12n
.rt  
If the attribute is a string that takes parameters, the argument \fIparm\fR
will be instantiated into the string. An all numeric argument will be passed to
the attribute as a number.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRInitializing the terminal according to TERM
.sp
.LP
This example initializes the terminal according to the type of terminal in the
environment variable \fBTERM\fR. This command should be included in
everyone's .profile after the environment variable \fBTERM\fR has been exported, as
illustrated on the \fBprofile\fR(4) manual page.

.sp
.in +2
.nf
example% \fBtput init\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRResetting a terminal
.sp
.LP
This example resets an AT&T 5620 terminal, overriding the type of terminal in
the environment variable \fBTERM\fR:

.sp
.in +2
.nf
example% \fBtput -T5620 reset\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRMoving the cursor
.sp
.LP
The following example sends 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).

.sp
.in +2
.nf
example% \fBtput cup 0 0\fR
.fi
.in -2
.sp

.sp
.LP
This next example sends the sequence to move the cursor to row \fB23\fR, column
\fB4\fR.

.sp
.in +2
.nf
example% \fBtput cup 23 4\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fREchoing the clear-screen sequence
.sp
.LP
This example echos the clear-screen sequence for the current terminal.

.sp
.in +2
.nf
example% \fBtput clear\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRPrinting the number of columns
.sp
.LP
This command prints the number of columns for the current terminal.

.sp
.in +2
.nf
example% \fBtput cols\fR
.fi
.in -2
.sp

.sp
.LP
The following command prints the number of columns for the 450 terminal.

.sp
.in +2
.nf
example% \fBtput -T450 cols\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRSetting shell variables
.sp
.LP
This example sets 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:

.sp
.in +2
.nf
\fBecho "${bold}Please type in your name: ${offbold}\ec"\fR 
example% \fBbold='tput smso'\fR
example% \fBoffbold='tput rmso'\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRSetting the exit status
.sp
.LP
This example sets the exit status to indicate if the current terminal is a
hardcopy terminal.

.sp
.in +2
.nf
example% \fBtput hc\fR
.fi
.in -2
.sp

.LP
\fBExample 8 \fRPrinting the long name from terminfo
.sp
.LP
This command prints the long name from the \fBterminfo\fR database for the type
of terminal specified in the environment variable \fBTERM\fR.

.sp
.in +2
.nf
example% \fBtput longname\fR
.fi
.in -2
.sp

.LP
\fBExample 9 \fRProcessing several capabilities with one invocation
.sp
.LP
This example shows \fBtput\fR processing several capabilities in one
invocation. This example clears the screen, moves the cursor to position
\fB10\fR, \fB10\fR and turns on \fBbold\fR (extra bright) mode. The list is
terminated by an exclamation mark (\fB!\fR) on a line by itself.

.sp
.in +2
.nf
example% \fBtput -S <<! 
> clear 
> cup 10 10
> bold 
> !\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBtput\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.sp
.ne 2
.mk
.na
\fB\fBTERM\fR \fR
.ad
.RS 9n
.rt  
Determine the terminal type. If this variable is unset or null, and if the
\fB-T\fR option is not specified, an unspecified default terminal type will be
used.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR \fR
.ad
.RS 10n
.rt  
.RS +4
.TP
.ie t \(bu
.el o
If \fIcapname\fR is of type boolean and \fB-S\fR is not specified, indicates
\fBTRUE\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIcapname\fR is of type string and \fB-S\fR is not specified, indicates
\fIcapname\fR is defined for this terminal type.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIcapname\fR is of type boolean or string and \fB-S\fR is specified,
indicates that all lines were successful.
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIcapname\fR is of type integer.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The requested string was written successfully.
.RE
.RE

.sp
.ne 2
.mk
.na
\fB\fB1\fR \fR
.ad
.RS 10n
.rt  
.RS +4
.TP
.ie t \(bu
.el o
If \fIcapname\fR is of type boolean and \fB-S\fR is not specified, indicates
\fBFALSE\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIcapname\fR is of type string and \fB-S\fR is not specified, indicates
that \fIcapname\fR is not defined for this terminal type.
.RE
.RE

.sp
.ne 2
.mk
.na
\fB\fB2\fR \fR
.ad
.RS 10n
.rt  
Usage error.
.RE

.sp
.ne 2
.mk
.na
\fB\fB3\fR \fR
.ad
.RS 10n
.rt  
No information is available about the specified terminal type.
.RE

.sp
.ne 2
.mk
.na
\fB\fB4\fR \fR
.ad
.RS 10n
.rt  
The specified operand is invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fB>4\fR \fR
.ad
.RS 10n
.rt  
An error occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\(mi1\fR \fR
.ad
.RS 10n
.rt  
\fIcapname\fR is a numeric variable that is not specified in the \fBterminfo\fR
database. For instance, \fBtput\fR \fB-T450\fR lines and \fBtput\fR
\fB-T2621\fR xmc.
.RE

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/usr/include/curses.h\fR \fR
.ad
.sp .6
.RS 4n
\fBcurses\fR(3CURSES) header
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/include/term.h\fR \fR
.ad
.sp .6
.RS 4n
\fBterminfo\fR header
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/lib/tabset/*\fR \fR
.ad
.sp .6
.RS 4n
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(4)
.RE

.sp
.ne 2
.mk
.na
\fB\fB/usr/share/lib/terminfo/?/*\fR \fR
.ad
.sp .6
.RS 4n
compiled terminal description database
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityStandard
.TE

.SH SEE ALSO
.sp
.LP
\fBclear\fR(1), \fBsh\fR(1), \fBstty\fR(1), \fBtabs\fR(1),
\fBcurses\fR(3CURSES), \fBprofile\fR(4), \fBterminfo\fR(4),
\fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5), \fBterm\fR(5)