ncurses 6.2 - patch 20200314
[ncurses.git] / doc / html / man / ncurses.3x.html
index b1f5bad6408d9b1827f99c607d6fff2f06535ab3..bda5c0ccd28e723041dc734a06c8b08fdb972581 100644 (file)
@@ -1,7 +1,8 @@
 <!-- 
   * 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.133 2017/05/06 14:32:49 tom Exp @
+  * @Id: ncurses.3x,v 1.146 2020/03/14 23:13:18 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>
@@ -59,7 +60,7 @@
        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 20170520).
+       This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200314).
 
        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
@@ -92,7 +93,7 @@
        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/share/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/share/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/share/terminfo</STRONG> is not available.
                     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
-         $HOME/.terminfo
+           $HOME/.termcap
+           $HOME/.terminfo
 
 
 </PRE><H3><a name="h3-LINES">LINES</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 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
-         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-
 
 
 </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.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
-           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
+               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,
+           /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>&lt;curses.h&gt;</STRONG>
+                <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</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>&lt;ncurses/curses.h&gt;</STRONG>
+                <STRONG>#include</STRONG> <STRONG>&lt;ncurses/curses.h&gt;</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  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.
 
-            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
+            <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
        <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 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
-       configured with a SIGWINCH handler.
+       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
        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
+       some of the SVr4 documentation.
+
        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.
 
-       This implementation also contains several extensions:
+
+</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.
+       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 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
+
+</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
        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>&lt;curses.h&gt;</STRONG>  automatically  includes  the  header  files
+</PRE><H3><a name="h3-Header-files">Header files</a></H3><PRE>
+       The  header  file  <STRONG>&lt;curses.h&gt;</STRONG>  automatically  includes the header files
        <STRONG>&lt;stdio.h&gt;</STRONG> and <STRONG>&lt;unctrl.h&gt;</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.
+       X/Open Curses has more to say, but does not finish the story:
+
+           The inclusion of &lt;curses.h&gt; may make visible all symbols  from  the
+           headers &lt;stdio.h&gt;, &lt;term.h&gt;, &lt;termios.h&gt;, and &lt;wchar.h&gt;.
+
+       Here is a more complete story:
+
+       <STRONG>o</STRONG>   Starting   with  BSD  curses,  all  implementations  have  included
+           &lt;stdio.h&gt;.
+
+           BSD curses included &lt;curses.h&gt;  and  &lt;unctrl.h&gt;  from  an  internal
+           header "curses.ext" ("ext" was a short name for <EM>externs</EM>).
+
+           BSD  curses  used  &lt;stdio.h&gt; internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but
+           nothing in &lt;curses.h&gt; itself relied upon &lt;stdio.h&gt;.
+
+       <STRONG>o</STRONG>   SVr2 curses added <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, which relies upon  &lt;stdio.h&gt;.   That
+           is, the function prototype uses <STRONG>FILE</STRONG>.
+
+           SVr4 curses added <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>, which also use &lt;stdio.h&gt;.
+
+           X/Open Curses documents all three of these functions.
+
+           SVr4  curses  and  X/Open  Curses  do  not require the developer to
+           include  &lt;stdio.h&gt;  before  including  &lt;curses.h&gt;.   Both  document
+           curses showing &lt;curses.h&gt; as the only required header.
+
+           As a result, standard &lt;curses.h&gt; will always include &lt;stdio.h&gt;.
+
+       <STRONG>o</STRONG>   X/Open  Curses is inconsistent with respect to SVr4 regarding &lt;unc-
+           trl.h&gt;.
+
+           As  noted  in  <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>,  ncurses  includes  &lt;unctrl.h&gt;   from
+           &lt;curses.h&gt; (like SVr4).
+
+       <STRONG>o</STRONG>   X/Open's comments about &lt;term.h&gt; and &lt;termios.h&gt; may refer to HP-UX
+           and AIX:
+
+           HP-UX curses includes &lt;term.h&gt; from &lt;curses.h&gt; to declare <STRONG>setupterm</STRONG>
+           in curses.h, but ncurses (and Solaris curses) do not.
+
+           AIX  curses includes &lt;term.h&gt; and &lt;termios.h&gt;.  Again, ncurses (and
+           Solaris curses) do not.
+
+       <STRONG>o</STRONG>   X/Open says that &lt;curses.h&gt; <EM>may</EM> include &lt;term.h&gt;, but there  is  no
+           requirement that it do that.
+
+           Some  programs  use  functions  declared  in  both  &lt;curses.h&gt;  and
+           &lt;term.h&gt;, and must include both headers in the same  module.   Very
+           old  versions  of  AIX  curses required including &lt;curses.h&gt; before
+           including &lt;term.h&gt;.
+
+           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  &lt;curses.h&gt;
+           before &lt;term.h&gt;.
+
+       <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 &lt;wchar.h&gt; <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 visi-
+           ble.  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:
+           &lt;stdarg.h&gt;  before  &lt;curses.h&gt;  to  prototype  the  <STRONG>vw_printw</STRONG>   and
+           <STRONG>vw_scanw</STRONG>  functions  (as well as the obsolete the <STRONG>vwprintw</STRONG> and <STRONG>vws-</STRONG>
+           <STRONG>canw</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
+           include either &lt;varargs.h&gt; or &lt;stdarg.h&gt;.  Initially, that was done
+           by using <STRONG>void*</STRONG> for the <STRONG>va_list</STRONG> parameter.  Later,  a  special  type
+           (defined  in &lt;stdio.h&gt;) was introduced, to allow for compiler type-
+           checking.  That special type is always available, because &lt;stdio.h&gt;
+           is always included by &lt;curses.h&gt;.
+
+           None of the X/Open Curses implementations require an application to
+           include &lt;stdarg.h&gt;  before  &lt;curses.h&gt;  because  they  either  have
+           allowed  for  a  special type, or (like ncurses) include &lt;stdarg.h&gt;
+           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.
        This was an undocumented feature of AT&amp;T System V Release 3 curses.
 
 
 <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></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a>
+<ul>
+<li><a href="#h3-Error-checking">Error checking</a></li>
+<li><a href="#h3-Extensions-versus-portability">Extensions versus portability</a></li>
+<li><a href="#h3-Padding-differences">Padding differences</a></li>
+<li><a href="#h3-Header-files">Header files</a></li>
+</ul>
+</li>
 <li><a href="#h2-NOTES">NOTES</a></li>
 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 </ul>