<!--
* t
****************************************************************************
- * Copyright (c) 1998-2014,2015 Free Software Foundation, Inc. *
+ * Copyright (c) 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.124 2015/08/08 14:57:51 tom Exp @
+ * @Id: ncurses.3x,v 1.125 2017/01/07 19:25:15 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
-</PRE>
-<H2><a name="h2-NAME">NAME</a></H2><PRE>
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>ncurses</STRONG> - CRT screen handling and optimization package
-</PRE>
-<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
-</PRE>
-<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The <STRONG>ncurses</STRONG> library routines give the user a terminal-
independent method of updating character screens with rea-
sonable optimization. This implementation is "new curses"
(ncurses) and is the approved replacement for 4.4BSD clas-
sic curses, which has been discontinued. This describes
- <STRONG>ncurses</STRONG> version 6.0 (patch 20150808).
+ <STRONG>ncurses</STRONG> version 6.0 (patch 20170128).
The <STRONG>ncurses</STRONG> library emulates the curses library of System
V Release 4 UNIX, and XPG4 (X/Open Portability Guide)
access to low-level terminal-manipulation routines.
-</PRE>
-<H3><a name="h3-Initialization">Initialization</a></H3><PRE>
+</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
The library uses the locale which the calling program has
initialized. That is normally done with <STRONG>setlocale</STRONG>:
The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initial-
ize the library before any of the other routines that deal
- with windows and screens are used. The routine <STRONG>endwin</STRONG>
+ with windows and screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>
must be called before exiting.
To get character-at-a-time input without echoing (most
for doing this. [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.]
-</PRE>
-<H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
+</PRE><H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
The <STRONG>ncurses</STRONG> library permits manipulation of data struc-
tures, called <EM>windows</EM>, which can be thought of as two-
dimensional arrays of characters representing all or part
names beginning with <STRONG>w</STRONG>, allowing the user to specify a
window. The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>.
- After using routines to manipulate a window, <STRONG>refresh</STRONG> is
- called, telling <STRONG>curses</STRONG> to make the user's CRT screen look
- like <STRONG>stdscr</STRONG>. The characters in a window are actually of
- type <STRONG>chtype</STRONG>, (character and attribute data) so that other
- information about the character may also be stored with
- each character.
+ After using routines to manipulate a window, <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>
+ is called, telling <STRONG>curses</STRONG> to make the user's CRT screen
+ look like <STRONG>stdscr</STRONG>. The characters in a window are actually
+ of type <STRONG>chtype</STRONG>, (character and attribute data) so that
+ other information about the character may also be stored
+ with each character.
Special windows called <EM>pads</EM> may also be manipulated.
These are windows which are not constrained to the size of
<STRONG><curses.h></STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>, and <STRONG>KEY_LEFT</STRONG>.
-</PRE>
-<H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
+</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or
if the program is executing in a window environment, line
and column information in the environment will override
<STRONG>curscr</STRONG> can be used in only a few routines.
-</PRE>
-<H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
+</PRE><H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
Many <STRONG>curses</STRONG> routines have two or more versions. The rou-
tines prefixed with <STRONG>w</STRONG> require a window argument. The rou-
tines prefixed with <STRONG>p</STRONG> require a pad argument. Those with-
becomes <STRONG>wadd_wch</STRONG>.
-</PRE>
-<H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
+</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 manual page on which it is described. Routines
flagged with `*' are ncurses-specific, not described by
wvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
-</PRE>
-<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+</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 value other than <STRONG>ERR</STRONG> upon successful com-
pletion, unless otherwise noted in the routine descrip-
Routines that return pointers return <STRONG>NULL</STRONG> on error.
-</PRE>
-<H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
+</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
The following environment symbols are useful for customiz-
ing the runtime behavior of the <STRONG>ncurses</STRONG> library. The most
important ones have been already discussed in detail.
it does not happen to be a single character.
-</PRE>
-<H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
+</PRE><H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
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
costs that depend on baudrate.
-</PRE>
-<H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
+</PRE><H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
Specify the width of the screen in characters. Applica-
tions running in a windowing environment usually are able
to obtain the width of the window in which they are exe-
system calls or the terminal database.
-</PRE>
-<H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
+</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
lems when compiling an application.
-</PRE>
-<H3><a name="h3-HOME">HOME</a></H3><PRE>
+</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 and write auxiliary terminal descriptions:
$HOME/.terminfo
-</PRE>
-<H3><a name="h3-LINES">LINES</a></H3><PRE>
+</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
Like COLUMNS, specify the height of the screen in charac-
ters. See COLUMNS for a detailed description.
-</PRE>
-<H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
+</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 buttons on the mouse. OS/2 numbers a 3-button
mouse inconsistently from other platforms:
or 321. If it is not specified, <STRONG>ncurses</STRONG> uses 132.
-</PRE>
-<H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
+</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>default_col-</STRONG>
<STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG>). You may set the foreground and background color
value is allowed.
-</PRE>
-<H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
+</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
same effect.
-</PRE>
-<H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
+</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.
attempt to open GPM if TERM contains "linux".
-</PRE>
-<H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
+</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 opti-
mization. In some cases, your terminal driver may not
handle these properly. Set this environment variable to
environment variable.
-</PRE>
-<H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
+</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 which run in a windowing environ-
part of special control sequences such as <EM>flash</EM>.
-</PRE>
-<H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
This setting is obsolete. Before changes
<STRONG>o</STRONG> started with 5.9 patch 20120825 and
level curses calls do not.
-</PRE>
-<H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
+</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 spe-
cial cases where VT100 line-drawing (and the corresponding
alternate character set capabilities) described in the
interface.
-</PRE>
-<H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
+</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> func-
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>
+</PRE><H3><a name="h3-TERM">TERM</a></H3><PRE>
Denotes your terminal type. Each terminal type is dis-
tinct, though many are similar.
match that setting.
-</PRE>
-<H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
+</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 is not available in the terminfo
mation, e.g., /etc/termcap.
-</PRE>
-<H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
Overrides the directory in which <STRONG>ncurses</STRONG> searches for your
terminal description. This is the simplest, but not the
only way to change the list of directories. The complete
MINFO variable)
-</PRE>
-<H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
Specifies a list of directories to search for terminal
descriptions. The list is separated by colons (i.e., ":")
on Unix, semicolons on OS/2 EMX.
of a termcap file.
-</PRE>
-<H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
+</PRE><H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
If TERMCAP does not hold a file name then <STRONG>ncurses</STRONG> checks
the TERMPATH environment variable. This is a list of
filenames separated by spaces or colons (i.e., ":") on
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
-</PRE>
-<H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
+</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
Several different configurations are possible, depending
on the configure script options used when building
<STRONG>ncurses</STRONG>. There are a few main options whose effects are
ing it is always in the debug library.
-</PRE>
-<H2><a name="h2-FILES">FILES</a></H2><PRE>
+</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
/usr/share/tabset
directory containing initialization files for the
terminal capability database /usr/share/terminfo ter-
minal capability database
-</PRE>
-<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> and related pages whose names begin "curs_"
for detailed routine descriptions.
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
-</PRE>
-<H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
The <STRONG>ncurses</STRONG> library can be compiled with an option
(<STRONG>-DUSE_GETCAP</STRONG>) that falls back to the old-style /etc/term-
cap file if the terminal setup code cannot find a terminfo
device. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
-</PRE>
-<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The <STRONG>ncurses</STRONG> library is intended to be BASE-level confor-
mant with XSI Curses. The EXTENDED XSI Curses functional-
ity (including color support) is supported.
package's portability correspondingly.
-</PRE>
-<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
The header file <STRONG><curses.h></STRONG> automatically includes the
header files <STRONG><stdio.h></STRONG> and <STRONG><unctrl.h></STRONG>.
ture of AT&T System V Release 3 curses.
-</PRE>
-<H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
+</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on pcurses by Pavel Curtis.