3b36fa9a6df1671780602016aefda64749c40240
[ncurses.git] / man / ncurses.3x
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright (c) 1998,1999 Free Software Foundation, Inc.                   *
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 .\"***************************************************************************
29 .\"
30 .\" $Id: ncurses.3x,v 1.44 2000/10/08 01:39:26 tom Exp $
31 .hy 0
32 .TH ncurses 3X ""
33 .ds n 5
34 .ds d @TERMINFO@
35 .SH NAME
36 \fBncurses\fR - CRT screen handling and optimization package
37 .SH SYNOPSIS
38 \fB#include <curses.h>\fR
39 .br
40 .SH DESCRIPTION
41 The \fBncurses\fR library routines give the user a terminal-independent method
42 of updating character screens with reasonable optimization.  This
43 implementation is ``new curses'' (ncurses) and is the approved replacement for
44 4.4BSD classic curses, which has been discontinued.
45
46 The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
47 Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
48 library is freely redistributable in source form.  Differences from the SVr4
49 curses are summarized under the EXTENSIONS and BUGS sections below and
50 described in detail in the EXTENSIONS and BUGS sections of individual man
51 pages.
52
53 A program using these routines must be linked with the \fB-lncurses\fR option,
54 or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
55 (Your system integrator may also have installed these libraries under
56 the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
57 The ncurses_g library generates trace logs (in a file called 'trace' in the
58 current directory) that describe curses actions.
59
60 The \fBncurses\fR package supports: overall screen, window and pad
61 manipulation; output to windows and pads; reading terminal input; control over
62 terminal and \fBcurses\fR input and output options; environment query
63 routines; color manipulation; use of soft label keys; terminfo capabilities;
64 and access to low-level terminal-manipulation routines.
65
66 To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
67 must be called before any of the other routines that deal with windows
68 and screens are used.  The routine \fBendwin\fR must be called before
69 exiting.  To get character-at-a-time input without echoing (most
70 interactive, screen oriented programs want this), the following
71 sequence should be used:
72
73       \fBinitscr(); cbreak(); noecho();\fR
74
75 Most programs would additionally use the sequence:
76
77       \fBnonl();\fR
78       \fBintrflush(stdscr, FALSE);\fR
79       \fBkeypad(stdscr, TRUE);\fR
80
81 Before a \fBcurses\fR program is run, the tab stops of the terminal
82 should be set and its initialization strings, if defined, must be
83 output.  This can be done by executing the \fBtput init\fR command
84 after the shell environment variable \fBTERM\fR has been exported.
85 \fBtset(1)\fR is usually responsible for doing this.
86 [See \fBterminfo\fR(\*n) for further details.]
87
88 The \fBncurses\fR library permits manipulation of data structures,
89 called \fIwindows\fR, which can be thought of as two-dimensional
90 arrays of characters representing all or part of a CRT screen.  A
91 default window called \fBstdscr\fR, which is the size of the terminal
92 screen, is supplied.  Others may be created with \fBnewwin\fR.
93
94 Note that \fBcurses\fR does not handle overlapping windows, that's done by
95 the \fBpanel\fR(3X) library. This means that you can either use
96 \fBstdscr\fR or divide the screen into tiled windows and not using
97 \fBstdscr\fR at all. Mixing the two will result in unpredictable, and
98 undesired, effects.
99
100 Windows are referred to by variables declared as \fBWINDOW *\fR.
101 These data structures are manipulated with routines described here and
102 elsewhere in the \fBncurses\fR manual pages.  Among which the most basic
103 routines are \fBmove\fR and \fBaddch\fR.  More general versions of
104 these routines are included with names beginning with \fBw\fR,
105 allowing the user to specify a window.  The routines not beginning
106 with \fBw\fR affect \fBstdscr\fR.)
107
108 After using routines to manipulate a window, \fBrefresh\fR is called,
109 telling \fBcurses\fR to make the user's CRT screen look like
110 \fBstdscr\fR.  The characters in a window are actually of type
111 \fBchtype\fR, (character and attribute data) so that other information
112 about the character may also be stored with each character.
113
114 Special windows called \fIpads\fR may also be manipulated.  These are windows
115 which are not constrained to the size of the screen and whose contents need not
116 be completely displayed.  See \fBcurs_pad\fR(3X) for more information.
117
118 In addition to drawing characters on the screen, video attributes and colors
119 may be supported, causing the characters to show up in such modes as
120 underlined, in reverse video, or in color on terminals that support such
121 display enhancements.  Line drawing characters may be specified to be output.
122 On input, \fBcurses\fR is also able to translate arrow and function keys that
123 transmit escape sequences into single values.  The video attributes, line
124 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
125 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
126
127 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
128 program is executing in a window environment, line and column information in
129 the environment will override information read by \fIterminfo\fR.  This would
130 effect a program running in an AT&T 630 layer, for example, where the size of a
131 screen is changeable (see \fBENVIRONMENT\fR).
132
133 If the environment variable \fBTERMINFO\fR is defined, any program using
134 \fBcurses\fR checks for a local terminal definition before checking in the
135 standard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
136 compiled terminal definition is found in
137
138       \fB\*d/a/att4424\fR.
139
140 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
141 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
142 \fB$HOME/myterms\fR, \fBcurses\fR first checks
143
144       \fB$HOME/myterms/a/att4424\fR,
145
146 and if that fails, it then checks
147
148       \fB\*d/a/att4424\fR.
149
150 This is useful for developing experimental definitions or when write
151 permission in \fB\*d\fR is not available.
152
153 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
154 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
155 screen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
156 \fB0\fR, respectively.
157
158 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
159 which is used for certain low-level operations like clearing and redrawing a
160 screen containing garbage.  The \fBcurscr\fR can be used in only a few
161 routines.
162
163 .SS Routine and Argument Names
164 Many \fBcurses\fR routines have two or more versions.  The routines prefixed
165 with \fBw\fR require a window argument.  The routines prefixed with \fBp\fR
166 require a pad argument.  Those without a prefix generally use \fBstdscr\fR.
167
168 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
169 coordinate to move to before performing the appropriate action.  The
170 \fBmv\fR routines imply a call to \fBmove\fR before the call to the
171 other routine.  The coordinate \fIy\fR always refers to the row (of
172 the window), and \fIx\fR always refers to the column.  The upper
173 left-hand corner is always (0,0), not (1,1).
174
175 The routines prefixed with \fBmvw\fR take both a window argument and
176 \fIx\fR and \fIy\fR coordinates.  The window argument is always
177 specified before the coordinates.
178
179 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
180 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
181 \fBWINDOW\fR.
182
183 Option setting routines require a Boolean flag \fIbf\fR with the value
184 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  The
185 variables \fIch\fR and \fIattrs\fR below are always of type
186 \fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
187 \fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fR
188 is defined in \fB<term.h>\fR.  All other arguments are integers.
189
190 .SS Routine Name Index
191 The following table lists each \fBcurses\fR routine and the name of
192 the manual page on which it is described.  Routines flagged with `*'
193 are ncurses-specific, not described by XPG4 or present in SVr4.
194
195 .TS
196 center tab(/);
197 l l
198 l l .
199 \fBcurses\fR Routine Name/Manual Page Name
200 =
201 COLOR_PAIR/\fBcurs_color\fR(3X)
202 PAIR_NUMBER/\fBcurs_attr\fR(3X)
203 _nc_tracebits/\fBcurs_trace\fR(3X)*
204 _traceattr/\fBcurs_trace\fR(3X)*
205 _traceattr2/\fBcurs_trace\fR(3X)*
206 _tracechar/\fBcurs_trace\fR(3X)*
207 _tracechtype/\fBcurs_trace\fR(3X)*
208 _tracechtype2/\fBcurs_trace\fR(3X)*
209 _tracedump/\fBcurs_trace\fR(3X)*
210 _tracef/\fBcurs_trace\fR(3X)*
211 _tracemouse/\fBcurs_trace\fR(3X)*
212 addch/\fBcurs_addch\fR(3X)
213 addchnstr/\fBcurs_addchstr\fR(3X)
214 addchstr/\fBcurs_addchstr\fR(3X)
215 addnstr/\fBcurs_addstr\fR(3X)
216 addstr/\fBcurs_addstr\fR(3X)
217 assume_default_colors/\fBdefault_colors\fR(3X)*
218 attr_get/\fBcurs_attr\fR(3X)
219 attr_off/\fBcurs_attr\fR(3X)
220 attr_on/\fBcurs_attr\fR(3X)
221 attr_set/\fBcurs_attr\fR(3X)
222 attroff/\fBcurs_attr\fR(3X)
223 attron/\fBcurs_attr\fR(3X)
224 attrset/\fBcurs_attr\fR(3X)
225 baudrate/\fBcurs_termattrs\fR(3X)
226 beep/\fBcurs_beep\fR(3X)
227 bkgd/\fBcurs_bkgd\fR(3X)
228 bkgdset/\fBcurs_bkgd\fR(3X)
229 border/\fBcurs_border\fR(3X)
230 box/\fBcurs_border\fR(3X)
231 can_change_color/\fBcurs_color\fR(3X)
232 cbreak/\fBcurs_inopts\fR(3X)
233 chgat/\fBcurs_attr\fR(3X)
234 clear/\fBcurs_clear\fR(3X)
235 clearok/\fBcurs_outopts\fR(3X)
236 clrtobot/\fBcurs_clear\fR(3X)
237 clrtoeol/\fBcurs_clear\fR(3X)
238 color_content/\fBcurs_color\fR(3X)
239 color_set/\fBcurs_attr\fR(3X)
240 copywin/\fBcurs_overlay\fR(3X)
241 curs_set/\fBcurs_kernel\fR(3X)
242 curses_version/\fBcurs_extend\fR(3X)*
243 def_prog_mode/\fBcurs_kernel\fR(3X)
244 def_shell_mode/\fBcurs_kernel\fR(3X)
245 define_key/\fBdefine_key\fR(3X)*
246 del_curterm/\fBcurs_terminfo\fR(3X)
247 delay_output/\fBcurs_util\fR(3X)
248 delch/\fBcurs_delch\fR(3X)
249 deleteln/\fBcurs_deleteln\fR(3X)
250 delscreen/\fBcurs_initscr\fR(3X)
251 delwin/\fBcurs_window\fR(3X)
252 derwin/\fBcurs_window\fR(3X)
253 doupdate/\fBcurs_refresh\fR(3X)
254 dupwin/\fBcurs_window\fR(3X)
255 echo/\fBcurs_inopts\fR(3X)
256 echochar/\fBcurs_addch\fR(3X)
257 endwin/\fBcurs_initscr\fR(3X)
258 erase/\fBcurs_clear\fR(3X)
259 erasechar/\fBcurs_termattrs\fR(3X)
260 filter/\fBcurs_util\fR(3X)
261 flash/\fBcurs_beep\fR(3X)
262 flushinp/\fBcurs_util\fR(3X)
263 getbegyx/\fBcurs_getyx\fR(3X)
264 getbkgd/\fBcurs_bkgd\fR(3X)
265 getch/\fBcurs_getch\fR(3X)
266 getmaxyx/\fBcurs_getyx\fR(3X)
267 getmouse/\fBcurs_mouse\fR(3X)*
268 getnstr/\fBcurs_getstr\fR(3X)
269 getparyx/\fBcurs_getyx\fR(3X)
270 getstr/\fBcurs_getstr\fR(3X)
271 getsyx/\fBcurs_kernel\fR(3X)
272 getwin/\fBcurs_util\fR(3X)
273 getyx/\fBcurs_getyx\fR(3X)
274 halfdelay/\fBcurs_inopts\fR(3X)
275 has_colors/\fBcurs_color\fR(3X)
276 has_ic/\fBcurs_termattrs\fR(3X)
277 has_il/\fBcurs_termattrs\fR(3X)
278 has_key/\fBcurs_getch\fR(3X)*
279 hline/\fBcurs_border\fR(3X)
280 idcok/\fBcurs_outopts\fR(3X)
281 idlok/\fBcurs_outopts\fR(3X)
282 immedok/\fBcurs_outopts\fR(3X)
283 inch/\fBcurs_inch\fR(3X)
284 inchnstr/\fBcurs_inchstr\fR(3X)
285 inchstr/\fBcurs_inchstr\fR(3X)
286 init_color/\fBcurs_color\fR(3X)
287 init_pair/\fBcurs_color\fR(3X)
288 initscr/\fBcurs_initscr\fR(3X)
289 innstr/\fBcurs_instr\fR(3X)
290 insch/\fBcurs_insch\fR(3X)
291 insdelln/\fBcurs_deleteln\fR(3X)
292 insertln/\fBcurs_deleteln\fR(3X)
293 insnstr/\fBcurs_insstr\fR(3X)
294 insstr/\fBcurs_insstr\fR(3X)
295 instr/\fBcurs_instr\fR(3X)
296 intrflush/\fBcurs_inopts\fR(3X)
297 is_linetouched/\fBcurs_touch\fR(3X)
298 is_wintouched/\fBcurs_touch\fR(3X)
299 isendwin/\fBcurs_initscr\fR(3X)
300 keybound/\fBkeybound\fR(3X)*
301 keyname/\fBcurs_util\fR(3X)
302 keyok/\fBkeyok\fR(3X)*
303 keypad/\fBcurs_inopts\fR(3X)
304 killchar/\fBcurs_termattrs\fR(3X)
305 leaveok/\fBcurs_outopts\fR(3X)
306 longname/\fBcurs_termattrs\fR(3X)
307 mcprint/\fBcurs_print\fR(3X)*
308 meta/\fBcurs_inopts\fR(3X)
309 mouse_trafo/\fBcurs_mouse\fR(3X)*
310 mouseinterval/\fBcurs_mouse\fR(3X)*
311 mousemask/\fBcurs_mouse\fR(3X)*
312 move/\fBcurs_move\fR(3X)
313 mvaddch/\fBcurs_addch\fR(3X)
314 mvaddchnstr/\fBcurs_addchstr\fR(3X)
315 mvaddchstr/\fBcurs_addchstr\fR(3X)
316 mvaddnstr/\fBcurs_addstr\fR(3X)
317 mvaddstr/\fBcurs_addstr\fR(3X)
318 mvchgat/\fBcurs_attr\fR(3X)
319 mvcur/\fBcurs_terminfo\fR(3X)
320 mvdelch/\fBcurs_delch\fR(3X)
321 mvderwin/\fBcurs_window\fR(3X)
322 mvgetch/\fBcurs_getch\fR(3X)
323 mvgetnstr/\fBcurs_getstr\fR(3X)
324 mvgetstr/\fBcurs_getstr\fR(3X)
325 mvhline/\fBcurs_border\fR(3X)
326 mvinch/\fBcurs_inch\fR(3X)
327 mvinchnstr/\fBcurs_inchstr\fR(3X)
328 mvinchstr/\fBcurs_inchstr\fR(3X)
329 mvinnstr/\fBcurs_instr\fR(3X)
330 mvinsch/\fBcurs_insch\fR(3X)
331 mvinsnstr/\fBcurs_insstr\fR(3X)
332 mvinsstr/\fBcurs_insstr\fR(3X)
333 mvinstr/\fBcurs_instr\fR(3X)
334 mvprintw/\fBcurs_printw\fR(3X)
335 mvscanw/\fBcurs_scanw\fR(3X)
336 mvvline/\fBcurs_border\fR(3X)
337 mvwaddch/\fBcurs_addch\fR(3X)
338 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
339 mvwaddchstr/\fBcurs_addchstr\fR(3X)
340 mvwaddnstr/\fBcurs_addstr\fR(3X)
341 mvwaddstr/\fBcurs_addstr\fR(3X)
342 mvwchgat/\fBcurs_attr\fR(3X)
343 mvwdelch/\fBcurs_delch\fR(3X)
344 mvwgetch/\fBcurs_getch\fR(3X)
345 mvwgetnstr/\fBcurs_getstr\fR(3X)
346 mvwgetstr/\fBcurs_getstr\fR(3X)
347 mvwhline/\fBcurs_border\fR(3X)
348 mvwin/\fBcurs_window\fR(3X)
349 mvwinch/\fBcurs_inch\fR(3X)
350 mvwinchnstr/\fBcurs_inchstr\fR(3X)
351 mvwinchstr/\fBcurs_inchstr\fR(3X)
352 mvwinnstr/\fBcurs_instr\fR(3X)
353 mvwinsch/\fBcurs_insch\fR(3X)
354 mvwinsnstr/\fBcurs_insstr\fR(3X)
355 mvwinsstr/\fBcurs_insstr\fR(3X)
356 mvwinstr/\fBcurs_instr\fR(3X)
357 mvwprintw/\fBcurs_printw\fR(3X)
358 mvwscanw/\fBcurs_scanw\fR(3X)
359 mvwvline/\fBcurs_border\fR(3X)
360 napms/\fBcurs_kernel\fR(3X)
361 newpad/\fBcurs_pad\fR(3X)
362 newterm/\fBcurs_initscr\fR(3X)
363 newwin/\fBcurs_window\fR(3X)
364 nl/\fBcurs_outopts\fR(3X)
365 nocbreak/\fBcurs_inopts\fR(3X)
366 nodelay/\fBcurs_inopts\fR(3X)
367 noecho/\fBcurs_inopts\fR(3X)
368 nonl/\fBcurs_outopts\fR(3X)
369 noqiflush/\fBcurs_inopts\fR(3X)
370 noraw/\fBcurs_inopts\fR(3X)
371 notimeout/\fBcurs_inopts\fR(3X)
372 overlay/\fBcurs_overlay\fR(3X)
373 overwrite/\fBcurs_overlay\fR(3X)
374 pair_content/\fBcurs_color\fR(3X)
375 pechochar/\fBcurs_pad\fR(3X)
376 pnoutrefresh/\fBcurs_pad\fR(3X)
377 prefresh/\fBcurs_pad\fR(3X)
378 printw/\fBcurs_printw\fR(3X)
379 putp/\fBcurs_terminfo\fR(3X)
380 putwin/\fBcurs_util\fR(3X)
381 qiflush/\fBcurs_inopts\fR(3X)
382 raw/\fBcurs_inopts\fR(3X)
383 redrawwin/\fBcurs_refresh\fR(3X)
384 refresh/\fBcurs_refresh\fR(3X)
385 reset_prog_mode/\fBcurs_kernel\fR(3X)
386 reset_shell_mode/\fBcurs_kernel\fR(3X)
387 resetty/\fBcurs_kernel\fR(3X)
388 resizeterm/\fBresizeterm\fR(3X)*
389 restartterm/\fBcurs_terminfo\fR(3X)
390 ripoffline/\fBcurs_kernel\fR(3X)
391 savetty/\fBcurs_kernel\fR(3X)
392 scanw/\fBcurs_scanw\fR(3X)
393 scr_dump/\fBcurs_scr_dump\fR(3X)
394 scr_init/\fBcurs_scr_dump\fR(3X)
395 scr_restore/\fBcurs_scr_dump\fR(3X)
396 scr_set/\fBcurs_scr_dump\fR(3X)
397 scrl/\fBcurs_scroll\fR(3X)
398 scroll/\fBcurs_scroll\fR(3X)
399 scrollok/\fBcurs_outopts\fR(3X)
400 set_curterm/\fBcurs_terminfo\fR(3X)
401 set_term/\fBcurs_initscr\fR(3X)
402 setscrreg/\fBcurs_outopts\fR(3X)
403 setsyx/\fBcurs_kernel\fR(3X)
404 setterm/\fBcurs_terminfo\fR(3X)
405 setupterm/\fBcurs_terminfo\fR(3X)
406 slk_attr/\fBcurs_slk\fR(3X)*
407 slk_attr_off/\fBcurs_slk\fR(3X)
408 slk_attr_on/\fBcurs_slk\fR(3X)
409 slk_attr_set/\fBcurs_slk\fR(3X)
410 slk_attroff/\fBcurs_slk\fR(3X)
411 slk_attron/\fBcurs_slk\fR(3X)
412 slk_attrset/\fBcurs_slk\fR(3X)
413 slk_clear/\fBcurs_slk\fR(3X)
414 slk_color/\fBcurs_slk\fR(3X)
415 slk_init/\fBcurs_slk\fR(3X)
416 slk_label/\fBcurs_slk\fR(3X)
417 slk_noutrefresh/\fBcurs_slk\fR(3X)
418 slk_refresh/\fBcurs_slk\fR(3X)
419 slk_restore/\fBcurs_slk\fR(3X)
420 slk_set/\fBcurs_slk\fR(3X)
421 slk_touch/\fBcurs_slk\fR(3X)
422 standend/\fBcurs_attr\fR(3X)
423 standout/\fBcurs_attr\fR(3X)
424 start_color/\fBcurs_color\fR(3X)
425 subpad/\fBcurs_pad\fR(3X)
426 subwin/\fBcurs_window\fR(3X)
427 syncok/\fBcurs_window\fR(3X)
428 termattrs/\fBcurs_termattrs\fR(3X)
429 termname/\fBcurs_termattrs\fR(3X)
430 tgetent/\fBcurs_termcap\fR(3X)
431 tgetflag/\fBcurs_termcap\fR(3X)
432 tgetnum/\fBcurs_termcap\fR(3X)
433 tgetstr/\fBcurs_termcap\fR(3X)
434 tgoto/\fBcurs_termcap\fR(3X)
435 tigetflag/\fBcurs_terminfo\fR(3X)
436 tigetnum/\fBcurs_terminfo\fR(3X)
437 tigetstr/\fBcurs_terminfo\fR(3X)
438 timeout/\fBcurs_inopts\fR(3X)
439 touchline/\fBcurs_touch\fR(3X)
440 touchwin/\fBcurs_touch\fR(3X)
441 tparm/\fBcurs_terminfo\fR(3X)
442 tputs/\fBcurs_termcap\fR(3X)
443 tputs/\fBcurs_terminfo\fR(3X)
444 trace/\fBcurs_trace\fR(3X)*
445 typeahead/\fBcurs_inopts\fR(3X)
446 unctrl/\fBcurs_util\fR(3X)
447 ungetch/\fBcurs_getch\fR(3X)
448 ungetmouse/\fBcurs_mouse\fR(3X)*
449 untouchwin/\fBcurs_touch\fR(3X)
450 use_default_colors/\fBdefault_colors\fR(3X)*
451 use_env/\fBcurs_util\fR(3X)
452 use_extended_names/\fBcurs_extend\fR(3X)*
453 vidattr/\fBcurs_terminfo\fR(3X)
454 vidputs/\fBcurs_terminfo\fR(3X)
455 vline/\fBcurs_border\fR(3X)
456 vw_printw/\fBcurs_printw\fR(3X)
457 vw_scanw/\fBcurs_scanw\fR(3X)
458 vwprintw/\fBcurs_printw\fR(3X)
459 vwscanw/\fBcurs_scanw\fR(3X)
460 waddch/\fBcurs_addch\fR(3X)
461 waddchnstr/\fBcurs_addchstr\fR(3X)
462 waddchstr/\fBcurs_addchstr\fR(3X)
463 waddnstr/\fBcurs_addstr\fR(3X)
464 waddstr/\fBcurs_addstr\fR(3X)
465 wattr_get/\fBcurs_attr\fR(3X)
466 wattr_off/\fBcurs_attr\fR(3X)
467 wattr_on/\fBcurs_attr\fR(3X)
468 wattr_set/\fBcurs_attr\fR(3X)
469 wattroff/\fBcurs_attr\fR(3X)
470 wattron/\fBcurs_attr\fR(3X)
471 wattrset/\fBcurs_attr\fR(3X)
472 wbkgd/\fBcurs_bkgd\fR(3X)
473 wbkgdset/\fBcurs_bkgd\fR(3X)
474 wborder/\fBcurs_border\fR(3X)
475 wchgat/\fBcurs_attr\fR(3X)
476 wclear/\fBcurs_clear\fR(3X)
477 wclrtobot/\fBcurs_clear\fR(3X)
478 wclrtoeol/\fBcurs_clear\fR(3X)
479 wcolor_set/\fBcurs_attr\fR(3X)
480 wcursyncup/\fBcurs_window\fR(3X)
481 wdelch/\fBcurs_delch\fR(3X)
482 wdeleteln/\fBcurs_deleteln\fR(3X)
483 wechochar/\fBcurs_addch\fR(3X)
484 wenclose/\fBcurs_mouse\fR(3X)*
485 werase/\fBcurs_clear\fR(3X)
486 wgetch/\fBcurs_getch\fR(3X)
487 wgetnstr/\fBcurs_getstr\fR(3X)
488 wgetstr/\fBcurs_getstr\fR(3X)
489 whline/\fBcurs_border\fR(3X)
490 winch/\fBcurs_inch\fR(3X)
491 winchnstr/\fBcurs_inchstr\fR(3X)
492 winchstr/\fBcurs_inchstr\fR(3X)
493 winnstr/\fBcurs_instr\fR(3X)
494 winsch/\fBcurs_insch\fR(3X)
495 winsdelln/\fBcurs_deleteln\fR(3X)
496 winsertln/\fBcurs_deleteln\fR(3X)
497 winsnstr/\fBcurs_insstr\fR(3X)
498 winsstr/\fBcurs_insstr\fR(3X)
499 winstr/\fBcurs_instr\fR(3X)
500 wmouse_trafo/\fBcurs_mouse\fR(3X)*
501 wmove/\fBcurs_move\fR(3X)
502 wnoutrefresh/\fBcurs_refresh\fR(3X)
503 wprintw/\fBcurs_printw\fR(3X)
504 wredrawln/\fBcurs_refresh\fR(3X)
505 wrefresh/\fBcurs_refresh\fR(3X)
506 wresize/\fBwresize\fR(3X)*
507 wscanw/\fBcurs_scanw\fR(3X)
508 wscrl/\fBcurs_scroll\fR(3X)
509 wsetscrreg/\fBcurs_outopts\fR(3X)
510 wstandend/\fBcurs_attr\fR(3X)
511 wstandout/\fBcurs_attr\fR(3X)
512 wsyncdown/\fBcurs_window\fR(3X)
513 wsyncup/\fBcurs_window\fR(3X)
514 wtimeout/\fBcurs_inopts\fR(3X)
515 wtouchln/\fBcurs_touch\fR(3X)
516 wvline/\fBcurs_border\fR(3X)
517 .TE
518 .SH RETURN VALUE
519 Routines that return an integer return \fBERR\fR upon failure and an
520 integer value other than \fBERR\fR upon successful completion, unless
521 otherwise noted in the routine descriptions.
522
523 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
524 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, \fBgetmaxyx\fR.  The return
525 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
526 \fBgetmaxyx\fR are undefined (\fIi\fR.\fIe\fR., these should not be used as the
527 right-hand side of assignment statements).
528
529 Routines that return pointers return \fBNULL\fR on error.
530 .SH ENVIRONMENT
531 The following environment symbols are useful for customizing the
532 runtime behavior of the \fBncurses\fR library.  The most important
533 ones have been already discussed in detail.
534 .TP 5
535 BAUDRATE
536 The debugging library checks this environment symbol when the application
537 has redirected output to a file.
538 The symbol's numeric value is used for the baudrate.
539 If no value is found \fBncurses\fR uses 9600.
540 This allows testers to construct repeatable test-cases
541 that take into account costs that depend on baudrate.
542 .TP 5
543 CC
544 When set, change occurrences of the command_character
545 (i.e., the \fBcmdch\fP capability)
546 of the loaded terminfo entries to the value of this symbol.
547 Very few terminfo entries provide this feature.
548 .TP 5
549 COLUMNS
550 Specify the width of the screen in characters.
551 Applications running in a windowing environment usually are able to
552 obtain the width of the window in which they are executing.
553 If neither the $COLUMNS value nor the terminal's screen size is available,
554 \fBncurses\fR uses the size which may be specified in the terminfo database
555 (i.e., the \fBcols\fR capability).
556
557 It is important that your application use a correct size for the screen.
558 However, this is not always possible because your application may be
559 running on a host which does not honor NAWS (Negotiations About Window
560 Size), or because you are temporarily running as another user.
561
562 Either COLUMNS or LINES symbols may be specified independently.
563 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
564 e.g., xterm which commonly specifies a 65 line screen.
565 For best results, \fBlines\fR and \fBcols\fR should not be specified in
566 a terminal description for terminals which are run as emulations.
567
568 Use the \fBuse_env\fR function to disable this feature.
569 .TP 5
570 ESCDELAY
571 Specifies the total time, in milliseconds, for which ncurses will
572 await a character sequence, e.g., a function key.
573 The default value, 1000 milliseconds, is enough for most uses.
574 However, it is made a variable to accommodate unusual applications.
575
576 The most common instance where you may wish to change this value
577 is to work with slow hosts, e.g., running on a network.
578 If the host cannot read characters rapidly enough, it will have the same
579 effect as if the terminal did not send characters rapidly enough.
580 The library will still see a timeout.
581
582 Note that xterm mouse events are built up from character sequences
583 received from the xterm.
584 If your application makes heavy use of multiple-clicking, you may
585 wish to lengthen this default value because the timeout applies
586 to the composed multi-click event as well as the individual clicks.
587 .TP 5
588 HOME
589 Tells \fBncurses\fR where your home directory is.
590 That is where it may read and write auxiliary terminal descriptions:
591
592 $HOME/.termcap
593 .br
594 $HOME/.terminfo
595 .TP 5
596 LINES
597 Like COLUMNS, specify the height of the screen in characters.
598 See COLUMNS for a detailed description.
599 .TP 5
600 MOUSE_BUTTONS_123
601 This applies only to the OS/2 EMX port.
602 It specifies the order of buttons on the mouse.
603 OS/2 numbers a 3-button mouse inconsistently from other
604 platforms:
605
606 1 = left
607 .br
608 2 = right
609 .br
610 3 = middle.
611
612 This symbol lets you customize the mouse.
613 The symbol must be three numeric digits 1-3 in any order, e.g., 123 or 321.
614 If it is not specified, \fBncurses\fR uses 132.
615 .TP 5
616 NCURSES_NO_PADDING
617 Most of the terminal descriptions in the terminfo database are written
618 for real "hardware" terminals.
619 Many people use terminal emulators
620 which run in a windowing environment and use curses-based applications.
621 Terminal emulators can duplicate
622 all of the important aspects of a hardware terminal, but they do not
623 have the same limitations.
624 The chief limitation of a hardware terminal from the standpoint
625 of your application is the management of dataflow, i.e., timing.
626 Unless a hardware terminal is interfaced into a terminal concentrator
627 (which does flow control),
628 it (or your application) must manage dataflow, preventing overruns.
629 The cheapest solution (no hardware cost)
630 is for your program to do this by pausing after
631 operations that the terminal does slowly, such as clearing the display.
632
633 As a result, many terminal descriptions (including the vt100)
634 have delay times embedded.  You may wish to use these descriptions,
635 but not want to pay the performance penalty.
636
637 Set the NCURSES_NO_PADDING symbol to disable all but mandatory
638 padding.  Mandatory padding is used as a part of special control
639 sequences such as \fIflash\fR.
640 .TP 5
641 NCURSES_NO_SETBUF
642 Normally \fBncurses\fR enables buffered output during terminal initialization.
643 This is done (as in SVr4 curses) for performance reasons.
644 For testing purposes, both of \fBncurses\fR and certain applications,
645 this feature is made optional.  Setting the NCURSES_NO_SETBUF variable
646 disables output buffering, leaving the output in the original (usually
647 line buffered) mode.
648 .TP 5
649 NCURSES_TRACE
650 During initialization, the \fBncurses\fR debugging library
651 checks the NCURSES_TRACE symbol.
652 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
653 function, using that value as the argument.
654
655 The argument values, which are defined in \fBcurses.h\fR, provide several
656 types of information.
657 When running with traces enabled, your application will write the
658 file \fBtrace\fR to the current directory.
659 .TP 5
660 TERM
661 Denotes your terminal type.
662 Each terminal type is distinct, though many are similar.
663 .TP 5
664 TERMCAP
665 If the \fBncurses\fR library has been configured with \fItermcap\fR
666 support, \fBncurses\fR will check for a terminal's description in
667 termcap form if it is not available in the terminfo database.
668
669 The TERMCAP symbol contains either a terminal description (with
670 newlines stripped out),
671 or a file name telling where the information denoted by the TERM symbol exists.
672 In either case, setting it directs \fBncurses\fR to ignore
673 the usual place for this information, e.g., /etc/termcap.
674 .TP 5
675 TERMINFO
676 Overrides the directory in which \fBncurses\fR searches for your terminal
677 description.
678 This is the simplest, but not the only way to change the list of directories.
679 The complete list of directories in order follows:
680 .RS
681 .TP 3
682 -
683 the last directory to which \fBncurses\fR wrote, if any, is searched first.
684 .TP 3
685 -
686 the directory specified by the TERMINFO symbol
687 .TP 3
688 -
689 $HOME/.terminfo
690 .TP 3
691 -
692 directories listed in the TERMINFO_DIRS symbol
693 .TP 3
694 -
695 one or more directories whose names are configured and compiled into the
696 ncurses library, e.g.,
697 @TERMINFO@
698 .RE
699 .TP 5
700 TERMINFO_DIRS
701 Specifies a list of directories to search for terminal descriptions.
702 The list is separated by colons (i.e., ":").
703 All of the terminal descriptions are in terminfo form, which makes
704 a subdirectory named for the first letter of the terminal names therein.
705 .TP 5
706 TERMPATH
707 If TERMCAP does not hold a file name then \fBncurses\fR checks
708 the TERMPATH symbol.
709 This is a list of filenames separated by colons (i.e., ":").
710 If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
711 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
712 .PP
713 The library may be configured to disregard the following variables when the
714 current user is the superuser (root), or if the application uses setuid or
715 setgid permissions:
716 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
717 .SH FILES
718 .TP 5
719 @DATADIR@/tabset
720 directory containing initialization files for the terminal capability database
721 @TERMINFO@
722 terminal capability database
723 .SH SEE ALSO
724 \fBterminfo\fR(\*n) and 3X pages whose names begin "curs_" for detailed routine
725 descriptions.
726 .SH EXTENSIONS
727 The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR)
728 that falls back to the old-style /etc/termcap file if the terminal setup code
729 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
730 is not recommended, as it essentially includes an entire termcap compiler in
731 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
732
733 The \fBncurses\fR library includes facilities for capturing mouse events on
734 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
735 manual page for details.
736
737 The \fBncurses\fR library includes facilities for responding to window
738 resizing events, e.g., when running in an xterm.
739 See the \fBresizeterm\fR(3X)
740 and \fBwresize\fR(3X) manual pages for details.
741 In addition, the library may be configured with a SIGWINCH handler.
742
743 The \fBncurses\fR library extends the fixed set of function key capabilities
744 of terminals by allowing the application designer to define additional
745 key sequences at runtime.
746 See the \fBdefine_key\fR(3X)
747 and \fBkeyok\fR(3X) manual pages for details.
748
749 The \fBncurses\fR library can exploit the capabilities of terminals which
750 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application
751 to reset the terminal to its original foreground and background colors.
752 From the users' perspective, the application is able to draw colored
753 text on a background whose color is set independently, providing better
754 control over color contrasts.
755 See the \fBuse_default_colors\fR(3X) manual page for details.
756
757 The \fBncurses\fR library includes a function for directing application output
758 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
759 manual page for details.
760 .SH PORTABILITY
761 The \fBncurses\fR library is intended to be BASE-level conformant with the XSI
762 Curses standard.  Certain portions of the EXTENDED XSI Curses functionality
763 (including color support) are supported.  The following EXTENDED XSI Curses
764 calls in support of wide (multibyte) characters are not yet implemented:
765 \fBadd_wch\fP,
766 \fBadd_wchnstr\fP,
767 \fBadd_wchstr\fP,
768 \fBaddnwstr\fP,
769 \fBaddwstr\fP,
770 \fBbkgrnd\fP,
771 \fBbkgrndset\fP,
772 \fBborder_set\fP,
773 \fBbox_set\fP,
774 \fBecho_wchar\fP,
775 \fBerasewchar\fP,
776 \fBget_wch\fP,
777 \fBget_wstr\fP,
778 \fBgetbkgrnd\fP,
779 \fBgetcchar\fP,
780 \fBgetn_wstr\fP,
781 \fBgetwchtype\fP,
782 \fBhline_set\fP,
783 \fBin_wch\fP,
784 \fBin_wchnstr\fP,
785 \fBin_wchstr\fP,
786 \fBinnwstr\fP,
787 \fBins_nwstr\fP,
788 \fBins_wch\fP,
789 \fBins_wstr\fP,
790 \fBinwchnstr\fP,
791 \fBinwchstr\fP,
792 \fBinwstr\fP,
793 \fBkey_name\fP,
794 \fBkillwchar\fP,
795 \fBmvadd_wch\fP,
796 \fBmvadd_wchnstr\fP,
797 \fBmvadd_wchstr\fP,
798 \fBmvaddnwstr\fP,
799 \fBmvaddwstr\fP,
800 \fBmvget_wch\fP,
801 \fBmvget_wstr\fP,
802 \fBmvgetn_wstr\fP,
803 \fBmvhline_set\fP,
804 \fBmvin_wch\fP,
805 \fBmvinnwstr\fP,
806 \fBmvins_nwstr\fP,
807 \fBmvins_wch\fP,
808 \fBmvins_wstr\fP,
809 \fBmvinwchnstr\fP,
810 \fBmvinwchstr\fP,
811 \fBmvinwchstr\fP,
812 \fBmvinwstr\fP,
813 \fBmvvline_set\fP,
814 \fBmvwadd_wch\fP,
815 \fBmvwadd_wchnstr\fP,
816 \fBmvwadd_wchstr\fP,
817 \fBmvwaddnwstr\fP,
818 \fBmvwaddwstr\fP,
819 \fBmvwget_ch\fP,
820 \fBmvwget_wch\fP,
821 \fBmvwget_wstr\fP,
822 \fBmvwgetn_wstr\fP,
823 \fBmvwhline_set\fP,
824 \fBmvwin_wch\fP,
825 \fBmvwin_wchnstr\fP,
826 \fBmvwin_wchstr\fP,
827 \fBmvwinnwstr\fP,
828 \fBmvwins_nwstr\fP,
829 \fBmvwins_wch\fP,
830 \fBmvwins_wstr\fP,
831 \fBmvwinwchnstr\fP.
832 \fBmvwinwstr\fP,
833 \fBmvwvline_set\fP,
834 \fBpecho_wchar\fP,
835 \fBsetcchar\fP,
836 \fBslk_wset\fP,
837 \fBterm_attrs\fP,
838 \fBunget_wch\fP,
839 \fBvhline_set\fP,
840 \fBvid_attr\fP,
841 \fBvid_puts\fP,
842 \fBvline_set\fP,
843 \fBwadd_wch\fP,
844 \fBwadd_wchnstr\fP,
845 \fBwadd_wchstr\fP,
846 \fBwaddnwstr\fP,
847 \fBwaddwstr\fP,
848 \fBwaddwstr\fP,
849 \fBwbkgrnd\fP,
850 \fBwbkgrndset\fP,
851 \fBwbkgrndset\fP,
852 \fBwborder_set\fP,
853 \fBwecho_wchar\fP,
854 \fBwecho_wchar\fP,
855 \fBwget_wch\fP,
856 \fBwget_wstr\fP,
857 \fBwgetbkgrnd\fP,
858 \fBwgetn_wstr\fP,
859 \fBwhline_set\fP,
860 \fBwin_wch\fP,
861 \fBwin_wchnstr\fP,
862 \fBwin_wchstr\fP,
863 \fBwinnwstr\fP,
864 \fBwins_nwstr\fP,
865 \fBwins_wch\fP,
866 \fBwins_wstr\fP,
867 \fBwinwchnstr\fP,
868 \fBwinwchstr\fP,
869 \fBwinwstr\fP,
870 \fBwunctrl\fP,
871 \fBwvline_set\fP,
872 .PP
873 A small number of local differences (that is, individual differences between
874 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
875 sections of the library man pages.
876 .PP
877 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
878 the \fBcurs_getch\fR(3X) manual page for details.
879 .PP
880 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.  See
881 the \fBcurs_slk\fR(3X) manual page for details.
882 .PP
883 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
884 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
885 part of XPG4, nor are they present in SVr4.  See the \fBcurs_mouse\fR(3X)
886 manual page for details.
887 .PP
888 The routine \fBmcprint\fR was not present in any previous curses
889 implementation.  See the \fBcurs_print\fR(3X) manual page for details.
890 .PP
891 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.  See
892 the \fBwresize\fR(3X) manual page for details.
893 .PP
894 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
895 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
896 bits in the UNIX tty driver.  In this implementation, all padding is done by
897 NUL sends.  This method is slightly more expensive, but narrows the interface
898 to the UNIX kernel significantly and increases the package's portability
899 correspondingly.
900 .PP
901 In the XSI standard and SVr4 manual pages, many entry points have prototype
902 arguments of the for \fBchar *const\fR (or \fBcchar_t *const\fR, or
903 \fBwchar_t *const\fR, or \fBvoid *const\fR).  Depending on one's interpretation of the
904 ANSI C standard (see section 3.5.4.1), these declarations are either (a)
905 meaningless, or (b) meaningless and illegal.  The declaration
906 \fBconst char *x\fR is a modifiable pointer to unmodifiable data, but
907 \fBchar *const x\fR' is
908 an unmodifiable pointer to modifiable data.  Given that C passes arguments by
909 value, \fB<type> *const\fR as a formal type is at best dubious.  Some compilers
910 choke on the prototypes.  Therefore, in this implementation, they have been
911 changed to \fBconst <type> *\fR globally.
912 .SH NOTES
913 The header file \fB<curses.h>\fR automatically includes the header files
914 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
915
916 If standard output from a \fBncurses\fR program is re-directed to something
917 which is not a tty, screen updates will be directed to standard error.  This
918 was an undocumented feature of AT&T System V Release 3 curses.
919 .SH AUTHORS
920 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
921 Based on pcurses by Pavel Curtis.
922 .\"#
923 .\"# The following sets edit modes for GNU EMACS
924 .\"# Local Variables:
925 .\"# mode:nroff
926 .\"# fill-column:79
927 .\"# End: