-<!--
+<!--
* t
****************************************************************************
- * Copyright 2018-2019,2020 Thomas E. Dickey *
+ * Copyright 2018-2021,2023 Thomas E. Dickey *
* Copyright 1998-2015,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.150 2020/11/07 23:48:27 tom Exp @
+ * @Id: ncurses.3x,v 1.178 2023/10/07 22:17:08 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 https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>ncurses 3x</TITLE>
+<TITLE>ncurses 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
</HEAD>
<BODY>
-<H1 class="no-header">ncurses 3x</H1>
+<H1 class="no-header">ncurses 3x 2023-10-07 ncurses 6.4 Library calls</H1>
<PRE>
-<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
Library calls <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>ncurses</STRONG> - CRT screen handling and optimization package
+ <STRONG>ncurses</STRONG> - character-cell terminal interface with optimized output
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
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.2 (patch 20201219).
+ This describes <STRONG>ncurses</STRONG> version 6.4 (patch 20231007).
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
curses). XSI stands for X/Open System Interfaces Extension. The
<STRONG>ncurses</STRONG> library is freely redistributable in source form. Differences
- from the SVr4 curses are summarized under the <STRONG>EXTENSIONS</STRONG> and
- <STRONG>PORTABILITY</STRONG> sections below and described in detail in the respective
- <STRONG>EXTENSIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections of individual man pages.
+ from the SVr4 curses are summarized under the <EM>EXTENSIONS</EM> and
+ <EM>PORTABILITY</EM> sections below and described in detail in the respective
+ <EM>EXTENSIONS</EM>, <EM>PORTABILITY</EM> and <EM>BUGS</EM> sections of individual man pages.
The <STRONG>ncurses</STRONG> library also provides many useful extensions, i.e.,
features which cannot be implemented by a simple add-on library but
option, or (if it has been generated) with the debugging library
<STRONG>-lncurses_g</STRONG>. (Your system integrator may also have installed these
libraries under the names <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>.) The ncurses_g
- library generates trace logs (in a file called 'trace' in the current
+ library generates trace logs (in a file called "trace" in the current
directory) that describe curses actions. See also the section on
<STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>.
</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>:
+ That is normally done with <STRONG>setlocale(3)</STRONG>:
<STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG>
</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 routines prefixed
- with <STRONG>w</STRONG> require a window argument. The routines prefixed with <STRONG>p</STRONG> require
+ with <EM>w</EM> require a window argument. The routines prefixed with <EM>p</EM> require
a pad argument. Those without a prefix generally use <STRONG>stdscr</STRONG>.
The routines prefixed with <STRONG>mv</STRONG> require a <EM>y</EM> and <EM>x</EM> coordinate to move to
instr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
intrflush <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
inwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
+ is_cbreak <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
is_cleared <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
+ is_echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
is_idcok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_idlok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_immedok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_keypad <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_leaveok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_linetouched <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
+ is_nl <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
is_nodelay <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_notimeout <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_pad <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
+ is_raw <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
is_scrollok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_subwin <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_syncok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(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>
-
longname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
mcprint <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>*
meta <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(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>
-
mvwgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwhline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
newpad <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
newterm <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
newwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
- nl <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
+ nl <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
nocbreak <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
nodelay <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
noecho <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
overlay <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
overwrite <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
- pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>*
+ pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
pechochar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
pnoutrefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
prefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(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>
scroll <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
setcchar <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>
setscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
setsyx <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
- setterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
setupterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
slk_attr <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
slk_attr_off <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_restore <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_touch <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
- slk_wset <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
+ slk_wset <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
standend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
standout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
start_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
tigetnum <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
tigetstr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
timeout <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
- tiparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>*
+ tiparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+ tiparm_s <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>*
+ tiscan_s <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>*
touchline <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
touchwin <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>
tparm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
ungetmouse <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
untouchwin <STRONG><A HREF="curs_touch.3x.html">curs_touch(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>*
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>
win_wchnstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
win_wchstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(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>
<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.
+ your <STRONG>stty(1)</STRONG> settings to avoid the problem.
</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">NCURSES_NO_MAGIC_COOKIE</a></H3><PRE>
Set the NCURSES_NO_PADDING environment variable to disable all but
mandatory padding. Mandatory padding is used as a part of special
- control sequences such as <EM>flash</EM>.
+ control sequences such as <STRONG>flash</STRONG>.
</PRE><H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
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.
+ within the terminal. Likewise, as a general rule (<STRONG>xterm(1)</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>
<STRONG>o</STRONG> one or more locations whose names are configured and compiled
into the ncurses library, i.e.,
- <STRONG>o</STRONG> no default value (corresponding to the TERMINFO_DIRS
+ <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO_DIRS
variable)
<STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO variable)
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
- 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
- termcap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in
+ 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
+ termcap 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
- resizing 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 <STRONG>ncurses</STRONG> library includes facilities for responding to window
+ resizing 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 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
- background colors. From the users' perspective, the application is
+ 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
+ background 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
+ independently, providing better control over color contrasts. See the
<STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> manual page for details.
- The <STRONG>ncurses</STRONG> library includes a function for directing application
+ The <STRONG>ncurses</STRONG> library includes a function for directing application
output 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
+ The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI
+ Curses. The EXTENDED XSI Curses functionality (including color
support) 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.
</PRE><H3><a name="h3-Error-checking">Error checking</a></H3><PRE>
- In many cases, X/Open Curses is vague about error conditions, omitting
+ In many cases, X/Open Curses is vague about error conditions, omitting
some of the SVr4 documentation.
- Unlike other implementations, this one checks parameters such as
- pointers 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
+ Unlike other implementations, this one checks parameters such as
+ pointers 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.
</PRE><H3><a name="h3-Extensions-versus-portability">Extensions versus portability</a></H3><PRE>
- Most of the extensions provided by ncurses have not been standardized.
+ Most of the extensions provided by ncurses have not been standardized.
Some have been incorporated into other implementations, such as
PDCurses or NetBSD curses. Here are a few to consider:
<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
<STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4.
See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The WINDOW structure's internal details can be hidden from
- application programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of
+ <STRONG>o</STRONG> The WINDOW structure's internal details can be hidden from
+ application programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of
<STRONG>is_scrollok</STRONG>, etc.
<STRONG>o</STRONG> This implementation can be configured to provide rudimentary
- support for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
+ support 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.
</PRE><H3><a name="h3-Padding-differences">Padding differences</a></H3><PRE>
- 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
- interface to the UNIX kernel significantly and increases the package's
+ bytes. This method is slightly more expensive, but narrows the
+ interface to the UNIX kernel significantly and increases the package's
portability correspondingly.
</PRE><H3><a name="h3-Header-files">Header files</a></H3><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>.
X/Open Curses has more to say, but does not finish the story:
- The inclusion of <curses.h> may make visible all symbols from the
+ The inclusion of <curses.h> may make visible all symbols from the
headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
Here is a more complete story:
- <STRONG>o</STRONG> Starting with BSD curses, all implementations have included
+ <STRONG>o</STRONG> Starting with BSD curses, all implementations have included
<stdio.h>.
- BSD curses included <curses.h> and <unctrl.h> from an internal
+ BSD curses included <curses.h> and <unctrl.h> from an internal
header "curses.ext" ("ext" was a short name for <EM>externs</EM>).
- BSD curses used <stdio.h> internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but
+ BSD curses used <stdio.h> internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but
nothing in <curses.h> itself relied upon <stdio.h>.
- <STRONG>o</STRONG> SVr2 curses added <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, which relies upon <stdio.h>. That
+ <STRONG>o</STRONG> SVr2 curses added <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, which relies upon <stdio.h>. That
is, the function prototype uses <STRONG>FILE</STRONG>.
SVr4 curses added <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>, which also use <stdio.h>.
X/Open Curses documents all three of these functions.
- SVr4 curses and X/Open Curses do not require the developer to
+ 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.
As a result, standard <curses.h> will always include <stdio.h>.
- <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding
+ <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding
<unctrl.h>.
- As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from
+ As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from
<curses.h> (like SVr4).
<STRONG>o</STRONG> X/Open's comments about <term.h> and <termios.h> may refer to HP-UX
HP-UX curses includes <term.h> from <curses.h> to declare <STRONG>setupterm</STRONG>
in curses.h, but ncurses (and Solaris curses) do not.
- AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
+ AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
Solaris curses) do not.
- <STRONG>o</STRONG> X/Open says that <curses.h> <EM>may</EM> include <term.h>, but there is no
+ <STRONG>o</STRONG> X/Open says that <curses.h> <EM>may</EM> include <term.h>, but there is no
requirement that it do that.
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
+ <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>.
- Because ncurses header files include the headers needed to define
+ Because ncurses header files include the headers needed to define
datatypes used in the headers, ncurses header files can be included
- in any order. But for portability, you should include <curses.h>
+ in any order. But for portability, you should include <curses.h>
before <term.h>.
- <STRONG>o</STRONG> X/Open Curses says <EM>"may</EM> <EM>make</EM> <EM>visible"</EM> because including a header
+ <STRONG>o</STRONG> X/Open Curses says <EM>"may</EM> <EM>make</EM> <EM>visible"</EM> because including a header
file does not necessarily make all symbols in it visible (there are
ifdef's to consider).
- For instance, in ncurses <wchar.h> <EM>may</EM> be included if the proper
- symbol is defined, and if ncurses is configured for wide-character
- support. If the header is included, its symbols may be made
- visible. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature
+ For instance, in ncurses <wchar.h> <EM>may</EM> be included if the proper
+ symbol is defined, and if ncurses is configured for wide-character
+ support. If the header is included, its symbols may be made
+ visible. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature
test macro.
- <STRONG>o</STRONG> X/Open Curses documents one required header, in a special case:
- <stdarg.h> before <curses.h> to prototype the <STRONG>vw_printw</STRONG> and
- <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and
+ <STRONG>o</STRONG> X/Open Curses documents one required header, in a special case:
+ <stdarg.h> before <curses.h> to prototype the <STRONG>vw_printw</STRONG> and
+ <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and
<STRONG>vwscanw</STRONG> functions). Each of those uses a <STRONG>va_list</STRONG> parameter.
- 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
+ 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 <STRONG>void*</STRONG> for the <STRONG>va_list</STRONG> parameter. Later, a special type
- (defined in <stdio.h>) was introduced, to allow for compiler type-
+ by using <STRONG>void*</STRONG> for the <STRONG>va_list</STRONG> 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>.
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 ncurses) include <stdarg.h>
+ include <stdarg.h> before <curses.h> because they either have
+ allowed for a special type, or (like ncurses) include <stdarg.h>
directly to provide a portable interface.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- 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.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
- Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on pcurses
+ Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey. Based on <EM>pcurses</EM>
by Pavel Curtis.
+</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>
+ <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for user-defined capabilities
+
- <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+
+ncurses 6.4 2023-10-07 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
</li>
<li><a href="#h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></li>
<li><a href="#h2-FILES">FILES</a></li>
-<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
</li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-AUTHORS">AUTHORS</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
projects / ncurses.git / blobdiff