2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2012,2016 Free Software Foundation, Inc. *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
28 .\"***************************************************************************
30 .\" $Id: tput.1,v 1.36 2016/04/02 23:41:08 tom Exp $
38 \fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
40 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparameters\fR]
42 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
44 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
46 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
48 \fB@TPUT@ \-S\fR \fB<<\fR
53 The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
54 values of terminal-dependent capabilities and information available to
55 the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
56 return the long name of the requested terminal type.
57 The result depends upon the capability's type:
61 \fB@TPUT@\fR writes the string to the standard output.
62 No trailing newline is supplied.
65 \fB@TPUT@\fR writes the decimal value to the standard output,
66 with a trailing newline.
69 \fB@TPUT@\fR simply sets the exit code
70 (\fB0\fR for TRUE if the terminal has the capability,
71 \fB1\fR for FALSE if it does not),
72 and writes nothing to the standard output.
75 Before using a value returned on the standard output,
76 the application should test the exit code
77 (e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
78 (See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
79 For a complete list of capabilities
80 and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
84 indicates the \fItype\fR of terminal.
85 Normally this option is
86 unnecessary, because the default is taken from the environment
88 If \fB\-T\fR is specified, then the shell
89 variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
92 allows more than one capability per invocation of \fB@TPUT@\fR. The
93 capabilities must be passed to \fB@TPUT@\fR from the standard input
94 instead of from the command line (see example).
95 Only one \fIcapname\fR is allowed per line.
96 The \fB\-S\fR option changes the
97 meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
100 Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
101 to decide whether to use \fBtparm\fR(3X),
102 and how to interpret the parameters.
105 reports the version of ncurses which was used in this program, and exits.
109 indicates the capability from the \fBterminfo\fR database. When
110 \fBtermcap\fR support is compiled in, the \fBtermcap\fR name for
111 the capability is also accepted.
113 If the capability is a string that takes parameters, the arguments
114 following the capability will be used as parameters for the string.
116 Most parameters are numbers.
117 Only a few terminfo capabilities require string parameters;
118 \fB@TPUT@\fR uses a table to decide which to pass as strings.
119 Normally \fB@TPUT@\fR uses \fBtparm\fR(3X) to perform the substitution.
120 If no parameters are given for the capability,
121 \fB@TPUT@\fR writes the string without performing the substitution.
124 If the \fBterminfo\fR database is present and an entry for the user's
125 terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
130 if present, the terminal's initialization strings will be
131 output as detailed in the \fBterminfo\fR(5) section on
132 .IR "Tabs and Initialization" ,
135 any delays (e.g., newline) specified in the entry will
136 be set in the tty driver,
139 tabs expansion will be turned on or off according to
140 the specification in the entry, and
143 if tabs are not expanded,
144 standard tabs will be set (every 8 spaces).
148 contain the information needed for any of these activities,
149 that activity will silently be skipped.
152 Instead of putting out initialization strings, the terminal's
153 reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
154 If the reset strings are not present, but initialization
155 strings are, the initialization strings will be output.
156 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
159 If the \fBterminfo\fR database is present and an entry for the
160 user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
161 of the terminal will be put out. The long name is the last
162 name in the first line of the terminal's description in the
163 \fBterminfo\fR database [see \fBterm\fR(5)].
165 \fB@TPUT@\fR handles the \fBinit\fP and \fBreset\fP commands specially:
166 it allows for the possibility that it is invoked by a link with those names.
168 If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
169 same effect as \fB@TPUT@ reset\fR.
170 The \fB@TSET@\fR(\*n) utility also treats a link named \fBreset\fP specially:
172 That utility resets the terminal modes and special characters (not done here).
174 On the other hand, @TSET@'s repertoire of terminal capabilities for
175 resetting the terminal is more limited, i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
176 in contrast to the tab-stops and margins which are set by this utility.
178 The \fBreset\fP program is usually an alias for @TSET@,
179 due to the resetting of terminal modes and special characters.
181 If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
182 same effect as \fB@TPUT@ init\fR.
183 Again, you are less likely to use that link because another program
184 named \fBinit\fP has a more well-established use.
188 Initialize the terminal according to the type of
189 terminal in the environmental variable \fBTERM\fR. This
190 command should be included in everyone's .profile after
191 the environmental variable \fBTERM\fR has been exported, as
192 illustrated on the \fBprofile\fR(5) manual page.
194 \fB@TPUT@ \-T5620 reset\fR
195 Reset an AT&T 5620 terminal, overriding the type of
196 terminal in the environmental variable \fBTERM\fR.
199 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
200 (the upper left corner of the screen, usually known as the "home"
204 Echo the clear-screen sequence for the current terminal.
207 Print the number of columns for the current terminal.
209 \fB@TPUT@ \-T450 cols\fR
210 Print the number of columns for the 450 terminal.
212 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
213 Set the shell variables \fBbold\fR, to begin stand-out mode
214 sequence, and \fBoffbold\fR, to end standout mode sequence,
215 for the current terminal. This might be followed by a
216 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
219 Set exit code to indicate if the current terminal is a hard copy terminal.
221 \fB@TPUT@ cup 23 4\fR
222 Send the sequence to move the cursor to row 23, column 4.
225 Send the terminfo string for cursor-movement, with no parameters substituted.
227 \fB@TPUT@ longname\fR
228 Print the long name from the \fBterminfo\fR database for the
229 type of terminal specified in the environmental
245 This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
246 It clears the screen,
247 moves the cursor to position 10, 10
248 and turns on bold (extra bright) mode.
249 The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
253 compiled terminal description database
255 \fB@DATADIR@/tabset/*\fR
256 tab settings for some terminals, in a format
257 appropriate to be output to the terminal (escape
258 sequences that set margins and tabs); for more
259 information, see the "Tabs and Initialization"
260 section of \fBterminfo\fR(5)
262 If the \fB\-S\fR option is used,
263 \fB@TPUT@\fR checks for errors from each line,
264 and if any errors are found, will set the exit code to 4 plus the
265 number of lines with errors.
266 If no errors are found, the exit code is \fB0\fR.
267 No indication of which line failed can be given so
268 exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
269 \fB4\fR retain their usual interpretation.
270 If the \fB\-S\fR option is not used,
271 the exit code depends on the type of \fIcapname\fR:
275 a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
278 a value of \fB0\fR is set if the
279 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
280 \fIcapname\fR is returned on standard output);
281 a value of \fB1\fR is set if \fIcapname\fR
282 is not defined for this terminal \fItype\fR
283 (nothing is written to standard output).
286 a value of \fB0\fR is always set,
287 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
288 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
289 the user must test the value written to standard output.
291 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
294 \fBreset\fR or \fBinit\fR may fail to find their respective files.
295 In that case, the exit code is set to 4 + \fBerrno\fR.
298 Any other exit code indicates an error; see the DIAGNOSTICS section.
300 \fB@TPUT@\fR prints the following error messages and sets the corresponding exit
306 exit code error message
309 (\fIcapname\fR is a numeric variable that is not specified in the
310 \fBterminfo\fR(5) database for this terminal type, e.g.
311 \fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
313 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
315 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
316 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
317 \fB>4\fR error occurred in \-S
322 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
323 features used in the \fBcup\fR example, are not supported in BSD curses or in
324 AT&T/USL curses before SVr4.
326 IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008)
327 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
328 There are a few interesting observations to make regarding that:
330 In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
331 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
334 Other implementations of \fB@TPUT@\fP on
335 SVr4-based systems such as Solaris, IRIX64 and HPUX
336 as well as others such as AIX and Tru64
337 provide support for \fIcapname\fR operands.
339 A few platforms such as FreeBSD recognize termcap names rather
340 than terminfo capability names in their respective \fB@TPUT@\fP commands.
341 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
342 Before that, it (like FreeBSD) recognized termcap names.
344 Because (apparently) \fIall\fP of the certified Unix systems
345 support the full set of capability names, the reasoning for documenting
346 only a few may not be apparent.
348 X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
349 and the other features used in this implementation.
351 That is, there are two standards for \fBtput\fP: POSIX (a subset) and X/Open Curses (the full implementation).
352 POSIX documents a subset to avoid the complication of including X/Open Curses
353 and the terminal capabilities database.
355 While it is certainly possible to write a \fBtput\fP program without using curses,
356 none of the systems which have a curses implementation provide
357 a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
359 Most implementations which provide support for \fIcapname\fR operands
360 use the \fItparm\fP function to expand parameters in it.
361 That function expects a mixture of numeric and string parameters,
362 requiring \fB@TPUT@\fP to know which type to use.
363 This implementation uses a table to determine that for
364 the standard \fIcapname\fR operands, and an internal library
365 function to analyze nonstandard \fIcapname\fR operands.
366 Other implementations may simply guess that an operand containing only digits
367 is intended to be a number.
374 \fBcurs_termcap\fR(3X).
376 This describes \fBncurses\fR
377 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
projects / ncurses.git / blob