http://invisible-island.net/ncurses/man/


tput 1

tput(1)                                                         tput(1)




NAME

       tput,  reset  -  initialize  a  terminal or query terminfo
       database


SYNOPSIS

       tput [-Ttype] capname [parameters]
       tput [-Ttype] init
       tput [-Ttype] reset
       tput [-Ttype] longname
       tput -S  <<
       tput -V


DESCRIPTION

       The tput utility uses the terminfo database  to  make  the
       values  of terminal-dependent capabilities and information
       available to the shell (see sh(1)), to initialize or reset
       the  terminal,  or  return  the long name of the requested
       terminal type.  The result depends upon  the  capability's
       type:

          string
               tput writes the string to the standard output.  No
               trailing newline is supplied.

          integer
               tput writes the decimal value to the standard out-
               put, with a trailing newline.

          boolean
               tput  simply sets the exit code (0 for TRUE if the
               terminal has the capability, 1  for  FALSE  if  it
               does not), and writes nothing to the standard out-
               put.

       Before using a value returned on the standard output,  the
       application  should  test  the  exit  code  (e.g., $?, see
       sh(1)) to be sure it is 0.  (See the EXIT CODES and  DIAG-
       NOSTICS  sections.)   For  a complete list of capabilities
       and the capname associated with each, see terminfo(5).


Options

       -Ttype indicates the  type  of  terminal.   Normally  this
              option is unnecessary, because the default is taken
              from the environment variable TERM.  If -T is spec-
              ified,  then  the shell variables LINES and COLUMNS
              will also be ignored.

       -S     allows more than one capability per  invocation  of
              tput.  The capabilities must be passed to tput from
              the standard input instead of from the command line
              (see  example).   Only  one  capname is allowed per
              line.  The -S option changes the meaning of  the  0
              and  1  boolean and string exit codes (see the EXIT
              CODES section).

              Again, tput uses a table and the presence of param-
              eters  in  its  input  to  decide  whether  to  use
              tparm(3x), and how to interpret the parameters.

       -V     reports the version of ncurses which  was  used  in
              this program, and exits.


Commands

       capname
              indicates  the  capability  from the terminfo data-
              base.  When termcap support  is  compiled  in,  the
              termcap name for the capability is also accepted.

              If  the  capability  is a string that takes parame-
              ters, the arguments following the  capability  will
              be used as parameters for the string.

              Most  parameters  are numbers.  Only a few terminfo
              capabilities require string parameters; tput uses a
              table to decide which to pass as strings.  Normally
              tput uses tparm(3x) to  perform  the  substitution.
              If no parameters are given for the capability, tput
              writes the string without performing the  substitu-
              tion.

       init   If  the  terminfo  database is present and an entry
              for the user's terminal exists (see -Ttype, above),
              the following will occur:

              (1)  if   present,  the  terminal's  initialization
                   strings will be output as detailed in the ter-
                   minfo(5) section on Tabs and Initialization,

              (2)  any  delays  (e.g.,  newline) specified in the
                   entry will be set in the tty driver,

              (3)  tabs  expansion  will  be  turned  on  or  off
                   according  to  the specification in the entry,
                   and

              (4)  if tabs are not expanded, standard  tabs  will
                   be set (every 8 spaces).

              If an entry does not contain the information needed
              for any of these  activities,  that  activity  will
              silently be skipped.

       reset  Instead  of putting out initialization strings, the
              terminal's reset strings will be output if  present
              (rs1,  rs2, rs3, rf).  If the reset strings are not
              present, but initialization strings are,  the  ini-
              tialization  strings  will  be  output.  Otherwise,
              reset acts identically to init.

       longname
              If the terminfo database is present  and  an  entry
              for  the user's terminal exists (see -Ttype 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 terminfo database
              [see term(5)].


Aliases

       tput  handles  the  init  and reset commands specially: it
       allows for the possibility that it is invoked  by  a  link
       with those names.

       If  tput  is  invoked  by a link named reset, this has the
       same effect as  tput  reset.   The  tset(1)  utility  also
       treats a link named reset specially:

       o   That  utility  resets  the  terminal modes and special
           characters (not done here).

       o   On the other hand, tset's repertoire of terminal capa-
           bilities  for  resetting the terminal is more limited,
           i.e., only reset_1string, reset_2string and reset_file
           in contrast to the tab-stops and margins which are set
           by this utility.

       o   The reset program is usually an alias for tset, due to
           the  resetting  of  terminal modes and special charac-
           ters.

       If tput is invoked by a link named init, this has the same
       effect  as  tput  init.  Again, you are less likely to use
       that link because another program named init  has  a  more
       well-established use.


EXAMPLES

       tput init
            Initialize the terminal according to the type of ter-
            minal in the environmental variable TERM.  This  com-
            mand  should be included in everyone's .profile after
            the environmental variable TERM has been exported, as
            illustrated on the profile(5) manual page.

       tput -T5620 reset
            Reset  an  AT&T 5620 terminal, overriding the type of
            terminal in the environmental variable TERM.

       tput cup 0 0
            Send the sequence to move the cursor to row 0, column
            0 (the upper left corner of the screen, usually known
            as the "home" cursor position).

       tput clear
            Echo the clear-screen sequence for the current termi-
            nal.

       tput cols
            Print the number of columns for the current terminal.

       tput -T450 cols
            Print the number of columns for the 450 terminal.

       bold=`tput smso` offbold=`tput rmso`
            Set the shell variables bold, to begin stand-out mode
            sequence, and offbold, to end standout mode sequence,
            for  the current terminal.  This might be followed by
            a prompt: echo  "${bold}Please  type  in  your  name:
            ${offbold}\c"

       tput hc
            Set  exit code to indicate if the current terminal is
            a hard copy terminal.

       tput cup 23 4
            Send the sequence to move the cursor to row 23,  col-
            umn 4.

       tput cup
            Send the terminfo string for cursor-movement, with no
            parameters substituted.

       tput longname
            Print the long name from the  terminfo  database  for
            the  type  of terminal specified in the environmental
            variable TERM.

            tput -S <<!
            > clear
            > cup 10 10
            > bold
            > !

            This example shows tput processing several  capabili-
            ties  in one invocation.  It clears the screen, moves
            the cursor to position  10,  10  and  turns  on  bold
            (extra  bright)  mode.   The list is terminated by an
            exclamation mark (!) on a line by itself.


FILES

       /usr/share/terminfo
              compiled terminal description database

       /usr/share/tabset/*
              tab settings for some terminals, in a format appro-
              priate   to  be  output  to  the  terminal  (escape
              sequences that set  margins  and  tabs);  for  more
              information, see the "Tabs and Initialization" sec-
              tion of terminfo(5)


EXIT CODES

       If the -S option is used, tput 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 0.  No indication of which
       line failed can be given so exit code 1 will never appear.
       Exit  codes 2, 3, and 4 retain their usual interpretation.
       If the -S option is not used, the exit code depends on the
       type of capname:

          boolean
                 a value of 0 is set for TRUE and 1 for FALSE.

          string a  value  of  0 is set if the capname is defined
                 for this terminal type (the value of capname  is
                 returned  on  standard  output); a value of 1 is
                 set if capname is not defined for this  terminal
                 type (nothing is written to standard output).

          integer
                 a  value of 0 is always set, whether or not cap-
                 name is defined  for  this  terminal  type.   To
                 determine  if capname is defined for this termi-
                 nal type, the user must test the  value  written
                 to  standard  output.   A value of -1 means that
                 capname is not defined for this terminal type.

          other  reset or init may fail to find their  respective
                 files.   In that case, the exit code is set to 4
                 + errno.

       Any other exit code indicates an error; see  the  DIAGNOS-
       TICS section.


DIAGNOSTICS

       tput prints the following error messages and sets the cor-
       responding exit codes.

       exit code   error message
       ---------------------------------------------------------------------
       0           (capname is a numeric variable that is not specified  in
                   the  terminfo(5)  database  for this terminal type, e.g.
                   tput -T450 lines and tput -T2621 xmc)
       1           no error message is printed, see the EXIT CODES section.
       2           usage error
       3           unknown terminal type or no terminfo database
       4           unknown terminfo capability capname
       >4          error occurred in -S
       ---------------------------------------------------------------------


PORTABILITY

       The longname and -S options, and  the  parameter-substitu-
       tion  features  used in the cup example, are not supported
       in BSD curses or in AT&T/USL curses before SVr4.

       IEEE Std 1003.1/The Open Group  Base Specifications  Issue
       7  (POSIX.1-2008)  documents  only the operands for clear,
       init and reset.  There are a few interesting  observations
       to make regarding that:

       o   In  this  implementation, clear is part of the capname
           support.  The others (init and longname) do not corre-
           spond to terminal capabilities.

       o   Other  implementations  of  tput on SVr4-based systems
           such as Solaris, IRIX64 and HPUX  as  well  as  others
           such  as AIX and Tru64 provide support for capname op-
           erands.

       o   A few platforms  such  as  FreeBSD  recognize  termcap
           names  rather  than terminfo capability names in their
           respective tput commands.  Since 2010,  NetBSD's  tput
           uses  terminfo  names.  Before that, it (like FreeBSD)
           recognized termcap names.

       Because (apparently) all of  the  certified  Unix  systems
       support  the  full  set of capability names, the reasoning
       for documenting only a few may not be apparent.

       o   X/Open Curses Issue 7 documents tput differently, with
           capname  and the other features used in this implemen-
           tation.

       o   That is, there are two standards for  tput:  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 terminal capabilities
           database.

       o   While it is certainly possible to write a tput program
           without using curses, none of the systems which have a
           curses implementation provide  a  tput  utility  which
           does not provide the capname feature.

       Most implementations which provide support for capname op-
       erands use the tparm function to expand parameters in  it.
       That  function  expects  a  mixture  of numeric and string
       parameters, requiring tput to  know  which  type  to  use.
       This implementation uses a table to determine that for the
       standard capname operands, and an internal  library  func-
       tion  to  analyze  nonstandard  capname  operands.   Other
       implementations may simply guess that an operand  contain-
       ing only digits is intended to be a number.


SEE ALSO

       clear(1),    stty(1),   tabs(1),   tset(1),   terminfo(5),
       curs_termcap(3x).

       This describes ncurses version 6.0 (patch 20160611).



                                                                tput(1)