man1p/tput.1p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "TPUT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" tput
   4 .SH NAME
   5 tput \- change terminal characteristics
   6 .SH SYNOPSIS
   7 .LP
   8 \fBtput\fP \fB[\fP\fB-T\fP \fItype\fP\fB]\fP \fIoperand\fP\fB... \fP
   9 .SH DESCRIPTION
  10 .LP
  11 The \fItput\fP utility shall display terminal-dependent information.
  12 The manner in which this information is retrieved is
  13 unspecified. The information displayed shall clear the terminal screen,
  14 initialize the user's terminal, or reset the user's
  15 terminal, depending on the operand given. The exact consequences of
  16 displaying this information are unspecified.
  17 .SH OPTIONS
  18 .LP
  19 The \fItput\fP utility shall conform to the Base Definitions volume
  20 of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
  21 .LP
  22 The following option shall be supported:
  23 .TP 7
  24 \fB-T\ \fP \fItype\fP
  25 Indicate the type of terminal. If this option is not supplied and
  26 the \fITERM\fP variable is unset or null, an unspecified
  27 default terminal type shall be used. The setting of \fItype\fP shall
  28 take precedence over the value in \fITERM .\fP
  29 .sp
  30 .SH OPERANDS
  31 .LP
  32 The following strings shall be supported as operands by the implementation
  33 in the POSIX locale:
  34 .TP 7
  35 \fBclear\fP
  36 Display the clear-screen sequence.
  37 .TP 7
  38 \fBinit\fP
  39 Display the sequence that initializes the user's terminal in an implementation-defined
  40 manner.
  41 .TP 7
  42 \fBreset\fP
  43 Display the sequence that resets the user's terminal in an implementation-defined
  44 manner.
  45 .sp
  46 .LP
  47 If a terminal does not support any of the operations described by
  48 these operands, this shall not be considered an error
  49 condition.
  50 .SH STDIN
  51 .LP
  52 Not used.
  53 .SH INPUT FILES
  54 .LP
  55 None.
  56 .SH ENVIRONMENT VARIABLES
  57 .LP
  58 The following environment variables shall affect the execution of
  59 \fItput\fP:
  60 .TP 7
  61 \fILANG\fP
  62 Provide a default value for the internationalization variables that
  63 are unset or null. (See the Base Definitions volume of
  64 IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
  65 for
  66 the precedence of internationalization variables used to determine
  67 the values of locale categories.)
  68 .TP 7
  69 \fILC_ALL\fP
  70 If set to a non-empty string value, override the values of all the
  71 other internationalization variables.
  72 .TP 7
  73 \fILC_CTYPE\fP
  74 Determine the locale for the interpretation of sequences of bytes
  75 of text data as characters (for example, single-byte as
  76 opposed to multi-byte characters in arguments).
  77 .TP 7
  78 \fILC_MESSAGES\fP
  79 Determine the locale that should be used to affect the format and
  80 contents of diagnostic messages written to standard
  81 error.
  82 .TP 7
  83 \fINLSPATH\fP
  84 Determine the location of message catalogs for the processing of \fILC_MESSAGES
  85 \&.\fP
  86 .TP 7
  87 \fITERM\fP
  88 Determine the terminal type. If this variable is unset or null, and
  89 if the \fB-T\fP option is not specified, an unspecified
  90 default terminal type shall be used.
  91 .sp
  92 .SH ASYNCHRONOUS EVENTS
  93 .LP
  94 Default.
  95 .SH STDOUT
  96 .LP
  97 If standard output is a terminal device, it may be used for writing
  98 the appropriate sequence to clear the screen or reset or
  99 initialize the terminal. If standard output is not a terminal device,
 100 undefined results occur.
 101 .SH STDERR
 102 .LP
 103 The standard error shall be used only for diagnostic messages.
 104 .SH OUTPUT FILES
 105 .LP
 106 None.
 107 .SH EXTENDED DESCRIPTION
 108 .LP
 109 None.
 110 .SH EXIT STATUS
 111 .LP
 112 The following exit values shall be returned:
 113 .TP 7
 114 \ 0
 115 The requested string was written successfully.
 116 .TP 7
 117 \ 1
 118 Unspecified.
 119 .TP 7
 120 \ 2
 121 Usage error.
 122 .TP 7
 123 \ 3
 124 No information is available about the specified terminal type.
 125 .TP 7
 126 \ 4
 127 The specified operand is invalid.
 128 .TP 7
 129 >4
 130 An error occurred.
 131 .sp
 132 .SH CONSEQUENCES OF ERRORS
 133 .LP
 134 If one of the operands is not available for the terminal, \fItput\fP
 135 continues processing the remaining operands.
 136 .LP
 137 \fIThe following sections are informative.\fP
 138 .SH APPLICATION USAGE
 139 .LP
 140 The difference between resetting and initializing a terminal is left
 141 unspecified, as they vary greatly based on hardware types.
 142 In general, resetting is a more severe action.
 143 .LP
 144 Some terminals use control characters to perform the stated functions,
 145 and on such terminals it might make sense to use
 146 \fItput\fP to store the initialization strings in a file or environment
 147 variable for later use. However, because other terminals
 148 might rely on system calls to do this work, the standard output cannot
 149 be used in a portable manner, such as the following
 150 non-portable constructs:
 151 .sp
 152 .RS
 153 .nf
 154
 155 \fBClearVar=`tput clear`
 156 tput reset | mailx -s "Wake Up" ddg
 157 \fP
 158 .fi
 159 .RE
 160 .SH EXAMPLES
 161 .IP " 1." 4
 162 Initialize the terminal according to the type of terminal in the environmental
 163 variable \fITERM .\fP This command can be
 164 included in a \fB.profile\fP file.
 165 .sp
 166 .RS
 167 .nf
 168
 169 \fBtput init
 170 \fP
 171 .fi
 172 .RE
 173 .LP
 174 .IP " 2." 4
 175 Reset a 450 terminal.
 176 .sp
 177 .RS
 178 .nf
 179
 180 \fBtput -T 450 reset
 181 \fP
 182 .fi
 183 .RE
 184 .LP
 185 .SH RATIONALE
 186 .LP
 187 The list of operands was reduced to a minimum for the following reasons:
 188 .IP " *" 3
 189 The only features chosen were those that were likely to be used by
 190 human users interacting with a terminal.
 191 .LP
 192 .IP " *" 3
 193 Specifying the full \fIterminfo\fP set was not considered desirable,
 194 but the standard developers did not want to select among
 195 operands.
 196 .LP
 197 .IP " *" 3
 198 This volume of IEEE\ Std\ 1003.1-2001 does not attempt to provide
 199 applications with sophisticated terminal handling
 200 capabilities, as that falls outside of its assigned scope and intersects
 201 with the responsibilities of other standards bodies.
 202 .LP
 203 .LP
 204 The difference between resetting and initializing a terminal is left
 205 unspecified as this varies greatly based on hardware types.
 206 In general, resetting is a more severe action.
 207 .LP
 208 The exit status of 1 is historically reserved for finding out if a
 209 Boolean operand is not set. Although the operands were
 210 reduced to a minimum, the exit status of 1 should still be reserved
 211 for the Boolean operands, for those sites that wish to support
 212 them.
 213 .SH FUTURE DIRECTIONS
 214 .LP
 215 None.
 216 .SH SEE ALSO
 217 .LP
 218 \fIstty\fP , \fItabs\fP
 219 .SH COPYRIGHT
 220 Portions of this text are reprinted and reproduced in electronic form
 221 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 222 -- Portable Operating System Interface (POSIX), The Open Group Base
 223 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 224 Electrical and Electronics Engineers, Inc and The Open Group. In the
 225 event of any discrepancy between this version and the original IEEE and
 226 The Open Group Standard, the original IEEE and The Open Group Standard
 227 is the referee document. The original Standard can be obtained online at
 228 http://www.opengroup.org/unix/online.html .