Annotation of src/usr.bin/tput/tput.1, Revision 1.14
1.14 ! jmc 1: .\" $OpenBSD: tput.1,v 1.13 2003/06/03 02:56:20 millert Exp $
1.1 deraadt 2: .\" $NetBSD: tput.1,v 1.4 1994/12/07 08:49:10 jtc Exp $
3: .\"
4: .\" Copyright (c) 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.13 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)tput.1 8.2 (Berkeley) 3/19/94
32: .\"
1.7 millert 33: .Dd June 29, 1999
1.1 deraadt 34: .Dt TPUT 1
1.6 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm tput
38: .Nd terminal capability interface
39: .Sh SYNOPSIS
40: .Nm tput
41: .Op Fl T Ar term
42: .Ar attribute
43: .Op Ar attribute-args
44: .Ar ...
1.7 millert 45: .Nm tput
46: .Op Fl T Ar term
47: .Fl S
1.1 deraadt 48: .Sh DESCRIPTION
1.8 aaron 49: The
50: .Nm
51: utility makes terminal-dependent information available to users or shell
1.1 deraadt 52: applications.
1.8 aaron 53: .Pp
1.1 deraadt 54: The options are as follows:
55: .Bl -tag -width Ds
1.14 ! jmc 56: .It Fl S
! 57: The attributes are read from stdin instead of the command line.
1.1 deraadt 58: .It Fl T
1.8 aaron 59: The terminal name as found in the
1.7 millert 60: .Xr terminfo
1.8 aaron 61: database; for example,
62: .Dq vt100
63: or
64: .Dq xterm .
1.1 deraadt 65: If not specified,
1.8 aaron 66: .Nm
1.1 deraadt 67: retrieves the
1.8 aaron 68: .Ev TERM
1.1 deraadt 69: variable from the environment.
70: .El
71: .Pp
1.8 aaron 72: .Nm
1.1 deraadt 73: outputs a string if the
74: .Ar attribute
1.8 aaron 75: is of type string or a number if it is of type integer.
1.7 millert 76: If the
77: .Ar attribute
78: is of type boolean,
1.8 aaron 79: .Nm
80: exits 0 if the terminal has the capability or 1 if it
1.10 aaron 81: does not.
82: Each
1.7 millert 83: .Ar attribute
84: should be a string defined in either
85: .Xr terminfo 5
86: or
87: .Xr termcap 5 .
1.1 deraadt 88: .Pp
89: If the
90: .Ar attribute
1.8 aaron 91: is of type string and takes arguments (e.g., cursor movement,
1.7 millert 92: the
93: .Xr terminfo
94: .Dq cup
1.1 deraadt 95: sequence) the arguments are taken from the command line immediately
96: following the attribute.
97: .Pp
98: The following special attributes are available:
99: .Bl -tag -width Ar
100: .It clear
101: Clear the screen (the
1.7 millert 102: .Xr terminfo
1.8 aaron 103: .Dq clear
104: sequence).
1.1 deraadt 105: .It init
1.7 millert 106: Print the
107: .Xr terminfo
108: initialization strings for the specified terminal.
1.1 deraadt 109: .It longname
110: Print the descriptive name of the user's terminal type.
111: .It reset
1.7 millert 112: Reset the terminal (using the
113: .Xr terminfo
114: reset sequences).
1.12 mpech 115: .El
1.11 aaron 116: .Sh EXAMPLES
117: .Bl -tag -width "tput cup 6 11 dch 6" -compact
118: .It Li "tput clear cup 5 10"
119: clear the screen and goto line 5 column 10
120: .Pp
121: .It Li "tput cup 6 11 dch 6"
122: goto line 6 column 11 and delete 6 characters
123: .El
1.1 deraadt 124: .Sh DIAGNOSTICS
125: The exit value of
1.8 aaron 126: .Nm
1.1 deraadt 127: is based on the last attribute specified.
1.7 millert 128: If the attribute is of type string or of type integer the exit
129: value is as follows:
1.8 aaron 130: .Pp
1.7 millert 131: .Bl -tag -offset indent -width Ds -compact
132: .It 0
133: The requested string was written successfully.
134: .It 2
135: Usage error.
136: .It 3
137: Unknown terminal type.
138: .It 4
139: Unknown attribute name.
140: .It >4
141: An error occurred.
142: .El
143: .Pp
1.1 deraadt 144: If the attribute is of type boolean,
1.8 aaron 145: .Nm
146: exits with a value of 0 if the terminal has this attribute or
1.7 millert 147: 1 if it does not.
1.1 deraadt 148: .Sh SEE ALSO
1.7 millert 149: .Xr terminfo 3 ,
150: .Xr terminfo 5
1.1 deraadt 151: .Sh HISTORY
152: The
153: .Nm
1.8 aaron 154: utility appeared in
1.1 deraadt 155: .Bx 4.4 .
1.9 aaron 156: .Sh BUGS
157: .Nm
158: can't really distinguish between different types of attributes.