ebcaa40bb4e5333f8639364f9ed89e805cb62786
[ncurses.git] / man / ncurses.3x
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2006,2007 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.86 2007/04/07 23:08:08 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 This describes \fBncurses\fR
46 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
47 .PP
48 The \fBncurses\fR routines emulate the \fBcurses\fR(3X) library of System V
49 Release 4 UNIX, and the XPG4 curses standard (XSI curses) but the \fBncurses\fR
50 library is freely redistributable in source form.  Differences from the SVr4
51 curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
52 described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
53 of individual man pages.
54 .PP
55 A program using these routines must be linked with the \fB-lncurses\fR option,
56 or (if it has been generated) with the debugging library \fB-lncurses_g\fR.
57 (Your system integrator may also have installed these libraries under
58 the names \fB-lcurses\fR and \fB-lcurses_g\fR.)
59 The ncurses_g library generates trace logs (in a file called 'trace' in the
60 current directory) that describe curses actions.
61 See also the section on \fBALTERNATE CONFIGURATIONS\fP.
62 .PP
63 The \fBncurses\fR package supports: overall screen, window and pad
64 manipulation; output to windows and pads; reading terminal input; control over
65 terminal and \fBcurses\fR input and output options; environment query
66 routines; color manipulation; use of soft label keys; terminfo capabilities;
67 and access to low-level terminal-manipulation routines.
68 .PP
69 To initialize the routines, the routine \fBinitscr\fR or \fBnewterm\fR
70 must be called before any of the other routines that deal with windows
71 and screens are used.  The routine \fBendwin\fR must be called before
72 exiting.  To get character-at-a-time input without echoing (most
73 interactive, screen oriented programs want this), the following
74 sequence should be used:
75 .sp
76       \fBinitscr(); cbreak(); noecho();\fR
77 .sp
78 Most programs would additionally use the sequence:
79 .sp
80       \fBnonl();\fR
81       \fBintrflush(stdscr, FALSE);\fR
82       \fBkeypad(stdscr, TRUE);\fR
83 .sp
84 Before a \fBcurses\fR program is run, the tab stops of the terminal
85 should be set and its initialization strings, if defined, must be
86 output.  This can be done by executing the \fBtput init\fR command
87 after the shell environment variable \fBTERM\fR has been exported.
88 \fBtset(1)\fR is usually responsible for doing this.
89 [See \fBterminfo\fR(\*n) for further details.]
90 .PP
91 The \fBncurses\fR library permits manipulation of data structures,
92 called \fIwindows\fR, which can be thought of as two-dimensional
93 arrays of characters representing all or part of a CRT screen.  A
94 default window called \fBstdscr\fR, which is the size of the terminal
95 screen, is supplied.  Others may be created with \fBnewwin\fR.
96 .PP
97 Note that \fBcurses\fR does not handle overlapping windows, that's done by
98 the \fBpanel\fR(3X) library. This means that you can either use
99 \fBstdscr\fR or divide the screen into tiled windows and not using
100 \fBstdscr\fR at all. Mixing the two will result in unpredictable, and
101 undesired, effects.
102 .PP
103 Windows are referred to by variables declared as \fBWINDOW *\fR.
104 These data structures are manipulated with routines described here and
105 elsewhere in the \fBncurses\fR manual pages.  Among those, the most basic
106 routines are \fBmove\fR and \fBaddch\fR.  More general versions of
107 these routines are included with names beginning with \fBw\fR,
108 allowing the user to specify a window.  The routines not beginning
109 with \fBw\fR affect \fBstdscr\fR.
110 .PP
111 After using routines to manipulate a window, \fBrefresh\fR is called,
112 telling \fBcurses\fR to make the user's CRT screen look like
113 \fBstdscr\fR.  The characters in a window are actually of type
114 \fBchtype\fR, (character and attribute data) so that other information
115 about the character may also be stored with each character.
116 .PP
117 Special windows called \fIpads\fR may also be manipulated.  These are windows
118 which are not constrained to the size of the screen and whose contents need not
119 be completely displayed.  See \fBcurs_pad\fR(3X) for more information.
120 .PP
121 In addition to drawing characters on the screen, video attributes and colors
122 may be supported, causing the characters to show up in such modes as
123 underlined, in reverse video, or in color on terminals that support such
124 display enhancements.  Line drawing characters may be specified to be output.
125 On input, \fBcurses\fR is also able to translate arrow and function keys that
126 transmit escape sequences into single values.  The video attributes, line
127 drawing characters, and input values use names, defined in \fB<curses.h>\fR,
128 such as \fBA_REVERSE\fR, \fBACS_HLINE\fR, and \fBKEY_LEFT\fR.
129 .PP
130 If the environment variables \fBLINES\fR and \fBCOLUMNS\fR are set, or if the
131 program is executing in a window environment, line and column information in
132 the environment will override information read by \fIterminfo\fR.  This would
133 effect a program running in an AT&T 630 layer, for example, where the size of a
134 screen is changeable (see \fBENVIRONMENT\fR).
135 .PP
136 If the environment variable \fBTERMINFO\fR is defined, any program using
137 \fBcurses\fR checks for a local terminal definition before checking in the
138 standard place.  For example, if \fBTERM\fR is set to \fBatt4424\fR, then the
139 compiled terminal definition is found in
140 .sp
141       \fB\*d/a/att4424\fR.
142 .sp
143 (The \fBa\fR is copied from the first letter of \fBatt4424\fR to avoid
144 creation of huge directories.)  However, if \fBTERMINFO\fR is set to
145 \fB$HOME/myterms\fR, \fBcurses\fR first checks
146 .sp
147       \fB$HOME/myterms/a/att4424\fR,
148 .sp
149 and if that fails, it then checks
150 .sp
151       \fB\*d/a/att4424\fR.
152 .sp
153 This is useful for developing experimental definitions or when write
154 permission in \fB\*d\fR is not available.
155 .PP
156 The integer variables \fBLINES\fR and \fBCOLS\fR are defined in
157 \fB<curses.h>\fR and will be filled in by \fBinitscr\fR with the size of the
158 screen.  The constants \fBTRUE\fR and \fBFALSE\fR have the values \fB1\fR and
159 \fB0\fR, respectively.
160 .PP
161 The \fBcurses\fR routines also define the \fBWINDOW *\fR variable \fBcurscr\fR
162 which is used for certain low-level operations like clearing and redrawing a
163 screen containing garbage.  The \fBcurscr\fR can be used in only a few
164 routines.
165 .
166 .SS Routine and Argument Names
167 Many \fBcurses\fR routines have two or more versions.  The routines prefixed
168 with \fBw\fR require a window argument.  The routines prefixed with \fBp\fR
169 require a pad argument.  Those without a prefix generally use \fBstdscr\fR.
170 .PP
171 The routines prefixed with \fBmv\fR require a \fIy\fR and \fIx\fR
172 coordinate to move to before performing the appropriate action.  The
173 \fBmv\fR routines imply a call to \fBmove\fR before the call to the
174 other routine.  The coordinate \fIy\fR always refers to the row (of
175 the window), and \fIx\fR always refers to the column.  The upper
176 left-hand corner is always (0,0), not (1,1).
177 .PP
178 The routines prefixed with \fBmvw\fR take both a window argument and
179 \fIx\fR and \fIy\fR coordinates.  The window argument is always
180 specified before the coordinates.
181 .PP
182 In each case, \fIwin\fR is the window affected, and \fIpad\fR is the
183 pad affected; \fIwin\fR and \fIpad\fR are always pointers to type
184 \fBWINDOW\fR.
185 .PP
186 Option setting routines require a Boolean flag \fIbf\fR with the value
187 \fBTRUE\fR or \fBFALSE\fR; \fIbf\fR is always of type \fBbool\fR.  The
188 variables \fIch\fR and \fIattrs\fR below are always of type
189 \fBchtype\fR.  The types \fBWINDOW\fR, \fBSCREEN\fR, \fBbool\fR, and
190 \fBchtype\fR are defined in \fB<curses.h>\fR.  The type \fBTERMINAL\fR
191 is defined in \fB<term.h>\fR.  All other arguments are integers.
192 .SS Routine Name Index
193 The following table lists each \fBcurses\fR routine and the name of
194 the manual page on which it is described.  Routines flagged with `*'
195 are ncurses-specific, not described by XPG4 or present in SVr4.
196 .PP
197 .TS
198 center tab(/);
199 l l
200 l l .
201 \fBcurses\fR Routine Name/Manual Page Name
202 =
203 COLOR_PAIR/\fBcurs_color\fR(3X)
204 PAIR_NUMBER/\fBcurs_attr\fR(3X)
205 _nc_tracebits/\fBcurs_trace\fR(3X)*
206 _traceattr/\fBcurs_trace\fR(3X)*
207 _traceattr2/\fBcurs_trace\fR(3X)*
208 _tracechar/\fBcurs_trace\fR(3X)*
209 _tracechtype/\fBcurs_trace\fR(3X)*
210 _tracechtype2/\fBcurs_trace\fR(3X)*
211 _tracedump/\fBcurs_trace\fR(3X)*
212 _tracef/\fBcurs_trace\fR(3X)*
213 _tracemouse/\fBcurs_trace\fR(3X)*
214 add_wch/\fBcurs_add_wch\fR(3X)
215 add_wchnstr/\fBcurs_add_wchstr\fR(3X)
216 add_wchstr/\fBcurs_add_wchstr\fR(3X)
217 addch/\fBcurs_addch\fR(3X)
218 addchnstr/\fBcurs_addchstr\fR(3X)
219 addchstr/\fBcurs_addchstr\fR(3X)
220 addnstr/\fBcurs_addstr\fR(3X)
221 addnwstr/\fBcurs_addwstr\fR(3X)
222 addstr/\fBcurs_addstr\fR(3X)
223 addwstr/\fBcurs_addwstr\fR(3X)
224 assume_default_colors/\fBdefault_colors\fR(3X)*
225 attr_get/\fBcurs_attr\fR(3X)
226 attr_off/\fBcurs_attr\fR(3X)
227 attr_on/\fBcurs_attr\fR(3X)
228 attr_set/\fBcurs_attr\fR(3X)
229 attroff/\fBcurs_attr\fR(3X)
230 attron/\fBcurs_attr\fR(3X)
231 attrset/\fBcurs_attr\fR(3X)
232 baudrate/\fBcurs_termattrs\fR(3X)
233 beep/\fBcurs_beep\fR(3X)
234 bkgd/\fBcurs_bkgd\fR(3X)
235 bkgdset/\fBcurs_bkgd\fR(3X)
236 bkgrnd/\fBcurs_bkgrnd\fR(3X)
237 bkgrndset/\fBcurs_bkgrnd\fR(3X)
238 border/\fBcurs_border\fR(3X)
239 border_set/\fBcurs_border_set\fR(3X)
240 box/\fBcurs_border\fR(3X)
241 box_set/\fBcurs_border_set\fR(3X)
242 can_change_color/\fBcurs_color\fR(3X)
243 cbreak/\fBcurs_inopts\fR(3X)
244 chgat/\fBcurs_attr\fR(3X)
245 clear/\fBcurs_clear\fR(3X)
246 clearok/\fBcurs_outopts\fR(3X)
247 clrtobot/\fBcurs_clear\fR(3X)
248 clrtoeol/\fBcurs_clear\fR(3X)
249 color_content/\fBcurs_color\fR(3X)
250 color_set/\fBcurs_attr\fR(3X)
251 copywin/\fBcurs_overlay\fR(3X)
252 curs_set/\fBcurs_kernel\fR(3X)
253 curses_version/\fBcurs_extend\fR(3X)*
254 def_prog_mode/\fBcurs_kernel\fR(3X)
255 def_shell_mode/\fBcurs_kernel\fR(3X)
256 define_key/\fBdefine_key\fR(3X)*
257 del_curterm/\fBcurs_terminfo\fR(3X)
258 delay_output/\fBcurs_util\fR(3X)
259 delch/\fBcurs_delch\fR(3X)
260 deleteln/\fBcurs_deleteln\fR(3X)
261 delscreen/\fBcurs_initscr\fR(3X)
262 delwin/\fBcurs_window\fR(3X)
263 derwin/\fBcurs_window\fR(3X)
264 doupdate/\fBcurs_refresh\fR(3X)
265 dupwin/\fBcurs_window\fR(3X)
266 echo/\fBcurs_inopts\fR(3X)
267 echo_wchar/\fBcurs_add_wch\fR(3X)
268 echochar/\fBcurs_addch\fR(3X)
269 endwin/\fBcurs_initscr\fR(3X)
270 erase/\fBcurs_clear\fR(3X)
271 erasechar/\fBcurs_termattrs\fR(3X)
272 erasewchar/\fBcurs_termattrs\fR(3X)
273 filter/\fBcurs_util\fR(3X)
274 flash/\fBcurs_beep\fR(3X)
275 flushinp/\fBcurs_util\fR(3X)
276 get_wch/\fBcurs_get_wch\fR(3X)
277 get_wstr/\fBcurs_get_wstr\fR(3X)
278 getattrs/\fBcurs_attr\fR(3X)
279 getbegx/\fBcurs_legacy\fR(3X)*
280 getbegy/\fBcurs_legacy\fR(3X)*
281 getbegyx/\fBcurs_getyx\fR(3X)
282 getbkgd/\fBcurs_bkgd\fR(3X)
283 getbkgrnd/\fBcurs_bkgrnd\fR(3X)
284 getcchar/\fBcurs_getcchar\fR(3X)
285 getch/\fBcurs_getch\fR(3X)
286 getcurx/\fBcurs_legacy\fR(3X)*
287 getcury/\fBcurs_legacy\fR(3X)*
288 getmaxx/\fBcurs_legacy\fR(3X)*
289 getmaxy/\fBcurs_legacy\fR(3X)*
290 getmaxyx/\fBcurs_getyx\fR(3X)
291 getmouse/\fBcurs_mouse\fR(3X)*
292 getn_wstr/\fBcurs_get_wstr\fR(3X)
293 getnstr/\fBcurs_getstr\fR(3X)
294 getparx/\fBcurs_legacy\fR(3X)*
295 getpary/\fBcurs_legacy\fR(3X)*
296 getparyx/\fBcurs_getyx\fR(3X)
297 getstr/\fBcurs_getstr\fR(3X)
298 getsyx/\fBcurs_kernel\fR(3X)
299 getwin/\fBcurs_util\fR(3X)
300 getyx/\fBcurs_getyx\fR(3X)
301 halfdelay/\fBcurs_inopts\fR(3X)
302 has_colors/\fBcurs_color\fR(3X)
303 has_ic/\fBcurs_termattrs\fR(3X)
304 has_il/\fBcurs_termattrs\fR(3X)
305 has_key/\fBcurs_getch\fR(3X)*
306 hline/\fBcurs_border\fR(3X)
307 hline_set/\fBcurs_border_set\fR(3X)
308 idcok/\fBcurs_outopts\fR(3X)
309 idlok/\fBcurs_outopts\fR(3X)
310 immedok/\fBcurs_outopts\fR(3X)
311 in_wch/\fBcurs_in_wch\fR(3X)
312 in_wchnstr/\fBcurs_in_wchstr\fR(3X)
313 in_wchstr/\fBcurs_in_wchstr\fR(3X)
314 inch/\fBcurs_inch\fR(3X)
315 inchnstr/\fBcurs_inchstr\fR(3X)
316 inchstr/\fBcurs_inchstr\fR(3X)
317 init_color/\fBcurs_color\fR(3X)
318 init_pair/\fBcurs_color\fR(3X)
319 initscr/\fBcurs_initscr\fR(3X)
320 innstr/\fBcurs_instr\fR(3X)
321 innwstr/\fBcurs_inwstr\fR(3X)
322 ins_nwstr/\fBcurs_ins_wstr\fR(3X)
323 ins_wch/\fBcurs_ins_wch\fR(3X)
324 ins_wstr/\fBcurs_ins_wstr\fR(3X)
325 insch/\fBcurs_insch\fR(3X)
326 insdelln/\fBcurs_deleteln\fR(3X)
327 insertln/\fBcurs_deleteln\fR(3X)
328 insnstr/\fBcurs_insstr\fR(3X)
329 insstr/\fBcurs_insstr\fR(3X)
330 instr/\fBcurs_instr\fR(3X)
331 intrflush/\fBcurs_inopts\fR(3X)
332 inwstr/\fBcurs_inwstr\fR(3X)
333 is_cleared/\fBcurs_opaque\fR(3X)*
334 is_idcok/\fBcurs_opaque\fR(3X)*
335 is_idlok/\fBcurs_opaque\fR(3X)*
336 is_immedok/\fBcurs_opaque\fR(3X)*
337 is_keypad/\fBcurs_opaque\fR(3X)*
338 is_leaveok/\fBcurs_opaque\fR(3X)*
339 is_linetouched/\fBcurs_touch\fR(3X)
340 is_nodelay/\fBcurs_opaque\fR(3X)*
341 is_notimeout/\fBcurs_opaque\fR(3X)*
342 is_scrollok/\fBcurs_opaque\fR(3X)*
343 is_syncok/\fBcurs_opaque\fR(3X)*
344 is_term_resized/\fBresizeterm\fR(3X)*
345 is_wintouched/\fBcurs_touch\fR(3X)
346 isendwin/\fBcurs_initscr\fR(3X)
347 key_defined/\fBkey_defined\fR(3X)*
348 key_name/\fBcurs_util\fR(3X)
349 keybound/\fBkeybound\fR(3X)*
350 keyname/\fBcurs_util\fR(3X)
351 keyok/\fBkeyok\fR(3X)*
352 keypad/\fBcurs_inopts\fR(3X)
353 killchar/\fBcurs_termattrs\fR(3X)
354 killwchar/\fBcurs_termattrs\fR(3X)
355 leaveok/\fBcurs_outopts\fR(3X)
356 longname/\fBcurs_termattrs\fR(3X)
357 mcprint/\fBcurs_print\fR(3X)*
358 meta/\fBcurs_inopts\fR(3X)
359 mouse_trafo/\fBcurs_mouse\fR(3X)*
360 mouseinterval/\fBcurs_mouse\fR(3X)*
361 mousemask/\fBcurs_mouse\fR(3X)*
362 move/\fBcurs_move\fR(3X)
363 mvadd_wch/\fBcurs_add_wch\fR(3X)
364 mvadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
365 mvadd_wchstr/\fBcurs_add_wchstr\fR(3X)
366 mvaddch/\fBcurs_addch\fR(3X)
367 mvaddchnstr/\fBcurs_addchstr\fR(3X)
368 mvaddchstr/\fBcurs_addchstr\fR(3X)
369 mvaddnstr/\fBcurs_addstr\fR(3X)
370 mvaddnwstr/\fBcurs_addwstr\fR(3X)
371 mvaddstr/\fBcurs_addstr\fR(3X)
372 mvaddwstr/\fBcurs_addwstr\fR(3X)
373 mvchgat/\fBcurs_attr\fR(3X)
374 mvcur/\fBcurs_terminfo\fR(3X)
375 mvdelch/\fBcurs_delch\fR(3X)
376 mvderwin/\fBcurs_window\fR(3X)
377 mvget_wch/\fBcurs_get_wch\fR(3X)
378 mvget_wstr/\fBcurs_get_wstr\fR(3X)
379 mvgetch/\fBcurs_getch\fR(3X)
380 mvgetn_wstr/\fBcurs_get_wstr\fR(3X)
381 mvgetnstr/\fBcurs_getstr\fR(3X)
382 mvgetstr/\fBcurs_getstr\fR(3X)
383 mvhline/\fBcurs_border\fR(3X)
384 mvhline_set/\fBcurs_border_set\fR(3X)
385 mvin_wch/\fBcurs_in_wch\fR(3X)
386 mvin_wchnstr/\fBcurs_in_wchstr\fR(3X)
387 mvin_wchstr/\fBcurs_in_wchstr\fR(3X)
388 mvinch/\fBcurs_inch\fR(3X)
389 mvinchnstr/\fBcurs_inchstr\fR(3X)
390 mvinchstr/\fBcurs_inchstr\fR(3X)
391 mvinnstr/\fBcurs_instr\fR(3X)
392 mvinnwstr/\fBcurs_inwstr\fR(3X)
393 mvins_nwstr/\fBcurs_ins_wstr\fR(3X)
394 mvins_wch/\fBcurs_ins_wch\fR(3X)
395 mvins_wstr/\fBcurs_ins_wstr\fR(3X)
396 mvinsch/\fBcurs_insch\fR(3X)
397 mvinsnstr/\fBcurs_insstr\fR(3X)
398 mvinsstr/\fBcurs_insstr\fR(3X)
399 mvinstr/\fBcurs_instr\fR(3X)
400 mvinwstr/\fBcurs_inwstr\fR(3X)
401 mvprintw/\fBcurs_printw\fR(3X)
402 mvscanw/\fBcurs_scanw\fR(3X)
403 mvvline/\fBcurs_border\fR(3X)
404 mvvline_set/\fBcurs_border_set\fR(3X)
405 mvwadd_wch/\fBcurs_add_wch\fR(3X)
406 mvwadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
407 mvwadd_wchstr/\fBcurs_add_wchstr\fR(3X)
408 mvwaddch/\fBcurs_addch\fR(3X)
409 mvwaddchnstr/\fBcurs_addchstr\fR(3X)
410 mvwaddchstr/\fBcurs_addchstr\fR(3X)
411 mvwaddnstr/\fBcurs_addstr\fR(3X)
412 mvwaddnwstr/\fBcurs_addwstr\fR(3X)
413 mvwaddstr/\fBcurs_addstr\fR(3X)
414 mvwaddwstr/\fBcurs_addwstr\fR(3X)
415 mvwchgat/\fBcurs_attr\fR(3X)
416 mvwdelch/\fBcurs_delch\fR(3X)
417 mvwget_wch/\fBcurs_get_wch\fR(3X)
418 mvwget_wstr/\fBcurs_get_wstr\fR(3X)
419 mvwgetch/\fBcurs_getch\fR(3X)
420 mvwgetn_wstr/\fBcurs_get_wstr\fR(3X)
421 mvwgetnstr/\fBcurs_getstr\fR(3X)
422 mvwgetstr/\fBcurs_getstr\fR(3X)
423 mvwhline/\fBcurs_border\fR(3X)
424 mvwhline_set/\fBcurs_border_set\fR(3X)
425 mvwin/\fBcurs_window\fR(3X)
426 mvwin_wch/\fBcurs_in_wch\fR(3X)
427 mvwin_wchnstr/\fBcurs_in_wchstr\fR(3X)
428 mvwin_wchstr/\fBcurs_in_wchstr\fR(3X)
429 mvwinch/\fBcurs_inch\fR(3X)
430 mvwinchnstr/\fBcurs_inchstr\fR(3X)
431 mvwinchstr/\fBcurs_inchstr\fR(3X)
432 mvwinnstr/\fBcurs_instr\fR(3X)
433 mvwinnwstr/\fBcurs_inwstr\fR(3X)
434 mvwins_nwstr/\fBcurs_ins_wstr\fR(3X)
435 mvwins_wch/\fBcurs_ins_wch\fR(3X)
436 mvwins_wstr/\fBcurs_ins_wstr\fR(3X)
437 mvwinsch/\fBcurs_insch\fR(3X)
438 mvwinsnstr/\fBcurs_insstr\fR(3X)
439 mvwinsstr/\fBcurs_insstr\fR(3X)
440 mvwinstr/\fBcurs_instr\fR(3X)
441 mvwinwstr/\fBcurs_inwstr\fR(3X)
442 mvwprintw/\fBcurs_printw\fR(3X)
443 mvwscanw/\fBcurs_scanw\fR(3X)
444 mvwvline/\fBcurs_border\fR(3X)
445 mvwvline_set/\fBcurs_border_set\fR(3X)
446 napms/\fBcurs_kernel\fR(3X)
447 newpad/\fBcurs_pad\fR(3X)
448 newterm/\fBcurs_initscr\fR(3X)
449 newwin/\fBcurs_window\fR(3X)
450 nl/\fBcurs_outopts\fR(3X)
451 nocbreak/\fBcurs_inopts\fR(3X)
452 nodelay/\fBcurs_inopts\fR(3X)
453 noecho/\fBcurs_inopts\fR(3X)
454 nofilter/\fBcurs_util\fR(3X)*
455 nonl/\fBcurs_outopts\fR(3X)
456 noqiflush/\fBcurs_inopts\fR(3X)
457 noraw/\fBcurs_inopts\fR(3X)
458 notimeout/\fBcurs_inopts\fR(3X)
459 overlay/\fBcurs_overlay\fR(3X)
460 overwrite/\fBcurs_overlay\fR(3X)
461 pair_content/\fBcurs_color\fR(3X)
462 pechochar/\fBcurs_pad\fR(3X)
463 pnoutrefresh/\fBcurs_pad\fR(3X)
464 prefresh/\fBcurs_pad\fR(3X)
465 printw/\fBcurs_printw\fR(3X)
466 putp/\fBcurs_terminfo\fR(3X)
467 putwin/\fBcurs_util\fR(3X)
468 qiflush/\fBcurs_inopts\fR(3X)
469 raw/\fBcurs_inopts\fR(3X)
470 redrawwin/\fBcurs_refresh\fR(3X)
471 refresh/\fBcurs_refresh\fR(3X)
472 reset_prog_mode/\fBcurs_kernel\fR(3X)
473 reset_shell_mode/\fBcurs_kernel\fR(3X)
474 resetty/\fBcurs_kernel\fR(3X)
475 resizeterm/\fBresizeterm\fR(3X)*
476 restartterm/\fBcurs_terminfo\fR(3X)
477 ripoffline/\fBcurs_kernel\fR(3X)
478 savetty/\fBcurs_kernel\fR(3X)
479 scanw/\fBcurs_scanw\fR(3X)
480 scr_dump/\fBcurs_scr_dump\fR(3X)
481 scr_init/\fBcurs_scr_dump\fR(3X)
482 scr_restore/\fBcurs_scr_dump\fR(3X)
483 scr_set/\fBcurs_scr_dump\fR(3X)
484 scrl/\fBcurs_scroll\fR(3X)
485 scroll/\fBcurs_scroll\fR(3X)
486 scrollok/\fBcurs_outopts\fR(3X)
487 set_curterm/\fBcurs_terminfo\fR(3X)
488 set_term/\fBcurs_initscr\fR(3X)
489 setcchar/\fBcurs_getcchar\fR(3X)
490 setscrreg/\fBcurs_outopts\fR(3X)
491 setsyx/\fBcurs_kernel\fR(3X)
492 setterm/\fBcurs_terminfo\fR(3X)
493 setupterm/\fBcurs_terminfo\fR(3X)
494 slk_attr/\fBcurs_slk\fR(3X)*
495 slk_attr_off/\fBcurs_slk\fR(3X)
496 slk_attr_on/\fBcurs_slk\fR(3X)
497 slk_attr_set/\fBcurs_slk\fR(3X)
498 slk_attroff/\fBcurs_slk\fR(3X)
499 slk_attron/\fBcurs_slk\fR(3X)
500 slk_attrset/\fBcurs_slk\fR(3X)
501 slk_clear/\fBcurs_slk\fR(3X)
502 slk_color/\fBcurs_slk\fR(3X)
503 slk_init/\fBcurs_slk\fR(3X)
504 slk_label/\fBcurs_slk\fR(3X)
505 slk_noutrefresh/\fBcurs_slk\fR(3X)
506 slk_refresh/\fBcurs_slk\fR(3X)
507 slk_restore/\fBcurs_slk\fR(3X)
508 slk_set/\fBcurs_slk\fR(3X)
509 slk_touch/\fBcurs_slk\fR(3X)
510 standend/\fBcurs_attr\fR(3X)
511 standout/\fBcurs_attr\fR(3X)
512 start_color/\fBcurs_color\fR(3X)
513 subpad/\fBcurs_pad\fR(3X)
514 subwin/\fBcurs_window\fR(3X)
515 syncok/\fBcurs_window\fR(3X)
516 term_attrs/\fBcurs_termattrs\fR(3X)
517 termattrs/\fBcurs_termattrs\fR(3X)
518 termname/\fBcurs_termattrs\fR(3X)
519 tgetent/\fBcurs_termcap\fR(3X)
520 tgetflag/\fBcurs_termcap\fR(3X)
521 tgetnum/\fBcurs_termcap\fR(3X)
522 tgetstr/\fBcurs_termcap\fR(3X)
523 tgoto/\fBcurs_termcap\fR(3X)
524 tigetflag/\fBcurs_terminfo\fR(3X)
525 tigetnum/\fBcurs_terminfo\fR(3X)
526 tigetstr/\fBcurs_terminfo\fR(3X)
527 timeout/\fBcurs_inopts\fR(3X)
528 touchline/\fBcurs_touch\fR(3X)
529 touchwin/\fBcurs_touch\fR(3X)
530 tparm/\fBcurs_terminfo\fR(3X)
531 tputs/\fBcurs_termcap\fR(3X)
532 tputs/\fBcurs_terminfo\fR(3X)
533 trace/\fBcurs_trace\fR(3X)*
534 typeahead/\fBcurs_inopts\fR(3X)
535 unctrl/\fBcurs_util\fR(3X)
536 unget_wch/\fBcurs_get_wch\fR(3X)
537 ungetch/\fBcurs_getch\fR(3X)
538 ungetmouse/\fBcurs_mouse\fR(3X)*
539 untouchwin/\fBcurs_touch\fR(3X)
540 use_default_colors/\fBdefault_colors\fR(3X)*
541 use_env/\fBcurs_util\fR(3X)
542 use_extended_names/\fBcurs_extend\fR(3X)*
543 use_legacy_coding/\fBlegacy_coding\fR(3X)*
544 vid_attr/\fBcurs_terminfo\fR(3X)
545 vid_puts/\fBcurs_terminfo\fR(3X)
546 vidattr/\fBcurs_terminfo\fR(3X)
547 vidputs/\fBcurs_terminfo\fR(3X)
548 vline/\fBcurs_border\fR(3X)
549 vline_set/\fBcurs_border_set\fR(3X)
550 vw_printw/\fBcurs_printw\fR(3X)
551 vw_scanw/\fBcurs_scanw\fR(3X)
552 vwprintw/\fBcurs_printw\fR(3X)
553 vwscanw/\fBcurs_scanw\fR(3X)
554 wadd_wch/\fBcurs_add_wch\fR(3X)
555 wadd_wchnstr/\fBcurs_add_wchstr\fR(3X)
556 wadd_wchstr/\fBcurs_add_wchstr\fR(3X)
557 waddch/\fBcurs_addch\fR(3X)
558 waddchnstr/\fBcurs_addchstr\fR(3X)
559 waddchstr/\fBcurs_addchstr\fR(3X)
560 waddnstr/\fBcurs_addstr\fR(3X)
561 waddnwstr/\fBcurs_addwstr\fR(3X)
562 waddstr/\fBcurs_addstr\fR(3X)
563 waddwstr/\fBcurs_addwstr\fR(3X)
564 wattr_get/\fBcurs_attr\fR(3X)
565 wattr_off/\fBcurs_attr\fR(3X)
566 wattr_on/\fBcurs_attr\fR(3X)
567 wattr_set/\fBcurs_attr\fR(3X)
568 wattroff/\fBcurs_attr\fR(3X)
569 wattron/\fBcurs_attr\fR(3X)
570 wattrset/\fBcurs_attr\fR(3X)
571 wbkgd/\fBcurs_bkgd\fR(3X)
572 wbkgdset/\fBcurs_bkgd\fR(3X)
573 wbkgrnd/\fBcurs_bkgrnd\fR(3X)
574 wbkgrndset/\fBcurs_bkgrnd\fR(3X)
575 wborder/\fBcurs_border\fR(3X)
576 wborder_set/\fBcurs_border_set\fR(3X)
577 wchgat/\fBcurs_attr\fR(3X)
578 wclear/\fBcurs_clear\fR(3X)
579 wclrtobot/\fBcurs_clear\fR(3X)
580 wclrtoeol/\fBcurs_clear\fR(3X)
581 wcolor_set/\fBcurs_attr\fR(3X)
582 wcursyncup/\fBcurs_window\fR(3X)
583 wdelch/\fBcurs_delch\fR(3X)
584 wdeleteln/\fBcurs_deleteln\fR(3X)
585 wecho_wchar/\fBcurs_add_wch\fR(3X)
586 wechochar/\fBcurs_addch\fR(3X)
587 wenclose/\fBcurs_mouse\fR(3X)*
588 werase/\fBcurs_clear\fR(3X)
589 wget_wch/\fBcurs_get_wch\fR(3X)
590 wget_wstr/\fBcurs_get_wstr\fR(3X)
591 wgetbkgrnd/\fBcurs_bkgrnd\fR(3X)
592 wgetch/\fBcurs_getch\fR(3X)
593 wgetn_wstr/\fBcurs_get_wstr\fR(3X)
594 wgetnstr/\fBcurs_getstr\fR(3X)
595 wgetstr/\fBcurs_getstr\fR(3X)
596 whline/\fBcurs_border\fR(3X)
597 whline_set/\fBcurs_border_set\fR(3X)
598 win_wch/\fBcurs_in_wch\fR(3X)
599 win_wchnstr/\fBcurs_in_wchstr\fR(3X)
600 win_wchstr/\fBcurs_in_wchstr\fR(3X)
601 winch/\fBcurs_inch\fR(3X)
602 winchnstr/\fBcurs_inchstr\fR(3X)
603 winchstr/\fBcurs_inchstr\fR(3X)
604 winnstr/\fBcurs_instr\fR(3X)
605 winnwstr/\fBcurs_inwstr\fR(3X)
606 wins_nwstr/\fBcurs_ins_wstr\fR(3X)
607 wins_wch/\fBcurs_ins_wch\fR(3X)
608 wins_wstr/\fBcurs_ins_wstr\fR(3X)
609 winsch/\fBcurs_insch\fR(3X)
610 winsdelln/\fBcurs_deleteln\fR(3X)
611 winsertln/\fBcurs_deleteln\fR(3X)
612 winsnstr/\fBcurs_insstr\fR(3X)
613 winsstr/\fBcurs_insstr\fR(3X)
614 winstr/\fBcurs_instr\fR(3X)
615 winwstr/\fBcurs_inwstr\fR(3X)
616 wmouse_trafo/\fBcurs_mouse\fR(3X)*
617 wmove/\fBcurs_move\fR(3X)
618 wnoutrefresh/\fBcurs_refresh\fR(3X)
619 wprintw/\fBcurs_printw\fR(3X)
620 wredrawln/\fBcurs_refresh\fR(3X)
621 wrefresh/\fBcurs_refresh\fR(3X)
622 wresize/\fBwresize\fR(3X)*
623 wscanw/\fBcurs_scanw\fR(3X)
624 wscrl/\fBcurs_scroll\fR(3X)
625 wsetscrreg/\fBcurs_outopts\fR(3X)
626 wstandend/\fBcurs_attr\fR(3X)
627 wstandout/\fBcurs_attr\fR(3X)
628 wsyncdown/\fBcurs_window\fR(3X)
629 wsyncup/\fBcurs_window\fR(3X)
630 wtimeout/\fBcurs_inopts\fR(3X)
631 wtouchln/\fBcurs_touch\fR(3X)
632 wunctrl/\fBcurs_util\fR(3X)
633 wvline/\fBcurs_border\fR(3X)
634 wvline_set/\fBcurs_border_set\fR(3X)
635 .TE
636 .SH RETURN VALUE
637 Routines that return an integer return \fBERR\fR upon failure and an
638 integer value other than \fBERR\fR upon successful completion, unless
639 otherwise noted in the routine descriptions.
640 .PP
641 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
642 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.  The return
643 values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
644 \fBgetmaxyx\fR are undefined (i.e., these should not be used as the
645 right-hand side of assignment statements).
646 .PP
647 Routines that return pointers return \fBNULL\fR on error.
648 .SH ENVIRONMENT
649 The following environment symbols are useful for customizing the
650 runtime behavior of the \fBncurses\fR library.  The most important
651 ones have been already discussed in detail.
652 .TP 5
653 BAUDRATE
654 The debugging library checks this environment symbol when the application
655 has redirected output to a file.
656 The symbol's numeric value is used for the baudrate.
657 If no value is found, \fBncurses\fR uses 9600.
658 This allows testers to construct repeatable test-cases
659 that take into account costs that depend on baudrate.
660 .TP 5
661 CC
662 When set, change occurrences of the command_character
663 (i.e., the \fBcmdch\fP capability)
664 of the loaded terminfo entries to the value of this symbol.
665 Very few terminfo entries provide this feature.
666 .TP 5
667 COLUMNS
668 Specify the width of the screen in characters.
669 Applications running in a windowing environment usually are able to
670 obtain the width of the window in which they are executing.
671 If neither the \fBCOLUMNS\fP value nor the terminal's screen size is available,
672 \fBncurses\fR uses the size which may be specified in the terminfo database
673 (i.e., the \fBcols\fR capability).
674 .IP
675 It is important that your application use a correct size for the screen.
676 This is not always possible because your application may be
677 running on a host which does not honor NAWS (Negotiations About Window
678 Size), or because you are temporarily running as another user.
679 However, setting \fBCOLUMNS\fP and/or \fBLINES\fP overrides the library's
680 use of the screen size obtained from the operating system.
681 .IP
682 Either \fBCOLUMNS\fP or \fBLINES\fP symbols may be specified independently.
683 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
684 e.g., xterm which commonly specifies a 65 line screen.
685 For best results, \fBlines\fR and \fBcols\fR should not be specified in
686 a terminal description for terminals which are run as emulations.
687 .IP
688 Use the \fBuse_env\fR function to disable all use of external environment
689 (including system calls) to determine the screen size.
690 .TP 5
691 ESCDELAY
692 Specifies the total time, in milliseconds, for which ncurses will
693 await a character sequence, e.g., a function key.
694 The default value, 1000 milliseconds, is enough for most uses.
695 However, it is made a variable to accommodate unusual applications.
696 .IP
697 The most common instance where you may wish to change this value
698 is to work with slow hosts, e.g., running on a network.
699 If the host cannot read characters rapidly enough, it will have the same
700 effect as if the terminal did not send characters rapidly enough.
701 The library will still see a timeout.
702 .IP
703 Note that xterm mouse events are built up from character sequences
704 received from the xterm.
705 If your application makes heavy use of multiple-clicking, you may
706 wish to lengthen this default value because the timeout applies
707 to the composed multi-click event as well as the individual clicks.
708 .IP
709 In addition to the environment variable,
710 this implementation provides a global variable with the same name.
711 Portable applications should not rely upon the presence of ESCDELAY
712 in either form,
713 but setting the environment variable rather than the global variable
714 does not create problems when compiling an application.
715 .TP 5
716 HOME
717 Tells \fBncurses\fR where your home directory is.
718 That is where it may read and write auxiliary terminal descriptions:
719 .IP
720 $HOME/.termcap
721 .br
722 $HOME/.terminfo
723 .TP 5
724 LINES
725 Like COLUMNS, specify the height of the screen in characters.
726 See COLUMNS for a detailed description.
727 .TP 5
728 MOUSE_BUTTONS_123
729 This applies only to the OS/2 EMX port.
730 It specifies the order of buttons on the mouse.
731 OS/2 numbers a 3-button mouse inconsistently from other
732 platforms:
733 .sp
734 1 = left
735 .br
736 2 = right
737 .br
738 3 = middle.
739 .sp
740 This symbol lets you customize the mouse.
741 The symbol must be three numeric digits 1-3 in any order, e.g., 123 or 321.
742 If it is not specified, \fBncurses\fR uses 132.
743 .TP 5
744 NCURSES_ASSUMED_COLORS
745 Override the compiled-in assumption that the
746 terminal's default colors are white-on-black
747 (see \fBdefault_colors\fR(3X)).
748 You may set the foreground and background color values with this environment
749 variable by proving a 2-element list: foreground,background.
750 For example, to tell ncurses to not assume anything
751 about the colors, set this to "-1,-1".
752 To make it green-on-black, set it to "2,0".
753 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
754 .TP 5
755 NCURSES_NO_HARD_TABS
756 \fBNcurses\fP may use tabs as part of the cursor movement optimization.
757 In some cases,
758 your terminal driver may not handle these properly.
759 Set this environment variable to disable the feature.
760 You can also adjust your \fBstty\fP settings to avoid the problem.
761 .TP 5
762 NCURSES_NO_MAGIC_COOKIES
763 Some terminals use a magic-cookie feature which requires special handling
764 to make highlighting and other video attributes display properly. 
765 You can suppress the highlighting entirely for these terminals by
766 setting this environment variable.
767 .TP 5
768 NCURSES_NO_PADDING
769 Most of the terminal descriptions in the terminfo database are written
770 for real "hardware" terminals.
771 Many people use terminal emulators
772 which run in a windowing environment and use curses-based applications.
773 Terminal emulators can duplicate
774 all of the important aspects of a hardware terminal, but they do not
775 have the same limitations.
776 The chief limitation of a hardware terminal from the standpoint
777 of your application is the management of dataflow, i.e., timing.
778 Unless a hardware terminal is interfaced into a terminal concentrator
779 (which does flow control),
780 it (or your application) must manage dataflow, preventing overruns.
781 The cheapest solution (no hardware cost)
782 is for your program to do this by pausing after
783 operations that the terminal does slowly, such as clearing the display.
784 .IP
785 As a result, many terminal descriptions (including the vt100)
786 have delay times embedded.  You may wish to use these descriptions,
787 but not want to pay the performance penalty.
788 .IP
789 Set the NCURSES_NO_PADDING symbol to disable all but mandatory
790 padding.  Mandatory padding is used as a part of special control
791 sequences such as \fIflash\fR.
792 .TP 5
793 NCURSES_NO_SETBUF
794 Normally \fBncurses\fR enables buffered output during terminal initialization.
795 This is done (as in SVr4 curses) for performance reasons.
796 For testing purposes, both of \fBncurses\fR and certain applications,
797 this feature is made optional.  Setting the NCURSES_NO_SETBUF variable
798 disables output buffering, leaving the output in the original (usually
799 line buffered) mode.
800 .TP 5
801 NCURSES_NO_UTF8_ACS
802 During initialization, the \fBncurses\fR library
803 checks for special cases where VT100 line-drawing (and the corresponding
804 alternate character set capabilities) described in the terminfo are known
805 to be missing.
806 Specifically, when running in a UTF-8 locale,
807 the Linux console emulator and the GNU screen program ignore these.
808 Ncurses checks the TERM environment variable for these.
809 For other special cases, you should set this environment variable.
810 Doing this tells ncurses to use Unicode values which correspond to
811 the VT100 line-drawing glyphs.
812 That works for the special cases cited,
813 and is likely to work for terminal emulators.
814 .IP
815 When setting this variable, you should set it to a nonzero value.
816 Setting it to zero (or to a nonnumber)
817 disables the special check for Linux and screen.
818 .TP 5
819 NCURSES_TRACE
820 During initialization, the \fBncurses\fR debugging library
821 checks the NCURSES_TRACE symbol.
822 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
823 function, using that value as the argument.
824 .IP
825 The argument values, which are defined in \fBcurses.h\fR, provide several
826 types of information.
827 When running with traces enabled, your application will write the
828 file \fBtrace\fR to the current directory.
829 .TP 5
830 TERM
831 Denotes your terminal type.
832 Each terminal type is distinct, though many are similar.
833 .TP 5
834 TERMCAP
835 If the \fBncurses\fR library has been configured with \fItermcap\fR
836 support, \fBncurses\fR will check for a terminal's description in
837 termcap form if it is not available in the terminfo database.
838 .IP
839 The TERMCAP symbol contains either a terminal description (with
840 newlines stripped out),
841 or a file name telling where the information denoted by the TERM symbol exists.
842 In either case, setting it directs \fBncurses\fR to ignore
843 the usual place for this information, e.g., /etc/termcap.
844 .TP 5
845 TERMINFO
846 Overrides the directory in which \fBncurses\fR searches for your terminal
847 description.
848 This is the simplest, but not the only way to change the list of directories.
849 The complete list of directories in order follows:
850 .RS
851 .TP 3
852 -
853 the last directory to which \fBncurses\fR wrote, if any, is searched first
854 .TP 3
855 -
856 the directory specified by the TERMINFO symbol
857 .TP 3
858 -
859 $HOME/.terminfo
860 .TP 3
861 -
862 directories listed in the TERMINFO_DIRS symbol
863 .TP 3
864 -
865 one or more directories whose names are configured and compiled into the
866 ncurses library, e.g.,
867 @TERMINFO@
868 .RE
869 .TP 5
870 TERMINFO_DIRS
871 Specifies a list of directories to search for terminal descriptions.
872 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
873 All of the terminal descriptions are in terminfo form, which makes
874 a subdirectory named for the first letter of the terminal names therein.
875 .TP 5
876 TERMPATH
877 If TERMCAP does not hold a file name then \fBncurses\fR checks
878 the TERMPATH symbol.
879 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
880 If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
881 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
882 .PP
883 The library may be configured to disregard the following variables when the
884 current user is the superuser (root), or if the application uses setuid or
885 setgid permissions:
886 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
887 .SH ALTERNATE CONFIGURATIONS
888 Several different configurations are possible,
889 depending on the configure script options used when building \fBncurses\fP.
890 There are a few main options whose effects are visible to the applications
891 developer using \fBncurses\fP:
892 .TP 5
893 --disable-overwrite
894 The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
895 .RS
896 .sp
897 \fB#include <curses.h>\fR
898 .RE
899 .IP
900 This option is used to avoid filename conflicts when \fBncurses\fP
901 is not the main implementation of curses of the computer.
902 If \fBncurses\fP is installed disabling overwrite, it puts its headers in
903 a subdirectory, e.g.,
904 .RS
905 .sp
906 \fB#include <ncurses/curses.h>\fR
907 .RE
908 .IP
909 It also omits a symbolic link which would allow you to use \fB-lcurses\fP
910 to build executables.
911 .TP 5
912 --enable-widec
913 The configure script renames the library and (if the \fB--disable-overwrite\fP
914 option is used) puts the header files in a different subdirectory.
915 All of the library names have a "w" appended to them,
916 i.e., instead of
917 .RS
918 .sp
919 \fB-lncurses\fR
920 .RE
921 .IP
922 you link with
923 .RS
924 .sp
925 \fB-lncursesw\fR
926 .RE
927 .IP
928 You must also define \fB_XOPEN_SOURCE_EXTENDED\fP when compiling for the
929 wide-character library to use the extended (wide-character) functions.
930 The \fBcurses.h\fP file which is installed for the wide-character
931 library is designed to be compatible with the normal library's header.
932 Only the size of the \fBWINDOW\fP structure differs, and very few
933 applications require more than a pointer to \fBWINDOW\fPs.
934 If the headers are installed allowing overwrite,
935 the wide-character library's headers should be installed last,
936 to allow applications to be built using either library
937 from the same set of headers.
938 .TP 5
939 --with-shared
940 .TP
941 --with-normal
942 .TP
943 --with-debug
944 .TP
945 --with-profile
946 The shared and normal (static) library names differ by their suffixes,
947 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
948 The debug and profiling libraries add a "_g" and a "_p" to the root
949 names respectively,
950 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
951 .TP 5
952 --with-trace
953 The \fBtrace\fP function normally resides in the debug library,
954 but it is sometimes useful to configure this in the shared library.
955 Configure scripts should check for the function's existence rather
956 than assuming it is always in the debug library.
957 .SH FILES
958 .TP 5
959 @DATADIR@/tabset
960 directory containing initialization files for the terminal capability database
961 @TERMINFO@
962 terminal capability database
963 .SH SEE ALSO
964 \fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
965 descriptions.
966 .SH EXTENSIONS
967 The \fBncurses\fR library can be compiled with an option (\fB-DUSE_GETCAP\fR)
968 that falls back to the old-style /etc/termcap file if the terminal setup code
969 cannot find a terminfo entry corresponding to \fBTERM\fR.  Use of this feature
970 is not recommended, as it essentially includes an entire termcap compiler in
971 the \fBncurses\fR startup code, at significant cost in core and startup cycles.
972 .PP
973 The \fBncurses\fR library includes facilities for capturing mouse events on
974 certain terminals (including xterm). See the \fBcurs_mouse\fR(3X)
975 manual page for details.
976 .PP
977 The \fBncurses\fR library includes facilities for responding to window
978 resizing events, e.g., when running in an xterm.
979 See the \fBresizeterm\fR(3X)
980 and \fBwresize\fR(3X) manual pages for details.
981 In addition, the library may be configured with a SIGWINCH handler.
982 .PP
983 The \fBncurses\fR library extends the fixed set of function key capabilities
984 of terminals by allowing the application designer to define additional
985 key sequences at runtime.
986 See the \fBdefine_key\fR(3X)
987 \fBkey_defined\fR(3X),
988 and \fBkeyok\fR(3X) manual pages for details.
989 .PP
990 The \fBncurses\fR library can exploit the capabilities of terminals which
991 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an application
992 to reset the terminal to its original foreground and background colors.
993 From the users' perspective, the application is able to draw colored
994 text on a background whose color is set independently, providing better
995 control over color contrasts.
996 See the \fBdefault_colors\fR(3X) manual page for details.
997 .PP
998 The \fBncurses\fR library includes a function for directing application output
999 to a printer attached to the terminal device.  See the \fBcurs_print\fR(3X)
1000 manual page for details.
1001 .SH PORTABILITY
1002 The \fBncurses\fR library is intended to be BASE-level conformant with the XSI
1003 Curses standard.  The EXTENDED XSI Curses functionality
1004 (including color support) is supported.
1005 .PP
1006 A small number of local differences (that is, individual differences between
1007 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
1008 sections of the library man pages.
1009 .PP
1010 This implementation also contains several extensions:
1011 .RS 5
1012 .PP
1013 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.  See
1014 the \fBcurs_getch\fR(3X) manual page for details.
1015 .PP
1016 The routine \fBslk_attr\fR is not part of XPG4, nor is it present in SVr4.
1017 See the \fBcurs_slk\fR(3X) manual page for details.
1018 .PP
1019 The routines \fBgetmouse\fR, \fBmousemask\fR, \fBungetmouse\fR,
1020 \fBmouseinterval\fR, and \fBwenclose\fR relating to mouse interfacing are not
1021 part of XPG4, nor are they present in SVr4.
1022 See the \fBcurs_mouse\fR(3X) manual page for details.
1023 .PP
1024 The routine \fBmcprint\fR was not present in any previous curses implementation.
1025 See the \fBcurs_print\fR(3X) manual page for details.
1026 .PP
1027 The routine \fBwresize\fR is not part of XPG4, nor is it present in SVr4.
1028 See the \fBwresize\fR(3X) manual page for details.
1029 .PP
1030 The WINDOW structure's internal details can be hidden from application
1031 programs.
1032 See \fBcurs_opaque\fR(3X) for the discussion of \fBis_scrollok\fR, etc.
1033 .RE
1034 .PP
1035 In historic curses versions, delays embedded in the capabilities \fBcr\fR,
1036 \fBind\fR, \fBcub1\fR, \fBff\fR and \fBtab\fR activated corresponding delay
1037 bits in the UNIX tty driver.  In this implementation, all padding is done by
1038 NUL sends.  This method is slightly more expensive, but narrows the interface
1039 to the UNIX kernel significantly and increases the package's portability
1040 correspondingly.
1041 .SH NOTES
1042 The header file \fB<curses.h>\fR automatically includes the header files
1043 \fB<stdio.h>\fR and \fB<unctrl.h>\fR.
1044 .PP
1045 If standard output from a \fBncurses\fR program is re-directed to something
1046 which is not a tty, screen updates will be directed to standard error.  This
1047 was an undocumented feature of AT&T System V Release 3 curses.
1048 .SH AUTHORS
1049 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1050 Based on pcurses by Pavel Curtis.
1051 .\"#
1052 .\"# The following sets edit modes for GNU EMACS
1053 .\"# Local Variables:
1054 .\"# mode:nroff
1055 .\"# fill-column:79
1056 .\"# End: