2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: ncurses.3x,v 1.200 2024/02/24 20:03:50 tom Exp $
32 .TH ncurses 3X 2024-02-24 "ncurses 6.4" "Library calls"
52 character-cell terminal interface with optimized output
55 \fB#include <curses.h>
58 The \fI\%ncurses\fP library routines give the user a
59 terminal-independent method of updating character screens with
60 reasonable optimization.
61 This implementation is \*(``new curses\*('' (\fI\%ncurses\fP) and
62 is the approved replacement for
63 4.4BSD classic curses, which has been discontinued.
64 This describes \fI\%ncurses\fP
65 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
67 The \fI\%ncurses\fP library emulates the curses library of
68 System V Release 4 Unix (\*(``SVr4\*(''),
69 and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
70 XSI stands for X/Open System Interfaces Extension.
71 The \fI\%ncurses\fP library is freely redistributable in source form.
73 \fI\%ncurses\fP man pages employ several sections to clarify matters of
74 usage and interoperability with other \fIcurses\fP implementations.
76 \*(``NOTES\*('' describes matters and caveats of which any user of the
77 \fI\%ncurses\fP API should be aware,
78 such as limitations on the size of an underlying integral type or the
79 availability of a preprocessor macro exclusive of a function definition
80 (which prevents its address from being taken).
81 This section also describes implementation details that will be
82 significant to the programmer but which are not standardized.
84 \*(``EXTENSIONS\*('' presents \fI\%ncurses\fP innovations beyond the
85 X/Open Curses standard and/or the SVr4 \fIcurses\fP implementation.
86 They are termed \fIextensions\fP to indicate that they cannot be
87 implemented solely by using the library API, but require access to the
88 library's internal state.
90 \*(``PORTABILITY\*('' discusses matters
91 (beyond the exercise of extensions)
92 that should be considered when writing to a \fIcurses\fP standard,
93 or to multiple implementations.
95 \*(``HISTORY\*('' examines points of detail in \fI\%ncurses\fP and other
96 \fIcurses\fP implementations over the decades of their development,
97 particularly where precedent or inertia have frustrated better design
100 where such inertia has been overcome).
102 A program using these routines must be linked with the \fB\-lncurses\fP option,
103 or (if it has been generated) with the debugging library \fB\-lncurses_g\fP.
104 (Your system integrator may also have installed these libraries under
105 the names \fB\-lcurses\fP and \fB\-lcurses_g\fP.)
106 The ncurses_g library generates trace logs
107 (in a file called \*(``trace\*('' in the current directory)
108 that describe curses actions.
109 See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
111 The \fI\%ncurses\fP package supports: overall screen, window and pad
112 manipulation; output to windows and pads; reading terminal input; control over
113 terminal and \fBcurses\fP input and output options; environment query
114 routines; color manipulation; use of soft label keys; terminfo capabilities;
115 and access to low-level terminal-manipulation routines.
117 The library uses the locale which the calling program has initialized.
118 That is normally done with \fBsetlocale\fP(3):
122 \fBsetlocale(LC_ALL, "");\fP
126 If the locale is not initialized,
127 the library assumes that characters are printable as in ISO\-8859\-1,
128 to work with certain legacy programs.
129 You should initialize the locale and not rely on specific details of
130 the library when the locale has not been set up.
132 The function \fBinitscr\fP or \fBnewterm\fP
133 must be called to initialize the library
134 before any of the other routines that deal with windows
135 and screens are used.
136 The routine \fBendwin\fP(3X) must be called before exiting.
138 To get character-at-a-time input without echoing (most
139 interactive, screen oriented programs want this), the following
140 sequence should be used:
144 \fBinitscr(); cbreak(); noecho();\fP
148 Most programs would additionally use the sequence:
152 \fBintrflush(stdscr, FALSE);\fP
153 \fBkeypad(stdscr, TRUE);\fP
157 Before a \fBcurses\fP program is run, the tab stops of the terminal
158 should be set and its initialization strings, if defined, must be output.
159 This can be done by executing the \fB@TPUT@ init\fP command
160 after the shell environment variable \fITERM\fP has been exported.
161 (The BSD-style \fB\%@TSET@\fP(1) utility also performs this function.)
162 See subsection \*(``Tabs and Initialization\*('' of \fBterminfo\fP(5).
166 library abstracts the terminal screen by representing all or part of it
172 is a rectangular grid of character cells,
173 addressed by row and column coordinates
176 with the upper left corner as (0, 0).
177 A window called \fB\%stdscr\fP,
178 the same size as the terminal screen,
180 Create others with \fB\%newwin\fP(3X).
184 library does not manage overlapping windows.
185 (See \fBpanel\fP(3X) if you desire this.)
186 You can either use \fB\%stdscr\fP to manage one screen-filling window,
187 or tile the screen into non-overlapping windows and not use
188 \fB\%stdscr\fP at all.
189 Mixing the two approaches will result in unpredictable,
193 Functions permit manipulation of a window and the
195 identifying the cell within it at which the next output operation will
198 the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X):
199 these place the cursor and write a character to
203 window-addressing functions feature names prefixed
207 these allow the user to specify a pointer to a
209 Counterparts not thus prefixed
211 affect \fB\%stdscr\fP.
212 Because moving the cursor prior to another operation is so common,
214 generally also provides functions with a \*(``mv\*('' prefix as a
217 the library defines all of
223 When both prefixes are present,
224 the order of arguments is a
233 Updating the terminal screen with every
235 call can cause unpleasant flicker or inefficient use of the
236 communications channel to the device.
240 functions to accumulate a set of desired updates that make sense to
242 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
243 look like \fBstdscr\fP.
245 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
246 .\" does not mandate it in any way.
248 its output by computing a minimal number of operations to mutate the
249 screen from its state at the previous refresh to the new one.
250 Effective optimization demands accurate information about the terminal
252 the management of such information is the province of the
253 \fB\%terminfo\fP(3X) API,
254 a feature of every standard
258 Special windows called \fIpads\fP may also be manipulated.
259 These are windows that are not constrained to the size of the terminal
260 screen and whose contents need not be completely displayed.
261 See \fB\%curs_pad\fP(3X).
263 In addition to drawing characters on the screen,
264 rendering attributes and colors may be supported,
265 causing the characters to show up in such modes as underlined,
267 or in color on terminals that support such display enhancements.
268 See \fB\%curs_attr\fP(3X).
271 predefines constants for a small set of line-drawing and other graphics
272 corresponding to the DEC Alternate Character Set (ACS),
273 a feature of VT100 and other terminals.
275 \fB\%waddch\fP(3X) and
276 \fB\%wadd_wch\fP(3X).
279 is implemented using the operating system's terminal driver;
280 keystroke events are received not as scan codes but as byte sequences.
282 (alphanumeric and punctuation keys,
291 appears as a control character or a multibyte
292 .I "escape sequence."
294 translates these into unique
296 See \fB\%getch\fP(3X).
297 .SS "Effects of GUIs and Environment Variables"
298 The selection of an appropriate value of
300 in the process environment is essential to correct
305 A well-configured system selects a correct
308 \fB\%tset\fP(1) may assist with troubleshooting exotic situations.
310 If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
313 program is executing in a graphical windowing environment,
314 the information obtained thence overrides that obtained by
318 extension supports resizable terminals;
319 see \fB\%wresize\fP(3X).
321 If the environment variable \fI\%TERMINFO\fP is defined,
324 program checks first for a terminal type description in the location it
327 is useful for developing experimental type descriptions or when write
328 permission to \fI\*d\fP is not available.
330 See section \*(``ENVIRONMENT\*('' below.
331 .SS "Naming Conventions"
334 functions have two or more versions.
335 Those prefixed with \*(``w\*('' require a window argument.
336 Four functions prefixed with \*(``p\*('' require a pad argument.
337 Those without a prefix generally operate on \fB\%stdscr\fP.
339 In function synopses,
341 man pages apply the following names to parameters.
346 bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
347 win pointer to \fIWINDOW\fP
348 pad pointer to \fIWINDOW\fP that is a pad
350 .SS "Wide and Non-wide Character Configurations"
351 This manual page describes functions that appear in any configuration
353 There are two common configurations;
354 see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
355 .TP 10 \" "ncursesw" + 2n
357 is the library in its \*(``non-wide\*('' configuration,
358 handling only eight-bit characters.
359 It stores a character combined with attributes in a
362 which is often an alias of
366 (with no corresponding character)
367 can be stored in variables of
373 they are represented as an integral bit mask.
381 is the library in its \*(``wide\*('' configuration,
382 which handles character encodings requiring a larger data type than
386 It adds about one third more calls using additional data types that
390 .RS 10 \" same as foregoing tag width
391 .TP 9 \" "cchar_t" + 2n
393 corresponds to the non-wide configuration's
395 It always a structure type,
396 because it stores more data than fits into an integral type.
397 A character code may not be representable as a
399 and moreover more than one character may occupy a cell
400 (as with accent marks and other diacritics).
401 Each character is of type
403 a complex character contains one spacing character and zero or more
404 non-spacing characters
406 Attributes and color data are stored in separate fields of the
416 The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
417 functions store and retrieve the data from a
420 The wide library API of
422 depends on two data types standardized by ISO C95.
425 stores a wide character.
428 it may be an alias of
430 Depending on the character encoding,
431 a wide character may be
433 meaning that it occupies a character cell by itself and typically
434 accompanies cursor advancement,
437 meaning that it occupies the same cell as a spacing character,
438 is often regarded as a \*(``modifier\*('' of the base glyph with which
440 and typically does not advance the cursor.
449 character manipulation functions of ISO C and its constant
453 The wide library provides additional functions that complement those in
454 the non-wide library where the size of the underlying character type is
456 A somewhat regular naming convention relates many of the wide variants
457 to their non-wide counterparts;
458 where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
459 prefix it with \*(``_w\*('' to obtain the wide counterpart.
461 \fB\%waddch\fP becomes \fB\%wadd_wch\fP.
463 This convention is inapplicable to some non-wide function names,
464 so other transformations are used for the wide configuration:
465 in the window background management functions,
466 \*(``bkgd\*('' becomes \*(``bkgrnd\*('';
467 the window border-drawing and -clearing functions are suffixed with
470 .SS "Function Name Index"
471 The following table lists the
473 functions provided in the non-wide and wide APIs and the corresponding
474 man pages that describe them.
475 Those flagged with \*(``*\*(''
477 .IR \%ncurses -specific,
478 neither described by X/Open Curses nor present in SVr4.
483 \f(BIcurses\fP Function Name/Man Page
485 COLOR_PAIR/\fBcurs_color\fP(3X)
486 PAIR_NUMBER/\fBcurs_color\fP(3X)
487 add_wch/\fBcurs_add_wch\fP(3X)
488 add_wchnstr/\fBcurs_add_wchstr\fP(3X)
489 add_wchstr/\fBcurs_add_wchstr\fP(3X)
490 addch/\fBcurs_addch\fP(3X)
491 addchnstr/\fBcurs_addchstr\fP(3X)
492 addchstr/\fBcurs_addchstr\fP(3X)
493 addnstr/\fBcurs_addstr\fP(3X)
494 addnwstr/\fBcurs_addwstr\fP(3X)
495 addstr/\fBcurs_addstr\fP(3X)
496 addwstr/\fBcurs_addwstr\fP(3X)
497 alloc_pair/\fBnew_pair\fP(3X)*
498 assume_default_colors/\fBdefault_colors\fP(3X)*
499 attr_get/\fBcurs_attr\fP(3X)
500 attr_off/\fBcurs_attr\fP(3X)
501 attr_on/\fBcurs_attr\fP(3X)
502 attr_set/\fBcurs_attr\fP(3X)
503 attroff/\fBcurs_attr\fP(3X)
504 attron/\fBcurs_attr\fP(3X)
505 attrset/\fBcurs_attr\fP(3X)
506 baudrate/\fBcurs_termattrs\fP(3X)
507 beep/\fBcurs_beep\fP(3X)
508 bkgd/\fBcurs_bkgd\fP(3X)
509 bkgdset/\fBcurs_bkgd\fP(3X)
510 bkgrnd/\fBcurs_bkgrnd\fP(3X)
511 bkgrndset/\fBcurs_bkgrnd\fP(3X)
512 border/\fBcurs_border\fP(3X)
513 border_set/\fBcurs_border_set\fP(3X)
514 box/\fBcurs_border\fP(3X)
515 box_set/\fBcurs_border_set\fP(3X)
516 can_change_color/\fBcurs_color\fP(3X)
517 cbreak/\fBcurs_inopts\fP(3X)
518 chgat/\fBcurs_attr\fP(3X)
519 clear/\fBcurs_clear\fP(3X)
520 clearok/\fBcurs_outopts\fP(3X)
521 clrtobot/\fBcurs_clear\fP(3X)
522 clrtoeol/\fBcurs_clear\fP(3X)
523 color_content/\fBcurs_color\fP(3X)
524 color_set/\fBcurs_attr\fP(3X)
525 copywin/\fBcurs_overlay\fP(3X)
526 curs_set/\fBcurs_kernel\fP(3X)
527 curses_trace/\fBcurs_trace\fP(3X)*
528 curses_version/\fBcurs_extend\fP(3X)*
529 def_prog_mode/\fBcurs_kernel\fP(3X)
530 def_shell_mode/\fBcurs_kernel\fP(3X)
531 define_key/\fBdefine_key\fP(3X)*
532 del_curterm/\fBcurs_terminfo\fP(3X)
533 delay_output/\fBcurs_util\fP(3X)
534 delch/\fBcurs_delch\fP(3X)
535 deleteln/\fBcurs_deleteln\fP(3X)
536 delscreen/\fBcurs_initscr\fP(3X)
537 delwin/\fBcurs_window\fP(3X)
538 derwin/\fBcurs_window\fP(3X)
539 doupdate/\fBcurs_refresh\fP(3X)
540 dupwin/\fBcurs_window\fP(3X)
541 echo/\fBcurs_inopts\fP(3X)
542 echo_wchar/\fBcurs_add_wch\fP(3X)
543 echochar/\fBcurs_addch\fP(3X)
544 endwin/\fBcurs_initscr\fP(3X)
545 erase/\fBcurs_clear\fP(3X)
546 erasechar/\fBcurs_termattrs\fP(3X)
547 erasewchar/\fBcurs_termattrs\fP(3X)
548 exit_curses/\fBcurs_memleaks\fP(3X)*
549 exit_terminfo/\fBcurs_memleaks\fP(3X)*
550 extended_color_content/\fBcurs_color\fP(3X)*
551 extended_pair_content/\fBcurs_color\fP(3X)*
552 extended_slk_color/\fBcurs_slk\fP(3X)*
553 filter/\fBcurs_util\fP(3X)
554 find_pair/\fBnew_pair\fP(3X)*
555 flash/\fBcurs_beep\fP(3X)
556 flushinp/\fBcurs_util\fP(3X)
557 free_pair/\fBnew_pair\fP(3X)*
558 get_wch/\fBcurs_get_wch\fP(3X)
559 get_wstr/\fBcurs_get_wstr\fP(3X)
560 getattrs/\fBcurs_attr\fP(3X)
561 getbegx/\fBcurs_legacy\fP(3X)*
562 getbegy/\fBcurs_legacy\fP(3X)*
563 getbegyx/\fBcurs_getyx\fP(3X)
564 getbkgd/\fBcurs_bkgd\fP(3X)
565 getbkgrnd/\fBcurs_bkgrnd\fP(3X)
566 getcchar/\fBcurs_getcchar\fP(3X)
567 getch/\fBcurs_getch\fP(3X)
568 getcurx/\fBcurs_legacy\fP(3X)*
569 getcury/\fBcurs_legacy\fP(3X)*
570 getmaxx/\fBcurs_legacy\fP(3X)*
571 getmaxy/\fBcurs_legacy\fP(3X)*
572 getmaxyx/\fBcurs_getyx\fP(3X)
573 getmouse/\fBcurs_mouse\fP(3X)*
574 getn_wstr/\fBcurs_get_wstr\fP(3X)
575 getnstr/\fBcurs_getstr\fP(3X)
576 getparx/\fBcurs_legacy\fP(3X)*
577 getpary/\fBcurs_legacy\fP(3X)*
578 getparyx/\fBcurs_getyx\fP(3X)
579 getstr/\fBcurs_getstr\fP(3X)
580 getsyx/\fBcurs_kernel\fP(3X)
581 getwin/\fBcurs_util\fP(3X)
582 getyx/\fBcurs_getyx\fP(3X)
583 halfdelay/\fBcurs_inopts\fP(3X)
584 has_colors/\fBcurs_color\fP(3X)
585 has_ic/\fBcurs_termattrs\fP(3X)
586 has_il/\fBcurs_termattrs\fP(3X)
587 has_key/\fBcurs_getch\fP(3X)*
588 has_mouse/\fBcurs_mouse\fP(3X)*
589 hline/\fBcurs_border\fP(3X)
590 hline_set/\fBcurs_border_set\fP(3X)
591 idcok/\fBcurs_outopts\fP(3X)
592 idlok/\fBcurs_outopts\fP(3X)
593 immedok/\fBcurs_outopts\fP(3X)
594 in_wch/\fBcurs_in_wch\fP(3X)
595 in_wchnstr/\fBcurs_in_wchstr\fP(3X)
596 in_wchstr/\fBcurs_in_wchstr\fP(3X)
597 inch/\fBcurs_inch\fP(3X)
598 inchnstr/\fBcurs_inchstr\fP(3X)
599 inchstr/\fBcurs_inchstr\fP(3X)
600 init_color/\fBcurs_color\fP(3X)
601 init_extended_color/\fBcurs_color\fP(3X)*
602 init_extended_pair/\fBcurs_color\fP(3X)*
603 init_pair/\fBcurs_color\fP(3X)
604 initscr/\fBcurs_initscr\fP(3X)
605 innstr/\fBcurs_instr\fP(3X)
606 innwstr/\fBcurs_inwstr\fP(3X)
607 ins_nwstr/\fBcurs_ins_wstr\fP(3X)
608 ins_wch/\fBcurs_ins_wch\fP(3X)
609 ins_wstr/\fBcurs_ins_wstr\fP(3X)
610 insch/\fBcurs_insch\fP(3X)
611 insdelln/\fBcurs_deleteln\fP(3X)
612 insertln/\fBcurs_deleteln\fP(3X)
613 insnstr/\fBcurs_insstr\fP(3X)
614 insstr/\fBcurs_insstr\fP(3X)
615 instr/\fBcurs_instr\fP(3X)
616 intrflush/\fBcurs_inopts\fP(3X)
617 inwstr/\fBcurs_inwstr\fP(3X)
618 is_cbreak/\fBcurs_inopts\fP(3X)*
619 is_cleared/\fBcurs_opaque\fP(3X)*
620 is_echo/\fBcurs_inopts\fP(3X)*
621 is_idcok/\fBcurs_opaque\fP(3X)*
622 is_idlok/\fBcurs_opaque\fP(3X)*
623 is_immedok/\fBcurs_opaque\fP(3X)*
624 is_keypad/\fBcurs_opaque\fP(3X)*
625 is_leaveok/\fBcurs_opaque\fP(3X)*
626 is_linetouched/\fBcurs_touch\fP(3X)
627 is_nl/\fBcurs_inopts\fP(3X)*
628 is_nodelay/\fBcurs_opaque\fP(3X)*
629 is_notimeout/\fBcurs_opaque\fP(3X)*
630 is_pad/\fBcurs_opaque\fP(3X)*
631 is_raw/\fBcurs_inopts\fP(3X)*
632 is_scrollok/\fBcurs_opaque\fP(3X)*
633 is_subwin/\fBcurs_opaque\fP(3X)*
634 is_syncok/\fBcurs_opaque\fP(3X)*
635 is_term_resized/\fBresizeterm\fP(3X)*
636 is_wintouched/\fBcurs_touch\fP(3X)
637 isendwin/\fBcurs_initscr\fP(3X)
638 key_defined/\fBkey_defined\fP(3X)*
639 key_name/\fBcurs_util\fP(3X)
640 keybound/\fBkeybound\fP(3X)*
641 keyname/\fBcurs_util\fP(3X)
642 keyok/\fBkeyok\fP(3X)*
643 keypad/\fBcurs_inopts\fP(3X)
644 killchar/\fBcurs_termattrs\fP(3X)
645 killwchar/\fBcurs_termattrs\fP(3X)
646 leaveok/\fBcurs_outopts\fP(3X)
647 longname/\fBcurs_termattrs\fP(3X)
648 mcprint/\fBcurs_print\fP(3X)*
649 meta/\fBcurs_inopts\fP(3X)
650 mouse_trafo/\fBcurs_mouse\fP(3X)*
651 mouseinterval/\fBcurs_mouse\fP(3X)*
652 mousemask/\fBcurs_mouse\fP(3X)*
653 move/\fBcurs_move\fP(3X)
654 mvadd_wch/\fBcurs_add_wch\fP(3X)
655 mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
656 mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
657 mvaddch/\fBcurs_addch\fP(3X)
658 mvaddchnstr/\fBcurs_addchstr\fP(3X)
659 mvaddchstr/\fBcurs_addchstr\fP(3X)
660 mvaddnstr/\fBcurs_addstr\fP(3X)
661 mvaddnwstr/\fBcurs_addwstr\fP(3X)
662 mvaddstr/\fBcurs_addstr\fP(3X)
663 mvaddwstr/\fBcurs_addwstr\fP(3X)
664 mvchgat/\fBcurs_attr\fP(3X)
665 mvcur/\fBcurs_terminfo\fP(3X)
666 mvdelch/\fBcurs_delch\fP(3X)
667 mvderwin/\fBcurs_window\fP(3X)
668 mvget_wch/\fBcurs_get_wch\fP(3X)
669 mvget_wstr/\fBcurs_get_wstr\fP(3X)
670 mvgetch/\fBcurs_getch\fP(3X)
671 mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
672 mvgetnstr/\fBcurs_getstr\fP(3X)
673 mvgetstr/\fBcurs_getstr\fP(3X)
674 mvhline/\fBcurs_border\fP(3X)
675 mvhline_set/\fBcurs_border_set\fP(3X)
676 mvin_wch/\fBcurs_in_wch\fP(3X)
677 mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
678 mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
679 mvinch/\fBcurs_inch\fP(3X)
680 mvinchnstr/\fBcurs_inchstr\fP(3X)
681 mvinchstr/\fBcurs_inchstr\fP(3X)
682 mvinnstr/\fBcurs_instr\fP(3X)
683 mvinnwstr/\fBcurs_inwstr\fP(3X)
684 mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
685 mvins_wch/\fBcurs_ins_wch\fP(3X)
686 mvins_wstr/\fBcurs_ins_wstr\fP(3X)
687 mvinsch/\fBcurs_insch\fP(3X)
688 mvinsnstr/\fBcurs_insstr\fP(3X)
689 mvinsstr/\fBcurs_insstr\fP(3X)
690 mvinstr/\fBcurs_instr\fP(3X)
691 mvinwstr/\fBcurs_inwstr\fP(3X)
692 mvprintw/\fBcurs_printw\fP(3X)
693 mvscanw/\fBcurs_scanw\fP(3X)
694 mvvline/\fBcurs_border\fP(3X)
695 mvvline_set/\fBcurs_border_set\fP(3X)
696 mvwadd_wch/\fBcurs_add_wch\fP(3X)
697 mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
698 mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
699 mvwaddch/\fBcurs_addch\fP(3X)
700 mvwaddchnstr/\fBcurs_addchstr\fP(3X)
701 mvwaddchstr/\fBcurs_addchstr\fP(3X)
702 mvwaddnstr/\fBcurs_addstr\fP(3X)
703 mvwaddnwstr/\fBcurs_addwstr\fP(3X)
704 mvwaddstr/\fBcurs_addstr\fP(3X)
705 mvwaddwstr/\fBcurs_addwstr\fP(3X)
706 mvwchgat/\fBcurs_attr\fP(3X)
707 mvwdelch/\fBcurs_delch\fP(3X)
708 mvwget_wch/\fBcurs_get_wch\fP(3X)
709 mvwget_wstr/\fBcurs_get_wstr\fP(3X)
710 mvwgetch/\fBcurs_getch\fP(3X)
711 mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
712 mvwgetnstr/\fBcurs_getstr\fP(3X)
713 mvwgetstr/\fBcurs_getstr\fP(3X)
714 mvwhline/\fBcurs_border\fP(3X)
715 mvwhline_set/\fBcurs_border_set\fP(3X)
716 mvwin/\fBcurs_window\fP(3X)
717 mvwin_wch/\fBcurs_in_wch\fP(3X)
718 mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
719 mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
720 mvwinch/\fBcurs_inch\fP(3X)
721 mvwinchnstr/\fBcurs_inchstr\fP(3X)
722 mvwinchstr/\fBcurs_inchstr\fP(3X)
723 mvwinnstr/\fBcurs_instr\fP(3X)
724 mvwinnwstr/\fBcurs_inwstr\fP(3X)
725 mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
726 mvwins_wch/\fBcurs_ins_wch\fP(3X)
727 mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
728 mvwinsch/\fBcurs_insch\fP(3X)
729 mvwinsnstr/\fBcurs_insstr\fP(3X)
730 mvwinsstr/\fBcurs_insstr\fP(3X)
731 mvwinstr/\fBcurs_instr\fP(3X)
732 mvwinwstr/\fBcurs_inwstr\fP(3X)
733 mvwprintw/\fBcurs_printw\fP(3X)
734 mvwscanw/\fBcurs_scanw\fP(3X)
735 mvwvline/\fBcurs_border\fP(3X)
736 mvwvline_set/\fBcurs_border_set\fP(3X)
737 napms/\fBcurs_kernel\fP(3X)
738 newpad/\fBcurs_pad\fP(3X)
739 newterm/\fBcurs_initscr\fP(3X)
740 newwin/\fBcurs_window\fP(3X)
741 nl/\fBcurs_inopts\fP(3X)
742 nocbreak/\fBcurs_inopts\fP(3X)
743 nodelay/\fBcurs_inopts\fP(3X)
744 noecho/\fBcurs_inopts\fP(3X)
745 nofilter/\fBcurs_util\fP(3X)*
746 nonl/\fBcurs_inopts\fP(3X)
747 noqiflush/\fBcurs_inopts\fP(3X)
748 noraw/\fBcurs_inopts\fP(3X)
749 notimeout/\fBcurs_inopts\fP(3X)
750 overlay/\fBcurs_overlay\fP(3X)
751 overwrite/\fBcurs_overlay\fP(3X)
752 pair_content/\fBcurs_color\fP(3X)
753 pecho_wchar/\fBcurs_pad\fP(3X)
754 pechochar/\fBcurs_pad\fP(3X)
755 pnoutrefresh/\fBcurs_pad\fP(3X)
756 prefresh/\fBcurs_pad\fP(3X)
757 printw/\fBcurs_printw\fP(3X)
758 putp/\fBcurs_terminfo\fP(3X)
759 putwin/\fBcurs_util\fP(3X)
760 qiflush/\fBcurs_inopts\fP(3X)
761 raw/\fBcurs_inopts\fP(3X)
762 redrawwin/\fBcurs_refresh\fP(3X)
763 refresh/\fBcurs_refresh\fP(3X)
764 reset_color_pairs/\fBcurs_color\fP(3X)*
765 reset_prog_mode/\fBcurs_kernel\fP(3X)
766 reset_shell_mode/\fBcurs_kernel\fP(3X)
767 resetty/\fBcurs_kernel\fP(3X)
768 resize_term/\fBresizeterm\fP(3X)*
769 resizeterm/\fBresizeterm\fP(3X)*
770 restartterm/\fBcurs_terminfo\fP(3X)
771 ripoffline/\fBcurs_kernel\fP(3X)
772 savetty/\fBcurs_kernel\fP(3X)
773 scanw/\fBcurs_scanw\fP(3X)
774 scr_dump/\fBcurs_scr_dump\fP(3X)
775 scr_init/\fBcurs_scr_dump\fP(3X)
776 scr_restore/\fBcurs_scr_dump\fP(3X)
777 scr_set/\fBcurs_scr_dump\fP(3X)
778 scrl/\fBcurs_scroll\fP(3X)
779 scroll/\fBcurs_scroll\fP(3X)
780 scrollok/\fBcurs_outopts\fP(3X)
781 set_curterm/\fBcurs_terminfo\fP(3X)
782 set_term/\fBcurs_initscr\fP(3X)
783 setcchar/\fBcurs_getcchar\fP(3X)
784 setscrreg/\fBcurs_outopts\fP(3X)
785 setsyx/\fBcurs_kernel\fP(3X)
786 setupterm/\fBcurs_terminfo\fP(3X)
787 slk_attr/\fBcurs_slk\fP(3X)*
788 slk_attr_off/\fBcurs_slk\fP(3X)
789 slk_attr_on/\fBcurs_slk\fP(3X)
790 slk_attr_set/\fBcurs_slk\fP(3X)
791 slk_attroff/\fBcurs_slk\fP(3X)
792 slk_attron/\fBcurs_slk\fP(3X)
793 slk_attrset/\fBcurs_slk\fP(3X)
794 slk_clear/\fBcurs_slk\fP(3X)
795 slk_color/\fBcurs_slk\fP(3X)
796 slk_init/\fBcurs_slk\fP(3X)
797 slk_label/\fBcurs_slk\fP(3X)
798 slk_noutrefresh/\fBcurs_slk\fP(3X)
799 slk_refresh/\fBcurs_slk\fP(3X)
800 slk_restore/\fBcurs_slk\fP(3X)
801 slk_set/\fBcurs_slk\fP(3X)
802 slk_touch/\fBcurs_slk\fP(3X)
803 slk_wset/\fBcurs_slk\fP(3X)
804 standend/\fBcurs_attr\fP(3X)
805 standout/\fBcurs_attr\fP(3X)
806 start_color/\fBcurs_color\fP(3X)
807 subpad/\fBcurs_pad\fP(3X)
808 subwin/\fBcurs_window\fP(3X)
809 syncok/\fBcurs_window\fP(3X)
810 term_attrs/\fBcurs_termattrs\fP(3X)
811 termattrs/\fBcurs_termattrs\fP(3X)
812 termname/\fBcurs_termattrs\fP(3X)
813 tgetent/\fBcurs_termcap\fP(3X)
814 tgetflag/\fBcurs_termcap\fP(3X)
815 tgetnum/\fBcurs_termcap\fP(3X)
816 tgetstr/\fBcurs_termcap\fP(3X)
817 tgoto/\fBcurs_termcap\fP(3X)
818 tigetflag/\fBcurs_terminfo\fP(3X)
819 tigetnum/\fBcurs_terminfo\fP(3X)
820 tigetstr/\fBcurs_terminfo\fP(3X)
821 timeout/\fBcurs_inopts\fP(3X)
822 tiparm/\fBcurs_terminfo\fP(3X)
823 tiparm_s/\fBcurs_terminfo\fP(3X)*
824 tiscan_s/\fBcurs_terminfo\fP(3X)*
825 touchline/\fBcurs_touch\fP(3X)
826 touchwin/\fBcurs_touch\fP(3X)
827 tparm/\fBcurs_terminfo\fP(3X)
828 tputs/\fBcurs_termcap\fP(3X)
829 tputs/\fBcurs_terminfo\fP(3X)
830 trace/\fBcurs_trace\fP(3X)*
831 typeahead/\fBcurs_inopts\fP(3X)
832 unctrl/\fBcurs_util\fP(3X)
833 unget_wch/\fBcurs_get_wch\fP(3X)
834 ungetch/\fBcurs_getch\fP(3X)
835 ungetmouse/\fBcurs_mouse\fP(3X)*
836 untouchwin/\fBcurs_touch\fP(3X)
837 use_default_colors/\fBdefault_colors\fP(3X)*
838 use_env/\fBcurs_util\fP(3X)
839 use_extended_names/\fBcurs_extend\fP(3X)*
840 use_legacy_coding/\fBlegacy_coding\fP(3X)*
841 use_tioctl/\fBcurs_util\fP(3X)*
842 vid_attr/\fBcurs_terminfo\fP(3X)
843 vid_puts/\fBcurs_terminfo\fP(3X)
844 vidattr/\fBcurs_terminfo\fP(3X)
845 vidputs/\fBcurs_terminfo\fP(3X)
846 vline/\fBcurs_border\fP(3X)
847 vline_set/\fBcurs_border_set\fP(3X)
848 vw_printw/\fBcurs_printw\fP(3X)
849 vw_scanw/\fBcurs_scanw\fP(3X)
850 vwprintw/\fBcurs_printw\fP(3X)
851 vwscanw/\fBcurs_scanw\fP(3X)
852 wadd_wch/\fBcurs_add_wch\fP(3X)
853 wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
854 wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
855 waddch/\fBcurs_addch\fP(3X)
856 waddchnstr/\fBcurs_addchstr\fP(3X)
857 waddchstr/\fBcurs_addchstr\fP(3X)
858 waddnstr/\fBcurs_addstr\fP(3X)
859 waddnwstr/\fBcurs_addwstr\fP(3X)
860 waddstr/\fBcurs_addstr\fP(3X)
861 waddwstr/\fBcurs_addwstr\fP(3X)
862 wattr_get/\fBcurs_attr\fP(3X)
863 wattr_off/\fBcurs_attr\fP(3X)
864 wattr_on/\fBcurs_attr\fP(3X)
865 wattr_set/\fBcurs_attr\fP(3X)
866 wattroff/\fBcurs_attr\fP(3X)
867 wattron/\fBcurs_attr\fP(3X)
868 wattrset/\fBcurs_attr\fP(3X)
869 wbkgd/\fBcurs_bkgd\fP(3X)
870 wbkgdset/\fBcurs_bkgd\fP(3X)
871 wbkgrnd/\fBcurs_bkgrnd\fP(3X)
872 wbkgrndset/\fBcurs_bkgrnd\fP(3X)
873 wborder/\fBcurs_border\fP(3X)
874 wborder_set/\fBcurs_border_set\fP(3X)
875 wchgat/\fBcurs_attr\fP(3X)
876 wclear/\fBcurs_clear\fP(3X)
877 wclrtobot/\fBcurs_clear\fP(3X)
878 wclrtoeol/\fBcurs_clear\fP(3X)
879 wcolor_set/\fBcurs_attr\fP(3X)
880 wcursyncup/\fBcurs_window\fP(3X)
881 wdelch/\fBcurs_delch\fP(3X)
882 wdeleteln/\fBcurs_deleteln\fP(3X)
883 wecho_wchar/\fBcurs_add_wch\fP(3X)
884 wechochar/\fBcurs_addch\fP(3X)
885 wenclose/\fBcurs_mouse\fP(3X)*
886 werase/\fBcurs_clear\fP(3X)
887 wget_wch/\fBcurs_get_wch\fP(3X)
888 wget_wstr/\fBcurs_get_wstr\fP(3X)
889 wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
890 wgetch/\fBcurs_getch\fP(3X)
891 wgetdelay/\fBcurs_opaque\fP(3X)*
892 wgetn_wstr/\fBcurs_get_wstr\fP(3X)
893 wgetnstr/\fBcurs_getstr\fP(3X)
894 wgetparent/\fBcurs_opaque\fP(3X)*
895 wgetscrreg/\fBcurs_opaque\fP(3X)*
896 wgetstr/\fBcurs_getstr\fP(3X)
897 whline/\fBcurs_border\fP(3X)
898 whline_set/\fBcurs_border_set\fP(3X)
899 win_wch/\fBcurs_in_wch\fP(3X)
900 win_wchnstr/\fBcurs_in_wchstr\fP(3X)
901 win_wchstr/\fBcurs_in_wchstr\fP(3X)
902 winch/\fBcurs_inch\fP(3X)
903 winchnstr/\fBcurs_inchstr\fP(3X)
904 winchstr/\fBcurs_inchstr\fP(3X)
905 winnstr/\fBcurs_instr\fP(3X)
906 winnwstr/\fBcurs_inwstr\fP(3X)
907 wins_nwstr/\fBcurs_ins_wstr\fP(3X)
908 wins_wch/\fBcurs_ins_wch\fP(3X)
909 wins_wstr/\fBcurs_ins_wstr\fP(3X)
910 winsch/\fBcurs_insch\fP(3X)
911 winsdelln/\fBcurs_deleteln\fP(3X)
912 winsertln/\fBcurs_deleteln\fP(3X)
913 winsnstr/\fBcurs_insstr\fP(3X)
914 winsstr/\fBcurs_insstr\fP(3X)
915 winstr/\fBcurs_instr\fP(3X)
916 winwstr/\fBcurs_inwstr\fP(3X)
917 wmouse_trafo/\fBcurs_mouse\fP(3X)*
918 wmove/\fBcurs_move\fP(3X)
919 wnoutrefresh/\fBcurs_refresh\fP(3X)
920 wprintw/\fBcurs_printw\fP(3X)
921 wredrawln/\fBcurs_refresh\fP(3X)
922 wrefresh/\fBcurs_refresh\fP(3X)
923 wresize/\fBwresize\fP(3X)*
924 wscanw/\fBcurs_scanw\fP(3X)
925 wscrl/\fBcurs_scroll\fP(3X)
926 wsetscrreg/\fBcurs_outopts\fP(3X)
927 wstandend/\fBcurs_attr\fP(3X)
928 wstandout/\fBcurs_attr\fP(3X)
929 wsyncdown/\fBcurs_window\fP(3X)
930 wsyncup/\fBcurs_window\fP(3X)
931 wtimeout/\fBcurs_inopts\fP(3X)
932 wtouchln/\fBcurs_touch\fP(3X)
933 wunctrl/\fBcurs_util\fP(3X)
934 wvline/\fBcurs_border\fP(3X)
935 wvline_set/\fBcurs_border_set\fP(3X)
938 Depending on the configuration,
939 additional sets of functions may be available:
942 \fBcurs_memleaks\fP(3X) - curses memory-leak checking
944 \fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension
946 \fBcurs_threads\fP(3X) - curses thread support
948 \fBcurs_trace\fP(3X) - curses debugging routines
951 Unless otherwise noted,
952 functions that return an integer return \fBOK\fP on success and
953 \fBERR\fP on failure.
954 Functions that return pointers return \fBNULL\fP on failure.
957 treats a null pointer passed as a function parameter as a failure.
959 Functions with a \*(``mv\*('' prefix first perform cursor movement using
960 \fB\%wmove\fP and fail if the position is outside the window,
962 (for \*(``mvw\*('' functions)
967 The following environment symbols are useful for customizing the
968 runtime behavior of the \fI\%ncurses\fP library.
969 The most important ones have been already discussed in detail.
970 .SS "\fICC\fP (command character)"
973 .B \%command_character
975 capability value of loaded
977 entries to the value of this variable.
980 entries provide this feature.
982 Because this name is also used in development environments to represent
983 the C compiler's name,
984 \fI\%ncurses\fP ignores it if it does not happen to be a single
987 The debugging library checks this environment variable when the application
988 has redirected output to a file.
989 The variable's numeric value is used for the baud rate.
990 If no value is found, \fI\%ncurses\fP uses 9600.
991 This allows testers to construct repeatable test-cases
992 that take into account costs that depend on baud rate.
994 Specify the width of the screen in characters.
995 Applications running in a windowing environment usually are able to
996 obtain the width of the window in which they are executing.
997 If neither the \fI\%COLUMNS\fP value
998 nor the terminal's screen size is available,
999 \fI\%ncurses\fP uses the size which may be specified in the terminfo
1001 (i.e., the \fBcols\fP capability).
1003 It is important that your application use a correct size for the screen.
1004 This is not always possible because your application may be
1005 running on a host which does not honor NAWS (Negotiations About Window
1006 Size), or because you are temporarily running as another user.
1008 setting \fI\%COLUMNS\fP and/or \fILINES\fP overrides the library's use
1009 of the screen size obtained from the operating system.
1011 Either \fI\%COLUMNS\fP or \fILINES\fP symbols may be specified
1013 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
1014 e.g., xterm which commonly specifies a 65 line screen.
1015 For best results, \fBlines\fP and \fBcols\fP should not be specified in
1016 a terminal description for terminals which are run as emulations.
1018 Use the \fBuse_env\fP function to disable all use of external environment
1019 (but not including system calls) to determine the screen size.
1020 Use the \fBuse_tioctl\fP function to update \fI\%COLUMNS\fP or
1021 \fILINES\fP to match the screen size obtained from system calls or the
1023 .SS "\fIESCDELAY\fP"
1024 Specifies the total time,
1026 for which \fI\%ncurses\fP will await a character sequence,
1029 The default value, 1000 milliseconds, is enough for most uses.
1030 However, it is made a variable to accommodate unusual applications.
1032 The most common instance where you may wish to change this value
1033 is to work with slow hosts, e.g., running on a network.
1034 If the host cannot read characters rapidly enough, it will have the same
1035 effect as if the terminal did not send characters rapidly enough.
1036 The library will still see a timeout.
1038 Note that xterm mouse events are built up from character sequences
1039 received from the xterm.
1040 If your application makes heavy use of multiple-clicking, you may
1041 wish to lengthen this default value because the timeout applies
1042 to the composed multi-click event as well as the individual clicks.
1044 In addition to the environment variable,
1045 this implementation provides a global variable with the same name.
1046 Portable applications should not rely upon the presence of \fB\%ESCDELAY\fP
1048 but setting the environment variable rather than the global variable
1049 does not create problems when compiling an application.
1051 Tells \fI\%ncurses\fP where your home directory is.
1052 That is where it may read and write auxiliary terminal descriptions:
1061 Like \fI\%COLUMNS\fP, specify the height of the screen in characters.
1062 See \fI\%COLUMNS\fP for a detailed description.
1063 .SS "\fIMOUSE_BUTTONS_123\fP"
1064 This applies only to the OS/2 EMX port.
1065 It specifies the order of buttons on the mouse.
1066 OS/2 numbers a 3-button mouse inconsistently from other
1077 This variable lets you customize the mouse.
1078 The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
1079 If it is not specified, \fI\%ncurses\fP uses 132.
1080 .SS "\fINCURSES_ASSUMED_COLORS\fP"
1081 Override the compiled-in assumption that the
1082 terminal's default colors are white-on-black
1083 (see \fBdefault_colors\fP(3X)).
1084 You may set the foreground and background color values with this environment
1085 variable by proving a 2-element list: foreground,background.
1086 For example, to tell \fI\%ncurses\fP to not assume anything
1087 about the colors, set this to "\-1,\-1".
1088 To make it green-on-black, set it to "2,0".
1089 Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed.
1090 .SS "\fINCURSES_CONSOLE2\fP"
1091 This applies only to the MinGW port of \fI\%ncurses\fP.
1093 The \fBConsole2\fP program's handling of the Microsoft Console API call
1094 \fBCreateConsoleScreenBuffer\fP is defective.
1095 Applications which use this will hang.
1096 However, it is possible to simulate the action of this call by
1097 mapping coordinates,
1098 explicitly saving and restoring the original screen contents.
1099 Setting the environment variable \fBNCGDB\fP has the same effect.
1100 .SS "\fINCURSES_GPM_TERMS\fP"
1101 This applies only to \fI\%ncurses\fP configured to use the GPM
1105 the environment variable is a list of one or more terminal names
1106 against which the \fITERM\fP environment variable is matched.
1107 Setting it to an empty value disables the GPM interface;
1108 using the built-in support for xterm, etc.
1110 If the environment variable is absent,
1111 \fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains
1113 .SS "\fINCURSES_NO_HARD_TABS\fP"
1114 \fI\%ncurses\fP may use tabs as part of cursor movement optimization.
1116 your terminal driver may not handle these properly.
1117 Set this environment variable to any value to disable the feature.
1118 You can also adjust your \fBstty\fP(1) settings to avoid the problem.
1119 .SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
1120 Some terminals use a magic-cookie feature which requires special handling
1121 to make highlighting and other video attributes display properly.
1122 You can suppress the highlighting entirely for these terminals by
1123 setting this environment variable to any value.
1124 .SS "\fINCURSES_NO_PADDING\fP"
1125 Most of the terminal descriptions in the terminfo database are written
1126 for real \*(``hardware\*('' terminals.
1127 Many people use terminal emulators
1128 which run in a windowing environment and use curses-based applications.
1129 Terminal emulators can duplicate
1130 all of the important aspects of a hardware terminal, but they do not
1131 have the same limitations.
1132 The chief limitation of a hardware terminal from the standpoint
1133 of your application is the management of dataflow, i.e., timing.
1134 Unless a hardware terminal is interfaced into a terminal concentrator
1135 (which does flow control),
1136 it (or your application) must manage dataflow, preventing overruns.
1137 The cheapest solution (no hardware cost)
1138 is for your program to do this by pausing after
1139 operations that the terminal does slowly, such as clearing the display.
1141 As a result, many terminal descriptions (including the vt100)
1142 have delay times embedded.
1143 You may wish to use these descriptions,
1144 but not want to pay the performance penalty.
1146 Set the \fI\%NCURSES_NO_PADDING\fP environment variable
1147 to disable all but mandatory padding.
1148 Mandatory padding is used as a part of special control
1149 sequences such as \fBflash\fP.
1150 .SS "\fINCURSES_NO_SETBUF\fP"
1151 This setting is obsolete.
1155 started with 5.9 patch 20120825
1159 though 5.9 patch 20130126
1162 \fI\%ncurses\fP enabled buffered output during terminal initialization.
1163 This was done (as in SVr4 curses) for performance reasons.
1164 For testing purposes, both of \fI\%ncurses\fP and certain applications,
1165 this feature was made optional.
1166 Setting the \fI\%NCURSES_NO_SETBUF\fP variable
1167 disabled output buffering, leaving the output in the original (usually
1168 line buffered) mode.
1170 In the current implementation,
1171 \fI\%ncurses\fP performs its own buffering and does not require this
1173 It does not modify the buffering of the standard output.
1175 The reason for the change was to make the behavior for interrupts and
1176 other signals more robust.
1177 One drawback is that certain nonconventional programs would mix
1178 ordinary \fI\%stdio\fP(3) calls with \fI\%ncurses\fP calls and (usually)
1180 This is no longer possible since \fI\%ncurses\fP is not using
1181 the buffered standard output but its own output (to the same file descriptor).
1182 As a special case, the low-level calls such as \fBputp\fP still use the
1184 But high-level curses calls do not.
1185 .SS "\fINCURSES_NO_UTF8_ACS\fP"
1186 During initialization, the \fI\%ncurses\fP library
1187 checks for special cases where VT100 line-drawing (and the corresponding
1188 alternate character set capabilities) described in the terminfo are known
1190 Specifically, when running in a UTF\-8 locale,
1191 the Linux console emulator and the GNU screen program ignore these.
1192 \fI\%ncurses checks the \fITERM\fP environment variable for these.
1193 For other special cases, you should set this environment variable.
1194 Doing this tells \fI\%ncurses\fP to use Unicode values which correspond
1195 to the VT100 line-drawing glyphs.
1196 That works for the special cases cited,
1197 and is likely to work for terminal emulators.
1199 When setting this variable, you should set it to a nonzero value.
1200 Setting it to zero (or to a nonnumber)
1201 disables the special check for \*(``linux\*('' and \*(``screen\*(''.
1203 As an alternative to the environment variable,
1204 \fI\%ncurses\fP checks for an extended terminfo capability \fBU8\fP.
1205 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
1210 # linux console, if patched to provide working
1211 # VT100 shift\-in/shift\-out, with corresponding font.
1212 linux\-vt100|linux console with VT100 line\-graphics,
1215 # uxterm with vt100Graphics resource set to false
1216 xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
1221 The name \*(``U8\*('' is chosen to be two characters,
1222 to permit it to be used by applications that use \fI\%ncurses\fP'
1224 .SS "\fINCURSES_TRACE\fP"
1225 During initialization, the \fI\%ncurses\fP debugging library
1226 checks the \fI\%NCURSES_TRACE\fP environment variable.
1229 \fI\%ncurses\fP calls the \fBtrace\fP function,
1230 using that value as the argument.
1232 The argument values, which are defined in \fBcurses.h\fP, provide several
1233 types of information.
1234 When running with traces enabled, your application will write the
1235 file \fBtrace\fP to the current directory.
1237 See \fBcurs_trace\fP(3X) for more information.
1239 Denotes your terminal type.
1240 Each terminal type is distinct, though many are similar.
1242 \fITERM\fP is commonly set by terminal emulators to help
1243 applications find a workable terminal description.
1244 Some of those choose a popular approximation, e.g.,
1245 \*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
1246 Not infrequently, your application will have problems with that approach,
1247 e.g., incorrect function-key definitions.
1249 If you set \fITERM\fP in your environment,
1250 it has no effect on the operation of the terminal emulator.
1251 It only affects the way applications work within the terminal.
1252 Likewise, as a general rule (\fBxterm\fP(1) being a rare exception),
1253 terminal emulators which allow you to
1254 specify \fITERM\fP as a parameter or configuration value do
1255 not change their behavior to match that setting.
1257 If the \fI\%ncurses\fP library has been configured with \fItermcap\fP
1258 support, \fI\%ncurses\fP will check for a terminal's description in
1259 termcap form if it is not available in the terminfo database.
1261 The \fI\%TERMCAP\fP environment variable contains
1262 either a terminal description (with newlines stripped out),
1263 or a file name telling where the information denoted by
1264 the \fITERM\fP environment variable exists.
1265 In either case, setting it directs \fI\%ncurses\fP to ignore
1266 the usual place for this information, e.g., /etc/termcap.
1267 .SS "\fITERMINFO\fP"
1268 \fI\%ncurses\fP can be configured to read from multiple terminal
1270 The \fI\%TERMINFO\fP variable overrides the location for
1271 the default terminal database.
1272 Terminal descriptions (in terminal format) are stored in terminal databases:
1274 Normally these are stored in a directory tree,
1275 using subdirectories named by the first letter of the terminal names therein.
1277 This is the scheme used in System V, which legacy Unix systems use,
1278 and the \fI\%TERMINFO\fP variable is used by \fIcurses\fP applications
1280 systems to override the default location of the terminal database.
1282 If \fI\%ncurses\fP is built to use hashed databases,
1283 then each entry in this list may be the path of a hashed database file, e.g.,
1288 /usr/share/terminfo.db
1296 /usr/share/terminfo/
1300 The hashed database uses less disk-space and is a little faster than the
1303 some applications assume the existence of the directory tree,
1305 rather than using the terminfo library calls.
1308 If \fI\%ncurses\fP is built with a support for reading termcap files
1309 directly, then an entry in this list may be the path of a termcap file.
1311 If the \fI\%TERMINFO\fP variable begins with
1312 \*(``hex:\*('' or \*(``b64:\*('',
1313 \fI\%ncurses\fP uses the remainder of that variable as a compiled
1314 terminal description.
1315 You might produce the base64 format using \fBinfocmp\fP(1M):
1320 TERMINFO="$(infocmp \-0 \-Q2 \-q)"
1325 The compiled description is used if it corresponds to the terminal identified
1326 by the \fITERM\fP variable.
1329 Setting \fI\%TERMINFO\fP is the simplest,
1330 but not the only way to set location of the default terminal database.
1331 The complete list of database locations in order follows:
1334 the last terminal database to which \fI\%ncurses\fP wrote,
1335 if any, is searched first
1337 the location specified by the \fI\%TERMINFO\fP environment variable
1341 locations listed in the \fI\%TERMINFO_DIRS\fP environment variable
1343 one or more locations whose names are configured and compiled into the
1344 \fI\%ncurses\fP library, i.e.,
1347 @TERMINFO_DIRS@ (corresponding to the \fI\%TERMINFO_DIRS\fP variable)
1349 @TERMINFO@ (corresponding to the \fITERMINFO\fP variable)
1352 .SS "\fITERMINFO_DIRS\fP"
1353 Specifies a list of locations to search for terminal descriptions.
1354 Each location in the list is a terminal database as described in
1355 the section on the \fI\%TERMINFO\fP variable.
1356 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1358 There is no corresponding feature in System V terminfo;
1359 it is an extension developed for \fI\%ncurses\fP.
1360 .SS "\fITERMPATH\fP"
1361 If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks
1362 the \fI\%TERMPATH\fP environment variable.
1363 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
1364 semicolons on OS/2 EMX.
1366 If the \fI\%TERMPATH\fP environment variable is not set,
1367 \fI\%ncurses\fP looks in the files
1371 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1377 The library may be configured to disregard the following variables when the
1378 current user is the superuser (root), or if the application uses setuid or
1383 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1386 .SH "ALTERNATE CONFIGURATIONS"
1389 configurations are possible,
1390 determined by the options given to the
1392 script when building the library.
1393 Run the script with the
1395 option to peruse them all.
1396 A few are of particular significance to the application developer
1400 \-\-disable\-overwrite
1401 The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
1406 \fB#include <curses.h>\fP
1410 This option is used to avoid filename conflicts when \fI\%ncurses\fP
1411 is not the main implementation of curses of the computer.
1412 If \fI\%ncurses\fP is installed disabling overwrite,
1413 it puts its headers in a subdirectory,
1418 \fB#include <ncurses/curses.h>\fP
1422 It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
1423 to build executables.
1427 The configure script renames the library and
1428 (if the \fB\-\-disable\-overwrite\fP option is used)
1429 puts the header files in a different subdirectory.
1430 All of the library names have a \*(``w\*('' appended to them,
1448 You must also enable the wide-character features in the header file
1449 when compiling for the wide-character library
1450 to use the extended (wide-character) functions.
1451 The symbol which enables these features has changed since XSI Curses, Issue 4:
1453 Originally, the wide-character feature required the symbol
1454 \fB_XOPEN_SOURCE_EXTENDED\fP
1455 but that was only valid for XPG4 (1996).
1457 Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
1460 none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
1461 feature greater than 600.
1462 However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1464 Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
1465 with the caveat that some other header file than \fBcurses.h\fP
1466 may require a specific value for \fB_XOPEN_SOURCE\fP
1467 (or a system-specific symbol).
1469 The \fI\%curses.h\fP header file installed for the wide-character
1470 library is designed to be compatible with the non-wide library's header.
1471 Only the size of the \fI\%WINDOW\fP structure differs;
1472 few applications require more than pointers to \fI\%WINDOW\fPs.
1474 If the headers are installed allowing overwrite,
1475 the wide-character library's headers should be installed last,
1476 to allow applications to be built using either library
1477 from the same set of headers.
1481 The configure script renames the library.
1482 All of the library names have a \*(``t\*('' appended to them
1483 (before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
1485 The global variables such as \fBLINES\fP are replaced by macros to
1486 allow read-only access.
1487 At the same time, setter-functions are provided to set these values.
1488 Some applications (very few) may require changes to work with this convention.
1497 The shared and normal (static) library names differ by their suffixes,
1498 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1499 The debug and profiling libraries add a \*(``_g\*(''
1500 and a \*(``_p\*('' to the root names respectively,
1501 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1504 Low-level functions which do not depend upon whether the library
1505 supports wide-characters, are provided in the tinfo library.
1507 By doing this, it is possible to share the tinfo library between
1508 wide/normal configurations as well as reduce the size of the library
1509 when only low-level functions are needed.
1511 Those functions are described in these pages:
1514 \fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
1516 \fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
1518 \fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
1520 \fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
1522 \fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
1524 \fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
1527 \fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
1531 The \fBtrace\fP function normally resides in the debug library,
1532 but it is sometimes useful to configure this in the shared library.
1533 Configure scripts should check for the function's existence rather
1534 than assuming it is always in the debug library.
1538 tab stop initialization database
1541 compiled terminal capability database
1543 X/Open Curses permits most functions it specifies to be made available
1545 .\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
1546 .\" See X/Open Curses Issue 7, pp. 311-318.
1547 \fI\%ncurses\fP does so
1549 for functions that return values via their parameters,
1551 to support obsolete features,
1555 those that move the cursor before another operation),
1558 a few special cases.
1560 If the standard output file descriptor of an
1562 program is redirected to something that is not a terminal device,
1563 the library writes screen updates to the standard error file descriptor.
1564 This was an undocumented feature of SVr3.
1566 See subsection \*(``Header files\*('' below regarding symbols exposed by
1567 inclusion of \fI\%curses.h\fP.
1570 enables an application to capture mouse events on certain terminals,
1573 see \fB\%curs_mouse\fP(3X).
1576 provides a means of responding to window resizing events,
1577 as when running in a GUI terminal emulator application such as
1579 see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
1582 allows an application to query the terminal for the presence of a wide
1583 variety of special keys;
1584 see \fB\%has_key\fP(3X).
1587 extends the fixed set of function key capabilities specified by X/Open
1588 Curses by allowing the application programmer to define additional key
1589 sequences at runtime;
1591 \fB\%define_key\fP(3X),
1592 \fB\%key_defined\fP(3X),
1597 can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
1598 SGR\ 39 and SGR\ 49 sequences,
1599 which allow an application to reset the terminal to its original
1600 foreground and background colors.
1601 From a user's perspective,
1602 the application is able to draw colored text on a background whose color
1603 is set independently,
1604 providing better control over color contrasts.
1605 See \fB\%default_colors\fP(3X).
1609 application can choose to hide the internal details of
1612 instead using accessor functions such as
1613 \fB\%is_scrollok\fP(3X).
1616 enables an application to direct application output to a printer
1617 attached to the terminal device;
1618 see \fB\%curs_print\fP(3X).
1621 offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
1622 soft-label key lines,
1623 and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
1624 that can gather color information from them when many colors are
1627 Some extensions are only available if
1629 is compiled to support them;
1630 see section \*(``ALTERNATE CONFIGURATIONS\*('' above.
1632 Rudimentary support for multi-threaded applications may be available;
1633 see \fBcurs_threads\fP(3X).
1635 Functions that ease the management of multiple screens can be exposed;
1636 see \fBcurs_sp_funcs\fP(3X).
1640 causes the library to fall back to reading
1642 if the terminal setup code cannot find a
1644 entry corresponding to
1646 Use of this feature is not recommended,
1647 as it essentially includes an entire
1652 at a cost in memory usage and application launch latency.
1660 Individual man pages indicate where this is the case.
1662 X/Open Curses defines two levels of conformance,
1663 \*(``base\*('' and \*(``enhanced\*(''.
1664 The latter includes several additional features,
1665 such as wide-character and color support.
1667 intends base-level conformance with X/Open Curses,
1668 and supports nearly all its enhanced features.
1669 .\" XXX: What's missing? GBR counts untic(1), and that's all.
1671 Differences between X/Open Curses and
1673 are documented in the \*(``PORTABILITY\*('' sections of applicable man
1675 .SS "Error Checking"
1676 In many cases, X/Open Curses is vague about error conditions,
1677 omitting some of the SVr4 documentation.
1679 Unlike other implementations, this one checks parameters such as pointers
1680 to \fI\%WINDOW\fP structures to ensure they are not null.
1681 The main reason for providing this behavior is to guard against programmer
1683 The standard interface does not provide a way for the library
1684 to tell an application which of several possible errors were detected.
1685 Relying on this (or some other) extension will adversely affect the
1686 portability of curses applications.
1687 .SS "Padding Differences"
1688 In historic curses versions, delays embedded in the capabilities \fBcr\fP,
1689 \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay
1690 bits in the Unix tty driver.
1691 In this implementation, all padding is done by sending NUL bytes.
1692 This method is slightly more expensive, but narrows the interface
1693 to the Unix kernel significantly and increases the package's portability
1696 The header file \fI\%curses.h\fP itself includes the header files
1697 \fI\%stdio.h\fP and \fI\%unctrl.h\fP.
1699 X/Open Curses has more to say,
1700 but does not finish the story:
1703 The inclusion of <curses.h> may make visible all symbols
1704 from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1707 Here is a more complete story:
1709 Starting with BSD curses, all implementations have included <stdio.h>.
1711 BSD curses included <curses.h> and <unctrl.h> from an internal header
1714 (\*(``ext\*('' abbreviated \*(``externs\*('').
1716 BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
1717 but nothing in <curses.h> itself relied upon <stdio.h>.
1719 SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
1720 That is, the function prototype uses \fBFILE\fP.
1722 SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
1724 X/Open Curses documents all three of these functions.
1726 SVr4 curses and X/Open Curses do not require the developer to
1727 include <stdio.h> before including <curses.h>.
1728 Both document curses showing <curses.h> as the only required header.
1730 As a result, standard <curses.h> will always include <stdio.h>.
1732 X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
1734 As noted in \fBcurs_util\fP(3X),
1735 \fI\%ncurses\fP includes <unctrl.h> from <curses.h>
1738 X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
1740 HP-UX curses includes <term.h> from <curses.h>
1741 to declare \fBsetupterm\fP in curses.h,
1742 but \fI\%ncurses\fP (and Solaris curses) do not.
1744 AIX curses includes <term.h> and <termios.h>.
1745 Again, \fI\%ncurses\fP (and Solaris curses) do not.
1747 X/Open says that <curses.h> \fImay\fP include <term.h>,
1748 but there is no requirement that it do that.
1750 Some programs use functions declared in both <curses.h> and <term.h>,
1751 and must include both headers in the same module.
1752 Very old versions of AIX curses required including <curses.h>
1753 before including <term.h>.
1755 Because \fI\%ncurses\fP header files include the headers needed to
1756 define datatypes used in the headers,
1757 \fI\%ncurses\fP header files can be included in any order.
1758 But for portability, you should include <curses.h> before <term.h>.
1760 X/Open Curses says \fI"may make visible"\fP
1761 because including a header file does not necessarily make all symbols
1762 in it visible (there are ifdef's to consider).
1764 For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if
1765 the proper symbol is defined, and if \fI\%ncurses\fP is configured for
1766 wide-character support.
1767 If the header is included, its symbols may be made visible.
1768 That depends on the value used for \fB_XOPEN_SOURCE\fP
1771 X/Open Curses documents one required header,
1772 in a special case: <stdarg.h> before <curses.h> to prototype
1773 the \fBvw_printw\fP and \fBvw_scanw\fP functions
1774 (as well as the obsolete
1775 the \fBvwprintw\fP and \fBvwscanw\fP functions).
1776 Each of those uses a \fBva_list\fP parameter.
1778 The two obsolete functions were introduced in SVr3.
1779 The other functions were introduced in X/Open Curses.
1780 In between, SVr4 curses provided for the possibility that
1781 an application might include either <varargs.h> or <stdarg.h>.
1782 Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP
1784 Later, a special type (defined in <stdio.h>) was introduced,
1785 to allow for compiler type-checking.
1786 That special type is always available,
1787 because <stdio.h> is always included by <curses.h>.
1789 None of the X/Open Curses implementations require an application
1790 to include <stdarg.h> before <curses.h> because they either
1791 have allowed for a special type,
1793 (like \fI\%ncurses\fP)
1794 include <stdarg.h> directly to provide a portable interface.
1796 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1797 Based on \fIpcurses\fP by Pavel Curtis.
1799 \fB\%curs_variables\fP(3X),
1800 \fB\%terminfo\fP(5),
1801 \fB\%user_caps\fP(5)