ncurses 6.2 - patch 20200314
[ncurses.git] / doc / html / man / ncurses.3x.html
index 80cfdda7678daafbfade64624636a57c71fe03cd..bda5c0ccd28e723041dc734a06c8b08fdb972581 100644 (file)
@@ -1,7 +1,8 @@
 <!-- 
   * t
   ****************************************************************************
-  * Copyright (c) 1998-2018,2019 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            *
@@ -27,7 +28,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: ncurses.3x,v 1.143 2019/11/30 20:47:07 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>
@@ -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.1 (patch 20191214).
+       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
        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>