diff options
Diffstat (limited to 'upstream/fedora-40/man3/ncurses.3x')
| -rw-r--r-- | upstream/fedora-40/man3/ncurses.3x | 1800 |
1 files changed, 1800 insertions, 0 deletions
diff --git a/upstream/fedora-40/man3/ncurses.3x b/upstream/fedora-40/man3/ncurses.3x new file mode 100644 index 00000000..a56ca82c --- /dev/null +++ b/upstream/fedora-40/man3/ncurses.3x @@ -0,0 +1,1800 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: ncurses.3x,v 1.197 2024/01/13 20:30:39 tom Exp $ +.TH ncurses 3X 2024-01-13 "ncurses 6.4" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. +.ds d /usr/share/terminfo +.SH NAME +\fB\%ncurses\fP \- +character-cell terminal interface with optimized output +.SH SYNOPSIS +.nf +\fB#include <curses.h> +.fi +.SH DESCRIPTION +The \fI\%ncurses\fP library routines give the user a +terminal-independent method of updating character screens with +reasonable optimization. +This implementation is \*(``new curses\*('' (\fI\%ncurses\fP) and +is the approved replacement for +4.4BSD classic curses, which has been discontinued. +This describes \fI\%ncurses\fP +version 6.4 (patch 20240127). +.PP +The \fI\%ncurses\fP library emulates the curses library of +System V Release 4 Unix (\*(``SVr4\*(''), +and XPG4 (X/Open Portability Guide) curses (also known as XSI curses). +XSI stands for X/Open System Interfaces Extension. +The \fI\%ncurses\fP library is freely redistributable in source form. +.PP +\fI\%ncurses\fP man pages employ several sections to clarify matters of +usage and interoperability with other \fIcurses\fP implementations. +.bP +\*(``NOTES\*('' describes matters and caveats of which any user of the +\fI\%ncurses\fP API should be aware, +such as limitations on the size of an underlying integral type or the +availability of a preprocessor macro exclusive of a function definition +(which prevents its address from being taken). +This section also describes implementation details that will be +significant to the programmer but which are not standardized. +.bP +\*(``EXTENSIONS\*('' presents \fI\%ncurses\fP innovations beyond the +X/Open Curses standard and/or the SVr4 \fIcurses\fP implementation. +They are termed \fIextensions\fP to indicate that they cannot be +implemented solely by using the library API, but require access to the +library's internal state. +.bP +\*(``PORTABILITY\*('' discusses matters +(beyond the exercise of extensions) +that should be considered when writing to a \fIcurses\fP standard, +or to multiple implementations. +.bP +\*(``HISTORY\*('' examines points of detail in \fI\%ncurses\fP and other +\fIcurses\fP implementations over the decades of their development, +particularly where precedent or inertia have frustrated better design +(and, +in a few cases, +where such inertia has been overcome). +.PP +A program using these routines must be linked with the \fB\-lncurses\fP option, +or (if it has been generated) with the debugging library \fB\-lncurses_g\fP. +(Your system integrator may also have installed these libraries under +the names \fB\-lcurses\fP and \fB\-lcurses_g\fP.) +The ncurses_g library generates trace logs +(in a file called \*(``trace\*('' in the current directory) +that describe curses actions. +See section \*(``ALTERNATE CONFIGURATIONS\*('' below. +.PP +The \fI\%ncurses\fP package supports: overall screen, window and pad +manipulation; output to windows and pads; reading terminal input; control over +terminal and \fBcurses\fP input and output options; environment query +routines; color manipulation; use of soft label keys; terminfo capabilities; +and access to low-level terminal-manipulation routines. +.SS Initialization +The library uses the locale which the calling program has initialized. +That is normally done with \fBsetlocale\fP(3): +.PP +.RS 4 +.EX +\fBsetlocale(LC_ALL, "");\fP +.EE +.RE +.PP +If the locale is not initialized, +the library assumes that characters are printable as in ISO\-8859\-1, +to work with certain legacy programs. +You should initialize the locale and not rely on specific details of +the library when the locale has not been setup. +.PP +The function \fBinitscr\fP or \fBnewterm\fP +must be called to initialize the library +before any of the other routines that deal with windows +and screens are used. +The routine \fBendwin\fP(3X) must be called before exiting. +.PP +To get character-at-a-time input without echoing (most +interactive, screen oriented programs want this), the following +sequence should be used: +.PP +.RS 4 +.EX +\fBinitscr(); cbreak(); noecho();\fP +.EE +.RE +.PP +Most programs would additionally use the sequence: +.PP +.RS 4 +.EX +\fBintrflush(stdscr, FALSE);\fP +\fBkeypad(stdscr, TRUE);\fP +.EE +.RE +.PP +Before a \fBcurses\fP program is run, the tab stops of the terminal +should be set and its initialization strings, if defined, must be output. +This can be done by executing the \fBtput init\fP command +after the shell environment variable \fITERM\fP has been exported. +(The BSD-style \fB\%tset\fP(1) utility also performs this function.) +See subsection \*(``Tabs and Initialization\*('' of \fBterminfo\fP(5). +.SS Overview +A +.I curses +library abstracts the terminal screen by representing all or part of it +as a +.I \%WINDOW +data structure. +A +.I window +is a rectangular grid of character cells, +addressed by row and column coordinates +.RI ( y , +.IR x ), +with the upper left corner as (0, 0). +A window called \fB\%stdscr\fP, +the same size as the terminal screen, +is always available. +Create others with \fB\%newwin\fP(3X). +.PP +A +.I curses +library does not manage overlapping windows. +(See \fBpanel\fP(3X) if you desire this.) +You can either use \fB\%stdscr\fP to manage one screen-filling window, +or tile the screen into non-overlapping windows and not use +\fB\%stdscr\fP at all. +Mixing the two approaches will result in unpredictable, +and undesired, +effects. +.PP +Functions permit manipulation of a window and the +.I cursor +identifying the cell within it at which the next output operation will +occur. +Among those, +the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X): +these place the cursor and write a character to +.BR \%stdscr , +respectively. +As a rule, +window-addressing functions feature names prefixed +(or infixed, +see below) +with \*(``w\*(''; +these allow the user to specify a pointer to a +.I \%WINDOW. +Counterparts not thus prefixed +(or infixed) +affect \fB\%stdscr\fP. +Because moving the cursor prior to another operation is so common, +.I curses +generally also provides functions with a \*(``mv\*('' prefix as a +convenience. +Thus, +the library defines all of +\fB\%addch\fP, +\fB\%waddch\fP, +\fB\%mvaddch\fP, +and +\fB\%mvwaddch\fP. +When both prefixes are present, +the order of arguments is a +.I \%WINDOW +pointer first, +then a +.I y +and +.I x +coordinate pair. +.PP +Updating the terminal screen with every +.I curses +call can cause unpleasant flicker or inefficient use of the +communications channel to the device. +Therefore, +after using +.I curses +functions to accumulate a set of desired updates that make sense to +present together, +call \fB\%refresh\fP(3X) to tell the library to make the user's screen +look like \fBstdscr\fP. +.I \%ncurses +.\" X/Open Curses Issue 7 assumes some optimization will be done, but +.\" does not mandate it in any way. +.I optimizes +its output by computing a minimal number of operations to mutate the +screen from its state at the previous refresh to the new one. +Effective optimization demands accurate information about the terminal +device: +the management of such information is the province of the +\fB\%terminfo\fP(3X) API, +a feature of every standard +.I curses +implementation. +.PP +Special windows called \fIpads\fP may also be manipulated. +These are windows that are not constrained to the size of the terminal +screen and whose contents need not be completely displayed. +See \fB\%curs_pad\fP(3X). +.PP +In addition to drawing characters on the screen, +rendering attributes and colors may be supported, +causing the characters to show up in such modes as underlined, +in reverse video, +or in color on terminals that support such display enhancements. +See \fB\%curs_attr\fP(3X). +.PP +.I curses +predefines constants for a small set of line-drawing and other graphics +corresponding to the DEC Alternate Character Set (ACS), +a feature of VT100 and other terminals. +See +\fB\%waddch\fP(3X) and +\fB\%wadd_wch\fP(3X). +.PP +.I curses +is implemented using the operating system's terminal driver; +keystroke events are received not as scan codes but as byte sequences. +Graphical keycaps +(alphanumeric and punctuation keys, +and the space) +appear as-is. +Everything else, +including the tab, +enter/return, +keypad, +arrow, +and function keys, +appears as a control character or a multibyte +.I "escape sequence." +.I curses +translates these into unique +.I "key codes." +See \fB\%getch\fP(3X). +.SS "Effects of GUIs and Environment Variables" +The selection of an appropriate value of +.I TERM +in the process environment is essential to correct +.I curses +and +.I \%term\%info +library operation. +A well-configured system selects a correct +.I TERM +value automatically; +\fB\%tset\fP(1) may assist with troubleshooting exotic situations. +.PP +If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set, +or if the +.I curses +program is executing in a graphical windowing environment, +the information obtained thence overrides that obtained by +.IR \%term\%info . +An +.I \%ncurses +extension supports resizable terminals; +see \fB\%wresize\fP(3X). +.PP +If the environment variable \fI\%TERMINFO\fP is defined, +a +.I curses +program checks first for a terminal type description in the location it +identifies. +.I \%TERMINFO +is useful for developing experimental type descriptions or when write +permission to \fI\*d\fP is not available. +.PP +See section \*(``ENVIRONMENT\*('' below. +.SS "Naming Conventions" +Many +.I curses +functions have two or more versions. +Those prefixed with \*(``w\*('' require a window argument. +Four functions prefixed with \*(``p\*('' require a pad argument. +Those without a prefix generally operate on \fB\%stdscr\fP. +.PP +In function synopses, +.I \%ncurses +man pages apply the following names to parameters. +.PP +.TS +center; +Li L. +bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP) +win pointer to \fIWINDOW\fP +pad pointer to \fIWINDOW\fP that is a pad +.TE +.SS "Wide and Non-wide Character Configurations" +This manual page describes functions that appear in any configuration +of the library. +There are two common configurations; +see section \*(``ALTERNATE CONFIGURATIONS\*('' below. +.TP 10 \" "ncursesw" + 2n +.I \%ncurses +is the library in its \*(``non-wide\*('' configuration, +handling only eight-bit characters. +It stores a character combined with attributes in a +.I \%chtype +datum, +which is often an alias of +.I int. +.IP +Attributes alone +(with no corresponding character) +can be stored in variables of +.I \%chtype +or +.I \%attr_t +type. +In either case, +they are represented as an integral bit mask. +.IP +Each cell of a +.I \%WINDOW +is stored as a +.I \%chtype. +.TP 10 +.I \%ncursesw +is the library in its \*(``wide\*('' configuration, +which handles character encodings requiring a larger data type than +.I \%char +(a byte-sized type) +can represent. +It adds about one third more calls using additional data types that +can store such +.I multibyte +characters. +.RS 10 \" same as foregoing tag width +.TP 9 \" "cchar_t" + 2n +.I \%cchar_t +corresponds to the non-wide configuration's +.I \%chtype. +It always a structure type, +because it stores more data than fits into an integral type. +A character code may not be representable as a +.I \%char, +and moreover more than one character may occupy a cell +(as with accent marks and other diacritics). +Each character is of type +.I \%wchar_t; +a complex character contains one spacing character and zero or more +non-spacing characters +(see below). +Attributes and color data are stored in separate fields of the +structure, +not combined as in +.I \%chtype. +.PP +Each cell of a +.I \%WINDOW +is stored as a +.I \%cchar_t. +.PP +The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X) +functions store and retrieve the data from a +.I \%cchar_t +structure. +The wide library API of +.I \%ncurses +depends on two data types standardized by ISO C95. +.TP 9 +.I \%wchar_t +stores a wide character. +Like +.I \%chtype, +it may be an alias of +.I int. +Depending on the character encoding, +a wide character may be +.I spacing, +meaning that it occupies a character cell by itself and typically +accompanies cursor advancement, +or +.I non-spacing, +meaning that it occupies the same cell as a spacing character, +is often regarded as a \*(``modifier\*('' of the base glyph with which +it combines, +and typically does not advance the cursor. +.TP 9 +.I \%wint_t +can store a +.I \%wchar_t +or the constant +.BR \%WEOF , +analogously to the +.IR int -sized +character manipulation functions of ISO C and its constant +.BR \%EOF . +.RE +.IP +The wide library provides additional functions that complement those in +the non-wide library where the size of the underlying character type is +significant. +A somewhat regular naming convention relates many of the wide variants +to their non-wide counterparts; +where a non-wide function name contains \*(``ch\*('' or \*(``str\*('', +prefix it with \*(``_w\*('' to obtain the wide counterpart. +For example, +\fB\%waddch\fP becomes \fB\%wadd_wch\fP. +.IP +This convention is inapplicable to some non-wide function names, +so other transformations are used for the wide configuration: +in the window background management functions, +\*(``bkgd\*('' becomes \*(``bkgrnd\*(''; +the window border-drawing and -clearing functions are suffixed with +\*(``_set\*(''. +.\" +.SS "Function Name Index" +The following table lists the +.I curses +functions provided in the non-wide and wide APIs and the corresponding +man pages that describe them. +Those flagged with \*(``*\*('' +are +.IR \%ncurses -specific, +neither described by X/Open Curses nor present in SVr4. +.PP +.TS +center tab(/); +l l . +\f(BIcurses\fP Function Name/Man Page +_ +COLOR_PAIR/\fBcurs_color\fP(3X) +PAIR_NUMBER/\fBcurs_color\fP(3X) +add_wch/\fBcurs_add_wch\fP(3X) +add_wchnstr/\fBcurs_add_wchstr\fP(3X) +add_wchstr/\fBcurs_add_wchstr\fP(3X) +addch/\fBcurs_addch\fP(3X) +addchnstr/\fBcurs_addchstr\fP(3X) +addchstr/\fBcurs_addchstr\fP(3X) +addnstr/\fBcurs_addstr\fP(3X) +addnwstr/\fBcurs_addwstr\fP(3X) +addstr/\fBcurs_addstr\fP(3X) +addwstr/\fBcurs_addwstr\fP(3X) +alloc_pair/\fBnew_pair\fP(3X)* +assume_default_colors/\fBdefault_colors\fP(3X)* +attr_get/\fBcurs_attr\fP(3X) +attr_off/\fBcurs_attr\fP(3X) +attr_on/\fBcurs_attr\fP(3X) +attr_set/\fBcurs_attr\fP(3X) +attroff/\fBcurs_attr\fP(3X) +attron/\fBcurs_attr\fP(3X) +attrset/\fBcurs_attr\fP(3X) +baudrate/\fBcurs_termattrs\fP(3X) +beep/\fBcurs_beep\fP(3X) +bkgd/\fBcurs_bkgd\fP(3X) +bkgdset/\fBcurs_bkgd\fP(3X) +bkgrnd/\fBcurs_bkgrnd\fP(3X) +bkgrndset/\fBcurs_bkgrnd\fP(3X) +border/\fBcurs_border\fP(3X) +border_set/\fBcurs_border_set\fP(3X) +box/\fBcurs_border\fP(3X) +box_set/\fBcurs_border_set\fP(3X) +can_change_color/\fBcurs_color\fP(3X) +cbreak/\fBcurs_inopts\fP(3X) +chgat/\fBcurs_attr\fP(3X) +clear/\fBcurs_clear\fP(3X) +clearok/\fBcurs_outopts\fP(3X) +clrtobot/\fBcurs_clear\fP(3X) +clrtoeol/\fBcurs_clear\fP(3X) +color_content/\fBcurs_color\fP(3X) +color_set/\fBcurs_attr\fP(3X) +copywin/\fBcurs_overlay\fP(3X) +curs_set/\fBcurs_kernel\fP(3X) +curses_trace/\fBcurs_trace\fP(3X)* +curses_version/\fBcurs_extend\fP(3X)* +def_prog_mode/\fBcurs_kernel\fP(3X) +def_shell_mode/\fBcurs_kernel\fP(3X) +define_key/\fBdefine_key\fP(3X)* +del_curterm/\fBcurs_terminfo\fP(3X) +delay_output/\fBcurs_util\fP(3X) +delch/\fBcurs_delch\fP(3X) +deleteln/\fBcurs_deleteln\fP(3X) +delscreen/\fBcurs_initscr\fP(3X) +delwin/\fBcurs_window\fP(3X) +derwin/\fBcurs_window\fP(3X) +doupdate/\fBcurs_refresh\fP(3X) +dupwin/\fBcurs_window\fP(3X) +echo/\fBcurs_inopts\fP(3X) +echo_wchar/\fBcurs_add_wch\fP(3X) +echochar/\fBcurs_addch\fP(3X) +endwin/\fBcurs_initscr\fP(3X) +erase/\fBcurs_clear\fP(3X) +erasechar/\fBcurs_termattrs\fP(3X) +erasewchar/\fBcurs_termattrs\fP(3X) +exit_curses/\fBcurs_memleaks\fP(3X)* +exit_terminfo/\fBcurs_memleaks\fP(3X)* +extended_color_content/\fBcurs_color\fP(3X)* +extended_pair_content/\fBcurs_color\fP(3X)* +extended_slk_color/\fBcurs_slk\fP(3X)* +filter/\fBcurs_util\fP(3X) +find_pair/\fBnew_pair\fP(3X)* +flash/\fBcurs_beep\fP(3X) +flushinp/\fBcurs_util\fP(3X) +free_pair/\fBnew_pair\fP(3X)* +get_wch/\fBcurs_get_wch\fP(3X) +get_wstr/\fBcurs_get_wstr\fP(3X) +getattrs/\fBcurs_attr\fP(3X) +getbegx/\fBcurs_legacy\fP(3X)* +getbegy/\fBcurs_legacy\fP(3X)* +getbegyx/\fBcurs_getyx\fP(3X) +getbkgd/\fBcurs_bkgd\fP(3X) +getbkgrnd/\fBcurs_bkgrnd\fP(3X) +getcchar/\fBcurs_getcchar\fP(3X) +getch/\fBcurs_getch\fP(3X) +getcurx/\fBcurs_legacy\fP(3X)* +getcury/\fBcurs_legacy\fP(3X)* +getmaxx/\fBcurs_legacy\fP(3X)* +getmaxy/\fBcurs_legacy\fP(3X)* +getmaxyx/\fBcurs_getyx\fP(3X) +getmouse/\fBcurs_mouse\fP(3X)* +getn_wstr/\fBcurs_get_wstr\fP(3X) +getnstr/\fBcurs_getstr\fP(3X) +getparx/\fBcurs_legacy\fP(3X)* +getpary/\fBcurs_legacy\fP(3X)* +getparyx/\fBcurs_getyx\fP(3X) +getstr/\fBcurs_getstr\fP(3X) +getsyx/\fBcurs_kernel\fP(3X) +getwin/\fBcurs_util\fP(3X) +getyx/\fBcurs_getyx\fP(3X) +halfdelay/\fBcurs_inopts\fP(3X) +has_colors/\fBcurs_color\fP(3X) +has_ic/\fBcurs_termattrs\fP(3X) +has_il/\fBcurs_termattrs\fP(3X) +has_key/\fBcurs_getch\fP(3X)* +has_mouse/\fBcurs_mouse\fP(3X)* +hline/\fBcurs_border\fP(3X) +hline_set/\fBcurs_border_set\fP(3X) +idcok/\fBcurs_outopts\fP(3X) +idlok/\fBcurs_outopts\fP(3X) +immedok/\fBcurs_outopts\fP(3X) +in_wch/\fBcurs_in_wch\fP(3X) +in_wchnstr/\fBcurs_in_wchstr\fP(3X) +in_wchstr/\fBcurs_in_wchstr\fP(3X) +inch/\fBcurs_inch\fP(3X) +inchnstr/\fBcurs_inchstr\fP(3X) +inchstr/\fBcurs_inchstr\fP(3X) +init_color/\fBcurs_color\fP(3X) +init_extended_color/\fBcurs_color\fP(3X)* +init_extended_pair/\fBcurs_color\fP(3X)* +init_pair/\fBcurs_color\fP(3X) +initscr/\fBcurs_initscr\fP(3X) +innstr/\fBcurs_instr\fP(3X) +innwstr/\fBcurs_inwstr\fP(3X) +ins_nwstr/\fBcurs_ins_wstr\fP(3X) +ins_wch/\fBcurs_ins_wch\fP(3X) +ins_wstr/\fBcurs_ins_wstr\fP(3X) +insch/\fBcurs_insch\fP(3X) +insdelln/\fBcurs_deleteln\fP(3X) +insertln/\fBcurs_deleteln\fP(3X) +insnstr/\fBcurs_insstr\fP(3X) +insstr/\fBcurs_insstr\fP(3X) +instr/\fBcurs_instr\fP(3X) +intrflush/\fBcurs_inopts\fP(3X) +inwstr/\fBcurs_inwstr\fP(3X) +is_cbreak/\fBcurs_inopts\fP(3X)* +is_cleared/\fBcurs_opaque\fP(3X)* +is_echo/\fBcurs_inopts\fP(3X)* +is_idcok/\fBcurs_opaque\fP(3X)* +is_idlok/\fBcurs_opaque\fP(3X)* +is_immedok/\fBcurs_opaque\fP(3X)* +is_keypad/\fBcurs_opaque\fP(3X)* +is_leaveok/\fBcurs_opaque\fP(3X)* +is_linetouched/\fBcurs_touch\fP(3X) +is_nl/\fBcurs_inopts\fP(3X)* +is_nodelay/\fBcurs_opaque\fP(3X)* +is_notimeout/\fBcurs_opaque\fP(3X)* +is_pad/\fBcurs_opaque\fP(3X)* +is_raw/\fBcurs_inopts\fP(3X)* +is_scrollok/\fBcurs_opaque\fP(3X)* +is_subwin/\fBcurs_opaque\fP(3X)* +is_syncok/\fBcurs_opaque\fP(3X)* +is_term_resized/\fBresizeterm\fP(3X)* +is_wintouched/\fBcurs_touch\fP(3X) +isendwin/\fBcurs_initscr\fP(3X) +key_defined/\fBkey_defined\fP(3X)* +key_name/\fBcurs_util\fP(3X) +keybound/\fBkeybound\fP(3X)* +keyname/\fBcurs_util\fP(3X) +keyok/\fBkeyok\fP(3X)* +keypad/\fBcurs_inopts\fP(3X) +killchar/\fBcurs_termattrs\fP(3X) +killwchar/\fBcurs_termattrs\fP(3X) +leaveok/\fBcurs_outopts\fP(3X) +longname/\fBcurs_termattrs\fP(3X) +mcprint/\fBcurs_print\fP(3X)* +meta/\fBcurs_inopts\fP(3X) +mouse_trafo/\fBcurs_mouse\fP(3X)* +mouseinterval/\fBcurs_mouse\fP(3X)* +mousemask/\fBcurs_mouse\fP(3X)* +move/\fBcurs_move\fP(3X) +mvadd_wch/\fBcurs_add_wch\fP(3X) +mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X) +mvadd_wchstr/\fBcurs_add_wchstr\fP(3X) +mvaddch/\fBcurs_addch\fP(3X) +mvaddchnstr/\fBcurs_addchstr\fP(3X) +mvaddchstr/\fBcurs_addchstr\fP(3X) +mvaddnstr/\fBcurs_addstr\fP(3X) +mvaddnwstr/\fBcurs_addwstr\fP(3X) +mvaddstr/\fBcurs_addstr\fP(3X) +mvaddwstr/\fBcurs_addwstr\fP(3X) +mvchgat/\fBcurs_attr\fP(3X) +mvcur/\fBcurs_terminfo\fP(3X) +mvdelch/\fBcurs_delch\fP(3X) +mvderwin/\fBcurs_window\fP(3X) +mvget_wch/\fBcurs_get_wch\fP(3X) +mvget_wstr/\fBcurs_get_wstr\fP(3X) +mvgetch/\fBcurs_getch\fP(3X) +mvgetn_wstr/\fBcurs_get_wstr\fP(3X) +mvgetnstr/\fBcurs_getstr\fP(3X) +mvgetstr/\fBcurs_getstr\fP(3X) +mvhline/\fBcurs_border\fP(3X) +mvhline_set/\fBcurs_border_set\fP(3X) +mvin_wch/\fBcurs_in_wch\fP(3X) +mvin_wchnstr/\fBcurs_in_wchstr\fP(3X) +mvin_wchstr/\fBcurs_in_wchstr\fP(3X) +mvinch/\fBcurs_inch\fP(3X) +mvinchnstr/\fBcurs_inchstr\fP(3X) +mvinchstr/\fBcurs_inchstr\fP(3X) +mvinnstr/\fBcurs_instr\fP(3X) +mvinnwstr/\fBcurs_inwstr\fP(3X) +mvins_nwstr/\fBcurs_ins_wstr\fP(3X) +mvins_wch/\fBcurs_ins_wch\fP(3X) +mvins_wstr/\fBcurs_ins_wstr\fP(3X) +mvinsch/\fBcurs_insch\fP(3X) +mvinsnstr/\fBcurs_insstr\fP(3X) +mvinsstr/\fBcurs_insstr\fP(3X) +mvinstr/\fBcurs_instr\fP(3X) +mvinwstr/\fBcurs_inwstr\fP(3X) +mvprintw/\fBcurs_printw\fP(3X) +mvscanw/\fBcurs_scanw\fP(3X) +mvvline/\fBcurs_border\fP(3X) +mvvline_set/\fBcurs_border_set\fP(3X) +mvwadd_wch/\fBcurs_add_wch\fP(3X) +mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X) +mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X) +mvwaddch/\fBcurs_addch\fP(3X) +mvwaddchnstr/\fBcurs_addchstr\fP(3X) +mvwaddchstr/\fBcurs_addchstr\fP(3X) +mvwaddnstr/\fBcurs_addstr\fP(3X) +mvwaddnwstr/\fBcurs_addwstr\fP(3X) +mvwaddstr/\fBcurs_addstr\fP(3X) +mvwaddwstr/\fBcurs_addwstr\fP(3X) +mvwchgat/\fBcurs_attr\fP(3X) +mvwdelch/\fBcurs_delch\fP(3X) +mvwget_wch/\fBcurs_get_wch\fP(3X) +mvwget_wstr/\fBcurs_get_wstr\fP(3X) +mvwgetch/\fBcurs_getch\fP(3X) +mvwgetn_wstr/\fBcurs_get_wstr\fP(3X) +mvwgetnstr/\fBcurs_getstr\fP(3X) +mvwgetstr/\fBcurs_getstr\fP(3X) +mvwhline/\fBcurs_border\fP(3X) +mvwhline_set/\fBcurs_border_set\fP(3X) +mvwin/\fBcurs_window\fP(3X) +mvwin_wch/\fBcurs_in_wch\fP(3X) +mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X) +mvwin_wchstr/\fBcurs_in_wchstr\fP(3X) +mvwinch/\fBcurs_inch\fP(3X) +mvwinchnstr/\fBcurs_inchstr\fP(3X) +mvwinchstr/\fBcurs_inchstr\fP(3X) +mvwinnstr/\fBcurs_instr\fP(3X) +mvwinnwstr/\fBcurs_inwstr\fP(3X) +mvwins_nwstr/\fBcurs_ins_wstr\fP(3X) +mvwins_wch/\fBcurs_ins_wch\fP(3X) +mvwins_wstr/\fBcurs_ins_wstr\fP(3X) +mvwinsch/\fBcurs_insch\fP(3X) +mvwinsnstr/\fBcurs_insstr\fP(3X) +mvwinsstr/\fBcurs_insstr\fP(3X) +mvwinstr/\fBcurs_instr\fP(3X) +mvwinwstr/\fBcurs_inwstr\fP(3X) +mvwprintw/\fBcurs_printw\fP(3X) +mvwscanw/\fBcurs_scanw\fP(3X) +mvwvline/\fBcurs_border\fP(3X) +mvwvline_set/\fBcurs_border_set\fP(3X) +napms/\fBcurs_kernel\fP(3X) +newpad/\fBcurs_pad\fP(3X) +newterm/\fBcurs_initscr\fP(3X) +newwin/\fBcurs_window\fP(3X) +nl/\fBcurs_inopts\fP(3X) +nocbreak/\fBcurs_inopts\fP(3X) +nodelay/\fBcurs_inopts\fP(3X) +noecho/\fBcurs_inopts\fP(3X) +nofilter/\fBcurs_util\fP(3X)* +nonl/\fBcurs_inopts\fP(3X) +noqiflush/\fBcurs_inopts\fP(3X) +noraw/\fBcurs_inopts\fP(3X) +notimeout/\fBcurs_inopts\fP(3X) +overlay/\fBcurs_overlay\fP(3X) +overwrite/\fBcurs_overlay\fP(3X) +pair_content/\fBcurs_color\fP(3X) +pecho_wchar/\fBcurs_pad\fP(3X) +pechochar/\fBcurs_pad\fP(3X) +pnoutrefresh/\fBcurs_pad\fP(3X) +prefresh/\fBcurs_pad\fP(3X) +printw/\fBcurs_printw\fP(3X) +putp/\fBcurs_terminfo\fP(3X) +putwin/\fBcurs_util\fP(3X) +qiflush/\fBcurs_inopts\fP(3X) +raw/\fBcurs_inopts\fP(3X) +redrawwin/\fBcurs_refresh\fP(3X) +refresh/\fBcurs_refresh\fP(3X) +reset_color_pairs/\fBcurs_color\fP(3X)* +reset_prog_mode/\fBcurs_kernel\fP(3X) +reset_shell_mode/\fBcurs_kernel\fP(3X) +resetty/\fBcurs_kernel\fP(3X) +resize_term/\fBresizeterm\fP(3X)* +resizeterm/\fBresizeterm\fP(3X)* +restartterm/\fBcurs_terminfo\fP(3X) +ripoffline/\fBcurs_kernel\fP(3X) +savetty/\fBcurs_kernel\fP(3X) +scanw/\fBcurs_scanw\fP(3X) +scr_dump/\fBcurs_scr_dump\fP(3X) +scr_init/\fBcurs_scr_dump\fP(3X) +scr_restore/\fBcurs_scr_dump\fP(3X) +scr_set/\fBcurs_scr_dump\fP(3X) +scrl/\fBcurs_scroll\fP(3X) +scroll/\fBcurs_scroll\fP(3X) +scrollok/\fBcurs_outopts\fP(3X) +set_curterm/\fBcurs_terminfo\fP(3X) +set_term/\fBcurs_initscr\fP(3X) +setcchar/\fBcurs_getcchar\fP(3X) +setscrreg/\fBcurs_outopts\fP(3X) +setsyx/\fBcurs_kernel\fP(3X) +setupterm/\fBcurs_terminfo\fP(3X) +slk_attr/\fBcurs_slk\fP(3X)* +slk_attr_off/\fBcurs_slk\fP(3X) +slk_attr_on/\fBcurs_slk\fP(3X) +slk_attr_set/\fBcurs_slk\fP(3X) +slk_attroff/\fBcurs_slk\fP(3X) +slk_attron/\fBcurs_slk\fP(3X) +slk_attrset/\fBcurs_slk\fP(3X) +slk_clear/\fBcurs_slk\fP(3X) +slk_color/\fBcurs_slk\fP(3X) +slk_init/\fBcurs_slk\fP(3X) +slk_label/\fBcurs_slk\fP(3X) +slk_noutrefresh/\fBcurs_slk\fP(3X) +slk_refresh/\fBcurs_slk\fP(3X) +slk_restore/\fBcurs_slk\fP(3X) +slk_set/\fBcurs_slk\fP(3X) +slk_touch/\fBcurs_slk\fP(3X) +slk_wset/\fBcurs_slk\fP(3X) +standend/\fBcurs_attr\fP(3X) +standout/\fBcurs_attr\fP(3X) +start_color/\fBcurs_color\fP(3X) +subpad/\fBcurs_pad\fP(3X) +subwin/\fBcurs_window\fP(3X) +syncok/\fBcurs_window\fP(3X) +term_attrs/\fBcurs_termattrs\fP(3X) +termattrs/\fBcurs_termattrs\fP(3X) +termname/\fBcurs_termattrs\fP(3X) +tgetent/\fBcurs_termcap\fP(3X) +tgetflag/\fBcurs_termcap\fP(3X) +tgetnum/\fBcurs_termcap\fP(3X) +tgetstr/\fBcurs_termcap\fP(3X) +tgoto/\fBcurs_termcap\fP(3X) +tigetflag/\fBcurs_terminfo\fP(3X) +tigetnum/\fBcurs_terminfo\fP(3X) +tigetstr/\fBcurs_terminfo\fP(3X) +timeout/\fBcurs_inopts\fP(3X) +tiparm/\fBcurs_terminfo\fP(3X) +tiparm_s/\fBcurs_terminfo\fP(3X)* +tiscan_s/\fBcurs_terminfo\fP(3X)* +touchline/\fBcurs_touch\fP(3X) +touchwin/\fBcurs_touch\fP(3X) +tparm/\fBcurs_terminfo\fP(3X) +tputs/\fBcurs_termcap\fP(3X) +tputs/\fBcurs_terminfo\fP(3X) +trace/\fBcurs_trace\fP(3X)* +typeahead/\fBcurs_inopts\fP(3X) +unctrl/\fBcurs_util\fP(3X) +unget_wch/\fBcurs_get_wch\fP(3X) +ungetch/\fBcurs_getch\fP(3X) +ungetmouse/\fBcurs_mouse\fP(3X)* +untouchwin/\fBcurs_touch\fP(3X) +use_default_colors/\fBdefault_colors\fP(3X)* +use_env/\fBcurs_util\fP(3X) +use_extended_names/\fBcurs_extend\fP(3X)* +use_legacy_coding/\fBlegacy_coding\fP(3X)* +use_tioctl/\fBcurs_util\fP(3X)* +vid_attr/\fBcurs_terminfo\fP(3X) +vid_puts/\fBcurs_terminfo\fP(3X) +vidattr/\fBcurs_terminfo\fP(3X) +vidputs/\fBcurs_terminfo\fP(3X) +vline/\fBcurs_border\fP(3X) +vline_set/\fBcurs_border_set\fP(3X) +vw_printw/\fBcurs_printw\fP(3X) +vw_scanw/\fBcurs_scanw\fP(3X) +vwprintw/\fBcurs_printw\fP(3X) +vwscanw/\fBcurs_scanw\fP(3X) +wadd_wch/\fBcurs_add_wch\fP(3X) +wadd_wchnstr/\fBcurs_add_wchstr\fP(3X) +wadd_wchstr/\fBcurs_add_wchstr\fP(3X) +waddch/\fBcurs_addch\fP(3X) +waddchnstr/\fBcurs_addchstr\fP(3X) +waddchstr/\fBcurs_addchstr\fP(3X) +waddnstr/\fBcurs_addstr\fP(3X) +waddnwstr/\fBcurs_addwstr\fP(3X) +waddstr/\fBcurs_addstr\fP(3X) +waddwstr/\fBcurs_addwstr\fP(3X) +wattr_get/\fBcurs_attr\fP(3X) +wattr_off/\fBcurs_attr\fP(3X) +wattr_on/\fBcurs_attr\fP(3X) +wattr_set/\fBcurs_attr\fP(3X) +wattroff/\fBcurs_attr\fP(3X) +wattron/\fBcurs_attr\fP(3X) +wattrset/\fBcurs_attr\fP(3X) +wbkgd/\fBcurs_bkgd\fP(3X) +wbkgdset/\fBcurs_bkgd\fP(3X) +wbkgrnd/\fBcurs_bkgrnd\fP(3X) +wbkgrndset/\fBcurs_bkgrnd\fP(3X) +wborder/\fBcurs_border\fP(3X) +wborder_set/\fBcurs_border_set\fP(3X) +wchgat/\fBcurs_attr\fP(3X) +wclear/\fBcurs_clear\fP(3X) +wclrtobot/\fBcurs_clear\fP(3X) +wclrtoeol/\fBcurs_clear\fP(3X) +wcolor_set/\fBcurs_attr\fP(3X) +wcursyncup/\fBcurs_window\fP(3X) +wdelch/\fBcurs_delch\fP(3X) +wdeleteln/\fBcurs_deleteln\fP(3X) +wecho_wchar/\fBcurs_add_wch\fP(3X) +wechochar/\fBcurs_addch\fP(3X) +wenclose/\fBcurs_mouse\fP(3X)* +werase/\fBcurs_clear\fP(3X) +wget_wch/\fBcurs_get_wch\fP(3X) +wget_wstr/\fBcurs_get_wstr\fP(3X) +wgetbkgrnd/\fBcurs_bkgrnd\fP(3X) +wgetch/\fBcurs_getch\fP(3X) +wgetdelay/\fBcurs_opaque\fP(3X)* +wgetn_wstr/\fBcurs_get_wstr\fP(3X) +wgetnstr/\fBcurs_getstr\fP(3X) +wgetparent/\fBcurs_opaque\fP(3X)* +wgetscrreg/\fBcurs_opaque\fP(3X)* +wgetstr/\fBcurs_getstr\fP(3X) +whline/\fBcurs_border\fP(3X) +whline_set/\fBcurs_border_set\fP(3X) +win_wch/\fBcurs_in_wch\fP(3X) +win_wchnstr/\fBcurs_in_wchstr\fP(3X) +win_wchstr/\fBcurs_in_wchstr\fP(3X) +winch/\fBcurs_inch\fP(3X) +winchnstr/\fBcurs_inchstr\fP(3X) +winchstr/\fBcurs_inchstr\fP(3X) +winnstr/\fBcurs_instr\fP(3X) +winnwstr/\fBcurs_inwstr\fP(3X) +wins_nwstr/\fBcurs_ins_wstr\fP(3X) +wins_wch/\fBcurs_ins_wch\fP(3X) +wins_wstr/\fBcurs_ins_wstr\fP(3X) +winsch/\fBcurs_insch\fP(3X) +winsdelln/\fBcurs_deleteln\fP(3X) +winsertln/\fBcurs_deleteln\fP(3X) +winsnstr/\fBcurs_insstr\fP(3X) +winsstr/\fBcurs_insstr\fP(3X) +winstr/\fBcurs_instr\fP(3X) +winwstr/\fBcurs_inwstr\fP(3X) +wmouse_trafo/\fBcurs_mouse\fP(3X)* +wmove/\fBcurs_move\fP(3X) +wnoutrefresh/\fBcurs_refresh\fP(3X) +wprintw/\fBcurs_printw\fP(3X) +wredrawln/\fBcurs_refresh\fP(3X) +wrefresh/\fBcurs_refresh\fP(3X) +wresize/\fBwresize\fP(3X)* +wscanw/\fBcurs_scanw\fP(3X) +wscrl/\fBcurs_scroll\fP(3X) +wsetscrreg/\fBcurs_outopts\fP(3X) +wstandend/\fBcurs_attr\fP(3X) +wstandout/\fBcurs_attr\fP(3X) +wsyncdown/\fBcurs_window\fP(3X) +wsyncup/\fBcurs_window\fP(3X) +wtimeout/\fBcurs_inopts\fP(3X) +wtouchln/\fBcurs_touch\fP(3X) +wunctrl/\fBcurs_util\fP(3X) +wvline/\fBcurs_border\fP(3X) +wvline_set/\fBcurs_border_set\fP(3X) +.TE +.PP +Depending on the configuration, +additional sets of functions may be available: +.RS 3 +.TP 5 +\fBcurs_memleaks\fP(3X) - curses memory-leak checking +.TP 5 +\fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension +.TP 5 +\fBcurs_threads\fP(3X) - curses thread support +.TP 5 +\fBcurs_trace\fP(3X) - curses debugging routines +.RE +.SH RETURN VALUE +Unless otherwise noted, +functions that return an integer return \fBOK\fP on success and +\fBERR\fP on failure. +Functions that return pointers return \fBNULL\fP on failure. +Typically, +.I \%ncurses +treats a null pointer passed as a function parameter as a failure. +.PP +Functions with a \*(``mv\*('' prefix first perform cursor movement using +\fB\%wmove\fP and fail if the position is outside the window, +or +(for \*(``mvw\*('' functions) +if the +.I \%WINDOW +pointer is null. +.SH ENVIRONMENT +The following environment symbols are useful for customizing the +runtime behavior of the \fI\%ncurses\fP library. +The most important ones have been already discussed in detail. +.SS "\fICC\fP (command character)" +When set, +change the +.B \%command_character +.RB ( \%cmdch ) +capability value of loaded +.I \%term\%info +entries to the value of this variable. +Very few +.I \%term\%info +entries provide this feature. +.PP +Because this name is also used in development environments to represent +the C compiler's name, +\fI\%ncurses\fP ignores it if it does not happen to be a single +character. +.SS "\fIBAUDRATE\fP" +The debugging library checks this environment variable when the application +has redirected output to a file. +The variable's numeric value is used for the baudrate. +If no value is found, \fI\%ncurses\fP uses 9600. +This allows testers to construct repeatable test-cases +that take into account costs that depend on baudrate. +.SS "\fICOLUMNS\fP" +Specify the width of the screen in characters. +Applications running in a windowing environment usually are able to +obtain the width of the window in which they are executing. +If neither the \fI\%COLUMNS\fP value nor the terminal's screen size is available, +\fI\%ncurses\fP uses the size which may be specified in the terminfo +database +(i.e., the \fBcols\fP capability). +.PP +It is important that your application use a correct size for the screen. +This is not always possible because your application may be +running on a host which does not honor NAWS (Negotiations About Window +Size), or because you are temporarily running as another user. +However, +setting \fI\%COLUMNS\fP and/or \fILINES\fP overrides the library's use +of the screen size obtained from the operating system. +.PP +Either \fI\%COLUMNS\fP or \fILINES\fP symbols may be specified +independently. +This is mainly useful to circumvent legacy misfeatures of terminal descriptions, +e.g., xterm which commonly specifies a 65 line screen. +For best results, \fBlines\fP and \fBcols\fP should not be specified in +a terminal description for terminals which are run as emulations. +.PP +Use the \fBuse_env\fP function to disable all use of external environment +(but not including system calls) to determine the screen size. +Use the \fBuse_tioctl\fP function to update \fI\%COLUMNS\fP or +\fILINES\fP to match the screen size obtained from system calls or the +terminal database. +.SS "\fIESCDELAY\fP" +Specifies the total time, +in milliseconds, +for which \fI\%ncurses\fP will await a character sequence, +e.g., +a function key. +The default value, 1000 milliseconds, is enough for most uses. +However, it is made a variable to accommodate unusual applications. +.PP +The most common instance where you may wish to change this value +is to work with slow hosts, e.g., running on a network. +If the host cannot read characters rapidly enough, it will have the same +effect as if the terminal did not send characters rapidly enough. +The library will still see a timeout. +.PP +Note that xterm mouse events are built up from character sequences +received from the xterm. +If your application makes heavy use of multiple-clicking, you may +wish to lengthen this default value because the timeout applies +to the composed multi-click event as well as the individual clicks. +.PP +In addition to the environment variable, +this implementation provides a global variable with the same name. +Portable applications should not rely upon the presence of \fB\%ESCDELAY\fP +in either form, +but setting the environment variable rather than the global variable +does not create problems when compiling an application. +.SS "\fIHOME\fP" +Tells \fI\%ncurses\fP where your home directory is. +That is where it may read and write auxiliary terminal descriptions: +.PP +.RS 4 +.EX +$HOME/.termcap +$HOME/.terminfo +.EE +.RE +.SS "\fILINES\fP" +Like \fI\%COLUMNS\fP, specify the height of the screen in characters. +See \fI\%COLUMNS\fP for a detailed description. +.SS "\fIMOUSE_BUTTONS_123\fP" +This applies only to the OS/2 EMX port. +It specifies the order of buttons on the mouse. +OS/2 numbers a 3-button mouse inconsistently from other +platforms: +.PP +.RS 4 +.EX +1 = left +2 = right +3 = middle. +.EE +.RE +.PP +This variable lets you customize the mouse. +The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321. +If it is not specified, \fI\%ncurses\fP uses 132. +.SS "\fINCURSES_ASSUMED_COLORS\fP" +Override the compiled-in assumption that the +terminal's default colors are white-on-black +(see \fBdefault_colors\fP(3X)). +You may set the foreground and background color values with this environment +variable by proving a 2-element list: foreground,background. +For example, to tell \fI\%ncurses\fP to not assume anything +about the colors, set this to "\-1,\-1". +To make it green-on-black, set it to "2,0". +Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed. +.SS "\fINCURSES_CONSOLE2\fP" +This applies only to the MinGW port of \fI\%ncurses\fP. +.PP +The \fBConsole2\fP program's handling of the Microsoft Console API call +\fBCreateConsoleScreenBuffer\fP is defective. +Applications which use this will hang. +However, it is possible to simulate the action of this call by +mapping coordinates, +explicitly saving and restoring the original screen contents. +Setting the environment variable \fBNCGDB\fP has the same effect. +.SS "\fINCURSES_GPM_TERMS\fP" +This applies only to \fI\%ncurses\fP configured to use the GPM +interface. +.PP +If present, +the environment variable is a list of one or more terminal names +against which the \fITERM\fP environment variable is matched. +Setting it to an empty value disables the GPM interface; +using the built-in support for xterm, etc. +.PP +If the environment variable is absent, +\fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains +\*(``linux\*(''. +.SS "\fINCURSES_NO_HARD_TABS\fP" +\fI\%ncurses\fP may use tabs as part of cursor movement optimization. +In some cases, +your terminal driver may not handle these properly. +Set this environment variable to any value to disable the feature. +You can also adjust your \fBstty\fP(1) settings to avoid the problem. +.SS "\fINCURSES_NO_MAGIC_COOKIE\fP" +Some terminals use a magic-cookie feature which requires special handling +to make highlighting and other video attributes display properly. +You can suppress the highlighting entirely for these terminals by +setting this environment variable to any value. +.SS "\fINCURSES_NO_PADDING\fP" +Most of the terminal descriptions in the terminfo database are written +for real \*(``hardware\*('' terminals. +Many people use terminal emulators +which run in a windowing environment and use curses-based applications. +Terminal emulators can duplicate +all of the important aspects of a hardware terminal, but they do not +have the same limitations. +The chief limitation of a hardware terminal from the standpoint +of your application is the management of dataflow, i.e., timing. +Unless a hardware terminal is interfaced into a terminal concentrator +(which does flow control), +it (or your application) must manage dataflow, preventing overruns. +The cheapest solution (no hardware cost) +is for your program to do this by pausing after +operations that the terminal does slowly, such as clearing the display. +.PP +As a result, many terminal descriptions (including the vt100) +have delay times embedded. +You may wish to use these descriptions, +but not want to pay the performance penalty. +.PP +Set the \fI\%NCURSES_NO_PADDING\fP environment variable +to disable all but mandatory padding. +Mandatory padding is used as a part of special control +sequences such as \fBflash\fP. +.SS "\fINCURSES_NO_SETBUF\fP" +This setting is obsolete. +Before changes +.RS 3 +.bP +started with 5.9 patch 20120825 +and +.bP +continued +though 5.9 patch 20130126 +.RE +.PP +\fI\%ncurses\fP enabled buffered output during terminal initialization. +This was done (as in SVr4 curses) for performance reasons. +For testing purposes, both of \fI\%ncurses\fP and certain applications, +this feature was made optional. +Setting the \fI\%NCURSES_NO_SETBUF\fP variable +disabled output buffering, leaving the output in the original (usually +line buffered) mode. +.PP +In the current implementation, +\fI\%ncurses\fP performs its own buffering and does not require this +workaround. +It does not modify the buffering of the standard output. +.PP +The reason for the change was to make the behavior for interrupts and +other signals more robust. +One drawback is that certain nonconventional programs would mix +ordinary \fI\%stdio\fP(3) calls with \fI\%ncurses\fP calls and (usually) +work. +This is no longer possible since \fI\%ncurses\fP is not using +the buffered standard output but its own output (to the same file descriptor). +As a special case, the low-level calls such as \fBputp\fP still use the +standard output. +But high-level curses calls do not. +.SS "\fINCURSES_NO_UTF8_ACS\fP" +During initialization, the \fI\%ncurses\fP library +checks for special cases where VT100 line-drawing (and the corresponding +alternate character set capabilities) described in the terminfo are known +to be missing. +Specifically, when running in a UTF\-8 locale, +the Linux console emulator and the GNU screen program ignore these. +\fI\%ncurses checks the \fITERM\fP environment variable for these. +For other special cases, you should set this environment variable. +Doing this tells \fI\%ncurses\fP to use Unicode values which correspond +to the VT100 line-drawing glyphs. +That works for the special cases cited, +and is likely to work for terminal emulators. +.PP +When setting this variable, you should set it to a nonzero value. +Setting it to zero (or to a nonnumber) +disables the special check for \*(``linux\*('' and \*(``screen\*(''. +.PP +As an alternative to the environment variable, +\fI\%ncurses\fP checks for an extended terminfo capability \fBU8\fP. +This is a numeric capability which can be compiled using \fBtic\ \-x\fP. +For example +.PP +.RS 3 +.EX +# linux console, if patched to provide working +# VT100 shift\-in/shift\-out, with corresponding font. +linux\-vt100|linux console with VT100 line\-graphics, + U8#0, use=linux, + +# uxterm with vt100Graphics resource set to false +xterm\-utf8|xterm relying on UTF\-8 line\-graphics, + U8#1, use=xterm, +.EE +.RE +.PP +The name \*(``U8\*('' is chosen to be two characters, +to permit it to be used by applications that use \fI\%ncurses\fP' +termcap interface. +.SS "\fINCURSES_TRACE\fP" +During initialization, the \fI\%ncurses\fP debugging library +checks the \fI\%NCURSES_TRACE\fP environment variable. +If it is defined, +to a numeric value, +\fI\%ncurses\fP calls the \fBtrace\fP function, +using that value as the argument. +.PP +The argument values, which are defined in \fBcurses.h\fP, provide several +types of information. +When running with traces enabled, your application will write the +file \fBtrace\fP to the current directory. +.PP +See \fBcurs_trace\fP(3X) for more information. +.SS "\fITERM\fP" +Denotes your terminal type. +Each terminal type is distinct, though many are similar. +.PP +\fITERM\fP is commonly set by terminal emulators to help +applications find a workable terminal description. +Some of those choose a popular approximation, e.g., +\*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit. +Not infrequently, your application will have problems with that approach, +e.g., incorrect function-key definitions. +.PP +If you set \fITERM\fP in your environment, +it has no effect on the operation of the terminal emulator. +It only affects the way applications work within the terminal. +Likewise, as a general rule (\fBxterm\fP(1) being a rare exception), +terminal emulators which allow you to +specify \fITERM\fP as a parameter or configuration value do +not change their behavior to match that setting. +.SS "\fITERMCAP\fP" +If the \fI\%ncurses\fP library has been configured with \fItermcap\fP +support, \fI\%ncurses\fP will check for a terminal's description in +termcap form if it is not available in the terminfo database. +.PP +The \fI\%TERMCAP\fP environment variable contains +either a terminal description (with newlines stripped out), +or a file name telling where the information denoted by +the \fITERM\fP environment variable exists. +In either case, setting it directs \fI\%ncurses\fP to ignore +the usual place for this information, e.g., /etc/termcap. +.SS "\fITERMINFO\fP" +\fI\%ncurses\fP can be configured to read from multiple terminal +databases. +The \fI\%TERMINFO\fP variable overrides the location for +the default terminal database. +Terminal descriptions (in terminal format) are stored in terminal databases: +.bP +Normally these are stored in a directory tree, +using subdirectories named by the first letter of the terminal names therein. +.IP +This is the scheme used in System V, which legacy Unix systems use, +and the \fI\%TERMINFO\fP variable is used by \fIcurses\fP applications +on those +systems to override the default location of the terminal database. +.IP \(bu 4 +If \fI\%ncurses\fP is built to use hashed databases, +then each entry in this list may be the path of a hashed database file, e.g., +.RS 4 +.PP +.RS 4 +.EX +/usr/share/terminfo.db +.EE +.RE +.PP +rather than +.PP +.RS 4 +.EX +/usr/share/terminfo/ +.EE +.RE +.PP +The hashed database uses less disk-space and is a little faster than the +directory tree. +However, +some applications assume the existence of the directory tree, +reading it directly +rather than using the terminfo library calls. +.RE +.bP +If \fI\%ncurses\fP is built with a support for reading termcap files +directly, then an entry in this list may be the path of a termcap file. +.IP \(bu 4 +If the \fI\%TERMINFO\fP variable begins with +\*(``hex:\*('' or \*(``b64:\*('', +\fI\%ncurses\fP uses the remainder of that variable as a compiled +terminal description. +You might produce the base64 format using \fBinfocmp\fP(1M): +.RS 4 +.PP +.RS 4 +.EX +TERMINFO="$(infocmp \-0 \-Q2 \-q)" +export TERMINFO +.EE +.RE +.PP +The compiled description is used if it corresponds to the terminal identified +by the \fITERM\fP variable. +.RE +.PP +Setting \fI\%TERMINFO\fP is the simplest, +but not the only way to set location of the default terminal database. +The complete list of database locations in order follows: +.RS 3 +.bP +the last terminal database to which \fI\%ncurses\fP wrote, +if any, is searched first +.bP +the location specified by the \fI\%TERMINFO\fP environment variable +.bP +$HOME/.terminfo +.bP +locations listed in the \fI\%TERMINFO_DIRS\fP environment variable +.bP +one or more locations whose names are configured and compiled into the +\fI\%ncurses\fP library, i.e., +.RS 3 +.bP +/etc/terminfo:/usr/share/terminfo (corresponding to the \fI\%TERMINFO_DIRS\fP variable) +.bP +/usr/share/terminfo (corresponding to the \fITERMINFO\fP variable) +.RE +.RE +.SS "\fITERMINFO_DIRS\fP" +Specifies a list of locations to search for terminal descriptions. +Each location in the list is a terminal database as described in +the section on the \fI\%TERMINFO\fP variable. +The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX. +.PP +There is no corresponding feature in System V terminfo; +it is an extension developed for \fI\%ncurses\fP. +.SS "\fITERMPATH\fP" +If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks +the \fI\%TERMPATH\fP environment variable. +This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, +semicolons on OS/2 EMX. +.PP +If the \fI\%TERMPATH\fP environment variable is not set, +\fI\%ncurses\fP looks in the files +.PP +.RS 4 +.EX +/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, +.EE +.RE +.PP +in that order. +.PP +The library may be configured to disregard the following variables when the +current user is the superuser (root), or if the application uses setuid or +setgid permissions: +.PP +.RS 4 +.EX +$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. +.EE +.RE +.SH "ALTERNATE CONFIGURATIONS" +Many different +.I \%ncurses +configurations are possible, +determined by the options given to the +.I \%configure +script when building the library. +Run the script with the +.B \-\-help +option to peruse them all. +A few are of particular significance to the application developer +employing +.I \%ncurses. +.TP 5 +\-\-disable\-overwrite +The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP: +.RS 5 +.PP +.RS 4 +.EX +\fB#include <curses.h>\fP +.EE +.RE +.PP +This option is used to avoid filename conflicts when \fI\%ncurses\fP +is not the main implementation of curses of the computer. +If \fI\%ncurses\fP is installed disabling overwrite, +it puts its headers in a subdirectory, +e.g., +.PP +.RS 4 +.EX +\fB#include <ncurses/curses.h>\fP +.EE +.RE +.PP +It also omits a symbolic link which would allow you to use \fB\-lcurses\fP +to build executables. +.RE +.TP 5 +\-\-enable\-widec +The configure script renames the library and +(if the \fB\-\-disable\-overwrite\fP option is used) +puts the header files in a different subdirectory. +All of the library names have a \*(``w\*('' appended to them, +i.e., instead of +.RS 5 +.PP +.RS 4 +.EX +\fB\-lncurses\fP +.EE +.RE +.PP +you link with +.PP +.RS 4 +.EX +\fB\-lncursesw\fP +.EE +.RE +.PP +You must also enable the wide-character features in the header file +when compiling for the wide-character library +to use the extended (wide-character) functions. +The symbol which enables these features has changed since XSI Curses, Issue 4: +.bP +Originally, the wide-character feature required the symbol +\fB_XOPEN_SOURCE_EXTENDED\fP +but that was only valid for XPG4 (1996). +.bP +Later, that was deemed conflicting with \fB_XOPEN_SOURCE\fP defined to 500. +.bP +As of mid-2018, +none of the features in this implementation require a \fB_XOPEN_SOURCE\fP +feature greater than 600. +However, X/Open Curses, Issue 7 (2009) recommends defining it to 700. +.bP +Alternatively, you can enable the feature by defining \fBNCURSES_WIDECHAR\fP +with the caveat that some other header file than \fBcurses.h\fP +may require a specific value for \fB_XOPEN_SOURCE\fP +(or a system-specific symbol). +.PP +The \fI\%curses.h\fP header file installed for the wide-character +library is designed to be compatible with the non-wide library's header. +Only the size of the \fI\%WINDOW\fP structure differs; +few applications require more than pointers to \fI\%WINDOW\fPs. +.PP +If the headers are installed allowing overwrite, +the wide-character library's headers should be installed last, +to allow applications to be built using either library +from the same set of headers. +.RE +.TP 5 +\-\-with\-pthread +The configure script renames the library. +All of the library names have a \*(``t\*('' appended to them +(before any \*(``w\*('' added by \fB\-\-enable\-widec\fP). +.IP +The global variables such as \fBLINES\fP are replaced by macros to +allow read-only access. +At the same time, setter-functions are provided to set these values. +Some applications (very few) may require changes to work with this convention. +.TP 5 +\-\-with\-shared +.TP +\-\-with\-normal +.TP +\-\-with\-debug +.TP +\-\-with\-profile +The shared and normal (static) library names differ by their suffixes, +e.g., \fBlibncurses.so\fP and \fBlibncurses.a\fP. +The debug and profiling libraries add a \*(``_g\*('' +and a \*(``_p\*('' to the root names respectively, +e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP. +.TP 5 +\-\-with\-termlib +Low-level functions which do not depend upon whether the library +supports wide-characters, are provided in the tinfo library. +.IP +By doing this, it is possible to share the tinfo library between +wide/normal configurations as well as reduce the size of the library +when only low-level functions are needed. +.IP +Those functions are described in these pages: +.RS +.bP +\fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions +.bP +\fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options +.bP +\fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines +.bP +\fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines +.bP +\fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP +.bP +\fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP +database +.bP +\fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines +.RE +.TP 5 +\-\-with\-trace +The \fBtrace\fP function normally resides in the debug library, +but it is sometimes useful to configure this in the shared library. +Configure scripts should check for the function's existence rather +than assuming it is always in the debug library. +.SH FILES +.TP +.I /usr/share/tabset +tab stop initialization database +.TP +.I \*d +compiled terminal capability database +.SH NOTES +X/Open Curses permits most functions it specifies to be made available +as macros as well. +.\" See X/Open Curses Issue 4, Version 2, pp. 227-234. +.\" See X/Open Curses Issue 7, pp. 311-318. +\fI\%ncurses\fP does so +.bP +for functions that return values via their parameters, +.bP +to support obsolete features, +.bP +to reuse functions +(for example, +those that move the cursor before another operation), +and +.bP +a few special cases. +.PP +If the standard output file descriptor of an +.I \%ncurses +program is redirected to something that is not a terminal device, +the library writes screen updates to the standard error file descriptor. +This was an undocumented feature of SVr3. +.PP +See subsection \*(``Header files\*('' below regarding symbols exposed by +inclusion of \fI\%curses.h\fP. +.SH EXTENSIONS +.I \%ncurses +enables an application to capture mouse events on certain terminals, +including +.I \%xterm; +see \fB\%curs_mouse\fP(3X). +.PP +.I \%ncurses +provides a means of responding to window resizing events, +as when running in a GUI terminal emulator application such as +.I \%xterm; +see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X). +.PP +.I \%ncurses +allows an application to query the terminal for the presence of a wide +variety of special keys; +see \fB\%has_key\fP(3X). +.PP +.I \%ncurses +extends the fixed set of function key capabilities specified by X/Open +Curses by allowing the application programmer to define additional key +sequences at runtime; +see +\fB\%define_key\fP(3X), +\fB\%key_defined\fP(3X), +and +\fB\%keyok\fP(3X). +.PP +.I \%ncurses +can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48 +SGR\ 39 and SGR\ 49 sequences, +which allow an application to reset the terminal to its original +foreground and background colors. +From a user's perspective, +the application is able to draw colored text on a background whose color +is set independently, +providing better control over color contrasts. +See \fB\%default_colors\fP(3X). +.PP +An +.I \%ncurses +application can choose to hide the internal details of +.I \%WINDOW +structures, +instead using accessor functions such as +\fB\%is_scrollok\fP(3X). +.PP +.I \%ncurses +enables an application to direct application output to a printer +attached to the terminal device; +see \fB\%curs_print\fP(3X). +.PP +.I \%ncurses +offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for +soft-label key lines, +and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X) +that can gather color information from them when many colors are +supported. +.PP +Some extensions are only available if +.I \%ncurses +is compiled to support them; +see section \*(``ALTERNATE CONFIGURATIONS\*('' above. +.bP +Rudimentary support for multi-threaded applications may be available; +see \fBcurs_threads\fP(3X). +.bP +Functions that ease the management of multiple screens can be exposed; +see \fBcurs_sp_funcs\fP(3X). +.bP +The compiler option +.B \%\-DUSE_GETCAP +causes the library to fall back to reading +.I \%/etc/termcap +if the terminal setup code cannot find a +.I \%term\%info +entry corresponding to +.I TERM. +Use of this feature is not recommended, +as it essentially includes an entire +.I termcap +compiler in the +.I \%ncurses +startup code, +at a cost in memory usage and application launch latency. +.PP +.I \%PDCurses +and NetBSD +.I curses +incorporate some +.I \%ncurses +extensions. +Individual man pages indicate where this is the case. +.SH PORTABILITY +X/Open Curses defines two levels of conformance, +\*(``base\*('' and \*(``enhanced\*(''. +The latter includes several additional features, +such as wide-character and color support. +.I \%ncurses +intends base-level conformance with X/Open Curses, +and supports nearly all its enhanced features. +.\" XXX: What's missing? GBR counts untic(1), and that's all. +.PP +Differences between X/Open Curses and +.I \%ncurses +are documented in the \*(``PORTABILITY\*('' sections of applicable man +pages. +.SS "Error Checking" +In many cases, X/Open Curses is vague about error conditions, +omitting some of the SVr4 documentation. +.PP +Unlike other implementations, this one checks parameters such as pointers +to \fI\%WINDOW\fP structures to ensure they are not null. +The main reason for providing this behavior is to guard against programmer +error. +The standard interface does not provide a way for the library +to tell an application which of several possible errors were detected. +Relying on this (or some other) extension will adversely affect the +portability of curses applications. +.SS "Padding Differences" +In historic curses versions, delays embedded in the capabilities \fBcr\fP, +\fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay +bits in the Unix tty driver. +In this implementation, all padding is done by sending NUL bytes. +This method is slightly more expensive, but narrows the interface +to the Unix kernel significantly and increases the package's portability +correspondingly. +.SS "Header Files" +The header file \fI\%curses.h\fP itself includes the header files +\fI\%stdio.h\fP and \fI\%unctrl.h\fP. +.PP +X/Open Curses has more to say, +but does not finish the story: +.RS 4 +.PP +The inclusion of <curses.h> may make visible all symbols +from the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>. +.RE +.PP +Here is a more complete story: +.bP +Starting with BSD curses, all implementations have included <stdio.h>. +.IP +BSD curses included <curses.h> and <unctrl.h> from an internal header +file +.I \%curses.ext +(\*(``ext\*('' abbreviated \*(``externs\*(''). +.IP +BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP), +but nothing in <curses.h> itself relied upon <stdio.h>. +.bP +SVr2 curses added \fBnewterm\fP(3X), which relies upon <stdio.h>. +That is, the function prototype uses \fBFILE\fP. +.IP +SVr4 curses added \fBputwin\fP and \fBgetwin\fP, which also use <stdio.h>. +.IP +X/Open Curses documents all three of these functions. +.IP +SVr4 curses and X/Open Curses do not require the developer to +include <stdio.h> before including <curses.h>. +Both document curses showing <curses.h> as the only required header. +.IP +As a result, standard <curses.h> will always include <stdio.h>. +.bP +X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>. +.IP +As noted in \fBcurs_util\fP(3X), +\fI\%ncurses\fP includes <unctrl.h> from <curses.h> +(like SVr4). +.bP +X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX: +.IP +HP-UX curses includes <term.h> from <curses.h> +to declare \fBsetupterm\fP in curses.h, +but \fI\%ncurses\fP (and Solaris curses) do not. +.IP +AIX curses includes <term.h> and <termios.h>. +Again, \fI\%ncurses\fP (and Solaris curses) do not. +.bP +X/Open says that <curses.h> \fImay\fP include <term.h>, +but there is no requirement that it do that. +.IP +Some programs use functions declared in both <curses.h> and <term.h>, +and must include both headers in the same module. +Very old versions of AIX curses required including <curses.h> +before including <term.h>. +.IP +Because \fI\%ncurses\fP header files include the headers needed to +define datatypes used in the headers, +\fI\%ncurses\fP header files can be included in any order. +But for portability, you should include <curses.h> before <term.h>. +.bP +X/Open Curses says \fI"may make visible"\fP +because including a header file does not necessarily make all symbols +in it visible (there are ifdef's to consider). +.IP +For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if +the proper symbol is defined, and if \fI\%ncurses\fP is configured for +wide-character support. +If the header is included, its symbols may be made visible. +That depends on the value used for \fB_XOPEN_SOURCE\fP +feature test macro. +.bP +X/Open Curses documents one required header, +in a special case: <stdarg.h> before <curses.h> to prototype +the \fBvw_printw\fP and \fBvw_scanw\fP functions +(as well as the obsolete +the \fBvwprintw\fP and \fBvwscanw\fP functions). +Each of those uses a \fBva_list\fP parameter. +.IP +The two obsolete functions were introduced in SVr3. +The other functions were introduced in X/Open Curses. +In between, SVr4 curses provided for the possibility that +an application might include either <varargs.h> or <stdarg.h>. +Initially, that was done by using \fBvoid*\fP for the \fBva_list\fP +parameter. +Later, a special type (defined in <stdio.h>) was introduced, +to allow for compiler type-checking. +That special type is always available, +because <stdio.h> is always included by <curses.h>. +.IP +None of the X/Open Curses implementations require an application +to include <stdarg.h> before <curses.h> because they either +have allowed for a special type, +or +(like \fI\%ncurses\fP) +include <stdarg.h> directly to provide a portable interface. +.SH AUTHORS +Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. +Based on \fIpcurses\fP by Pavel Curtis. +.SH SEE ALSO +\fB\%curs_variables\fP(3X), +\fB\%terminfo\fP(5), +\fB\%user_caps\fP(5) |