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.221 2024/06/01 22:29:08 tom Exp $
32 .TH ncurses 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
49 .\" Add supplementary paragraph tag on its own line after TP.
50 .\" Adapted from TQ (which would produce mandoc warnings).
59 character-cell terminal interface with optimized output
62 \fB#include <curses.h>
65 The \*(``new curses\*('' library offers the programmer a
66 terminal-independent means of reading keyboard and mouse input and
67 updating character-cell terminals with output optimized to minimize
73 System V Release 4 Unix (\*(``SVr4\*('')
76 the development of which ceased in the 1990s.
77 This document describes
79 version @NCURSES_MAJOR@.@NCURSES_MINOR@
80 (patch @NCURSES_PATCH@).
83 permits control of the terminal screen's contents;
84 abstraction and subdivision thereof with
88 acquisition of keyboard and mouse events;
89 control of terminal input and output options;
90 selection of color and rendering attributes
91 (such as bold or underline);
92 the definition and use of
97 terminal capability database;
100 compatibility interface;
101 and an abstraction of the system's API for manipulating the terminal
102 (such as \fI\%termios\fP(3)).
105 implements the interface described by X/Open Curses Issue\ 7.
106 In many behavioral details not standardized by X/Open,
110 library of SVr4 and provides numerous useful extensions.
113 man pages employ several sections to clarify matters of usage and
114 interoperability with other
118 \*(``NOTES\*('' describes issues and caveats of which any user of the
121 such as limitations on the size of an underlying integral type or the
122 availability of a preprocessor macro exclusive of a function definition
123 (which prevents its address from being taken).
124 This section also describes implementation details that will be
125 significant to the programmer but which are not standardized.
127 \*(``EXTENSIONS\*('' presents
129 innovations beyond the X/Open Curses standard and/or the SVr4
134 to indicate that they cannot be implemented solely by using the library
136 but require access to the library's internal state.
138 \*(``PORTABILITY\*('' discusses matters
139 (beyond the exercise of extensions)
140 that should be considered when writing to a
143 or for multiple implementations.
145 \*(``HISTORY\*('' examines points of detail in
149 implementations over the decades of their development,
150 particularly where precedent or inertia have frustrated better design
153 where such inertia has been overcome).
157 application must be linked with the library;
160 option to your compiler or linker.
161 A debugging version of the library may be available;
165 (Your system integrator may have installed these libraries such that you
173 library generates trace logs
176 in the current directory)
180 See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
181 .SS "Application Structure"
184 application uses information from the system locale;
185 \fI\%setlocale\fP(3) prepares it for
191 setlocale(LC_ALL, "");
195 If the locale is not thus initialized,
196 the library assumes that characters are printable as in ISO\ 8859-1,
197 to work with certain legacy programs.
198 You should initialize the locale;
199 do not expect consistent behavior from the library when the locale has
202 \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)
203 must be called to initialize
205 before use of any functions that deal with windows and screens.
207 To get character-at-a-time input without echoing\(emmost interactive,
208 screen-oriented programs want this\(emuse the following sequence.
212 initscr(); cbreak(); noecho();
216 Most applications would perform further setup as follows.
221 keypad(stdscr, TRUE);
227 program then often enters an event loop of some sort.
228 Call \fB\%endwin\fP(3X) before exiting.
232 library abstracts the terminal screen by representing all or part of it
238 is a rectangular grid of character cells,
239 addressed by row and column coordinates
242 with the upper left corner as (0, 0).
245 the same size as the terminal screen,
247 Create others with \fB\%newwin\fP(3X).
251 library does not manage overlapping windows
255 to manage one screen-filling window,
256 or tile the screen into non-overlapping windows and not use
259 Mixing the two approaches will result in unpredictable and undesired
262 Functions permit manipulation of a window and the
264 identifying the cell within it at which the next output operation will
267 the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
268 these place the cursor within and write a character to
272 Frequent changes to the terminal screen can cause unpleasant flicker or
273 inefficient use of the communication channel to the device,
274 so as a rule the library does not update it automatically.
278 functions to accumulate a set of desired updates that make sense to
280 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
281 look like \fBstdscr\fP.
283 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
284 .\" does not mandate it in any way.
286 its output by computing a minimal volume of operations to mutate the
287 screen from its state at the previous refresh to the new one.
288 Effective optimization demands accurate information about the terminal
290 the management of such information is the province of the
291 \fB\%terminfo\fP(3X) API,
292 a feature of every standard
296 Special windows called
298 may also be manipulated.
299 These are not constrained to the size of the terminal screen and their
300 contents need not be completely displayed.
301 See \fB\%curs_pad\fP(3X).
303 Many terminals support configuration of character cell foreground and
304 background colors as well as
306 which cause characters to render in such modes as
310 See \fB\%curs_attr\fP(3X).
313 predefines constants for a small set of forms-drawing graphics
314 corresponding to the DEC Alternate Character Set (ACS),
315 a feature of VT100 and other terminals.
316 See \fB\%addch\fP(3X).
319 is implemented using the operating system's terminal driver;
320 key events are received not as scan codes but as byte sequences.
322 (alphanumeric and punctuation keys,
331 appears as a control character or a multibyte
332 .I "escape sequence."
334 can translate the latter into unique
336 See \fB\%keypad\fP(3X) and \fB\%getch\fP(3X).
339 provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
340 and \fBmenu\fP(3X) libraries;
341 they permit overlapping windows and ease construction of user interfaces
345 The selection of an appropriate value of
347 in the process environment is essential to correct
352 A well-configured system selects a correct
355 \fB\%tset\fP(1) may assist with troubleshooting exotic situations.
357 If you change the terminal type,
361 then run \fB\%tset\fP(1) or the
362 .RB \*(`` "@TPUT@ init" \*(''
364 See subsection \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
366 If the environment variables
373 program is executing in a graphical windowing environment,
374 the information obtained thence overrides that obtained by
378 extension supports resizable terminals;
379 see \fB\%wresize\fP(3X).
381 If the environment variable
386 program checks first for a terminal type description in the location it
389 is useful for developing type descriptions or when write permission to
393 See section \*(``ENVIRONMENT\*('' below.
394 .SS "Naming Conventions"
396 offers many functions in variant forms using a regular set of
397 alternatives to the name of an elemental one.
398 Those prefixed with \*(``w\*('' require a
401 those with a \*(``mv\*('' prefix first perform cursor movement using
403 a \*(``mvw\*('' prefix indicates both.
404 The \*(``w\*('' function is typically the elemental one;
405 the removal of this prefix usually indicates operation on
408 Four functions prefixed with \*(``p\*('' require a pad argument.
410 In function synopses,
412 man pages apply the following names to parameters.
413 We introduce the character types in the next subsection.
418 bf a \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
419 c a \fIchar\fP or \fIint\fP
421 wc a \fIwchar_t\fP or \fIwint_t\fP
423 win pointer to a \fIWINDOW\fP
424 pad pointer to a \fIWINDOW\fP that is a pad
426 .SS "Wide and Non-wide Character Configurations"
427 This man page primarily surveys functions that appear in any
428 configuration of the library.
429 There are two common configurations;
430 see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
431 .TP 10 \" "ncursesw" + 2n
433 is the library in its \*(``non-wide\*('' configuration,
434 handling only eight-bit characters.
435 It stores a character combined with attributes and a color pair in a
438 which is often an alias of
442 characters is similar to a C
447 string ends with an integral
453 Attributes and a color pair selection
454 (with no corresponding character)
455 can be stored in variables of
461 they are accessed via an integral bit mask.
469 is the library in its \*(``wide\*('' configuration,
470 which handles character encodings requiring a larger data type than
474 It provides additional functions that complement those in
475 the non-wide library where the size of the underlying character type is
477 A somewhat regular naming convention relates many of the wide variants
478 to their non-wide counterparts;
479 where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
480 prefix it with \*(``_w\*('' to obtain the wide counterpart.
482 \fB\%waddch\fP becomes \fB\%wadd_wch\fP.
483 (Exceptions that add only \*(``w\*('' comprise
488 This convention is inapplicable to some non-wide function names,
489 so other transformations are used for the wide configuration:
490 the window background management function \*(``bkgd\*('' becomes
492 the window border-drawing and -clearing functions are suffixed with
494 and character attribute manipulation functions like
495 \*(``attron\*('' become \*(``attr_on\*(''.
496 .RS 10 \" same as foregoing tag width
497 .TP 9 \" "cchar_t" + 2n
499 corresponds to the non-wide configuration's
501 It is a structure type
502 because it requires more storage than fits into a standard scalar type.
503 A character code may not be representable as a
505 and moreover more than one character may occupy a cell
506 (as with accent marks and other diacritics).
507 Each character is of type
509 a complex character contains one spacing character and zero or more
510 non-spacing characters
512 A string of complex characters ends with a
516 member is the null wide character.
517 Attributes and a color pair selection are stored in separate fields of
519 not combined into an integer as in
527 \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
531 The wide library API of
533 depends on two data types standardized by ISO C95.
536 stores a wide character.
539 it may be an alias of
541 Depending on the character encoding,
542 a wide character may be
544 meaning that it occupies a character cell by itself and typically
545 accompanies cursor advancement,
548 meaning that it occupies the same cell as a spacing character,
549 is often regarded as a \*(``modifier\*('' of the base glyph with which
551 and typically does not advance the cursor.
560 character manipulation functions of ISO C and its constant
564 .SS "Function Name Index"
565 The following table lists the
567 functions provided in the non-wide and wide APIs and the corresponding
568 man pages that describe them.
569 Those flagged with \*(``*\*(''
571 .IR \%ncurses "-specific,"
572 neither described by X/Open Curses nor present in SVr4.
577 \f(BIcurses\fP Function Name/Man Page
579 COLOR_PAIR/\fBcurs_color\fP(3X)
580 PAIR_NUMBER/\fBcurs_color\fP(3X)
581 add_wch/\fBcurs_add_wch\fP(3X)
582 add_wchnstr/\fBcurs_add_wchstr\fP(3X)
583 add_wchstr/\fBcurs_add_wchstr\fP(3X)
584 addch/\fBcurs_addch\fP(3X)
585 addchnstr/\fBcurs_addchstr\fP(3X)
586 addchstr/\fBcurs_addchstr\fP(3X)
587 addnstr/\fBcurs_addstr\fP(3X)
588 addnwstr/\fBcurs_addwstr\fP(3X)
589 addstr/\fBcurs_addstr\fP(3X)
590 addwstr/\fBcurs_addwstr\fP(3X)
591 alloc_pair/\fBnew_pair\fP(3X)*
592 assume_default_colors/\fBdefault_colors\fP(3X)*
593 attr_get/\fBcurs_attr\fP(3X)
594 attr_off/\fBcurs_attr\fP(3X)
595 attr_on/\fBcurs_attr\fP(3X)
596 attr_set/\fBcurs_attr\fP(3X)
597 attroff/\fBcurs_attr\fP(3X)
598 attron/\fBcurs_attr\fP(3X)
599 attrset/\fBcurs_attr\fP(3X)
600 baudrate/\fBcurs_termattrs\fP(3X)
601 beep/\fBcurs_beep\fP(3X)
602 bkgd/\fBcurs_bkgd\fP(3X)
603 bkgdset/\fBcurs_bkgd\fP(3X)
604 bkgrnd/\fBcurs_bkgrnd\fP(3X)
605 bkgrndset/\fBcurs_bkgrnd\fP(3X)
606 border/\fBcurs_border\fP(3X)
607 border_set/\fBcurs_border_set\fP(3X)
608 box/\fBcurs_border\fP(3X)
609 box_set/\fBcurs_border_set\fP(3X)
610 can_change_color/\fBcurs_color\fP(3X)
611 cbreak/\fBcurs_inopts\fP(3X)
612 chgat/\fBcurs_attr\fP(3X)
613 clear/\fBcurs_clear\fP(3X)
614 clearok/\fBcurs_outopts\fP(3X)
615 clrtobot/\fBcurs_clear\fP(3X)
616 clrtoeol/\fBcurs_clear\fP(3X)
617 color_content/\fBcurs_color\fP(3X)
618 color_set/\fBcurs_attr\fP(3X)
619 copywin/\fBcurs_overlay\fP(3X)
620 curs_set/\fBcurs_kernel\fP(3X)
621 curses_trace/\fBcurs_trace\fP(3X)*
622 curses_version/\fBcurs_extend\fP(3X)*
623 def_prog_mode/\fBcurs_kernel\fP(3X)
624 def_shell_mode/\fBcurs_kernel\fP(3X)
625 define_key/\fBdefine_key\fP(3X)*
626 del_curterm/\fBcurs_terminfo\fP(3X)
627 delay_output/\fBcurs_util\fP(3X)
628 delch/\fBcurs_delch\fP(3X)
629 deleteln/\fBcurs_deleteln\fP(3X)
630 delscreen/\fBcurs_initscr\fP(3X)
631 delwin/\fBcurs_window\fP(3X)
632 derwin/\fBcurs_window\fP(3X)
633 doupdate/\fBcurs_refresh\fP(3X)
634 dupwin/\fBcurs_window\fP(3X)
635 echo/\fBcurs_inopts\fP(3X)
636 echo_wchar/\fBcurs_add_wch\fP(3X)
637 echochar/\fBcurs_addch\fP(3X)
638 endwin/\fBcurs_initscr\fP(3X)
639 erase/\fBcurs_clear\fP(3X)
640 erasechar/\fBcurs_termattrs\fP(3X)
641 erasewchar/\fBcurs_termattrs\fP(3X)
642 exit_curses/\fBcurs_memleaks\fP(3X)*
643 exit_terminfo/\fBcurs_memleaks\fP(3X)*
644 extended_color_content/\fBcurs_color\fP(3X)*
645 extended_pair_content/\fBcurs_color\fP(3X)*
646 extended_slk_color/\fBcurs_slk\fP(3X)*
647 filter/\fBcurs_util\fP(3X)
648 find_pair/\fBnew_pair\fP(3X)*
649 flash/\fBcurs_beep\fP(3X)
650 flushinp/\fBcurs_util\fP(3X)
651 free_pair/\fBnew_pair\fP(3X)*
652 get_escdelay/\fBcurs_threads\fP(3X)*
653 get_wch/\fBcurs_get_wch\fP(3X)
654 get_wstr/\fBcurs_get_wstr\fP(3X)
655 getattrs/\fBcurs_attr\fP(3X)
656 getbegx/\fBcurs_legacy\fP(3X)*
657 getbegy/\fBcurs_legacy\fP(3X)*
658 getbegyx/\fBcurs_getyx\fP(3X)
659 getbkgd/\fBcurs_bkgd\fP(3X)
660 getbkgrnd/\fBcurs_bkgrnd\fP(3X)
661 getcchar/\fBcurs_getcchar\fP(3X)
662 getch/\fBcurs_getch\fP(3X)
663 getcurx/\fBcurs_legacy\fP(3X)*
664 getcury/\fBcurs_legacy\fP(3X)*
665 getmaxx/\fBcurs_legacy\fP(3X)*
666 getmaxy/\fBcurs_legacy\fP(3X)*
667 getmaxyx/\fBcurs_getyx\fP(3X)
668 getmouse/\fBcurs_mouse\fP(3X)*
669 getn_wstr/\fBcurs_get_wstr\fP(3X)
670 getnstr/\fBcurs_getstr\fP(3X)
671 getparx/\fBcurs_legacy\fP(3X)*
672 getpary/\fBcurs_legacy\fP(3X)*
673 getparyx/\fBcurs_getyx\fP(3X)
674 getstr/\fBcurs_getstr\fP(3X)
675 getsyx/\fBcurs_kernel\fP(3X)
676 getwin/\fBcurs_util\fP(3X)
677 getyx/\fBcurs_getyx\fP(3X)
678 halfdelay/\fBcurs_inopts\fP(3X)
679 has_colors/\fBcurs_color\fP(3X)
680 has_ic/\fBcurs_termattrs\fP(3X)
681 has_il/\fBcurs_termattrs\fP(3X)
682 has_key/\fBcurs_getch\fP(3X)*
683 has_mouse/\fBcurs_mouse\fP(3X)*
684 hline/\fBcurs_border\fP(3X)
685 hline_set/\fBcurs_border_set\fP(3X)
686 idcok/\fBcurs_outopts\fP(3X)
687 idlok/\fBcurs_outopts\fP(3X)
688 immedok/\fBcurs_outopts\fP(3X)
689 in_wch/\fBcurs_in_wch\fP(3X)
690 in_wchnstr/\fBcurs_in_wchstr\fP(3X)
691 in_wchstr/\fBcurs_in_wchstr\fP(3X)
692 inch/\fBcurs_inch\fP(3X)
693 inchnstr/\fBcurs_inchstr\fP(3X)
694 inchstr/\fBcurs_inchstr\fP(3X)
695 init_color/\fBcurs_color\fP(3X)
696 init_extended_color/\fBcurs_color\fP(3X)*
697 init_extended_pair/\fBcurs_color\fP(3X)*
698 init_pair/\fBcurs_color\fP(3X)
699 initscr/\fBcurs_initscr\fP(3X)
700 innstr/\fBcurs_instr\fP(3X)
701 innwstr/\fBcurs_inwstr\fP(3X)
702 ins_nwstr/\fBcurs_ins_wstr\fP(3X)
703 ins_wch/\fBcurs_ins_wch\fP(3X)
704 ins_wstr/\fBcurs_ins_wstr\fP(3X)
705 insch/\fBcurs_insch\fP(3X)
706 insdelln/\fBcurs_deleteln\fP(3X)
707 insertln/\fBcurs_deleteln\fP(3X)
708 insnstr/\fBcurs_insstr\fP(3X)
709 insstr/\fBcurs_insstr\fP(3X)
710 instr/\fBcurs_instr\fP(3X)
711 intrflush/\fBcurs_inopts\fP(3X)
712 inwstr/\fBcurs_inwstr\fP(3X)
713 is_cbreak/\fBcurs_inopts\fP(3X)*
714 is_cleared/\fBcurs_opaque\fP(3X)*
715 is_echo/\fBcurs_inopts\fP(3X)*
716 is_idcok/\fBcurs_opaque\fP(3X)*
717 is_idlok/\fBcurs_opaque\fP(3X)*
718 is_immedok/\fBcurs_opaque\fP(3X)*
719 is_keypad/\fBcurs_opaque\fP(3X)*
720 is_leaveok/\fBcurs_opaque\fP(3X)*
721 is_linetouched/\fBcurs_touch\fP(3X)
722 is_nl/\fBcurs_inopts\fP(3X)*
723 is_nodelay/\fBcurs_opaque\fP(3X)*
724 is_notimeout/\fBcurs_opaque\fP(3X)*
725 is_pad/\fBcurs_opaque\fP(3X)*
726 is_raw/\fBcurs_inopts\fP(3X)*
727 is_scrollok/\fBcurs_opaque\fP(3X)*
728 is_subwin/\fBcurs_opaque\fP(3X)*
729 is_syncok/\fBcurs_opaque\fP(3X)*
730 is_term_resized/\fBresizeterm\fP(3X)*
731 is_wintouched/\fBcurs_touch\fP(3X)
732 isendwin/\fBcurs_initscr\fP(3X)
733 key_defined/\fBkey_defined\fP(3X)*
734 key_name/\fBcurs_util\fP(3X)
735 keybound/\fBkeybound\fP(3X)*
736 keyname/\fBcurs_util\fP(3X)
737 keyok/\fBkeyok\fP(3X)*
738 keypad/\fBcurs_inopts\fP(3X)
739 killchar/\fBcurs_termattrs\fP(3X)
740 killwchar/\fBcurs_termattrs\fP(3X)
741 leaveok/\fBcurs_outopts\fP(3X)
742 longname/\fBcurs_termattrs\fP(3X)
743 mcprint/\fBcurs_print\fP(3X)*
744 meta/\fBcurs_inopts\fP(3X)
745 mouse_trafo/\fBcurs_mouse\fP(3X)*
746 mouseinterval/\fBcurs_mouse\fP(3X)*
747 mousemask/\fBcurs_mouse\fP(3X)*
748 move/\fBcurs_move\fP(3X)
749 mvadd_wch/\fBcurs_add_wch\fP(3X)
750 mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
751 mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
752 mvaddch/\fBcurs_addch\fP(3X)
753 mvaddchnstr/\fBcurs_addchstr\fP(3X)
754 mvaddchstr/\fBcurs_addchstr\fP(3X)
755 mvaddnstr/\fBcurs_addstr\fP(3X)
756 mvaddnwstr/\fBcurs_addwstr\fP(3X)
757 mvaddstr/\fBcurs_addstr\fP(3X)
758 mvaddwstr/\fBcurs_addwstr\fP(3X)
759 mvchgat/\fBcurs_attr\fP(3X)
760 mvcur/\fBcurs_kernel\fP(3X)
761 mvdelch/\fBcurs_delch\fP(3X)
762 mvderwin/\fBcurs_window\fP(3X)
763 mvget_wch/\fBcurs_get_wch\fP(3X)
764 mvget_wstr/\fBcurs_get_wstr\fP(3X)
765 mvgetch/\fBcurs_getch\fP(3X)
766 mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
767 mvgetnstr/\fBcurs_getstr\fP(3X)
768 mvgetstr/\fBcurs_getstr\fP(3X)
769 mvhline/\fBcurs_border\fP(3X)
770 mvhline_set/\fBcurs_border_set\fP(3X)
771 mvin_wch/\fBcurs_in_wch\fP(3X)
772 mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
773 mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
774 mvinch/\fBcurs_inch\fP(3X)
775 mvinchnstr/\fBcurs_inchstr\fP(3X)
776 mvinchstr/\fBcurs_inchstr\fP(3X)
777 mvinnstr/\fBcurs_instr\fP(3X)
778 mvinnwstr/\fBcurs_inwstr\fP(3X)
779 mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
780 mvins_wch/\fBcurs_ins_wch\fP(3X)
781 mvins_wstr/\fBcurs_ins_wstr\fP(3X)
782 mvinsch/\fBcurs_insch\fP(3X)
783 mvinsnstr/\fBcurs_insstr\fP(3X)
784 mvinsstr/\fBcurs_insstr\fP(3X)
785 mvinstr/\fBcurs_instr\fP(3X)
786 mvinwstr/\fBcurs_inwstr\fP(3X)
787 mvprintw/\fBcurs_printw\fP(3X)
788 mvscanw/\fBcurs_scanw\fP(3X)
789 mvvline/\fBcurs_border\fP(3X)
790 mvvline_set/\fBcurs_border_set\fP(3X)
791 mvwadd_wch/\fBcurs_add_wch\fP(3X)
792 mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
793 mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
794 mvwaddch/\fBcurs_addch\fP(3X)
795 mvwaddchnstr/\fBcurs_addchstr\fP(3X)
796 mvwaddchstr/\fBcurs_addchstr\fP(3X)
797 mvwaddnstr/\fBcurs_addstr\fP(3X)
798 mvwaddnwstr/\fBcurs_addwstr\fP(3X)
799 mvwaddstr/\fBcurs_addstr\fP(3X)
800 mvwaddwstr/\fBcurs_addwstr\fP(3X)
801 mvwchgat/\fBcurs_attr\fP(3X)
802 mvwdelch/\fBcurs_delch\fP(3X)
803 mvwget_wch/\fBcurs_get_wch\fP(3X)
804 mvwget_wstr/\fBcurs_get_wstr\fP(3X)
805 mvwgetch/\fBcurs_getch\fP(3X)
806 mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
807 mvwgetnstr/\fBcurs_getstr\fP(3X)
808 mvwgetstr/\fBcurs_getstr\fP(3X)
809 mvwhline/\fBcurs_border\fP(3X)
810 mvwhline_set/\fBcurs_border_set\fP(3X)
811 mvwin/\fBcurs_window\fP(3X)
812 mvwin_wch/\fBcurs_in_wch\fP(3X)
813 mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
814 mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
815 mvwinch/\fBcurs_inch\fP(3X)
816 mvwinchnstr/\fBcurs_inchstr\fP(3X)
817 mvwinchstr/\fBcurs_inchstr\fP(3X)
818 mvwinnstr/\fBcurs_instr\fP(3X)
819 mvwinnwstr/\fBcurs_inwstr\fP(3X)
820 mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
821 mvwins_wch/\fBcurs_ins_wch\fP(3X)
822 mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
823 mvwinsch/\fBcurs_insch\fP(3X)
824 mvwinsnstr/\fBcurs_insstr\fP(3X)
825 mvwinsstr/\fBcurs_insstr\fP(3X)
826 mvwinstr/\fBcurs_instr\fP(3X)
827 mvwinwstr/\fBcurs_inwstr\fP(3X)
828 mvwprintw/\fBcurs_printw\fP(3X)
829 mvwscanw/\fBcurs_scanw\fP(3X)
830 mvwvline/\fBcurs_border\fP(3X)
831 mvwvline_set/\fBcurs_border_set\fP(3X)
832 napms/\fBcurs_kernel\fP(3X)
833 newpad/\fBcurs_pad\fP(3X)
834 newterm/\fBcurs_initscr\fP(3X)
835 newwin/\fBcurs_window\fP(3X)
836 nl/\fBcurs_inopts\fP(3X)
837 nocbreak/\fBcurs_inopts\fP(3X)
838 nodelay/\fBcurs_inopts\fP(3X)
839 noecho/\fBcurs_inopts\fP(3X)
840 nofilter/\fBcurs_util\fP(3X)*
841 nonl/\fBcurs_inopts\fP(3X)
842 noqiflush/\fBcurs_inopts\fP(3X)
843 noraw/\fBcurs_inopts\fP(3X)
844 notimeout/\fBcurs_inopts\fP(3X)
845 overlay/\fBcurs_overlay\fP(3X)
846 overwrite/\fBcurs_overlay\fP(3X)
847 pair_content/\fBcurs_color\fP(3X)
848 pecho_wchar/\fBcurs_pad\fP(3X)
849 pechochar/\fBcurs_pad\fP(3X)
850 pnoutrefresh/\fBcurs_pad\fP(3X)
851 prefresh/\fBcurs_pad\fP(3X)
852 printw/\fBcurs_printw\fP(3X)
853 putp/\fBcurs_terminfo\fP(3X)
854 putwin/\fBcurs_util\fP(3X)
855 qiflush/\fBcurs_inopts\fP(3X)
856 raw/\fBcurs_inopts\fP(3X)
857 redrawwin/\fBcurs_refresh\fP(3X)
858 refresh/\fBcurs_refresh\fP(3X)
859 reset_color_pairs/\fBcurs_color\fP(3X)*
860 reset_prog_mode/\fBcurs_kernel\fP(3X)
861 reset_shell_mode/\fBcurs_kernel\fP(3X)
862 resetty/\fBcurs_kernel\fP(3X)
863 resize_term/\fBresizeterm\fP(3X)*
864 resizeterm/\fBresizeterm\fP(3X)*
865 restartterm/\fBcurs_terminfo\fP(3X)
866 ripoffline/\fBcurs_kernel\fP(3X)
867 savetty/\fBcurs_kernel\fP(3X)
868 scanw/\fBcurs_scanw\fP(3X)
869 scr_dump/\fBcurs_scr_dump\fP(3X)
870 scr_init/\fBcurs_scr_dump\fP(3X)
871 scr_restore/\fBcurs_scr_dump\fP(3X)
872 scr_set/\fBcurs_scr_dump\fP(3X)
873 scrl/\fBcurs_scroll\fP(3X)
874 scroll/\fBcurs_scroll\fP(3X)
875 scrollok/\fBcurs_outopts\fP(3X)
876 set_curterm/\fBcurs_terminfo\fP(3X)
877 set_escdelay/\fBcurs_threads\fP(3X)*
878 set_tabsize/\fBcurs_threads\fP(3X)*
879 set_term/\fBcurs_initscr\fP(3X)
880 setcchar/\fBcurs_getcchar\fP(3X)
881 setscrreg/\fBcurs_outopts\fP(3X)
882 setsyx/\fBcurs_kernel\fP(3X)
883 setupterm/\fBcurs_terminfo\fP(3X)
884 slk_attr/\fBcurs_slk\fP(3X)*
885 slk_attr_off/\fBcurs_slk\fP(3X)
886 slk_attr_on/\fBcurs_slk\fP(3X)
887 slk_attr_set/\fBcurs_slk\fP(3X)
888 slk_attroff/\fBcurs_slk\fP(3X)
889 slk_attron/\fBcurs_slk\fP(3X)
890 slk_attrset/\fBcurs_slk\fP(3X)
891 slk_clear/\fBcurs_slk\fP(3X)
892 slk_color/\fBcurs_slk\fP(3X)
893 slk_init/\fBcurs_slk\fP(3X)
894 slk_label/\fBcurs_slk\fP(3X)
895 slk_noutrefresh/\fBcurs_slk\fP(3X)
896 slk_refresh/\fBcurs_slk\fP(3X)
897 slk_restore/\fBcurs_slk\fP(3X)
898 slk_set/\fBcurs_slk\fP(3X)
899 slk_touch/\fBcurs_slk\fP(3X)
900 slk_wset/\fBcurs_slk\fP(3X)
901 standend/\fBcurs_attr\fP(3X)
902 standout/\fBcurs_attr\fP(3X)
903 start_color/\fBcurs_color\fP(3X)
904 subpad/\fBcurs_pad\fP(3X)
905 subwin/\fBcurs_window\fP(3X)
906 syncok/\fBcurs_window\fP(3X)
907 term_attrs/\fBcurs_termattrs\fP(3X)
908 termattrs/\fBcurs_termattrs\fP(3X)
909 termname/\fBcurs_termattrs\fP(3X)
910 tgetent/\fBcurs_termcap\fP(3X)
911 tgetflag/\fBcurs_termcap\fP(3X)
912 tgetnum/\fBcurs_termcap\fP(3X)
913 tgetstr/\fBcurs_termcap\fP(3X)
914 tgoto/\fBcurs_termcap\fP(3X)
915 tigetflag/\fBcurs_terminfo\fP(3X)
916 tigetnum/\fBcurs_terminfo\fP(3X)
917 tigetstr/\fBcurs_terminfo\fP(3X)
918 timeout/\fBcurs_inopts\fP(3X)
919 tiparm/\fBcurs_terminfo\fP(3X)
920 tiparm_s/\fBcurs_terminfo\fP(3X)*
921 tiscan_s/\fBcurs_terminfo\fP(3X)*
922 touchline/\fBcurs_touch\fP(3X)
923 touchwin/\fBcurs_touch\fP(3X)
924 tparm/\fBcurs_terminfo\fP(3X)
925 tputs/\fBcurs_termcap\fP(3X)
926 tputs/\fBcurs_terminfo\fP(3X)
927 trace/\fBcurs_trace\fP(3X)*
928 typeahead/\fBcurs_inopts\fP(3X)
929 unctrl/\fBcurs_util\fP(3X)
930 unget_wch/\fBcurs_get_wch\fP(3X)
931 ungetch/\fBcurs_getch\fP(3X)
932 ungetmouse/\fBcurs_mouse\fP(3X)*
933 untouchwin/\fBcurs_touch\fP(3X)
934 use_default_colors/\fBdefault_colors\fP(3X)*
935 use_env/\fBcurs_util\fP(3X)
936 use_extended_names/\fBcurs_extend\fP(3X)*
937 use_legacy_coding/\fBlegacy_coding\fP(3X)*
938 use_screen/\fBcurs_threads\fP(3X)*
939 use_tioctl/\fBcurs_util\fP(3X)*
940 use_window/\fBcurs_threads\fP(3X)*
941 vid_attr/\fBcurs_terminfo\fP(3X)
942 vid_puts/\fBcurs_terminfo\fP(3X)
943 vidattr/\fBcurs_terminfo\fP(3X)
944 vidputs/\fBcurs_terminfo\fP(3X)
945 vline/\fBcurs_border\fP(3X)
946 vline_set/\fBcurs_border_set\fP(3X)
947 vw_printw/\fBcurs_printw\fP(3X)
948 vw_scanw/\fBcurs_scanw\fP(3X)
949 vwprintw/\fBcurs_printw\fP(3X)
950 vwscanw/\fBcurs_scanw\fP(3X)
951 wadd_wch/\fBcurs_add_wch\fP(3X)
952 wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
953 wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
954 waddch/\fBcurs_addch\fP(3X)
955 waddchnstr/\fBcurs_addchstr\fP(3X)
956 waddchstr/\fBcurs_addchstr\fP(3X)
957 waddnstr/\fBcurs_addstr\fP(3X)
958 waddnwstr/\fBcurs_addwstr\fP(3X)
959 waddstr/\fBcurs_addstr\fP(3X)
960 waddwstr/\fBcurs_addwstr\fP(3X)
961 wattr_get/\fBcurs_attr\fP(3X)
962 wattr_off/\fBcurs_attr\fP(3X)
963 wattr_on/\fBcurs_attr\fP(3X)
964 wattr_set/\fBcurs_attr\fP(3X)
965 wattroff/\fBcurs_attr\fP(3X)
966 wattron/\fBcurs_attr\fP(3X)
967 wattrset/\fBcurs_attr\fP(3X)
968 wbkgd/\fBcurs_bkgd\fP(3X)
969 wbkgdset/\fBcurs_bkgd\fP(3X)
970 wbkgrnd/\fBcurs_bkgrnd\fP(3X)
971 wbkgrndset/\fBcurs_bkgrnd\fP(3X)
972 wborder/\fBcurs_border\fP(3X)
973 wborder_set/\fBcurs_border_set\fP(3X)
974 wchgat/\fBcurs_attr\fP(3X)
975 wclear/\fBcurs_clear\fP(3X)
976 wclrtobot/\fBcurs_clear\fP(3X)
977 wclrtoeol/\fBcurs_clear\fP(3X)
978 wcolor_set/\fBcurs_attr\fP(3X)
979 wcursyncup/\fBcurs_window\fP(3X)
980 wdelch/\fBcurs_delch\fP(3X)
981 wdeleteln/\fBcurs_deleteln\fP(3X)
982 wecho_wchar/\fBcurs_add_wch\fP(3X)
983 wechochar/\fBcurs_addch\fP(3X)
984 wenclose/\fBcurs_mouse\fP(3X)*
985 werase/\fBcurs_clear\fP(3X)
986 wget_wch/\fBcurs_get_wch\fP(3X)
987 wget_wstr/\fBcurs_get_wstr\fP(3X)
988 wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
989 wgetch/\fBcurs_getch\fP(3X)
990 wgetdelay/\fBcurs_opaque\fP(3X)*
991 wgetn_wstr/\fBcurs_get_wstr\fP(3X)
992 wgetnstr/\fBcurs_getstr\fP(3X)
993 wgetparent/\fBcurs_opaque\fP(3X)*
994 wgetscrreg/\fBcurs_opaque\fP(3X)*
995 wgetstr/\fBcurs_getstr\fP(3X)
996 whline/\fBcurs_border\fP(3X)
997 whline_set/\fBcurs_border_set\fP(3X)
998 win_wch/\fBcurs_in_wch\fP(3X)
999 win_wchnstr/\fBcurs_in_wchstr\fP(3X)
1000 win_wchstr/\fBcurs_in_wchstr\fP(3X)
1001 winch/\fBcurs_inch\fP(3X)
1002 winchnstr/\fBcurs_inchstr\fP(3X)
1003 winchstr/\fBcurs_inchstr\fP(3X)
1004 winnstr/\fBcurs_instr\fP(3X)
1005 winnwstr/\fBcurs_inwstr\fP(3X)
1006 wins_nwstr/\fBcurs_ins_wstr\fP(3X)
1007 wins_wch/\fBcurs_ins_wch\fP(3X)
1008 wins_wstr/\fBcurs_ins_wstr\fP(3X)
1009 winsch/\fBcurs_insch\fP(3X)
1010 winsdelln/\fBcurs_deleteln\fP(3X)
1011 winsertln/\fBcurs_deleteln\fP(3X)
1012 winsnstr/\fBcurs_insstr\fP(3X)
1013 winsstr/\fBcurs_insstr\fP(3X)
1014 winstr/\fBcurs_instr\fP(3X)
1015 winwstr/\fBcurs_inwstr\fP(3X)
1016 wmouse_trafo/\fBcurs_mouse\fP(3X)*
1017 wmove/\fBcurs_move\fP(3X)
1018 wnoutrefresh/\fBcurs_refresh\fP(3X)
1019 wprintw/\fBcurs_printw\fP(3X)
1020 wredrawln/\fBcurs_refresh\fP(3X)
1021 wrefresh/\fBcurs_refresh\fP(3X)
1022 wresize/\fBwresize\fP(3X)*
1023 wscanw/\fBcurs_scanw\fP(3X)
1024 wscrl/\fBcurs_scroll\fP(3X)
1025 wsetscrreg/\fBcurs_outopts\fP(3X)
1026 wstandend/\fBcurs_attr\fP(3X)
1027 wstandout/\fBcurs_attr\fP(3X)
1028 wsyncdown/\fBcurs_window\fP(3X)
1029 wsyncup/\fBcurs_window\fP(3X)
1030 wtimeout/\fBcurs_inopts\fP(3X)
1031 wtouchln/\fBcurs_touch\fP(3X)
1032 wunctrl/\fBcurs_util\fP(3X)
1033 wvline/\fBcurs_border\fP(3X)
1034 wvline_set/\fBcurs_border_set\fP(3X)
1038 .I "screen-pointer extension"
1039 adds additional functions corresponding to many of the above,
1040 each with an \*(``_sp\*('' suffix;
1041 see \fBcurs_sp_funcs\fP(3X).
1043 The availability of some extensions is configurable when
1046 see sections \*(``ALTERNATE CONFIGURATIONS\*('' and \*(``EXTENSIONS\*(''
1049 Unless otherwise noted,
1050 functions that return integers return the constants
1055 see \fB\%curs_variables\fP(3X).
1056 Functions that return pointers return
1061 treats a null pointer passed as a function parameter as a failure.
1062 Functions prefixed with \*(``mv\*('' first perform cursor movement and
1063 fail if the position
1066 is outside the window boundaries.
1068 The following symbols from the process environment customize the
1072 The library may be configured to disregard the variables
1074 .IR \%TERMINFO_DIRS ,
1078 if the user is the superuser (root),
1079 or the application uses \fI\%setuid\fP(2) or \fI\%setgid\fP(2).
1080 .SS "\fIBAUDRATE\fP"
1081 The debugging library checks this variable when the application has
1082 redirected output to a file.
1083 Its integral value is used for the baud rate.
1084 If that value is absent or invalid,
1087 This feature allows developers to construct repeatable test cases
1088 that take into account optimization decisions that depend on baud rate.
1089 .SS "\fICC\fP (command character)"
1092 .B \%command_character
1094 capability value of loaded
1096 entries changes to the value of this variable.
1099 entries provide this feature.
1101 Because this name is also used in development environments to store the
1104 ignores its value if it is not one character in length.
1106 This variable specifies the width of the screen in characters.
1107 Applications running in a windowing environment usually are able to
1108 obtain the width of the window in which they are executing.
1111 is not defined and the terminal's screen size is not available from the
1114 uses the size specified by the
1117 capability of the terminal type's entry in the
1122 It is important that your application use the correct screen size.
1123 Automatic detection thereof is not always possible because an
1124 application may be running on a host that does not honor NAWS
1125 (Negotiations About Window Size)
1126 or as a different user ID than the owner of the terminal device file.
1131 overrides the library's use of the screen size obtained from the
1138 variables may be specified independently.
1140 enforces an upper limit of 512 on each when reading the value.
1141 This property is useful to circumvent misfeatures of legacy terminal
1143 \fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
1151 descriptions of terminal emulators.
1153 \fBuse_env\fP(3X) can disable use of the process environment
1154 in determining the screen size.
1155 \fBuse_tioctl\fP(3X) can update
1159 to match the screen size obtained from system calls or the terminal
1161 .SS "\fIESCDELAY\fP"
1164 to distinguish the ESC character resulting from a user's press of the
1165 \*(``Escape\*('' key on the input device from one beginning an
1166 .I "escape sequence"
1167 (as commonly produced by function keys),
1168 it waits after receiving the escape character to see if further
1169 characters are available on the input stream within a short interval.
1172 stores this interval in milliseconds.
1173 The default value of 1000
1175 is adequate for most uses.
1176 This environment variable overrides it;
1178 enforces an upper limit of 30,000
1180 when reading the value.
1182 The most common instance where you may wish to change this value
1183 is to work with a remote host over a slow communication channel.
1184 If the host running a
1186 application does not receive the characters of an escape sequence in a
1188 the library can interpret them as multiple key stroke events.
1190 \fI\%xterm\fP(1) mouse events are a form of escape sequence;
1192 if your application makes heavy use of multiple-clicking,
1193 you may wish to lengthen the default value because the delay applies
1194 to the composite multi-click event as well as the individual clicks.
1196 Portable applications should not rely upon the presence of
1199 but setting the environment variable rather than the global variable
1200 does not create problems when compiling an application.
1202 If \fB\%keypad\fP(3X) is disabled for the
1204 window receiving input,
1205 a program must disambiguate escape sequences itself.
1208 may read and write auxiliary terminal descriptions in
1212 files in the user's home directory.
1216 specifies the height of the screen in characters.
1219 capability and code is
1221 See the description of the
1224 .SS "\fIMOUSE_BUTTONS_123\fP"
1225 (OS/2 EMX port only)
1226 OS/2 numbers a three-button mouse inconsistently with other platforms,
1227 such that 1 is the left button,
1230 This variable customizes the mouse button numbering.
1231 Its value must be three digits 1\-3 in any order.
1234 assumes a numbering of \*(``132\*(''.
1235 .SS "\fINCURSES_ASSUMED_COLORS\fP"
1237 this variable overrides the
1239 library's compiled-in assumption that the terminal's default colors are
1241 see \fB\%default_colors\fP(3X).
1242 Set the foreground and background color values with this environment
1243 variable by assigning it two integer values separated by a comma,
1244 indicating foregound and background color numbers,
1250 not to assume anything about the colors,
1251 use a value of \*(``\-1,\-1\*(''.
1252 To make the default color scheme green on black,
1255 accepts integral values from \-1 up to the value of the
1260 .SS "\fINCURSES_CONSOLE2\fP"
1264 .\" https://www.hanselman.com/blog/console2-a-better-windows-command-prompt
1265 program defectively handles the Microsoft Console API call
1266 .IR \%Create\%Console\%Screen\%Buffer .
1267 Applications that use it will hang.
1269 it is possible to simulate the action of this call by mapping
1271 explicitly saving and restoring the original screen contents.
1272 Setting the environment variable
1274 has the same effect.
1275 .SS "\fINCURSES_GPM_TERMS\fP"
1279 is configured to use the GPM interface,
1280 this variable may list one or more terminal type names,
1281 delimited by vertical bars
1290 An empty value disables the GPM interface,
1293 built-in support for \fI\%xterm\fP(1) mouse protocols instead.
1294 If the variable is absent,
1296 attempts to open GPM if
1298 contains \*(``linux\*(''.
1299 .SS "\fINCURSES_NO_HARD_TABS\fP"
1301 may use tab characters in cursor movement optimization.
1303 your terminal driver may not handle them properly.
1304 Set this environment variable to any value to disable the feature.
1305 You can also adjust your \fI\%stty\fP(1) settings to avoid the problem.
1306 .SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
1307 Many terminals store video attributes as a property of a character cell,
1312 some recorded changes in video attributes as data that logically
1314 character cells on the display,
1315 switching attributes on or off,
1316 similarly to tags in a markup language;
1317 these are termed \*(``magic cookies\*('',
1318 and must be subsequently overprinted.
1321 entry for your terminal type does not adequately describe its handling
1323 set this variable to any value to instruct
1325 to disable attributes entirely.
1326 .SS "\fINCURSES_NO_PADDING\fP"
1327 Most terminal type descriptions in the
1329 database detail hardware devices.
1332 applications in terminal emulator programs that run in a windowing
1334 These programs can duplicate all of the important features of a hardware
1336 but often lack their limitations.
1337 Chief among these absent drawbacks is the problem of data flow
1340 limiting the speed of communication to what the hardware could handle.
1341 Unless a hardware terminal is interfaced into a terminal concentrator
1342 (which does flow control),
1343 an application must manage flow itself to prevent overruns and data
1346 A solution that comes at no hardware cost is for an application to pause
1347 after directing a terminal to execute an operation that it performs
1349 such as clearing the display.
1350 Many terminal type descriptions,
1351 including that for the VT100,
1352 embed delay specifications in capabilities.
1353 You may wish to use these terminal descriptions without paying the
1354 performance penalty.
1356 .I \%NCURSES_NO_PADDING
1357 to any value to disable all but mandatory padding.
1358 Mandatory padding is used by such terminal capabilities as
1361 .SS "\fINCURSES_NO_SETBUF\fP"
1363 Prior to internal changes developed in
1366 (patches 20120825 through 20130126),
1367 the library used \fI\%setbuf\fP(3) to enable fully buffered output when
1368 initializing the terminal.
1372 to increase performance.
1373 For testing purposes,
1376 and of certain applications,
1377 this feature was made optional.
1378 Setting this variable disabled output buffering,
1379 leaving the output stream in the original
1380 (usually line-buffered)
1385 performs its own buffering and does not require this workaround;
1386 it does not modify the buffering of the standard output stream.
1387 This approach makes signal handling,
1390 A drawback is that certain unconventional programs mixed
1391 \fI\%stdio\fP(3) calls with
1394 got the behavior they expected.
1395 This is no longer the case;
1397 does not write to the standard output file descriptor through a
1402 low-level API calls such as \fB\%putp\fP(3X) still use the
1403 standard output stream.
1406 calls such as \fB\%printw\fP(3X) do not.
1407 .SS "\fINCURSES_NO_UTF8_ACS\fP"
1412 environment variable for special cases where VT100 forms-drawing
1414 (and the corresponding alternate character set
1417 are known to be unsupported by terminal types that otherwise claim VT100
1420 when running in a UTF-8 locale,
1421 the Linux virtual console device and the GNU \fI\%screen\fP(1)
1422 program ignore them.
1423 Set this variable to a nonzero value to instruct
1425 that the terminal's ACS support is broken;
1426 the library then outputs Unicode code points that correspond to the
1431 to disable the special check for terminal type names matching
1432 \*(``linux\*('' or \*(``screen\*('',
1435 to assume that the ACS feature works if the terminal type description
1438 As an alternative to use of this variable,
1440 checks for an extended
1442 numeric capability \fBU8\fP
1443 that can be compiled using
1444 .RB \*(`` "@TIC@ \-x" \*(''.
1449 # linux console, if patched to provide working
1450 # VT100 shift\-in/shift\-out, with corresponding font.
1451 linux\-vt100|linux console with VT100 line\-graphics,
1454 # uxterm with vt100Graphics resource set to false
1455 xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
1460 The two-character name \*(``U8\*('' was chosen to permit its use via
1464 .SS "\fINCURSES_TRACE\fP"
1467 (in its debugging configuration)
1468 checks for this variable's presence.
1469 If defined with an integral value,
1470 the library calls \fB\%curses_trace\fP(3X) with that value as the
1475 variable denotes the terminal type.
1477 though many are similar.
1478 It is commonly set by terminal emulators to help applications find a
1479 workable terminal description.
1480 Some choose a popular approximation such as \*(``ansi\*('',
1481 \*(``vt100\*('', or \*(``xterm\*('' rather than an exact fit to their
1484 an application will have problems with that approach;
1486 a key stroke may not operate correctly,
1487 or produce no effect but seeming garbage characters on the screen.
1491 has no effect on hardware operation;
1492 it affects the way applications communicate with the terminal.
1495 (\fIxterm\fP(1) being a rare exception),
1496 terminal emulators that allow you to specify
1498 as a parameter or configuration value do not change their behavior to
1506 it checks for a terminal type description in
1510 format is not available.
1511 Setting this variable directs
1516 .IR \%/etc/termcap ;
1521 should contain either a terminal description
1522 (with newlines stripped out),
1523 or a file name indicating where the information required by the
1525 environment variable is stored.
1526 .SS "\fITERMINFO\fP"
1528 can be configured to read terminal type description databases in various
1529 locations using different formats.
1530 This variable overrides the default location.
1534 format are normally stored in a directory tree using subdirectories
1535 named by the common first letters of the terminal types named therein.
1536 This is the scheme used in System\ V.
1540 is configured to use hashed databases,
1543 may name its location,
1545 .IR \%/usr/share/terminfo.db ,
1547 .IR \%/usr/share/terminfo/ .
1549 The hashed database uses less disk space and is a little faster than the
1552 some applications assume the existence of the directory tree,
1553 and read it directly
1554 rather than using the
1563 this variable may contain the location of a
1569 begins with \*(``hex:\*('' or \*(``b64:\*('',
1571 uses the remainder of the value as a compiled
1574 You might produce the base64 format using \fB\%infocmp\fP(1M).
1578 TERMINFO=$(infocmp \-0 \-Q2 \-q)
1583 The compiled description is used only if it corresponds to the terminal
1593 to a terminal database.
1594 The search path is as follows.
1596 the last terminal database to which the running
1601 the location specified by the
1603 environment variable
1607 locations listed in the
1609 environment variable
1611 .if !'@TERMINFO_DIRS@'no default value' .as td @TERMINFO_DIRS@
1612 .if !'@TERMINFO@\*(td'' \{\
1614 location(s) configured and compiled into
1619 .I \%@TERMINFO_DIRS@
1621 .if !'@TERMINFO'' .if !'\*(td'@TERMINFO@' \{\
1627 .SS "\fITERMINFO_DIRS\fP"
1628 This variable specifies a list of locations,
1633 searches for the terminal type descriptions described by
1636 The list items are separated by colons on Unix
1637 and semicolons on OS/2 EMX.
1640 lacks a corresponding feature;
1645 .SS "\fITERMPATH\fP"
1648 does not hold a terminal type description or file name,
1651 checks the contents of
1653 a list of locations,
1656 in which it searches for
1658 terminal type descriptions.
1659 The list items are separated by colons on Unix
1660 and semicolons on OS/2 EMX.
1666 are unset or invalid,
1668 searches for the files
1669 .IR \%/etc/termcap ,
1670 .IR \%/usr/share/misc/termcap ,
1672 .IR \%$HOME/.termcap ,
1674 .SH "ALTERNATE CONFIGURATIONS"
1677 configurations are possible,
1678 determined by the options given to the
1680 script when building the library.
1681 Run the script with the
1683 option to peruse them all.
1684 A few are of particular significance to the application developer
1688 .B \-\-disable\-overwrite
1689 The standard C preprocessor inclusion for the
1691 library is as follows.
1696 .\" The dummy character prevents undesired rewriting of the next line on
1697 .\" installation of the man page.
1698 \fB#\&include <curses.h>\fP
1702 This option is used to avoid file name conflicts between
1706 installation on the system.
1709 is installed disabling overwrite,
1710 it puts its header files in a subdirectory.
1715 .\" The dummy character prevents undesired rewriting of the next line on
1716 .\" installation of the man page.
1717 \fB#\&include <ncurses/curses.h>\fP
1721 Installation also omits a symbolic link that would cause the compiler's
1723 option to link object files with
1725 instead of the system
1729 The directory used by this configuration of
1731 is shown in section \*(``SYNOPSIS\*('' above.
1734 .B \-\-enable\-widec
1735 The configure script renames the library and
1736 (if the \fB\-\-disable\-overwrite\fP option is used)
1737 puts the header files in a different subdirectory.
1738 All of the library names have a \*(``w\*('' appended to them,
1756 You must also enable the wide-character features in the header file
1757 when compiling for the wide-character library
1758 to use the extended (wide-character) functions.
1759 The symbol which enables these features has changed
1760 since X/Open Curses, Issue 4:
1762 Originally, the wide-character feature required the symbol
1763 \fB_XOPEN_SOURCE_EXTENDED\fP
1764 but that was only valid for XPG4 (1996).
1766 Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
1769 none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
1770 feature greater than 600.
1771 However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1773 Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
1774 with the caveat that some other header file than \fBcurses.h\fP
1775 may require a specific value for \fB_XOPEN_SOURCE\fP
1776 (or a system-specific symbol).
1778 The \fI\%curses.h\fP header file installed for the wide-character
1779 library is designed to be compatible with the non-wide library's header.
1780 Only the size of the \fI\%WINDOW\fP structure differs;
1781 few applications require more than pointers to \fI\%WINDOW\fPs.
1783 If the headers are installed allowing overwrite,
1784 the wide-character library's headers should be installed last,
1785 to allow applications to be built using either library
1786 from the same set of headers.
1789 .B \-\-with\-pthread
1790 The configure script renames the library.
1791 All of the library names have a \*(``t\*('' appended to them
1792 (before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
1794 The global variables such as \fBLINES\fP are replaced by macros to
1795 allow read-only access.
1796 At the same time, setter-functions are provided to set these values.
1797 Some applications (very few) may require changes to work with this convention.
1805 .B \-\-with\-profile
1806 The shared and normal (static) library names differ by their suffixes,
1807 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1808 The debug and profiling libraries add a \*(``_g\*(''
1809 and a \*(``_p\*('' to the root names respectively,
1810 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1812 .B \-\-with\-termlib
1813 Low-level functions which do not depend upon whether the library
1814 supports wide-characters, are provided in the tinfo library.
1816 By doing this, it is possible to share the tinfo library between
1817 wide/normal configurations as well as reduce the size of the library
1818 when only low-level functions are needed.
1820 Those functions are described in these pages:
1823 \fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
1825 \fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
1827 \fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
1829 \fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
1831 \fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
1833 \fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
1836 \fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
1840 The \fBtrace\fP function normally resides in the debug library,
1841 but it is sometimes useful to configure this in the shared library.
1842 Configure scripts should check for the function's existence rather
1843 than assuming it is always in the debug library.
1847 tab stop initialization database
1850 compiled terminal capability database
1852 X/Open Curses permits most functions it specifies to be made available
1854 .\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
1855 .\" See X/Open Curses Issue 7, pp. 311-318.
1856 \fI\%ncurses\fP does so
1858 for functions that return values via their parameters,
1860 to support obsolete features,
1864 those that move the cursor before another operation),
1867 in a few special cases.
1869 If the standard output file descriptor of an
1871 program is redirected to something that is not a terminal device,
1872 the library writes screen updates to the standard error file descriptor.
1873 This was an undocumented feature of SVr3
1876 See subsection \*(``Header Files\*('' below regarding symbols exposed by
1877 inclusion of \fI\%curses.h\fP.
1880 enables an application to capture mouse events on certain terminals,
1881 including \fI\%xterm\fP(1);
1882 see \fB\%curs_mouse\fP(3X).
1885 provides a means of responding to window resizing events,
1886 as when running in a GUI terminal emulator application such as
1888 see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
1891 allows an application to query the terminal for the presence of a wide
1892 variety of special keys;
1893 see \fB\%has_key\fP(3X).
1896 extends the fixed set of function key capabilities specified by X/Open
1897 Curses by allowing the application programmer to define additional key
1900 \fB\%define_key\fP(3X),
1901 \fB\%key_defined\fP(3X),
1902 \fB\%keybound\fP(3X),
1907 can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
1908 SGR\ 39 and SGR\ 49 sequences,
1909 which allow an application to reset the terminal to its original
1910 foreground and background colors.
1911 From a user's perspective,
1912 the application is able to draw colored text on a background whose color
1913 is set independently,
1914 providing better control over color contrasts.
1915 See \fB\%default_colors\fP(3X).
1919 application can eschew knowledge of
1921 structure internals,
1922 instead using accessor functions such as
1923 \fB\%is_scrollok\fP(3X).
1926 enables an application to direct its output to a printer attached to the
1928 see \fB\%curs_print\fP(3X).
1931 offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
1932 soft-label key lines,
1933 and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
1934 that can gather color information from them when many colors are
1938 permits modification of \fB\%unctrl\fP(3X)'s behavior;
1939 see \fB\%use_legacy_coding\fP(3X).
1941 Rudimentary support for multi-threaded applications may be available;
1942 see \fBcurs_threads\fP(3X).
1944 Functions that ease the management of multiple screens can be exposed;
1945 see \fBcurs_sp_funcs\fP(3X).
1947 To aid applications to debug their memory usage,
1949 optionally offers functions to more aggressively free memory it
1950 dynamically allocates itself;
1951 see \fBcurs_memleaks\fP(3X).
1953 The library facilitates auditing and troubleshooting of its behavior;
1954 see \fBcurs_trace\fP(3X).
1960 causes it to fall back to reading
1962 if the terminal setup code cannot find a
1964 entry corresponding to
1966 Use of this feature is not recommended,
1967 as it essentially includes an entire
1972 at a cost in memory usage and application launch latency.
1980 Individual man pages indicate where this is the case.
1982 X/Open Curses defines two levels of conformance,
1983 \*(``base\*('' and \*(``enhanced\*(''.
1984 The latter includes several additional features,
1985 such as wide-character and color support.
1987 intends base-level conformance with X/Open Curses,
1988 and supports all features of its enhanced level
1989 except the \fB\%untic\fP utility.
1991 Differences between X/Open Curses and
1993 are documented in the \*(``PORTABILITY\*('' sections of applicable man
1995 .SS "Error Checking"
1996 In many cases, X/Open Curses is vague about error conditions,
1997 omitting some of the SVr4 documentation.
1999 Unlike other implementations,
2001 checks pointer parameters,
2005 to ensure that they are not null.
2006 This is done primarily to guard against programmer error.
2007 The standard interface does not provide a way for the library
2008 to tell an application which of several possible errors occurred.
2009 An application that relies on
2011 to check its function parameters for validity limits its portability and
2013 .SS "Padding Differences"
2017 delays embedded in the
2020 .B \%carriage_return
2031 activated corresponding delay bits in the Unix terminal driver.
2033 performs all padding by sending NUL bytes to the device.
2034 This method is slightly more expensive,
2035 but narrows the interface to the Unix kernel significantly and
2036 correspondingly increases the package's portability.
2040 itself includes the header files
2045 X/Open Curses has more to say,
2050 may make visible all symbols from the headers
2058 but does not finish the story.
2059 A more complete account follows.
2074 from an internal header file
2077 \*(``ext\*('' abbreviated \*(``externs\*(''.
2079 The implementations of
2083 used undocumented internal functions of the standard I/O library
2098 because its function prototype employs the
2111 X/Open Curses specifies all three of these functions.
2115 and X/Open Curses do not require the developer to include
2119 Both document use of
2130 X/Open Curses and SVr4
2132 are inconsistent with respect to
2135 As noted in \fBcurs_util\fP(3X),
2143 X/Open Curses's comments about
2147 may refer to HP-UX and AIX.
2177 X/Open Curses says that
2182 but does not require it to do so.
2184 Some programs use functions declared in both
2188 and must include both header files in the same module.
2189 Very old versions of AIX
2191 required inclusion of
2196 The header files supplied by
2198 include the standard library headers required for its declarations,
2201 own header files can be included in any order.
2202 But for portability,
2208 X/Open Curses says \*(``may make visible\*('' because including a header
2209 file does not necessarily make visible all of the symbols in it
2217 .B may \" bold to contrast with preceding italic
2220 if the proper symbol is defined,
2223 is configured for wide-character support.
2228 .B may \" bold for consistency in this paragraph
2229 be made visible depending on the value of the
2233 X/Open Curses mandates an application's inclusion of one standard C
2234 library header in a special case:
2238 to prototype the functions
2242 (as well as the obsolete
2246 Each of these takes a variadic argument list,
2250 like that of \fI\%printf\fP(3).
2255 the two obsolete functions,
2256 and X/Open Curses the others.
2260 provided for the possibility that an application might include either
2264 These represented contrasting approaches to handling variadic
2266 The older interface,
2269 .I char \" V7, 32V, System III, 3BSD
2270 for variadic functions'
2274 the list acquired its own standard data type,
2278 empowering the compiler to check the types of a function call's actual
2279 parameters against the formal ones declared in its prototype.
2281 No conforming implementations of X/Open Curses require an application
2286 because they either have allowed for a special type,
2292 themselves to provide a portable interface.
2301 \fB\%curs_variables\fP(3X),
2302 \fB\%terminfo\fP(5),
2303 \fB\%user_caps\fP(5)