Annotation of src/usr.bin/tput/tput.1, Revision 1.22
1.22 ! jca 1: .\" $OpenBSD: tput.1,v 1.21 2014/06/03 20:28:24 jmc 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.22 ! jca 33: .Dd $Mdocdate: June 3 2014 $
1.1 deraadt 34: .Dt TPUT 1
1.6 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
1.22 ! jca 37: .Nm tput ,
! 38: .Nm clear
1.1 deraadt 39: .Nd terminal capability interface
40: .Sh SYNOPSIS
41: .Nm tput
42: .Op Fl T Ar term
43: .Ar attribute
44: .Op Ar attribute-args
45: .Ar ...
1.7 millert 46: .Nm tput
47: .Op Fl T Ar term
48: .Fl S
1.22 ! jca 49: .Nm clear
! 50: .Op Fl T Ar term
1.1 deraadt 51: .Sh DESCRIPTION
1.8 aaron 52: The
53: .Nm
54: utility makes terminal-dependent information available to users or shell
1.1 deraadt 55: applications.
1.22 ! jca 56: When invoked as
! 57: .Nm clear
! 58: it provides the same functionality as
! 59: .Nm tput Cm clear .
1.8 aaron 60: .Pp
1.1 deraadt 61: The options are as follows:
62: .Bl -tag -width Ds
1.14 jmc 63: .It Fl S
64: The attributes are read from stdin instead of the command line.
1.1 deraadt 65: .It Fl T
1.8 aaron 66: The terminal name as found in the
1.7 millert 67: .Xr terminfo
1.8 aaron 68: database; for example,
69: .Dq vt100
70: or
71: .Dq xterm .
1.1 deraadt 72: If not specified,
1.8 aaron 73: .Nm
1.1 deraadt 74: retrieves the
1.8 aaron 75: .Ev TERM
1.1 deraadt 76: variable from the environment.
77: .El
78: .Pp
1.8 aaron 79: .Nm
1.1 deraadt 80: outputs a string if the
81: .Ar attribute
1.8 aaron 82: is of type string or a number if it is of type integer.
1.7 millert 83: If the
84: .Ar attribute
85: is of type boolean,
1.8 aaron 86: .Nm
87: exits 0 if the terminal has the capability or 1 if it
1.10 aaron 88: does not.
89: Each
1.7 millert 90: .Ar attribute
91: should be a string defined in either
92: .Xr terminfo 5
93: or
94: .Xr termcap 5 .
1.1 deraadt 95: .Pp
96: If the
97: .Ar attribute
1.8 aaron 98: is of type string and takes arguments (e.g., cursor movement,
1.7 millert 99: the
100: .Xr terminfo
101: .Dq cup
1.1 deraadt 102: sequence) the arguments are taken from the command line immediately
103: following the attribute.
104: .Pp
105: The following special attributes are available:
106: .Bl -tag -width Ar
107: .It clear
108: Clear the screen (the
1.7 millert 109: .Xr terminfo
1.8 aaron 110: .Dq clear
111: sequence).
1.1 deraadt 112: .It init
1.7 millert 113: Print the
114: .Xr terminfo
115: initialization strings for the specified terminal.
1.1 deraadt 116: .It longname
117: Print the descriptive name of the user's terminal type.
118: .It reset
1.7 millert 119: Reset the terminal (using the
120: .Xr terminfo
121: reset sequences).
1.12 mpech 122: .El
1.21 jmc 123: .Sh ENVIRONMENT
124: .Bl -tag -width Ds
125: .It Ev TERM
126: Determine the terminal type.
127: .El
1.19 jmc 128: .Sh EXIT STATUS
1.1 deraadt 129: The exit value of
1.8 aaron 130: .Nm
1.1 deraadt 131: is based on the last attribute specified.
1.7 millert 132: If the attribute is of type string or of type integer the exit
133: value is as follows:
1.8 aaron 134: .Pp
1.7 millert 135: .Bl -tag -offset indent -width Ds -compact
136: .It 0
137: The requested string was written successfully.
138: .It 2
139: Usage error.
140: .It 3
141: Unknown terminal type.
142: .It 4
143: Unknown attribute name.
144: .It >4
145: An error occurred.
146: .El
147: .Pp
1.1 deraadt 148: If the attribute is of type boolean,
1.8 aaron 149: .Nm
150: exits with a value of 0 if the terminal has this attribute or
1.7 millert 151: 1 if it does not.
1.19 jmc 152: .Sh EXAMPLES
1.21 jmc 153: Clear the screen and go to line 5 column 10:
154: .Pp
155: .Dl $ tput clear cup 5 10
1.19 jmc 156: .Pp
1.21 jmc 157: Go to line 6 column 11 and delete 6 characters:
158: .Pp
159: .Dl $ tput cup 6 11 dch 6
1.1 deraadt 160: .Sh SEE ALSO
1.7 millert 161: .Xr terminfo 3 ,
162: .Xr terminfo 5
1.15 jmc 163: .Sh STANDARDS
164: The
165: .Nm
166: utility is compliant with the
1.17 jmc 167: .St -p1003.1-2008
1.18 jmc 168: specification.
1.15 jmc 169: .Pp
170: The flag
171: .Op Fl S
1.21 jmc 172: and the attribute
173: .Cm longname
174: are extensions to that specification.
1.1 deraadt 175: .Sh HISTORY
1.22 ! jca 176: The
1.20 schwarze 177: .Nm clear
1.22 ! jca 178: utility first appeared in
1.20 schwarze 179: .Bx 2 .
1.1 deraadt 180: The
181: .Nm
1.8 aaron 182: utility appeared in
1.1 deraadt 183: .Bx 4.4 .
1.9 aaron 184: .Sh BUGS
185: .Nm
186: can't really distinguish between different types of attributes.