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.54 2017/01/29 00:51:08 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.
113 A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
114 special; they are defined by the \fB@TPUT@\fP program.
115 The others are the names of \fIcapabilities\fP from the terminal database
116 (see \fBterminfo\fR(5) for a list).
117 Although \fBinit\fP and \fBreset\fP resemble capability names,
118 \fB@TPUT@\fP uses several capabilities to perform these special functions.
121 indicates the capability from the terminal database.
123 If the capability is a string that takes parameters, the arguments
124 following the capability will be used as parameters for the string.
126 Most parameters are numbers.
127 Only a few terminal capabilities require string parameters;
128 \fB@TPUT@\fR uses a table to decide which to pass as strings.
129 Normally \fB@TPUT@\fR uses \fBtparm\fR(3X) to perform the substitution.
130 If no parameters are given for the capability,
131 \fB@TPUT@\fR writes the string without performing the substitution.
134 If the terminal database is present and an entry for the user's
135 terminal exists (see \fB\-T\fR\fItype\fR, above), the following will
140 first, \fB@TPUT@\fR retrieves the current terminal mode settings
142 It does this by successively testing
151 ultimately \*(lq/dev/tty\*(rq
154 to obtain terminal settings.
155 Having retrieved these settings, \fB@TPUT@\fP remembers which
156 file descriptor to use when updating settings.
159 if the window size cannot be obtained from the operating system,
160 but the terminal description (or environment, e.g., \fBLINES\fP
161 and \fBCOLUMNS\fP variables specify this),
162 update the operating system's notion of the window size.
165 the terminal modes will be updated:
168 any delays (e.g., newline) specified in the entry will
169 be set in the tty driver,
171 tabs expansion will be turned on or off according to
172 the specification in the entry, and
174 if tabs are not expanded,
175 standard tabs will be set (every 8 spaces).
179 if present, the terminal's initialization strings will be
180 output as detailed in the \fBterminfo\fR(5) section on
181 .IR "Tabs and Initialization" ,
188 contain the information needed for any of these activities,
189 that activity will silently be skipped.
192 This is similar to \fBinit\fP, with two differences:
196 before any other initialization,
197 the terminal modes will be reset to a \*(``sane\*('' state:
200 set cooked and echo modes,
202 turn off cbreak and raw modes,
204 turn on newline translation and
206 reset any unset special characters to their default values
210 Instead of putting out \fIinitialization\fP strings, the terminal's
211 \fIreset\fP strings will be output if present
212 (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
213 If the \fIreset\fP strings are not present, but \fIinitialization\fP
214 strings are, the \fIinitialization\fP strings will be output.
217 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
220 If the terminal database is present and an entry for the
221 user's terminal exists (see \fB\-T\fR\fItype\fR above), then the long name
222 of the terminal will be put out. The long name is the last
223 name in the first line of the terminal's description in the
224 \fBterminfo\fR database [see \fBterm\fR(5)].
226 \fB@TPUT@\fR handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
228 it allows for the possibility that it is invoked by a link with those names.
230 If \fB@TPUT@\fR is invoked by a link named \fBreset\fR, this has the
231 same effect as \fB@TPUT@ reset\fR.
232 The \fB@TSET@\fR(\*n) utility also treats a link named \fBreset\fP specially.
234 Before ncurses 6.1, the two utilities were different from each other:
236 \fB@TSET@\fP utility reset the terminal modes and special characters
237 (not done with \fB@TPUT@\fP).
239 On the other hand, \fB@TSET@\fP's repertoire of terminal capabilities for
240 resetting the terminal was more limited, i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
241 in contrast to the tab-stops and margins which are set by this utility.
243 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
244 because of this difference with resetting terminal modes and special characters.
246 With the changes made for ncurses 6.1, the \fIreset\fP feature of the
247 two programs is (mostly) the same. A few differences remain:
249 The \fB@TSET@\fP program waits one second when resetting,
250 in case it happens to be a hardware terminal.
252 The two programs write the terminal initialization strings
253 to different streams (i.e.,. the standard error for \fB@TSET@\fP and the
254 standard output for \fB@TPUT@\fP).
256 \fBNote:\fP although these programs write to different streams,
257 redirecting their output to a file will capture only part of their actions.
258 The changes to the terminal modes are not affected by redirecting the output.
260 If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
261 same effect as \fB@TPUT@ init\fR.
262 Again, you are less likely to use that link because another program
263 named \fBinit\fP has a more well-established use.
267 Initialize the terminal according to the type of
268 terminal in the environmental variable \fBTERM\fR. This
269 command should be included in everyone's .profile after
270 the environmental variable \fBTERM\fR has been exported, as
271 illustrated on the \fBprofile\fR(5) manual page.
273 \fB@TPUT@ \-T5620 reset\fR
274 Reset an AT&T 5620 terminal, overriding the type of
275 terminal in the environmental variable \fBTERM\fR.
278 Send the sequence to move the cursor to row \fB0\fR, column \fB0\fR
279 (the upper left corner of the screen, usually known as the \*(lqhome\*(rq
283 Echo the clear-screen sequence for the current terminal.
286 Print the number of columns for the current terminal.
288 \fB@TPUT@ \-T450 cols\fR
289 Print the number of columns for the 450 terminal.
291 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fR
292 Set the shell variables \fBbold\fR, to begin stand-out mode
293 sequence, and \fBoffbold\fR, to end standout mode sequence,
294 for the current terminal. This might be followed by a
295 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fR
298 Set exit code to indicate if the current terminal is a hard copy terminal.
300 \fB@TPUT@ cup 23 4\fR
301 Send the sequence to move the cursor to row 23, column 4.
304 Send the terminfo string for cursor-movement, with no parameters substituted.
306 \fB@TPUT@ longname\fR
307 Print the long name from the \fBterminfo\fR database for the
308 type of terminal specified in the environmental
324 This example shows \fB@TPUT@\fR processing several capabilities in one invocation.
325 It clears the screen,
326 moves the cursor to position 10, 10
327 and turns on bold (extra bright) mode.
328 The list is terminated by an exclamation mark (\fB!\fR) on a line by itself.
332 compiled terminal description database
334 \fB@DATADIR@/tabset/*\fR
335 tab settings for some terminals, in a format
336 appropriate to be output to the terminal (escape
337 sequences that set margins and tabs); for more
339 .IR "Tabs and Initialization" ,
340 section of \fBterminfo\fR(5)
342 If the \fB\-S\fR option is used,
343 \fB@TPUT@\fR checks for errors from each line,
344 and if any errors are found, will set the exit code to 4 plus the
345 number of lines with errors.
346 If no errors are found, the exit code is \fB0\fR.
347 No indication of which line failed can be given so
348 exit code \fB1\fR will never appear. Exit codes \fB2\fR, \fB3\fR, and
349 \fB4\fR retain their usual interpretation.
350 If the \fB\-S\fR option is not used,
351 the exit code depends on the type of \fIcapname\fR:
355 a value of \fB0\fR is set for TRUE and \fB1\fR for FALSE.
358 a value of \fB0\fR is set if the
359 \fIcapname\fR is defined for this terminal \fItype\fR (the value of
360 \fIcapname\fR is returned on standard output);
361 a value of \fB1\fR is set if \fIcapname\fR
362 is not defined for this terminal \fItype\fR
363 (nothing is written to standard output).
366 a value of \fB0\fR is always set,
367 whether or not \fIcapname\fR is defined for this terminal \fItype\fR.
368 To determine if \fIcapname\fR is defined for this terminal \fItype\fR,
369 the user must test the value written to standard output.
371 means that \fIcapname\fR is not defined for this terminal \fItype\fR.
374 \fBreset\fR or \fBinit\fR may fail to find their respective files.
375 In that case, the exit code is set to 4 + \fBerrno\fR.
378 Any other exit code indicates an error; see the DIAGNOSTICS section.
380 \fB@TPUT@\fR prints the following error messages and sets the corresponding exit
386 exit code error message
389 (\fIcapname\fR is a numeric variable that is not specified in the
390 \fBterminfo\fR(5) database for this terminal type, e.g.
391 \fB@TPUT@ \-T450 lines\fR and \fB@TPUT@ \-T2621 xmc\fR)
393 \fB1\fR no error message is printed, see the \fBEXIT CODES\fR section.
395 \fB3\fR unknown terminal \fItype\fR or no \fBterminfo\fR database
396 \fB4\fR unknown \fBterminfo\fR capability \fIcapname\fR
397 \fB>4\fR error occurred in \-S
401 The \fBtput\fP command was begun by Bill Joy in 1980.
402 The initial version only cleared the screen.
404 AT&T System V provided a different \fBtput\fP command,
405 whose \fBinit\fP and \fBreset\fP subcommands
406 (more than half the program) were incorporated from
407 the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
409 Keith Bostic replaced the BSD \fBtput\fP command in 1989 with a new implementation
410 based on the AT&T System V program \fBtput\fP.
411 Like the AT&T program, Bostic's version
412 accepted some parameters named for \fIterminfo capabilities\fP
413 (\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
414 However (because he had only termcap available),
415 it accepted \fItermcap names\fP for other capabilities.
416 Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
417 as the earlier BSD \fBtset\fP had done.
419 At the same time, Bostic added a shell script named \*(lqclear\*(rq,
420 which used \fBtput\fP to clear the screen.
422 Both of these appeared in 4.4BSD,
423 becoming the \*(lqmodern\*(rq BSD implementation of \fBtput\fP.
425 This implementation of \fBtput\fP began from a different source than
426 AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on
427 \fIcomp.sources.unix\fP in December 1992.
428 Ridge's program made more sophisticated use of the terminal capabilities
429 than the BSD program.
430 Eric Raymond used the \fBtput\fP program
431 (and other parts of \fImytinfo\fP) in ncurses in June 1995.
432 Using the portions dealing with terminal capabilities
433 almost without change,
434 Raymond made improvements to the way the command-line parameters
438 This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
441 \fB@TPUT@\fP \fIcapname\fP writes to the standard output.
442 That need not be a regular terminal.
443 However, the subcommands which manipulate terminal modes
444 may not use the standard output.
446 The AT&T implementation's \fBinit\fP and \fBreset\fP commands
447 use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
448 It successively tries standard output, standard error, standard input
449 before falling back to \*(lq/dev/tty\*(rq and finally just assumes
451 When updating terminal modes, it ignores errors.
453 Until changes made after ncurses 6.0, \fB@TPUT@\fP did not modify terminal modes.
454 \fB@TPUT@\fP now uses a similar scheme,
455 using functions shared with \fB@TSET@\fP
456 (and ultimately based on the 4.4BSD \fBtset\fP).
457 If it is not able to open a terminal, e.g., when running in \fBcron\fP,
458 \fB@TPUT@\fP will return an error.
460 AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if
461 all of the characters are numeric, or not.
463 Most implementations which provide support for \fIcapname\fR operands
464 use the \fItparm\fP function to expand parameters in it.
465 That function expects a mixture of numeric and string parameters,
466 requiring \fB@TPUT@\fP to know which type to use.
468 This implementation uses a table to determine the parameter types for
469 the standard \fIcapname\fR operands, and an internal library
470 function to analyze nonstandard \fIcapname\fR operands.
472 This implementation (unlike others) can accept both \fItermcap\fP
473 and \fIterminfo\fP names for the \fIcapname\fP feature,
475 \fItermcap\fR support is compiled in.
476 However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
477 ambiguities in this case (and the \fIterminfo\fP name is assumed):
479 The \fItermcap\fP name \fBdl\fP corresponds to
480 the \fIterminfo\fP name \fBdl1\fP (delete one line).
482 The \fIterminfo\fP name \fBdl\fP corresponds to
483 the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
485 The \fItermcap\fP name \fBed\fP corresponds to
486 the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
488 The \fIterminfo\fP name \fBed\fP corresponds to
489 the \fItermcap\fP name \fBcd\fP (clear to end of screen).
491 The \fBlongname\fR and \fB\-S\fR options, and the parameter-substitution
492 features used in the \fBcup\fR example,
493 were not supported in BSD curses before 4.3reno (1989) or in
494 AT&T/USL curses before SVr4 (1988).
496 IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008)
497 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
498 There are a few interesting observations to make regarding that:
500 In this implementation, \fBclear\fP is part of the \fIcapname\fR support.
501 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
504 Other implementations of \fBtput\fP on
505 SVr4-based systems such as Solaris, IRIX64 and HPUX
506 as well as others such as AIX and Tru64
507 provide support for \fIcapname\fR operands.
509 A few platforms such as FreeBSD recognize termcap names rather
510 than terminfo capability names in their respective \fBtput\fP commands.
511 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
512 Before that, it (like FreeBSD) recognized termcap names.
514 Because (apparently) \fIall\fP of the certified Unix systems
515 support the full set of capability names, the reasoning for documenting
516 only a few may not be apparent.
518 X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
519 and the other features used in this implementation.
521 That is, there are two standards for \fBtput\fP: POSIX (a subset) and X/Open Curses (the full implementation).
522 POSIX documents a subset to avoid the complication of including X/Open Curses
523 and the terminal capabilities database.
525 While it is certainly possible to write a \fBtput\fP program without using curses,
526 none of the systems which have a curses implementation provide
527 a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
534 \fBcurs_termcap\fR(3X).
536 This describes \fBncurses\fR
537 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
projects / ncurses.git / blob