usr.bin/tput/tput.1

   1 .\" Copyright (c) 1989, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)tput.1      8.2 (Berkeley) 3/19/94
  29 .\" $FreeBSD: src/usr.bin/tput/tput.1,v 1.5.2.3 2001/08/16 13:17:08 ru Exp $
  30 .\"
  31 .Dd March 19, 1994
  32 .Dt TPUT 1
  33 .Os
  34 .Sh NAME
  35 .Nm tput ,
  36 .Nm clear
  37 .Nd terminal capability interface
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl T Ar term
  41 .Ar attribute
  42 .Nm clear
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 command makes terminal-dependent information available to users or shell
  47 applications.  When invoked as the
  48 .Nm clear
  49 utility, the screen will be cleared as if
  50 .Dl tput clear
  51 had been executed.
  52 The options to
  53 .Nm
  54 are as follows:
  55 .Bl -tag -width Ds
  56 .It Fl T
  57 The terminal name as specified in the
  58 .Xr termcap 5
  59 database, for example,
  60 .Dq vt100
  61 or
  62 .Dq xterm .
  63 If not specified,
  64 .Nm
  65 retrieves the
  66 .Dq Ev TERM
  67 variable from the environment.
  68 .El
  69 .Pp
  70 The
  71 .Nm
  72 command outputs a string if the
  73 .Ar attribute
  74 is of type string; a number if it is of type integer.
  75 Otherwise,
  76 .Nm
  77 exits 0 if the terminal has the capability and 1 if it does not,
  78 without further action.
  79 .Pp
  80 If the
  81 .Ar attribute
  82 is of type string, and takes arguments (e.g. cursor movement,
  83 the termcap
  84 .Dq cm
  85 sequence) the arguments are taken from the command line immediately
  86 following the attribute.
  87 .Pp
  88 The following special attributes are available:
  89 .Bl -tag -width Ar
  90 .It clear
  91 Clear the screen (the
  92 .Xr termcap 5
  93 .Dq cl
  94 sequence).
  95 .It init
  96 Initialize the terminal (the
  97 .Xr termcap 5
  98 .Dq is
  99 sequence).
 100 .It longname
 101 Print the descriptive name of the user's terminal type.
 102 .It reset
 103 Reset the terminal (the
 104 .Xr termcap 5
 105 .Dq rs
 106 sequence).
 107 .El
 108 .Sh EXIT STATUS
 109 The exit value of
 110 .Nm
 111 is based on the last attribute specified.
 112 If the attribute is of type string or of type integer,
 113 .Nm
 114 exits 0 if the attribute is defined for this terminal type and 1
 115 if it is not.
 116 If the attribute is of type boolean,
 117 .Nm
 118 exits 0 if the terminal has this attribute, and 1 if it does not.
 119 The
 120 .Nm
 121 command exits 2 if any error occurred.
 122 .Sh SEE ALSO
 123 .Xr termcap 5 ,
 124 .Xr terminfo 5
 125 .Sh HISTORY
 126 The
 127 .Nm
 128 command appeared in
 129 .Bx 4.4 .
 130 .Sh BUGS
 131 The
 132 .Nm
 133 command can't really distinguish between different types of attributes.
 134 .Pp
 135 Some termcap entries depend upon having a
 136 .Sq %
 137 in them that is just a
 138 .Sq %
 139 and nothing more.  Right now we just warn about them if they don't
 140 have a valid type declaration.  These warnings are sent to
 141 stderr.