<!--
* t
****************************************************************************
- * Copyright (c) 1998-2015,2017 Free Software Foundation, Inc. *
+ * Copyright (c) 1998-2017,2018 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.135 2017/08/12 22:27:43 tom Exp @
+ * @Id: ncurses.3x,v 1.140 2018/07/28 23:30:17 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">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
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 20170819).
+ This describes <STRONG>ncurses</STRONG> version 6.1 (patch 20180825).
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
The library uses the locale which the calling program has initialized.
That is normally done with <STRONG>setlocale</STRONG>:
- <STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG>
+ <STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG>
If the locale is not initialized, the library assumes that characters
are printable as in ISO-8859-1, to work with certain legacy programs.
screen oriented programs want this), the following sequence should be
used:
- <STRONG>initscr();</STRONG> <STRONG>cbreak();</STRONG> <STRONG>noecho();</STRONG>
+ <STRONG>initscr();</STRONG> <STRONG>cbreak();</STRONG> <STRONG>noecho();</STRONG>
Most programs would additionally use the sequence:
- <STRONG>nonl();</STRONG>
- <STRONG>intrflush(stdscr,</STRONG> <STRONG>FALSE);</STRONG>
- <STRONG>keypad(stdscr,</STRONG> <STRONG>TRUE);</STRONG>
+ <STRONG>nonl();</STRONG>
+ <STRONG>intrflush(stdscr,</STRONG> <STRONG>FALSE);</STRONG>
+ <STRONG>keypad(stdscr,</STRONG> <STRONG>TRUE);</STRONG>
Before a <STRONG>curses</STRONG> program is run, the tab stops of the terminal should be
set and its initialization strings, if defined, must be output. This
standard place. For example, if <STRONG>TERM</STRONG> is set to <STRONG>att4424</STRONG>, then the com-
piled terminal definition is found in
- <STRONG>/usr/local/ncurses/lib/terminfo/a/att4424</STRONG>.
+ <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
(The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of
huge directories.) However, if <STRONG>TERMINFO</STRONG> is set to <STRONG>$HOME/myterms</STRONG>,
<STRONG>curses</STRONG> first checks
- <STRONG>$HOME/myterms/a/att4424</STRONG>,
+ <STRONG>$HOME/myterms/a/att4424</STRONG>,
and if that fails, it then checks
- <STRONG>/usr/local/ncurses/lib/terminfo/a/att4424</STRONG>.
+ <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
This is useful for developing experimental definitions or when write
- permission in <STRONG>/usr/local/ncurses/lib/terminfo</STRONG> is not available.
+ permission in <STRONG>/usr/share/terminfo</STRONG> is not available.
The integer variables <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> are defined in <STRONG><curses.h></STRONG> and will
be filled in by <STRONG>initscr</STRONG> with the size of the screen. The constants
Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
- $HOME/.termcap
- $HOME/.terminfo
+ $HOME/.termcap
+ $HOME/.terminfo
</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
other platforms:
- 1 = left
- 2 = right
- 3 = middle.
+ 1 = left
+ 2 = right
+ 3 = middle.
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 speci-
<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.db
rather than
- /usr/share/terminfo/
+ /usr/share/terminfo/
The hashed database uses less disk-space and is a little faster
than the directory tree. However, some applications assume the
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
+ TERMINFO="$(infocmp -0 -Q2 -q)"
+ export TERMINFO
The compiled description is used if it corresponds to the terminal
identified by the <STRONG>TERM</STRONG> variable.
<STRONG>o</STRONG> /usr/local/ncurses/share/terminfo:/usr/share/terminfo (corre-
sponding to the TERMINFO_DIRS variable)
- <STRONG>o</STRONG> /usr/local/ncurses/lib/terminfo (corresponding to the TER-
- MINFO variable)
+ <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO variable)
</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,
+ /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.
+ $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
The standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYNOPSIS</STRONG>:
- <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
+ <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>
+ <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>-lncurses</STRONG>
+ <STRONG>-lncurses</STRONG>
you link with
- <STRONG>-lncursesw</STRONG>
+ <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
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
/usr/share/tabset
directory containing initialization files for the terminal capa-
- bility database /usr/local/ncurses/lib/terminfo terminal capabil-
- ity database
+ bility database /usr/share/terminfo terminal capability database
</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
+ <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>
<STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for user-defined capabilities
</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/termcap file if the terminal setup
- code cannot find a terminfo entry corresponding to <STRONG>TERM</STRONG>. Use of this
- feature is not recommended, as it essentially includes an entire term-
- cap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in core
+ The <STRONG>ncurses</STRONG> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that
+ falls back to the old-style /etc/termcap file if the terminal setup
+ code cannot find a terminfo entry corresponding to <STRONG>TERM</STRONG>. Use of this
+ feature is not recommended, as it essentially includes an entire term-
+ cap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in core
and startup cycles.
- The <STRONG>ncurses</STRONG> library includes facilities for capturing mouse events on
- certain terminals (including xterm). See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual
+ The <STRONG>ncurses</STRONG> library includes facilities for capturing mouse events on
+ certain terminals (including xterm). See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual
page for details.
The <STRONG>ncurses</STRONG> library includes facilities for responding to window resiz-
ing events, e.g., when running in an xterm. See the <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and
- <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition, the library may be
+ <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition, the library may be
configured with a <STRONG>SIGWINCH</STRONG> handler.
- The <STRONG>ncurses</STRONG> library extends the fixed set of function key capabilities
- of terminals by allowing the application designer to define additional
- key sequences at runtime. See the <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and
+ The <STRONG>ncurses</STRONG> library extends the fixed set of function key capabilities
+ of terminals by allowing the application designer to define additional
+ key sequences at runtime. See the <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and
<STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> manual pages for details.
- The <STRONG>ncurses</STRONG> library can exploit the capabilities of terminals which
- implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
- application to reset the terminal to its original foreground and back-
+ The <STRONG>ncurses</STRONG> library can exploit the capabilities of terminals which
+ implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
+ application to reset the terminal to its original foreground and back-
ground colors. From the users' perspective, the application is able to
- draw colored text on a background whose color is set independently,
- providing better control over color contrasts. See the <STRONG>default_col-</STRONG>
+ draw colored text on a background whose color is set independently,
+ providing better control over color contrasts. See the <STRONG>default_col-</STRONG>
<STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG> manual page for details.
- The <STRONG>ncurses</STRONG> library includes a function for directing application out-
- put to a printer attached to the terminal device. See the
+ The <STRONG>ncurses</STRONG> library includes a function for directing application out-
+ put to a printer attached to the terminal 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>
- The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI
- Curses. The EXTENDED XSI Curses functionality (including color sup-
+ The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI
+ Curses. The EXTENDED XSI Curses functionality (including color sup-
port) is supported.
- A small number of local differences (that is, individual differences
- between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG>
+ A small number of local differences (that is, individual differences
+ between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG>
sections of the library man pages.
Unlike other implementations, this one checks parameters such as point-
- ers to WINDOW 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
+ ers to WINDOW 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.
<STRONG>o</STRONG> The routine <STRONG>has_key</STRONG> is not part of XPG4, nor is it present in SVr4.
See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in
+ <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in
SVr4. See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and
- <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor
- are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
+ <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and
+ <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor
+ are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
details.
- <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses imple-
+ <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses imple-
mentation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
<STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4.
tion programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of <STRONG>is_scrol-</STRONG>
<STRONG>lok</STRONG>, etc.
- <STRONG>o</STRONG> This implementation can be configured to provide rudimentary sup-
- port for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
+ <STRONG>o</STRONG> This implementation can be configured to provide rudimentary sup-
+ port for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
details.
- <STRONG>o</STRONG> This implementation can also be configured to provide a set of
- functions which improve the ability to manage multiple screens.
+ <STRONG>o</STRONG> This implementation can also be configured to provide a set of
+ functions which improve the ability to manage multiple screens.
See <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> for details.
- In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>,
- <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> activated corresponding delay bits in the UNIX
+ In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>,
+ <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> 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 inter-
- face to the UNIX kernel significantly and increases the package's
+ bytes. This method is slightly more expensive, but narrows the inter-
+ face to the UNIX kernel significantly and increases the package's
portability correspondingly.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The header file <STRONG><curses.h></STRONG> automatically includes the header files
+ The header file <STRONG><curses.h></STRONG> automatically includes the header files
<STRONG><stdio.h></STRONG> and <STRONG><unctrl.h></STRONG>.
- If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something
- which is not a tty, screen updates will be directed to standard error.
+ If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something
+ which is not a tty, screen updates will be directed to standard error.
This was an undocumented feature of AT&T System V Release 3 curses.