<!--
* t
****************************************************************************
- * Copyright (c) 1998-2015,2017 Free Software Foundation, Inc. *
+ * Copyright 2018-2019,2020 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 *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.136 2017/11/18 23:48:44 tom Exp @
+ * @Id: ncurses.3x,v 1.144 2020/02/02 23:34:34 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>ncurses 3x</TITLE>
-<link rev=made href="mailto:bug-ncurses@gnu.org">
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
method of updating character screens with reasonable optimization.
This implementation is "new curses" (ncurses) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20171216).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200215).
The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a
<STRONG>cchar_t</STRONG>.
+ The <STRONG><A HREF="setcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
+ retrieve the data from a <STRONG>cchar_t</STRONG> structure.
+
<STRONG>wchar_t</STRONG>
- stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an
+ stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an
integer.
<STRONG>wint_t</STRONG>
- stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may
+ stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may
have the same size.
- The "wide" library provides new functions which are analogous
- to functions in the "normal" library. There is a naming con-
- vention which relates many of the normal/wide variants: a "_w"
+ The "wide" library provides new functions which are analogous
+ to functions in the "normal" library. There is a naming con-
+ vention which relates many of the normal/wide variants: a "_w"
is inserted into the name. For example, <STRONG>waddch</STRONG> becomes
<STRONG>wadd_wch</STRONG>.
</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
- The following table lists each <STRONG>curses</STRONG> routine and the name of the man-
- ual page on which it is described. Routines flagged with "*" are
+ The following table lists each <STRONG>curses</STRONG> routine and the name of the man-
+ ual page on which it is described. Routines flagged with "*" are
ncurses-specific, not described by XPG4 or present in SVr4.
<STRONG>curses</STRONG> Routine Name Manual Page Name
attr_off <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attr_on <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attr_set <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+
attroff <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attron <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attrset <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
-
baudrate <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
beep <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG>
bkgd <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
getcurx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getcury <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getmaxx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
+
getmaxy <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getmaxyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
getmouse <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
-
getn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
getnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
getparx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
key_defined <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>*
key_name <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
keybound <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>*
+
keyname <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
keyok <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>*
keypad <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
-
killchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
killwchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
leaveok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
mvwaddnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
mvwaddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
mvwaddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
+
mvwchgat <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
mvwdelch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
mvwget_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
-
mvwget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
mvwgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
mvwgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
restartterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
ripoffline <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
savetty <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
+
scanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
scr_dump <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_init <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
-
scr_restore <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_set <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
use_default_colors <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>*
use_env <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
use_extended_names <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>*
+
use_legacy_coding <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>*
- use_tioctl <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+ use_tioctl <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>*
vid_attr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
-
vid_puts <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidattr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidputs <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
winch <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
winchnstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
winchstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
+
winnstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
winnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
wins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
-
wins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
wins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
winsch <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
+ Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
value other than <STRONG>ERR</STRONG> upon successful completion, unless otherwise noted
in the routine descriptions.
- As a general rule, routines check for null pointers passed as parame-
+ As a general rule, routines check for null pointers passed as parame-
ters, and handle this as an error.
- All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>,
- <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of
- <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined
- (i.e., these should not be used as the right-hand side of assignment
+ All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>,
+ <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of
+ <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined
+ (i.e., these should not be used as the right-hand side of assignment
statements).
Routines that return pointers return <STRONG>NULL</STRONG> on error.
</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
- The following environment symbols are useful for customizing the run-
- time behavior of the <STRONG>ncurses</STRONG> library. The most important ones have
+ The following environment symbols are useful for customizing the run-
+ time behavior of the <STRONG>ncurses</STRONG> library. The most important ones have
been already discussed in detail.
</PRE><H3><a name="h3-CC-command-character">CC command-character</a></H3><PRE>
- When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
- capability) of the loaded terminfo entries to the value of this vari-
+ When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
+ capability) of the loaded terminfo entries to the value of this vari-
able. Very few terminfo entries provide this feature.
Because this name is also used in development environments to represent
</PRE><H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
- The debugging library checks this environment variable when the appli-
- cation has redirected output to a file. The variable's numeric value
- is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses 9600.
- This allows testers to construct repeatable test-cases that take into
+ The debugging library checks this environment variable when the appli-
+ cation has redirected output to a file. The variable's numeric value
+ is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses 9600.
+ This allows testers to construct repeatable test-cases that take into
account costs that depend on baudrate.
</PRE><H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
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 <STRONG>COLUMNS</STRONG> value nor
- the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
+ a windowing environment usually are able to obtain the width of the
+ window in which they are executing. If neither the <STRONG>COLUMNS</STRONG> value nor
+ the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
may be specified in the terminfo database (i.e., the <STRONG>cols</STRONG> capability).
- 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. How-
- ever, setting <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of the
+ 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. How-
+ ever, setting <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of the
screen size obtained from the operating system.
- Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified independently. This
- is mainly useful to circumvent legacy misfeatures of terminal descrip-
+ Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified independently. This
+ is mainly useful to circumvent legacy misfeatures of terminal descrip-
tions, e.g., xterm which commonly specifies a 65 line screen. For best
- results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal descrip-
+ results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal descrip-
tion for terminals which are run as emulations.
- Use the <STRONG>use_env</STRONG> function to disable all use of external environment
+ Use the <STRONG>use_env</STRONG> function to disable all use of external environment
(but not including system calls) to determine the screen size. Use the
<STRONG>use_tioctl</STRONG> function to update <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen size
obtained from system calls or the terminal database.
</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
Specifies the total time, in milliseconds, for which ncurses 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
+ 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.
- 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
+ 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.
- Note that xterm mouse events are built up from character sequences
+ Note that xterm mouse events are built up from character sequences
received from the xterm. If your application makes heavy use of multi-
- ple-clicking, you may wish to lengthen this default value because the
- timeout applies to the composed multi-click event as well as the indi-
+ ple-clicking, you may wish to lengthen this default value because the
+ timeout applies to the composed multi-click event as well as the indi-
vidual clicks.
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 ESCDELAY in either form, but setting the
- environment variable rather than the global variable does not create
+ global variable with the same name. Portable applications should not
+ rely upon the presence of ESCDELAY in either form, but setting the
+ environment variable rather than the global variable does not create
problems when compiling an application.
</PRE><H3><a name="h3-HOME">HOME</a></H3><PRE>
- Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
+ Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
$HOME/.termcap
</PRE><H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
This applies only to the OS/2 EMX port. It specifies the order of but-
- tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
+ tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
other platforms:
1 = left
</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
- Override the compiled-in assumption that the terminal's default colors
- are white-on-black (see <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>). You may set the fore-
- ground and background color values with this environment variable by
- proving a 2-element list: foreground,background. For example, to tell
- ncurses 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
+ Override the compiled-in assumption that the terminal's default colors
+ are white-on-black (see <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>). You may set the fore-
+ ground and background color values with this environment variable by
+ proving a 2-element list: foreground,background. For example, to tell
+ ncurses 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 <STRONG>max_colors</STRONG> value is allowed.
</PRE><H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
This applies only to the MinGW port of ncurses.
- The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call <STRONG>Cre-</STRONG>
- <STRONG>ateConsoleScreenBuffer</STRONG> 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 <STRONG>NCGDB</STRONG> has the same
+ The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call <STRONG>Cre-</STRONG>
+ <STRONG>ateConsoleScreenBuffer</STRONG> 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 <STRONG>NCGDB</STRONG> has the same
effect.
</PRE><H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
This applies only to ncurses configured to use the GPM interface.
- If present, the environment variable is a list of one or more terminal
- names against which the <STRONG>TERM</STRONG> environment variable is matched. Setting
- it to an empty value disables the GPM interface; using the built-in
+ If present, the environment variable is a list of one or more terminal
+ names against which the <STRONG>TERM</STRONG> environment variable is matched. Setting
+ it to an empty value disables the GPM interface; using the built-in
support for xterm, etc.
If the environment variable is absent, ncurses will attempt to open GPM
</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
- <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In
- some cases, your terminal driver may not handle these properly. Set
- this environment variable to disable the feature. You can also adjust
+ <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In
+ some cases, your terminal driver may not handle these properly. Set
+ this environment variable to disable the feature. You can also adjust
your <STRONG>stty</STRONG> settings to avoid the problem.
</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">NCURSES_NO_MAGIC_COOKIE</a></H3><PRE>
- Some terminals use a magic-cookie feature which requires special han-
+ Some terminals use a magic-cookie feature which requires special han-
dling to make highlighting and other video attributes display properly.
- You can suppress the highlighting entirely for these terminals by set-
+ You can suppress the highlighting entirely for these terminals by set-
ting this environment variable.
</PRE><H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
- Most of the terminal descriptions in the terminfo database are written
- for real "hardware" terminals. Many people use terminal emulators
+ 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
+ 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, pre-
venting overruns. The cheapest solution (no hardware cost) is for your
- program to do this by pausing after operations that the terminal does
+ program to do this by pausing after operations that the terminal does
slowly, such as clearing the display.
- As a result, many terminal descriptions (including the vt100) have
- delay times embedded. You may wish to use these descriptions, but not
+ 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.
- Set the NCURSES_NO_PADDING environment variable to disable all but
+ Set the NCURSES_NO_PADDING environment variable to disable all but
mandatory padding. Mandatory padding is used as a part of special con-
trol sequences such as <EM>flash</EM>.
<STRONG>o</STRONG> continued though 5.9 patch 20130126
- <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
+ <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
was done (as in SVr4 curses) for performance reasons. For testing pur-
- poses, both of <STRONG>ncurses</STRONG> and certain applications, this feature was made
+ poses, both of <STRONG>ncurses</STRONG> and certain applications, this feature was made
optional. Setting the NCURSES_NO_SETBUF variable disabled output
- buffering, leaving the output in the original (usually line buffered)
+ buffering, leaving the output in the original (usually line buffered)
mode.
- In the current implementation, ncurses performs its own buffering and
- does not require this workaround. It does not modify the buffering of
+ In the current implementation, ncurses performs its own buffering and
+ does not require this workaround. It does not modify the buffering of
the standard output.
- The reason for the change was to make the behavior for interrupts and
- other signals more robust. One drawback is that certain nonconven-
- tional programs would mix ordinary stdio calls with ncurses calls and
- (usually) work. This is no longer possible since ncurses is not using
- the buffered standard output but its own output (to the same file
+ The reason for the change was to make the behavior for interrupts and
+ other signals more robust. One drawback is that certain nonconven-
+ tional programs would mix ordinary stdio calls with ncurses calls and
+ (usually) work. This is no longer possible since ncurses 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 <STRONG>putp</STRONG> still
use the standard output. But high-level curses calls do not.
</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> library checks for special cases
+ During initialization, the <STRONG>ncurses</STRONG> 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 emula-
- tor and the GNU screen program ignore these. Ncurses checks the <STRONG>TERM</STRONG>
- environment variable for these. For other special cases, you should
+ capabilities) described in the terminfo are known to be missing.
+ Specifically, when running in a UTF-8 locale, the Linux console emula-
+ tor and the GNU screen program ignore these. Ncurses checks the <STRONG>TERM</STRONG>
+ environment variable for these. For other special cases, you should
set this environment variable. Doing this tells ncurses 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 emula-
+ values which correspond to the VT100 line-drawing glyphs. That works
+ for the special cases cited, and is likely to work for terminal emula-
tors.
When setting this variable, you should set it to a nonzero value. Set-
- ting it to zero (or to a nonnumber) disables the special check for
+ ting it to zero (or to a nonnumber) disables the special check for
"linux" and "screen".
- As an alternative to the environment variable, ncurses checks for an
- extended terminfo capability <STRONG>U8</STRONG>. This is a numeric capability which
+ As an alternative to the environment variable, ncurses checks for an
+ extended terminfo capability <STRONG>U8</STRONG>. This is a numeric capability which
can be compiled using <STRONG>tic</STRONG> <STRONG>-x</STRONG>. For example
# linux console, if patched to provide working
xterm-utf8|xterm relying on UTF-8 line-graphics,
U8#1, use=xterm,
- The name "U8" is chosen to be two characters, to permit it to be used
+ The name "U8" is chosen to be two characters, to permit it to be used
by applications that use ncurses' termcap interface.
</PRE><H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
- NCURSES_TRACE environment variable. If it is defined, to a numeric
- value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the argu-
+ During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
+ NCURSES_TRACE environment variable. If it is defined, to a numeric
+ value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the argu-
ment.
- The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several
- types of information. When running with traces enabled, your applica-
+ The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several
+ types of information. When running with traces enabled, your applica-
tion will write the file <STRONG>trace</STRONG> to the current directory.
See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information.
</PRE><H3><a name="h3-TERM">TERM</a></H3><PRE>
- Denotes your terminal type. Each terminal type is distinct, though
+ Denotes your terminal type. Each terminal type is distinct, though
many are similar.
- <STRONG>TERM</STRONG> is commonly set by terminal emulators to help applications find a
+ <STRONG>TERM</STRONG> is commonly set by terminal emulators to help applications find a
workable terminal description. Some of those choose a popular approxi-
- mation, e.g., "ansi", "vt100", "xterm" rather than an exact fit. Not
- infrequently, your application will have problems with that approach,
+ mation, 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.
- If you set <STRONG>TERM</STRONG> 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 (<STRONG>xterm</STRONG> being a rare
- exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as a
- parameter or configuration value do not change their behavior to match
+ If you set <STRONG>TERM</STRONG> 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 (<STRONG>xterm</STRONG> being a rare
+ exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as a
+ parameter or configuration value do not change their behavior to match
that setting.
</PRE><H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
- If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
- <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
+ If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
+ <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
is not available in the terminfo database.
The <STRONG>TERMCAP</STRONG> environment variable contains either a terminal description
(with newlines stripped out), or a file name telling where the informa-
- tion denoted by the <STRONG>TERM</STRONG> environment variable exists. In either case,
- setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this informa-
+ tion denoted by the <STRONG>TERM</STRONG> environment variable exists. In either case,
+ setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this informa-
tion, e.g., /etc/termcap.
</PRE><H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
- <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
- The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal
- database. Terminal descriptions (in terminal format) are stored in
+ <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
+ The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal
+ database. Terminal descriptions (in terminal format) are stored in
terminal databases:
<STRONG>o</STRONG> Normally these are stored in a directory tree, using subdirectories
named by the first letter of the terminal names therein.
This is the scheme used in System V, which legacy Unix systems use,
- and the <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those
+ and the <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those
systems to override the default location of the terminal database.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
+ <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
this list may be the path of a hashed database file, e.g.,
/usr/share/terminfo.db
/usr/share/terminfo/
- 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
+ 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.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files
- directly, then an entry in this list may be the path of a termcap
+ <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files
+ directly, then an entry in this list may be the path of a termcap
file.
<STRONG>o</STRONG> If the <STRONG>TERMINFO</STRONG> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses
- the remainder of that variable as a compiled terminal description.
+ the remainder of that variable as a compiled terminal description.
You might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>:
TERMINFO="$(infocmp -0 -Q2 -q)"
export TERMINFO
- The compiled description is used if it corresponds to the terminal
+ The compiled description is used if it corresponds to the terminal
identified by the <STRONG>TERM</STRONG> variable.
- Setting <STRONG>TERMINFO</STRONG> is the simplest, but not the only way to set location
- of the default terminal database. The complete list of database loca-
+ Setting <STRONG>TERMINFO</STRONG> is the simplest, but not the only way to set location
+ of the default terminal database. The complete list of database loca-
tions in order follows:
- <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
+ <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
searched first
<STRONG>o</STRONG> the location specified by the TERMINFO environment variable
<STRONG>o</STRONG> locations listed in the TERMINFO_DIRS environment variable
- <STRONG>o</STRONG> one or more locations whose names are configured and compiled
+ <STRONG>o</STRONG> one or more locations whose names are configured and compiled
into the ncurses library, i.e.,
<STRONG>o</STRONG> /usr/local/ncurses/share/terminfo:/usr/share/terminfo (corre-
</PRE><H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
- 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 <STRONG>TERMINFO</STRONG> variable. The list is separated by colons
+ 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 <STRONG>TERMINFO</STRONG> variable. The list is separated by colons
(i.e., ":") on Unix, semicolons on OS/2 EMX.
There is no corresponding feature in System V terminfo; it is an exten-
</PRE><H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
- If <STRONG>TERMCAP</STRONG> does not hold a file name then <STRONG>ncurses</STRONG> checks the <STRONG>TERMPATH</STRONG>
- environment variable. This is a list of filenames separated by spaces
+ If <STRONG>TERMCAP</STRONG> does not hold a file name then <STRONG>ncurses</STRONG> checks the <STRONG>TERMPATH</STRONG>
+ environment variable. This is a list of filenames separated by spaces
or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
- If the <STRONG>TERMPATH</STRONG> environment variable is not set, <STRONG>ncurses</STRONG> looks in the
+ If the <STRONG>TERMPATH</STRONG> environment variable is not set, <STRONG>ncurses</STRONG> looks in the
files
/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
in that order.
The library may be configured to disregard the following variables when
- the current user is the superuser (root), or if the application uses
+ the current user is the superuser (root), or if the application uses
setuid or setgid permissions:
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
Several different configurations are possible, depending on the config-
- ure script options used when building <STRONG>ncurses</STRONG>. There are a few main
- options whose effects are visible to the applications developer using
+ ure script options used when building <STRONG>ncurses</STRONG>. There are a few main
+ options whose effects are visible to the applications developer using
<STRONG>ncurses</STRONG>:
--disable-overwrite
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
- This option is used to avoid filename conflicts when <STRONG>ncurses</STRONG> is
+ This option is used to avoid filename conflicts when <STRONG>ncurses</STRONG> is
not the main implementation of curses of the computer. If <STRONG>ncurses</STRONG>
- is installed disabling overwrite, it puts its headers in a subdi-
+ is installed disabling overwrite, it puts its headers in a subdi-
rectory, e.g.,
<STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG>
- It also omits a symbolic link which would allow you to use
+ It also omits a symbolic link which would allow you to use
<STRONG>-lcurses</STRONG> to build executables.
--enable-widec
- The configure script renames the library and (if the <STRONG>--dis-</STRONG>
- <STRONG>able-overwrite</STRONG> option is used) puts the header files in a differ-
+ The configure script renames the library and (if the <STRONG>--dis-</STRONG>
+ <STRONG>able-overwrite</STRONG> option is used) puts the header files in a differ-
ent subdirectory. All of the library names have a "w" appended to
them, i.e., instead of
<STRONG>-lncursesw</STRONG>
- You must also define <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> when compiling for the
- wide-character library to use the extended (wide-character) func-
- tions. The <STRONG>curses.h</STRONG> file which is installed for the wide-charac-
- ter library is designed to be compatible with the normal library's
+ 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:
+
+ <STRONG>o</STRONG> Originally, the wide-character feature required the symbol
+ <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> but that was only valid for XPG4
+ (1996).
+
+ <STRONG>o</STRONG> Later, that was deemed conflicting with <STRONG>_XOPEN_SOURCE</STRONG> defined
+ to 500.
+
+ <STRONG>o</STRONG> As of mid-2018, none of the features in this implementation
+ require a <STRONG>_XOPEN_SOURCE</STRONG> feature greater than 600. However,
+ X/Open Curses, Issue 7 (2009) recommends defining it to 700.
+
+ <STRONG>o</STRONG> Alternatively, you can enable the feature by defining
+ <STRONG>NCURSES_WIDECHAR</STRONG> with the caveat that some other header file
+ than <STRONG>curses.h</STRONG> may require a specific value for <STRONG>_XOPEN_SOURCE</STRONG>
+ (or a system-specific symbol).
+
+ The <STRONG>curses.h</STRONG> file which is installed for the wide-character
+ library is designed to be compatible with the normal library's
header. Only the size of the <STRONG>WINDOW</STRONG> structure differs, and very
- few applications require more than a pointer to <STRONG>WINDOW</STRONG>s. 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.
+ few applications require more than a pointer to <STRONG>WINDOW</STRONG>s.
+
+ If the headers are installed allowing overwrite, the wide-charac-
+ ter library's headers should be installed last, to allow applica-
+ tions to be built using either library from the same set of head-
+ ers.
--with-pthread
The configure script renames the library. All of the library