]> ncurses.scripts.mit.edu Git - ncurses.git/blobdiff - doc/html/man/curs_util.3x.html
projects / ncurses.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
ncurses 6.4 - patch 20240420
[ncurses.git] / doc / html / man / curs_util.3x.html
diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html
index 3589d2a7e002743db0d42bedb66dd93305a4b7ec..9b6c3655f6125dd17530d069201226d6fdbf02ad 100644 (file)
--- a/doc/html/man/curs_util.3x.html
+++ b/doc/html/man/curs_util.3x.html
@@ -1,7 +1,7 @@
-<!-- 
+<!--
   * t
   ****************************************************************************
   * t
   ****************************************************************************
-  * Copyright 2018-2019,2020 Thomas E. Dickey                                *
+  * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -28,198 +28,218 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_util.3x,v 1.58 2020/10/17 22:54:59 tom Exp @
+  * @Id: curs_util.3x,v 1.101 2024/04/20 21:20:07 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">
 -->
 <!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>curs_util 3x</TITLE>
+<TITLE>curs_util 3x 2024-04-20 ncurses 6.4 Library calls</TITLE>
 <link rel="author" 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>
 </HEAD>
 <BODY>
-<H1 class="no-header">curs_util 3x</H1>
+<H1 class="no-header">curs_util 3x 2024-04-20 ncurses 6.4 Library calls</H1>
 <PRE>
 <PRE>
-<STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>                                                    <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+<STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>                    Library calls                   <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
 
 
 
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
 
 
 
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
-       <STRONG>delay_output</STRONG>, <STRONG>filter</STRONG>, <STRONG>flushinp</STRONG>, <STRONG>getwin</STRONG>, <STRONG>key_name</STRONG>, <STRONG>keyname</STRONG>, <STRONG>nofilter</STRONG>,
-       <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>use_tioctl</STRONG>, <STRONG>wunctrl</STRONG> - miscellaneous <STRONG>curses</STRONG>
+       <STRONG>delay_output</STRONG>,  <STRONG>filter</STRONG>,  <STRONG>flushinp</STRONG>,  <STRONG>getwin</STRONG>, <STRONG>key_name</STRONG>, <STRONG>keyname</STRONG>, <STRONG>nofilter</STRONG>,
+       <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>use_tioctl</STRONG>,  <STRONG>wunctrl</STRONG>  -  miscellaneous  <EM>curses</EM>
        utility routines
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
        utility routines
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
-       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*unctrl(chtype</STRONG> <STRONG>c);</STRONG>
-       <STRONG>wchar_t</STRONG> <STRONG>*wunctrl(cchar_t</STRONG> <STRONG>*c);</STRONG>
+       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*unctrl(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+       <STRONG>wchar_t</STRONG> <STRONG>*wunctrl(cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
 
 
-       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*keyname(int</STRONG> <STRONG>c);</STRONG>
-       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*key_name(wchar_t</STRONG> <STRONG>w);</STRONG>
+       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*keyname(int</STRONG> <EM>c</EM><STRONG>);</STRONG>
+       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*key_name(wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG>
 
        <STRONG>void</STRONG> <STRONG>filter(void);</STRONG>
 
        <STRONG>void</STRONG> <STRONG>filter(void);</STRONG>
-       <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG>
 
 
-       <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <STRONG>f);</STRONG>
-       <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <STRONG>f);</STRONG>
+       <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
 
 
-       <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>FILE</STRONG> <STRONG>*filep);</STRONG>
-       <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*filep);</STRONG>
+       <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
+       <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
 
 
-       <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <STRONG>ms);</STRONG>
+       <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <EM>ms</EM><STRONG>);</STRONG>
        <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG>
 
        <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG>
 
+       <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
+       <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG>
+       <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
+
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-unctrl">unctrl</a></H3><PRE>
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE><H3><a name="h3-unctrl">unctrl</a></H3><PRE>
-       The <STRONG>unctrl</STRONG> routine returns a character string which is a printable rep-
-       resentation of the character <EM>c</EM>, ignoring attributes.   Control  charac-
-       ters  are  displayed  in the <STRONG>^</STRONG><EM>X</EM> notation.  Printing characters are dis-
-       played as is.  The corresponding <STRONG>wunctrl</STRONG> returns a printable  represen-
-       tation of a wide character.
-
-
-</PRE><H3><a name="h3-keyname_key_name">keyname/key_name</a></H3><PRE>
-       The <STRONG>keyname</STRONG> routine returns a character string corresponding to the key
-       <EM>c</EM>:
+       The  <STRONG>unctrl</STRONG>  routine  returns  a  character string which is a printable
+       representation of the character <EM>ch</EM>:
 
 
-       <STRONG>o</STRONG>   Printable characters are displayed as themselves, e.g., a one-char-
-           acter string containing the key.
+       <STRONG>o</STRONG>   Printable characters are displayed  as  themselves,  e.g.,  a  one-
+           character string containing the key.
 
        <STRONG>o</STRONG>   Control characters are displayed in the <STRONG>^</STRONG><EM>X</EM> notation.
 
 
        <STRONG>o</STRONG>   Control characters are displayed in the <STRONG>^</STRONG><EM>X</EM> notation.
 
+       <STRONG>o</STRONG>   Printing characters are displayed as is.
+
        <STRONG>o</STRONG>   DEL (character 127) is displayed as <STRONG>^?</STRONG>.
 
        <STRONG>o</STRONG>   Values  above 128 are either meta characters (if the screen has not
        <STRONG>o</STRONG>   DEL (character 127) is displayed as <STRONG>^?</STRONG>.
 
        <STRONG>o</STRONG>   Values  above 128 are either meta characters (if the screen has not
-           been initialized, or if <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> has been called with a <STRONG>TRUE</STRONG> param-
-           eter),  shown  in the <STRONG>M-</STRONG><EM>X</EM> notation, or are displayed as themselves.
-           In the latter case, the values may not be printable;  this  follows
-           the X/Open specification.
+           been initialized, or if  <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG>  has  been  called  with  a  <STRONG>TRUE</STRONG>
+           parameter),  shown  in  the  <STRONG>M-</STRONG><EM>X</EM>  notation,  or  are  displayed  as
+           themselves.  In the latter case, the values may not  be  printable;
+           this follows the X/Open specification.
+
+       The  corresponding  <STRONG>wunctrl</STRONG>  returns  a  printable  representation of a
+       complex character <EM>wch</EM>.
+
+       In both <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> the attributes and color associated with the
+       character parameter are ignored.
+
+
+</PRE><H3><a name="h3-keyname_key_name">keyname, key_name</a></H3><PRE>
+       The <STRONG>keyname</STRONG> routine returns a character string corresponding to the key
+       <EM>c</EM>.  Key codes are different from character codes.
 
 
-       <STRONG>o</STRONG>   Values above 256 may be the names of the names of function keys.
+       <STRONG>o</STRONG>   Key codes below 256  are  characters.   They  are  displayed  using
+           <STRONG>unctrl</STRONG>.
 
 
-       <STRONG>o</STRONG>   Otherwise  (if there is no corresponding name) the function returns
-           null, to denote an error.  X/Open also lists an "UNKNOWN  KEY"  re-
-           turn value, which some implementations return rather than null.
+       <STRONG>o</STRONG>   Values  above 256 may be the codes for function keys.  The function
+           key name is displayed.
 
 
-       The  corresponding <STRONG>key_name</STRONG> returns a character string corresponding to
-       the wide-character value <EM>w</EM>.  The two functions do not return  the  same
-       set  of strings; the latter returns null where the former would display
-       a meta character.
+       <STRONG>o</STRONG>   Otherwise (if there is no corresponding name and the key is  not  a
+           character)  the  function returns null, to denote an error.  X/Open
+           also  lists   an   "UNKNOWN   KEY"   return   value,   which   some
+           implementations return rather than null.
 
 
+       The   corresponding  <STRONG>key_name</STRONG>  returns  a  multibyte  character  string
+       corresponding  to  the  wide-character  value  <EM>w</EM>.   The  two  functions
+       (<STRONG>keyname</STRONG> and <STRONG>key_name</STRONG>) do not return the same set of strings:
 
 
-</PRE><H3><a name="h3-filter_nofilter">filter/nofilter</a></H3><PRE>
-       The <STRONG>filter</STRONG> routine, if used, must be called before <STRONG>initscr</STRONG>  or  <STRONG>newterm</STRONG>
+       <STRONG>o</STRONG>   <STRONG>keyname</STRONG> returns null where <STRONG>key_name</STRONG> would display a meta character.
+
+       <STRONG>o</STRONG>   <STRONG>key_name</STRONG> does not return the name of a function key.
+
+
+</PRE><H3><a name="h3-filter_nofilter">filter, nofilter</a></H3><PRE>
+       The  <STRONG>filter</STRONG>  routine, if used, must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>
        are called.  Calling <STRONG>filter</STRONG> causes these changes in initialization:
 
        <STRONG>o</STRONG>   <STRONG>LINES</STRONG> is set to 1;
 
        are called.  Calling <STRONG>filter</STRONG> causes these changes in initialization:
 
        <STRONG>o</STRONG>   <STRONG>LINES</STRONG> is set to 1;
 
-       <STRONG>o</STRONG>   the  capabilities  <STRONG>clear</STRONG>,  <STRONG>cud1</STRONG>,  <STRONG>cud</STRONG>, <STRONG>cup</STRONG>, <STRONG>cuu1</STRONG>, <STRONG>cuu</STRONG>, <STRONG>vpa</STRONG> are dis-
-           abled;
+       <STRONG>o</STRONG>   the  capabilities  <STRONG>clear</STRONG>,  <STRONG>cud1</STRONG>,  <STRONG>cud</STRONG>,  <STRONG>cup</STRONG>,  <STRONG>cuu1</STRONG>,  <STRONG>cuu</STRONG>,  <STRONG>vpa</STRONG>  are
+           disabled;
 
        <STRONG>o</STRONG>   the capability <STRONG>ed</STRONG> is disabled if <STRONG>bce</STRONG> is set;
 
        <STRONG>o</STRONG>   and the <STRONG>home</STRONG> string is set to the value of <STRONG>cr</STRONG>.
 
 
        <STRONG>o</STRONG>   the capability <STRONG>ed</STRONG> is disabled if <STRONG>bce</STRONG> is set;
 
        <STRONG>o</STRONG>   and the <STRONG>home</STRONG> string is set to the value of <STRONG>cr</STRONG>.
 
-       The <STRONG>nofilter</STRONG> routine cancels the effect of  a  preceding  <STRONG>filter</STRONG>  call.
-       That  allows  the  caller to initialize a screen on a different device,
-       using a different value of <STRONG>$TERM</STRONG>.  The limitation  arises  because  the
+       The  <STRONG>nofilter</STRONG>  routine  cancels  the effect of a preceding <STRONG>filter</STRONG> call.
+       That allows the caller to initialize a screen on  a  different  device,
+       using  a  different  value of <STRONG>$TERM</STRONG>.  The limitation arises because the
        <STRONG>filter</STRONG> routine modifies the in-memory copy of the terminal information.
 
 
 </PRE><H3><a name="h3-use_env">use_env</a></H3><PRE>
        <STRONG>filter</STRONG> routine modifies the in-memory copy of the terminal information.
 
 
 </PRE><H3><a name="h3-use_env">use_env</a></H3><PRE>
-       The  <STRONG>use_env</STRONG>  routine,  if  used,  should  be  called before <STRONG>initscr</STRONG> or
-       <STRONG>newterm</STRONG> are called (because those compute the screen size).   It  modi-
-       fies  the way <STRONG>ncurses</STRONG> treats environment variables when determining the
-       screen size.
+       The <STRONG>use_env</STRONG> routine, if  used,  should  be  called  before  <STRONG>initscr</STRONG>  or
+       <STRONG>newterm</STRONG>  are  called  (because  those  compute  the  screen  size).  It
+       modifies the way <EM>ncurses</EM> treats environment variables when  determining
+       the screen size.
 
 
-       <STRONG>o</STRONG>   Normally <STRONG>ncurses</STRONG> looks first  at  the  terminal  database  for  the
+       <STRONG>o</STRONG>   Normally  <EM>ncurses</EM>  looks  first  at  the  terminal database for the
            screen size.
 
            screen size.
 
-           If  <STRONG>use_env</STRONG>  was called with <STRONG>FALSE</STRONG> for parameter, it stops here un-
-           less <STRONG>use_tioctl</STRONG> was also called with <STRONG>TRUE</STRONG> for parameter.
+           If <STRONG>use_env</STRONG> was called with  <STRONG>FALSE</STRONG>  for  parameter,  it  stops  here
+           unless <STRONG>use_tioctl</STRONG> was also called with <STRONG>TRUE</STRONG> for parameter.
 
 
-       <STRONG>o</STRONG>   Then it asks for the screen size via operating  system  calls.   If
+       <STRONG>o</STRONG>   Then  it  asks  for the screen size via operating system calls.  If
            successful, it overrides the values from the terminal database.
 
            successful, it overrides the values from the terminal database.
 
-       <STRONG>o</STRONG>   Finally  (unless  <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parameter), <STRONG>ncurses</STRONG>
-           examines the <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> environment variables, using a  value
-           in  those to override the results from the operating system or ter-
-           minal database.
+       <STRONG>o</STRONG>   Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG>  parameter),  <EM>ncurses</EM>
+           examines  the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables, using a value
+           in those to override the  results  from  the  operating  system  or
+           terminal database.
 
 
-           <STRONG>Ncurses</STRONG> also updates the screen size in response to  <STRONG>SIGWINCH</STRONG>,  un-
-           less overridden by the <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> environment variables,
+           <EM>curses</EM> also updates the screen size in response to <STRONG>SIGWINCH</STRONG>, unless
+           overridden by the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables,
 
 
 </PRE><H3><a name="h3-use_tioctl">use_tioctl</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-use_tioctl">use_tioctl</a></H3><PRE>
-       The  <STRONG>use_tioctl</STRONG>  routine,  if  used, should be called before <STRONG>initscr</STRONG> or
-       <STRONG>newterm</STRONG> are called (because those  compute  the  screen  size).   After
-       <STRONG>use_tioctl</STRONG>  is  called  with  <STRONG>TRUE</STRONG> as an argument, <STRONG>ncurses</STRONG> modifies the
+       The <STRONG>use_tioctl</STRONG> routine, if used, should be  called  before  <STRONG>initscr</STRONG>  or
+       <STRONG>newterm</STRONG>  are  called  (because  those  compute the screen size).  After
+       <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an  argument,  <EM>ncurses</EM>  modifies  the
        last step in its computation of screen size as follows:
 
        last step in its computation of screen size as follows:
 
-       <STRONG>o</STRONG>   checks if the <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> environment variables are set to  a
+       <STRONG>o</STRONG>   checks  if the <EM>LINES</EM> and <EM>COLUMNS</EM> environment variables are set to a
            number greater than zero.
 
            number greater than zero.
 
-       <STRONG>o</STRONG>   for  each,  <STRONG>ncurses</STRONG>  updates the corresponding environment variable
-           with the value that it has obtained via operating  system  call  or
+       <STRONG>o</STRONG>   for each, <EM>ncurses</EM> updates the  corresponding  environment  variable
+           with  the  value  that it has obtained via operating system call or
            from the terminal database.
 
            from the terminal database.
 
-       <STRONG>o</STRONG>   <STRONG>ncurses</STRONG>  re-fetches  the value of the environment variables so that
+       <STRONG>o</STRONG>   <EM>ncurses</EM> re-fetches the value of the environment variables  so  that
            it is still the environment variables which set the screen size.
 
            it is still the environment variables which set the screen size.
 
-       The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as summarized here:
+       The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as follows.
 
 
-           <EM>use</EM><STRONG>_</STRONG><EM>env</EM>   <EM>use</EM><STRONG>_</STRONG><EM>tioctl</EM>   <EM>Summary</EM>
-           ----------------------------------------------------------------
-           TRUE      FALSE        This is the default  behavior.   <STRONG>ncurses</STRONG>
-                                  uses operating system calls unless over-
-                                  ridden by $LINES or $COLUMNS environment
-                                  variables.
+              <STRONG>use_env</STRONG>   <STRONG>use_tioctl</STRONG>   <STRONG>Summary</STRONG>
+              -----------------------------------------------------------------
+              <STRONG>TRUE</STRONG>      <STRONG>FALSE</STRONG>        This  is  the  default behavior.  <EM>ncurses</EM>
+                                     uses  operating   system   calls   unless
+                                     overridden    by    <EM>LINES</EM>    or   <EM>COLUMNS</EM>
+                                     environment variables; default.
+              <STRONG>TRUE</STRONG>      <STRONG>TRUE</STRONG>         <EM>ncurses</EM> updates <EM>LINES</EM> and  <EM>COLUMNS</EM>  based
+                                     on operating system calls.
+              <STRONG>FALSE</STRONG>     <STRONG>TRUE</STRONG>         <EM>ncurses</EM>  ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using
+                                     operating system calls to obtain size.
 
 
-           TRUE      TRUE         <STRONG>ncurses</STRONG>   updates  $LINES  and  $COLUMNS
-                                  based on operating system calls.
-           FALSE     TRUE         <STRONG>ncurses</STRONG> ignores $LINES and $COLUMNS, us-
-                                  es  operating  system  calls  to  obtain
-                                  size.
-           FALSE     FALSE        <STRONG>ncurses</STRONG> relies on the terminal  database
-                                  to determine size.
 
 
+</PRE><H3><a name="h3-putwin_getwin">putwin, getwin</a></H3><PRE>
+       The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad)  <EM>win</EM>
+       into  the  file  to  which <EM>filep</EM> points.  This information can be later
+       retrieved using the <STRONG>getwin</STRONG> function.
 
 
-</PRE><H3><a name="h3-putwin_getwin">putwin/getwin</a></H3><PRE>
-       The  <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM>
-       into the file to which <EM>filep</EM> points.  This information can be later re-
-       trieved using the <STRONG>getwin</STRONG> function.
-
-       The  <STRONG>getwin</STRONG>  routine  reads  window  related data stored in the file by
-       <STRONG>putwin</STRONG>.  The routine then creates and initializes a  new  window  using
-       that  data.   It  returns a pointer to the new window.  There are a few
+       The <STRONG>getwin</STRONG> routine reads window related data  stored  in  the  file  by
+       <STRONG>putwin</STRONG>.   The  routine  then creates and initializes a new window using
+       that data.  It returns a pointer to the new window.  There  are  a  few
        caveats:
 
        caveats:
 
-       <STRONG>o</STRONG>   the data written is a copy of the <STRONG>WINDOW</STRONG> structure, and its associ-
-           ated  character cells.  The format differs between the wide-charac-
-           ter (<STRONG>ncursesw</STRONG>) and non-wide (<STRONG>ncurses</STRONG>) libraries.  You can  transfer
-           data between the two, however.
+       <STRONG>o</STRONG>   the  data  written  is  a  copy  of  the  <EM>WINDOW</EM> structure, and its
+           associated character cells.  The format differs between  the  wide-
+           character  (<EM>ncursesw</EM>)  and  non-wide  (<EM>ncurses</EM>) libraries.  You can
+           transfer data between the two, however.
 
 
-       <STRONG>o</STRONG>   the  retrieved  window  is always created as a top-level window (or
+       <STRONG>o</STRONG>   the retrieved window is always created as a  top-level  window  (or
            pad), rather than a subwindow.
 
            pad), rather than a subwindow.
 
-       <STRONG>o</STRONG>   the window's character cells contain the color pair <EM>value</EM>, but  not
-           the  actual  color  <EM>numbers</EM>.   If cells in the retrieved window use
-           color pairs which have not been created in  the  application  using
+       <STRONG>o</STRONG>   the  window's character cells contain the color pair <EM>value</EM>, but not
+           the actual color <EM>numbers</EM>.  If cells in  the  retrieved  window  use
+           color  pairs  which  have not been created in the application using
            <STRONG>init_pair</STRONG>, they will not be colored when the window is refreshed.
 
 
 </PRE><H3><a name="h3-delay_output">delay_output</a></H3><PRE>
            <STRONG>init_pair</STRONG>, they will not be colored when the window is refreshed.
 
 
 </PRE><H3><a name="h3-delay_output">delay_output</a></H3><PRE>
-       The  <STRONG>delay_output</STRONG>  routine  inserts  an <EM>ms</EM> millisecond pause in output.
-       This routine should not be used extensively because padding  characters
-       are  used  rather  than a CPU pause.  If no padding character is speci-
-       fied, this uses <STRONG>napms</STRONG> to perform the delay.
+       The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM>  millisecond  pause  in  output.
+       Employ  this  function  judiciously  when terminal output uses padding,
+       because <EM>ncurses</EM>  transmits  null  characters  (consuming  CPU  and  I/O
+       resources)  instead  of  sleeping  and  requesting  resumption from the
+       operating system.  Padding is used unless:
+
+       <STRONG>o</STRONG>   the terminal description has <STRONG>npc</STRONG> (<STRONG>no_pad_char</STRONG>) capability, or
+
+       <STRONG>o</STRONG>   the environment variable <STRONG>NCURSES_NO_PADDING</STRONG> is set.
+
+       If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay.   If
+       the  value  of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that
+       value.
 
 
 </PRE><H3><a name="h3-flushinp">flushinp</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-flushinp">flushinp</a></H3><PRE>
@@ -234,29 +254,43 @@
 
        Routines that return pointers return <STRONG>NULL</STRONG> on error.
 
 
        Routines that return pointers return <STRONG>NULL</STRONG> on error.
 
-       X/Open does not define any error conditions.  In this implementation
+       X/Open   Curses  does  not  specify  any  error  conditions.   In  this
+       implementation
 
           <STRONG>flushinp</STRONG>
                returns an error if the terminal was not initialized.
 
           <STRONG>putwin</STRONG>
 
           <STRONG>flushinp</STRONG>
                returns an error if the terminal was not initialized.
 
           <STRONG>putwin</STRONG>
-               returns  an  error if the associated <STRONG>fwrite</STRONG> calls return an er-
-               ror.
+               returns an error if  the  associated  <STRONG>fwrite</STRONG>  calls  return  an
+               error.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 
 </PRE><H3><a name="h3-filter">filter</a></H3><PRE>
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 
 </PRE><H3><a name="h3-filter">filter</a></H3><PRE>
-       The SVr4 documentation describes the  action  of  <STRONG>filter</STRONG>  only  in  the
-       vaguest  terms.   The  description  here is adapted from the XSI Curses
-       standard (which erroneously fails to describe the disabling of <STRONG>cuu</STRONG>).
+       The  SVr4  documentation  describes  the  action  of <STRONG>filter</STRONG> only in the
+       vaguest terms.  The description here  is  adapted  from  X/Open  Curses
+       (which erroneously fails to describe the disabling of <STRONG>cuu</STRONG>).
+
+
+</PRE><H3><a name="h3-delay_output-padding">delay_output padding</a></H3><PRE>
+       The  limitation  to  30  seconds and the use of <STRONG>napms</STRONG> differ from other
+       implementations.
+
+       <STRONG>o</STRONG>   SVr4 curses does not delay if no padding character is available.
+
+       <STRONG>o</STRONG>   NetBSD curses uses <STRONG>napms</STRONG> when no padding  character  is  available,
+           but  does  not  take  timing  into  account  when using the padding
+           character.
+
+       Neither limits the delay.
 
 
 </PRE><H3><a name="h3-keyname">keyname</a></H3><PRE>
 
 
 </PRE><H3><a name="h3-keyname">keyname</a></H3><PRE>
-       The <STRONG>keyname</STRONG> function may return the names of user-defined string  capa-
-       bilities  which  are defined in the terminfo entry via the <STRONG>-x</STRONG> option of
-       <STRONG>tic</STRONG>.  This implementation automatically assigns at run-time keycodes to
-       user-defined  strings  which  begin  with  "k".   The keycodes start at
+       The <STRONG>keyname</STRONG> function  may  return  the  names  of  user-defined  string
+       capabilities  which are defined in the terminfo entry via the <STRONG>-x</STRONG> option
+       of <STRONG>tic</STRONG>.  This implementation automatically assigns at run-time keycodes
+       to  user-defined  strings  which begin with "k".  The keycodes start at
        KEY_MAX, but are not guaranteed to be the same value for different runs
        because  user-defined  codes  are merged from all terminal descriptions
        which have been loaded.  The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG>  function  controls
        KEY_MAX, but are not guaranteed to be the same value for different runs
        because  user-defined  codes  are merged from all terminal descriptions
        which have been loaded.  The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG>  function  controls
@@ -264,19 +298,19 @@
        the library.
 
 
        the library.
 
 
-</PRE><H3><a name="h3-nofilter_use_tioctl">nofilter/use_tioctl</a></H3><PRE>
-       The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are  specific  to  <STRONG>ncurses</STRONG>.   They
+</PRE><H3><a name="h3-nofilter_use_tioctl">nofilter, use_tioctl</a></H3><PRE>
+       The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are  specific  to  <EM>ncurses</EM>.   They
        were  not  supported on Version 7, BSD or System V implementations.  It
        were  not  supported on Version 7, BSD or System V implementations.  It
-       is recommended that any code depending on <STRONG>ncurses</STRONG> extensions be  condi-
-       tioned using NCURSES_VERSION.
+       is recommended  that  any  code  depending  on  <EM>ncurses</EM>  extensions  be
+       conditioned using <STRONG>NCURSES_VERSION</STRONG>.
 
 
 
 
-</PRE><H3><a name="h3-putwin_getwin">putwin/getwin</a></H3><PRE>
+</PRE><H3><a name="h3-putwin_getwin-file-format">putwin/getwin file-format</a></H3><PRE>
        The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions have several issues with portability:
 
        The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions have several issues with portability:
 
-       <STRONG>o</STRONG>   The  files  written  and read by these functions use an implementa-
-           tion-specific format.  Although the format is an obvious target for
-           standardization, it has been overlooked.
+       <STRONG>o</STRONG>   The   files   written   and   read   by   these  functions  use  an
+           implementation-specific format.  Although the format is an  obvious
+           target for standardization, it has been overlooked.
 
            Interestingly  enough,  according to the copyright dates in Solaris
            source, the functions (along with <STRONG>scr_init</STRONG>, etc.)  originated  with
 
            Interestingly  enough,  according to the copyright dates in Solaris
            source, the functions (along with <STRONG>scr_init</STRONG>, etc.)  originated  with
@@ -284,9 +318,9 @@
            1988) incorporated into SVr4.  Oddly, there are no  such  functions
            in the 4.3BSD curses sources.
 
            1988) incorporated into SVr4.  Oddly, there are no  such  functions
            in the 4.3BSD curses sources.
 
-       <STRONG>o</STRONG>   Most implementations simply dump the binary <STRONG>WINDOW</STRONG> structure to the
+       <STRONG>o</STRONG>   Most implementations simply dump the binary <EM>WINDOW</EM> structure to the
            file.  These include SVr4 curses, NetBSD and PDCurses, as  well  as
            file.  These include SVr4 curses, NetBSD and PDCurses, as  well  as
-           older <STRONG>ncurses</STRONG> versions.  This implementation (as well as the X/Open
+           older <EM>ncurses</EM> versions.  This implementation (as well as the X/Open
            variant of Solaris curses, dated 1995) uses textual dumps.
 
            The implementations which  use  binary  dumps  use  block-I/O  (the
            variant of Solaris curses, dated 1995) uses textual dumps.
 
            The implementations which  use  binary  dumps  use  block-I/O  (the
@@ -298,20 +332,20 @@
            file written using mixed schemes may not be successful.
 
 
            file written using mixed schemes may not be successful.
 
 
-</PRE><H3><a name="h3-unctrl_wunctrl">unctrl/wunctrl</a></H3><PRE>
-       The XSI Curses standard, Issue 4 describes these functions.  It  states
-       that <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a null pointer if unsuccessful, but
-       does not define any error conditions.  This implementation  checks  for
-       three cases:
+</PRE><H3><a name="h3-unctrl_wunctrl">unctrl, wunctrl</a></H3><PRE>
+       X/Open Curses, Issue 4  describes  these  functions.   It  states  that
+       <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a null pointer if unsuccessful, but does
+       not define any error conditions.  This implementation checks for  three
+       cases:
 
        <STRONG>o</STRONG>   the  parameter  is  a  7-bit  US-ASCII code.  This is the case that
            X/Open Curses documented.
 
        <STRONG>o</STRONG>   the parameter is in the range 128-159, i.e., a C1 control code.  If
            <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>  has  been  called with a <STRONG>2</STRONG> parameter, <STRONG>unctrl</STRONG>
 
        <STRONG>o</STRONG>   the  parameter  is  a  7-bit  US-ASCII code.  This is the case that
            X/Open Curses documented.
 
        <STRONG>o</STRONG>   the parameter is in the range 128-159, i.e., a C1 control code.  If
            <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>  has  been  called with a <STRONG>2</STRONG> parameter, <STRONG>unctrl</STRONG>
-           returns the parameter, i.e., a one-character string with the param-
-           eter  as  the  first  character.  Otherwise, it returns "~@", "~A",
-           etc., analogous to "^@", "^A", C0 controls.
+           returns the  parameter,  i.e.,  a  one-character  string  with  the
+           parameter  as  the  first  character.   Otherwise, it returns "~@",
+           "~A", etc., analogous to "^@", "^A", C0 controls.
 
            X/Open Curses does not document whether <STRONG>unctrl</STRONG> can be called before
            initializing curses.  This implementation permits that, and returns
 
            X/Open Curses does not document whether <STRONG>unctrl</STRONG> can be called before
            initializing curses.  This implementation permits that, and returns
@@ -322,42 +356,43 @@
 
        The strings returned by <STRONG>unctrl</STRONG> in this implementation are determined at
        compile time, showing C1 controls from the upper-128 codes with  a  "~"
 
        The strings returned by <STRONG>unctrl</STRONG> in this implementation are determined at
        compile time, showing C1 controls from the upper-128 codes with  a  "~"
-       prefix  rather  than "^".  Other implementations have different conven-
-       tions.  For example, they may show both sets of control characters with
-       "^", and strip the parameter to 7 bits.  Or they may ignore C1 controls
-       and treat all of the upper-128 codes as printable.  This implementation
-       uses  8  bits  but  does  not modify the string to reflect locale.  The
-       <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> function allows the caller to change  the  output
-       of <STRONG>unctrl</STRONG>.
+       prefix   rather   than   "^".   Other  implementations  have  different
+       conventions.   For  example,  they  may  show  both  sets  of   control
+       characters  with  "^",  and strip the parameter to 7 bits.  Or they may
+       ignore C1 controls and treat all of the upper-128 codes  as  printable.
+       This  implementation  uses  8  bits  but  does not modify the string to
+       reflect locale.  The <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> function allows  the  caller
+       to change the output of <STRONG>unctrl</STRONG>.
 
        Likewise,  the <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> function allows the caller to change the output
        of <STRONG>keyname</STRONG>, i.e., it determines whether to  use  the  "M-"  prefix  for
 
        Likewise,  the <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> function allows the caller to change the output
        of <STRONG>keyname</STRONG>, i.e., it determines whether to  use  the  "M-"  prefix  for
-       "meta"  keys  (codes  in  the  range 128 to 255).  Both <STRONG>use_legacy_cod-</STRONG>
-       <STRONG><A HREF="use_legacy_coding.3x.html">ing(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> succeed only after curses is initialized.   X/Open
-       Curses  does  not  document  the  treatment  of codes 128 to 159.  When
-       treating them as "meta" keys (or if <STRONG>keyname</STRONG> is called before initializ-
-       ing curses), this implementation returns strings "M-^@", "M-^A", etc.
-
-       X/Open Curses documents <STRONG>unctrl</STRONG> as declared in <STRONG>&lt;unctrl.h&gt;</STRONG>, which <STRONG>ncurses</STRONG>
-       does.  However, <STRONG>ncurses</STRONG>' <STRONG>&lt;curses.h&gt;</STRONG> includes <STRONG>&lt;unctrl.h&gt;</STRONG>,  matching  the
+       "meta"    keys    (codes    in   the   range   128   to   255).    Both
+       <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>  and  <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG>  succeed  only  after  curses   is
+       initialized.   X/Open  Curses  does not document the treatment of codes
+       128 to 159.  When treating them as "meta" keys (or if <STRONG>keyname</STRONG> is called
+       before   initializing  curses),  this  implementation  returns  strings
+       "M-^@", "M-^A", etc.
+
+       X/Open Curses documents <STRONG>unctrl</STRONG> as declared in <STRONG>&lt;unctrl.h&gt;</STRONG>, which <EM>ncurses</EM>
+       does.   However,  <EM>ncurses</EM>' <STRONG>&lt;curses.h&gt;</STRONG> includes <STRONG>&lt;unctrl.h&gt;</STRONG>, matching the
        behavior of SVr4 curses.  Other implementations may not do that.
 
 
        behavior of SVr4 curses.  Other implementations may not do that.
 
 
-</PRE><H3><a name="h3-use_env_use_tioctl">use_env/use_tioctl</a></H3><PRE>
-       If  <STRONG>ncurses</STRONG>  is  configured  to provide the sp-functions extension, the
-       state of <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> may be  updated  before  creating  each
-       <EM>screen</EM>  rather  than  once  only  (<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>).  This feature of
-       <STRONG>use_env</STRONG> is not provided by other implementation of curses.
+</PRE><H3><a name="h3-use_env_use_tioctl">use_env, use_tioctl</a></H3><PRE>
+       If <EM>ncurses</EM> is configured to provide  the  sp-functions  extension,  the
+       state  of  <STRONG>use_env</STRONG>  and  <STRONG>use_tioctl</STRONG> may be updated before creating each
+       <EM>screen</EM> rather than once  only  (<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>).   This  feature  of
+       <STRONG>use_env</STRONG> is not provided by other implementations of curses.
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-       <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>,   <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,
-       <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,   <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>,   <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>,   <STRONG>curs_vari-</STRONG>
-       <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>, <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>.
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,    <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,    <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>,   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,
+       <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>,        <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>,        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
+       <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>
 
 
 
 
 
 
-                                                                 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+ncurses 6.4                       2024-04-20                     <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
 </PRE>
 <div class="nav">
 <ul>
 </PRE>
 <div class="nav">
 <ul>
@@ -366,11 +401,11 @@
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h3-unctrl">unctrl</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h3-unctrl">unctrl</a></li>
-<li><a href="#h3-keyname_key_name">keyname/key_name</a></li>
-<li><a href="#h3-filter_nofilter">filter/nofilter</a></li>
+<li><a href="#h3-keyname_key_name">keyname, key_name</a></li>
+<li><a href="#h3-filter_nofilter">filter, nofilter</a></li>
 <li><a href="#h3-use_env">use_env</a></li>
 <li><a href="#h3-use_tioctl">use_tioctl</a></li>
 <li><a href="#h3-use_env">use_env</a></li>
 <li><a href="#h3-use_tioctl">use_tioctl</a></li>
-<li><a href="#h3-putwin_getwin">putwin/getwin</a></li>
+<li><a href="#h3-putwin_getwin">putwin, getwin</a></li>
 <li><a href="#h3-delay_output">delay_output</a></li>
 <li><a href="#h3-flushinp">flushinp</a></li>
 </ul>
 <li><a href="#h3-delay_output">delay_output</a></li>
 <li><a href="#h3-flushinp">flushinp</a></li>
 </ul>
@@ -379,11 +414,12 @@
 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 <ul>
 <li><a href="#h3-filter">filter</a></li>
 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 <ul>
 <li><a href="#h3-filter">filter</a></li>
+<li><a href="#h3-delay_output-padding">delay_output padding</a></li>
 <li><a href="#h3-keyname">keyname</a></li>
 <li><a href="#h3-keyname">keyname</a></li>
-<li><a href="#h3-nofilter_use_tioctl">nofilter/use_tioctl</a></li>
-<li><a href="#h3-putwin_getwin">putwin/getwin</a></li>
-<li><a href="#h3-unctrl_wunctrl">unctrl/wunctrl</a></li>
-<li><a href="#h3-use_env_use_tioctl">use_env/use_tioctl</a></li>
+<li><a href="#h3-nofilter_use_tioctl">nofilter, use_tioctl</a></li>
+<li><a href="#h3-putwin_getwin-file-format">putwin/getwin file-format</a></li>
+<li><a href="#h3-unctrl_wunctrl">unctrl, wunctrl</a></li>
+<li><a href="#h3-use_env_use_tioctl">use_env, use_tioctl</a></li>
 </ul>
 </li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 </ul>
 </li>
 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
ncurses, with patches starting at ncurses-5.6; new users should use https://github.com/ThomasDickey/ncurses-snapshots/