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.1 (patch 20180224).
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 wchar_t
212 stores a "wide" character. Like chtype, this may be an
213 integer.
214 wint_t
216 stores a wchar_t or WEOF - not the same, though both may
217 have the same size.
218 The "wide" library provides new functions which are analogous
220 to functions in the "normal" library. There is a naming con‐
221 vention which relates many of the normal/wide variants: a "_w"
222 is inserted into the name. For example, waddch becomes
223 wadd_wch.
224 Routine Name Index
226 The following table lists each curses routine and the name of the man‐
227 ual page on which it is described. Routines flagged with “*” are
228 ncurses-specific, not described by XPG4 or present in SVr4.
229 curses Routine Name Manual Page Name
231 ─────────────────────────────────────────────
232 COLOR_PAIR curs_color(3X)
233 PAIR_NUMBER curs_attr(3X)
234 _nc_free_and_exit curs_memleaks(3X)*
235 _nc_freeall curs_memleaks(3X)*
236 _nc_tracebits curs_trace(3X)*
237 _traceattr curs_trace(3X)*
238 _traceattr2 curs_trace(3X)*
239 _tracechar curs_trace(3X)*
240 _tracechtype curs_trace(3X)*
241 _tracechtype2 curs_trace(3X)*
242 _tracedump curs_trace(3X)*
243 _tracef curs_trace(3X)*
244 _tracemouse curs_trace(3X)*
245 add_wch curs_add_wch(3X)
246 add_wchnstr curs_add_wchstr(3X)
247 add_wchstr curs_add_wchstr(3X)
248 addch curs_addch(3X)
249 addchnstr curs_addchstr(3X)
250 addchstr curs_addchstr(3X)
251 addnstr curs_addstr(3X)
252 addnwstr curs_addwstr(3X)
253 addstr curs_addstr(3X)
254 addwstr curs_addwstr(3X)
255 alloc_pair new_pair(3X)*
256 assume_default_colors default_colors(3X)*
257 attr_get curs_attr(3X)
258 attr_off curs_attr(3X)
259 attr_on curs_attr(3X)
260 attr_set curs_attr(3X)
261 attroff curs_attr(3X)
262 attron curs_attr(3X)
263 attrset curs_attr(3X)
264 baudrate curs_termattrs(3X)
266 beep curs_beep(3X)
267 bkgd curs_bkgd(3X)
268 bkgdset curs_bkgd(3X)
269 bkgrnd curs_bkgrnd(3X)
270 bkgrndset curs_bkgrnd(3X)
271 border curs_border(3X)
272 border_set curs_border_set(3X)
273 box curs_border(3X)
274 box_set curs_border_set(3X)
275 can_change_color curs_color(3X)
276 cbreak curs_inopts(3X)
277 chgat curs_attr(3X)
278 clear curs_clear(3X)
279 clearok curs_outopts(3X)
280 clrtobot curs_clear(3X)
281 clrtoeol curs_clear(3X)
282 color_content curs_color(3X)
283 color_set curs_attr(3X)
284 copywin curs_overlay(3X)
285 curs_set curs_kernel(3X)
286 curses_version curs_extend(3X)*
287 def_prog_mode curs_kernel(3X)
288 def_shell_mode curs_kernel(3X)
289 define_key define_key(3X)*
290 del_curterm curs_terminfo(3X)
291 delay_output curs_util(3X)
292 delch curs_delch(3X)
293 deleteln curs_deleteln(3X)
294 delscreen curs_initscr(3X)
295 delwin curs_window(3X)
296 derwin curs_window(3X)
297 doupdate curs_refresh(3X)
298 dupwin curs_window(3X)
299 echo curs_inopts(3X)
300 echo_wchar curs_add_wch(3X)
301 echochar curs_addch(3X)
302 endwin curs_initscr(3X)
303 erase curs_clear(3X)
304 erasechar curs_termattrs(3X)
305 erasewchar curs_termattrs(3X)
306 extended_color_content curs_color(3X)*
307 extended_pair_content curs_color(3X)*
308 extended_slk_color curs_slk(3X)*
309 filter curs_util(3X)
310 find_pair new_pair(3X)*
311 flash curs_beep(3X)
312 flushinp curs_util(3X)
313 free_pair new_pair(3X)*
314 get_wch curs_get_wch(3X)
315 get_wstr curs_get_wstr(3X)
316 getattrs curs_attr(3X)
317 getbegx curs_legacy(3X)*
318 getbegy curs_legacy(3X)*
319 getbegyx curs_getyx(3X)
320 getbkgd curs_bkgd(3X)
321 getbkgrnd curs_bkgrnd(3X)
322 getcchar curs_getcchar(3X)
323 getch curs_getch(3X)
324 getcurx curs_legacy(3X)*
325 getcury curs_legacy(3X)*
326 getmaxx curs_legacy(3X)*
327 getmaxy curs_legacy(3X)*
328 getmaxyx curs_getyx(3X)
329 getmouse curs_mouse(3X)*
330 getn_wstr curs_get_wstr(3X)
332 getnstr curs_getstr(3X)
333 getparx curs_legacy(3X)*
334 getpary curs_legacy(3X)*
335 getparyx curs_getyx(3X)
336 getstr curs_getstr(3X)
337 getsyx curs_kernel(3X)
338 getwin curs_util(3X)
339 getyx curs_getyx(3X)
340 halfdelay curs_inopts(3X)
341 has_colors curs_color(3X)
342 has_ic curs_termattrs(3X)
343 has_il curs_termattrs(3X)
344 has_key curs_getch(3X)*
345 hline curs_border(3X)
346 hline_set curs_border_set(3X)
347 idcok curs_outopts(3X)
348 idlok curs_outopts(3X)
349 immedok curs_outopts(3X)
350 in_wch curs_in_wch(3X)
351 in_wchnstr curs_in_wchstr(3X)
352 in_wchstr curs_in_wchstr(3X)
353 inch curs_inch(3X)
354 inchnstr curs_inchstr(3X)
355 inchstr curs_inchstr(3X)
356 init_color curs_color(3X)
357 init_extended_color curs_color(3X)*
358 init_extended_pair curs_color(3X)*
359 init_pair curs_color(3X)
360 initscr curs_initscr(3X)
361 innstr curs_instr(3X)
362 innwstr curs_inwstr(3X)
363 ins_nwstr curs_ins_wstr(3X)
364 ins_wch curs_ins_wch(3X)
365 ins_wstr curs_ins_wstr(3X)
366 insch curs_insch(3X)
367 insdelln curs_deleteln(3X)
368 insertln curs_deleteln(3X)
369 insnstr curs_insstr(3X)
370 insstr curs_insstr(3X)
371 instr curs_instr(3X)
372 intrflush curs_inopts(3X)
373 inwstr curs_inwstr(3X)
374 is_cleared curs_opaque(3X)*
375 is_idcok curs_opaque(3X)*
376 is_idlok curs_opaque(3X)*
377 is_immedok curs_opaque(3X)*
378 is_keypad curs_opaque(3X)*
379 is_leaveok curs_opaque(3X)*
380 is_linetouched curs_touch(3X)
381 is_nodelay curs_opaque(3X)*
382 is_notimeout curs_opaque(3X)*
383 is_pad curs_opaque(3X)*
384 is_scrollok curs_opaque(3X)*
385 is_subwin curs_opaque(3X)*
386 is_syncok curs_opaque(3X)*
387 is_term_resized resizeterm(3X)*
388 is_wintouched curs_touch(3X)
389 isendwin curs_initscr(3X)
390 key_defined key_defined(3X)*
391 key_name curs_util(3X)
392 keybound keybound(3X)*
393 keyname curs_util(3X)
394 keyok keyok(3X)*
395 keypad curs_inopts(3X)
396 killchar curs_termattrs(3X)
398 killwchar curs_termattrs(3X)
399 leaveok curs_outopts(3X)
400 longname curs_termattrs(3X)
401 mcprint curs_print(3X)*
402 meta curs_inopts(3X)
403 mouse_trafo curs_mouse(3X)*
404 mouseinterval curs_mouse(3X)*
405 mousemask curs_mouse(3X)*
406 move curs_move(3X)
407 mvadd_wch curs_add_wch(3X)
408 mvadd_wchnstr curs_add_wchstr(3X)
409 mvadd_wchstr curs_add_wchstr(3X)
410 mvaddch curs_addch(3X)
411 mvaddchnstr curs_addchstr(3X)
412 mvaddchstr curs_addchstr(3X)
413 mvaddnstr curs_addstr(3X)
414 mvaddnwstr curs_addwstr(3X)
415 mvaddstr curs_addstr(3X)
416 mvaddwstr curs_addwstr(3X)
417 mvchgat curs_attr(3X)
418 mvcur curs_terminfo(3X)
419 mvdelch curs_delch(3X)
420 mvderwin curs_window(3X)
421 mvget_wch curs_get_wch(3X)
422 mvget_wstr curs_get_wstr(3X)
423 mvgetch curs_getch(3X)
424 mvgetn_wstr curs_get_wstr(3X)
425 mvgetnstr curs_getstr(3X)
426 mvgetstr curs_getstr(3X)
427 mvhline curs_border(3X)
428 mvhline_set curs_border_set(3X)
429 mvin_wch curs_in_wch(3X)
430 mvin_wchnstr curs_in_wchstr(3X)
431 mvin_wchstr curs_in_wchstr(3X)
432 mvinch curs_inch(3X)
433 mvinchnstr curs_inchstr(3X)
434 mvinchstr curs_inchstr(3X)
435 mvinnstr curs_instr(3X)
436 mvinnwstr curs_inwstr(3X)
437 mvins_nwstr curs_ins_wstr(3X)
438 mvins_wch curs_ins_wch(3X)
439 mvins_wstr curs_ins_wstr(3X)
440 mvinsch curs_insch(3X)
441 mvinsnstr curs_insstr(3X)
442 mvinsstr curs_insstr(3X)
443 mvinstr curs_instr(3X)
444 mvinwstr curs_inwstr(3X)
445 mvprintw curs_printw(3X)
446 mvscanw curs_scanw(3X)
447 mvvline curs_border(3X)
448 mvvline_set curs_border_set(3X)
449 mvwadd_wch curs_add_wch(3X)
450 mvwadd_wchnstr curs_add_wchstr(3X)
451 mvwadd_wchstr curs_add_wchstr(3X)
452 mvwaddch curs_addch(3X)
453 mvwaddchnstr curs_addchstr(3X)
454 mvwaddchstr curs_addchstr(3X)
455 mvwaddnstr curs_addstr(3X)
456 mvwaddnwstr curs_addwstr(3X)
457 mvwaddstr curs_addstr(3X)
458 mvwaddwstr curs_addwstr(3X)
459 mvwchgat curs_attr(3X)
460 mvwdelch curs_delch(3X)
461 mvwget_wch curs_get_wch(3X)
462 mvwget_wstr curs_get_wstr(3X)
464 mvwgetch curs_getch(3X)
465 mvwgetn_wstr curs_get_wstr(3X)
466 mvwgetnstr curs_getstr(3X)
467 mvwgetstr curs_getstr(3X)
468 mvwhline curs_border(3X)
469 mvwhline_set curs_border_set(3X)
470 mvwin curs_window(3X)
471 mvwin_wch curs_in_wch(3X)
472 mvwin_wchnstr curs_in_wchstr(3X)
473 mvwin_wchstr curs_in_wchstr(3X)
474 mvwinch curs_inch(3X)
475 mvwinchnstr curs_inchstr(3X)
476 mvwinchstr curs_inchstr(3X)
477 mvwinnstr curs_instr(3X)
478 mvwinnwstr curs_inwstr(3X)
479 mvwins_nwstr curs_ins_wstr(3X)
480 mvwins_wch curs_ins_wch(3X)
481 mvwins_wstr curs_ins_wstr(3X)
482 mvwinsch curs_insch(3X)
483 mvwinsnstr curs_insstr(3X)
484 mvwinsstr curs_insstr(3X)
485 mvwinstr curs_instr(3X)
486 mvwinwstr curs_inwstr(3X)
487 mvwprintw curs_printw(3X)
488 mvwscanw curs_scanw(3X)
489 mvwvline curs_border(3X)
490 mvwvline_set curs_border_set(3X)
491 napms curs_kernel(3X)
492 newpad curs_pad(3X)
493 newterm curs_initscr(3X)
494 newwin curs_window(3X)
495 nl curs_outopts(3X)
496 nocbreak curs_inopts(3X)
497 nodelay curs_inopts(3X)
498 noecho curs_inopts(3X)
499 nofilter curs_util(3X)*
500 nonl curs_outopts(3X)
501 noqiflush curs_inopts(3X)
502 noraw curs_inopts(3X)
503 notimeout curs_inopts(3X)
504 overlay curs_overlay(3X)
505 overwrite curs_overlay(3X)
506 pair_content curs_color(3X)
507 pechochar curs_pad(3X)
508 pnoutrefresh curs_pad(3X)
509 prefresh curs_pad(3X)
510 printw curs_printw(3X)
511 putp curs_terminfo(3X)
512 putwin curs_util(3X)
513 qiflush curs_inopts(3X)
514 raw curs_inopts(3X)
515 redrawwin curs_refresh(3X)
516 refresh curs_refresh(3X)
517 reset_prog_mode curs_kernel(3X)
518 reset_shell_mode curs_kernel(3X)
519 resetty curs_kernel(3X)
520 resize_term resizeterm(3X)*
521 resizeterm resizeterm(3X)*
522 restartterm curs_terminfo(3X)
523 ripoffline curs_kernel(3X)
524 savetty curs_kernel(3X)
525 scanw curs_scanw(3X)
526 scr_dump curs_scr_dump(3X)
527 scr_init curs_scr_dump(3X)
528 scr_restore curs_scr_dump(3X)
530 scr_set curs_scr_dump(3X)
531 scrl curs_scroll(3X)
532 scroll curs_scroll(3X)
533 scrollok curs_outopts(3X)
534 set_curterm curs_terminfo(3X)
535 set_term curs_initscr(3X)
536 setcchar curs_getcchar(3X)
537 setscrreg curs_outopts(3X)
538 setsyx curs_kernel(3X)
539 setterm curs_terminfo(3X)
540 setupterm curs_terminfo(3X)
541 slk_attr curs_slk(3X)*
542 slk_attr_off curs_slk(3X)
543 slk_attr_on curs_slk(3X)
544 slk_attr_set curs_slk(3X)
545 slk_attroff curs_slk(3X)
546 slk_attron curs_slk(3X)
547 slk_attrset curs_slk(3X)
548 slk_clear curs_slk(3X)
549 slk_color curs_slk(3X)
550 slk_init curs_slk(3X)
551 slk_label curs_slk(3X)
552 slk_noutrefresh curs_slk(3X)
553 slk_refresh curs_slk(3X)
554 slk_restore curs_slk(3X)
555 slk_set curs_slk(3X)
556 slk_touch curs_slk(3X)
557 standend curs_attr(3X)
558 standout curs_attr(3X)
559 start_color curs_color(3X)
560 subpad curs_pad(3X)
561 subwin curs_window(3X)
562 syncok curs_window(3X)
563 term_attrs curs_termattrs(3X)
564 termattrs curs_termattrs(3X)
565 termname curs_termattrs(3X)
566 tgetent curs_termcap(3X)
567 tgetflag curs_termcap(3X)
568 tgetnum curs_termcap(3X)
569 tgetstr curs_termcap(3X)
570 tgoto curs_termcap(3X)
571 tigetflag curs_terminfo(3X)
572 tigetnum curs_terminfo(3X)
573 tigetstr curs_terminfo(3X)
574 timeout curs_inopts(3X)
575 tiparm 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
691 Routines that return an integer return ERR upon failure and an integer
692 value other than ERR upon successful completion, unless otherwise noted
693 in the routine descriptions.
694 As a general rule, routines check for null pointers passed as parame‐
696 ters, and handle this as an error.
697 All macros return the value of the w version, except setscrreg,
699 wsetscrreg, getyx, getbegyx, and getmaxyx. The return values of
700 setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined
701 (i.e., these should not be used as the right-hand side of assignment
702 statements).
703 Routines that return pointers return NULL on error.
705
707 The following environment symbols are useful for customizing the run‐
708 time behavior of the ncurses library. The most important ones have
709 been already discussed in detail.
710 CC command-character
712 When set, change occurrences of the command_character (i.e., the cmdch
713 capability) of the loaded terminfo entries to the value of this vari‐
714 able. Very few terminfo entries provide this feature.
715 Because this name is also used in development environments to represent
717 the C compiler's name, ncurses ignores it if it does not happen to be a
718 single character.
719 BAUDRATE
721 The debugging library checks this environment variable when the appli‐
722 cation has redirected output to a file. The variable's numeric value
723 is used for the baudrate. If no value is found, ncurses uses 9600.
724 This allows testers to construct repeatable test-cases that take into
725 account costs that depend on baudrate.
726 COLUMNS
728 Specify the width of the screen in characters. Applications running in
729 a windowing environment usually are able to obtain the width of the
730 window in which they are executing. If neither the COLUMNS value nor
731 the terminal's screen size is available, ncurses uses the size which
732 may be specified in the terminfo database (i.e., the cols capability).
733 It is important that your application use a correct size for the
735 screen. This is not always possible because your application may be
736 running on a host which does not honor NAWS (Negotiations About Window
737 Size), or because you are temporarily running as another user. How‐
738 ever, setting COLUMNS and/or LINES overrides the library's use of the
739 screen size obtained from the operating system.
740 Either COLUMNS or LINES symbols may be specified independently. This
742 is mainly useful to circumvent legacy misfeatures of terminal descrip‐
743 tions, e.g., xterm which commonly specifies a 65 line screen. For best
744 results, lines and cols should not be specified in a terminal descrip‐
745 tion for terminals which are run as emulations.
746 Use the use_env function to disable all use of external environment
748 (but not including system calls) to determine the screen size. Use the
749 use_tioctl function to update COLUMNS or LINES to match the screen size
750 obtained from system calls or the terminal database.
751 ESCDELAY
753 Specifies the total time, in milliseconds, for which ncurses will await
754 a character sequence, e.g., a function key. The default value, 1000
755 milliseconds, is enough for most uses. However, it is made a variable
756 to accommodate unusual applications.
757 The most common instance where you may wish to change this value is to
759 work with slow hosts, e.g., running on a network. If the host cannot
760 read characters rapidly enough, it will have the same effect as if the
761 terminal did not send characters rapidly enough. The library will
762 still see a timeout.
763 Note that xterm mouse events are built up from character sequences
765 received from the xterm. If your application makes heavy use of multi‐
766 ple-clicking, you may wish to lengthen this default value because the
767 timeout applies to the composed multi-click event as well as the indi‐
768 vidual clicks.
769 In addition to the environment variable, this implementation provides a
771 global variable with the same name. Portable applications should not
772 rely upon the presence of ESCDELAY in either form, but setting the
773 environment variable rather than the global variable does not create
774 problems when compiling an application.
775 HOME
777 Tells ncurses where your home directory is. That is where it may read
778 and write auxiliary terminal descriptions:
779 $HOME/.termcap
781 $HOME/.terminfo
782 LINES
784 Like COLUMNS, specify the height of the screen in characters. See COL‐
785 UMNS for a detailed description.
786 MOUSE_BUTTONS_123
788 This applies only to the OS/2 EMX port. It specifies the order of but‐
789 tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
790 other platforms:
791 1 = left
793 2 = right
794 3 = middle.
795 This variable lets you customize the mouse. The variable must be three
797 numeric digits 1-3 in any order, e.g., 123 or 321. If it is not speci‐
798 fied, ncurses uses 132.
799 NCURSES_ASSUMED_COLORS
801 Override the compiled-in assumption that the terminal's default colors
802 are white-on-black (see default_colors(3X)). You may set the fore‐
803 ground and background color values with this environment variable by
804 proving a 2-element list: foreground,background. For example, to tell
805 ncurses to not assume anything about the colors, set this to "-1,-1".
806 To make it green-on-black, set it to "2,0". Any positive value from
807 zero to the terminfo max_colors value is allowed.
808 NCURSES_CONSOLE2
810 This applies only to the MinGW port of ncurses.
811 The Console2 program's handling of the Microsoft Console API call Cre‐
813 ateConsoleScreenBuffer is defective. Applications which use this will
814 hang. However, it is possible to simulate the action of this call by
815 mapping coordinates, explicitly saving and restoring the original
816 screen contents. Setting the environment variable NCGDB has the same
817 effect.
818 NCURSES_GPM_TERMS
820 This applies only to ncurses configured to use the GPM interface.
821 If present, the environment variable is a list of one or more terminal
823 names against which the TERM environment variable is matched. Setting
824 it to an empty value disables the GPM interface; using the built-in
825 support for xterm, etc.
826 If the environment variable is absent, ncurses will attempt to open GPM
828 if TERM contains "linux".
829 NCURSES_NO_HARD_TABS
831 Ncurses may use tabs as part of the cursor movement optimization. In
832 some cases, your terminal driver may not handle these properly. Set
833 this environment variable to disable the feature. You can also adjust
834 your stty settings to avoid the problem.
835 NCURSES_NO_MAGIC_COOKIE
837 Some terminals use a magic-cookie feature which requires special han‐
838 dling to make highlighting and other video attributes display properly.
839 You can suppress the highlighting entirely for these terminals by set‐
840 ting this environment variable.
841 NCURSES_NO_PADDING
843 Most of the terminal descriptions in the terminfo database are written
844 for real "hardware" terminals. Many people use terminal emulators
845 which run in a windowing environment and use curses-based applications.
846 Terminal emulators can duplicate all of the important aspects of a
847 hardware terminal, but they do not have the same limitations. The
848 chief limitation of a hardware terminal from the standpoint of your
849 application is the management of dataflow, i.e., timing. Unless a
850 hardware terminal is interfaced into a terminal concentrator (which
851 does flow control), it (or your application) must manage dataflow, pre‐
852 venting overruns. The cheapest solution (no hardware cost) is for your
853 program to do this by pausing after operations that the terminal does
854 slowly, such as clearing the display.
855 As a result, many terminal descriptions (including the vt100) have
857 delay times embedded. You may wish to use these descriptions, but not
858 want to pay the performance penalty.
859 Set the NCURSES_NO_PADDING environment variable to disable all but
861 mandatory padding. Mandatory padding is used as a part of special con‐
862 trol sequences such as flash.
863 NCURSES_NO_SETBUF
865 This setting is obsolete. Before changes
866 · started with 5.9 patch 20120825 and
868 · continued though 5.9 patch 20130126
870 ncurses enabled buffered output during terminal initialization. This
872 was done (as in SVr4 curses) for performance reasons. For testing pur‐
873 poses, both of ncurses and certain applications, this feature was made
874 optional. Setting the NCURSES_NO_SETBUF variable disabled output
875 buffering, leaving the output in the original (usually line buffered)
876 mode.
877 In the current implementation, ncurses performs its own buffering and
879 does not require this workaround. It does not modify the buffering of
880 the standard output.
881 The reason for the change was to make the behavior for interrupts and
883 other signals more robust. One drawback is that certain nonconven‐
884 tional programs would mix ordinary stdio calls with ncurses calls and
885 (usually) work. This is no longer possible since ncurses is not using
886 the buffered standard output but its own output (to the same file
887 descriptor). As a special case, the low-level calls such as putp still
888 use the standard output. But high-level curses calls do not.
889 NCURSES_NO_UTF8_ACS
891 During initialization, the ncurses library checks for special cases
892 where VT100 line-drawing (and the corresponding alternate character set
893 capabilities) described in the terminfo are known to be missing.
894 Specifically, when running in a UTF-8 locale, the Linux console emula‐
895 tor and the GNU screen program ignore these. Ncurses checks the TERM
896 environment variable for these. For other special cases, you should
897 set this environment variable. Doing this tells ncurses to use Unicode
898 values which correspond to the VT100 line-drawing glyphs. That works
899 for the special cases cited, and is likely to work for terminal emula‐
900 tors.
901 When setting this variable, you should set it to a nonzero value. Set‐
903 ting it to zero (or to a nonnumber) disables the special check for
904 "linux" and "screen".
905 As an alternative to the environment variable, ncurses checks for an
907 extended terminfo capability U8. This is a numeric capability which
908 can be compiled using tic -x. For example
909 # linux console, if patched to provide working
911 # VT100 shift-in/shift-out, with corresponding font.
912 linux-vt100|linux console with VT100 line-graphics,
913 U8#0, use=linux,
914 # uxterm with vt100Graphics resource set to false
916 xterm-utf8|xterm relying on UTF-8 line-graphics,
917 U8#1, use=xterm,
918 The name "U8" is chosen to be two characters, to permit it to be used
920 by applications that use ncurses' termcap interface.
921 NCURSES_TRACE
923 During initialization, the ncurses debugging library checks the
924 NCURSES_TRACE environment variable. If it is defined, to a numeric
925 value, ncurses calls the trace function, using that value as the argu‐
926 ment.
927 The argument values, which are defined in curses.h, provide several
929 types of information. When running with traces enabled, your applica‐
930 tion will write the file trace to the current directory.
931 See curs_trace(3X) for more information.
933 TERM
935 Denotes your terminal type. Each terminal type is distinct, though
936 many are similar.
937 TERM is commonly set by terminal emulators to help applications find a
939 workable terminal description. Some of those choose a popular approxi‐
940 mation, e.g., “ansi”, “vt100”, “xterm” rather than an exact fit. Not
941 infrequently, your application will have problems with that approach,
942 e.g., incorrect function-key definitions.
943 If you set TERM in your environment, it has no effect on the operation
945 of the terminal emulator. It only affects the way applications work
946 within the terminal. Likewise, as a general rule (xterm being a rare
947 exception), terminal emulators which allow you to specify TERM as a
948 parameter or configuration value do not change their behavior to match
949 that setting.
950 TERMCAP
952 If the ncurses library has been configured with termcap support,
953 ncurses will check for a terminal's description in termcap form if it
954 is not available in the terminfo database.
955 The TERMCAP environment variable contains either a terminal description
957 (with newlines stripped out), or a file name telling where the informa‐
958 tion denoted by the TERM environment variable exists. In either case,
959 setting it directs ncurses to ignore the usual place for this informa‐
960 tion, e.g., /etc/termcap.
961 TERMINFO
963 ncurses can be configured to read from multiple terminal databases.
964 The TERMINFO variable overrides the location for the default terminal
965 database. Terminal descriptions (in terminal format) are stored in
966 terminal databases:
967 · Normally these are stored in a directory tree, using subdirectories
969 named by the first letter of the terminal names therein.
970 This is the scheme used in System V, which legacy Unix systems use,
972 and the TERMINFO variable is used by curses applications on those
973 systems to override the default location of the terminal database.
974 · If ncurses is built to use hashed databases, then each entry in
976 this list may be the path of a hashed database file, e.g.,
977 /usr/share/terminfo.db
979 rather than
981 /usr/share/terminfo/
983 The hashed database uses less disk-space and is a little faster
985 than the directory tree. However, some applications assume the
986 existence of the directory tree, reading it directly rather than
987 using the terminfo library calls.
988 · If ncurses is built with a support for reading termcap files
990 directly, then an entry in this list may be the path of a termcap
991 file.
992 · If the TERMINFO variable begins with “hex:” or “b64:”, ncurses uses
994 the remainder of that variable as a compiled terminal description.
995 You might produce the base64 format using infocmp(1M):
996 TERMINFO="$(infocmp -0 -Q2 -q)"
998 export TERMINFO
999 The compiled description is used if it corresponds to the terminal
1001 identified by the TERM variable.
1002 Setting TERMINFO is the simplest, but not the only way to set location
1004 of the default terminal database. The complete list of database loca‐
1005 tions in order follows:
1006 · the last terminal database to which ncurses wrote, if any, is
1008 searched first
1009 · the location specified by the TERMINFO environment variable
1011 · $HOME/.terminfo
1013 · locations listed in the TERMINFO_DIRS environment variable
1015 · one or more locations whose names are configured and compiled
1017 into the ncurses library, i.e.,
1018 · no default value (corresponding to the TERMINFO_DIRS vari‐
1020 able)
1021 · /usr/share/terminfo (corresponding to the TERMINFO variable)
1023 TERMINFO_DIRS
1025 Specifies a list of locations to search for terminal descriptions.
1026 Each location in the list is a terminal database as described in the
1027 section on the TERMINFO variable. The list is separated by colons
1028 (i.e., ":") on Unix, semicolons on OS/2 EMX.
1029 There is no corresponding feature in System V terminfo; it is an exten‐
1031 sion developed for ncurses.
1032 TERMPATH
1034 If TERMCAP does not hold a file name then ncurses checks the TERMPATH
1035 environment variable. This is a list of filenames separated by spaces
1036 or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1037 If the TERMPATH environment variable is not set, ncurses looks in the
1039 files
1040 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1042 in that order.
1044 The library may be configured to disregard the following variables when
1046 the current user is the superuser (root), or if the application uses
1047 setuid or setgid permissions:
1048 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1050
1052 Several different configurations are possible, depending on the config‐
1053 ure script options used when building ncurses. There are a few main
1054 options whose effects are visible to the applications developer using
1055 ncurses:
1056 --disable-overwrite
1058 The standard include for ncurses is as noted in SYNOPSIS:
1059 #include <curses.h>
1061 This option is used to avoid filename conflicts when ncurses is
1063 not the main implementation of curses of the computer. If ncurses
1064 is installed disabling overwrite, it puts its headers in a subdi‐
1065 rectory, e.g.,
1066 #include <ncurses/curses.h>
1068 It also omits a symbolic link which would allow you to use
1070 -lcurses to build executables.
1071 --enable-widec
1073 The configure script renames the library and (if the --dis‐
1074 able-overwrite option is used) puts the header files in a differ‐
1075 ent subdirectory. All of the library names have a "w" appended to
1076 them, i.e., instead of
1077 -lncurses
1079 you link with
1081 -lncursesw
1083 You must also define _XOPEN_SOURCE_EXTENDED when compiling for the
1085 wide-character library to use the extended (wide-character) func‐
1086 tions. The curses.h file which is installed for the wide-charac‐
1087 ter library is designed to be compatible with the normal library's
1088 header. Only the size of the WINDOW structure differs, and very
1089 few applications require more than a pointer to WINDOWs. If the
1090 headers are installed allowing overwrite, the wide-character
1091 library's headers should be installed last, to allow applications
1092 to be built using either library from the same set of headers.
1093 --with-pthread
1095 The configure script renames the library. All of the library
1096 names have a "t" appended to them (before any "w" added by
1097 --enable-widec).
1098 The global variables such as LINES are replaced by macros to allow
1100 read-only access. At the same time, setter-functions are provided
1101 to set these values. Some applications (very few) may require
1102 changes to work with this convention.
1103 --with-shared
1105 --with-normal
1107 --with-debug
1109 --with-profile
1111 The shared and normal (static) library names differ by their suf‐
1112 fixes, e.g., libncurses.so and libncurses.a. The debug and pro‐
1113 filing libraries add a "_g" and a "_p" to the root names respec‐
1114 tively, e.g., libncurses_g.a and libncurses_p.a.
1115 --with-trace
1117 The trace function normally resides in the debug library, but it
1118 is sometimes useful to configure this in the shared library. Con‐
1119 figure scripts should check for the function's existence rather
1120 than assuming it is always in the debug library.
1121
1123 /usr/share/tabset
1124 directory containing initialization files for the terminal capa‐
1125 bility database /usr/share/terminfo terminal capability database
1126
1128 terminfo(5) and related pages whose names begin "curs_" for detailed
1129 routine descriptions.
1130 curs_variables(3X)
1131 user_caps(5) for user-defined capabilities
1132
1134 The ncurses library can be compiled with an option (-DUSE_GETCAP) that
1135 falls back to the old-style /etc/termcap file if the terminal setup
1136 code cannot find a terminfo entry corresponding to TERM. Use of this
1137 feature is not recommended, as it essentially includes an entire term‐
1138 cap compiler in the ncurses startup code, at significant cost in core
1139 and startup cycles.
1140 The ncurses library includes facilities for capturing mouse events on
1142 certain terminals (including xterm). See the curs_mouse(3X) manual
1143 page for details.
1144 The ncurses library includes facilities for responding to window resiz‐
1146 ing events, e.g., when running in an xterm. See the resizeterm(3X) and
1147 wresize(3X) manual pages for details. In addition, the library may be
1148 configured with a SIGWINCH handler.
1149 The ncurses library extends the fixed set of function key capabilities
1151 of terminals by allowing the application designer to define additional
1152 key sequences at runtime. See the define_key(3X) key_defined(3X), and
1153 keyok(3X) manual pages for details.
1154 The ncurses library can exploit the capabilities of terminals which
1156 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
1157 application to reset the terminal to its original foreground and back‐
1158 ground colors. From the users' perspective, the application is able to
1159 draw colored text on a background whose color is set independently,
1160 providing better control over color contrasts. See the default_col‐
1161 ors(3X) manual page for details.
1162 The ncurses library includes a function for directing application out‐
1164 put to a printer attached to the terminal device. See the
1165 curs_print(3X) manual page for details.
1166
1168 The ncurses library is intended to be BASE-level conformant with XSI
1169 Curses. The EXTENDED XSI Curses functionality (including color sup‐
1170 port) is supported.
1171 A small number of local differences (that is, individual differences
1173 between the XSI Curses and ncurses calls) are described in PORTABILITY
1174 sections of the library man pages.
1175 Unlike other implementations, this one checks parameters such as point‐
1177 ers to WINDOW structures to ensure they are not null. The main reason
1178 for providing this behavior is to guard against programmer error. The
1179 standard interface does not provide a way for the library to tell an
1180 application which of several possible errors were detected. Relying on
1181 this (or some other) extension will adversely affect the portability of
1182 curses applications.
1183 This implementation also contains several extensions:
1185 · The routine has_key is not part of XPG4, nor is it present in SVr4.
1187 See the curs_getch(3X) manual page for details.
1188 · The routine slk_attr is not part of XPG4, nor is it present in
1190 SVr4. See the curs_slk(3X) manual page for details.
1191 · The routines getmouse, mousemask, ungetmouse, mouseinterval, and
1193 wenclose relating to mouse interfacing are not part of XPG4, nor
1194 are they present in SVr4. See the curs_mouse(3X) manual page for
1195 details.
1196 · The routine mcprint was not present in any previous curses imple‐
1198 mentation. See the curs_print(3X) manual page for details.
1199 · The routine wresize is not part of XPG4, nor is it present in SVr4.
1201 See the wresize(3X) manual page for details.
1202 · The WINDOW structure's internal details can be hidden from applica‐
1204 tion programs. See curs_opaque(3X) for the discussion of is_scrol‐
1205 lok, etc.
1206 · This implementation can be configured to provide rudimentary sup‐
1208 port for multi-threaded applications. See curs_threads(3X) for
1209 details.
1210 · This implementation can also be configured to provide a set of
1212 functions which improve the ability to manage multiple screens.
1213 See curs_sp_funcs(3X) for details.
1214 In historic curses versions, delays embedded in the capabilities cr,
1216 ind, cub1, ff and tab activated corresponding delay bits in the UNIX
1217 tty driver. In this implementation, all padding is done by sending NUL
1218 bytes. This method is slightly more expensive, but narrows the inter‐
1219 face to the UNIX kernel significantly and increases the package's
1220 portability correspondingly.
1221
1223 The header file <curses.h> automatically includes the header files
1224 <stdio.h> and <unctrl.h>.
1225 If standard output from a ncurses program is re-directed to something
1227 which is not a tty, screen updates will be directed to standard error.
1228 This was an undocumented feature of AT&T System V Release 3 curses.
1229
1231 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses
1232 by Pavel Curtis.
1233 ncurses(3X)