X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_util.3x.html;h=8839fce8739b20786332a8a04069412e20857a98;hp=650e6513c40fc2bdcfe59a2dec7e2c1a08971faf;hb=HEAD;hpb=894a177fd5228cdbe790bd1dc9435bd435c29681 diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 650e6513..bce853e2 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -1,7 +1,7 @@ -curs_util 3x 2023-10-07 ncurses 6.4 Library calls +curs_util 3x 2024-05-11 ncurses 6.5 Library calls -

curs_util 3x 2023-10-07 ncurses 6.4 Library calls

+

curs_util 3x 2024-05-11 ncurses 6.5 Library calls

 curs_util(3x)                    Library calls                   curs_util(3x)
 
@@ -56,15 +56,15 @@

SYNOPSIS

        #include <curses.h>
 
-       const char *unctrl(chtype c);
-       wchar_t *wunctrl(cchar_t *c);
+       const char *unctrl(chtype ch);
+       wchar_t *wunctrl(cchar_t *wch);
 
        const char *keyname(int c);
-       const char *key_name(wchar_t w);
+       const char *key_name(wchar_t wc);
 
        void filter(void);
 
-       void use_env(bool f);
+       void use_env(bool bf);
 
        int putwin(WINDOW *win, FILE *filep);
        WINDOW *getwin(FILE *filep);
@@ -74,14 +74,14 @@
 
        /* extensions */
        void nofilter(void);
-       void use_tioctl(bool f);
+       void use_tioctl(bool bf);

DESCRIPTION

unctrl

        The  unctrl  routine  returns  a  character string which is a printable
-       representation of the character c:
+       representation of the character ch:
 
        o   Printable characters are displayed  as  themselves,  e.g.,  a  one-
            character string containing the key.
@@ -99,13 +99,13 @@
            this follows the X/Open specification.
 
        The  corresponding  wunctrl  returns  a  printable  representation of a
-       complex character c.
+       complex character wch.
 
        In both unctrl and wunctrl the attributes and color associated with the
        character parameter are ignored.
 
 
-

keyname/key_name

+

keyname, key_name

        The keyname routine returns a character string corresponding to the key
        c.  Key codes are different from character codes.
 
@@ -129,7 +129,7 @@
        o   key_name does not return the name of a function key.
 
 
-

filter/nofilter

+

filter, nofilter

        The  filter  routine, if used, must be called before initscr or newterm
        are called.  Calling filter causes these changes in initialization:
 
@@ -163,74 +163,82 @@
        o   Then  it  asks  for the screen size via operating system calls.  If
            successful, it overrides the values from the terminal database.
 
-       o   Finally (unless use_env was called with FALSE  parameter),  ncurses
-           examines  the LINES or COLUMNS environment variables, using a value
+       o   Finally (unless use_env was called with FALSE  parameter),  ncurses
+           examines  the LINES or COLUMNS environment variables, using a value
            in those to override the  results  from  the  operating  system  or
            terminal database.
 
-           Ncurses  also  updates  the  screen  size  in response to SIGWINCH,
-           unless overridden by the LINES or COLUMNS environment variables,
+           curses also updates the screen size in response to SIGWINCH, unless
+           overridden by the LINES or COLUMNS environment variables,

use_tioctl

        The use_tioctl routine, if used, should be  called  before  initscr  or
        newterm  are  called  (because  those  compute the screen size).  After
-       use_tioctl is called with TRUE as an  argument,  ncurses  modifies  the
+       use_tioctl is called with TRUE as an  argument,  ncurses  modifies  the
        last step in its computation of screen size as follows:
 
-       o   checks  if the LINES and COLUMNS environment variables are set to a
+       o   checks  if the LINES and COLUMNS environment variables are set to a
            number greater than zero.
 
-       o   for each, ncurses updates the  corresponding  environment  variable
+       o   for each, ncurses updates the  corresponding  environment  variable
            with  the  value  that it has obtained via operating system call or
            from the terminal database.
 
-       o   ncurses re-fetches the value of the environment variables  so  that
+       o   ncurses re-fetches the value of the environment variables  so  that
            it is still the environment variables which set the screen size.
 
        The use_env and use_tioctl routines combine as follows.
 
               use_env   use_tioctl   Summary
               -----------------------------------------------------------------
-              TRUE      FALSE        This  is  the  default behavior.  ncurses
-                                     uses  operating   system   calls   unless
-                                     overridden    by    LINES    or   COLUMNS
+              TRUE      FALSE        ncurses   uses   operating  system  calls
+                                     unless overridden  by  LINES  or  COLUMNS
                                      environment variables; default.
-              TRUE      TRUE         ncurses updates LINES and  COLUMNS  based
+              TRUE      TRUE         ncurses  updates  LINES and COLUMNS based
                                      on operating system calls.
-              FALSE     TRUE         ncurses  ignores LINES and COLUMNS, using
+              FALSE     TRUE         ncurses ignores LINES and COLUMNS,  using
                                      operating system calls to obtain size.
 
 
-

putwin/getwin

-       The putwin routine writes all data associated with window (or pad)  win
-       into  the  file  to  which filep points.  This information can be later
+

putwin, getwin

+       The  putwin routine writes all data associated with window (or pad) win
+       into the file to which filep points.  This  information  can  be  later
        retrieved using the getwin function.
 
-       The getwin routine reads window related data  stored  in  the  file  by
-       putwin.   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  getwin  routine  reads  window  related data stored in the file by
+       putwin.  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:
 
-       o   the  data  written  is  a  copy  of  the  WINDOW structure, and its
-           associated character cells.  The format differs between  the  wide-
-           character  (ncursesw)  and  non-wide  (ncurses) libraries.  You can
+       o   the data written is  a  copy  of  the  WINDOW  structure,  and  its
+           associated  character  cells.  The format differs between the wide-
+           character (ncursesw) and non-wide  (ncurses)  libraries.   You  can
            transfer data between the two, however.
 
-       o   the retrieved window is always created as a  top-level  window  (or
+       o   the  retrieved  window  is always created as a top-level window (or
            pad), rather than a subwindow.
 
-       o   the  window's character cells contain the color pair value, but not
-           the actual color numbers.  If cells in  the  retrieved  window  use
-           color  pairs  which  have not been created in the application using
+       o   the window's character cells contain the color pair value, but  not
+           the  actual  color  numbers.   If cells in the retrieved window use
+           color pairs which have not been created in  the  application  using
            init_pair, they will not be colored when the window is refreshed.

delay_output

-       The delay_output routine inserts an ms  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
-       specified, this uses napms to perform the delay.
+       The  delay_output  routine  inserts  an ms millisecond pause in output.
+       Employ this function judiciously when  terminal  output  uses  padding,
+       because  ncurses  transmits  null  characters  (consuming  CPU  and I/O
+       resources) instead of  sleeping  and  requesting  resumption  from  the
+       operating system.  Padding is used unless:
+
+       o   the terminal description has npc (no_pad_char) capability, or
+
+       o   the environment variable NCURSES_NO_PADDING is set.
+
+       If  padding is not in use, ncurses uses napms to perform the delay.  If
+       the value of ms exceeds 30,000 (thirty seconds), it is capped  at  that
+       value.

flushinp

@@ -245,22 +253,36 @@
 
        Routines that return pointers return NULL 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
 
           flushinp
                returns an error if the terminal was not initialized.
 
           putwin
-               returns an error if  the  associated  fwrite  calls  return  an
+               returns  an  error  if  the  associated  fwrite calls return an
                error.

PORTABILITY

filter

-       The  SVr4  documentation  describes  the  action  of filter only in the
-       vaguest terms.  The description here is adapted  from  the  XSI  Curses
-       standard (which erroneously fails to describe the disabling of cuu).
+       The SVr4 documentation describes the  action  of  filter  only  in  the
+       vaguest  terms.   The  description  here  is adapted from X/Open Curses
+       (which erroneously fails to describe the disabling of cuu).
+
+
+

delay_output padding

+       The limitation to 30 seconds and the use of  napms  differ  from  other
+       implementations.
+
+       o   SVr4 curses does not delay if no padding character is available.
+
+       o   NetBSD  curses  uses  napms when no padding character is available,
+           but does not take  timing  into  account  when  using  the  padding
+           character.
+
+       Neither limits the delay.

keyname

@@ -275,10 +297,10 @@
        the library.
 
 
-

nofilter/use_tioctl

-       The  nofilter  and  use_tioctl  routines are specific to ncurses.  They
+

nofilter, use_tioctl

+       The  nofilter  and  use_tioctl  routines are specific to ncurses.  They
        were not supported on Version 7, BSD or System V  implementations.   It
-       is  recommended  that  any  code  depending  on  ncurses  extensions be
+       is  recommended  that  any  code  depending  on  ncurses  extensions be
        conditioned using NCURSES_VERSION.
 
 
@@ -295,9 +317,9 @@
            1988)  incorporated  into SVr4.  Oddly, there are no such functions
            in the 4.3BSD curses sources.
 
-       o   Most implementations simply dump the binary WINDOW structure to the
+       o   Most implementations simply dump the binary WINDOW structure to the
            file.   These  include SVr4 curses, NetBSD and PDCurses, as well as
-           older ncurses versions.  This implementation (as well as the X/Open
+           older ncurses 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
@@ -309,11 +331,11 @@
            file written using mixed schemes may not be successful.
 
 
-

unctrl/wunctrl

-       The  XSI Curses standard, Issue 4 describes these functions.  It states
-       that unctrl and wunctrl will return a null pointer if unsuccessful, but
-       does  not  define any error conditions.  This implementation checks for
-       three cases:
+

unctrl, wunctrl

+       X/Open  Curses,  Issue  4  describes  these  functions.  It states that
+       unctrl and wunctrl will return a null pointer if unsuccessful, but does
+       not  define any error conditions.  This implementation checks for three
+       cases:
 
        o   the parameter is a 7-bit US-ASCII code.   This  is  the  case  that
            X/Open Curses documented.
@@ -350,13 +372,13 @@
        before  initializing  curses),  this  implementation  returns   strings
        "M-^@", "M-^A", etc.
 
-       X/Open Curses documents unctrl as declared in <unctrl.h>, which ncurses
-       does.  However, ncurses' <curses.h> includes <unctrl.h>,  matching  the
+       X/Open Curses documents unctrl as declared in <unctrl.h>, which ncurses
+       does.  However, ncurses' <curses.h> includes <unctrl.h>,  matching  the
        behavior of SVr4 curses.  Other implementations may not do that.
 
 
-

use_env/use_tioctl

-       If  ncurses  is  configured  to provide the sp-functions extension, the
+

use_env, use_tioctl

+       If  ncurses  is  configured  to provide the sp-functions extension, the
        state of use_env and use_tioctl may be  updated  before  creating  each
        screen  rather  than  once  only  (curs_sp_funcs(3x)).  This feature of
        use_env is not provided by other implementations of curses.
@@ -369,7 +391,7 @@
 
 
 
-ncurses 6.4                       2023-10-07                     curs_util(3x)
+ncurses 6.5                       2024-05-11                     curs_util(3x)