diff options
Diffstat (limited to 'man1p/tput.1p')
| -rw-r--r-- | man1p/tput.1p | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/man1p/tput.1p b/man1p/tput.1p new file mode 100644 index 000000000..3a94b1e9f --- /dev/null +++ b/man1p/tput.1p @@ -0,0 +1,228 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TPUT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tput +.SH NAME +tput \- change terminal characteristics +.SH SYNOPSIS +.LP +\fBtput\fP \fB[\fP\fB-T\fP \fItype\fP\fB]\fP \fIoperand\fP\fB... \fP +.SH DESCRIPTION +.LP +The \fItput\fP 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 +.LP +The \fItput\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-T\ \fP \fItype\fP +Indicate the type of terminal. If this option is not supplied and +the \fITERM\fP variable is unset or null, an unspecified +default terminal type shall be used. The setting of \fItype\fP shall +take precedence over the value in \fITERM .\fP +.sp +.SH OPERANDS +.LP +The following strings shall be supported as operands by the implementation +in the POSIX locale: +.TP 7 +\fBclear\fP +Display the clear-screen sequence. +.TP 7 +\fBinit\fP +Display the sequence that initializes the user's terminal in an implementation-defined +manner. +.TP 7 +\fBreset\fP +Display the sequence that resets the user's terminal in an implementation-defined +manner. +.sp +.LP +If a terminal does not support any of the operations described by +these operands, this shall not be considered an error +condition. +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItput\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +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). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fITERM\fP +Determine the terminal type. If this variable is unset or null, and +if the \fB-T\fP option is not specified, an unspecified +default terminal type shall be used. +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +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 +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +The requested string was written successfully. +.TP 7 +\ 1 +Unspecified. +.TP 7 +\ 2 +Usage error. +.TP 7 +\ 3 +No information is available about the specified terminal type. +.TP 7 +\ 4 +The specified operand is invalid. +.TP 7 +>4 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +If one of the operands is not available for the terminal, \fItput\fP +continues processing the remaining operands. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +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. +.LP +Some terminals use control characters to perform the stated functions, +and on such terminals it might make sense to use +\fItput\fP 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 +.nf + +\fBClearVar=`tput clear` +tput reset | mailx -s "Wake Up" ddg +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +Initialize the terminal according to the type of terminal in the environmental +variable \fITERM .\fP This command can be +included in a \fB.profile\fP file. +.sp +.RS +.nf + +\fBtput init +\fP +.fi +.RE +.LP +.IP " 2." 4 +Reset a 450 terminal. +.sp +.RS +.nf + +\fBtput -T 450 reset +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The list of operands was reduced to a minimum for the following reasons: +.IP " *" 3 +The only features chosen were those that were likely to be used by +human users interacting with a terminal. +.LP +.IP " *" 3 +Specifying the full \fIterminfo\fP set was not considered desirable, +but the standard developers did not want to select among +operands. +.LP +.IP " *" 3 +This volume of IEEE\ Std\ 1003.1-2001 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. +.LP +.LP +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. +.LP +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 +.LP +None. +.SH SEE ALSO +.LP +\fIstty\fP , \fItabs\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |