ncurses 6.3 - patch 20220514
[ncurses.git] / man / tput.1
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
5 .\"                                                                          *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
7 .\" copy of this software and associated documentation files (the            *
8 .\" "Software"), to deal in the Software without restriction, including      *
9 .\" without limitation the rights to use, copy, modify, merge, publish,      *
10 .\" distribute, distribute with modifications, sublicense, and/or sell       *
11 .\" copies of the Software, and to permit persons to whom the Software is    *
12 .\" furnished to do so, subject to the following conditions:                 *
13 .\"                                                                          *
14 .\" The above copyright notice and this permission notice shall be included  *
15 .\" in all copies or substantial portions of the Software.                   *
16 .\"                                                                          *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
24 .\"                                                                          *
25 .\" Except as contained in this notice, the name(s) of the above copyright   *
26 .\" holders shall not be used in advertising or otherwise to promote the     *
27 .\" sale, use or other dealings in this Software without prior written       *
28 .\" authorization.                                                           *
29 .\"***************************************************************************
30 .\"
31 .\" $Id: tput.1,v 1.76 2022/02/12 20:02:20 tom Exp $
32 .TH @TPUT@ 1 ""
33 .ds d @TERMINFO@
34 .ds n 1
35 .ie \n(.g .ds `` \(lq
36 .el       .ds `` ``
37 .ie \n(.g .ds '' \(rq
38 .el       .ds '' ''
39 .de bP
40 .ie n  .IP \(bu 4
41 .el    .IP \(bu 2
42 ..
43 .SH NAME
44 \fB@TPUT@\fP, \fBreset\fP \- initialize a terminal or query terminfo database
45 .SH SYNOPSIS
46 \fB@TPUT@\fR [\fB\-T\fItype\fR] \fIcapname\fR [\fIparameters\fR]
47 .br
48 \fB@TPUT@\fR [\fB\-T\fItype\fR] [\fB\-x\fR] \fBclear\fR
49 .br
50 \fB@TPUT@\fR [\fB\-T\fItype\fR] \fBinit\fR
51 .br
52 \fB@TPUT@\fR [\fB\-T\fItype\fR] \fBreset\fR
53 .br
54 \fB@TPUT@\fR [\fB\-T\fItype\fR] \fBlongname\fR
55 .br
56 \fB@TPUT@ \-S\fP  \fB<<\fP
57 .br
58 \fB@TPUT@ \-V\fP
59 .br
60 .SH DESCRIPTION
61 The \fB@TPUT@\fP utility uses the \fBterminfo\fP database to make the
62 values of terminal-dependent capabilities and information available to
63 the shell (see \fBsh\fP(1)), to initialize or reset the terminal, or
64 return the long name of the requested terminal type.
65 The result depends upon the capability's type:
66 .RS 3
67 .TP 5
68 string
69 \fB@TPUT@\fP writes the string to the standard output.
70 No trailing newline is supplied.
71 .TP
72 integer
73 \fB@TPUT@\fP writes the decimal value to the standard output,
74 with a trailing newline.
75 .TP
76 boolean
77 \fB@TPUT@\fP simply sets the exit code
78 (\fB0\fP for TRUE if the terminal has the capability,
79 \fB1\fP for FALSE if it does not),
80 and writes nothing to the standard output.
81 .RE
82 .PP
83 Before using a value returned on the standard output,
84 the application should test the exit code
85 (e.g., \fB$?\fP, see \fBsh\fP(1)) to be sure it is \fB0\fP.
86 (See the \fBEXIT CODES\fP and \fBDIAGNOSTICS\fP sections.)
87 For a complete list of capabilities
88 and the \fIcapname\fP associated with each, see \fBterminfo\fP(5).
89 .SS Options
90 .TP
91 \fB\-S\fP
92 allows more than one capability per invocation of \fB@TPUT@\fP.  The
93 capabilities must be passed to \fB@TPUT@\fP from the standard input
94 instead of from the command line (see example).
95 Only one \fIcapname\fP is allowed per line.
96 The \fB\-S\fP option changes the
97 meaning of the \fB0\fP and \fB1\fP boolean and string exit codes (see the
98 EXIT CODES section).
99 .IP
100 Because some capabilities may use
101 \fIstring\fP parameters rather than \fInumbers\fP,
102 \fB@TPUT@\fP uses a table and the presence of parameters in its input
103 to decide whether to use \fBtparm\fP(3X),
104 and how to interpret the parameters.
105 .TP
106 \fB\-T\fItype\fR
107 indicates the \fItype\fP of terminal.
108 Normally this option is
109 unnecessary, because the default is taken from the environment
110 variable \fBTERM\fP.
111 If \fB\-T\fP is specified, then the shell
112 variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored.
113 .TP
114 \fB\-V\fP
115 reports the version of ncurses which was used in this program, and exits.
116 .TP
117 .B \-x
118 do not attempt to clear the terminal's scrollback buffer
119 using the extended \*(``E3\*('' capability.
120 .SS Commands
121 A few commands (\fBinit\fP, \fBreset\fP and \fBlongname\fP) are
122 special; they are defined by the \fB@TPUT@\fP program.
123 The others are the names of \fIcapabilities\fP from the terminal database
124 (see \fBterminfo\fP(5) for a list).
125 Although \fBinit\fP and \fBreset\fP resemble capability names,
126 \fB@TPUT@\fP uses several capabilities to perform these special functions.
127 .TP
128 \fIcapname\fP
129 indicates the capability from the terminal database.
130 .IP
131 If the capability is a string that takes parameters, the arguments
132 following the capability will be used as parameters for the string.
133 .IP
134 Most parameters are numbers.
135 Only a few terminal capabilities require string parameters;
136 \fB@TPUT@\fP uses a table to decide which to pass as strings.
137 Normally \fB@TPUT@\fP uses \fBtparm\fP(3X) to perform the substitution.
138 If no parameters are given for the capability,
139 \fB@TPUT@\fP writes the string without performing the substitution.
140 .TP
141 \fBinit\fP
142 If the terminal database is present and an entry for the user's
143 terminal exists (see \fB\-T\fItype\fR, above), the following will
144 occur:
145 .RS
146 .TP 5
147 (1)
148 first, \fB@TPUT@\fP retrieves the current terminal mode settings
149 for your terminal.
150 It does this by successively testing
151 .RS
152 .bP
153 the standard error,
154 .bP
155 standard output,
156 .bP
157 standard input and
158 .bP
159 ultimately \*(``/dev/tty\*(''
160 .RE
161 .IP
162 to obtain terminal settings.
163 Having retrieved these settings, \fB@TPUT@\fP remembers which
164 file descriptor to use when updating settings.
165 .TP
166 (2)
167 if the window size cannot be obtained from the operating system,
168 but the terminal description (or environment, e.g., \fBLINES\fP
169 and \fBCOLUMNS\fP variables specify this),
170 update the operating system's notion of the window size.
171 .TP
172 (3)
173 the terminal modes will be updated:
174 .RS
175 .bP
176 any delays (e.g., newline) specified in the entry will
177 be set in the tty driver,
178 .bP
179 tabs expansion will be turned on or off according to
180 the specification in the entry, and
181 .bP
182 if tabs are not expanded,
183 standard tabs will be set (every 8 spaces).
184 .RE
185 .TP
186 (4)
187 if present, the terminal's initialization strings will be
188 output as detailed in the \fBterminfo\fP(5) section on
189 .IR "Tabs and Initialization" ,
190 .TP
191 (5)
192 output is flushed.
193 .RE
194 .IP
195 If an entry does not
196 contain the information needed for any of these activities,
197 that activity will silently be skipped.
198 .TP
199 \fBreset\fP
200 This is similar to \fBinit\fP, with two differences:
201 .RS
202 .TP 5
203 (1)
204 before any other initialization,
205 the terminal modes will be reset to a \*(``sane\*('' state:
206 .RS
207 .bP
208 set cooked and echo modes,
209 .bP
210 turn off cbreak and raw modes,
211 .bP
212 turn on newline translation and
213 .bP
214 reset any unset special characters to their default values
215 .RE
216 .TP 5
217 (2)
218 Instead of putting out \fIinitialization\fP strings, the terminal's
219 \fIreset\fP strings will be output if present
220 (\fBrs1\fP, \fBrs2\fP, \fBrs3\fP, \fBrf\fP).
221 If the \fIreset\fP strings are not present, but \fIinitialization\fP
222 strings are, the \fIinitialization\fP strings will be output.
223 .RE
224 .IP
225 Otherwise, \fBreset\fP acts identically to \fBinit\fP.
226 .TP
227 \fBlongname\fP
228 If the terminal database is present and an entry for the
229 user's terminal exists (see \fB\-T\fItype\fR above), then the long name
230 of the terminal will be put out.
231 The long name is the last
232 name in the first line of the terminal's description in the
233 \fBterminfo\fP database [see \fBterm\fP(5)].
234 .SS Aliases
235 \fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
236 commands specially:
237 it allows for the possibility that it is invoked by a link with those names.
238 .PP
239 If \fB@TPUT@\fP is invoked by a link named \fBreset\fP, this has the
240 same effect as \fB@TPUT@ reset\fP.
241 The \fB@TSET@\fP(\*n) utility also treats a link named \fBreset\fP specially.
242 .PP
243 Before ncurses 6.1, the two utilities were different from each other:
244 .bP
245 \fB@TSET@\fP utility reset the terminal modes and special characters
246 (not done with \fB@TPUT@\fP).
247 .bP
248 On the other hand, \fB@TSET@\fP's repertoire of terminal capabilities for
249 resetting the terminal was more limited,
250 i.e., only \fBreset_1string\fP, \fBreset_2string\fP and \fBreset_file\fP
251 in contrast to the tab-stops and margins which are set by this utility.
252 .bP
253 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
254 because of this difference with resetting terminal modes and special characters.
255 .PP
256 With the changes made for ncurses 6.1, the \fIreset\fP feature of the
257 two programs is (mostly) the same.
258 A few differences remain:
259 .bP
260 The \fB@TSET@\fP program waits one second when resetting,
261 in case it happens to be a hardware terminal.
262 .bP
263 The two programs write the terminal initialization strings
264 to different streams (i.e., the standard error for \fB@TSET@\fP and the
265 standard output for \fB@TPUT@\fP).
266 .IP
267 \fBNote:\fP although these programs write to different streams,
268 redirecting their output to a file will capture only part of their actions.
269 The changes to the terminal modes are not affected by redirecting the output.
270 .PP
271 If \fB@TPUT@\fP is invoked by a link named \fBinit\fP, this has the
272 same effect as \fB@TPUT@ init\fP.
273 Again, you are less likely to use that link because another program
274 named \fBinit\fP has a more well-established use.
275 .SS Terminal Size
276 .PP
277 Besides the special commands (e.g., \fBclear\fP),
278 @TPUT@ treats certain terminfo capabilities specially:
279 \fBlines\fP and \fBcols\fP.
280 @TPUT@ calls \fBsetupterm\fP(3X) to obtain the terminal size:
281 .bP
282 first, it gets the size from the terminal database
283 (which generally is not provided for terminal emulators
284 which do not have a fixed window size)
285 .bP
286 then it asks the operating system for the terminal's size
287 (which generally works, unless connecting via a serial line which
288 does not support \fINAWS\fP: negotiations about window size).
289 .bP
290 finally, it inspects the environment variables \fBLINES\fP and \fBCOLUMNS\fP
291 which may override the terminal size.
292 .PP
293 If the \fB\-T\fP option is given
294 @TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP,
295 relying upon the operating system (or finally, the terminal database).
296 .SH EXAMPLES
297 .TP 5
298 \fB@TPUT@ init\fP
299 Initialize the terminal according to the type of
300 terminal in the environmental variable \fBTERM\fP.  This
301 command should be included in everyone's .profile after
302 the environmental variable \fBTERM\fP has been exported, as
303 illustrated on the \fBprofile\fP(5) manual page.
304 .TP 5
305 \fB@TPUT@ \-T5620 reset\fP
306 Reset an AT&T 5620 terminal, overriding the type of
307 terminal in the environmental variable \fBTERM\fP.
308 .TP 5
309 \fB@TPUT@ cup 0 0\fP
310 Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
311 (the upper left corner of the screen, usually known as the \*(``home\*(''
312 cursor position).
313 .TP 5
314 \fB@TPUT@ clear\fP
315 Echo the clear-screen sequence for the current terminal.
316 .TP 5
317 \fB@TPUT@ cols\fP
318 Print the number of columns for the current terminal.
319 .TP 5
320 \fB@TPUT@ \-T450 cols\fP
321 Print the number of columns for the 450 terminal.
322 .TP 5
323 \fBbold=`@TPUT@ smso` offbold=`@TPUT@ rmso`\fP
324 Set the shell variables \fBbold\fP, to begin stand-out mode
325 sequence, and \fBoffbold\fP, to end standout mode sequence,
326 for the current terminal.
327 This might be followed by a
328 prompt: \fBecho "${bold}Please type in your name: ${offbold}\\c"\fP
329 .TP 5
330 \fB@TPUT@ hc\fP
331 Set exit code to indicate if the current terminal is a hard copy terminal.
332 .TP 5
333 \fB@TPUT@ cup 23 4\fP
334 Send the sequence to move the cursor to row 23, column 4.
335 .TP 5
336 \fB@TPUT@ cup\fP
337 Send the terminfo string for cursor-movement, with no parameters substituted.
338 .TP 5
339 \fB@TPUT@ longname\fP
340 Print the long name from the \fBterminfo\fP database for the
341 type of terminal specified in the environmental
342 variable \fBTERM\fP.
343 .PP
344 .RS 5
345 \fB@TPUT@ \-S <<!\fP
346 .br
347 \fB> clear\fP
348 .br
349 \fB> cup 10 10\fP
350 .br
351 \fB> bold\fP
352 .br
353 \fB> !\fP
354 .RE
355 .TP 5
356 \&
357 This example shows \fB@TPUT@\fP processing several capabilities
358 in one invocation.
359 It clears the screen,
360 moves the cursor to position 10, 10
361 and turns on bold (extra bright) mode.
362 The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
363 .SH FILES
364 .TP
365 \fB\*d\fP
366 compiled terminal description database
367 .TP
368 \fB@DATADIR@/tabset/*\fP
369 tab settings for some terminals, in a format
370 appropriate to be output to the terminal (escape
371 sequences that set margins and tabs); for more
372 information, see the
373 .IR "Tabs and Initialization" ,
374 section of \fBterminfo\fP(5)
375 .SH EXIT CODES
376 If the \fB\-S\fP option is used,
377 \fB@TPUT@\fP checks for errors from each line,
378 and if any errors are found, will set the exit code to 4 plus the
379 number of lines with errors.
380 If no errors are found, the exit code is \fB0\fP.
381 No indication of which line failed can be given so
382 exit code \fB1\fP will never appear.
383 Exit codes \fB2\fP, \fB3\fP, and
384 \fB4\fP retain their usual interpretation.
385 If the \fB\-S\fP option is not used,
386 the exit code depends on the type of \fIcapname\fP:
387 .RS 3
388 .TP
389 .I boolean
390 a value of \fB0\fP is set for TRUE and \fB1\fP for FALSE.
391 .TP
392 .I string
393 a value of \fB0\fP is set if the
394 \fIcapname\fP is defined for this terminal \fItype\fP (the value of
395 \fIcapname\fP is returned on standard output);
396 a value of \fB1\fP is set if \fIcapname\fP
397 is not defined for this terminal \fItype\fP
398 (nothing is written to standard output).
399 .TP
400 .I integer
401 a value of \fB0\fP is always set,
402 whether or not \fIcapname\fP is defined for this terminal \fItype\fP.
403 To determine if \fIcapname\fP is defined for this terminal \fItype\fP,
404 the user must test the value written to standard output.
405 A value of \fB\-1\fP
406 means that \fIcapname\fP is not defined for this terminal \fItype\fP.
407 .TP
408 .I other
409 \fBreset\fP or \fBinit\fP may fail to find their respective files.
410 In that case, the exit code is set to 4 + \fBerrno\fP.
411 .RE
412 .PP
413 Any other exit code indicates an error; see the DIAGNOSTICS section.
414 .SH DIAGNOSTICS
415 \fB@TPUT@\fP prints the following error messages and sets the corresponding exit
416 codes.
417 .PP
418 .ne 15
419 .TS
420 l l.
421 exit code       error message
422 =
423 \fB0\fP T{
424 (\fIcapname\fP is a numeric variable that is not specified in the
425 \fBterminfo\fP(5) database for this terminal type, e.g.
426 \fB@TPUT@ \-T450 lines\fP and \fB@TPUT@ \-Thp2621 xmc\fP)
427 T}
428 \fB1\fP no error message is printed, see the \fBEXIT CODES\fP section.
429 \fB2\fP usage error
430 \fB3\fP unknown terminal \fItype\fP or no \fBterminfo\fP database
431 \fB4\fP unknown \fBterminfo\fP capability \fIcapname\fP
432 \fB>4\fP        error occurred in \-S
433 =
434 .TE
435 .SH HISTORY
436 The \fBtput\fP command was begun by Bill Joy in 1980.
437 The initial version only cleared the screen.
438 .PP
439 AT&T System V provided a different \fBtput\fP command:
440 .bP
441 SVr2 provided a rudimentary \fBtput\fP
442 which checked the parameter against each
443 predefined capability and returned the corresponding value.
444 This version of \fBtput\fP did not use \fBtparm\fP(3X) for
445 the capabilities which are parameterized.
446 .bP
447 SVr3 replaced that, a year later, by a more extensive program
448 whose \fBinit\fP and \fBreset\fP subcommands
449 (more than half the program) were incorporated from
450 the \fBreset\fP feature of BSD \fBtset\fP written by Eric Allman.
451 .bP
452 SVr4 added color initialization using the \fBorig_colors\fP and
453 \fBorig_pair\fP capabilities in the \fBinit\fP subcommand.
454 .PP
455 Keith Bostic replaced the BSD \fBtput\fP command in 1989
456 with a new implementation
457 based on the AT&T System V program \fBtput\fP.
458 Like the AT&T program, Bostic's version
459 accepted some parameters named for \fIterminfo\fP capabilities
460 (\fBclear\fP, \fBinit\fP, \fBlongname\fP and \fBreset\fP).
461 However (because he had only \fItermcap\fP available),
462 it accepted \fItermcap\fP names for other capabilities.
463 Also, Bostic's BSD \fBtput\fP did not modify the terminal I/O modes
464 as the earlier BSD \fBtset\fP had done.
465 .PP
466 At the same time, Bostic added a shell script named \*(``clear\*('',
467 which used \fBtput\fP to clear the screen.
468 .PP
469 Both of these appeared in 4.4BSD,
470 becoming the \*(``modern\*('' BSD implementation of \fBtput\fP.
471 .PP
472 This implementation of \fBtput\fP began from a different source than
473 AT&T or BSD: Ross Ridge's \fImytinfo\fP package, published on
474 \fIcomp.sources.unix\fP in December 1992.
475 Ridge's program made more sophisticated use of the terminal capabilities
476 than the BSD program.
477 Eric Raymond used that \fBtput\fP program
478 (and other parts of \fImytinfo\fP) in ncurses in June 1995.
479 Using the portions dealing with terminal capabilities
480 almost without change,
481 Raymond made improvements to the way the command-line parameters
482 were handled.
483 .SH PORTABILITY
484 .PP
485 This implementation of \fBtput\fP differs from AT&T \fBtput\fP in
486 two important areas:
487 .bP
488 \fB@TPUT@\fP \fIcapname\fP writes to the standard output.
489 That need not be a regular terminal.
490 However, the subcommands which manipulate terminal modes
491 may not use the standard output.
492 .IP
493 The AT&T implementation's \fBinit\fP and \fBreset\fP commands
494 use the BSD (4.1c) \fBtset\fP source, which manipulates terminal modes.
495 It successively tries standard output, standard error, standard input
496 before falling back to \*(``/dev/tty\*('' and finally just assumes
497 a 1200Bd terminal.
498 When updating terminal modes, it ignores errors.
499 .IP
500 Until changes made after ncurses 6.0,
501 \fB@TPUT@\fP did not modify terminal modes.
502 \fB@TPUT@\fP now uses a similar scheme,
503 using functions shared with \fB@TSET@\fP
504 (and ultimately based on the 4.4BSD \fBtset\fP).
505 If it is not able to open a terminal, e.g., when running in \fBcron\fP(1),
506 \fB@TPUT@\fP will return an error.
507 .bP
508 AT&T \fBtput\fP guesses the type of its \fIcapname\fP operands by seeing if
509 all of the characters are numeric, or not.
510 .IP
511 Most implementations which provide support for \fIcapname\fP operands
512 use the \fBtparm\fP function to expand parameters in it.
513 That function expects a mixture of numeric and string parameters,
514 requiring \fB@TPUT@\fP to know which type to use.
515 .IP
516 This implementation uses a table to determine the parameter types for
517 the standard \fIcapname\fP operands, and an internal library
518 function to analyze nonstandard \fIcapname\fP operands.
519 .IP
520 Besides providing more reliable operation than AT&T's utility,
521 a portability problem is introduced by this analysis:
522 An OpenBSD developer adapted the internal library function from ncurses
523 to port NetBSD's termcap-based \fBtput\fP to terminfo.
524 That had been modified to interpret multiple commands on a line.
525 Portable applications should not rely upon this feature;
526 ncurses provides it to support applications written
527 specifically for OpenBSD.
528 .PP
529 This implementation (unlike others) can accept both \fItermcap\fP
530 and \fIterminfo\fP names for the \fIcapname\fP feature,
531 if
532 \fItermcap\fP support is compiled in.
533 However, the predefined \fItermcap\fP and \fIterminfo\fP names have two
534 ambiguities in this case (and the \fIterminfo\fP name is assumed):
535 .bP
536 The \fItermcap\fP name \fBdl\fP corresponds to
537 the \fIterminfo\fP name \fBdl1\fP (delete one line).
538 .br
539 The \fIterminfo\fP name \fBdl\fP corresponds to
540 the \fItermcap\fP name \fBDL\fP (delete a given number of lines).
541 .bP
542 The \fItermcap\fP name \fBed\fP corresponds to
543 the \fIterminfo\fP name \fBrmdc\fP (end delete mode).
544 .br
545 The \fIterminfo\fP name \fBed\fP corresponds to
546 the \fItermcap\fP name \fBcd\fP (clear to end of screen).
547 .PP
548 The \fBlongname\fP and \fB\-S\fP options, and the parameter-substitution
549 features used in the \fBcup\fP example,
550 were not supported in BSD curses before 4.3reno (1989) or in
551 AT&T/USL curses before SVr4 (1988).
552 .PP
553 IEEE Std 1003.1/The Open Group  Base Specifications Issue 7 (POSIX.1-2008)
554 documents only the operands for \fBclear\fP, \fBinit\fP and \fBreset\fP.
555 There are a few interesting observations to make regarding that:
556 .bP
557 In this implementation, \fBclear\fP is part of the \fIcapname\fP support.
558 The others (\fBinit\fP and \fBlongname\fP) do not correspond to terminal
559 capabilities.
560 .bP
561 Other implementations of \fBtput\fP on
562 SVr4-based systems such as Solaris, IRIX64 and HPUX
563 as well as others such as AIX and Tru64
564 provide support for \fIcapname\fP operands.
565 .bP
566 A few platforms such as FreeBSD recognize termcap names rather
567 than terminfo capability names in their respective \fBtput\fP commands.
568 Since 2010, NetBSD's \fBtput\fP uses terminfo names.
569 Before that, it (like FreeBSD) recognized termcap names.
570 .IP
571 Beginning in 2021, FreeBSD uses the ncurses \fBtput\fP,
572 configured for both terminfo (tested first) and termcap (as a fallback).
573 .PP
574 Because (apparently) \fIall\fP of the certified Unix systems
575 support the full set of capability names, the reasoning for documenting
576 only a few may not be apparent.
577 .bP
578 X/Open Curses Issue 7 documents \fBtput\fP differently, with \fIcapname\fP
579 and the other features used in this implementation.
580 .bP
581 That is, there are two standards for \fBtput\fP:
582 POSIX (a subset) and X/Open Curses (the full implementation).
583 POSIX documents a subset to avoid the complication of including X/Open Curses
584 and the terminal capabilities database.
585 .bP
586 While it is certainly possible to write a \fBtput\fP program
587 without using curses,
588 none of the systems which have a curses implementation provide
589 a \fBtput\fP utility which does not provide the \fIcapname\fP feature.
590 .PP
591 X/Open Curses Issue 7 (2009) is the first version to document utilities.
592 However that part of X/Open Curses does not follow existing practice
593 (i.e., Unix features documented in SVID 3):
594 .bP
595 It assigns exit code 4 to \*(``invalid operand\*('',
596 which may be the same as \fIunknown capability\fP.
597 For instance, the source code for Solaris' xcurses uses the term
598 \*(``invalid\*('' in this case.
599 .bP
600 It assigns exit code 255 to a numeric variable that is not specified in
601 the terminfo database.
602 That likely is a documentation error,
603 confusing the \fB\-1\fP written to the standard output for an absent
604 or cancelled numeric value versus an (unsigned) exit code.
605 .PP
606 The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes
607 as ncurses.
608 .PP
609 NetBSD curses documents different exit codes which do not correspond
610 to either ncurses or X/Open.
611 .SH SEE ALSO
612 \fB@CLEAR@\fP(\*n),
613 \fBstty\fP(1),
614 \fB@TABS@\fP(\*n),
615 \fB@TSET@\fP(\*n),
616 \fBcurs_termcap\fP(3X),
617 \fBterminfo\fP(5).
618 .PP
619 This describes \fBncurses\fP
620 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).