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