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 5.9 (patch 20130511).
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 The library uses the locale which the calling program has initialized.
45 That is normally done with setlocale:
46 setlocale(LC_ALL, "");
48 If the locale is not initialized, the library assumes that characters
50 are printable as in ISO-8859-1, to work with certain legacy programs.
51 You should initialize the locale and not rely on specific details of
52 the library when the locale has not been setup.
53 The function initscr or newterm must be called to initialize the
55 library before any of the other routines that deal with windows and
56 screens are used. The routine endwin must be called before exiting.
57 To get character-at-a-time input without echoing (most interactive,
59 screen oriented programs want this), the following sequence should be
60 used:
61 initscr(); cbreak(); noecho();
63 Most programs would additionally use the sequence:
65 nonl();
67 intrflush(stdscr, FALSE);
68 keypad(stdscr, TRUE);
69 Before a curses program is run, the tab stops of the terminal should be
71 set and its initialization strings, if defined, must be output. This
72 can be done by executing the tput init command after the shell environ‐
73 ment variable TERM has been exported. tset(1) is usually responsible
74 for doing this. [See terminfo(5) for further details.]
75 The ncurses library permits manipulation of data structures, called
77 windows, which can be thought of as two-dimensional arrays of charac‐
78 ters representing all or part of a CRT screen. A default window called
79 stdscr, which is the size of the terminal screen, is supplied. Others
80 may be created with newwin.
81 Note that curses does not handle overlapping windows, that's done by
83 the panel(3X) library. This means that you can either use stdscr or
84 divide the screen into tiled windows and not using stdscr at all. Mix‐
85 ing the two will result in unpredictable, and undesired, effects.
86 Windows are referred to by variables declared as WINDOW *. These data
88 structures are manipulated with routines described here and elsewhere
89 in the ncurses manual pages. Among those, the most basic routines are
90 move and addch. More general versions of these routines are included
91 with names beginning with w, allowing the user to specify a window.
92 The routines not beginning with w affect stdscr.
93 After using routines to manipulate a window, refresh is called, telling
95 curses to make the user's CRT screen look like stdscr. The characters
96 in a window are actually of type chtype, (character and attribute data)
97 so that other information about the character may also be stored with
98 each character.
99 Special windows called pads may also be manipulated. These are windows
101 which are not constrained to the size of the screen and whose contents
102 need not be completely displayed. See curs_pad(3X) for more informa‐
103 tion.
104 In addition to drawing characters on the screen, video attributes and
106 colors may be supported, causing the characters to show up in such
107 modes as underlined, in reverse video, or in color on terminals that
108 support such display enhancements. Line drawing characters may be
109 specified to be output. On input, curses is also able to translate
110 arrow and function keys that transmit escape sequences into single val‐
111 ues. The video attributes, line drawing characters, and input values
112 use names, defined in <curses.h>, such as A_REVERSE, ACS_HLINE, and
113 KEY_LEFT.
114 If the environment variables LINES and COLUMNS are set, or if the pro‐
116 gram is executing in a window environment, line and column information
117 in the environment will override information read by terminfo. This
118 would affect a program running in an AT&T 630 layer, for example, where
119 the size of a screen is changeable (see ENVIRONMENT).
120 If the environment variable TERMINFO is defined, any program using
122 curses checks for a local terminal definition before checking in the
123 standard place. For example, if TERM is set to att4424, then the com‐
124 piled terminal definition is found in
125 /usr/share/terminfo/a/att4424.
127 (The a is copied from the first letter of att4424 to avoid creation of
129 huge directories.) However, if TERMINFO is set to $HOME/myterms,
130 curses first checks
131 $HOME/myterms/a/att4424,
133 and if that fails, it then checks
135 /usr/share/terminfo/a/att4424.
137 This is useful for developing experimental definitions or when write
139 permission in /usr/share/terminfo is not available.
140 The integer variables LINES and COLS are defined in <curses.h> and will
142 be filled in by initscr with the size of the screen. The constants
143 TRUE and FALSE have the values 1 and 0, respectively.
144 The curses routines also define the WINDOW * variable curscr which is
146 used for certain low-level operations like clearing and redrawing a
147 screen containing garbage. The curscr can be used in only a few rou‐
148 tines.
149 Routine and Argument Names
151 Many curses routines have two or more versions. The routines prefixed
152 with w require a window argument. The routines prefixed with p require
153 a pad argument. Those without a prefix generally use stdscr.
154 The routines prefixed with mv require a y and x coordinate to move to
156 before performing the appropriate action. The mv routines imply a call
157 to move before the call to the other routine. The coordinate y always
158 refers to the row (of the window), and x always refers to the column.
159 The upper left-hand corner is always (0,0), not (1,1).
160 The routines prefixed with mvw take both a window argument and x and y
162 coordinates. The window argument is always specified before the coor‐
163 dinates.
164 In each case, win is the window affected, and pad is the pad affected;
166 win and pad are always pointers to type WINDOW.
167 Option setting routines require a Boolean flag bf with the value TRUE
169 or FALSE; bf is always of type bool. Most of the data types used in
170 the library routines, such as WINDOW, SCREEN, bool, and chtype are
171 defined in <curses.h>. Types used for the terminfo routines such as
172 TERMINAL are defined in <term.h>.
173 This manual page describes functions which may appear in any configura‐
175 tion of the library. There are two common configurations of the
176 library:
177 ncurses
179 the "normal" library, which handles 8-bit characters. The
180 normal (8-bit) library stores characters combined with
181 attributes in chtype data.
182 Attributes alone (no corresponding character) may be stored
184 in chtype or the equivalent attr_t data. In either case,
185 the data is stored in something like an integer.
186 Each cell (row and column) in a WINDOW is stored as a
188 chtype.
189 ncursesw
191 the so-called "wide" library, which handles multibyte char‐
192 acters (see the section on ALTERNATE CONFIGURATIONS). The
193 "wide" library includes all of the calls from the "normal"
194 library. It adds about one third more calls using data
195 types which store multibyte characters:
196 cchar_t
198 corresponds to chtype. However it is a structure,
199 because more data is stored than can fit into an inte‐
200 ger. The characters are large enough to require a
201 full integer value - and there may be more than one
202 character per cell. The video attributes and color
203 are stored in separate fields of the structure.
204 Each cell (row and column) in a WINDOW is stored as a
206 cchar_t.
207 wchar_t
209 stores a "wide" character. Like chtype, this may be
210 an integer.
211 wint_t
213 stores a wchar_t or WEOF - not the same, though both
214 may have the same size.
215 The "wide" library provides new functions which are analo‐
217 gous to functions in the "normal" library. There is a nam‐
218 ing convention which relates many of the normal/wide vari‐
219 ants: a "_w" is inserted into the name. For example, wad‐
220 dch becomes wadd_wch.
221 Routine Name Index
223 The following table lists each curses routine and the name of the man‐
224 ual page on which it is described. Routines flagged with `*' are
225 ncurses-specific, not described by XPG4 or present in SVr4.
226 curses Routine Name Manual Page Name
228 ────────────────────────────────────────────
229 COLOR_PAIR curs_color(3X)
230 PAIR_NUMBER curs_attr(3X)
231 _nc_free_and_exit curs_memleaks(3X)*
232 _nc_freeall curs_memleaks(3X)*
233 _nc_tracebits curs_trace(3X)*
234 _traceattr curs_trace(3X)*
235 _traceattr2 curs_trace(3X)*
236 _tracechar curs_trace(3X)*
237 _tracechtype curs_trace(3X)*
238 _tracechtype2 curs_trace(3X)*
239 _tracedump curs_trace(3X)*
240 _tracef curs_trace(3X)*
241 _tracemouse curs_trace(3X)*
242 add_wch curs_add_wch(3X)
243 add_wchnstr curs_add_wchstr(3X)
244 add_wchstr curs_add_wchstr(3X)
245 addch curs_addch(3X)
246 addchnstr curs_addchstr(3X)
247 addchstr curs_addchstr(3X)
248 addnstr curs_addstr(3X)
249 addnwstr curs_addwstr(3X)
250 addstr curs_addstr(3X)
251 addwstr curs_addwstr(3X)
252 assume_default_colors default_colors(3X)*
253 attr_get curs_attr(3X)
254 attr_off curs_attr(3X)
255 attr_on curs_attr(3X)
256 attr_set curs_attr(3X)
257 attroff curs_attr(3X)
258 attron curs_attr(3X)
259 attrset curs_attr(3X)
260 baudrate curs_termattrs(3X)
261 beep curs_beep(3X)
262 bkgd curs_bkgd(3X)
263 bkgdset curs_bkgd(3X)
264 bkgrnd curs_bkgrnd(3X)
265 bkgrndset curs_bkgrnd(3X)
266 border curs_border(3X)
268 border_set curs_border_set(3X)
269 box curs_border(3X)
270 box_set curs_border_set(3X)
271 can_change_color curs_color(3X)
272 cbreak curs_inopts(3X)
273 chgat curs_attr(3X)
274 clear curs_clear(3X)
275 clearok curs_outopts(3X)
276 clrtobot curs_clear(3X)
277 clrtoeol curs_clear(3X)
278 color_content curs_color(3X)
279 color_set curs_attr(3X)
280 copywin curs_overlay(3X)
281 curs_set curs_kernel(3X)
282 curses_version curs_extend(3X)*
283 def_prog_mode curs_kernel(3X)
284 def_shell_mode curs_kernel(3X)
285 define_key define_key(3X)*
286 del_curterm curs_terminfo(3X)
287 delay_output curs_util(3X)
288 delch curs_delch(3X)
289 deleteln curs_deleteln(3X)
290 delscreen curs_initscr(3X)
291 delwin curs_window(3X)
292 derwin curs_window(3X)
293 doupdate curs_refresh(3X)
294 dupwin curs_window(3X)
295 echo curs_inopts(3X)
296 echo_wchar curs_add_wch(3X)
297 echochar curs_addch(3X)
298 endwin curs_initscr(3X)
299 erase curs_clear(3X)
300 erasechar curs_termattrs(3X)
301 erasewchar curs_termattrs(3X)
302 filter curs_util(3X)
303 flash curs_beep(3X)
304 flushinp curs_util(3X)
305 get_wch curs_get_wch(3X)
306 get_wstr curs_get_wstr(3X)
307 getattrs curs_attr(3X)
308 getbegx curs_legacy(3X)*
309 getbegy curs_legacy(3X)*
310 getbegyx curs_getyx(3X)
311 getbkgd curs_bkgd(3X)
312 getbkgrnd curs_bkgrnd(3X)
313 getcchar curs_getcchar(3X)
314 getch curs_getch(3X)
315 getcurx curs_legacy(3X)*
316 getcury curs_legacy(3X)*
317 getmaxx curs_legacy(3X)*
318 getmaxy curs_legacy(3X)*
319 getmaxyx curs_getyx(3X)
320 getmouse curs_mouse(3X)*
321 getn_wstr curs_get_wstr(3X)
322 getnstr curs_getstr(3X)
323 getparx curs_legacy(3X)*
324 getpary curs_legacy(3X)*
325 getparyx curs_getyx(3X)
326 getstr curs_getstr(3X)
327 getsyx curs_kernel(3X)
328 getwin curs_util(3X)
329 getyx curs_getyx(3X)
330 halfdelay curs_inopts(3X)
331 has_colors curs_color(3X)
332 has_ic curs_termattrs(3X)
333 has_il curs_termattrs(3X)
335 has_key curs_getch(3X)*
336 hline curs_border(3X)
337 hline_set curs_border_set(3X)
338 idcok curs_outopts(3X)
339 idlok curs_outopts(3X)
340 immedok curs_outopts(3X)
341 in_wch curs_in_wch(3X)
342 in_wchnstr curs_in_wchstr(3X)
343 in_wchstr curs_in_wchstr(3X)
344 inch curs_inch(3X)
345 inchnstr curs_inchstr(3X)
346 inchstr curs_inchstr(3X)
347 init_color curs_color(3X)
348 init_pair curs_color(3X)
349 initscr curs_initscr(3X)
350 innstr curs_instr(3X)
351 innwstr curs_inwstr(3X)
352 ins_nwstr curs_ins_wstr(3X)
353 ins_wch curs_ins_wch(3X)
354 ins_wstr curs_ins_wstr(3X)
355 insch curs_insch(3X)
356 insdelln curs_deleteln(3X)
357 insertln curs_deleteln(3X)
358 insnstr curs_insstr(3X)
359 insstr curs_insstr(3X)
360 instr curs_instr(3X)
361 intrflush curs_inopts(3X)
362 inwstr curs_inwstr(3X)
363 is_cleared curs_opaque(3X)*
364 is_idcok curs_opaque(3X)*
365 is_idlok curs_opaque(3X)*
366 is_immedok curs_opaque(3X)*
367 is_keypad curs_opaque(3X)*
368 is_leaveok curs_opaque(3X)*
369 is_linetouched curs_touch(3X)
370 is_nodelay curs_opaque(3X)*
371 is_notimeout curs_opaque(3X)*
372 is_scrollok curs_opaque(3X)*
373 is_syncok curs_opaque(3X)*
374 is_term_resized resizeterm(3X)*
375 is_wintouched curs_touch(3X)
376 isendwin curs_initscr(3X)
377 key_defined key_defined(3X)*
378 key_name curs_util(3X)
379 keybound keybound(3X)*
380 keyname curs_util(3X)
381 keyok keyok(3X)*
382 keypad curs_inopts(3X)
383 killchar curs_termattrs(3X)
384 killwchar curs_termattrs(3X)
385 leaveok curs_outopts(3X)
386 longname curs_termattrs(3X)
387 mcprint curs_print(3X)*
388 meta curs_inopts(3X)
389 mouse_trafo curs_mouse(3X)*
390 mouseinterval curs_mouse(3X)*
391 mousemask curs_mouse(3X)*
392 move curs_move(3X)
393 mvadd_wch curs_add_wch(3X)
394 mvadd_wchnstr curs_add_wchstr(3X)
395 mvadd_wchstr curs_add_wchstr(3X)
396 mvaddch curs_addch(3X)
397 mvaddchnstr curs_addchstr(3X)
398 mvaddchstr curs_addchstr(3X)
399 mvaddnstr curs_addstr(3X)
400 mvaddnwstr curs_addwstr(3X)
402 mvaddstr curs_addstr(3X)
403 mvaddwstr curs_addwstr(3X)
404 mvchgat curs_attr(3X)
405 mvcur curs_terminfo(3X)
406 mvdelch curs_delch(3X)
407 mvderwin curs_window(3X)
408 mvget_wch curs_get_wch(3X)
409 mvget_wstr curs_get_wstr(3X)
410 mvgetch curs_getch(3X)
411 mvgetn_wstr curs_get_wstr(3X)
412 mvgetnstr curs_getstr(3X)
413 mvgetstr curs_getstr(3X)
414 mvhline curs_border(3X)
415 mvhline_set curs_border_set(3X)
416 mvin_wch curs_in_wch(3X)
417 mvin_wchnstr curs_in_wchstr(3X)
418 mvin_wchstr curs_in_wchstr(3X)
419 mvinch curs_inch(3X)
420 mvinchnstr curs_inchstr(3X)
421 mvinchstr curs_inchstr(3X)
422 mvinnstr curs_instr(3X)
423 mvinnwstr curs_inwstr(3X)
424 mvins_nwstr curs_ins_wstr(3X)
425 mvins_wch curs_ins_wch(3X)
426 mvins_wstr curs_ins_wstr(3X)
427 mvinsch curs_insch(3X)
428 mvinsnstr curs_insstr(3X)
429 mvinsstr curs_insstr(3X)
430 mvinstr curs_instr(3X)
431 mvinwstr curs_inwstr(3X)
432 mvprintw curs_printw(3X)
433 mvscanw curs_scanw(3X)
434 mvvline curs_border(3X)
435 mvvline_set curs_border_set(3X)
436 mvwadd_wch curs_add_wch(3X)
437 mvwadd_wchnstr curs_add_wchstr(3X)
438 mvwadd_wchstr curs_add_wchstr(3X)
439 mvwaddch curs_addch(3X)
440 mvwaddchnstr curs_addchstr(3X)
441 mvwaddchstr curs_addchstr(3X)
442 mvwaddnstr curs_addstr(3X)
443 mvwaddnwstr curs_addwstr(3X)
444 mvwaddstr curs_addstr(3X)
445 mvwaddwstr curs_addwstr(3X)
446 mvwchgat curs_attr(3X)
447 mvwdelch curs_delch(3X)
448 mvwget_wch curs_get_wch(3X)
449 mvwget_wstr curs_get_wstr(3X)
450 mvwgetch curs_getch(3X)
451 mvwgetn_wstr curs_get_wstr(3X)
452 mvwgetnstr curs_getstr(3X)
453 mvwgetstr curs_getstr(3X)
454 mvwhline curs_border(3X)
455 mvwhline_set curs_border_set(3X)
456 mvwin curs_window(3X)
457 mvwin_wch curs_in_wch(3X)
458 mvwin_wchnstr curs_in_wchstr(3X)
459 mvwin_wchstr curs_in_wchstr(3X)
460 mvwinch curs_inch(3X)
461 mvwinchnstr curs_inchstr(3X)
462 mvwinchstr curs_inchstr(3X)
463 mvwinnstr curs_instr(3X)
464 mvwinnwstr curs_inwstr(3X)
465 mvwins_nwstr curs_ins_wstr(3X)
466 mvwins_wch curs_ins_wch(3X)
467 mvwins_wstr curs_ins_wstr(3X)
469 mvwinsch curs_insch(3X)
470 mvwinsnstr curs_insstr(3X)
471 mvwinsstr curs_insstr(3X)
472 mvwinstr curs_instr(3X)
473 mvwinwstr curs_inwstr(3X)
474 mvwprintw curs_printw(3X)
475 mvwscanw curs_scanw(3X)
476 mvwvline curs_border(3X)
477 mvwvline_set curs_border_set(3X)
478 napms curs_kernel(3X)
479 newpad curs_pad(3X)
480 newterm curs_initscr(3X)
481 newwin curs_window(3X)
482 nl curs_outopts(3X)
483 nocbreak curs_inopts(3X)
484 nodelay curs_inopts(3X)
485 noecho curs_inopts(3X)
486 nofilter curs_util(3X)*
487 nonl curs_outopts(3X)
488 noqiflush curs_inopts(3X)
489 noraw curs_inopts(3X)
490 notimeout curs_inopts(3X)
491 overlay curs_overlay(3X)
492 overwrite curs_overlay(3X)
493 pair_content curs_color(3X)
494 pechochar curs_pad(3X)
495 pnoutrefresh curs_pad(3X)
496 prefresh curs_pad(3X)
497 printw curs_printw(3X)
498 putp curs_terminfo(3X)
499 putwin curs_util(3X)
500 qiflush curs_inopts(3X)
501 raw curs_inopts(3X)
502 redrawwin curs_refresh(3X)
503 refresh curs_refresh(3X)
504 reset_prog_mode curs_kernel(3X)
505 reset_shell_mode curs_kernel(3X)
506 resetty curs_kernel(3X)
507 resizeterm resizeterm(3X)*
508 restartterm curs_terminfo(3X)
509 ripoffline curs_kernel(3X)
510 savetty curs_kernel(3X)
511 scanw curs_scanw(3X)
512 scr_dump curs_scr_dump(3X)
513 scr_init curs_scr_dump(3X)
514 scr_restore curs_scr_dump(3X)
515 scr_set curs_scr_dump(3X)
516 scrl curs_scroll(3X)
517 scroll curs_scroll(3X)
518 scrollok curs_outopts(3X)
519 set_curterm curs_terminfo(3X)
520 set_term curs_initscr(3X)
521 setcchar curs_getcchar(3X)
522 setscrreg curs_outopts(3X)
523 setsyx curs_kernel(3X)
524 setterm curs_terminfo(3X)
525 setupterm curs_terminfo(3X)
526 slk_attr curs_slk(3X)*
527 slk_attr_off curs_slk(3X)
528 slk_attr_on curs_slk(3X)
529 slk_attr_set curs_slk(3X)
530 slk_attroff curs_slk(3X)
531 slk_attron curs_slk(3X)
532 slk_attrset curs_slk(3X)
533 slk_clear curs_slk(3X)
534 slk_color curs_slk(3X)
536 slk_init curs_slk(3X)
537 slk_label curs_slk(3X)
538 slk_noutrefresh curs_slk(3X)
539 slk_refresh curs_slk(3X)
540 slk_restore curs_slk(3X)
541 slk_set curs_slk(3X)
542 slk_touch curs_slk(3X)
543 standend curs_attr(3X)
544 standout curs_attr(3X)
545 start_color curs_color(3X)
546 subpad curs_pad(3X)
547 subwin curs_window(3X)
548 syncok curs_window(3X)
549 term_attrs curs_termattrs(3X)
550 termattrs curs_termattrs(3X)
551 termname curs_termattrs(3X)
552 tgetent curs_termcap(3X)
553 tgetflag curs_termcap(3X)
554 tgetnum curs_termcap(3X)
555 tgetstr curs_termcap(3X)
556 tgoto curs_termcap(3X)
557 tigetflag curs_terminfo(3X)
558 tigetnum curs_terminfo(3X)
559 tigetstr curs_terminfo(3X)
560 timeout curs_inopts(3X)
561 touchline curs_touch(3X)
562 touchwin curs_touch(3X)
563 tparm curs_terminfo(3X)
564 tputs curs_termcap(3X)
565 tputs curs_terminfo(3X)
566 trace curs_trace(3X)*
567 typeahead curs_inopts(3X)
568 unctrl curs_util(3X)
569 unget_wch curs_get_wch(3X)
570 ungetch curs_getch(3X)
571 ungetmouse curs_mouse(3X)*
572 untouchwin curs_touch(3X)
573 use_default_colors default_colors(3X)*
574 use_env curs_util(3X)
575 use_extended_names curs_extend(3X)*
576 use_legacy_coding legacy_coding(3X)*
577 use_tioctl curs_util(3X)
578 vid_attr curs_terminfo(3X)
579 vid_puts curs_terminfo(3X)
580 vidattr curs_terminfo(3X)
581 vidputs curs_terminfo(3X)
582 vline curs_border(3X)
583 vline_set curs_border_set(3X)
584 vw_printw curs_printw(3X)
585 vw_scanw curs_scanw(3X)
586 vwprintw curs_printw(3X)
587 vwscanw curs_scanw(3X)
588 wadd_wch curs_add_wch(3X)
589 wadd_wchnstr curs_add_wchstr(3X)
590 wadd_wchstr curs_add_wchstr(3X)
591 waddch curs_addch(3X)
592 waddchnstr curs_addchstr(3X)
593 waddchstr curs_addchstr(3X)
594 waddnstr curs_addstr(3X)
595 waddnwstr curs_addwstr(3X)
596 waddstr curs_addstr(3X)
597 waddwstr curs_addwstr(3X)
598 wattr_get curs_attr(3X)
599 wattr_off curs_attr(3X)
600 wattr_on curs_attr(3X)
601 wattr_set curs_attr(3X)
603 wattroff curs_attr(3X)
604 wattron curs_attr(3X)
605 wattrset curs_attr(3X)
606 wbkgd curs_bkgd(3X)
607 wbkgdset curs_bkgd(3X)
608 wbkgrnd curs_bkgrnd(3X)
609 wbkgrndset curs_bkgrnd(3X)
610 wborder curs_border(3X)
611 wborder_set curs_border_set(3X)
612 wchgat curs_attr(3X)
613 wclear curs_clear(3X)
614 wclrtobot curs_clear(3X)
615 wclrtoeol curs_clear(3X)
616 wcolor_set curs_attr(3X)
617 wcursyncup curs_window(3X)
618 wdelch curs_delch(3X)
619 wdeleteln curs_deleteln(3X)
620 wecho_wchar curs_add_wch(3X)
621 wechochar curs_addch(3X)
622 wenclose curs_mouse(3X)*
623 werase curs_clear(3X)
624 wget_wch curs_get_wch(3X)
625 wget_wstr curs_get_wstr(3X)
626 wgetbkgrnd curs_bkgrnd(3X)
627 wgetch curs_getch(3X)
628 wgetn_wstr curs_get_wstr(3X)
629 wgetnstr curs_getstr(3X)
630 wgetstr curs_getstr(3X)
631 whline curs_border(3X)
632 whline_set curs_border_set(3X)
633 win_wch curs_in_wch(3X)
634 win_wchnstr curs_in_wchstr(3X)
635 win_wchstr curs_in_wchstr(3X)
636 winch curs_inch(3X)
637 winchnstr curs_inchstr(3X)
638 winchstr curs_inchstr(3X)
639 winnstr curs_instr(3X)
640 winnwstr curs_inwstr(3X)
641 wins_nwstr curs_ins_wstr(3X)
642 wins_wch curs_ins_wch(3X)
643 wins_wstr curs_ins_wstr(3X)
644 winsch curs_insch(3X)
645 winsdelln curs_deleteln(3X)
646 winsertln curs_deleteln(3X)
647 winsnstr curs_insstr(3X)
648 winsstr curs_insstr(3X)
649 winstr curs_instr(3X)
650 winwstr curs_inwstr(3X)
651 wmouse_trafo curs_mouse(3X)*
652 wmove curs_move(3X)
653 wnoutrefresh curs_refresh(3X)
654 wprintw curs_printw(3X)
655 wredrawln curs_refresh(3X)
656 wrefresh curs_refresh(3X)
657 wresize wresize(3X)*
658 wscanw curs_scanw(3X)
659 wscrl curs_scroll(3X)
660 wsetscrreg curs_outopts(3X)
661 wstandend curs_attr(3X)
662 wstandout curs_attr(3X)
663 wsyncdown curs_window(3X)
664 wsyncup curs_window(3X)
665 wtimeout curs_inopts(3X)
666 wtouchln curs_touch(3X)
667 wunctrl curs_util(3X)
668 wvline curs_border(3X)
670 wvline_set curs_border_set(3X)
671
673 Routines that return an integer return ERR upon failure and an integer
674 value other than ERR upon successful completion, unless otherwise noted
675 in the routine descriptions.
676 As a general rule, routines check for null pointers passed as parame‐
678 ters, and handle this as an error.
679 All macros return the value of the w version, except setscrreg,
681 wsetscrreg, getyx, getbegyx, and getmaxyx. The return values of
682 setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined
683 (i.e., these should not be used as the right-hand side of assignment
684 statements).
685 Routines that return pointers return NULL on error.
687
689 The following environment symbols are useful for customizing the run‐
690 time behavior of the ncurses library. The most important ones have
691 been already discussed in detail.
692 BAUDRATE
694 The debugging library checks this environment variable when the
695 application has redirected output to a file. The variable's
696 numeric value is used for the baudrate. If no value is found,
697 ncurses uses 9600. This allows testers to construct repeatable
698 test-cases that take into account costs that depend on baudrate.
699 CC When set, change occurrences of the command_character (i.e., the
701 cmdch capability) of the loaded terminfo entries to the value of
702 this variable. Very few terminfo entries provide this feature.
703 Because this name is also used in development environments to rep‐
705 resent the C compiler's name, ncurses ignores it if it does not
706 happen to be a single character.
707 COLUMNS
709 Specify the width of the screen in characters. Applications run‐
710 ning in a windowing environment usually are able to obtain the
711 width of the window in which they are executing. If neither the
712 COLUMNS value nor the terminal's screen size is available, ncurses
713 uses the size which may be specified in the terminfo database
714 (i.e., the cols capability).
715 It is important that your application use a correct size for the
717 screen. This is not always possible because your application may
718 be running on a host which does not honor NAWS (Negotiations About
719 Window Size), or because you are temporarily running as another
720 user. However, setting COLUMNS and/or LINES overrides the
721 library's use of the screen size obtained from the operating sys‐
722 tem.
723 Either COLUMNS or LINES symbols may be specified independently.
725 This is mainly useful to circumvent legacy misfeatures of terminal
726 descriptions, e.g., xterm which commonly specifies a 65 line
727 screen. For best results, lines and cols should not be specified
728 in a terminal description for terminals which are run as emula‐
729 tions.
730 Use the use_env function to disable all use of external environ‐
732 ment (but not including system calls) to determine the screen
733 size. Use the use_tioctl function to update COLUMNS or LINES to
734 match the screen size obtained from system calls or the terminal
735 database.
736 ESCDELAY
738 Specifies the total time, in milliseconds, for which ncurses will
739 await a character sequence, e.g., a function key. The default
740 value, 1000 milliseconds, is enough for most uses. However, it is
741 made a variable to accommodate unusual applications.
742 The most common instance where you may wish to change this value
744 is to work with slow hosts, e.g., running on a network. If the
745 host cannot read characters rapidly enough, it will have the same
746 effect as if the terminal did not send characters rapidly enough.
747 The library will still see a timeout.
748 Note that xterm mouse events are built up from character sequences
750 received from the xterm. If your application makes heavy use of
751 multiple-clicking, you may wish to lengthen this default value
752 because the timeout applies to the composed multi-click event as
753 well as the individual clicks.
754 In addition to the environment variable, this implementation pro‐
756 vides a global variable with the same name. Portable applications
757 should not rely upon the presence of ESCDELAY in either form, but
758 setting the environment variable rather than the global variable
759 does not create problems when compiling an application.
760 HOME Tells ncurses where your home directory is. That is where it may
762 read and write auxiliary terminal descriptions:
763 $HOME/.termcap
765 $HOME/.terminfo
766 LINES
768 Like COLUMNS, specify the height of the screen in characters. See
769 COLUMNS for a detailed description.
770 MOUSE_BUTTONS_123
772 This applies only to the OS/2 EMX port. It specifies the order of
773 buttons on the mouse. OS/2 numbers a 3-button mouse inconsis‐
774 tently from other platforms:
775 1 = left
777 2 = right
778 3 = middle.
779 This variable lets you customize the mouse. The variable must be
781 three numeric digits 1-3 in any order, e.g., 123 or 321. If it is
782 not specified, ncurses uses 132.
783 NCURSES_ASSUMED_COLORS
785 Override the compiled-in assumption that the terminal's default
786 colors are white-on-black (see default_colors(3X)). You may set
787 the foreground and background color values with this environment
788 variable by proving a 2-element list: foreground,background. For
789 example, to tell ncurses to not assume anything about the colors,
790 set this to "-1,-1". To make it green-on-black, set it to "2,0".
791 Any positive value from zero to the terminfo max_colors value is
792 allowed.
793 NCURSES_GPM_TERMS
795 This applies only to ncurses configured to use the GPM interface.
796 If present, the environment variable is a list of one or more ter‐
798 minal names against which the TERM environment variable is
799 matched. Setting it to an empty value disables the GPM interface;
800 using the built-in support for xterm, etc.
801 If the environment variable is absent, ncurses will attempt to
803 open GPM if TERM contains "linux".
804 NCURSES_NO_HARD_TABS
806 Ncurses may use tabs as part of the cursor movement optimization.
807 In some cases, your terminal driver may not handle these properly.
808 Set this environment variable to disable the feature. You can
809 also adjust your stty settings to avoid the problem.
810 NCURSES_NO_MAGIC_COOKIES
812 Some terminals use a magic-cookie feature which requires special
813 handling to make highlighting and other video attributes display
814 properly. You can suppress the highlighting entirely for these
815 terminals by setting this environment variable.
816 NCURSES_NO_PADDING
818 Most of the terminal descriptions in the terminfo database are
819 written for real "hardware" terminals. Many people use terminal
820 emulators which run in a windowing environment and use curses-
821 based applications. Terminal emulators can duplicate all of the
822 important aspects of a hardware terminal, but they do not have the
823 same limitations. The chief limitation of a hardware terminal
824 from the standpoint of your application is the management of
825 dataflow, i.e., timing. Unless a hardware terminal is interfaced
826 into a terminal concentrator (which does flow control), it (or
827 your application) must manage dataflow, preventing overruns. The
828 cheapest solution (no hardware cost) is for your program to do
829 this by pausing after operations that the terminal does slowly,
830 such as clearing the display.
831 As a result, many terminal descriptions (including the vt100) have
833 delay times embedded. You may wish to use these descriptions, but
834 not want to pay the performance penalty.
835 Set the NCURSES_NO_PADDING environment variable to disable all but
837 mandatory padding. Mandatory padding is used as a part of special
838 control sequences such as flash.
839 NCURSES_NO_SETBUF
841 This setting is obsolete. Before changes
842 · started with 5.9 patch 20120825 and
844 · continued though 5.9 patch 20130126
846 ncurses enabled buffered output during terminal initialization.
848 This was done (as in SVr4 curses) for performance reasons. For
849 testing purposes, both of ncurses and certain applications, this
850 feature was made optional. Setting the NCURSES_NO_SETBUF variable
851 disabled output buffering, leaving the output in the original
852 (usually line buffered) mode.
853 In the current implementation, ncurses performs its own buffering
855 and does not require this workaround. It does not modify the
856 buffering of the standard output.
857 The reason for the change was to make the behavior for interrupts
859 and other signals more robust. One drawback is that certain non‐
860 conventional programs would mix ordinary stdio calls with ncurses
861 calls and (usually) work. This is no longer possible since
862 ncurses is not using the buffered standard output but its own out‐
863 put (to the same file descriptor). As a special case, the low-
864 level calls such as putp still use the standard output. But high-
865 level curses calls do not.
866 NCURSES_NO_UTF8_ACS
868 During initialization, the ncurses library checks for special
869 cases where VT100 line-drawing (and the corresponding alternate
870 character set capabilities) described in the terminfo are known to
871 be missing. Specifically, when running in a UTF-8 locale, the
872 Linux console emulator and the GNU screen program ignore these.
873 Ncurses checks the TERM environment variable for these. For other
874 special cases, you should set this environment variable. Doing
875 this tells ncurses to use Unicode values which correspond to the
876 VT100 line-drawing glyphs. That works for the special cases
877 cited, and is likely to work for terminal emulators.
878 When setting this variable, you should set it to a nonzero value.
880 Setting it to zero (or to a nonnumber) disables the special check
881 for "linux" and "screen".
882 As an alternative to the environment variable, ncurses checks for
884 an extended terminfo capability U8. This is a numeric capability
885 which can be compiled using tic -x. For example
886 # linux console, if patched to provide working
888 # VT100 shift-in/shift-out, with corresponding font.
889 linux-vt100|linux console with VT100 line-graphics,
890 U8#0, use=linux,
891 # uxterm with vt100Graphics resource set to false
893 xterm-utf8|xterm relying on UTF-8 line-graphics,
894 U8#1, use=xterm,
895 The name "U8" is chosen to be two characters, to permit it to be
897 used by applications that use ncurses' termcap interface.
898 NCURSES_TRACE
900 During initialization, the ncurses debugging library checks the
901 NCURSES_TRACE environment variable. If it is defined, to a
902 numeric value, ncurses calls the trace function, using that value
903 as the argument.
904 The argument values, which are defined in curses.h, provide sev‐
906 eral types of information. When running with traces enabled, your
907 application will write the file trace to the current directory.
908 TERM Denotes your terminal type. Each terminal type is distinct,
910 though many are similar.
911 TERMCAP
913 If the ncurses library has been configured with termcap support,
914 ncurses will check for a terminal's description in termcap form if
915 it is not available in the terminfo database.
916 The TERMCAP environment variable contains either a terminal
918 description (with newlines stripped out), or a file name telling
919 where the information denoted by the TERM environment variable
920 exists. In either case, setting it directs ncurses to ignore the
921 usual place for this information, e.g., /etc/termcap.
922 TERMINFO
924 Overrides the directory in which ncurses searches for your termi‐
925 nal description. This is the simplest, but not the only way to
926 change the list of directories. The complete list of directories
927 in order follows:
928 · the last directory to which ncurses wrote, if any, is searched
930 first
931 · the directory specified by the TERMINFO environment variable
933 · $HOME/.terminfo
935 · directories listed in the TERMINFO_DIRS environment variable
937 · one or more directories whose names are configured and com‐
939 piled into the ncurses library, i.e.,
940 · no default value (corresponding to the TERMINFO_DIRS vari‐
942 able)
943 · /usr/share/terminfo (corresponding to the TERMINFO vari‐
945 able)
946 TERMINFO_DIRS
948 Specifies a list of directories to search for terminal descrip‐
949 tions. The list is separated by colons (i.e., ":") on Unix, semi‐
950 colons on OS/2 EMX.
951 All of the terminal descriptions are in terminfo form. Normally
953 these are stored in a directory tree, using subdirectories named
954 by the first letter of the terminal names therein.
955 If ncurses is built with a hashed database, then each entry in
957 this list can also be the path of the corresponding database file.
958 If ncurses is built with a support for reading termcap files
960 directly, then an entry in this list may be the path of a termcap
961 file.
962 TERMPATH
964 If TERMCAP does not hold a file name then ncurses checks the
965 TERMPATH environment variable. This is a list of filenames sepa‐
966 rated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2
967 EMX.
968 If the TERMPATH environment variable is not set, ncurses looks in
970 the files /etc/termcap, /usr/share/misc/termcap and $HOME/.term‐
971 cap, in that order.
972 The library may be configured to disregard the following variables when
974 the current user is the superuser (root), or if the application uses
975 setuid or setgid permissions:
976 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
978
980 Several different configurations are possible, depending on the config‐
981 ure script options used when building ncurses. There are a few main
982 options whose effects are visible to the applications developer using
983 ncurses:
984 --disable-overwrite
986 The standard include for ncurses is as noted in SYNOPSIS:
987 #include <curses.h>
989 This option is used to avoid filename conflicts when ncurses is
991 not the main implementation of curses of the computer. If ncurses
992 is installed disabling overwrite, it puts its headers in a subdi‐
993 rectory, e.g.,
994 #include <ncurses/curses.h>
996 It also omits a symbolic link which would allow you to use
998 -lcurses to build executables.
999 --enable-widec
1001 The configure script renames the library and (if the --dis‐
1002 able-overwrite option is used) puts the header files in a differ‐
1003 ent subdirectory. All of the library names have a "w" appended to
1004 them, i.e., instead of
1005 -lncurses
1007 you link with
1009 -lncursesw
1011 You must also define _XOPEN_SOURCE_EXTENDED when compiling for the
1013 wide-character library to use the extended (wide-character) func‐
1014 tions. The curses.h file which is installed for the wide-charac‐
1015 ter library is designed to be compatible with the normal library's
1016 header. Only the size of the WINDOW structure differs, and very
1017 few applications require more than a pointer to WINDOWs. If the
1018 headers are installed allowing overwrite, the wide-character
1019 library's headers should be installed last, to allow applications
1020 to be built using either library from the same set of headers.
1021 --with-shared
1023 --with-normal
1025 --with-debug
1027 --with-profile
1029 The shared and normal (static) library names differ by their suf‐
1030 fixes, e.g., libncurses.so and libncurses.a. The debug and pro‐
1031 filing libraries add a "_g" and a "_p" to the root names respec‐
1032 tively, e.g., libncurses_g.a and libncurses_p.a.
1033 --with-trace
1035 The trace function normally resides in the debug library, but it
1036 is sometimes useful to configure this in the shared library. Con‐
1037 figure scripts should check for the function's existence rather
1038 than assuming it is always in the debug library.
1039
1041 /usr/share/tabset
1042 directory containing initialization files for the terminal capa‐
1043 bility database /usr/share/terminfo terminal capability database
1044
1046 terminfo(5) and related pages whose names begin "curs_" for detailed
1047 routine descriptions.
1048 curs_variables(3X)
1049
1051 The ncurses library can be compiled with an option (-DUSE_GETCAP) that
1052 falls back to the old-style /etc/termcap file if the terminal setup
1053 code cannot find a terminfo entry corresponding to TERM. Use of this
1054 feature is not recommended, as it essentially includes an entire term‐
1055 cap compiler in the ncurses startup code, at significant cost in core
1056 and startup cycles.
1057 The ncurses library includes facilities for capturing mouse events on
1059 certain terminals (including xterm). See the curs_mouse(3X) manual
1060 page for details.
1061 The ncurses library includes facilities for responding to window resiz‐
1063 ing events, e.g., when running in an xterm. See the resizeterm(3X) and
1064 wresize(3X) manual pages for details. In addition, the library may be
1065 configured with a SIGWINCH handler.
1066 The ncurses library extends the fixed set of function key capabilities
1068 of terminals by allowing the application designer to define additional
1069 key sequences at runtime. See the define_key(3X) key_defined(3X), and
1070 keyok(3X) manual pages for details.
1071 The ncurses library can exploit the capabilities of terminals which
1073 implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
1074 application to reset the terminal to its original foreground and back‐
1075 ground colors. From the users' perspective, the application is able to
1076 draw colored text on a background whose color is set independently,
1077 providing better control over color contrasts. See the default_col‐
1078 ors(3X) manual page for details.
1079 The ncurses library includes a function for directing application out‐
1081 put to a printer attached to the terminal device. See the
1082 curs_print(3X) manual page for details.
1083
1085 The ncurses library is intended to be BASE-level conformant with XSI
1086 Curses. The EXTENDED XSI Curses functionality (including color sup‐
1087 port) is supported.
1088 A small number of local differences (that is, individual differences
1090 between the XSI Curses and ncurses calls) are described in PORTABILITY
1091 sections of the library man pages.
1092 Unlike other implementations, this one checks parameters such as point‐
1094 ers to WINDOW structures to ensure they are not null. The main reason
1095 for providing this behavior is to guard against programmer error. The
1096 standard interface does not provide a way for the library to tell an
1097 application which of several possible errors were detected. Relying on
1098 this (or some other) extension will adversely affect the portability of
1099 curses applications.
1100 This implementation also contains several extensions:
1102 · The routine has_key is not part of XPG4, nor is it present in SVr4.
1104 See the curs_getch(3X) manual page for details.
1105 · The routine slk_attr is not part of XPG4, nor is it present in
1107 SVr4. See the curs_slk(3X) manual page for details.
1108 · The routines getmouse, mousemask, ungetmouse, mouseinterval, and
1110 wenclose relating to mouse interfacing are not part of XPG4, nor
1111 are they present in SVr4. See the curs_mouse(3X) manual page for
1112 details.
1113 · The routine mcprint was not present in any previous curses imple‐
1115 mentation. See the curs_print(3X) manual page for details.
1116 · The routine wresize is not part of XPG4, nor is it present in SVr4.
1118 See the wresize(3X) manual page for details.
1119 · The WINDOW structure's internal details can be hidden from applica‐
1121 tion programs. See curs_opaque(3X) for the discussion of is_scrol‐
1122 lok, etc.
1123 · This implementation can be configured to provide rudimentary sup‐
1125 port for multi-threaded applications. See curs_threads(3X) for
1126 details.
1127 · This implementation can also be configured to provide a set of
1129 functions which improve the ability to manage multiple screens.
1130 See curs_sp_funcs(3X) for details.
1131 In historic curses versions, delays embedded in the capabilities cr,
1133 ind, cub1, ff and tab activated corresponding delay bits in the UNIX
1134 tty driver. In this implementation, all padding is done by sending NUL
1135 bytes. This method is slightly more expensive, but narrows the inter‐
1136 face to the UNIX kernel significantly and increases the package's
1137 portability correspondingly.
1138
1140 The header file <curses.h> automatically includes the header files
1141 <stdio.h> and <unctrl.h>.
1142 If standard output from a ncurses program is re-directed to something
1144 which is not a tty, screen updates will be directed to standard error.
1145 This was an undocumented feature of AT&T System V Release 3 curses.
1146
1148 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses
1149 by Pavel Curtis.
1150 ncurses(3X)