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