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