2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2016,2017 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.52 2017/01/21 17:38:30 tom Exp $
42 \fB@TPUT@\fR, \fBreset\fR \- initialize a terminal or query terminfo database
44 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fIcapname\fR [\fIparameters\fR]
46 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBclear\fR
48 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBinit\fR
50 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBreset\fR
52 \fB@TPUT@\fR [\fB\-T\fR\fItype\fR] \fBlongname\fR
54 \fB@TPUT@ \-S\fR \fB<<\fR
59 The \fB@TPUT@\fR utility uses the \fBterminfo\fR database to make the
60 values of terminal-dependent capabilities and information available to
61 the shell (see \fBsh\fR(1)), to initialize or reset the terminal, or
62 return the long name of the requested terminal type.
63 The result depends upon the capability's type:
67 \fB@TPUT@\fR writes the string to the standard output.
68 No trailing newline is supplied.
71 \fB@TPUT@\fR writes the decimal value to the standard output,
72 with a trailing newline.
75 \fB@TPUT@\fR simply sets the exit code
76 (\fB0\fR for TRUE if the terminal has the capability,
77 \fB1\fR for FALSE if it does not),
78 and writes nothing to the standard output.
81 Before using a value returned on the standard output,
82 the application should test the exit code
83 (e.g., \fB$?\fR, see \fBsh\fR(1)) to be sure it is \fB0\fR.
84 (See the \fBEXIT CODES\fR and \fBDIAGNOSTICS\fR sections.)
85 For a complete list of capabilities
86 and the \fIcapname\fR associated with each, see \fBterminfo\fR(5).
90 indicates the \fItype\fR of terminal.
91 Normally this option is
92 unnecessary, because the default is taken from the environment
94 If \fB\-T\fR is specified, then the shell
95 variables \fBLINES\fR and \fBCOLUMNS\fR will also be ignored.
98 allows more than one capability per invocation of \fB@TPUT@\fR. The
99 capabilities must be passed to \fB@TPUT@\fR from the standard input
100 instead of from the command line (see example).
101 Only one \fIcapname\fR is allowed per line.
102 The \fB\-S\fR option changes the
103 meaning of the \fB0\fR and \fB1\fR boolean and string exit codes (see the
106 Again, \fB@TPUT@\fR uses a table and the presence of parameters in its input
107 to decide whether to use \fBtparm\fR(3X),
108 and how to interpret the parameters.
111 reports the version of ncurses which was used in this program, and exits.
115 indicates the capability from the terminal database.
117 If the capability is a string that takes parameters, the arguments
118 following the capability will be used as parameters for the string.
120 Most parameters are numbers.
121 Only a few terminal capabilities require string parameters;
122 \fB@TPUT@\fR uses a table to decide which to pass as strings.
123 Normally \fB@TPUT@\fR uses \fBtparm\fR(3X) to perform the substitution.
124 If no parameters are given for the capability,
125 \fB@TPUT@\fR writes the string without performing the substitution.
128 If the terminal database is present and an entry for the user's
129 terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
134 first, \fB@TPUT@\fR retrieves the current terminal mode settings
136 It does this by successively testing
145 ultimately \*(lq/dev/tty\*(rq
148 to obtain terminal settings.
149 Having retrieved these settings, \fB@TPUT@\fP remembers which
150 file descriptor to use when updating settings.
153 if the window size cannot be obtained from the operating system,
154 but the terminal description (or environment, e.g., \fBLINES\fP
155 and \fBCOLUMNS\fP variables specify this),
156 update the operating system's notion of the window size.
159 the terminal modes will be updated:
162 any delays (e.g., newline) specified in the entry will
163 be set in the tty driver,
165 tabs expansion will be turned on or off according to
166 the specification in the entry, and
168 if tabs are not expanded,
169 standard tabs will be set (every 8 spaces).
173 if present, the terminal's initialization strings will be
174 output as detailed in the \fBterminfo\fR(5) section on
175 .IR "Tabs and Initialization" ,
182 contain the information needed for any of these activities,
183 that activity will silently be skipped.
186 This is similar to \fBinit\fP, with two differences:
190 before any other initialization,
191 the terminal modes will be reset to a \*(``sane\*('' state:
194 set cooked and echo modes,
196 turn off cbreak and raw modes,
198 turn on newline translation and
200 reset any unset special characters to their default values
204 Instead of putting out \fIinitialization\fP strings, the terminal's
205 \fIreset\fP strings will be output if present
206 (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
207 If the \fIreset\fP strings are not present, but \fIinitialization\fP
208 strings are, the \fIinitialization\fP strings will be output.
211 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
214 If the terminal database is present and an entry for the
215 user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
216 of the terminal will be put out. The long name is the last
217 name in the first line of the terminal's description in the
218 \fBterminfo\fR database [see \fBterm\fR(5)].
220 \fB@TPUT@\fR handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
222 it allows for the possibility that it is invoked by a link with those names.
224 If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
225 same effect as \fB@TPUT@ reset\fR.
226 The \fB@TSET@\fR(\*n) utility also treats a link named \fBreset\fP specially.
228 Before ncurses 6.1, the two utilities were different from each other:
230 \fB@TSET@\fP utility reset the terminal modes and special characters
231 (not done with \fB@TPUT@\fP).
233 On the other hand, \fB@TSET@\fP's repertoire of terminal capabilities for
234 resetting the terminal was more limited, i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
235 in contrast to the tab-stops and margins which are set by this utility.
237 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
238 because of this difference with resetting terminal modes and special characters.
240 With the changes made for ncurses 6.1, the \fIreset\fP feature of the
241 two programs is (mostly) the same. A few differences remain:
243 The \fB@TSET@\fP program waits one second when resetting,
244 in case it happens to be a hardware terminal.
246 The two programs write the terminal initialization strings
247 to different streams (i.e.,. the standard error for \fB@TSET@\fP and the
248 standard output for \fB@TPUT@\fP).
250 \fBNote:\fP although these programs write to different streams,
251 redirecting their output to a file will capture only part of their actions.
252 The changes to the terminal modes are not affected by redirecting the output.
254 If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
255 same effect as \fB@TPUT@ init\fR.
256 Again, you are less likely to use that link because another program
257 named \fBinit\fP has a more well-established use.
261 Initialize the terminal according to the type of
262 terminal in the environmental variable \fBTERM\fR. This
263 command should be included in everyone's .profile after
264 the environmental variable \fBTERM\fR has been exported, as
265 illustrated on the \fBprofile\fR(5) manual page.
267 \fB@TPUT@ \-T5620 reset\fR
268 Reset an AT&T 5620 terminal, overriding the type of
269 terminal in the environmental variable \fBTERM\fR.
272 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
273 (the upper left corner of the screen, usually known as the \*(lqhome\*(rq
277 Echo the clear-screen sequence for the current terminal.
280 Print the number of columns for the current terminal.
282 \fB@TPUT@ \-T450 cols\fR
283 Print the number of columns for the 450 terminal.
285 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
286 Set the shell variables \fBbold\fR, to begin stand-out mode
287 sequence, and \fBoffbold\fR, to end standout mode sequence,
288 for the current terminal. This might be followed by a
289 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
292 Set exit code to indicate if the current terminal is a hard copy terminal.
294 \fB@TPUT@ cup 23 4\fR
295 Send the sequence to move the cursor to row 23, column 4.
298 Send the terminfo string for cursor-movement, with no parameters substituted.
300 \fB@TPUT@ longname\fR
301 Print the long name from the \fBterminfo\fR database for the
302 type of terminal specified in the environmental
318 This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
319 It clears the screen,
320 moves the cursor to position 10, 10
321 and turns on bold (extra bright) mode.
322 The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
326 compiled terminal description database
328 \fB@DATADIR@/tabset/*\fR
329 tab settings for some terminals, in a format
330 appropriate to be output to the terminal (escape
331 sequences that set margins and tabs); for more
333 .IR "Tabs and Initialization" ,
334 section of \fBterminfo\fR(5)
336 If the \fB\-S\fR option is used,
337 \fB@TPUT@\fR checks for errors from each line,
338 and if any errors are found, will set the exit code to 4 plus the
339 number of lines with errors.
340 If no errors are found, the exit code is \fB0\fR.
341 No indication of which line failed can be given so
342 exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
343 \fB4\fR retain their usual interpretation.
344 If the \fB\-S\fR option is not used,
345 the exit code depends on the type of \fIcapname\fR:
349 a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
352 a value of \fB0\fR is set if the
353 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
354 \fIcapname\fR is returned on standard output);
355 a value of \fB1\fR is set if \fIcapname\fR
356 is not defined for this terminal \fItype\fR
357 (nothing is written to standard output).
360 a value of \fB0\fR is always set,
361 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
362 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
363 the user must test the value written to standard output.
365 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
368 \fBreset\fR or \fBinit\fR may fail to find their respective files.
369 In that case, the exit code is set to 4 + \fBerrno\fR.
372 Any other exit code indicates an error; see the DIAGNOSTICS section.
374 \fB@TPUT@\fR prints the following error messages and sets the corresponding exit
380 exit code error message
383 (\fIcapname\fR is a numeric variable that is not specified in the
384 \fBterminfo\fR(5) database for this terminal type, e.g.
385 \fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
387 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
389 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
390 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
391 \fB>4\fR error occurred in \-S
395 The \fBtput\fP command was begun by Bill Joy in 1980.
396 The initial version only cleared the screen.
398 AT&T System V provided a different \fBtput\fP command,
399 whose \fBinit\fP and \fBreset\fP subcommands
400 (more than half the program) were incorporated from
401 the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
403 Keith Bostic replaced the BSD \fBtput\fP command in 1989 with a new implementation
404 based on the AT&T System V program \fBtput\fP.
405 Like the AT&T program, Bostic's version
406 accepted some parameters named for \fIterminfo capabilities\fP
407 (\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
408 However (because he had only termcap available),
409 it accepted \fItermcap names\fP for other capabilities.
410 Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
411 as the earlier BSD \fBtset\fP had done.
413 At the same time, Bostic added a shell script named \*(lqclear\*(rq,
414 which used \fBtput\fP to clear the screen.
416 Both of these appeared in 4.4BSD,
417 becoming the \*(lqmodern\*(rq BSD implementation of \fBtput\fP.
420 This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
423 \fB@TPUT@\fP \fIcapname\fP writes to the standard output.
424 That need not be a regular terminal.
425 However, the subcommands which manipulate terminal modes
426 may not use the standard output.
428 The AT&T implementation's \fBinit\fP and \fBreset\fP commands
429 use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
430 It successively tries standard output, standard error, standard input
431 before falling back to \*(lq/dev/tty\*(rq and finally just assumes
433 When updating terminal modes, it ignores errors.
435 Until changes made after ncurses 6.0, \fB@TPUT@\fP did not modify terminal modes.
436 \fB@TPUT@\fP now uses a similar scheme,
437 using functions shared with \fB@TSET@\fP
438 (and ultimately based on the 4.4BSD \fBtset\fP).
439 If it is not able to open a terminal, e.g., when running in \fBcron\fP,
440 \fB@TPUT@\fP will return an error.
442 AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if
443 all of the characters are numeric, or not.
445 Most implementations which provide support for \fIcapname\fR operands
446 use the \fItparm\fP function to expand parameters in it.
447 That function expects a mixture of numeric and string parameters,
448 requiring \fB@TPUT@\fP to know which type to use.
450 This implementation uses a table to determine the parameter types for
451 the standard \fIcapname\fR operands, and an internal library
452 function to analyze nonstandard \fIcapname\fR operands.
454 This implementation (unlike others) can accept both \fItermcap\fP
455 and \fIterminfo\fP names for the \fIcapname\fP feature,
457 \fItermcap\fR support is compiled in.
458 However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
459 ambiguities in this case (and the \fIterminfo\fP name is assumed):
461 The \fItermcap\fP name \fBdl\fP corresponds to
462 the \fIterminfo\fP name \fBdl1\fP (delete one line).
464 The \fIterminfo\fP name \fBdl\fP corresponds to
465 the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
467 The \fItermcap\fP name \fBed\fP corresponds to
468 the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
470 The \fIterminfo\fP name \fBed\fP corresponds to
471 the \fItermcap\fP name \fBcd\fP (clear to end of screen).
473 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
474 features used in the \fBcup\fR example,
475 were not supported in BSD curses before 4.3reno (1989) or in
476 AT&T/USL curses before SVr4 (1988).
478 IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008)
479 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
480 There are a few interesting observations to make regarding that:
482 In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
483 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
486 Other implementations of \fBtput\fP on
487 SVr4-based systems such as Solaris, IRIX64 and HPUX
488 as well as others such as AIX and Tru64
489 provide support for \fIcapname\fR operands.
491 A few platforms such as FreeBSD recognize termcap names rather
492 than terminfo capability names in their respective \fBtput\fP commands.
493 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
494 Before that, it (like FreeBSD) recognized termcap names.
496 Because (apparently) \fIall\fP of the certified Unix systems
497 support the full set of capability names, the reasoning for documenting
498 only a few may not be apparent.
500 X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
501 and the other features used in this implementation.
503 That is, there are two standards for \fBtput\fP: POSIX (a subset) and X/Open Curses (the full implementation).
504 POSIX documents a subset to avoid the complication of including X/Open Curses
505 and the terminal capabilities database.
507 While it is certainly possible to write a \fBtput\fP program without using curses,
508 none of the systems which have a curses implementation provide
509 a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
516 \fBcurs_termcap\fR(3X).
518 This describes \fBncurses\fR
519 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
projects / ncurses.git / blob