1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
|
<!--
* t
****************************************************************************
* Copyright 2018,2020 Thomas E. Dickey *
* Copyright 1998-2016,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
* "Software"), to deal in the Software without restriction, including *
* without limitation the rights to use, copy, modify, merge, publish, *
* distribute, distribute with modifications, sublicense, and/or sell *
* copies of the Software, and to permit persons to whom the Software is *
* furnished to do so, subject to the following conditions: *
* *
* The above copyright notice and this permission notice shall be included *
* in all copies or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
* *
* Except as contained in this notice, the name(s) of the above copyright *
* holders shall not be used in advertising or otherwise to promote the *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
* @Id: tput.1,v 1.63 2020/02/02 23:34:34 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>tput 1</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
<H1 class="no-header">tput 1</H1>
<PRE>
<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> General Commands Manual <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>tput</STRONG>, <STRONG>reset</STRONG> - initialize a terminal or query terminfo database
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <EM>capname</EM> [<EM>parameters</EM>]
<STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
<STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>init</STRONG>
<STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>reset</STRONG>
<STRONG>tput</STRONG> [<STRONG>-T</STRONG><EM>type</EM>] <STRONG>longname</STRONG>
<STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG><<</STRONG>
<STRONG>tput</STRONG> <STRONG>-V</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The <STRONG>tput</STRONG> utility uses the <STRONG>terminfo</STRONG> database to make the values of ter-
minal-dependent capabilities and information available to the shell
(see <STRONG>sh(1)</STRONG>), to initialize or reset the terminal, or return the long
name of the requested terminal type. The result depends upon the capa-
bility's type:
string
<STRONG>tput</STRONG> writes the string to the standard output. No trailing
newline is supplied.
integer
<STRONG>tput</STRONG> writes the decimal value to the standard output, with a
trailing newline.
boolean
<STRONG>tput</STRONG> simply sets the exit code (<STRONG>0</STRONG> for TRUE if the terminal has
the capability, <STRONG>1</STRONG> for FALSE if it does not), and writes nothing
to the standard output.
Before using a value returned on the standard output, the application
should test the exit code (e.g., <STRONG>$?</STRONG>, see <STRONG>sh(1)</STRONG>) to be sure it is <STRONG>0</STRONG>.
(See the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> and <STRONG>DIAGNOSTICS</STRONG> sections.) For a complete list of
capabilities and the <EM>capname</EM> associated with each, see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
</PRE><H3><a name="h3-Options">Options</a></H3><PRE>
<STRONG>-S</STRONG> allows more than one capability per invocation of <STRONG>tput</STRONG>. The
capabilities must be passed to <STRONG>tput</STRONG> from the standard input
instead of from the command line (see example). Only one <EM>cap-</EM>
<EM>name</EM> is allowed per line. The <STRONG>-S</STRONG> option changes the meaning of
the <STRONG>0</STRONG> and <STRONG>1</STRONG> boolean and string exit codes (see the EXIT CODES
section).
Because some capabilities may use <EM>string</EM> parameters rather than
<EM>numbers</EM>, <STRONG>tput</STRONG> uses a table and the presence of parameters in its
input to decide whether to use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>, and how to interpret
the parameters.
<STRONG>-T</STRONG><EM>type</EM> indicates the <EM>type</EM> of terminal. Normally this option is unnec-
essary, because the default is taken from the environment vari-
able <STRONG>TERM</STRONG>. If <STRONG>-T</STRONG> is specified, then the shell variables <STRONG>LINES</STRONG>
and <STRONG>COLUMNS</STRONG> will also be ignored.
<STRONG>-V</STRONG> reports the version of ncurses which was used in this program,
and exits.
<STRONG>-x</STRONG> do not attempt to clear the terminal's scrollback buffer using
the extended "E3" capability.
</PRE><H3><a name="h3-Commands">Commands</a></H3><PRE>
A few commands (<STRONG>init</STRONG>, <STRONG>reset</STRONG> and <STRONG>longname</STRONG>) are special; they are defined
by the <STRONG>tput</STRONG> program. The others are the names of <EM>capabilities</EM> from the
terminal database (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for a list). Although <STRONG>init</STRONG> and
<STRONG>reset</STRONG> resemble capability names, <STRONG>tput</STRONG> uses several capabilities to per-
form these special functions.
<EM>capname</EM>
indicates the capability from the terminal database.
If the capability is a string that takes parameters, the argu-
ments following the capability will be used as parameters for
the string.
Most parameters are numbers. Only a few terminal capabilities
require string parameters; <STRONG>tput</STRONG> uses a table to decide which to
pass as strings. Normally <STRONG>tput</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the
substitution. If no parameters are given for the capability,
<STRONG>tput</STRONG> writes the string without performing the substitution.
<STRONG>init</STRONG> If the terminal database is present and an entry for the user's
terminal exists (see <STRONG>-T</STRONG><EM>type</EM>, above), the following will occur:
(1) first, <STRONG>tput</STRONG> retrieves the current terminal mode settings
for your terminal. It does this by successively testing
<STRONG>o</STRONG> the standard error,
<STRONG>o</STRONG> standard output,
<STRONG>o</STRONG> standard input and
<STRONG>o</STRONG> ultimately "/dev/tty"
to obtain terminal settings. Having retrieved these set-
tings, <STRONG>tput</STRONG> remembers which file descriptor to use when
updating settings.
(2) if the window size cannot be obtained from the operating
system, but the terminal description (or environment, e.g.,
<STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> variables specify this), update the oper-
ating system's notion of the window size.
(3) the terminal modes will be updated:
<STRONG>o</STRONG> any delays (e.g., newline) specified in the entry will
be set in the tty driver,
<STRONG>o</STRONG> tabs expansion will be turned on or off according to
the specification in the entry, and
<STRONG>o</STRONG> if tabs are not expanded, standard tabs will be set
(every 8 spaces).
(4) if present, the terminal's initialization strings will be
output as detailed in the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> section on <EM>Tabs</EM> <EM>and</EM>
<EM>Initialization</EM>,
(5) output is flushed.
If an entry does not contain the information needed for any of
these activities, that activity will silently be skipped.
<STRONG>reset</STRONG> This is similar to <STRONG>init</STRONG>, with two differences:
(1) before any other initialization, the terminal modes will be
reset to a "sane" state:
<STRONG>o</STRONG> set cooked and echo modes,
<STRONG>o</STRONG> turn off cbreak and raw modes,
<STRONG>o</STRONG> turn on newline translation and
<STRONG>o</STRONG> reset any unset special characters to their default
values
(2) Instead of putting out <EM>initialization</EM> strings, the termi-
nal's <EM>reset</EM> strings will be output if present (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>,
<STRONG>rs3</STRONG>, <STRONG>rf</STRONG>). If the <EM>reset</EM> strings are not present, but <EM>ini-</EM>
<EM>tialization</EM> strings are, the <EM>initialization</EM> strings will be
output.
Otherwise, <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
<STRONG>longname</STRONG>
If the terminal database is present and an entry for the user's
terminal exists (see <STRONG>-T</STRONG><EM>type</EM> above), then the long name of the
terminal will be put out. The long name is the last name in the
first line of the terminal's description in the <STRONG>terminfo</STRONG> data-
base [see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>].
</PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
<STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands specially: it allows
for the possibility that it is invoked by a link with those names.
If <STRONG>tput</STRONG> is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
<STRONG>tput</STRONG> <STRONG>reset</STRONG>. The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility also treats a link named <STRONG>reset</STRONG> spe-
cially.
Before ncurses 6.1, the two utilities were different from each other:
<STRONG>o</STRONG> <STRONG>tset</STRONG> utility reset the terminal modes and special characters (not
done with <STRONG>tput</STRONG>).
<STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for
resetting the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
<STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG> in contrast to the tab-stops and mar-
gins which are set by this utility.
<STRONG>o</STRONG> The <STRONG>reset</STRONG> program is usually an alias for <STRONG>tset</STRONG>, because of this
difference with resetting terminal modes and special characters.
With the changes made for ncurses 6.1, the <EM>reset</EM> feature of the two
programs is (mostly) the same. A few differences remain:
<STRONG>o</STRONG> The <STRONG>tset</STRONG> program waits one second when resetting, in case it hap-
pens to be a hardware terminal.
<STRONG>o</STRONG> The two programs write the terminal initialization strings to dif-
ferent streams (i.e., the standard error for <STRONG>tset</STRONG> and the standard
output for <STRONG>tput</STRONG>).
<STRONG>Note:</STRONG> although these programs write to different streams, redirect-
ing their output to a file will capture only part of their actions.
The changes to the terminal modes are not affected by redirecting
the output.
If <STRONG>tput</STRONG> is invoked by a link named <STRONG>init</STRONG>, this has the same effect as
<STRONG>tput</STRONG> <STRONG>init</STRONG>. Again, you are less likely to use that link because another
program named <STRONG>init</STRONG> has a more well-established use.
</PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
Besides the special commands (e.g., <STRONG>clear</STRONG>), tput treats certain ter-
minfo capabilities specially: <STRONG>lines</STRONG> and <STRONG>columns</STRONG>. tput calls
<STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the terminal size:
<STRONG>o</STRONG> first, it gets the size from the terminal database (which generally
is not provided for terminal emulators which do not have a fixed
window size)
<STRONG>o</STRONG> then it asks the operating system for the terminal's size (which
generally works, unless connecting via a serial line which does not
support <EM>NAWS</EM>: negotiations about window size).
<STRONG>o</STRONG> finally, it inspects the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG>
which may override the terminal size.
If the <STRONG>-T</STRONG> option is given tput ignores the environment variables by
calling <STRONG>use_tioctl(TRUE)</STRONG>, relying upon the operating system (or
finally, the terminal database).
</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
<STRONG>tput</STRONG> <STRONG>init</STRONG>
Initialize the terminal according to the type of terminal in the
environmental variable <STRONG>TERM</STRONG>. This command should be included in
everyone's .profile after the environmental variable <STRONG>TERM</STRONG> has been
exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
<STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
Reset an AT&T 5620 terminal, overriding the type of terminal in
the environmental variable <STRONG>TERM</STRONG>.
<STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
left corner of the screen, usually known as the "home" cursor
position).
<STRONG>tput</STRONG> <STRONG>clear</STRONG>
Echo the clear-screen sequence for the current terminal.
<STRONG>tput</STRONG> <STRONG>cols</STRONG>
Print the number of columns for the current terminal.
<STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>cols</STRONG>
Print the number of columns for the 450 terminal.
<STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
Set the shell variables <STRONG>bold</STRONG>, to begin stand-out mode sequence,
and <STRONG>offbold</STRONG>, to end standout mode sequence, for the current termi-
nal. This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG> <STRONG>type</STRONG>
<STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
<STRONG>tput</STRONG> <STRONG>hc</STRONG>
Set exit code to indicate if the current terminal is a hard copy
terminal.
<STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG>
Send the sequence to move the cursor to row 23, column 4.
<STRONG>tput</STRONG> <STRONG>cup</STRONG>
Send the terminfo string for cursor-movement, with no parameters
substituted.
<STRONG>tput</STRONG> <STRONG>longname</STRONG>
Print the long name from the <STRONG>terminfo</STRONG> database for the type of
terminal specified in the environmental variable <STRONG>TERM</STRONG>.
<STRONG>tput</STRONG> <STRONG>-S</STRONG> <STRONG><<!</STRONG>
<STRONG>></STRONG> <STRONG>clear</STRONG>
<STRONG>></STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG>
<STRONG>></STRONG> <STRONG>bold</STRONG>
<STRONG>></STRONG> <STRONG>!</STRONG>
This example shows <STRONG>tput</STRONG> processing several capabilities in one
invocation. It clears the screen, moves the cursor to position
10, 10 and turns on bold (extra bright) mode. The list is termi-
nated by an exclamation mark (<STRONG>!</STRONG>) on a line by itself.
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
<STRONG>/usr/share/terminfo</STRONG>
compiled terminal description database
<STRONG>/usr/share/tabset/*</STRONG>
tab settings for some terminals, in a format appropriate to be
output to the terminal (escape sequences that set margins and
tabs); for more information, see the <EM>Tabs</EM> <EM>and</EM> <EM>Initialization</EM>,
section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
</PRE><H2><a name="h2-EXIT-CODES">EXIT CODES</a></H2><PRE>
If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
any errors are found, will set the exit code to 4 plus the number of
lines with errors. If no errors are found, the exit code is <STRONG>0</STRONG>. No
indication of which line failed can be given so exit code <STRONG>1</STRONG> will never
appear. Exit codes <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual interpretation. If
the <STRONG>-S</STRONG> option is not used, the exit code depends on the type of <EM>cap-</EM>
<EM>name</EM>:
<EM>boolean</EM>
a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
<EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>capname</EM> is defined for this termi-
nal <EM>type</EM> (the value of <EM>capname</EM> is returned on standard out-
put); a value of <STRONG>1</STRONG> is set if <EM>capname</EM> is not defined for this
terminal <EM>type</EM> (nothing is written to standard output).
<EM>integer</EM>
a value of <STRONG>0</STRONG> is always set, whether or not <EM>capname</EM> is defined
for this terminal <EM>type</EM>. To determine if <EM>capname</EM> is defined
for this terminal <EM>type</EM>, the user must test the value written
to standard output. A value of <STRONG>-1</STRONG> means that <EM>capname</EM> is not
defined for this terminal <EM>type</EM>.
<EM>other</EM> <STRONG>reset</STRONG> or <STRONG>init</STRONG> may fail to find their respective files. In
that case, the exit code is set to 4 + <STRONG>errno</STRONG>.
Any other exit code indicates an error; see the DIAGNOSTICS section.
</PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
<STRONG>tput</STRONG> prints the following error messages and sets the corresponding
exit codes.
exit code error message
---------------------------------------------------------------------
<STRONG>0</STRONG> (<EM>capname</EM> is a numeric variable that is not specified in
the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> database for this terminal type, e.g.
<STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-T2621</STRONG> <STRONG>xmc</STRONG>)
<STRONG>1</STRONG> no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>CODES</STRONG> section.
<STRONG>2</STRONG> usage error
<STRONG>3</STRONG> unknown terminal <EM>type</EM> or no <STRONG>terminfo</STRONG> database
<STRONG>4</STRONG> unknown <STRONG>terminfo</STRONG> capability <EM>capname</EM>
<STRONG>>4</STRONG> error occurred in -S
---------------------------------------------------------------------
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
The <STRONG>tput</STRONG> command was begun by Bill Joy in 1980. The initial version
only cleared the screen.
AT&T System V provided a different <STRONG>tput</STRONG> command, whose <STRONG>init</STRONG> and <STRONG>reset</STRONG>
subcommands (more than half the program) were incorporated from the
<STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman.
Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with a new implemen-
tation based on the AT&T System V program <STRONG>tput</STRONG>. Like the AT&T program,
Bostic's version accepted some parameters named for <EM>terminfo</EM> <EM>capabili-</EM>
<EM>ties</EM> (<STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG> and <STRONG>reset</STRONG>). However (because he had only
termcap available), it accepted <EM>termcap</EM> <EM>names</EM> for other capabilities.
Also, Bostic's BSD <STRONG>tput</STRONG> did not modify the terminal I/O modes as the
earlier BSD <STRONG>tset</STRONG> had done.
At the same time, Bostic added a shell script named "clear", which used
<STRONG>tput</STRONG> to clear the screen.
Both of these appeared in 4.4BSD, becoming the "modern" BSD implementa-
tion of <STRONG>tput</STRONG>.
This implementation of <STRONG>tput</STRONG> began from a different source than AT&T or
BSD: Ross Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
December 1992. Ridge's program made more sophisticated use of the ter-
minal capabilities than the BSD program. Eric Raymond used that <STRONG>tput</STRONG>
program (and other parts of <EM>mytinfo</EM>) in ncurses in June 1995. Using
the portions dealing with terminal capabilities almost without change,
Raymond made improvements to the way the command-line parameters were
handled.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
This implementation of <STRONG>tput</STRONG> differs from AT&T <STRONG>tput</STRONG> in two important
areas:
<STRONG>o</STRONG> <STRONG>tput</STRONG> <EM>capname</EM> writes to the standard output. That need not be a
regular terminal. However, the subcommands which manipulate termi-
nal modes may not use the standard output.
The AT&T implementation's <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands use the BSD
(4.1c) <STRONG>tset</STRONG> source, which manipulates terminal modes. It succes-
sively tries standard output, standard error, standard input before
falling back to "/dev/tty" and finally just assumes a 1200Bd termi-
nal. When updating terminal modes, it ignores errors.
Until changes made after ncurses 6.0, <STRONG>tput</STRONG> did not modify terminal
modes. <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
<STRONG>tset</STRONG> (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>). If it is not able
to open a terminal, e.g., when running in <STRONG>cron</STRONG>, <STRONG>tput</STRONG> will return an
error.
<STRONG>o</STRONG> AT&T <STRONG>tput</STRONG> guesses the type of its <EM>capname</EM> operands by seeing if all
of the characters are numeric, or not.
Most implementations which provide support for <EM>capname</EM> operands use
the <EM>tparm</EM> function to expand parameters in it. That function
expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
to know which type to use.
This implementation uses a table to determine the parameter types
for the standard <EM>capname</EM> operands, and an internal library function
to analyze nonstandard <EM>capname</EM> operands.
This implementation (unlike others) can accept both <EM>termcap</EM> and <EM>ter-</EM>
<EM>minfo</EM> names for the <EM>capname</EM> feature, if <EM>termcap</EM> support is compiled in.
However, the predefined <EM>termcap</EM> and <EM>terminfo</EM> names have two ambiguities
in this case (and the <EM>terminfo</EM> name is assumed):
<STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>dl1</STRONG> (delete
one line).
The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG> (delete a
given number of lines).
<STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>ed</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>rmdc</STRONG> (end
delete mode).
The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG> (clear to
end of screen).
The <STRONG>longname</STRONG> and <STRONG>-S</STRONG> options, and the parameter-substitution features
used in the <STRONG>cup</STRONG> example, were not supported in BSD curses before
4.3reno (1989) or in AT&T/USL curses before SVr4 (1988).
IEEE Std 1003.1/The Open Group Base Specifications Issue 7
(POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG>.
There are a few interesting observations to make regarding that:
<STRONG>o</STRONG> In this implementation, <STRONG>clear</STRONG> is part of the <EM>capname</EM> support. The
others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal capabili-
ties.
<STRONG>o</STRONG> Other implementations of <STRONG>tput</STRONG> on SVr4-based systems such as
Solaris, IRIX64 and HPUX as well as others such as AIX and Tru64
provide support for <EM>capname</EM> operands.
<STRONG>o</STRONG> A few platforms such as FreeBSD recognize termcap names rather than
terminfo capability names in their respective <STRONG>tput</STRONG> commands. Since
2010, NetBSD's <STRONG>tput</STRONG> uses terminfo names. Before that, it (like
FreeBSD) recognized termcap names.
Because (apparently) <EM>all</EM> of the certified Unix systems support the full
set of capability names, the reasoning for documenting only a few may
not be apparent.
<STRONG>o</STRONG> X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>capname</EM> and
the other features used in this implementation.
<STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
X/Open Curses (the full implementation). POSIX documents a subset
to avoid the complication of including X/Open Curses and the termi-
nal capabilities database.
<STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without
using curses, none of the systems which have a curses implementa-
tion provide a <STRONG>tput</STRONG> utility which does not provide the <EM>capname</EM> fea-
ture.
X/Open Curses Issue 7 (2009) is the first version to document utili-
ties. However that part of X/Open Curses does not follow existing
practice (i.e., Unix features documented in SVID 3):
<STRONG>o</STRONG> It assigns exit code 4 to "invalid operand", which may be the same
as <EM>unknown</EM> <EM>capability</EM>. For instance, the source code for Solaris'
xcurses uses the term "invalid" in this case.
<STRONG>o</STRONG> It assigns exit code 255 to a numeric variable that is not speci-
fied in the terminfo database. That likely is a documentation
error, confusing the <STRONG>-1</STRONG> written to the standard output for an
absent or cancelled numeric value versus an (unsigned) exit code.
The various Unix systems (AIX, HPUX, Solaris) use the same exit-codes
as ncurses.
NetBSD curses documents different exit codes which do not correspond to
either ncurses or X/Open.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>.
This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200212).
<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Options">Options</a></li>
<li><a href="#h3-Commands">Commands</a></li>
<li><a href="#h3-Aliases">Aliases</a></li>
<li><a href="#h3-Terminal-Size">Terminal Size</a></li>
</ul>
</li>
<li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
<li><a href="#h2-FILES">FILES</a></li>
<li><a href="#h2-EXIT-CODES">EXIT CODES</a></li>
<li><a href="#h2-DIAGNOSTICS">DIAGNOSTICS</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
|
