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.204 2024/03/23 20:42:29 tom Exp $
32 .TH ncurses 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
52 character-cell terminal interface with optimized output
55 \fB#include <curses.h>
58 The \*(``new curses\*('' library offers the programmer a
59 terminal-independent means of reading keyboard and mouse input and
60 updating character-cell terminals with output optimized to minimize
66 System V Release 4 Unix (\*(``SVr4\*('')
69 the development of which ceased in the 1990s.
70 This describes \fI\%ncurses\fP
71 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
74 permits control of the terminal screen's contents;
75 abstraction and subdivision thereof with
79 the reading of terminal input;
80 control of terminal input and output options;
81 environment query routines;
83 the definition and use of
90 compatibility interface;
91 and access to low-level terminal-manipulation routines.
94 implements the standard interface described by
95 X/Open Curses Issue\ 7.
96 In many behavioral details not standardized by X/Open,
100 library of SVr4 and provides numerous useful extensions.
102 \fI\%ncurses\fP man pages employ several sections to clarify matters of
103 usage and interoperability with other \fIcurses\fP implementations.
105 \*(``NOTES\*('' describes matters and caveats of which any user of the
106 \fI\%ncurses\fP API should be aware,
107 such as limitations on the size of an underlying integral type or the
108 availability of a preprocessor macro exclusive of a function definition
109 (which prevents its address from being taken).
110 This section also describes implementation details that will be
111 significant to the programmer but which are not standardized.
113 \*(``EXTENSIONS\*('' presents \fI\%ncurses\fP innovations beyond the
114 X/Open Curses standard and/or the SVr4 \fIcurses\fP implementation.
115 They are termed \fIextensions\fP to indicate that they cannot be
116 implemented solely by using the library API, but require access to the
117 library's internal state.
119 \*(``PORTABILITY\*('' discusses matters
120 (beyond the exercise of extensions)
121 that should be considered when writing to a \fIcurses\fP standard,
122 or to multiple implementations.
124 \*(``HISTORY\*('' examines points of detail in \fI\%ncurses\fP and other
125 \fIcurses\fP implementations over the decades of their development,
126 particularly where precedent or inertia have frustrated better design
129 where such inertia has been overcome).
131 A program using these routines must be linked with the \fB\-lncurses\fP option,
132 or (if it has been generated) with the debugging library \fB\-lncurses_g\fP.
133 (Your system integrator may also have installed these libraries under
134 the names \fB\-lcurses\fP and \fB\-lcurses_g\fP.)
135 The ncurses_g library generates trace logs
136 (in a file called \*(``trace\*('' in the current directory)
137 that describe curses actions.
138 See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
140 The library uses the locale which the calling program has initialized.
141 That is normally done with \fBsetlocale\fP(3):
145 \fBsetlocale(LC_ALL, "");\fP
149 If the locale is not initialized,
150 the library assumes that characters are printable as in ISO\-8859\-1,
151 to work with certain legacy programs.
152 You should initialize the locale and not rely on specific details of
153 the library when the locale has not been set up.
155 The function \fBinitscr\fP or \fBnewterm\fP
156 must be called to initialize the library
157 before any of the other routines that deal with windows
158 and screens are used.
159 The routine \fBendwin\fP(3X) must be called before exiting.
161 To get character-at-a-time input without echoing (most
162 interactive, screen oriented programs want this), the following
163 sequence should be used:
167 \fBinitscr(); cbreak(); noecho();\fP
171 Most programs would additionally use the sequence:
175 \fBintrflush(stdscr, FALSE);\fP
176 \fBkeypad(stdscr, TRUE);\fP
180 Before a \fBcurses\fP program is run, the tab stops of the terminal
181 should be set and its initialization strings, if defined, must be output.
182 This can be done by executing the \fB@TPUT@ init\fP command
183 after the shell environment variable \fITERM\fP has been exported.
184 (The BSD-style \fB\%@TSET@\fP(1) utility also performs this function.)
185 See subsection \*(``Tabs and Initialization\*('' of \fBterminfo\fP(5).
189 library abstracts the terminal screen by representing all or part of it
195 is a rectangular grid of character cells,
196 addressed by row and column coordinates
199 with the upper left corner as (0, 0).
200 A window called \fB\%stdscr\fP,
201 the same size as the terminal screen,
203 Create others with \fB\%newwin\fP(3X).
207 library does not manage overlapping windows.
208 (See \fBpanel\fP(3X) if you desire this.)
209 You can either use \fB\%stdscr\fP to manage one screen-filling window,
210 or tile the screen into non-overlapping windows and not use
211 \fB\%stdscr\fP at all.
212 Mixing the two approaches will result in unpredictable,
216 Functions permit manipulation of a window and the
218 identifying the cell within it at which the next output operation will
221 the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X):
222 these place the cursor and write a character to
226 window-addressing functions feature names prefixed
230 these allow the user to specify a pointer to a
232 Counterparts not thus prefixed
234 affect \fB\%stdscr\fP.
235 Because moving the cursor prior to another operation is so common,
237 generally also provides functions with a \*(``mv\*('' prefix as a
240 the library defines all of
246 When both prefixes are present,
247 the order of arguments is a
256 Updating the terminal screen with every
258 call can cause unpleasant flicker or inefficient use of the
259 communications channel to the device.
263 functions to accumulate a set of desired updates that make sense to
265 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
266 look like \fBstdscr\fP.
268 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
269 .\" does not mandate it in any way.
271 its output by computing a minimal number of operations to mutate the
272 screen from its state at the previous refresh to the new one.
273 Effective optimization demands accurate information about the terminal
275 the management of such information is the province of the
276 \fB\%terminfo\fP(3X) API,
277 a feature of every standard
281 Special windows called \fIpads\fP may also be manipulated.
282 These are windows that are not constrained to the size of the terminal
283 screen and whose contents need not be completely displayed.
284 See \fB\%curs_pad\fP(3X).
286 In addition to drawing characters on the screen,
287 rendering attributes and colors may be supported,
288 causing the characters to show up in such modes as underlined,
290 or in color on terminals that support such display enhancements.
291 See \fB\%curs_attr\fP(3X).
294 predefines constants for a small set of line-drawing and other graphics
295 corresponding to the DEC Alternate Character Set (ACS),
296 a feature of VT100 and other terminals.
298 \fB\%waddch\fP(3X) and
299 \fB\%wadd_wch\fP(3X).
302 is implemented using the operating system's terminal driver;
303 keystroke events are received not as scan codes but as byte sequences.
305 (alphanumeric and punctuation keys,
314 appears as a control character or a multibyte
315 .I "escape sequence."
317 translates these into unique
319 See \fB\%getch\fP(3X).
320 .SS "Effects of GUIs and Environment Variables"
321 The selection of an appropriate value of
323 in the process environment is essential to correct
328 A well-configured system selects a correct
331 \fB\%tset\fP(1) may assist with troubleshooting exotic situations.
333 If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
336 program is executing in a graphical windowing environment,
337 the information obtained thence overrides that obtained by
341 extension supports resizable terminals;
342 see \fB\%wresize\fP(3X).
344 If the environment variable \fI\%TERMINFO\fP is defined,
347 program checks first for a terminal type description in the location it
350 is useful for developing experimental type descriptions or when write
351 permission to \fI\*d\fP is not available.
353 See section \*(``ENVIRONMENT\*('' below.
354 .SS "Naming Conventions"
357 functions have two or more versions.
358 Those prefixed with \*(``w\*('' require a window argument.
359 Four functions prefixed with \*(``p\*('' require a pad argument.
360 Those without a prefix generally operate on \fB\%stdscr\fP.
362 In function synopses,
364 man pages apply the following names to parameters.
369 bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
370 win pointer to \fIWINDOW\fP
371 pad pointer to \fIWINDOW\fP that is a pad
373 .SS "Wide and Non-wide Character Configurations"
374 This manual page describes functions that appear in any configuration
376 There are two common configurations;
377 see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
378 .TP 10 \" "ncursesw" + 2n
380 is the library in its \*(``non-wide\*('' configuration,
381 handling only eight-bit characters.
382 It stores a character combined with attributes in a
385 which is often an alias of
389 (with no corresponding character)
390 can be stored in variables of
396 they are represented as an integral bit mask.
404 is the library in its \*(``wide\*('' configuration,
405 which handles character encodings requiring a larger data type than
409 It adds about one third more calls using additional data types that
413 .RS 10 \" same as foregoing tag width
414 .TP 9 \" "cchar_t" + 2n
416 corresponds to the non-wide configuration's
418 It always a structure type,
419 because it stores more data than fits into an integral type.
420 A character code may not be representable as a
422 and moreover more than one character may occupy a cell
423 (as with accent marks and other diacritics).
424 Each character is of type
426 a complex character contains one spacing character and zero or more
427 non-spacing characters
429 Attributes and color data are stored in separate fields of the
439 The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
440 functions store and retrieve the data from a
443 The wide library API of
445 depends on two data types standardized by ISO C95.
448 stores a wide character.
451 it may be an alias of
453 Depending on the character encoding,
454 a wide character may be
456 meaning that it occupies a character cell by itself and typically
457 accompanies cursor advancement,
460 meaning that it occupies the same cell as a spacing character,
461 is often regarded as a \*(``modifier\*('' of the base glyph with which
463 and typically does not advance the cursor.
472 character manipulation functions of ISO C and its constant
476 The wide library provides additional functions that complement those in
477 the non-wide library where the size of the underlying character type is
479 A somewhat regular naming convention relates many of the wide variants
480 to their non-wide counterparts;
481 where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
482 prefix it with \*(``_w\*('' to obtain the wide counterpart.
484 \fB\%waddch\fP becomes \fB\%wadd_wch\fP.
486 This convention is inapplicable to some non-wide function names,
487 so other transformations are used for the wide configuration:
488 in the window background management functions,
489 \*(``bkgd\*('' becomes \*(``bkgrnd\*('';
490 the window border-drawing and -clearing functions are suffixed with
493 .SS "Function Name Index"
494 The following table lists the
496 functions provided in the non-wide and wide APIs and the corresponding
497 man pages that describe them.
498 Those flagged with \*(``*\*(''
500 .IR \%ncurses -specific,
501 neither described by X/Open Curses nor present in SVr4.
506 \f(BIcurses\fP Function Name/Man Page
508 COLOR_PAIR/\fBcurs_color\fP(3X)
509 PAIR_NUMBER/\fBcurs_color\fP(3X)
510 add_wch/\fBcurs_add_wch\fP(3X)
511 add_wchnstr/\fBcurs_add_wchstr\fP(3X)
512 add_wchstr/\fBcurs_add_wchstr\fP(3X)
513 addch/\fBcurs_addch\fP(3X)
514 addchnstr/\fBcurs_addchstr\fP(3X)
515 addchstr/\fBcurs_addchstr\fP(3X)
516 addnstr/\fBcurs_addstr\fP(3X)
517 addnwstr/\fBcurs_addwstr\fP(3X)
518 addstr/\fBcurs_addstr\fP(3X)
519 addwstr/\fBcurs_addwstr\fP(3X)
520 alloc_pair/\fBnew_pair\fP(3X)*
521 assume_default_colors/\fBdefault_colors\fP(3X)*
522 attr_get/\fBcurs_attr\fP(3X)
523 attr_off/\fBcurs_attr\fP(3X)
524 attr_on/\fBcurs_attr\fP(3X)
525 attr_set/\fBcurs_attr\fP(3X)
526 attroff/\fBcurs_attr\fP(3X)
527 attron/\fBcurs_attr\fP(3X)
528 attrset/\fBcurs_attr\fP(3X)
529 baudrate/\fBcurs_termattrs\fP(3X)
530 beep/\fBcurs_beep\fP(3X)
531 bkgd/\fBcurs_bkgd\fP(3X)
532 bkgdset/\fBcurs_bkgd\fP(3X)
533 bkgrnd/\fBcurs_bkgrnd\fP(3X)
534 bkgrndset/\fBcurs_bkgrnd\fP(3X)
535 border/\fBcurs_border\fP(3X)
536 border_set/\fBcurs_border_set\fP(3X)
537 box/\fBcurs_border\fP(3X)
538 box_set/\fBcurs_border_set\fP(3X)
539 can_change_color/\fBcurs_color\fP(3X)
540 cbreak/\fBcurs_inopts\fP(3X)
541 chgat/\fBcurs_attr\fP(3X)
542 clear/\fBcurs_clear\fP(3X)
543 clearok/\fBcurs_outopts\fP(3X)
544 clrtobot/\fBcurs_clear\fP(3X)
545 clrtoeol/\fBcurs_clear\fP(3X)
546 color_content/\fBcurs_color\fP(3X)
547 color_set/\fBcurs_attr\fP(3X)
548 copywin/\fBcurs_overlay\fP(3X)
549 curs_set/\fBcurs_kernel\fP(3X)
550 curses_trace/\fBcurs_trace\fP(3X)*
551 curses_version/\fBcurs_extend\fP(3X)*
552 def_prog_mode/\fBcurs_kernel\fP(3X)
553 def_shell_mode/\fBcurs_kernel\fP(3X)
554 define_key/\fBdefine_key\fP(3X)*
555 del_curterm/\fBcurs_terminfo\fP(3X)
556 delay_output/\fBcurs_util\fP(3X)
557 delch/\fBcurs_delch\fP(3X)
558 deleteln/\fBcurs_deleteln\fP(3X)
559 delscreen/\fBcurs_initscr\fP(3X)
560 delwin/\fBcurs_window\fP(3X)
561 derwin/\fBcurs_window\fP(3X)
562 doupdate/\fBcurs_refresh\fP(3X)
563 dupwin/\fBcurs_window\fP(3X)
564 echo/\fBcurs_inopts\fP(3X)
565 echo_wchar/\fBcurs_add_wch\fP(3X)
566 echochar/\fBcurs_addch\fP(3X)
567 endwin/\fBcurs_initscr\fP(3X)
568 erase/\fBcurs_clear\fP(3X)
569 erasechar/\fBcurs_termattrs\fP(3X)
570 erasewchar/\fBcurs_termattrs\fP(3X)
571 exit_curses/\fBcurs_memleaks\fP(3X)*
572 exit_terminfo/\fBcurs_memleaks\fP(3X)*
573 extended_color_content/\fBcurs_color\fP(3X)*
574 extended_pair_content/\fBcurs_color\fP(3X)*
575 extended_slk_color/\fBcurs_slk\fP(3X)*
576 filter/\fBcurs_util\fP(3X)
577 find_pair/\fBnew_pair\fP(3X)*
578 flash/\fBcurs_beep\fP(3X)
579 flushinp/\fBcurs_util\fP(3X)
580 free_pair/\fBnew_pair\fP(3X)*
581 get_wch/\fBcurs_get_wch\fP(3X)
582 get_wstr/\fBcurs_get_wstr\fP(3X)
583 getattrs/\fBcurs_attr\fP(3X)
584 getbegx/\fBcurs_legacy\fP(3X)*
585 getbegy/\fBcurs_legacy\fP(3X)*
586 getbegyx/\fBcurs_getyx\fP(3X)
587 getbkgd/\fBcurs_bkgd\fP(3X)
588 getbkgrnd/\fBcurs_bkgrnd\fP(3X)
589 getcchar/\fBcurs_getcchar\fP(3X)
590 getch/\fBcurs_getch\fP(3X)
591 getcurx/\fBcurs_legacy\fP(3X)*
592 getcury/\fBcurs_legacy\fP(3X)*
593 getmaxx/\fBcurs_legacy\fP(3X)*
594 getmaxy/\fBcurs_legacy\fP(3X)*
595 getmaxyx/\fBcurs_getyx\fP(3X)
596 getmouse/\fBcurs_mouse\fP(3X)*
597 getn_wstr/\fBcurs_get_wstr\fP(3X)
598 getnstr/\fBcurs_getstr\fP(3X)
599 getparx/\fBcurs_legacy\fP(3X)*
600 getpary/\fBcurs_legacy\fP(3X)*
601 getparyx/\fBcurs_getyx\fP(3X)
602 getstr/\fBcurs_getstr\fP(3X)
603 getsyx/\fBcurs_kernel\fP(3X)
604 getwin/\fBcurs_util\fP(3X)
605 getyx/\fBcurs_getyx\fP(3X)
606 halfdelay/\fBcurs_inopts\fP(3X)
607 has_colors/\fBcurs_color\fP(3X)
608 has_ic/\fBcurs_termattrs\fP(3X)
609 has_il/\fBcurs_termattrs\fP(3X)
610 has_key/\fBcurs_getch\fP(3X)*
611 has_mouse/\fBcurs_mouse\fP(3X)*
612 hline/\fBcurs_border\fP(3X)
613 hline_set/\fBcurs_border_set\fP(3X)
614 idcok/\fBcurs_outopts\fP(3X)
615 idlok/\fBcurs_outopts\fP(3X)
616 immedok/\fBcurs_outopts\fP(3X)
617 in_wch/\fBcurs_in_wch\fP(3X)
618 in_wchnstr/\fBcurs_in_wchstr\fP(3X)
619 in_wchstr/\fBcurs_in_wchstr\fP(3X)
620 inch/\fBcurs_inch\fP(3X)
621 inchnstr/\fBcurs_inchstr\fP(3X)
622 inchstr/\fBcurs_inchstr\fP(3X)
623 init_color/\fBcurs_color\fP(3X)
624 init_extended_color/\fBcurs_color\fP(3X)*
625 init_extended_pair/\fBcurs_color\fP(3X)*
626 init_pair/\fBcurs_color\fP(3X)
627 initscr/\fBcurs_initscr\fP(3X)
628 innstr/\fBcurs_instr\fP(3X)
629 innwstr/\fBcurs_inwstr\fP(3X)
630 ins_nwstr/\fBcurs_ins_wstr\fP(3X)
631 ins_wch/\fBcurs_ins_wch\fP(3X)
632 ins_wstr/\fBcurs_ins_wstr\fP(3X)
633 insch/\fBcurs_insch\fP(3X)
634 insdelln/\fBcurs_deleteln\fP(3X)
635 insertln/\fBcurs_deleteln\fP(3X)
636 insnstr/\fBcurs_insstr\fP(3X)
637 insstr/\fBcurs_insstr\fP(3X)
638 instr/\fBcurs_instr\fP(3X)
639 intrflush/\fBcurs_inopts\fP(3X)
640 inwstr/\fBcurs_inwstr\fP(3X)
641 is_cbreak/\fBcurs_inopts\fP(3X)*
642 is_cleared/\fBcurs_opaque\fP(3X)*
643 is_echo/\fBcurs_inopts\fP(3X)*
644 is_idcok/\fBcurs_opaque\fP(3X)*
645 is_idlok/\fBcurs_opaque\fP(3X)*
646 is_immedok/\fBcurs_opaque\fP(3X)*
647 is_keypad/\fBcurs_opaque\fP(3X)*
648 is_leaveok/\fBcurs_opaque\fP(3X)*
649 is_linetouched/\fBcurs_touch\fP(3X)
650 is_nl/\fBcurs_inopts\fP(3X)*
651 is_nodelay/\fBcurs_opaque\fP(3X)*
652 is_notimeout/\fBcurs_opaque\fP(3X)*
653 is_pad/\fBcurs_opaque\fP(3X)*
654 is_raw/\fBcurs_inopts\fP(3X)*
655 is_scrollok/\fBcurs_opaque\fP(3X)*
656 is_subwin/\fBcurs_opaque\fP(3X)*
657 is_syncok/\fBcurs_opaque\fP(3X)*
658 is_term_resized/\fBresizeterm\fP(3X)*
659 is_wintouched/\fBcurs_touch\fP(3X)
660 isendwin/\fBcurs_initscr\fP(3X)
661 key_defined/\fBkey_defined\fP(3X)*
662 key_name/\fBcurs_util\fP(3X)
663 keybound/\fBkeybound\fP(3X)*
664 keyname/\fBcurs_util\fP(3X)
665 keyok/\fBkeyok\fP(3X)*
666 keypad/\fBcurs_inopts\fP(3X)
667 killchar/\fBcurs_termattrs\fP(3X)
668 killwchar/\fBcurs_termattrs\fP(3X)
669 leaveok/\fBcurs_outopts\fP(3X)
670 longname/\fBcurs_termattrs\fP(3X)
671 mcprint/\fBcurs_print\fP(3X)*
672 meta/\fBcurs_inopts\fP(3X)
673 mouse_trafo/\fBcurs_mouse\fP(3X)*
674 mouseinterval/\fBcurs_mouse\fP(3X)*
675 mousemask/\fBcurs_mouse\fP(3X)*
676 move/\fBcurs_move\fP(3X)
677 mvadd_wch/\fBcurs_add_wch\fP(3X)
678 mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
679 mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
680 mvaddch/\fBcurs_addch\fP(3X)
681 mvaddchnstr/\fBcurs_addchstr\fP(3X)
682 mvaddchstr/\fBcurs_addchstr\fP(3X)
683 mvaddnstr/\fBcurs_addstr\fP(3X)
684 mvaddnwstr/\fBcurs_addwstr\fP(3X)
685 mvaddstr/\fBcurs_addstr\fP(3X)
686 mvaddwstr/\fBcurs_addwstr\fP(3X)
687 mvchgat/\fBcurs_attr\fP(3X)
688 mvcur/\fBcurs_terminfo\fP(3X)
689 mvdelch/\fBcurs_delch\fP(3X)
690 mvderwin/\fBcurs_window\fP(3X)
691 mvget_wch/\fBcurs_get_wch\fP(3X)
692 mvget_wstr/\fBcurs_get_wstr\fP(3X)
693 mvgetch/\fBcurs_getch\fP(3X)
694 mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
695 mvgetnstr/\fBcurs_getstr\fP(3X)
696 mvgetstr/\fBcurs_getstr\fP(3X)
697 mvhline/\fBcurs_border\fP(3X)
698 mvhline_set/\fBcurs_border_set\fP(3X)
699 mvin_wch/\fBcurs_in_wch\fP(3X)
700 mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
701 mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
702 mvinch/\fBcurs_inch\fP(3X)
703 mvinchnstr/\fBcurs_inchstr\fP(3X)
704 mvinchstr/\fBcurs_inchstr\fP(3X)
705 mvinnstr/\fBcurs_instr\fP(3X)
706 mvinnwstr/\fBcurs_inwstr\fP(3X)
707 mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
708 mvins_wch/\fBcurs_ins_wch\fP(3X)
709 mvins_wstr/\fBcurs_ins_wstr\fP(3X)
710 mvinsch/\fBcurs_insch\fP(3X)
711 mvinsnstr/\fBcurs_insstr\fP(3X)
712 mvinsstr/\fBcurs_insstr\fP(3X)
713 mvinstr/\fBcurs_instr\fP(3X)
714 mvinwstr/\fBcurs_inwstr\fP(3X)
715 mvprintw/\fBcurs_printw\fP(3X)
716 mvscanw/\fBcurs_scanw\fP(3X)
717 mvvline/\fBcurs_border\fP(3X)
718 mvvline_set/\fBcurs_border_set\fP(3X)
719 mvwadd_wch/\fBcurs_add_wch\fP(3X)
720 mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
721 mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
722 mvwaddch/\fBcurs_addch\fP(3X)
723 mvwaddchnstr/\fBcurs_addchstr\fP(3X)
724 mvwaddchstr/\fBcurs_addchstr\fP(3X)
725 mvwaddnstr/\fBcurs_addstr\fP(3X)
726 mvwaddnwstr/\fBcurs_addwstr\fP(3X)
727 mvwaddstr/\fBcurs_addstr\fP(3X)
728 mvwaddwstr/\fBcurs_addwstr\fP(3X)
729 mvwchgat/\fBcurs_attr\fP(3X)
730 mvwdelch/\fBcurs_delch\fP(3X)
731 mvwget_wch/\fBcurs_get_wch\fP(3X)
732 mvwget_wstr/\fBcurs_get_wstr\fP(3X)
733 mvwgetch/\fBcurs_getch\fP(3X)
734 mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
735 mvwgetnstr/\fBcurs_getstr\fP(3X)
736 mvwgetstr/\fBcurs_getstr\fP(3X)
737 mvwhline/\fBcurs_border\fP(3X)
738 mvwhline_set/\fBcurs_border_set\fP(3X)
739 mvwin/\fBcurs_window\fP(3X)
740 mvwin_wch/\fBcurs_in_wch\fP(3X)
741 mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
742 mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
743 mvwinch/\fBcurs_inch\fP(3X)
744 mvwinchnstr/\fBcurs_inchstr\fP(3X)
745 mvwinchstr/\fBcurs_inchstr\fP(3X)
746 mvwinnstr/\fBcurs_instr\fP(3X)
747 mvwinnwstr/\fBcurs_inwstr\fP(3X)
748 mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
749 mvwins_wch/\fBcurs_ins_wch\fP(3X)
750 mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
751 mvwinsch/\fBcurs_insch\fP(3X)
752 mvwinsnstr/\fBcurs_insstr\fP(3X)
753 mvwinsstr/\fBcurs_insstr\fP(3X)
754 mvwinstr/\fBcurs_instr\fP(3X)
755 mvwinwstr/\fBcurs_inwstr\fP(3X)
756 mvwprintw/\fBcurs_printw\fP(3X)
757 mvwscanw/\fBcurs_scanw\fP(3X)
758 mvwvline/\fBcurs_border\fP(3X)
759 mvwvline_set/\fBcurs_border_set\fP(3X)
760 napms/\fBcurs_kernel\fP(3X)
761 newpad/\fBcurs_pad\fP(3X)
762 newterm/\fBcurs_initscr\fP(3X)
763 newwin/\fBcurs_window\fP(3X)
764 nl/\fBcurs_inopts\fP(3X)
765 nocbreak/\fBcurs_inopts\fP(3X)
766 nodelay/\fBcurs_inopts\fP(3X)
767 noecho/\fBcurs_inopts\fP(3X)
768 nofilter/\fBcurs_util\fP(3X)*
769 nonl/\fBcurs_inopts\fP(3X)
770 noqiflush/\fBcurs_inopts\fP(3X)
771 noraw/\fBcurs_inopts\fP(3X)
772 notimeout/\fBcurs_inopts\fP(3X)
773 overlay/\fBcurs_overlay\fP(3X)
774 overwrite/\fBcurs_overlay\fP(3X)
775 pair_content/\fBcurs_color\fP(3X)
776 pecho_wchar/\fBcurs_pad\fP(3X)
777 pechochar/\fBcurs_pad\fP(3X)
778 pnoutrefresh/\fBcurs_pad\fP(3X)
779 prefresh/\fBcurs_pad\fP(3X)
780 printw/\fBcurs_printw\fP(3X)
781 putp/\fBcurs_terminfo\fP(3X)
782 putwin/\fBcurs_util\fP(3X)
783 qiflush/\fBcurs_inopts\fP(3X)
784 raw/\fBcurs_inopts\fP(3X)
785 redrawwin/\fBcurs_refresh\fP(3X)
786 refresh/\fBcurs_refresh\fP(3X)
787 reset_color_pairs/\fBcurs_color\fP(3X)*
788 reset_prog_mode/\fBcurs_kernel\fP(3X)
789 reset_shell_mode/\fBcurs_kernel\fP(3X)
790 resetty/\fBcurs_kernel\fP(3X)
791 resize_term/\fBresizeterm\fP(3X)*
792 resizeterm/\fBresizeterm\fP(3X)*
793 restartterm/\fBcurs_terminfo\fP(3X)
794 ripoffline/\fBcurs_kernel\fP(3X)
795 savetty/\fBcurs_kernel\fP(3X)
796 scanw/\fBcurs_scanw\fP(3X)
797 scr_dump/\fBcurs_scr_dump\fP(3X)
798 scr_init/\fBcurs_scr_dump\fP(3X)
799 scr_restore/\fBcurs_scr_dump\fP(3X)
800 scr_set/\fBcurs_scr_dump\fP(3X)
801 scrl/\fBcurs_scroll\fP(3X)
802 scroll/\fBcurs_scroll\fP(3X)
803 scrollok/\fBcurs_outopts\fP(3X)
804 set_curterm/\fBcurs_terminfo\fP(3X)
805 set_term/\fBcurs_initscr\fP(3X)
806 setcchar/\fBcurs_getcchar\fP(3X)
807 setscrreg/\fBcurs_outopts\fP(3X)
808 setsyx/\fBcurs_kernel\fP(3X)
809 setupterm/\fBcurs_terminfo\fP(3X)
810 slk_attr/\fBcurs_slk\fP(3X)*
811 slk_attr_off/\fBcurs_slk\fP(3X)
812 slk_attr_on/\fBcurs_slk\fP(3X)
813 slk_attr_set/\fBcurs_slk\fP(3X)
814 slk_attroff/\fBcurs_slk\fP(3X)
815 slk_attron/\fBcurs_slk\fP(3X)
816 slk_attrset/\fBcurs_slk\fP(3X)
817 slk_clear/\fBcurs_slk\fP(3X)
818 slk_color/\fBcurs_slk\fP(3X)
819 slk_init/\fBcurs_slk\fP(3X)
820 slk_label/\fBcurs_slk\fP(3X)
821 slk_noutrefresh/\fBcurs_slk\fP(3X)
822 slk_refresh/\fBcurs_slk\fP(3X)
823 slk_restore/\fBcurs_slk\fP(3X)
824 slk_set/\fBcurs_slk\fP(3X)
825 slk_touch/\fBcurs_slk\fP(3X)
826 slk_wset/\fBcurs_slk\fP(3X)
827 standend/\fBcurs_attr\fP(3X)
828 standout/\fBcurs_attr\fP(3X)
829 start_color/\fBcurs_color\fP(3X)
830 subpad/\fBcurs_pad\fP(3X)
831 subwin/\fBcurs_window\fP(3X)
832 syncok/\fBcurs_window\fP(3X)
833 term_attrs/\fBcurs_termattrs\fP(3X)
834 termattrs/\fBcurs_termattrs\fP(3X)
835 termname/\fBcurs_termattrs\fP(3X)
836 tgetent/\fBcurs_termcap\fP(3X)
837 tgetflag/\fBcurs_termcap\fP(3X)
838 tgetnum/\fBcurs_termcap\fP(3X)
839 tgetstr/\fBcurs_termcap\fP(3X)
840 tgoto/\fBcurs_termcap\fP(3X)
841 tigetflag/\fBcurs_terminfo\fP(3X)
842 tigetnum/\fBcurs_terminfo\fP(3X)
843 tigetstr/\fBcurs_terminfo\fP(3X)
844 timeout/\fBcurs_inopts\fP(3X)
845 tiparm/\fBcurs_terminfo\fP(3X)
846 tiparm_s/\fBcurs_terminfo\fP(3X)*
847 tiscan_s/\fBcurs_terminfo\fP(3X)*
848 touchline/\fBcurs_touch\fP(3X)
849 touchwin/\fBcurs_touch\fP(3X)
850 tparm/\fBcurs_terminfo\fP(3X)
851 tputs/\fBcurs_termcap\fP(3X)
852 tputs/\fBcurs_terminfo\fP(3X)
853 trace/\fBcurs_trace\fP(3X)*
854 typeahead/\fBcurs_inopts\fP(3X)
855 unctrl/\fBcurs_util\fP(3X)
856 unget_wch/\fBcurs_get_wch\fP(3X)
857 ungetch/\fBcurs_getch\fP(3X)
858 ungetmouse/\fBcurs_mouse\fP(3X)*
859 untouchwin/\fBcurs_touch\fP(3X)
860 use_default_colors/\fBdefault_colors\fP(3X)*
861 use_env/\fBcurs_util\fP(3X)
862 use_extended_names/\fBcurs_extend\fP(3X)*
863 use_legacy_coding/\fBlegacy_coding\fP(3X)*
864 use_tioctl/\fBcurs_util\fP(3X)*
865 vid_attr/\fBcurs_terminfo\fP(3X)
866 vid_puts/\fBcurs_terminfo\fP(3X)
867 vidattr/\fBcurs_terminfo\fP(3X)
868 vidputs/\fBcurs_terminfo\fP(3X)
869 vline/\fBcurs_border\fP(3X)
870 vline_set/\fBcurs_border_set\fP(3X)
871 vw_printw/\fBcurs_printw\fP(3X)
872 vw_scanw/\fBcurs_scanw\fP(3X)
873 vwprintw/\fBcurs_printw\fP(3X)
874 vwscanw/\fBcurs_scanw\fP(3X)
875 wadd_wch/\fBcurs_add_wch\fP(3X)
876 wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
877 wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
878 waddch/\fBcurs_addch\fP(3X)
879 waddchnstr/\fBcurs_addchstr\fP(3X)
880 waddchstr/\fBcurs_addchstr\fP(3X)
881 waddnstr/\fBcurs_addstr\fP(3X)
882 waddnwstr/\fBcurs_addwstr\fP(3X)
883 waddstr/\fBcurs_addstr\fP(3X)
884 waddwstr/\fBcurs_addwstr\fP(3X)
885 wattr_get/\fBcurs_attr\fP(3X)
886 wattr_off/\fBcurs_attr\fP(3X)
887 wattr_on/\fBcurs_attr\fP(3X)
888 wattr_set/\fBcurs_attr\fP(3X)
889 wattroff/\fBcurs_attr\fP(3X)
890 wattron/\fBcurs_attr\fP(3X)
891 wattrset/\fBcurs_attr\fP(3X)
892 wbkgd/\fBcurs_bkgd\fP(3X)
893 wbkgdset/\fBcurs_bkgd\fP(3X)
894 wbkgrnd/\fBcurs_bkgrnd\fP(3X)
895 wbkgrndset/\fBcurs_bkgrnd\fP(3X)
896 wborder/\fBcurs_border\fP(3X)
897 wborder_set/\fBcurs_border_set\fP(3X)
898 wchgat/\fBcurs_attr\fP(3X)
899 wclear/\fBcurs_clear\fP(3X)
900 wclrtobot/\fBcurs_clear\fP(3X)
901 wclrtoeol/\fBcurs_clear\fP(3X)
902 wcolor_set/\fBcurs_attr\fP(3X)
903 wcursyncup/\fBcurs_window\fP(3X)
904 wdelch/\fBcurs_delch\fP(3X)
905 wdeleteln/\fBcurs_deleteln\fP(3X)
906 wecho_wchar/\fBcurs_add_wch\fP(3X)
907 wechochar/\fBcurs_addch\fP(3X)
908 wenclose/\fBcurs_mouse\fP(3X)*
909 werase/\fBcurs_clear\fP(3X)
910 wget_wch/\fBcurs_get_wch\fP(3X)
911 wget_wstr/\fBcurs_get_wstr\fP(3X)
912 wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
913 wgetch/\fBcurs_getch\fP(3X)
914 wgetdelay/\fBcurs_opaque\fP(3X)*
915 wgetn_wstr/\fBcurs_get_wstr\fP(3X)
916 wgetnstr/\fBcurs_getstr\fP(3X)
917 wgetparent/\fBcurs_opaque\fP(3X)*
918 wgetscrreg/\fBcurs_opaque\fP(3X)*
919 wgetstr/\fBcurs_getstr\fP(3X)
920 whline/\fBcurs_border\fP(3X)
921 whline_set/\fBcurs_border_set\fP(3X)
922 win_wch/\fBcurs_in_wch\fP(3X)
923 win_wchnstr/\fBcurs_in_wchstr\fP(3X)
924 win_wchstr/\fBcurs_in_wchstr\fP(3X)
925 winch/\fBcurs_inch\fP(3X)
926 winchnstr/\fBcurs_inchstr\fP(3X)
927 winchstr/\fBcurs_inchstr\fP(3X)
928 winnstr/\fBcurs_instr\fP(3X)
929 winnwstr/\fBcurs_inwstr\fP(3X)
930 wins_nwstr/\fBcurs_ins_wstr\fP(3X)
931 wins_wch/\fBcurs_ins_wch\fP(3X)
932 wins_wstr/\fBcurs_ins_wstr\fP(3X)
933 winsch/\fBcurs_insch\fP(3X)
934 winsdelln/\fBcurs_deleteln\fP(3X)
935 winsertln/\fBcurs_deleteln\fP(3X)
936 winsnstr/\fBcurs_insstr\fP(3X)
937 winsstr/\fBcurs_insstr\fP(3X)
938 winstr/\fBcurs_instr\fP(3X)
939 winwstr/\fBcurs_inwstr\fP(3X)
940 wmouse_trafo/\fBcurs_mouse\fP(3X)*
941 wmove/\fBcurs_move\fP(3X)
942 wnoutrefresh/\fBcurs_refresh\fP(3X)
943 wprintw/\fBcurs_printw\fP(3X)
944 wredrawln/\fBcurs_refresh\fP(3X)
945 wrefresh/\fBcurs_refresh\fP(3X)
946 wresize/\fBwresize\fP(3X)*
947 wscanw/\fBcurs_scanw\fP(3X)
948 wscrl/\fBcurs_scroll\fP(3X)
949 wsetscrreg/\fBcurs_outopts\fP(3X)
950 wstandend/\fBcurs_attr\fP(3X)
951 wstandout/\fBcurs_attr\fP(3X)
952 wsyncdown/\fBcurs_window\fP(3X)
953 wsyncup/\fBcurs_window\fP(3X)
954 wtimeout/\fBcurs_inopts\fP(3X)
955 wtouchln/\fBcurs_touch\fP(3X)
956 wunctrl/\fBcurs_util\fP(3X)
957 wvline/\fBcurs_border\fP(3X)
958 wvline_set/\fBcurs_border_set\fP(3X)
961 Depending on the configuration,
962 additional sets of functions may be available:
965 \fBcurs_memleaks\fP(3X) - curses memory-leak checking
967 \fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension
969 \fBcurs_threads\fP(3X) - curses thread support
971 \fBcurs_trace\fP(3X) - curses debugging routines
974 Unless otherwise noted,
975 functions that return an integer return \fBOK\fP on success and
976 \fBERR\fP on failure.
977 Functions that return pointers return \fBNULL\fP on failure.
980 treats a null pointer passed as a function parameter as a failure.
982 Functions with a \*(``mv\*('' prefix first perform cursor movement using
983 \fB\%wmove\fP and fail if the position is outside the window,
985 (for \*(``mvw\*('' functions)
990 The following environment symbols are useful for customizing the
991 runtime behavior of the \fI\%ncurses\fP library.
992 The most important ones have been already discussed in detail.
993 .SS "\fICC\fP (command character)"
996 .B \%command_character
998 capability value of loaded
1000 entries to the value of this variable.
1003 entries provide this feature.
1005 Because this name is also used in development environments to represent
1006 the C compiler's name,
1007 \fI\%ncurses\fP ignores it if it does not happen to be a single
1009 .SS "\fIBAUDRATE\fP"
1010 The debugging library checks this environment variable when the application
1011 has redirected output to a file.
1012 The variable's numeric value is used for the baud rate.
1013 If no value is found, \fI\%ncurses\fP uses 9600.
1014 This allows testers to construct repeatable test-cases
1015 that take into account costs that depend on baud rate.
1017 Specify the width of the screen in characters.
1018 Applications running in a windowing environment usually are able to
1019 obtain the width of the window in which they are executing.
1020 If neither the \fI\%COLUMNS\fP value
1021 nor the terminal's screen size is available,
1022 \fI\%ncurses\fP uses the size which may be specified in the terminfo
1024 (i.e., the \fBcols\fP capability).
1026 It is important that your application use a correct size for the screen.
1027 This is not always possible because your application may be
1028 running on a host which does not honor NAWS (Negotiations About Window
1029 Size), or because you are temporarily running as another user.
1031 setting \fI\%COLUMNS\fP and/or \fILINES\fP overrides the library's use
1032 of the screen size obtained from the operating system.
1034 Either \fI\%COLUMNS\fP or \fILINES\fP symbols may be specified
1036 This is mainly useful to circumvent legacy misfeatures of terminal descriptions,
1037 e.g., xterm which commonly specifies a 65 line screen.
1038 For best results, \fBlines\fP and \fBcols\fP should not be specified in
1039 a terminal description for terminals which are run as emulations.
1041 Use the \fBuse_env\fP function to disable all use of external environment
1042 (but not including system calls) to determine the screen size.
1043 Use the \fBuse_tioctl\fP function to update \fI\%COLUMNS\fP or
1044 \fILINES\fP to match the screen size obtained from system calls or the
1046 .SS "\fIESCDELAY\fP"
1047 Specifies the total time,
1049 for which \fI\%ncurses\fP will await a character sequence,
1052 The default value, 1000 milliseconds, is enough for most uses.
1053 However, it is made a variable to accommodate unusual applications.
1055 The most common instance where you may wish to change this value
1056 is to work with slow hosts, e.g., running on a network.
1057 If the host cannot read characters rapidly enough, it will have the same
1058 effect as if the terminal did not send characters rapidly enough.
1059 The library will still see a timeout.
1061 Note that xterm mouse events are built up from character sequences
1062 received from the xterm.
1063 If your application makes heavy use of multiple-clicking, you may
1064 wish to lengthen this default value because the timeout applies
1065 to the composed multi-click event as well as the individual clicks.
1067 In addition to the environment variable,
1068 this implementation provides a global variable with the same name.
1069 Portable applications should not rely upon the presence of \fB\%ESCDELAY\fP
1071 but setting the environment variable rather than the global variable
1072 does not create problems when compiling an application.
1074 Tells \fI\%ncurses\fP where your home directory is.
1075 That is where it may read and write auxiliary terminal descriptions:
1084 Like \fI\%COLUMNS\fP, specify the height of the screen in characters.
1085 See \fI\%COLUMNS\fP for a detailed description.
1086 .SS "\fIMOUSE_BUTTONS_123\fP"
1087 This applies only to the OS/2 EMX port.
1088 It specifies the order of buttons on the mouse.
1089 OS/2 numbers a 3-button mouse inconsistently from other
1100 This variable lets you customize the mouse.
1101 The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
1102 If it is not specified, \fI\%ncurses\fP uses 132.
1103 .SS "\fINCURSES_ASSUMED_COLORS\fP"
1104 Override the compiled-in assumption that the
1105 terminal's default colors are white-on-black
1106 (see \fBdefault_colors\fP(3X)).
1107 You may set the foreground and background color values with this environment
1108 variable by proving a 2-element list: foreground,background.
1109 For example, to tell \fI\%ncurses\fP to not assume anything
1110 about the colors, set this to "\-1,\-1".
1111 To make it green-on-black, set it to "2,0".
1112 Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed.
1113 .SS "\fINCURSES_CONSOLE2\fP"
1114 This applies only to the MinGW port of \fI\%ncurses\fP.
1116 The \fBConsole2\fP program's handling of the Microsoft Console API call
1117 \fBCreateConsoleScreenBuffer\fP is defective.
1118 Applications which use this will hang.
1119 However, it is possible to simulate the action of this call by
1120 mapping coordinates,
1121 explicitly saving and restoring the original screen contents.
1122 Setting the environment variable \fBNCGDB\fP has the same effect.
1123 .SS "\fINCURSES_GPM_TERMS\fP"
1124 This applies only to \fI\%ncurses\fP configured to use the GPM
1128 the environment variable is a list of one or more terminal names
1129 against which the \fITERM\fP environment variable is matched.
1130 Setting it to an empty value disables the GPM interface;
1131 using the built-in support for xterm, etc.
1133 If the environment variable is absent,
1134 \fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains
1136 .SS "\fINCURSES_NO_HARD_TABS\fP"
1137 \fI\%ncurses\fP may use tabs as part of cursor movement optimization.
1139 your terminal driver may not handle these properly.
1140 Set this environment variable to any value to disable the feature.
1141 You can also adjust your \fBstty\fP(1) settings to avoid the problem.
1142 .SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
1143 Some terminals use a magic-cookie feature which requires special handling
1144 to make highlighting and other video attributes display properly.
1145 You can suppress the highlighting entirely for these terminals by
1146 setting this environment variable to any value.
1147 .SS "\fINCURSES_NO_PADDING\fP"
1148 Most of the terminal descriptions in the terminfo database are written
1149 for real \*(``hardware\*('' terminals.
1150 Many people use terminal emulators
1151 which run in a windowing environment and use curses-based applications.
1152 Terminal emulators can duplicate
1153 all of the important aspects of a hardware terminal, but they do not
1154 have the same limitations.
1155 The chief limitation of a hardware terminal from the standpoint
1156 of your application is the management of dataflow, i.e., timing.
1157 Unless a hardware terminal is interfaced into a terminal concentrator
1158 (which does flow control),
1159 it (or your application) must manage dataflow, preventing overruns.
1160 The cheapest solution (no hardware cost)
1161 is for your program to do this by pausing after
1162 operations that the terminal does slowly, such as clearing the display.
1164 As a result, many terminal descriptions (including the vt100)
1165 have delay times embedded.
1166 You may wish to use these descriptions,
1167 but not want to pay the performance penalty.
1169 Set the \fI\%NCURSES_NO_PADDING\fP environment variable
1170 to disable all but mandatory padding.
1171 Mandatory padding is used as a part of special control
1172 sequences such as \fBflash\fP.
1173 .SS "\fINCURSES_NO_SETBUF\fP"
1174 This setting is obsolete.
1178 started with 5.9 patch 20120825
1182 though 5.9 patch 20130126
1185 \fI\%ncurses\fP enabled buffered output during terminal initialization.
1186 This was done (as in SVr4 curses) for performance reasons.
1187 For testing purposes, both of \fI\%ncurses\fP and certain applications,
1188 this feature was made optional.
1189 Setting the \fI\%NCURSES_NO_SETBUF\fP variable
1190 disabled output buffering, leaving the output in the original (usually
1191 line buffered) mode.
1193 In the current implementation,
1194 \fI\%ncurses\fP performs its own buffering and does not require this
1196 It does not modify the buffering of the standard output.
1198 The reason for the change was to make the behavior for interrupts and
1199 other signals more robust.
1200 One drawback is that certain nonconventional programs would mix
1201 ordinary \fI\%stdio\fP(3) calls with \fI\%ncurses\fP calls and (usually)
1203 This is no longer possible since \fI\%ncurses\fP is not using
1204 the buffered standard output but its own output (to the same file descriptor).
1205 As a special case, the low-level calls such as \fBputp\fP still use the
1207 But high-level curses calls do not.
1208 .SS "\fINCURSES_NO_UTF8_ACS\fP"
1209 During initialization, the \fI\%ncurses\fP library
1210 checks for special cases where VT100 line-drawing (and the corresponding
1211 alternate character set capabilities) described in the terminfo are known
1213 Specifically, when running in a UTF\-8 locale,
1214 the Linux console emulator and the GNU screen program ignore these.
1215 \fI\%ncurses checks the \fITERM\fP environment variable for these.
1216 For other special cases, you should set this environment variable.
1217 Doing this tells \fI\%ncurses\fP to use Unicode values which correspond
1218 to the VT100 line-drawing glyphs.
1219 That works for the special cases cited,
1220 and is likely to work for terminal emulators.
1222 When setting this variable, you should set it to a nonzero value.
1223 Setting it to zero (or to a nonnumber)
1224 disables the special check for \*(``linux\*('' and \*(``screen\*(''.
1226 As an alternative to the environment variable,
1227 \fI\%ncurses\fP checks for an extended terminfo capability \fBU8\fP.
1228 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
1233 # linux console, if patched to provide working
1234 # VT100 shift\-in/shift\-out, with corresponding font.
1235 linux\-vt100|linux console with VT100 line\-graphics,
1238 # uxterm with vt100Graphics resource set to false
1239 xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
1244 The name \*(``U8\*('' is chosen to be two characters,
1245 to permit it to be used by applications that use \fI\%ncurses\fP'
1247 .SS "\fINCURSES_TRACE\fP"
1248 During initialization, the \fI\%ncurses\fP debugging library
1249 checks the \fI\%NCURSES_TRACE\fP environment variable.
1252 \fI\%ncurses\fP calls the \fBtrace\fP function,
1253 using that value as the argument.
1255 The argument values, which are defined in \fBcurses.h\fP, provide several
1256 types of information.
1257 When running with traces enabled, your application will write the
1258 file \fBtrace\fP to the current directory.
1260 See \fBcurs_trace\fP(3X) for more information.
1262 Denotes your terminal type.
1263 Each terminal type is distinct, though many are similar.
1265 \fITERM\fP is commonly set by terminal emulators to help
1266 applications find a workable terminal description.
1267 Some of those choose a popular approximation, e.g.,
1268 \*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
1269 Not infrequently, your application will have problems with that approach,
1270 e.g., incorrect function-key definitions.
1272 If you set \fITERM\fP in your environment,
1273 it has no effect on the operation of the terminal emulator.
1274 It only affects the way applications work within the terminal.
1275 Likewise, as a general rule (\fBxterm\fP(1) being a rare exception),
1276 terminal emulators which allow you to
1277 specify \fITERM\fP as a parameter or configuration value do
1278 not change their behavior to match that setting.
1280 If the \fI\%ncurses\fP library has been configured with \fItermcap\fP
1281 support, \fI\%ncurses\fP will check for a terminal's description in
1282 termcap form if it is not available in the terminfo database.
1284 The \fI\%TERMCAP\fP environment variable contains
1285 either a terminal description (with newlines stripped out),
1286 or a file name telling where the information denoted by
1287 the \fITERM\fP environment variable exists.
1288 In either case, setting it directs \fI\%ncurses\fP to ignore
1289 the usual place for this information, e.g., /etc/termcap.
1290 .SS "\fITERMINFO\fP"
1291 \fI\%ncurses\fP can be configured to read from multiple terminal
1293 The \fI\%TERMINFO\fP variable overrides the location for
1294 the default terminal database.
1295 Terminal descriptions (in terminal format) are stored in terminal databases:
1297 Normally these are stored in a directory tree,
1298 using subdirectories named by the first letter of the terminal names therein.
1300 This is the scheme used in System V, which legacy Unix systems use,
1301 and the \fI\%TERMINFO\fP variable is used by \fIcurses\fP applications
1303 systems to override the default location of the terminal database.
1305 If \fI\%ncurses\fP is built to use hashed databases,
1306 then each entry in this list may be the path of a hashed database file, e.g.,
1311 /usr/share/terminfo.db
1319 /usr/share/terminfo/
1323 The hashed database uses less disk-space and is a little faster than the
1326 some applications assume the existence of the directory tree,
1328 rather than using the terminfo library calls.
1331 If \fI\%ncurses\fP is built with a support for reading termcap files
1332 directly, then an entry in this list may be the path of a termcap file.
1334 If the \fI\%TERMINFO\fP variable begins with
1335 \*(``hex:\*('' or \*(``b64:\*('',
1336 \fI\%ncurses\fP uses the remainder of that variable as a compiled
1337 terminal description.
1338 You might produce the base64 format using \fBinfocmp\fP(1M):
1343 TERMINFO="$(infocmp \-0 \-Q2 \-q)"
1348 The compiled description is used if it corresponds to the terminal identified
1349 by the \fITERM\fP variable.
1352 Setting \fI\%TERMINFO\fP is the simplest,
1353 but not the only way to set location of the default terminal database.
1354 The complete list of database locations in order follows:
1357 the last terminal database to which \fI\%ncurses\fP wrote,
1358 if any, is searched first
1360 the location specified by the \fI\%TERMINFO\fP environment variable
1364 locations listed in the \fI\%TERMINFO_DIRS\fP environment variable
1366 one or more locations whose names are configured and compiled into the
1367 \fI\%ncurses\fP library, i.e.,
1370 @TERMINFO_DIRS@ (corresponding to the \fI\%TERMINFO_DIRS\fP variable)
1372 @TERMINFO@ (corresponding to the \fITERMINFO\fP variable)
1375 .SS "\fITERMINFO_DIRS\fP"
1376 Specifies a list of locations to search for terminal descriptions.
1377 Each location in the list is a terminal database as described in
1378 the section on the \fI\%TERMINFO\fP variable.
1379 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
1381 There is no corresponding feature in System V terminfo;
1382 it is an extension developed for \fI\%ncurses\fP.
1383 .SS "\fITERMPATH\fP"
1384 If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks
1385 the \fI\%TERMPATH\fP environment variable.
1386 This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
1387 semicolons on OS/2 EMX.
1389 If the \fI\%TERMPATH\fP environment variable is not set,
1390 \fI\%ncurses\fP looks in the files
1394 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
1400 The library may be configured to disregard the following variables when the
1401 current user is the superuser (root), or if the application uses setuid or
1406 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
1409 .SH "ALTERNATE CONFIGURATIONS"
1412 configurations are possible,
1413 determined by the options given to the
1415 script when building the library.
1416 Run the script with the
1418 option to peruse them all.
1419 A few are of particular significance to the application developer
1423 \-\-disable\-overwrite
1424 The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
1429 \fB#include <curses.h>\fP
1433 This option is used to avoid filename conflicts when \fI\%ncurses\fP
1434 is not the main implementation of curses of the computer.
1435 If \fI\%ncurses\fP is installed disabling overwrite,
1436 it puts its headers in a subdirectory,
1441 \fB#include <ncurses/curses.h>\fP
1445 It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
1446 to build executables.
1450 The configure script renames the library and
1451 (if the \fB\-\-disable\-overwrite\fP option is used)
1452 puts the header files in a different subdirectory.
1453 All of the library names have a \*(``w\*('' appended to them,
1471 You must also enable the wide-character features in the header file
1472 when compiling for the wide-character library
1473 to use the extended (wide-character) functions.
1474 The symbol which enables these features has changed since XSI Curses, Issue 4:
1476 Originally, the wide-character feature required the symbol
1477 \fB_XOPEN_SOURCE_EXTENDED\fP
1478 but that was only valid for XPG4 (1996).
1480 Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500.
1483 none of the features in this implementation require a \fB_XOPEN_SOURCE\fP
1484 feature greater than 600.
1485 However, X/Open Curses, Issue 7 (2009) recommends defining it to 700.
1487 Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP
1488 with the caveat that some other header file than \fBcurses.h\fP
1489 may require a specific value for \fB_XOPEN_SOURCE\fP
1490 (or a system-specific symbol).
1492 The \fI\%curses.h\fP header file installed for the wide-character
1493 library is designed to be compatible with the non-wide library's header.
1494 Only the size of the \fI\%WINDOW\fP structure differs;
1495 few applications require more than pointers to \fI\%WINDOW\fPs.
1497 If the headers are installed allowing overwrite,
1498 the wide-character library's headers should be installed last,
1499 to allow applications to be built using either library
1500 from the same set of headers.
1504 The configure script renames the library.
1505 All of the library names have a \*(``t\*('' appended to them
1506 (before any \*(``w\*('' added by \fB\-\-enable\-widec\fP).
1508 The global variables such as \fBLINES\fP are replaced by macros to
1509 allow read-only access.
1510 At the same time, setter-functions are provided to set these values.
1511 Some applications (very few) may require changes to work with this convention.
1520 The shared and normal (static) library names differ by their suffixes,
1521 e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP.
1522 The debug and profiling libraries add a \*(``_g\*(''
1523 and a \*(``_p\*('' to the root names respectively,
1524 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
1527 Low-level functions which do not depend upon whether the library
1528 supports wide-characters, are provided in the tinfo library.
1530 By doing this, it is possible to share the tinfo library between
1531 wide/normal configurations as well as reduce the size of the library
1532 when only low-level functions are needed.
1534 Those functions are described in these pages:
1537 \fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
1539 \fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
1541 \fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
1543 \fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
1545 \fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
1547 \fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
1550 \fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
1554 The \fBtrace\fP function normally resides in the debug library,
1555 but it is sometimes useful to configure this in the shared library.
1556 Configure scripts should check for the function's existence rather
1557 than assuming it is always in the debug library.
1561 tab stop initialization database
1564 compiled terminal capability database
1566 X/Open Curses permits most functions it specifies to be made available
1568 .\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
1569 .\" See X/Open Curses Issue 7, pp. 311-318.
1570 \fI\%ncurses\fP does so
1572 for functions that return values via their parameters,
1574 to support obsolete features,
1578 those that move the cursor before another operation),
1581 a few special cases.
1583 If the standard output file descriptor of an
1585 program is redirected to something that is not a terminal device,
1586 the library writes screen updates to the standard error file descriptor.
1587 This was an undocumented feature of SVr3.
1589 See subsection \*(``Header files\*('' below regarding symbols exposed by
1590 inclusion of \fI\%curses.h\fP.
1593 enables an application to capture mouse events on certain terminals,
1596 see \fB\%curs_mouse\fP(3X).
1599 provides a means of responding to window resizing events,
1600 as when running in a GUI terminal emulator application such as
1602 see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
1605 allows an application to query the terminal for the presence of a wide
1606 variety of special keys;
1607 see \fB\%has_key\fP(3X).
1610 extends the fixed set of function key capabilities specified by X/Open
1611 Curses by allowing the application programmer to define additional key
1612 sequences at runtime;
1614 \fB\%define_key\fP(3X),
1615 \fB\%key_defined\fP(3X),
1620 can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
1621 SGR\ 39 and SGR\ 49 sequences,
1622 which allow an application to reset the terminal to its original
1623 foreground and background colors.
1624 From a user's perspective,
1625 the application is able to draw colored text on a background whose color
1626 is set independently,
1627 providing better control over color contrasts.
1628 See \fB\%default_colors\fP(3X).
1632 application can choose to hide the internal details of
1635 instead using accessor functions such as
1636 \fB\%is_scrollok\fP(3X).
1639 enables an application to direct application output to a printer
1640 attached to the terminal device;
1641 see \fB\%curs_print\fP(3X).
1644 offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
1645 soft-label key lines,
1646 and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
1647 that can gather color information from them when many colors are
1650 Some extensions are only available if
1652 is compiled to support them;
1653 see section \*(``ALTERNATE CONFIGURATIONS\*('' above.
1655 Rudimentary support for multi-threaded applications may be available;
1656 see \fBcurs_threads\fP(3X).
1658 Functions that ease the management of multiple screens can be exposed;
1659 see \fBcurs_sp_funcs\fP(3X).
1663 causes the library to fall back to reading
1665 if the terminal setup code cannot find a
1667 entry corresponding to
1669 Use of this feature is not recommended,
1670 as it essentially includes an entire
1675 at a cost in memory usage and application launch latency.
1683 Individual man pages indicate where this is the case.
1685 X/Open Curses defines two levels of conformance,
1686 \*(``base\*('' and \*(``enhanced\*(''.
1687 The latter includes several additional features,
1688 such as wide-character and color support.
1690 intends base-level conformance with X/Open Curses,
1691 and supports nearly all its enhanced features.
1692 .\" XXX: What's missing? GBR counts untic(1), and that's all.
1694 Differences between X/Open Curses and
1696 are documented in the \*(``PORTABILITY\*('' sections of applicable man
1698 .SS "Error Checking"
1699 In many cases, X/Open Curses is vague about error conditions,
1700 omitting some of the SVr4 documentation.
1702 Unlike other implementations, this one checks parameters such as pointers
1703 to \fI\%WINDOW\fP structures to ensure they are not null.
1704 The main reason for providing this behavior is to guard against programmer
1706 The standard interface does not provide a way for the library
1707 to tell an application which of several possible errors were detected.
1708 Relying on this (or some other) extension will adversely affect the
1709 portability of curses applications.
1710 .SS "Padding Differences"
1711 In historic curses versions, delays embedded in the capabilities \fBcr\fP,
1712 \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay
1713 bits in the Unix tty driver.
1714 In this implementation, all padding is done by sending NUL bytes.
1715 This method is slightly more expensive, but narrows the interface
1716 to the Unix kernel significantly and increases the package's portability
1719 The header file \fI\%curses.h\fP itself includes the header files
1720 \fI\%stdio.h\fP and \fI\%unctrl.h\fP.
1722 X/Open Curses has more to say,
1723 but does not finish the story:
1726 The inclusion of <curses.h> may make visible all symbols
1727 from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
1730 Here is a more complete story:
1732 Starting with BSD curses, all implementations have included <stdio.h>.
1734 BSD curses included <curses.h> and <unctrl.h> from an internal header
1737 (\*(``ext\*('' abbreviated \*(``externs\*('').
1739 BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
1740 but nothing in <curses.h> itself relied upon <stdio.h>.
1742 SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>.
1743 That is, the function prototype uses \fBFILE\fP.
1745 SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>.
1747 X/Open Curses documents all three of these functions.
1749 SVr4 curses and X/Open Curses do not require the developer to
1750 include <stdio.h> before including <curses.h>.
1751 Both document curses showing <curses.h> as the only required header.
1753 As a result, standard <curses.h> will always include <stdio.h>.
1755 X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
1757 As noted in \fBcurs_util\fP(3X),
1758 \fI\%ncurses\fP includes <unctrl.h> from <curses.h>
1761 X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
1763 HP-UX curses includes <term.h> from <curses.h>
1764 to declare \fBsetupterm\fP in curses.h,
1765 but \fI\%ncurses\fP (and Solaris curses) do not.
1767 AIX curses includes <term.h> and <termios.h>.
1768 Again, \fI\%ncurses\fP (and Solaris curses) do not.
1770 X/Open says that <curses.h> \fImay\fP include <term.h>,
1771 but there is no requirement that it do that.
1773 Some programs use functions declared in both <curses.h> and <term.h>,
1774 and must include both headers in the same module.
1775 Very old versions of AIX curses required including <curses.h>
1776 before including <term.h>.
1778 Because \fI\%ncurses\fP header files include the headers needed to
1779 define datatypes used in the headers,
1780 \fI\%ncurses\fP header files can be included in any order.
1781 But for portability, you should include <curses.h> before <term.h>.
1783 X/Open Curses says \fI"may make visible"\fP
1784 because including a header file does not necessarily make all symbols
1785 in it visible (there are ifdef's to consider).
1787 For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if
1788 the proper symbol is defined, and if \fI\%ncurses\fP is configured for
1789 wide-character support.
1790 If the header is included, its symbols may be made visible.
1791 That depends on the value used for \fB_XOPEN_SOURCE\fP
1794 X/Open Curses documents one required header,
1795 in a special case: <stdarg.h> before <curses.h> to prototype
1796 the \fBvw_printw\fP and \fBvw_scanw\fP functions
1797 (as well as the obsolete
1798 the \fBvwprintw\fP and \fBvwscanw\fP functions).
1799 Each of those uses a \fBva_list\fP parameter.
1801 The two obsolete functions were introduced in SVr3.
1802 The other functions were introduced in X/Open Curses.
1803 In between, SVr4 curses provided for the possibility that
1804 an application might include either <varargs.h> or <stdarg.h>.
1805 Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP
1807 Later, a special type (defined in <stdio.h>) was introduced,
1808 to allow for compiler type-checking.
1809 That special type is always available,
1810 because <stdio.h> is always included by <curses.h>.
1812 None of the X/Open Curses implementations require an application
1813 to include <stdarg.h> before <curses.h> because they either
1814 have allowed for a special type,
1816 (like \fI\%ncurses\fP)
1817 include <stdarg.h> directly to provide a portable interface.
1819 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1820 Based on \fIpcurses\fP by Pavel Curtis.
1822 \fB\%curs_variables\fP(3X),
1823 \fB\%terminfo\fP(5),
1824 \fB\%user_caps\fP(5)