Blame - doc/html/man/tput.1.html - android_external_libncurses

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

2

<!--

3

* t

4

****************************************************************************

5

6

* *

7

* Permission is hereby granted, free of charge, to any person obtaining a *

8

* copy of this software and associated documentation files (the *

9

* "Software"), to deal in the Software without restriction, including *

10

* without limitation the rights to use, copy, modify, merge, publish, *

11

* distribute, distribute with modifications, sublicense, and/or sell *

12

* copies of the Software, and to permit persons to whom the Software is *

13

* furnished to do so, subject to the following conditions: *

14

* *

15

* The above copyright notice and this permission notice shall be included *

16

* in all copies or substantial portions of the Software. *

17

* *

18

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

19

* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

20

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

21

* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

22

* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

23

* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

24

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

25

* *

26

* Except as contained in this notice, the name(s) of the above copyright *

27

* holders shall not be used in advertising or otherwise to promote the *

28

* sale, use or other dealings in this Software without prior written *

29

* authorization. *

30

****************************************************************************

31

* @Id: tput.1,v 1.27 2006/12/24 18:11:31 tom Exp @

-->

<HTML>

<HEAD>

</HEAD>

<BODY>

<HR>

<PRE>

</PRE>

tput, reset - initialize a terminal or query terminfo

database

</PRE>

<H2>SYNOPSIS</H2><PRE>

57

tput [-Ttype] capname [parms ... ]

58

tput [-Ttype] init

59

tput [-Ttype] reset

60

tput [-Ttype] longname

tput -S <<

tput -V

</PRE>

<H2>DESCRIPTION</H2><PRE>

67

The tput utility uses the terminfo database to make the

68

values of terminal-dependent capabilities and information

69

available to the shell (see <A HREF="sh.1.html">sh(1)</A>), to initialize or reset

70

the terminal, or return the long name of the requested

71

terminal type. The result depends upon the capability's

type:

string

tput writes the string to the standard output.

76

No trailing newline is supplied.

77

78

integer

79

tput writes the decimal value to the standard

80

output, with a trailing newline.

81

82

boolean

83

tput simply sets the exit code (0 for TRUE if

84

the terminal has the capability, 1 for FALSE

85

if it does not), and writes nothing to the

86

standard output.

87

88

Before using a value returned on the standard output, the

89

application should test the exit code (e.g., $?, see

90

<A HREF="sh.1.html">sh(1)</A>) to be sure it is 0. (See the EXIT CODES and DIAG-

91

NOSTICS sections.) For a complete list of capabilities

92

and the capname associated with each, see <A HREF="terminfo.5.html">terminfo(5)</A>.

93

94

-Ttype indicates the type of terminal. Normally this

95

option is unnecessary, because the default is taken

96

from the environment variable TERM. If -T is spec-

97

ified, then the shell variables LINES and COLUMNS

98

will be ignored,and the operating system will not

99

be queried for the actual screen size.

100

101

capname

102

indicates the capability from the terminfo

103

database. When termcap support is compiled in, the

104

termcap name for the capability is also accepted.

105

106

parms If the capability is a string that takes parame-

107

ters, the arguments parms will be instantiated into

108

the string.

109

110

Most parameters are numbers. Only a few terminfo

111

capabilities require string parameters; tput uses a

112

table to decide which to pass as strings. Normally

113

tput uses tparm (3x) to perform the substitution.

114

If no parameters are given for the capability, tput

115

writes the string without performing the

116

substitution.

117

118

-S allows more than one capability per invocation of

119

tput. The capabilities must be passed to tput from

120

the standard input instead of from the command line

121

(see example). Only one capname is allowed per

122

line. The -S option changes the meaning of the 0

123

and 1 boolean and string exit codes (see the EXIT

124

CODES section).

125

126

Again, tput uses a table and the presence of param-

127

eters in its input to decide whether to use tparm

128

(3x), and how to interpret the parameters.

129

130

-V reports the version of ncurses which was used in

131

this program, and exits.

132

133

init If the terminfo database is present and an entry

134

for the user's terminal exists (see -Ttype, above),

135

the following will occur:

136

137

(1) if present, the terminal's initialization

138

strings will be output as detailed in the

139

<A HREF="terminfo.5.html">terminfo(5)</A> section on Tabs and Initializa-

140

tion,

141

142

(2) any delays (e.g., newline) specified in the

143

entry will be set in the tty driver,

144

145

(3) tabs expansion will be turned on or off

146

according to the specification in the entry,

147

and

148

149

(4) if tabs are not expanded, standard tabs will

150

be set (every 8 spaces).

151

152

If an entry does not contain the information needed

153

for any of the four above activities, that activity

154

will silently be skipped.

155

156

reset Instead of putting out initialization strings, the

157

terminal's reset strings will be output if present

158

(rs1, rs2, rs3, rf). If the reset strings are not

159

present, but initialization strings are, the ini-

160

tialization strings will be output. Otherwise,

161

reset acts identically to init.

162

163

longname

164

If the terminfo database is present and an entry

165

for the user's terminal exists (see -Ttype above),

166

then the long name of the terminal will be put out.

167

The long name is the last name in the first line of

168

the terminal's description in the terminfo database

169

[see <A HREF="term.5.html">term(5)</A>].

170

171

If tput is invoked by a link named reset, this has the

172

same effect as tput reset. See tset for comparison, which

173

has similar behavior.

</PRE>

<H2>EXAMPLES</H2><PRE>

178

tput init

179

Initialize the terminal according to the type of ter-

180

minal in the environmental variable TERM. This com-

181

mand should be included in everyone's .profile after

182

the environmental variable TERM has been exported, as

183

illustrated on the <A HREF="profile.5.html">profile(5)</A> manual page.

184

185

tput -T5620 reset

186

Reset an AT&T 5620 terminal, overriding the type of

187

terminal in the environmental variable TERM.

188

189

tput cup 0 0

190

Send the sequence to move the cursor to row 0, column

191

0 (the upper left corner of the screen, usually known

192

as the "home" cursor position).

193

194

tput clear

195

Echo the clear-screen sequence for the current termi-

nal.

tput cols

Print the number of columns for the current terminal.

200

201

tput -T450 cols

202

Print the number of columns for the 450 terminal.

203

204

bold=`tput smso` offbold=`tput rmso`

205

Set the shell variables bold, to begin stand-out mode

206

sequence, and offbold, to end standout mode sequence,

207

for the current terminal. This might be followed by

208

a prompt: echo "${bold}Please type in your name:

${offbold}\c"

tput hc

Set exit code to indicate if the current terminal is

213

a hard copy terminal.

214

215

tput cup 23 4

216

Send the sequence to move the cursor to row 23, col-

umn 4.

tput cup

Send the terminfo string for cursor-movement, with no

221

parameters substituted.

222

223

tput longname

224

Print the long name from the terminfo database for

225

the type of terminal specified in the environmental

variable TERM.

tput -S <<!

> clear

> cup 10 10

> bold

> !

This example shows tput processing several capabili-

235

ties in one invocation. It clears the screen, moves

236

the cursor to position 10, 10 and turns on bold

237

(extra bright) mode. The list is terminated by an

238

exclamation mark (!) on a line by itself.

</PRE>

<H2>FILES</H2><PRE>

/usr/share/terminfo

compiled terminal description database

245

246

/usr/share/tabset/*

247

tab settings for some terminals, in a format appro-

248

priate to be output to the terminal (escape

249

sequences that set margins and tabs); for more

250

information, see the "Tabs and Initialization" sec-

251

tion of <A HREF="terminfo.5.html">terminfo(5)</A>

</PRE>

<H2>EXIT CODES</H2><PRE>

256

If the -S option is used, tput checks for errors from each

257

line, and if any errors are found, will set the exit code

258

to 4 plus the number of lines with errors. If no errors

259

are found, the exit code is 0. No indication of which

260

line failed can be given so exit code 1 will never appear.

261

Exit codes 2, 3, and 4 retain their usual interpretation.

262

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.

267

268

string a value of 0 is set if the capname is defined

269

for this terminal type (the value of capname

270

is returned on standard output); a value of 1

271

is set if capname is not defined for this ter-

272

minal type (nothing is written to standard

output).

integer

a value of 0 is always set, whether or not

277

capname is defined for this terminal type. To

278

determine if capname is defined for this ter-

279

minal type, the user must test the value writ-

280

ten to standard output. A value of -1 means

281

that capname is not defined for this terminal

282

type.

283

284

other reset or init may fail to find their respec-

285

tive files. In that case, the exit code is

286

set to 4 + errno.

287

288

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

TICS section.

</PRE>

<H2>DIAGNOSTICS</H2><PRE>

294

tput prints the following error messages and sets the cor-

295

responding exit codes.

296

297

298

exit code error message

299

---------------------------------------------------------------------

300

0 (capname is a numeric variable that is not specified in

301

the <A HREF="terminfo.5.html">terminfo(5)</A> 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

---------------------------------------------------------------------

</PRE>

<H2>PORTABILITY</H2><PRE>

313

The longname and -S options, and the parameter-substitu-

314

tion features used in the cup example, are not supported

315

in BSD curses or in AT&T/USL curses before SVr4.

316

317

X/Open documents only the operands for clear, init and

318

reset. In this implementation, clear is part of the cap-

319

name support. Other implementations of tput on SVr4-based

320

systems such as Solaris, IRIX64 and HPUX as well as others

321

such as AIX and Tru64 provide support for capname

322

operands. A few platforms such as FreeBSD and NetBSD rec-

323

ognize termcap names rather than terminfo capability names

324

in their respective tput commands.

</PRE>

<A HREF="clear.1.html">clear(1)</A>, <A HREF="stty.1.html">stty(1)</A>, <A HREF="tabs.1.html">tabs(1)</A>, <A HREF="terminfo.5.html">terminfo(5)</A>.

330

331

This describes ncurses version 5.6 (patch 20081011).

</PRE>

<HR>

Man(1) output converted with

</ADDRESS>

</BODY>

</HTML>