1ncurses(3X) ncurses(3X)
2
6 ncurses - CRT screen handling and optimization package
7
9 #include <curses.h>
10
12 The ncurses library routines give the user a terminal-independent
13 method of updating character screens with reasonable optimization.
14 This implementation is “new curses” (ncurses) and is the approved
15 replacement for 4.4BSD classic curses, which has been discontinued.
16 This describes ncurses version 6.2 (patch 20200222).
17 The ncurses library emulates the curses library of System V Release 4
19 UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
20 curses). XSI stands for X/Open System Interfaces Extension. The
21 ncurses library is freely redistributable in source form. Differences
22 from the SVr4 curses are summarized under the EXTENSIONS and PORTABIL‐
23 ITY sections below and described in detail in the respective EXTEN‐
24 SIONS, PORTABILITY and BUGS sections of individual man pages.
25 The ncurses library also provides many useful extensions, i.e., fea‐
27 tures which cannot be implemented by a simple add-on library but which
28 require access to the internals of the library.
29 A program using these routines must be linked with the -lncurses
31 option, or (if it has been generated) with the debugging library
32 -lncurses_g. (Your system integrator may also have installed these
33 libraries under the names -lcurses and -lcurses_g.) The ncurses_g
34 library generates trace logs (in a file called 'trace' in the current
35 directory) that describe curses actions. See also the section on
36 ALTERNATE CONFIGURATIONS.
37 The ncurses package supports: overall screen, window and pad manipula‐
39 tion; output to windows and pads; reading terminal input; control over
40 terminal and curses input and output options; environment query rou‐
41 tines; color manipulation; use of soft label keys; terminfo capabili‐
42 ties; and access to low-level terminal-manipulation routines.
43 Initialization
45 The library uses the locale which the calling program has initialized.
46 That is normally done with setlocale:
47 setlocale(LC_ALL, "");
49 If the locale is not initialized, the library assumes that characters
51 are printable as in ISO-8859-1, to work with certain legacy programs.
52 You should initialize the locale and not rely on specific details of
53 the library when the locale has not been setup.
54 The function initscr or newterm must be called to initialize the
56 library before any of the other routines that deal with windows and
57 screens are used. The routine endwin(3X) must be called before exit‐
58 ing.
59 To get character-at-a-time input without echoing (most interactive,
61 screen oriented programs want this), the following sequence should be
62 used:
63 initscr(); cbreak(); noecho();
65 Most programs would additionally use the sequence:
67 nonl();
69 intrflush(stdscr, FALSE);
70 keypad(stdscr, TRUE);
71 Before a curses program is run, the tab stops of the terminal should be
73 set and its initialization strings, if defined, must be output. This
74 can be done by executing the tput init command after the shell environ‐
75 ment variable TERM has been exported. tset(1) is usually responsible
76 for doing this. [See terminfo(5) for further details.]
77 Datatypes
79 The ncurses library permits manipulation of data structures, called
80 windows, which can be thought of as two-dimensional arrays of charac‐
81 ters representing all or part of a CRT screen. A default window called
82 stdscr, which is the size of the terminal screen, is supplied. Others
83 may be created with newwin.
84 Note that curses does not handle overlapping windows, that's done by
86 the panel(3X) library. This means that you can either use stdscr or
87 divide the screen into tiled windows and not using stdscr at all. Mix‐
88 ing the two will result in unpredictable, and undesired, effects.
89 Windows are referred to by variables declared as WINDOW *. These data
91 structures are manipulated with routines described here and elsewhere
92 in the ncurses manual pages. Among those, the most basic routines are
93 move and addch. More general versions of these routines are included
94 with names beginning with w, allowing the user to specify a window.
95 The routines not beginning with w affect stdscr.
96 After using routines to manipulate a window, refresh(3X) is called,
98 telling curses to make the user's CRT screen look like stdscr. The
99 characters in a window are actually of type chtype, (character and
100 attribute data) so that other information about the character may also
101 be stored with each character.
102 Special windows called pads may also be manipulated. These are windows
104 which are not constrained to the size of the screen and whose contents
105 need not be completely displayed. See curs_pad(3X) for more informa‐
106 tion.
107 In addition to drawing characters on the screen, video attributes and
109 colors may be supported, causing the characters to show up in such
110 modes as underlined, in reverse video, or in color on terminals that
111 support such display enhancements. Line drawing characters may be
112 specified to be output. On input, curses is also able to translate
113 arrow and function keys that transmit escape sequences into single val‐
114 ues. The video attributes, line drawing characters, and input values
115 use names, defined in <curses.h>, such as A_REVERSE, ACS_HLINE, and
116 KEY_LEFT.
117 Environment variables
119 If the environment variables LINES and COLUMNS are set, or if the pro‐
120 gram is executing in a window environment, line and column information
121 in the environment will override information read by terminfo. This
122 would affect a program running in an AT&T 630 layer, for example, where
123 the size of a screen is changeable (see ENVIRONMENT).
124 If the environment variable TERMINFO is defined, any program using
126 curses checks for a local terminal definition before checking in the
127 standard place. For example, if TERM is set to att4424, then the com‐
128 piled terminal definition is found in
129 /usr/share/terminfo/a/att4424.
131 (The a is copied from the first letter of att4424 to avoid creation of
133 huge directories.) However, if TERMINFO is set to $HOME/myterms,
134 curses first checks
135 $HOME/myterms/a/att4424,
137 and if that fails, it then checks
139 /usr/share/terminfo/a/att4424.
141 This is useful for developing experimental definitions or when write
143 permission in /usr/share/terminfo is not available.
144 The integer variables LINES and COLS are defined in <curses.h> and will
146 be filled in by initscr with the size of the screen. The constants
147 TRUE and FALSE have the values 1 and 0, respectively.
148 The curses routines also define the WINDOW * variable curscr which is
150 used for certain low-level operations like clearing and redrawing a
151 screen containing garbage. The curscr can be used in only a few rou‐
152 tines.
153 Routine and Argument Names
155 Many curses routines have two or more versions. The routines prefixed
156 with w require a window argument. The routines prefixed with p require
157 a pad argument. Those without a prefix generally use stdscr.
158 The routines prefixed with mv require a y and x coordinate to move to
160 before performing the appropriate action. The mv routines imply a call
161 to move before the call to the other routine. The coordinate y always
162 refers to the row (of the window), and x always refers to the column.
163 The upper left-hand corner is always (0,0), not (1,1).
164 The routines prefixed with mvw take both a window argument and x and y
166 coordinates. The window argument is always specified before the coor‐
167 dinates.
168 In each case, win is the window affected, and pad is the pad affected;
170 win and pad are always pointers to type WINDOW.
171 Option setting routines require a Boolean flag bf with the value TRUE
173 or FALSE; bf is always of type bool. Most of the data types used in
174 the library routines, such as WINDOW, SCREEN, bool, and chtype are
175 defined in <curses.h>. Types used for the terminfo routines such as
176 TERMINAL are defined in <term.h>.
177 This manual page describes functions which may appear in any configura‐
179 tion of the library. There are two common configurations of the
180 library:
181 ncurses
183 the “normal” library, which handles 8-bit characters. The nor‐
184 mal (8-bit) library stores characters combined with attributes
185 in chtype data.
186 Attributes alone (no corresponding character) may be stored in
188 chtype or the equivalent attr_t data. In either case, the data
189 is stored in something like an integer.
190 Each cell (row and column) in a WINDOW is stored as a chtype.
192 ncursesw
194 the so-called “wide” library, which handles multibyte charac‐
195 ters (see the section on ALTERNATE CONFIGURATIONS). The “wide”
196 library includes all of the calls from the “normal” library.
197 It adds about one third more calls using data types which store
198 multibyte characters:
199 cchar_t
201 corresponds to chtype. However it is a structure, because
202 more data is stored than can fit into an integer. The
203 characters are large enough to require a full integer
204 value - and there may be more than one character per cell.
205 The video attributes and color are stored in separate
206 fields of the structure.
207 Each cell (row and column) in a WINDOW is stored as a
209 cchar_t.
210 The setcchar(3X) and getcchar(3X) functions store and
212 retrieve the data from a cchar_t structure.
213 wchar_t
215 stores a “wide” character. Like chtype, this may be an
216 integer.
217 wint_t
219 stores a wchar_t or WEOF - not the same, though both may
220 have the same size.
221 The “wide” library provides new functions which are analogous
223 to functions in the “normal” library. There is a naming con‐
224 vention which relates many of the normal/wide variants: a “_w”
225 is inserted into the name. For example, waddch becomes
226 wadd_wch.
227 Routine Name Index
229 The following table lists each curses routine and the name of the man‐
230 ual page on which it is described. Routines flagged with “*” are
231 ncurses-specific, not described by XPG4 or present in SVr4.
232 curses Routine Name Manual Page Name
234 ─────────────────────────────────────────────
235 COLOR_PAIR curs_color(3X)
236 PAIR_NUMBER curs_attr(3X)
237 _nc_free_and_exit curs_memleaks(3X)*
238 _nc_freeall curs_memleaks(3X)*
239 _nc_tracebits curs_trace(3X)*
240 _traceattr curs_trace(3X)*
241 _traceattr2 curs_trace(3X)*
242 _tracechar curs_trace(3X)*
243 _tracechtype curs_trace(3X)*
244 _tracechtype2 curs_trace(3X)*
245 _tracedump curs_trace(3X)*
246 _tracef curs_trace(3X)*
247 _tracemouse curs_trace(3X)*
248 add_wch curs_add_wch(3X)
249 add_wchnstr curs_add_wchstr(3X)
250 add_wchstr curs_add_wchstr(3X)
251 addch curs_addch(3X)
252 addchnstr curs_addchstr(3X)
253 addchstr curs_addchstr(3X)
254 addnstr curs_addstr(3X)
255 addnwstr curs_addwstr(3X)
256 addstr curs_addstr(3X)
257 addwstr curs_addwstr(3X)
258 alloc_pair new_pair(3X)*
259 assume_default_colors default_colors(3X)*
260 attr_get curs_attr(3X)
261 attr_off curs_attr(3X)
262 attr_on curs_attr(3X)
263 attr_set curs_attr(3X)
264 attroff curs_attr(3X)
266 attron curs_attr(3X)
267 attrset curs_attr(3X)
268 baudrate curs_termattrs(3X)
269 beep curs_beep(3X)
270 bkgd curs_bkgd(3X)
271 bkgdset curs_bkgd(3X)
272 bkgrnd curs_bkgrnd(3X)
273 bkgrndset curs_bkgrnd(3X)
274 border curs_border(3X)
275 border_set curs_border_set(3X)
276 box curs_border(3X)
277 box_set curs_border_set(3X)
278 can_change_color curs_color(3X)
279 cbreak curs_inopts(3X)
280 chgat curs_attr(3X)
281 clear curs_clear(3X)
282 clearok curs_outopts(3X)
283 clrtobot curs_clear(3X)
284 clrtoeol curs_clear(3X)
285 color_content curs_color(3X)
286 color_set curs_attr(3X)
287 copywin curs_overlay(3X)
288 curs_set curs_kernel(3X)
289 curses_version curs_extend(3X)*
290 def_prog_mode curs_kernel(3X)
291 def_shell_mode curs_kernel(3X)
292 define_key define_key(3X)*
293 del_curterm curs_terminfo(3X)
294 delay_output curs_util(3X)
295 delch curs_delch(3X)
296 deleteln curs_deleteln(3X)
297 delscreen curs_initscr(3X)
298 delwin curs_window(3X)
299 derwin curs_window(3X)
300 doupdate curs_refresh(3X)
301 dupwin curs_window(3X)
302 echo curs_inopts(3X)
303 echo_wchar curs_add_wch(3X)
304 echochar curs_addch(3X)
305 endwin curs_initscr(3X)
306 erase curs_clear(3X)
307 erasechar curs_termattrs(3X)
308 erasewchar curs_termattrs(3X)
309 extended_color_content curs_color(3X)*
310 extended_pair_content curs_color(3X)*
311 extended_slk_color curs_slk(3X)*
312 filter curs_util(3X)
313 find_pair new_pair(3X)*
314 flash curs_beep(3X)
315 flushinp curs_util(3X)
316 free_pair new_pair(3X)*
317 get_wch curs_get_wch(3X)
318 get_wstr curs_get_wstr(3X)
319 getattrs curs_attr(3X)
320 getbegx curs_legacy(3X)*
321 getbegy curs_legacy(3X)*
322 getbegyx curs_getyx(3X)
323 getbkgd curs_bkgd(3X)
324 getbkgrnd curs_bkgrnd(3X)
325 getcchar curs_getcchar(3X)
326 getch curs_getch(3X)
327 getcurx curs_legacy(3X)*
328 getcury curs_legacy(3X)*
329 getmaxx curs_legacy(3X)*
330 getmaxy curs_legacy(3X)*
332 getmaxyx curs_getyx(3X)
333 getmouse curs_mouse(3X)*
334 getn_wstr curs_get_wstr(3X)
335 getnstr curs_getstr(3X)
336 getparx curs_legacy(3X)*
337 getpary curs_legacy(3X)*
338 getparyx curs_getyx(3X)
339 getstr curs_getstr(3X)
340 getsyx curs_kernel(3X)
341 getwin curs_util(3X)
342 getyx curs_getyx(3X)
343 halfdelay curs_inopts(3X)
344 has_colors curs_color(3X)
345 has_ic curs_termattrs(3X)
346 has_il curs_termattrs(3X)
347 has_key curs_getch(3X)*
348 hline curs_border(3X)
349 hline_set curs_border_set(3X)
350 idcok curs_outopts(3X)
351 idlok curs_outopts(3X)
352 immedok curs_outopts(3X)
353 in_wch curs_in_wch(3X)
354 in_wchnstr curs_in_wchstr(3X)
355 in_wchstr curs_in_wchstr(3X)
356 inch curs_inch(3X)
357 inchnstr curs_inchstr(3X)
358 inchstr curs_inchstr(3X)
359 init_color curs_color(3X)
360 init_extended_color curs_color(3X)*
361 init_extended_pair curs_color(3X)*
362 init_pair curs_color(3X)
363 initscr curs_initscr(3X)
364 innstr curs_instr(3X)
365 innwstr curs_inwstr(3X)
366 ins_nwstr curs_ins_wstr(3X)
367 ins_wch curs_ins_wch(3X)
368 ins_wstr curs_ins_wstr(3X)
369 insch curs_insch(3X)
370 insdelln curs_deleteln(3X)
371 insertln curs_deleteln(3X)
372 insnstr curs_insstr(3X)
373 insstr curs_insstr(3X)
374 instr curs_instr(3X)
375 intrflush curs_inopts(3X)
376 inwstr curs_inwstr(3X)
377 is_cleared curs_opaque(3X)*
378 is_idcok curs_opaque(3X)*
379 is_idlok curs_opaque(3X)*
380 is_immedok curs_opaque(3X)*
381 is_keypad curs_opaque(3X)*
382 is_leaveok curs_opaque(3X)*
383 is_linetouched curs_touch(3X)
384 is_nodelay curs_opaque(3X)*
385 is_notimeout curs_opaque(3X)*
386 is_pad curs_opaque(3X)*
387 is_scrollok curs_opaque(3X)*
388 is_subwin curs_opaque(3X)*
389 is_syncok curs_opaque(3X)*
390 is_term_resized resizeterm(3X)*
391 is_wintouched curs_touch(3X)
392 isendwin curs_initscr(3X)
393 key_defined key_defined(3X)*
394 key_name curs_util(3X)
395 keybound keybound(3X)*
396 keyname curs_util(3X)
398 keyok keyok(3X)*
399 keypad curs_inopts(3X)
400 killchar curs_termattrs(3X)
401 killwchar curs_termattrs(3X)
402 leaveok curs_outopts(3X)
403 longname curs_termattrs(3X)
404 mcprint curs_print(3X)*
405 meta curs_inopts(3X)
406 mouse_trafo curs_mouse(3X)*
407 mouseinterval curs_mouse(3X)*
408 mousemask curs_mouse(3X)*
409 move curs_move(3X)
410 mvadd_wch curs_add_wch(3X)
411 mvadd_wchnstr curs_add_wchstr(3X)
412 mvadd_wchstr curs_add_wchstr(3X)
413 mvaddch curs_addch(3X)
414 mvaddchnstr curs_addchstr(3X)
415 mvaddchstr curs_addchstr(3X)
416 mvaddnstr curs_addstr(3X)
417 mvaddnwstr curs_addwstr(3X)
418 mvaddstr curs_addstr(3X)
419 mvaddwstr curs_addwstr(3X)
420 mvchgat curs_attr(3X)
421 mvcur curs_terminfo(3X)
422 mvdelch curs_delch(3X)
423 mvderwin curs_window(3X)
424 mvget_wch curs_get_wch(3X)
425 mvget_wstr curs_get_wstr(3X)
426 mvgetch curs_getch(3X)
427 mvgetn_wstr curs_get_wstr(3X)
428 mvgetnstr curs_getstr(3X)
429 mvgetstr curs_getstr(3X)
430 mvhline curs_border(3X)
431 mvhline_set curs_border_set(3X)
432 mvin_wch curs_in_wch(3X)
433 mvin_wchnstr curs_in_wchstr(3X)
434 mvin_wchstr curs_in_wchstr(3X)
435 mvinch curs_inch(3X)
436 mvinchnstr curs_inchstr(3X)
437 mvinchstr curs_inchstr(3X)
438 mvinnstr curs_instr(3X)
439 mvinnwstr curs_inwstr(3X)
440 mvins_nwstr curs_ins_wstr(3X)
441 mvins_wch curs_ins_wch(3X)
442 mvins_wstr curs_ins_wstr(3X)
443 mvinsch curs_insch(3X)
444 mvinsnstr curs_insstr(3X)
445 mvinsstr curs_insstr(3X)
446 mvinstr curs_instr(3X)
447 mvinwstr curs_inwstr(3X)
448 mvprintw curs_printw(3X)
449 mvscanw curs_scanw(3X)
450 mvvline curs_border(3X)
451 mvvline_set curs_border_set(3X)
452 mvwadd_wch curs_add_wch(3X)
453 mvwadd_wchnstr curs_add_wchstr(3X)
454 mvwadd_wchstr curs_add_wchstr(3X)
455 mvwaddch curs_addch(3X)
456 mvwaddchnstr curs_addchstr(3X)
457 mvwaddchstr curs_addchstr(3X)
458 mvwaddnstr curs_addstr(3X)
459 mvwaddnwstr curs_addwstr(3X)
460 mvwaddstr curs_addstr(3X)
461 mvwaddwstr curs_addwstr(3X)
462 mvwchgat curs_attr(3X)
464 mvwdelch curs_delch(3X)
465 mvwget_wch curs_get_wch(3X)
466 mvwget_wstr curs_get_wstr(3X)
467 mvwgetch curs_getch(3X)
468 mvwgetn_wstr curs_get_wstr(3X)
469 mvwgetnstr curs_getstr(3X)
470 mvwgetstr curs_getstr(3X)
471 mvwhline curs_border(3X)
472 mvwhline_set curs_border_set(3X)
473 mvwin curs_window(3X)
474 mvwin_wch curs_in_wch(3X)
475 mvwin_wchnstr curs_in_wchstr(3X)
476 mvwin_wchstr curs_in_wchstr(3X)
477 mvwinch curs_inch(3X)
478 mvwinchnstr curs_inchstr(3X)
479 mvwinchstr curs_inchstr(3X)
480 mvwinnstr curs_instr(3X)
481 mvwinnwstr curs_inwstr(3X)
482 mvwins_nwstr curs_ins_wstr(3X)
483 mvwins_wch curs_ins_wch(3X)
484 mvwins_wstr curs_ins_wstr(3X)
485 mvwinsch curs_insch(3X)
486 mvwinsnstr curs_insstr(3X)
487 mvwinsstr curs_insstr(3X)
488 mvwinstr curs_instr(3X)
489 mvwinwstr curs_inwstr(3X)
490 mvwprintw curs_printw(3X)
491 mvwscanw curs_scanw(3X)
492 mvwvline curs_border(3X)
493 mvwvline_set curs_border_set(3X)
494 napms curs_kernel(3X)
495 newpad curs_pad(3X)
496 newterm curs_initscr(3X)
497 newwin curs_window(3X)
498 nl curs_outopts(3X)
499 nocbreak curs_inopts(3X)
500 nodelay curs_inopts(3X)
501 noecho curs_inopts(3X)
502 nofilter curs_util(3X)*
503 nonl curs_outopts(3X)
504 noqiflush curs_inopts(3X)
505 noraw curs_inopts(3X)
506 notimeout curs_inopts(3X)
507 overlay curs_overlay(3X)
508 overwrite curs_overlay(3X)
509 pair_content curs_color(3X)
510 pechochar curs_pad(3X)
511 pnoutrefresh curs_pad(3X)
512 prefresh curs_pad(3X)
513 printw curs_printw(3X)
514 putp curs_terminfo(3X)
515 putwin curs_util(3X)
516 qiflush curs_inopts(3X)
517 raw curs_inopts(3X)
518 redrawwin curs_refresh(3X)
519 refresh curs_refresh(3X)
520 reset_prog_mode curs_kernel(3X)
521 reset_shell_mode curs_kernel(3X)
522 resetty curs_kernel(3X)
523 resize_term resizeterm(3X)*
524 resizeterm resizeterm(3X)*
525 restartterm curs_terminfo(3X)
526 ripoffline curs_kernel(3X)
527 savetty curs_kernel(3X)
528 scanw curs_scanw(3X)
530 scr_dump curs_scr_dump(3X)
531 scr_init curs_scr_dump(3X)
532 scr_restore curs_scr_dump(3X)
533 scr_set curs_scr_dump(3X)
534 scrl curs_scroll(3X)
535 scroll curs_scroll(3X)
536 scrollok curs_outopts(3X)
537 set_curterm curs_terminfo(3X)
538 set_term curs_initscr(3X)
539 setcchar curs_getcchar(3X)
540 setscrreg curs_outopts(3X)
541 setsyx curs_kernel(3X)
542 setterm curs_terminfo(3X)
543 setupterm curs_terminfo(3X)
544 slk_attr curs_slk(3X)*
545 slk_attr_off curs_slk(3X)
546 slk_attr_on curs_slk(3X)
547 slk_attr_set curs_slk(3X)
548 slk_attroff curs_slk(3X)
549 slk_attron curs_slk(3X)
550 slk_attrset curs_slk(3X)
551 slk_clear curs_slk(3X)
552 slk_color curs_slk(3X)
553 slk_init curs_slk(3X)
554 slk_label curs_slk(3X)
555 slk_noutrefresh curs_slk(3X)
556 slk_refresh curs_slk(3X)
557 slk_restore curs_slk(3X)
558 slk_set curs_slk(3X)
559 slk_touch curs_slk(3X)
560 standend curs_attr(3X)
561 standout curs_attr(3X)
562 start_color curs_color(3X)
563 subpad curs_pad(3X)
564 subwin curs_window(3X)
565 syncok curs_window(3X)
566 term_attrs curs_termattrs(3X)
567 termattrs curs_termattrs(3X)
568 termname curs_termattrs(3X)
569 tgetent curs_termcap(3X)
570 tgetflag curs_termcap(3X)
571 tgetnum curs_termcap(3X)
572 tgetstr curs_termcap(3X)
573 tgoto curs_termcap(3X)
574 tigetflag curs_terminfo(3X)
575 tigetnum curs_terminfo(3X)
576 tigetstr curs_terminfo(3X)
577 timeout curs_inopts(3X)
578 tiparm curs_terminfo(3X)*
579 touchline curs_touch(3X)
580 touchwin curs_touch(3X)
581 tparm curs_terminfo(3X)
582 tputs curs_termcap(3X)
583 tputs curs_terminfo(3X)
584 trace curs_trace(3X)*
585 typeahead curs_inopts(3X)
586 unctrl curs_util(3X)
587 unget_wch curs_get_wch(3X)
588 ungetch curs_getch(3X)
589 ungetmouse curs_mouse(3X)*
590 untouchwin curs_touch(3X)
591 use_default_colors default_colors(3X)*
592 use_env curs_util(3X)
593 use_extended_names curs_extend(3X)*
594 use_legacy_coding legacy_coding(3X)*
596 use_tioctl curs_util(3X)*
597 vid_attr curs_terminfo(3X)
598 vid_puts curs_terminfo(3X)
599 vidattr curs_terminfo(3X)
600 vidputs curs_terminfo(3X)
601 vline curs_border(3X)
602 vline_set curs_border_set(3X)
603 vw_printw curs_printw(3X)
604 vw_scanw curs_scanw(3X)
605 vwprintw curs_printw(3X)
606 vwscanw curs_scanw(3X)
607 wadd_wch curs_add_wch(3X)
608 wadd_wchnstr curs_add_wchstr(3X)
609 wadd_wchstr curs_add_wchstr(3X)
610 waddch curs_addch(3X)
611 waddchnstr curs_addchstr(3X)
612 waddchstr curs_addchstr(3X)
613 waddnstr curs_addstr(3X)
614 waddnwstr curs_addwstr(3X)
615 waddstr curs_addstr(3X)
616 waddwstr curs_addwstr(3X)
617 wattr_get curs_attr(3X)
618 wattr_off curs_attr(3X)
619 wattr_on curs_attr(3X)
620 wattr_set curs_attr(3X)
621 wattroff curs_attr(3X)
622 wattron curs_attr(3X)
623 wattrset curs_attr(3X)
624 wbkgd curs_bkgd(3X)
625 wbkgdset curs_bkgd(3X)
626 wbkgrnd curs_bkgrnd(3X)
627 wbkgrndset curs_bkgrnd(3X)
628 wborder curs_border(3X)
629 wborder_set curs_border_set(3X)
630 wchgat curs_attr(3X)
631 wclear curs_clear(3X)
632 wclrtobot curs_clear(3X)
633 wclrtoeol curs_clear(3X)
634 wcolor_set curs_attr(3X)
635 wcursyncup curs_window(3X)
636 wdelch curs_delch(3X)
637 wdeleteln curs_deleteln(3X)
638 wecho_wchar curs_add_wch(3X)
639 wechochar curs_addch(3X)
640 wenclose curs_mouse(3X)*
641 werase curs_clear(3X)
642 wget_wch curs_get_wch(3X)
643 wget_wstr curs_get_wstr(3X)
644 wgetbkgrnd curs_bkgrnd(3X)
645 wgetch curs_getch(3X)
646 wgetdelay curs_opaque(3X)*
647 wgetn_wstr curs_get_wstr(3X)
648 wgetnstr curs_getstr(3X)
649 wgetparent curs_opaque(3X)*
650 wgetscrreg curs_opaque(3X)*
651 wgetstr curs_getstr(3X)
652 whline curs_border(3X)
653 whline_set curs_border_set(3X)
654 win_wch curs_in_wch(3X)
655 win_wchnstr curs_in_wchstr(3X)
656 win_wchstr curs_in_wchstr(3X)
657 winch curs_inch(3X)
658 winchnstr curs_inchstr(3X)
659 winchstr curs_inchstr(3X)
660 winnstr curs_instr(3X)
662 winnwstr curs_inwstr(3X)
663 wins_nwstr curs_ins_wstr(3X)
664 wins_wch curs_ins_wch(3X)
665 wins_wstr curs_ins_wstr(3X)
666 winsch curs_insch(3X)
667 winsdelln curs_deleteln(3X)
668 winsertln curs_deleteln(3X)
669 winsnstr curs_insstr(3X)
670 winsstr curs_insstr(3X)
671 winstr curs_instr(3X)
672 winwstr curs_inwstr(3X)
673 wmouse_trafo curs_mouse(3X)*
674 wmove curs_move(3X)
675 wnoutrefresh curs_refresh(3X)
676 wprintw curs_printw(3X)
677 wredrawln curs_refresh(3X)
678 wrefresh curs_refresh(3X)
679 wresize wresize(3X)*
680 wscanw curs_scanw(3X)
681 wscrl curs_scroll(3X)
682 wsetscrreg curs_outopts(3X)
683 wstandend curs_attr(3X)
684 wstandout curs_attr(3X)
685 wsyncdown curs_window(3X)
686 wsyncup curs_window(3X)
687 wtimeout curs_inopts(3X)
688 wtouchln curs_touch(3X)
689 wunctrl curs_util(3X)
690 wvline curs_border(3X)
691 wvline_set curs_border_set(3X)
692
694 Routines that return an integer return ERR upon failure and an integer
695 value other than ERR upon successful completion, unless otherwise noted
696 in the routine descriptions.
697 As a general rule, routines check for null pointers passed as parame‐
699 ters, and handle this as an error.
700 All macros return the value of the w version, except setscrreg,
702 wsetscrreg, getyx, getbegyx, and getmaxyx. The return values of
703 setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined
704 (i.e., these should not be used as the right-hand side of assignment
705 statements).
706 Routines that return pointers return NULL on error.
708
710 The following environment symbols are useful for customizing the run‐
711 time behavior of the ncurses library. The most important ones have
712 been already discussed in detail.
713 CC command-character
715 When set, change occurrences of the command_character (i.e., the cmdch
716 capability) of the loaded terminfo entries to the value of this vari‐
717 able. Very few terminfo entries provide this feature.
718 Because this name is also used in development environments to represent
720 the C compiler's name, ncurses ignores it if it does not happen to be a
721 single character.
722 BAUDRATE
724 The debugging library checks this environment variable when the appli‐
725 cation has redirected output to a file. The variable's numeric value
726 is used for the baudrate. If no value is found, ncurses uses 9600.
727 This allows testers to construct repeatable test-cases that take into
728 account costs that depend on baudrate.
729 COLUMNS
731 Specify the width of the screen in characters. Applications running in
732 a windowing environment usually are able to obtain the width of the
733 window in which they are executing. If neither the COLUMNS value nor
734 the terminal's screen size is available, ncurses uses the size which
735 may be specified in the terminfo database (i.e., the cols capability).
736 It is important that your application use a correct size for the
738 screen. This is not always possible because your application may be
739 running on a host which does not honor NAWS (Negotiations About Window
740 Size), or because you are temporarily running as another user. How‐
741 ever, setting COLUMNS and/or LINES overrides the library's use of the
742 screen size obtained from the operating system.
743 Either COLUMNS or LINES symbols may be specified independently. This
745 is mainly useful to circumvent legacy misfeatures of terminal descrip‐
746 tions, e.g., xterm which commonly specifies a 65 line screen. For best
747 results, lines and cols should not be specified in a terminal descrip‐
748 tion for terminals which are run as emulations.
749 Use the use_env function to disable all use of external environment
751 (but not including system calls) to determine the screen size. Use the
752 use_tioctl function to update COLUMNS or LINES to match the screen size
753 obtained from system calls or the terminal database.
754 ESCDELAY
756 Specifies the total time, in milliseconds, for which ncurses will await
757 a character sequence, e.g., a function key. The default value, 1000
758 milliseconds, is enough for most uses. However, it is made a variable
759 to accommodate unusual applications.
760 The most common instance where you may wish to change this value is to
762 work with slow hosts, e.g., running on a network. If the host cannot
763 read characters rapidly enough, it will have the same effect as if the
764 terminal did not send characters rapidly enough. The library will
765 still see a timeout.
766 Note that xterm mouse events are built up from character sequences
768 received from the xterm. If your application makes heavy use of multi‐
769 ple-clicking, you may wish to lengthen this default value because the
770 timeout applies to the composed multi-click event as well as the indi‐
771 vidual clicks.
772 In addition to the environment variable, this implementation provides a
774 global variable with the same name. Portable applications should not
775 rely upon the presence of ESCDELAY in either form, but setting the
776 environment variable rather than the global variable does not create
777 problems when compiling an application.
778 HOME
780 Tells ncurses where your home directory is. That is where it may read
781 and write auxiliary terminal descriptions:
782 $HOME/.termcap
784 $HOME/.terminfo
785 LINES
787 Like COLUMNS, specify the height of the screen in characters. See COL‐
788 UMNS for a detailed description.
789 MOUSE_BUTTONS_123
791 This applies only to the OS/2 EMX port. It specifies the order of but‐
792 tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
793 other platforms:
794 1 = left
796 2 = right
797 3 = middle.
798 This variable lets you customize the mouse. The variable must be three
800 numeric digits 1-3 in any order, e.g., 123 or 321. If it is not speci‐
801 fied, ncurses uses 132.
802 NCURSES_ASSUMED_COLORS
804 Override the compiled-in assumption that the terminal's default colors
805 are white-on-black (see default_colors(3X)). You may set the fore‐
806 ground and background color values with this environment variable by
807 proving a 2-element list: foreground,background. For example, to tell
808 ncurses to not assume anything about the colors, set this to "-1,-1".
809 To make it green-on-black, set it to "2,0". Any positive value from
810 zero to the terminfo max_colors value is allowed.
811 NCURSES_CONSOLE2
813 This applies only to the MinGW port of ncurses.
814 The Console2 program's handling of the Microsoft Console API call Cre‐
816 ateConsoleScreenBuffer is defective. Applications which use this will
817 hang. However, it is possible to simulate the action of this call by
818 mapping coordinates, explicitly saving and restoring the original
819 screen contents. Setting the environment variable NCGDB has the same
820 effect.
821 NCURSES_GPM_TERMS
823 This applies only to ncurses configured to use the GPM interface.
824 If present, the environment variable is a list of one or more terminal
826 names against which the TERM environment variable is matched. Setting
827 it to an empty value disables the GPM interface; using the built-in
828 support for xterm, etc.
829 If the environment variable is absent, ncurses will attempt to open GPM
831 if TERM contains “linux”.
832 NCURSES_NO_HARD_TABS
834 Ncurses may use tabs as part of the cursor movement optimization. In
835 some cases, your terminal driver may not handle these properly. Set
836 this environment variable to disable the feature. You can also adjust
837 your stty settings to avoid the problem.
838 NCURSES_NO_MAGIC_COOKIE
840 Some terminals use a magic-cookie feature which requires special han‐
841 dling to make highlighting and other video attributes display properly.
842 You can suppress the highlighting entirely for these terminals by set‐
843 ting this environment variable.
844 NCURSES_NO_PADDING
846 Most of the terminal descriptions in the terminfo database are written
847 for real “hardware” terminals. Many people use terminal emulators
848 which run in a windowing environment and use curses-based applications.
849 Terminal emulators can duplicate all of the important aspects of a
850 hardware terminal, but they do not have the same limitations. The
851 chief limitation of a hardware terminal from the standpoint of your
852 application is the management of dataflow, i.e., timing. Unless a
853 hardware terminal is interfaced into a terminal concentrator (which
854 does flow control), it (or your application) must manage dataflow, pre‐
855 venting overruns. The cheapest solution (no hardware cost) is for your
856 program to do this by pausing after operations that the terminal does
857 slowly, such as clearing the display.
858 As a result, many terminal descriptions (including the vt100) have
860 delay times embedded. You may wish to use these descriptions, but not
861 want to pay the performance penalty.
862 Set the NCURSES_NO_PADDING environment variable to disable all but
864 mandatory padding. Mandatory padding is used as a part of special con‐
865 trol sequences such as flash.
866 NCURSES_NO_SETBUF
868 This setting is obsolete. Before changes
869 · started with 5.9 patch 20120825 and
871 · continued though 5.9 patch 20130126
873 ncurses enabled buffered output during terminal initialization. This
875 was done (as in SVr4 curses) for performance reasons. For testing pur‐
876 poses, both of ncurses and certain applications, this feature was made
877 optional. Setting the NCURSES_NO_SETBUF variable disabled output
878 buffering, leaving the output in the original (usually line buffered)
879 mode.
880 In the current implementation, ncurses performs its own buffering and
882 does not require this workaround. It does not modify the buffering of
883 the standard output.
884 The reason for the change was to make the behavior for interrupts and
886 other signals more robust. One drawback is that certain nonconven‐
887 tional programs would mix ordinary stdio calls with ncurses calls and
888 (usually) work. This is no longer possible since ncurses is not using
889 the buffered standard output but its own output (to the same file
890 descriptor). As a special case, the low-level calls such as putp still
891 use the standard output. But high-level curses calls do not.
892 NCURSES_NO_UTF8_ACS
894 During initialization, the ncurses library checks for special cases
895 where VT100 line-drawing (and the corresponding alternate character set
896 capabilities) described in the terminfo are known to be missing.
897 Specifically, when running in a UTF-8 locale, the Linux console emula‐
898 tor and the GNU screen program ignore these. Ncurses checks the TERM
899 environment variable for these. For other special cases, you should
900 set this environment variable. Doing this tells ncurses to use Unicode
901 values which correspond to the VT100 line-drawing glyphs. That works
902 for the special cases cited, and is likely to work for terminal emula‐
903 tors.
904 When setting this variable, you should set it to a nonzero value. Set‐
906 ting it to zero (or to a nonnumber) disables the special check for
907 “linux” and “screen”.
908 As an alternative to the environment variable, ncurses checks for an
910 extended terminfo capability U8. This is a numeric capability which
911 can be compiled using tic -x. For example
912 # linux console, if patched to provide working
914 # VT100 shift-in/shift-out, with corresponding font.
915 linux-vt100|linux console with VT100 line-graphics,
916 U8#0, use=linux,
917 # uxterm with vt100Graphics resource set to false
919 xterm-utf8|xterm relying on UTF-8 line-graphics,
920 U8#1, use=xterm,
921 The name “U8” is chosen to be two characters, to permit it to be used
923 by applications that use ncurses' termcap interface.
924 NCURSES_TRACE
926 During initialization, the ncurses debugging library checks the
927 NCURSES_TRACE environment variable. If it is defined, to a numeric
928 value, ncurses calls the trace function, using that value as the argu‐
929 ment.
930 The argument values, which are defined in curses.h, provide several
932 types of information. When running with traces enabled, your applica‐
933 tion will write the file trace to the current directory.
934 See curs_trace(3X) for more information.
936 TERM
938 Denotes your terminal type. Each terminal type is distinct, though
939 many are similar.
940 TERM is commonly set by terminal emulators to help applications find a
942 workable terminal description. Some of those choose a popular approxi‐
943 mation, e.g., “ansi”, “vt100”, “xterm” rather than an exact fit. Not
944 infrequently, your application will have problems with that approach,
945 e.g., incorrect function-key definitions.
946 If you set TERM in your environment, it has no effect on the operation
948 of the terminal emulator. It only affects the way applications work
949 within the terminal. Likewise, as a general rule (xterm being a rare
950 exception), terminal emulators which allow you to specify TERM as a
951 parameter or configuration value do not change their behavior to match
952 that setting.
953 TERMCAP
955 If the ncurses library has been configured with termcap support,
956 ncurses will check for a terminal's description in termcap form if it
957 is not available in the terminfo database.
958 The TERMCAP environment variable contains either a terminal description
960 (with newlines stripped out), or a file name telling where the informa‐
961 tion denoted by the TERM environment variable exists. In either case,
962 setting it directs ncurses to ignore the usual place for this informa‐
963 tion, e.g., /etc/termcap.
964 TERMINFO
966 ncurses can be configured to read from multiple terminal databases.
967 The TERMINFO variable overrides the location for the default terminal
968 database. Terminal descriptions (in terminal format) are stored in
969 terminal databases:
970 · Normally these are stored in a directory tree, using subdirectories
972 named by the first letter of the terminal names therein.
973 This is the scheme used in System V, which legacy Unix systems use,
975 and the TERMINFO variable is used by curses applications on those
976 systems to override the default location of the terminal database.
977 · If ncurses is built to use hashed databases, then each entry in
979 this list may be the path of a hashed database file, e.g.,
980 /usr/share/terminfo.db
982 rather than
984 /usr/share/terminfo/
986 The hashed database uses less disk-space and is a little faster
988 than the directory tree. However, some applications assume the
989 existence of the directory tree, reading it directly rather than
990 using the terminfo library calls.
991 · If ncurses is built with a support for reading termcap files
993 directly, then an entry in this list may be the path of a termcap
994 file.
995 · If the TERMINFO variable begins with “hex:” or “b64:”, ncurses uses
997 the remainder of that variable as a compiled terminal description.
998 You might produce the base64 format using infocmp(1M):
999 TERMINFO="$(infocmp -0 -Q2 -q)"
1001 export TERMINFO
1002 The compiled description is used if it corresponds to the terminal
1004 identified by the TERM variable.
1005 Setting TERMINFO is the simplest, but not the only way to set location
1007 of the default terminal database. The complete list of database loca‐
1008 tions in order follows:
1009 · the last terminal database to which ncurses wrote, if any, is
1011 searched first
1012 · the location specified by the TERMINFO environment variable
1014 · $HOME/.terminfo
1016 · locations listed in the TERMINFO_DIRS environment variable
1018 · one or more locations whose names are configured and compiled
1020 into the ncurses library, i.e.,
1021 · no default value (corresponding to the TERMINFO_DIRS vari‐
1023 able)
1024 · /usr/share/terminfo (corresponding to the TERMINFO variable)
1026 TERMINFO_DIRS
1028 Specifies a list of locations to search for terminal descriptions.
1029 Each location in the list is a terminal database as described in the
1030 section on the TERMINFO variable. The list is separated by colons
1031 (i.e., ":") on Unix, semicolons on OS/2 EMX.
1032 There is no corresponding feature in System V terminfo; it is an exten‐
1034 sion developed for ncurses.
1035 TERMPATH
1037 If TERMCAP does not hold a file name then ncurses checks the TERMPATH
1038 environment variable. This is a list of filenames separated by spaces
1039 or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1040 If the TERMPATH environment variable is not set, ncurses looks in the
1042 files
1043 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1045 in that order.
1047 The library may be configured to disregard the following variables when
1049 the current user is the superuser (root), or if the application uses
1050 setuid or setgid permissions:
1051 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1053
1055 Several different configurations are possible, depending on the config‐
1056 ure script options used when building ncurses. There are a few main
1057 options whose effects are visible to the applications developer using
1058 ncurses:
1059 --disable-overwrite
1061 The standard include for ncurses is as noted in SYNOPSIS:
1062 #include <curses.h>
1064 This option is used to avoid filename conflicts when ncurses is
1066 not the main implementation of curses of the computer. If ncurses
1067 is installed disabling overwrite, it puts its headers in a subdi‐
1068 rectory, e.g.,
1069 #include <ncurses/curses.h>
1071 It also omits a symbolic link which would allow you to use
1073 -lcurses to build executables.
1074 --enable-widec
1076 The configure script renames the library and (if the --dis‐
1077 able-overwrite option is used) puts the header files in a differ‐
1078 ent subdirectory. All of the library names have a “w” appended to
1079 them, i.e., instead of
1080 -lncurses
1082 you link with
1084 -lncursesw
1086 You must also enable the wide-character features in the header
1088 file when compiling for the wide-character library to use the
1089 extended (wide-character) functions. The symbol which enables
1090 these features has changed since XSI Curses, Issue 4:
1091 · Originally, the wide-character feature required the symbol
1093 _XOPEN_SOURCE_EXTENDED but that was only valid for XPG4
1094 (1996).
1095 · Later, that was deemed conflicting with _XOPEN_SOURCE defined
1097 to 500.
1098 · As of mid-2018, none of the features in this implementation
1100 require a _XOPEN_SOURCE feature greater than 600. However,
1101 X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1102 · Alternatively, you can enable the feature by defining
1104 NCURSES_WIDECHAR with the caveat that some other header file
1105 than curses.h may require a specific value for _XOPEN_SOURCE
1106 (or a system-specific symbol).
1107 The curses.h file which is installed for the wide-character
1109 library is designed to be compatible with the normal library's
1110 header. Only the size of the WINDOW structure differs, and very
1111 few applications require more than a pointer to WINDOWs.
1112 If the headers are installed allowing overwrite, the wide-charac‐
1114 ter library's headers should be installed last, to allow applica‐
1115 tions to be built using either library from the same set of head‐
1116 ers.
1117 --with-pthread
1119 The configure script renames the library. All of the library
1120 names have a “t” appended to them (before any “w” added by
1121 --enable-widec).
1122 The global variables such as LINES are replaced by macros to allow
1124 read-only access. At the same time, setter-functions are provided
1125 to set these values. Some applications (very few) may require
1126 changes to work with this convention.
1127 --with-shared
1129 --with-normal
1131 --with-debug
1133 --with-profile
1135 The shared and normal (static) library names differ by their suf‐
1136 fixes, e.g., libncurses.so and libncurses.a. The debug and pro‐
1137 filing libraries add a “_g” and a “_p” to the root names respec‐
1138 tively, e.g., libncurses_g.a and libncurses_p.a.
1139 --with-trace
1141 The trace function normally resides in the debug library, but it
1142 is sometimes useful to configure this in the shared library. Con‐
1143 figure scripts should check for the function's existence rather
1144 than assuming it is always in the debug library.
1145
1147 /usr/share/tabset
1148 directory containing initialization files for the terminal capa‐
1149 bility database /usr/share/terminfo terminal capability database
1150
1152 terminfo(5) and related pages whose names begin “curs_” for detailed
1153 routine descriptions.
1154 curs_variables(3X)
1155 user_caps(5) for user-defined capabilities
1156
1158 The ncurses library can be compiled with an option (-DUSE_GETCAP) that
1159 falls back to the old-style /etc/termcap file if the terminal setup
1160 code cannot find a terminfo entry corresponding to TERM. Use of this
1161 feature is not recommended, as it essentially includes an entire term‐
1162 cap compiler in the ncurses startup code, at significant cost in core
1163 and startup cycles.
1164 The ncurses library includes facilities for capturing mouse events on
1166 certain terminals (including xterm). See the curs_mouse(3X) manual
1167 page for details.
1168 The ncurses library includes facilities for responding to window resiz‐
1170 ing events, e.g., when running in an xterm. See the resizeterm(3X) and
1171 wresize(3X) manual pages for details. In addition, the library may be
1172 configured with a SIGWINCH handler.
1173 The ncurses library extends the fixed set of function key capabilities
1175 of terminals by allowing the application designer to define additional
1176 key sequences at runtime. See the define_key(3X) key_defined(3X), and
1177 keyok(3X) manual pages for details.
1178 The ncurses library can exploit the capabilities of terminals which
1180 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
1181 application to reset the terminal to its original foreground and back‐
1182 ground colors. From the users' perspective, the application is able to
1183 draw colored text on a background whose color is set independently,
1184 providing better control over color contrasts. See the default_col‐
1185 ors(3X) manual page for details.
1186 The ncurses library includes a function for directing application out‐
1188 put to a printer attached to the terminal device. See the
1189 curs_print(3X) manual page for details.
1190
1192 The ncurses library is intended to be BASE-level conformant with XSI
1193 Curses. The EXTENDED XSI Curses functionality (including color sup‐
1194 port) is supported.
1195 A small number of local differences (that is, individual differences
1197 between the XSI Curses and ncurses calls) are described in PORTABILITY
1198 sections of the library man pages.
1199 Error checking
1201 In many cases, X/Open Curses is vague about error conditions, omitting
1202 some of the SVr4 documentation.
1203 Unlike other implementations, this one checks parameters such as point‐
1205 ers to WINDOW structures to ensure they are not null. The main reason
1206 for providing this behavior is to guard against programmer error. The
1207 standard interface does not provide a way for the library to tell an
1208 application which of several possible errors were detected. Relying on
1209 this (or some other) extension will adversely affect the portability of
1210 curses applications.
1211 Extensions versus portability
1213 Most of the extensions provided by ncurses have not been standardized.
1214 Some have been incorporated into other implementations, such as
1215 PDCurses or NetBSD curses. Here are a few to consider:
1216 · The routine has_key is not part of XPG4, nor is it present in SVr4.
1218 See the curs_getch(3X) manual page for details.
1219 · The routine slk_attr is not part of XPG4, nor is it present in
1221 SVr4. See the curs_slk(3X) manual page for details.
1222 · The routines getmouse, mousemask, ungetmouse, mouseinterval, and
1224 wenclose relating to mouse interfacing are not part of XPG4, nor
1225 are they present in SVr4. See the curs_mouse(3X) manual page for
1226 details.
1227 · The routine mcprint was not present in any previous curses imple‐
1229 mentation. See the curs_print(3X) manual page for details.
1230 · The routine wresize is not part of XPG4, nor is it present in SVr4.
1232 See the wresize(3X) manual page for details.
1233 · The WINDOW structure's internal details can be hidden from applica‐
1235 tion programs. See curs_opaque(3X) for the discussion of is_scrol‐
1236 lok, etc.
1237 · This implementation can be configured to provide rudimentary sup‐
1239 port for multi-threaded applications. See curs_threads(3X) for
1240 details.
1241 · This implementation can also be configured to provide a set of
1243 functions which improve the ability to manage multiple screens.
1244 See curs_sp_funcs(3X) for details.
1245 Padding differences
1247 In historic curses versions, delays embedded in the capabilities cr,
1248 ind, cub1, ff and tab activated corresponding delay bits in the UNIX
1249 tty driver. In this implementation, all padding is done by sending NUL
1250 bytes. This method is slightly more expensive, but narrows the inter‐
1251 face to the UNIX kernel significantly and increases the package's
1252 portability correspondingly.
1253 Header files
1255 The header file <curses.h> automatically includes the header files
1256 <stdio.h> and <unctrl.h>.
1257 X/Open Curses has more to say, but does not finish the story:
1259 The inclusion of <curses.h> may make visible all symbols from the
1261 headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1262 Here is a more complete story:
1264 · Starting with BSD curses, all implementations have included
1266 <stdio.h>.
1267 BSD curses included <curses.h> and <unctrl.h> from an internal
1269 header "curses.ext" ("ext" was a short name for externs).
1270 BSD curses used <stdio.h> internally (for printw and scanw), but
1272 nothing in <curses.h> itself relied upon <stdio.h>.
1273 · SVr2 curses added newterm(3X), which relies upon <stdio.h>. That
1275 is, the function prototype uses FILE.
1276 SVr4 curses added putwin and getwin, which also use <stdio.h>.
1278 X/Open Curses documents all three of these functions.
1280 SVr4 curses and X/Open Curses do not require the developer to
1282 include <stdio.h> before including <curses.h>. Both document
1283 curses showing <curses.h> as the only required header.
1284 As a result, standard <curses.h> will always include <stdio.h>.
1286 · X/Open Curses is inconsistent with respect to SVr4 regarding <unc‐
1288 trl.h>.
1289 As noted in curs_util(3X), ncurses includes <unctrl.h> from
1291 <curses.h> (like SVr4).
1292 · X/Open's comments about <term.h> and <termios.h> may refer to HP-UX
1294 and AIX:
1295 HP-UX curses includes <term.h> from <curses.h> to declare setupterm
1297 in curses.h, but ncurses (and Solaris curses) do not.
1298 AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
1300 Solaris curses) do not.
1301 · X/Open says that <curses.h> may include <term.h>, but there is no
1303 requirement that it do that.
1304 Some programs use functions declared in both <curses.h> and
1306 <term.h>, and must include both headers in the same module. Very
1307 old versions of AIX curses required including <curses.h> before
1308 including <term.h>.
1309 Because ncurses header files include the headers needed to define
1311 datatypes used in the headers, ncurses header files can be included
1312 in any order. But for portability, you should include <curses.h>
1313 before <term.h>.
1314 · X/Open Curses says "may make visible" because including a header
1316 file does not necessarily make all symbols in it visible (there are
1317 ifdef's to consider).
1318 For instance, in ncurses <wchar.h> may be included if the proper
1320 symbol is defined, and if ncurses is configured for wide-character
1321 support. If the header is included, its symbols may be made visi‐
1322 ble. That depends on the value used for _XOPEN_SOURCE feature test
1323 macro.
1324
1326 If standard output from a ncurses program is re-directed to something
1327 which is not a tty, screen updates will be directed to standard error.
1328 This was an undocumented feature of AT&T System V Release 3 curses.
1329
1331 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses
1332 by Pavel Curtis.
1333 ncurses(3X)