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