Blame - doc/html/man/curs_inopts.3x.html - android_external_libncurses

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

1

<!--

2

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

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

3

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

4

* *

5

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

6

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

7

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

8

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

9

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

10

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

11

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

12

* *

13

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

14

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

15

* *

16

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

17

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

18

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

19

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

20

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

21

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

22

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

23

* *

24

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

25

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

26

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

27

* authorization. *

28

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

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

29

* @Id: curs_inopts.3x,v 1.19 2015/04/11 10:21:38 tom Exp @

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

30

-->

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

31

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

32

<HTML>

33

<HEAD>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

34

35

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

36

<TITLE>curs_inopts 3x</TITLE>

</HEAD>

<BODY>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

41

<H1 class="no-header">curs_inopts 3x</H1>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

42

<PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

43

<A HREF="curs_inopts.3x.html">curs_inopts(3x)</A> <A HREF="curs_inopts.3x.html">curs_inopts(3x)</A>

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

49

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

50

cbreak, nocbreak, echo, noecho, halfdelay, intrflush,

51

keypad, meta, nodelay, notimeout, raw, noraw, noqiflush,

52

qiflush, timeout, wtimeout, typeahead - curses input

options

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

57

<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

#include <curses.h>

int cbreak(void);

int nocbreak(void);

int echo(void);

int noecho(void);

int halfdelay(int tenths);

65

int intrflush(WINDOW *win, bool bf);

66

int keypad(WINDOW *win, bool bf);

67

int meta(WINDOW *win, bool bf);

68

int nodelay(WINDOW *win, bool bf);

69

int raw(void);

70

int noraw(void);

71

void noqiflush(void);

72

void qiflush(void);

73

int notimeout(WINDOW *win, bool bf);

74

void timeout(int delay);

75

void wtimeout(WINDOW *win, int delay);

76

int typeahead(int fd);

77

78

79

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

80

<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>

81

The ncurses library provides several functions which let

82

an application change way input from the terminal is han-

83

dled. Some are global, applying to all windows. Others

84

apply only to a specific window. Window-specific settings

85

are not automatically applied to new or derived windows.

86

An application must apply these to each window, if the

87

same behavior is needed.

</PRE>

<H3><a name="h3-cbreak">cbreak</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

92

Normally, the tty driver buffers typed characters until a

93

newline or carriage return is typed. The cbreak routine

94

disables line buffering and erase/kill character-process-

95

ing (interrupt and flow control characters are unaffect-

96

ed), making characters typed by the user immediately

97

available to the program. The nocbreak routine returns

98

the terminal to normal (cooked) mode.

99

100

Initially the terminal may or may not be in cbreak mode,

101

as the mode is inherited; therefore, a program should call

102

cbreak or nocbreak explicitly. Most interactive programs

103

using curses set the cbreak mode. Note that cbreak over-

104

rides raw. [See <A HREF="curs_getch.3x.html">curs_getch(3x)</A> for a discussion of how

105

these routines interact with echo and noecho.]

106

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

107

108

</PRE>

109

<H3><a name="h3-echo_noecho">echo/noecho</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

110

The echo and noecho routines control whether characters

111

typed by the user are echoed by getch as they are typed.

112

Echoing by the tty driver is always disabled, but initial-

113

ly getch is in echo mode, so characters typed are echoed.

114

Authors of most interactive programs prefer to do their

115

own echoing in a controlled area of the screen, or not to

116

echo at all, so they disable echoing by calling noecho.

117

[See <A HREF="curs_getch.3x.html">curs_getch(3x)</A> for a discussion of how these routines

118

interact with cbreak and nocbreak.]

119

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

120

121

</PRE>

122

<H3><a name="h3-halfdelay">halfdelay</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

123

The halfdelay routine is used for half-delay mode, which

124

is similar to cbreak mode in that characters typed by the

125

user are immediately available to the program. However,

126

after blocking for tenths tenths of seconds, ERR is re-

127

turned if nothing has been typed. The value of tenths

128

must be a number between 1 and 255. Use nocbreak to leave

129

half-delay mode.

130

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

131

132

</PRE>

133

<H3><a name="h3-intrflush">intrflush</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

134

If the intrflush option is enabled, (bf is TRUE), when an

135

interrupt key is pressed on the keyboard (interrupt,

136

break, quit) all output in the tty driver queue will be

137

flushed, giving the effect of faster response to the in-

138

terrupt, but causing curses to have the wrong idea of what

139

is on the screen. Disabling (bf is FALSE), the option

140

prevents the flush. The default for the option is inher-

141

ited from the tty driver settings. The window argument is

142

ignored.

143

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

144

145

</PRE>

146

<H3><a name="h3-keypad">keypad</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

147

The keypad option enables the keypad of the user's termi-

148

nal. If enabled (bf is TRUE), the user can press a func-

149

tion key (such as an arrow key) and wgetch returns a sin-

150

gle value representing the function key, as in KEY_LEFT.

151

If disabled (bf is FALSE), curses does not treat function

152

keys specially and the program has to interpret the escape

153

sequences itself. If the keypad in the terminal can be

154

turned on (made to transmit) and off (made to work local-

155

ly), turning on this option causes the terminal keypad to

156

be turned on when wgetch is called. The default value for

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

157

keypad is FALSE.

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

158

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

</PRE>

Amit Daniel Kachhap

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

[diff] [blame]

162

Initially, whether the terminal returns 7 or 8 significant

163

bits on input depends on the control mode of the tty driv-

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

164

er [see termio(7)]. To force 8 bits to be returned, in-

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

165

voke meta(win, TRUE); this is equivalent, under POSIX, to

166

setting the CS8 flag on the terminal. To force 7 bits to

167

be returned, invoke meta(win, FALSE); this is equivalent,

168

under POSIX, to setting the CS7 flag on the terminal. The

169

window argument, win, is always ignored. If the terminfo

170

capabilities smm (meta_on) and rmm (meta_off) are defined

171

for the terminal, smm is sent to the terminal when

172

meta(win, TRUE) is called and rmm is sent when meta(win,

173

FALSE) is called.

174

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

175

176

</PRE>

177

<H3><a name="h3-nodelay">nodelay</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

178

The nodelay option causes getch to be a non-blocking call.

179

If no input is ready, getch returns ERR. If disabled (bf

180

is FALSE), getch waits until a key is pressed.

181

182

While interpreting an input escape sequence, wgetch sets a

183

timer while waiting for the next character. If notime-

184

out(win, TRUE) is called, then wgetch does not set a

185

timer. The purpose of the timeout is to differentiate be-

186

tween sequences received from a function key and those

187

typed by a user.

188

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

189

190

</PRE>

191

<H3><a name="h3-raw_noraw">raw/noraw</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

192

The raw and noraw routines place the terminal into or out

193

of raw mode. Raw mode is similar to cbreak mode, in that

194

characters typed are immediately passed through to the us-

195

er program. The differences are that in raw mode, the in-

196

terrupt, quit, suspend, and flow control characters are

197

all passed through uninterpreted, instead of generating a

198

signal. The behavior of the BREAK key depends on other

199

bits in the tty driver that are not set by curses.

200

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

201

202

</PRE>

203

<H3><a name="h3-noqiflush">noqiflush</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

204

When the noqiflush routine is used, normal flush of input

205

and output queues associated with the INTR, QUIT and SUSP

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

206

characters will not be done [see termio(7)]. When qiflush

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

207

is called, the queues will be flushed when these control

208

characters are read. You may want to call noqiflush() in

209

a signal handler if you want output to continue as though

210

the interrupt had not occurred, after the handler exits.

211

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

212

213

</PRE>

214

<H3><a name="h3-timeout_wtimeout">timeout/wtimeout</a></H3><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

215

The timeout and wtimeout routines set blocking or non-

216

blocking read for a given window. If delay is negative,

217

blocking read is used (i.e., waits indefinitely for in-

218

put). If delay is zero, then non-blocking read is used

219

(i.e., read returns ERR if no input is waiting). If delay

220

is positive, then read blocks for delay milliseconds, and

221

returns ERR if there is still no input. Hence, these rou-

222

tines provide the same functionality as nodelay, plus the

223

additional capability of being able to block for only de-

224

lay milliseconds (where delay is positive).

225

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

226

227

</PRE>

228

<H3><a name="h3-typeahead">typeahead</a></H3><PRE>

229

The curses library does "line-breakout optimization" by

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

230

looking for typeahead periodically while updating the

231

screen. If input is found, and it is coming from a tty,

232

the current update is postponed until refresh or doupdate

233

is called again. This allows faster response to commands

234

typed in advance. Normally, the input FILE pointer passed

235

to newterm, or stdin in the case that initscr was used,

236

will be used to do this typeahead checking. The typeahead

237

routine specifies that the file descriptor fd is to be

238

used to check for typeahead instead. If fd is -1, then no

239

typeahead checking is done.

240

241

242

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

243

<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

244

All routines that return an integer return ERR upon fail-

245

ure and OK (SVr4 specifies only "an integer value other

246

than ERR") upon successful completion, unless otherwise

247

noted in the preceding routine descriptions.

248

249

X/Open does not define any error conditions. In this im-

250

plementation, functions with a window parameter will re-

251

turn an error if it is null. Any function will also re-

252

turn an error if the terminal was not initialized. Also,

253

254

halfdelay

255

returns an error if its parameter is outside

the range 1..255.

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

260

<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

261

These functions are described in the XSI Curses standard,

262

Issue 4.

263

264

The ncurses library obeys the XPG4 standard and the his-

265

torical practice of the AT&T curses implementations, in

266

that the echo bit is cleared when curses initializes the

267

terminal state. BSD curses differed from this slightly;

268

it left the echo bit on at initialization, but the BSD raw

269

call turned it off as a side-effect. For best portabili-

270

ty, set echo or noecho explicitly just after initializa-

271

tion, even if your program remains in cooked mode.

272

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

273

When keypad is first enabled, ncurses loads the key-defi-

274

nitions for the current terminal description. If the ter-

275

minal description includes extended string capabilities,

276

e.g., from using the -x option of tic, then ncurses also

277

defines keys for the capabilities whose names begin with

278

"k". The corresponding keycodes are generated and (de-

279

pending on previous loads of terminal descriptions) may

280

differ from one execution of a program to the next. The

281

generated keycodes are recognized by the keyname function

282

(which will then return a name beginning with "k" denoting

283

the terminfo capability name rather than "K", used for

284

curses key-names). On the other hand, an application can

285

use define_key to establish a specific keycode for a given

286

string. This makes it possible for an application to

287

check for an extended capability's presence with tigetstr,

288

and reassign the keycode to match its own needs.

289

290

Low-level applications can use tigetstr to obtain the def-

291

inition of any particular string capability. Higher-level

292

applications which use the curses wgetch and similar func-

293

tions to return keycodes rely upon the order in which the

294

strings are loaded. If more than one key definition has

295

the same string value, then wgetch can return only one

296

keycode. Most curses implementations (including ncurses)

297

load key definitions in the order defined by the array of

298

string capability names. The last key to be loaded deter-

299

mines the keycode which will be returned. In ncurses, you

300

may also have extended capabilities interpreted as key

301

definitions. These are loaded after the predefined keys,

302

and if a capability's value is the same as a previously-

303

loaded key definition, the later definition is the one

304

used.

305

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

306

307

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

308

<H2><a name="h2-NOTES">NOTES</a></H2><PRE>

309

Note that echo, noecho, halfdelay, intrflush, meta, node-

310

lay, notimeout, noqiflush, qiflush, timeout, and wtimeout

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

311

may be macros.

312

313

The noraw and nocbreak calls follow historical practice in

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

314

that they attempt to restore to normal (`cooked') mode

315

from raw and cbreak modes respectively. Mixing raw/noraw

316

and cbreak/nocbreak calls leads to tty driver control

317

states that are hard to predict or understand; it is not

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

recommended.

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

322

323

<A HREF="ncurses.3x.html">curses(3x)</A>, <A HREF="curs_getch.3x.html">curs_getch(3x)</A>, <A HREF="curs_initscr.3x.html">curs_initscr(3x)</A>,

324

<A HREF="curs_util.3x.html">curs_util(3x)</A>, <A HREF="define_key.3x.html">define_key(3x)</A>, termio(7)

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

<A HREF="curs_inopts.3x.html">curs_inopts(3x)</A>

329

</PRE>

Steve Kondik

ae271bc

2015-11-15 02:50:53 +0100

[diff] [blame]

<ul>

<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>

334

<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>

335

<ul>

336

<li><a href="#h3-cbreak">cbreak</a></li>

337

<li><a href="#h3-echo_noecho">echo/noecho</a></li>

338

<li><a href="#h3-halfdelay">halfdelay</a></li>

339

<li><a href="#h3-intrflush">intrflush</a></li>

340

<li><a href="#h3-keypad">keypad</a></li>

341

342

<li><a href="#h3-nodelay">nodelay</a></li>

343

<li><a href="#h3-raw_noraw">raw/noraw</a></li>

344

<li><a href="#h3-noqiflush">noqiflush</a></li>

345

<li><a href="#h3-timeout_wtimeout">timeout/wtimeout</a></li>

346

<li><a href="#h3-typeahead">typeahead</a></li>

347

</ul>

348

</li>

349

<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>

350

<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>

351

<li><a href="#h2-NOTES">NOTES</a></li>

352

353

</ul>

354

</div>

Amit Daniel Kachhap

e6a01f5

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

[diff] [blame]

355

</BODY>

356

</HTML>