tput.1p (7098B)
- '\" et
- .TH TPUT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- tput
- \(em change terminal characteristics
- .SH SYNOPSIS
- .LP
- .nf
- tput \fB[\fR-T \fItype\fB] \fIoperand\fR...
- .fi
- .SH DESCRIPTION
- The
- .IR tput
- utility shall display terminal-dependent information. The manner in
- which this information is retrieved is unspecified. The information
- displayed shall clear the terminal screen, initialize the user's
- terminal, or reset the user's terminal, depending on the operand
- given. The exact consequences of displaying this information are
- unspecified.
- .SH OPTIONS
- The
- .IR tput
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following option shall be supported:
- .IP "\fB\-T\ \fItype\fR" 10
- Indicate the type of terminal. If this option is not supplied and the
- .IR TERM
- variable is unset or null, an unspecified default terminal type shall
- be used. The setting of
- .IR type
- shall take precedence over the value in
- .IR TERM .
- .SH OPERANDS
- The following strings shall be supported as operands by the
- implementation in the POSIX locale:
- .IP "\fBclear\fR" 10
- Display the clear-screen sequence.
- .IP "\fBinit\fR" 10
- Display the sequence that initializes the user's terminal in an
- implementation-defined manner.
- .IP "\fBreset\fR" 10
- Display the sequence that resets the user's terminal in an
- implementation-defined manner.
- .P
- If a terminal does not support any of the operations described by these
- operands, this shall not be considered an error condition.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR tput :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fITERM\fP" 10
- Determine the terminal type. If this variable is unset or null, and if
- the
- .BR \-T
- option is not specified, an unspecified default terminal type shall be
- used.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- If standard output is a terminal device, it may be used for writing the
- appropriate sequence to clear the screen or reset or initialize the
- terminal. If standard output is not a terminal device, undefined
- results occur.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- The requested string was written successfully.
- .IP "\01" 6
- Unspecified.
- .IP "\02" 6
- Usage error.
- .IP "\03" 6
- No information is available about the specified terminal type.
- .IP "\04" 6
- The specified operand is invalid.
- .IP >4 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- If one of the operands is not available for the terminal,
- .IR tput
- continues processing the remaining operands.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The difference between resetting and initializing a terminal is left
- unspecified, as they vary greatly based on hardware types. In general,
- resetting is a more severe action.
- .P
- Some terminals use control characters to perform the stated functions,
- and on such terminals it might make sense to use
- .IR tput
- to store the initialization strings in a file or environment variable
- for later use. However, because other terminals might rely on system
- calls to do this work, the standard output cannot be used in a portable
- manner, such as the following non-portable constructs:
- .sp
- .RS 4
- .nf
- ClearVar=`tput clear`
- tput reset | mailx -s "Wake Up" ddg
- .fi
- .P
- .RE
- .SH EXAMPLES
- .IP " 1." 4
- Initialize the terminal according to the type of terminal in the
- environmental variable
- .IR TERM .
- This command can be included in a
- .BR .profile
- file.
- .RS 4
- .sp
- .RS 4
- .nf
- tput init
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- Reset a 450 terminal.
- .RS 4
- .sp
- .RS 4
- .nf
- tput -T 450 reset
- .fi
- .P
- .RE
- .RE
- .SH RATIONALE
- The list of operands was reduced to a minimum for the following
- reasons:
- .IP " *" 4
- The only features chosen were those that were likely to be used by
- human users interacting with a terminal.
- .IP " *" 4
- Specifying the full
- .IR terminfo
- set was not considered desirable, but the standard developers did not
- want to select among operands.
- .IP " *" 4
- This volume of POSIX.1\(hy2017 does not attempt to provide applications with sophisticated
- terminal handling capabilities, as that falls outside of its assigned
- scope and intersects with the responsibilities of other standards
- bodies.
- .P
- The difference between resetting and initializing a terminal is left
- unspecified as this varies greatly based on hardware types. In
- general, resetting is a more severe action.
- .P
- The exit status of 1 is historically reserved for finding out if a
- Boolean operand is not set. Although the operands were reduced to a
- minimum, the exit status of 1 should still be reserved for the Boolean
- operands, for those sites that wish to support them.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIstty\fR\^",
- .IR "\fItabs\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .