1tput(1)                     General Commands Manual                    tput(1)
2
3
4

NAME

6       tput, reset - initialize a terminal or query terminfo database
7

SYNOPSIS

9       tput [-Ttype] capname [parameters]
10       tput [-Ttype] [-x] clear
11       tput [-Ttype] init
12       tput [-Ttype] reset
13       tput [-Ttype] longname
14       tput -S  <<
15       tput -V
16

DESCRIPTION

18       The  tput utility uses the terminfo database to make the values of ter‐
19       minal-dependent capabilities and information  available  to  the  shell
20       (see  sh(1)),  to  initialize or reset the terminal, or return the long
21       name of the requested terminal type.  The result depends upon the capa‐
22       bility's type:
23
24          string
25               tput  writes  the  string  to the standard output.  No trailing
26               newline is supplied.
27
28          integer
29               tput writes the decimal value to the standard  output,  with  a
30               trailing newline.
31
32          boolean
33               tput  simply sets the exit code (0 for TRUE if the terminal has
34               the capability, 1 for FALSE if it does not), and writes nothing
35               to the standard output.
36
37       Before  using  a value returned on the standard output, the application
38       should test the exit code (e.g., $?, see sh(1)) to be  sure  it  is  0.
39       (See  the EXIT CODES and DIAGNOSTICS sections.)  For a complete list of
40       capabilities and the capname associated with each, see terminfo(5).
41
42   Options
43       -S     allows more than one capability per  invocation  of  tput.   The
44              capabilities  must  be  passed  to  tput from the standard input
45              instead of from the command line (see example).  Only  one  cap‐
46              name  is allowed per line.  The -S option changes the meaning of
47              the 0 and 1 boolean and string exit codes (see  the  EXIT  CODES
48              section).
49
50              Because  some capabilities may use string parameters rather than
51              numbers, tput uses a table and the presence of parameters in its
52              input  to  decide whether to use tparm(3X), and how to interpret
53              the parameters.
54
55       -Ttype indicates the type of terminal.  Normally this option is  unnec‐
56              essary,  because the default is taken from the environment vari‐
57              able TERM.  If -T is specified, then the shell  variables  LINES
58              and COLUMNS will also be ignored.
59
60       -V     reports  the  version of ncurses which was used in this program,
61              and exits.
62
63       -x     do not attempt to clear the terminal's scrollback  buffer  using
64              the extended “E3” capability.
65
66   Commands
67       A few commands (init, reset and longname) are special; they are defined
68       by the tput program.  The others are the names of capabilities from the
69       terminal  database  (see  terminfo(5)  for  a list).  Although init and
70       reset resemble capability names, tput uses several capabilities to per‐
71       form these special functions.
72
73       capname
74              indicates the capability from the terminal database.
75
76              If  the  capability is a string that takes parameters, the argu‐
77              ments following the capability will be used  as  parameters  for
78              the string.
79
80              Most  parameters  are numbers.  Only a few terminal capabilities
81              require string parameters; tput uses a table to decide which  to
82              pass  as  strings.   Normally tput uses tparm(3X) to perform the
83              substitution.  If no parameters are given  for  the  capability,
84              tput writes the string without performing the substitution.
85
86       init   If  the terminal database is present and an entry for the user's
87              terminal exists (see -Ttype, above), the following will occur:
88
89              (1)  first, tput retrieves the current  terminal  mode  settings
90                   for your terminal.  It does this by successively testing
91
92                   ·   the standard error,
93
94                   ·   standard output,
95
96                   ·   standard input and
97
98                   ·   ultimately “/dev/tty”
99
100                   to  obtain  terminal settings.  Having retrieved these set‐
101                   tings, tput remembers which file  descriptor  to  use  when
102                   updating settings.
103
104              (2)  if  the  window  size cannot be obtained from the operating
105                   system, but the terminal description (or environment, e.g.,
106                   LINES and COLUMNS variables specify this), update the oper‐
107                   ating system's notion of the window size.
108
109              (3)  the terminal modes will be updated:
110
111                   ·   any delays (e.g., newline) specified in the entry  will
112                       be set in the tty driver,
113
114                   ·   tabs  expansion  will  be turned on or off according to
115                       the specification in the entry, and
116
117                   ·   if tabs are not expanded, standard  tabs  will  be  set
118                       (every 8 spaces).
119
120              (4)  if  present,  the terminal's initialization strings will be
121                   output as detailed in the terminfo(5) section on  Tabs  and
122                   Initialization,
123
124              (5)  output is flushed.
125
126              If  an  entry does not contain the information needed for any of
127              these activities, that activity will silently be skipped.
128
129       reset  This is similar to init, with two differences:
130
131              (1)  before any other initialization, the terminal modes will be
132                   reset to a “sane” state:
133
134                   ·   set cooked and echo modes,
135
136                   ·   turn off cbreak and raw modes,
137
138                   ·   turn on newline translation and
139
140                   ·   reset  any  unset  special  characters to their default
141                       values
142
143              (2)  Instead of putting out initialization strings,  the  termi‐
144                   nal's  reset  strings  will be output if present (rs1, rs2,
145                   rs3, rf).  If the reset strings are not present,  but  ini‐
146                   tialization strings are, the initialization strings will be
147                   output.
148
149              Otherwise, reset acts identically to init.
150
151       longname
152              If the terminal database is present and an entry for the  user's
153              terminal  exists  (see  -Ttype above), then the long name of the
154              terminal will be put out.  The long name is the last name in the
155              first  line  of the terminal's description in the terminfo data‐
156              base [see term(5)].
157
158   Aliases
159       tput handles the clear, init and reset commands  specially:  it  allows
160       for the possibility that it is invoked by a link with those names.
161
162       If  tput  is invoked by a link named reset, this has the same effect as
163       tput reset.  The tset(1) utility also treats a link  named  reset  spe‐
164       cially.
165
166       Before ncurses 6.1, the two utilities were different from each other:
167
168       ·   tset  utility  reset the terminal modes and special characters (not
169           done with tput).
170
171       ·   On the other hand, tset's repertoire of terminal  capabilities  for
172           resetting  the terminal was more limited, i.e., only reset_1string,
173           reset_2string and reset_file in contrast to the tab-stops and  mar‐
174           gins which are set by this utility.
175
176       ·   The  reset  program  is  usually an alias for tset, because of this
177           difference with resetting terminal modes and special characters.
178
179       With the changes made for ncurses 6.1, the reset  feature  of  the  two
180       programs is (mostly) the same.  A few differences remain:
181
182       ·   The  tset  program waits one second when resetting, in case it hap‐
183           pens to be a hardware terminal.
184
185       ·   The two programs write the terminal initialization strings to  dif‐
186           ferent streams (i.e.,. the standard error for tset and the standard
187           output for tput).
188
189           Note: although these programs write to different streams, redirect‐
190           ing their output to a file will capture only part of their actions.
191           The changes to the terminal modes are not affected  by  redirecting
192           the output.
193
194       If  tput  is  invoked by a link named init, this has the same effect as
195       tput init.  Again, you are less likely to use that link because another
196       program named init has a more well-established use.
197

EXAMPLES

199       tput init
200            Initialize  the  terminal according to the type of terminal in the
201            environmental variable TERM.  This command should be  included  in
202            everyone's .profile after the environmental variable TERM has been
203            exported, as illustrated on the profile(5) manual page.
204
205       tput -T5620 reset
206            Reset an AT&T 5620 terminal, overriding the type  of  terminal  in
207            the environmental variable TERM.
208
209       tput cup 0 0
210            Send the sequence to move the cursor to row 0, column 0 (the upper
211            left corner of the screen, usually  known  as  the  “home”  cursor
212            position).
213
214       tput clear
215            Echo the clear-screen sequence for the current terminal.
216
217       tput cols
218            Print the number of columns for the current terminal.
219
220       tput -T450 cols
221            Print the number of columns for the 450 terminal.
222
223       bold=`tput smso` offbold=`tput rmso`
224            Set  the  shell  variables bold, to begin stand-out mode sequence,
225            and offbold, to end standout mode sequence, for the current termi‐
226            nal.  This might be followed by a prompt: echo "${bold}Please type
227            in your name: ${offbold}\c"
228
229       tput hc
230            Set exit code to indicate if the current terminal is a  hard  copy
231            terminal.
232
233       tput cup 23 4
234            Send the sequence to move the cursor to row 23, column 4.
235
236       tput cup
237            Send  the  terminfo string for cursor-movement, with no parameters
238            substituted.
239
240       tput longname
241            Print the long name from the terminfo database  for  the  type  of
242            terminal specified in the environmental variable TERM.
243
244            tput -S <<!
245            > clear
246            > cup 10 10
247            > bold
248            > !
249
250            This  example  shows  tput  processing several capabilities in one
251            invocation.  It clears the screen, moves the  cursor  to  position
252            10,  10 and turns on bold (extra bright) mode.  The list is termi‐
253            nated by an exclamation mark (!) on a line by itself.
254

FILES

256       /usr/share/terminfo
257              compiled terminal description database
258
259       /usr/share/tabset/*
260              tab settings for some terminals, in a format appropriate  to  be
261              output  to  the  terminal (escape sequences that set margins and
262              tabs); for more information, see the  Tabs  and  Initialization,
263              section of terminfo(5)
264

EXIT CODES

266       If the -S option is used, tput checks for errors from each line, and if
267       any errors are found, will set the exit code to 4 plus  the  number  of
268       lines  with  errors.   If  no errors are found, the exit code is 0.  No
269       indication of which line failed can be given so exit code 1 will  never
270       appear.   Exit codes 2, 3, and 4 retain their usual interpretation.  If
271       the -S option is not used, the exit code depends on the  type  of  cap‐
272       name:
273
274          boolean
275                 a value of 0 is set for TRUE and 1 for FALSE.
276
277          string a value of 0 is set if the capname is defined for this termi‐
278                 nal type (the value of capname is returned on  standard  out‐
279                 put);  a value of 1 is set if capname is not defined for this
280                 terminal type (nothing is written to standard output).
281
282          integer
283                 a value of 0 is always set, whether or not capname is defined
284                 for  this  terminal type.  To determine if capname is defined
285                 for this terminal type, the user must test the value  written
286                 to  standard output.  A value of -1 means that capname is not
287                 defined for this terminal type.
288
289          other  reset or init may fail to find their  respective  files.   In
290                 that case, the exit code is set to 4 + errno.
291
292       Any other exit code indicates an error; see the DIAGNOSTICS section.
293

DIAGNOSTICS

295       tput  prints  the  following  error messages and sets the corresponding
296       exit codes.
297
298       exit code   error message
299       ─────────────────────────────────────────────────────────────────────
300       0           (capname is a numeric variable that is not specified  in
301                   the  terminfo(5)  database  for this terminal type, e.g.
302                   tput -T450 lines and tput -T2621 xmc)
303       1           no error message is printed, see the EXIT CODES section.
304       2           usage error
305       3           unknown terminal type or no terminfo database
306       4           unknown terminfo capability capname
307       >4          error occurred in -S
308       ─────────────────────────────────────────────────────────────────────
309

HISTORY

311       The tput command was begun by Bill Joy in 1980.   The  initial  version
312       only cleared the screen.
313
314       AT&T  System  V provided a different tput command, whose init and reset
315       subcommands (more than half the program)  were  incorporated  from  the
316       reset feature of BSD tset written by Eric Allman.
317
318       Keith Bostic replaced the BSD tput command in 1989 with a new implemen‐
319       tation based on the AT&T System V program tput.  Like the AT&T program,
320       Bostic's  version accepted some parameters named for terminfo capabili‐
321       ties (clear, init, longname and reset).  However (because he  had  only
322       termcap  available),  it accepted termcap names for other capabilities.
323       Also, Bostic's BSD tput did not modify the terminal I/O  modes  as  the
324       earlier BSD tset had done.
325
326       At the same time, Bostic added a shell script named “clear”, which used
327       tput to clear the screen.
328
329       Both of these appeared in 4.4BSD, becoming the “modern” BSD implementa‐
330       tion of tput.
331
332       This  implementation of tput began from a different source than AT&T or
333       BSD: Ross Ridge's mytinfo package, published  on  comp.sources.unix  in
334       December 1992.  Ridge's program made more sophisticated use of the ter‐
335       minal capabilities than the BSD program.  Eric Raymond  used  the  tput
336       program  (and  other  parts of mytinfo) in ncurses in June 1995.  Using
337       the portions dealing with terminal capabilities almost without  change,
338       Raymond  made  improvements to the way the command-line parameters were
339       handled.
340

PORTABILITY

342       This implementation of tput differs from AT&T  tput  in  two  important
343       areas:
344
345       ·   tput  capname  writes  to  the standard output.  That need not be a
346           regular terminal.  However, the subcommands which manipulate termi‐
347           nal modes may not use the standard output.
348
349           The  AT&T  implementation's  init  and  reset  commands use the BSD
350           (4.1c) tset source, which manipulates terminal modes.   It  succes‐
351           sively tries standard output, standard error, standard input before
352           falling back to “/dev/tty” and finally just assumes a 1200Bd termi‐
353           nal.  When updating terminal modes, it ignores errors.
354
355           Until  changes made after ncurses 6.0, tput did not modify terminal
356           modes.  tput now uses a similar scheme, using functions shared with
357           tset  (and ultimately based on the 4.4BSD tset).  If it is not able
358           to open a terminal, e.g., when running in cron, tput will return an
359           error.
360
361       ·   AT&T tput guesses the type of its capname operands by seeing if all
362           of the characters are numeric, or not.
363
364           Most implementations which provide support for capname operands use
365           the  tparm  function  to  expand  parameters  in it.  That function
366           expects a mixture of numeric and string parameters, requiring  tput
367           to know which type to use.
368
369           This  implementation  uses a table to determine the parameter types
370           for the standard capname operands, and an internal library function
371           to analyze nonstandard capname operands.
372
373       This  implementation  (unlike  others) can accept both termcap and ter‐
374       minfo names for the capname feature, if termcap support is compiled in.
375       However, the predefined termcap and terminfo names have two ambiguities
376       in this case (and the terminfo name is assumed):
377
378       ·   The termcap name dl corresponds to the terminfo  name  dl1  (delete
379           one line).
380           The  terminfo  name dl corresponds to the termcap name DL (delete a
381           given number of lines).
382
383       ·   The termcap name ed corresponds to  the  terminfo  name  rmdc  (end
384           delete mode).
385           The  terminfo  name ed corresponds to the termcap name cd (clear to
386           end of screen).
387
388       The longname and -S options, and  the  parameter-substitution  features
389       used  in  the  cup  example,  were  not  supported in BSD curses before
390       4.3reno (1989) or in AT&T/USL curses before SVr4 (1988).
391
392       IEEE  Std  1003.1/The  Open  Group    Base   Specifications   Issue   7
393       (POSIX.1-2008)  documents  only the operands for clear, init and reset.
394       There are a few interesting observations to make regarding that:
395
396       ·   In this implementation, clear is part of the capname support.   The
397           others  (init and longname) do not correspond to terminal capabili‐
398           ties.
399
400       ·   Other  implementations  of  tput  on  SVr4-based  systems  such  as
401           Solaris,  IRIX64  and  HPUX as well as others such as AIX and Tru64
402           provide support for capname operands.
403
404       ·   A few platforms such as FreeBSD recognize termcap names rather than
405           terminfo capability names in their respective tput commands.  Since
406           2010, NetBSD's tput uses terminfo names.   Before  that,  it  (like
407           FreeBSD) recognized termcap names.
408
409       Because (apparently) all of the certified Unix systems support the full
410       set of capability names, the reasoning for documenting only a  few  may
411       not be apparent.
412
413       ·   X/Open  Curses Issue 7 documents tput differently, with capname and
414           the other features used in this implementation.
415
416       ·   That is, there are two standards for tput:  POSIX  (a  subset)  and
417           X/Open  Curses (the full implementation).  POSIX documents a subset
418           to avoid the complication of including X/Open Curses and the termi‐
419           nal capabilities database.
420
421       ·   While  it  is  certainly  possible  to write a tput program without
422           using curses, none of the systems which have a  curses  implementa‐
423           tion provide a tput utility which does not provide the capname fea‐
424           ture.
425

SEE ALSO

427       clear(1), stty(1), tabs(1), tset(1), terminfo(5), curs_termcap(3X).
428
429       This describes ncurses version 6.1 (patch 20180224).
430
431
432
433                                                                       tput(1)
Impressum