curs_inwstr 3x 2023-11-25 ncurses 6.4 Library calls

curs_inwstr 3x 2023-12-30 ncurses 6.4 Library calls

curs_inwstr 3x 2023-11-25 ncurses 6.4 Library calls

curs_inwstr 3x 2023-12-30 ncurses 6.4 Library calls

 curs_inwstr(3x)                  Library calls                 curs_inwstr(3x)
 
@@ -100,13 +100,14 @@

NOTES

        All routines except winnwstr may be macros.
 
-       Each cell in the window holds a  complex  character  (i.e.,  base-  and
-       combining-characters)   together  with  attributes  and  color.   These
-       functions store only  the  wide  characters,  ignoring  attributes  and
-       color.  Use in_wchstr to return the complex characters from a window.
+       Each cell in the window holds a complex character (a spacing  character
+       and  zero  or more non-spacing characters) together with attributes and
+       color.  These  functions  store  only  the  wide  characters,  ignoring
+       attributes  and  color.  Use in_wchstr to return the complex characters
+       from a window.
 
        Reading a line that overflows the array pointed to by wstr with inwstr,
-       mvinwstr, mvwinwstr or winwstr causes  undefined  results.   Therefore,
+       mvinwstr,  mvwinwstr  or  winwstr causes undefined results.  Therefore,
        the use of innwstr, mvinnwstr, mvwinnwstr, or winnwstr is recommended.
 
 
@@ -115,12 +116,12 @@

curs_scr_dump 3x 2023-12-16 ncurses 6.4 Library calls

curs_scr_dump 3x 2023-12-30 ncurses 6.4 Library calls

 curs_scr_dump(3x)                Library calls               curs_scr_dump(3x)
 
@@ -61,62 +62,67 @@

DESCRIPTION

+       curses provides applications the ability to write the contents  of  the
+       screen  to  a  file and read them back.  To read/write a window (rather
+       than the whole screen) from/to a file, use getwin(3x)  and  putwin(3x),
+       respectively.
+

scr_dump

-       The scr_dump routine dumps the current contents of the  virtual  screen
-       to the file filename.
+       scr_dump  writes  to  filename  the contents of the virtual screen; see
+       curscr(3x).

scr_restore

-       The  scr_restore  routine  sets  the  virtual screen to the contents of
-       filename, which must have been written using scr_dump.  The  next  call
-       to  doupdate  restores  the physical screen to the way it looked in the
-       dump file.
+       scr_restore updates the virtual  screen  to  contain  the  contents  of
+       filename  (if  it  was  validly  written with scr_dump).  No refresh is
+       performed;  after  performing  any  further   desired   updates,   call
+       doupdate(3x) or similar.

scr_init

-       The scr_init routine reads in the contents of filename and uses them to
-       initialize the curses data structures about what the terminal currently
-       has on its screen.  If the data is determined to be valid, curses bases
-       its  next update of the screen on this information rather than clearing
-       the  screen  and  starting  from  scratch.   scr_init  is  used   after
-       initscr(3x)  or  a  system(3)  call  to  share  the screen with another
-       process which has done a scr_dump after its endwin(3x) call.  The  data
-       is declared invalid
+       scr_init  reads filename, using it to initialize curses data structures
+       describing the state of the terminal screen.  If these data are  valid,
+       curses  bases  its next update of the screen on this information rather
+       than clearing it and starting from scratch.
+
+       The data fail the validity check
+
+       o   if the terminal employs terminfo capabilities exit_ca_mode  (rmcup)
+           or non_rev_rmcup (nrrmc) are defined, or
 
-       o   if the terminfo capabilities rmcup and nrrmc exist, also
+       o   if  curses  knows  that  the terminal has been written to since the
+           preceding scr_dump call.
 
-       o   if  the  terminal  has been written to since the preceding scr_dump
-           call.
+       scr_init could be used after initscr(3x)  or  system(3)  to  share  the
+       screen with another process that has done a scr_dump after endwin(3x).

scr_set

-       The scr_set routine is a combination of scr_restore and  scr_init.   It
+       The  scr_set  routine is a combination of scr_restore and scr_init.  It
        tells the program that the information in filename is what is currently
        on the screen, and also what the program wants on the screen.  This can
        be thought of as a screen inheritance function.
 
-       To  read  (write)  a window from (to) a file, use the getwin and putwin
-       routines [see curs_util(3x)].
-

RETURN VALUE

-       These routines return the integer ERR upon failure and OK upon success.
+       These functions return OK on success and ERR on failure.
 
-       X/Open defines no error conditions.  In this implementation, each  will
-       return an error if the file cannot be opened.
+       X/Open defines no failure conditions.   In  this  implementation,  each
+       function fails if it cannot open filename.

NOTES

-       Note that scr_init, scr_set, and scr_restore may be macros.
+       scr_init, scr_set, and scr_restore may be macros.

PORTABILITY

-       These  functions  are  described  in  the XSI Curses standard, Issue 4,
-       which adds const qualifiers to the arguments.
+       X/Open Curses, Issue 4, describes these functions.
+
+       SVr4 omitted the const qualifiers.
 
-       The SVr4 docs merely say under scr_init that  the  dump  data  is  also
-       considered  invalid  "if  the  time-stamp of the tty is old" but do not
+       SVr4  documentation  describes scr_init such that the dump data is also
+       considered invalid "if the time-stamp of the tty is old" but  does  not
        define "old".
 
 
@@ -126,7 +132,7 @@
 
 
 
-ncurses 6.4                       2023-12-16                 curs_scr_dump(3x)
+ncurses 6.4                       2023-12-30                 curs_scr_dump(3x)

curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-30 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-30 ncurses 6.4 Library calls

 curs_termcap(3x)                 Library calls                curs_termcap(3x)
 
@@ -315,33 +315,34 @@
        program.  The library remained much the same though 4.3BSD (June 1986).
        4.4BSD-Lite (June 1994) refactored it, leaving the API unchanged.
 
-       Function  prototypes were a feature of ANSI C (1989).  Thus the library
-       itself provided no header file declaring them.  Nevertheless,  the  BSD
-       sources included two different termcap.h header files over time.
+       Function  prototypes were a feature of ANSI C (1989).  The library long
+       antedated the standard and thus provided no header file declaring them.
+       Nevertheless,  the  BSD sources included two different termcap.h header
+       files over time.
 
-       o   One was used internally by jove(1) from 4.3BSD onward.  It delcared
+       o   One was used internally by jove(1) from 4.3BSD onward.  It declared
            global symbols for the termcap variables that it used.
 
-       o   The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part  of
-           libedit  (also known as the editline library).  CSRG source history
+       o   The  other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
+           libedit (also known as the editline library).  CSRG source  history
            shows that this was added in mid-1992.  The libedit header file was
            used  internally  as  a  convenience  for  compiling  the  editline
            library.  It declared function prototypes, but no global variables.
            This header file was added to NetBSD's termcap library in mid-1994.
 
-       Meanwhile,  GNU  termcap  began development in 1990.  Its first release
-       (1.0) in 1991  included  a  termcap.h  header.   Its  second  (1.1)  in
-       September  1992  modified  the  header  to  use  const for the function
-       prototypes in the header where one would expect the  parameters  to  be
+       Meanwhile, GNU termcap began development in 1990.   Its  first  release
+       (1.0)  in  1991  included  a  termcap.h  header.   Its  second (1.1) in
+       September 1992 modified the  header  to  use  const  for  the  function
+       prototypes  in  the  header where one would expect the parameters to be
        read-only.   BSD  termcap  did  not.   The  prototype  for  tputs  also
-       differed, but in that instance, it was libedit that differed  from  BSD
+       differed,  but  in that instance, it was libedit that differed from BSD
        termcap.
 
-       GNU  termcap  1.3  was  bundled with bash(1) in mid-1993 to support the
+       GNU termcap 1.3 was bundled with bash(1) in  mid-1993  to  support  the
        readline(3) library.
 
-       ncurses 1.8.1 (November 1993) provided a termcap.h file.  It  reflected
-       influence   from  GNU  termcap  and  emacs(1)  (rather  than  jove(1)),
+       ncurses  1.8.1 (November 1993) provided a termcap.h file.  It reflected
+       influence  from  GNU  termcap  and  emacs(1)  (rather  than   jove(1)),
        providing the following interface:
 
        o   global symbols used by emacs,
@@ -350,41 +351,41 @@
 
        o   a prototype for tparam, a GNU termcap feature.
 
-       Later (in mid-1996) the tparam function was removed from ncurses.   Any
-       two  of  the four implementations thus differ, and programs that intend
+       Later  (in mid-1996) the tparam function was removed from ncurses.  Any
+       two of the four implementations thus differ, and programs  that  intend
        to work with all termcap library interfaces must account for that fact.

BUGS

        If  you  call  tgetstr  to  fetch  column_address  (ch)  or  any  other
-       parameterized  string capability, be aware that it is returned in term-
+       parameterized string capability, be aware that it is returned in  term-
        info notation, not the older and not-quite-compatible termcap notation.
-       This  does  not  cause  problems if all you do with it is call tgoto or
-       tparm, which both expand terminfo-style strings as terminfo does.   (If
-       ncurses  is  configured  to  support  termcap, tgoto checks whether the
-       string is terminfo-style by looking  for  "%p"  parameters  or  "<...>"
+       This does not cause problems if all you do with it  is  call  tgoto  or
+       tparm,  which both expand terminfo-style strings as terminfo does.  (If
+       ncurses is configured to support  termcap,  tgoto  checks  whether  the
+       string  is  terminfo-style  by  looking  for "%p" parameters or "<...>"
        delays, and invokes a termcap-style parser if the string appears not to
        use terminfo syntax.)
 
-       Because terminfo's syntax for padding in  string  capabilities  differs
+       Because  terminfo's  syntax  for padding in string capabilities differs
        from termcap's, users can be surprised.
 
-       o   tputs("50")  in  a terminfo system transmits "50" rather than busy-
+       o   tputs("50") in a terminfo system transmits "50" rather  than  busy-
            waiting for 50 milliseconds.
 
-       o   However, if ncurses is configured to support termcap, it  may  also
+       o   However,  if  ncurses is configured to support termcap, it may also
            have been configured to support BSD-style padding.
 
-           In  that  case,  tputs  inspects  strings passed to it, looking for
+           In that case, tputs inspects strings  passed  to  it,  looking  for
            digits at the beginning of the string.
 
-           tputs("50") in a termcap system may busy-wait for  50  milliseconds
+           tputs("50")  in  a termcap system may busy-wait for 50 milliseconds
            rather than transmitting "50".
 
        termcap  has  nothing  analogous  to  terminfo's  set_attributes  (sgr)
-       capability.  One consequence is that termcap applications  assume  that
-       "me"  (equivalent  to terminfo's exit_attribute_mode (sgr0) capability)
-       does not reset the alternate character set.  ncurses  checks  for,  and
+       capability.   One  consequence is that termcap applications assume that
+       "me" (equivalent to terminfo's exit_attribute_mode  (sgr0)  capability)
+       does  not  reset  the alternate character set.  ncurses checks for, and
        modifies the data shared with, the termcap interface to accommodate the
        latter's limitation in this respect.
 
@@ -396,7 +397,7 @@
 
 
 
-ncurses 6.4                       2023-12-23                  curs_termcap(3x)
+ncurses 6.4                       2023-12-30                  curs_termcap(3x)

curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls

curs_terminfo 3x 2023-12-30 ncurses 6.4 Library calls

curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls

curs_terminfo 3x 2023-12-30 ncurses 6.4 Library calls

 curs_terminfo(3x)                Library calls               curs_terminfo(3x)
 
@@ -124,39 +123,39 @@
        recommended.
 
        None of these functions use  (or  are  aware  of)  multibyte  character
-       strings such as UTF-8:
+       strings such as UTF-8.
 
-       o   capability names use the POSIX portable character set
+       o   Capability names and codes use the POSIX portable character set.
 
-       o   capability  string  values  have  no  associated encoding; they are
+       o   Capability  string  values  have  no  associated encoding; they are
            strings of 8-bit characters.

Initialization

-       Initially, setupterm should be called.  The high-level curses functions
+       Initially, setupterm should be called.  The high-level curses functions
        initscr  and  newterm call setupterm to initialize the low-level set of
-       terminal-dependent variables [listed in terminfo(5)].
+       terminal-dependent variables listed in term_variables(3x).
 
        Applications can use the terminal  capabilities  either  directly  (via
        header  definitions),  or  by  special  functions.   The  header  files
-       curses.h and term.h should be included  (in  this  order)  to  get  the
+       curses.h and term.h should be included  (in  that  order)  to  get  the
        definitions for these strings, numbers, and flags.
 
-       The  terminfo  variables lines and columns are initialized by setupterm
+       The  terminfo  variables lines and columns are initialized by setupterm
        as follows:
 
        o   If use_env(FALSE) has been called, values  for  lines  and  columns
-           specified in terminfo are used.
+           specified in terminfo are used.
 
        o   Otherwise,  if  the  environment variables LINES and COLUMNS exist,
            their values are used.  If these environment variables do not exist
            and  the program is running in a window, the current window size is
            used.  Otherwise, if the environment variables do  not  exist,  the
-           values for lines and columns specified in the terminfo database are
+           values for lines and columns specified in the terminfo database are
            used.
 
        Parameterized strings should be passed  through  tparm  to  instantiate
-       them.   All  terminfo strings (including the output of tparm) should be
+       them.   All  terminfo strings (including the output of tparm) should be
        printed with tputs or putp.  Call reset_shell_mode to restore  the  tty
        modes before exiting [see curs_kernel(3x)].
 
@@ -174,9 +173,9 @@
        o   output enter_ca_mode and call reset_prog_mode after returning  from
            the shell.
 
-       The  setupterm routine reads in the terminfo database, initializing the
-       terminfo structures, but does not  set  up  the  output  virtualization
-       structures used by curses.  These are its parameters:
+       The  setupterm routine reads in the terminfo database, initializing the
+       terminfo structures, but does not  set  up  the  output  virtualization
+       structures used by curses.  These are its parameters:
 
           term is the terminal type, a character string.  If term is null, the
                environment variable TERM is used.
@@ -218,9 +217,9 @@
                If errret is null,  setupterm  prints  an  error  message  upon
                finding an error and exits.  Thus, the simplest call is:
 
-               setupterm((char *)0, 1, (int *)0);,
+                      setupterm((char *)0, 1, (int *)0);
 
-          which uses all the defaults and sends the output to stdout.
+               which uses all the defaults and sends the output to stdout.

The Terminal State

@@ -236,13 +235,13 @@
        terminal types,  setupterm  allocates  new  storage  for  each  set  of
        terminal capabilities.
 
-       The  set_curterm  routine  sets cur_term to nterm, and makes all of the
-       terminfo boolean, numeric, and string variables  use  the  values  from
-       nterm.  It returns the old value of cur_term.
+       set_curterm  sets  cur_term  to  nterm,  and  makes all of the terminfo
+       Boolean, numeric, and string variables use the values from  nterm.   It
+       returns the old value of cur_term.
 
-       The  del_curterm  routine frees the space pointed to by oterm and makes
-       it available for further use.   If  oterm  is  the  same  as  cur_term,
-       references  to  any  of  the  terminfo  boolean,  numeric,  and  string
+       del_curterm  routine  frees  the space pointed to by oterm and makes it
+       available  for  further  use.   If  oterm  is  the  same  as  cur_term,
+       references  to  any  of  the  terminfo  Boolean,  numeric,  and  string
        variables thereafter  may  refer  to  invalid  memory  locations  until
        another setupterm has been called.
 
@@ -273,9 +272,9 @@
        o   The  capability  string  is  null-terminated.   Use "\200" where an
            ASCII NUL is needed in the output.
 
-       tiparm is a newer form of tparm which uses  <stdarg.h>  rather  than  a
-       fixed-parameter list.  Its numeric parameters are integers (int) rather
-       than longs.
+       tiparm is a newer form of tparm  which  uses  stdarg.h  rather  than  a
+       fixed-parameter  list.   Its  numeric  parameters  are ints rather than
+       longs.
 
        Both tparm and tiparm assume that  the  application  passes  parameters
        consistent  with the terminal description.  Two extensions are provided
@@ -329,44 +328,43 @@
        The vidattr routine is like the vidputs routine, except that it outputs
        through putchar.
 
-       The vid_attr and vid_puts routines correspond to vidattr  and  vidputs,
-       respectively.   They  use a set of arguments for representing the video
-       attributes plus color, i.e.,
+       vid_attr and vid_puts correspond to vidattr and vidputs,  respectively.
+       They  use multiple parameters to represent the character attributes and
+       color; namely,
 
-       o   attrs of type attr_t for the attributes and
+       o   attrs, of type attr_t, for the attributes and
 
-       o   pair of type short for the color pair number.
+       o   pair, of type short, for the color pair number.
 
-       The vid_attr and vid_puts routines are designed to  use  the  attribute
-       constants with the WA_ prefix.
+       Use the attribute constants  prefixed  with  "WA_"  with  vid_attr  and
+       vid_puts.
 
        X/Open  Curses  reserves  the opts argument for future use, saying that
-       applications must provide a null pointer  for  that  argument.   As  an
-       extension,  this  implementation allows opts to be used as a pointer to
-       int, which overrides the pair (short) argument.
+       applications must provide a null pointer for  that  argument;  but  see
+       section "EXTENSIONS" below.
 
-       The mvcur routine provides low-level cursor motion.   It  takes  effect
-       immediately  (rather  than at the next refresh).  Unlike the other low-
-       level output functions, which either write to the  standard  output  or
+       The  mvcur  routine  provides low-level cursor motion.  It takes effect
+       immediately (rather than at the next refresh).  Unlike the  other  low-
+       level  output  functions,  which either write to the standard output or
        pass an output function parameter, mvcur uses an output file descriptor
        derived from the output stream parameter of newterm(3x).
 
        While putp and mvcur are low-level functions which do not use the high-
-       level  curses  state,  they are declared in <curses.h> because System V
-       did this (see HISTORY).
+       level curses state, they are declared in curses.h because System V  did
+       this (see HISTORY).

Terminal Capability Functions

-       The tigetflag, tigetnum and tigetstr routines return the value  of  the
-       capability  corresponding  to the terminfo capname passed to them, such
-       as xenl.  The capname for each capability is given in the table  column
+       The  tigetflag,  tigetnum and tigetstr routines return the value of the
+       capability corresponding to the terminfo capname passed to  them,  such
+       as  xenl.  The capname for each capability is given in the table column
        entitled capname code in the capabilities section of terminfo(5).
 
        These routines return special values to denote errors.
 
        The tigetflag routine returns
 
-       -1     if capname is not a boolean capability, or
+       -1     if capname is not a Boolean capability, or
 
        0      if it is canceled or absent from the terminal description.
 
@@ -402,89 +400,72 @@

Releasing Memory

        Each successful call to setupterm allocates memory to hold the terminal
-       description.  As a side-effect, it  sets  cur_term  to  point  to  this
+       description.   As  a  side-effect,  it  sets  cur_term to point to this
        memory.  If an application calls
 
               del_curterm(cur_term);
 
        the memory will be freed.
 
-       The  formatting functions tparm and tiparm extend the storage allocated
+       The formatting functions tparm and tiparm extend the storage  allocated
        by setupterm:
 
-       o   the "static" terminfo variables [a-z].  Before ncurses  6.3,  those
-           were  shared by all screens.  With ncurses 6.3, those are allocated
+       o   the  "static"  terminfo variables [a-z].  Before ncurses 6.3, those
+           were shared by all screens.  With ncurses 6.3, those are  allocated
            per screen.  See terminfo(5) for details.
 
-       o   to improve performance, ncurses 6.3 caches the result of  analyzing
-           terminfo  strings  for  their parameter types.  That is stored as a
+       o   to  improve performance, ncurses 6.3 caches the result of analyzing
+           terminfo strings for their parameter types.  That is  stored  as  a
            binary tree referenced from the TERMINAL structure.
 
        The higher-level initscr and newterm functions use setupterm.  Normally
-       they  do  not free this memory, but it is possible to do that using the
+       they do not free this memory, but it is possible to do that  using  the
        delscreen(3x) function.

RETURN VALUE

-       Routines that return an integer return ERR upon failure  and  OK  (SVr4
-       only  specifies  "an  integer  value  other  than ERR") upon successful
-       completion,  unless  otherwise   noted   in   the   preceding   routine
-       descriptions.
+       X/Open defines no failure conditions.  In ncurses,
 
-       Routines that return pointers always return NULL on error.
+       del_curterm
+            returns an error if its terminal parameter is null.
 
-       X/Open defines no error conditions.  In this implementation
+       putp calls tputs, returning the same error-codes.
 
-          del_curterm
-               returns an error if its terminal parameter is null.
+       restartterm
+            returns  an  error  if the associated call to setupterm returns an
+            error.
 
-          putp calls tputs, returning the same error-codes.
+       setupterm
+            returns an error if it cannot allocate enough  memory,  or  create
+            the  initial  windows  (stdscr,  curscr,  and  newscr) Other error
+            conditions are documented above.
 
-          restartterm
-               returns an error if the associated call to setupterm returns an
-               error.
+       tparm
+            returns  a  null  if  the  capability  would  require   unexpected
+            parameters,  e.g.,  too many, too few, or incorrect types (strings
+            where integers are expected, or vice versa).
 
-          setupterm
-               returns an error if it cannot allocate enough memory, or create
-               the  initial  windows  (stdscr,  curscr,  newscr).  Other error
-               conditions are documented above.
-
-          tparm
-               returns a null  if  the  capability  would  require  unexpected
-               parameters,  e.g.,  too  many,  too  few,  or  incorrect  types
-               (strings where integers are expected, or vice versa).
-
-          tputs
-               returns an error if the string parameter is null.  It does  not
-               detect  I/O errors: X/Open states that tputs ignores the return
-               value of the output function putc.
+       tputs
+            returns an error if the string parameter is  null.   It  does  not
+            detect  I/O  errors:  X/Open  Curses states that tputs ignores the
+            return value of the output function putc.

NOTES

-       According to X/Open Curses, any of the enhanced curses functions may be
-       implemented  as  macros.   The  term  "enhanced" refers to features not
-       found in SVr4 curses.
-
-       ncurses uses macros
-
-       o   for functions which return values via their parameters,
-
-       o   to support obsolete features,
-
-       o   to reuse functions, e.g., those that move the cursor before another
-           operation, and
-
-       o   a few special cases.
-
-       The  vid_puts function in ncurses is a special case.  It was originally
+       The vid_attr function in ncurses is a special case.  It was  originally
        implemented based on a draft of X/Open Curses, as a macro, before other
-       parts of the ncurses wide-character API were developed.
+       parts of the ncurses wide-character API were developed, and unlike  the
+       other  wide-character  functions,  is  also  provided  in the non-wide-
+       character configuration.

EXTENSIONS

-       The  functions  marked as extensions were designed for ncurses(3x), and
-       are not found in SVr4 curses, 4.4BSD  curses,  or  any  other  previous
-       curses implementation.
+       The functions marked as extensions were designed for ncurses,  and  are
+       not  found  in SVr4 curses, 4.4BSD curses, or any other previous curses
+       implementation.
+
+       ncurses allows opts to be a pointer to int, which  overrides  the  pair
+       (short) argument.

PORTABILITY

@@ -502,7 +483,7 @@
        likewise macros.  The one function, setterm, is mentioned in the manual
        page.  It further notes that setterm was replaced by setupterm, stating
        that the call
-              setupterm(term, 1, (int *)0)
+              setupterm(term, 1, (int *)0)
        provides the same  functionality  as  setterm(term),  discouraging  the
        latter  for  new programs.  ncurses implements each of these symbols as
        macros for BSD curses compatibility.
@@ -515,7 +496,7 @@
        Other  implementions  may not declare the capability name arrays.  Some
        provide them without declaring them.  X/Open does not specify them.
 
-       Extended terminal capability names, e.g., as defined by tic -x, are not
+       Extended terminal capability names, as defined  by  "tic -x",  are  not
        stored in the arrays described here.
 
 
@@ -523,31 +504,31 @@
        Older  versions  of  ncurses assumed that the file descriptor passed to
        setupterm from initscr or newterm uses buffered I/O, and would write to
        the  corresponding  stream.   In  addition  to  the limitation that the
-       terminal was left  in  block-buffered  mode  on  exit  (like  System  V
-       curses),  it  was  problematic because ncurses did not allow a reliable
-       way to cleanup on receiving SIGTSTP.
+       terminal was  left  in  block-buffered  mode  on  exit  (like  System V
+       curses),  it  was  problematic because ncurses did not allow a reliable
+       way to cleanup on receiving SIGTSTP.
 
        The current version (ncurses6) uses output buffers managed directly  by
-       ncurses.  Some of the low-level functions described in this manual page
+       ncurses.  Some of the low-level functions described in this manual page
        write to the standard output.  They are  not  signal-safe.   The  high-
-       level  functions  in  ncurses use alternate versions of these functions
+       level functions in ncurses employ alternate versions of these functions
        using the more reliable buffering scheme.

Function Prototypes

-       The X/Open Curses prototypes  are  based  on  the  SVr4  curses  header
+       The X/Open Curses prototypes  are  based  on  the  SVr4  curses  header
        declarations,  which  were  defined at the same time the C language was
        first standardized in the late 1980s.
 
-       o   X/Open Curses uses const  less  effectively  than  a  later  design
+       o   X/Open Curses uses const  less  effectively  than  a  later  design
            might,  in  some cases applying it needlessly to values are already
            constant, and in most cases overlooking parameters  which  normally
-           would  use const.  Using constant parameters for functions which do
-           not use const may prevent the program from compiling.  On the other
-           hand, writable strings are an obsolescent feature.
+           would  use const.  Using constant parameters for functions which do
+           not use const may prevent the program from compiling.  On the other
+           hand, "writable strings" are an obsolescent feature.
 
            As  an  extension,  this implementation can be configured to change
-           the function prototypes to use the const keyword.  The ncurses  ABI
+           the function prototypes to use the const keyword.  The ncurses  ABI
            6 enables this feature by default.
 
        o   X/Open  Curses  prototypes tparm with a fixed number of parameters,
@@ -570,7 +551,7 @@
        o   Most of the calls to tparm use only one or two parameters.  Passing
            nine on each call is awkward.
 
-           Using  long  for the numeric parameter type is a workaround to make
+           Using  long  for the numeric parameter type is a workaround to make
            the parameter use the same amount of  stack  as  a  pointer.   That
            approach  dates  back  to the mid-1980s, before C was standardized.
            Since then, there is a standard (and pointers are not  required  to
@@ -597,8 +578,8 @@
 
            SVr4 curses uses the special value "dumb".
 
-           The  difference  between  the  two  is  that the former uses the gn
-           (generic_type) terminfo capability, while the latter does  not.   A
+           The  difference  between  the two is that the former uses the gn (-
+           generic_type) terminfo capability, while the latter  does  not.   A
            generic terminal is unsuitable for full-screen applications.
 
        o   setupterm  allows explicit use of the the windows console driver by
@@ -607,15 +588,21 @@

Other Portability Issues

-       In  System  V Release 4, set_curterm has an int return type and returns
-       OK or ERR.  We have chosen to implement the X/Open Curses semantics.
+       In  SVr4,  set_curterm  returns  an  int, OK or ERR.  We have chosen to
+       implement the X/Open Curses semantics.
 
-       In System V Release 4, the third argument of tputs  has  the  type  int
-       (*putc)(char).
+       In SVr4, the third argument of tputs has the type "int (*putc)(char)".
 
-       At  least one implementation of X/Open Curses (Solaris) returns a value
-       other than OK/ERR from tputs.  That returns the length of  the  string,
-       and does no error-checking.
+       At least one implementation of X/Open Curses (Solaris) returns a  value
+       other  than OK or ERR from tputs.  It instead returns the length of the
+       string, and does no error checking.
+
+       X/Open Curses notes that after calling mvcur, the curses state may  not
+       match  the  actual terminal state, and that an application should touch
+       and refresh the window  before  resuming  normal  curses  calls.   Both
+       ncurses and SVr4 curses implement mvcur using the SCREEN data allocated
+       in either initscr or newterm.  So though it is documented as a terminfo
+       function, mvcur is really a curses function that is not well specified.
 
        X/Open  notes  that after calling mvcur, the curses state may not match
        the actual terminal state, and that an  application  should  touch  and
@@ -625,61 +612,61 @@
        a terminfo function, mvcur is really a curses  function  which  is  not
        well specified.
 
-       X/Open  states  that  the  old  location must be given for mvcur.  This
-       implementation allows the caller to use -1's for the old ordinates.  In
-       that case, the old location is unknown.
+       X/Open  Curses  states that the old location must be given for mvcur to
+       accommodate terminals that lack absolute cursor  positioning.   ncurses
+       allows the caller to use -1 for either or both old coordinates.  The -1
+       tells ncurses that the old location is unknown, and that  it  must  use
+       only  absolute  motion  (such  as cursor_address) rather than the least
+       costly combination of absolute and relative motion.

HISTORY

-       SVr2 introduced the terminfo feature.  Its programming manual mentioned
-       the following low-level functions.
+       SVr2 (1984) introduced the terminfo feature.   Its  programming  manual
+       mentioned the following low-level functions.
 
        Function    Description
        ------------------------------------------------------------------------
        fixterm     restore tty to "in curses" state
        gettmode    establish current tty modes
        mvcur       low level cursor motion
-       putp        utility function that uses tputs  to  send  characters  via
-                   putchar.
+       putp        use tputs to send characters via putchar
        resetterm   set tty modes to "out of curses" state
        resetty     reset tty flags to stored value
        saveterm    save current modes as "in curses" state
        savetty     store current tty flags
        setterm     establish terminal with given type
        setupterm   establish terminal with given type
-       tparm       instantiate a string expression with parameters
+       tparm       interpolate parameters into string capability
        tputs       apply padding information to a string
-       vidattr     like vidputs, but outputs through putchar
-       vidputs     output  a  string  to  put  terminal  in  a specified video
-                   attribute mode
+       vidattr     like vidputs, but output through putchar
+       vidputs     write string to terminal, applying specified attributes
 
-       The programming manual also mentioned functions  provided  for  termcap
+       The  programming  manual  also mentioned functions provided for termcap
        compatibility (commenting that they "may go away at a later date").
 
        Function   Description
        ------------------------------------------------------------------------
        tgetent    look up termcap entry for given name
-       tgetflag   get boolean entry for given id
+       tgetflag   get Boolean entry for given id
        tgetnum    get numeric entry for given id
        tgetstr    get string entry for given id
        tgoto      apply parameters to given capability
-       tputs      apply  padding  to  capability,  calling  a  function to put
-                  characters
+       tputs      write characters via a function parameter, applying padding
 
-       Early terminfo programs obtained capability values  from  the  TERMINAL
+       Early terminfo programs obtained capability values  from  the  TERMINAL
        structure initialized by setupterm.
 
-       SVr3  extended  terminfo  by  adding  functions  to retrieve capability
-       values (like the termcap interface), and reusing tgoto and tputs:
+       SVr3   (1987)   extended  terminfo  by  adding  functions  to  retrieve
+       capability values (like the termcap interface), and reusing  tgoto  and
+       tputs.
 
        Function    Description
        ------------------------------------------------------------------------
-
-       tigetflag   get boolean entry for given id
+       tigetflag   get Boolean entry for given id
        tigetnum    get numeric entry for given id
        tigetstr    get string entry for given id
 
-       SVr3 also replaced several of the SVr2 terminfo functions which had  no
+       SVr3  also  replaced several of the SVr2 terminfo functions that had no
        counterpart in the termcap interface, documenting them as obsolete.
 
        Function    Replaced by
@@ -692,37 +679,37 @@
        saveterm    def_prog_mode
        setterm     setupterm
 
-       SVr3  kept  the  mvcur, vidattr and vidputs functions, along with putp,
-       tparm and tputs.  The  latter  were  needed  to  support  padding,  and
-       handling  functions  such  as  vidattr  (which  used  more than the two
-       parameters supported by tgoto).
+       SVr3 kept the mvcur, vidattr, and vidputs functions, along  with  putp,
+       tparm,  and  tputs.   The latter were needed to support padding, and to
+       handle capabilities accessed by functions such as vidattr  (which  used
+       more than the two parameters supported by tgoto).
 
-       SVr3  introduced  the  functions   for   switching   between   terminal
-       descriptions,   e.g.,   set_curterm.   Some  of  that  was  incremental
-       improvements to the SVr2 library:
+       SVr3   introduced   the   functions   for  switching  between  terminal
+       descriptions;  for  example,  set_curterm.   Some   changes   reflected
+       incremental improvements to the SVr2 library.
 
-       o   The TERMINAL type definition was introduced  in  SVr3.01,  for  the
-           term structure provided in SVr2.
+       o   The  TERMINAL  type  definition  was introduced in SVr3.01, for the
+           term structure provided in SVr2.
 
-       o   The  various  global  variables such as boolnames were mentioned in
-           the programming manual at this point,  though  the  variables  were
+       o   Various global variables such as boolnames were  mentioned  in  the
+           programming  manual  at  this  point, though the variables had been
            provided in SVr2.
 
-       SVr4 added the vid_attr and vid_puts functions.
+       SVr4 (1989) added the vid_attr and vid_puts functions.
 
-       There are other low-level functions declared in the curses header files
-       on Unix systems,  but  none  were  documented.   The  functions  marked
-       "obsolete" remained in use by the Unix vi(1) editor.
+       Other low-level functions are declared in the curses  header  files  of
+       Unix  systems,  but  none are documented.  Those noted as "obsolete" by
+       SVr3 remained in use by System V's vi(1) editor.

infocmp 1m 2023-12-23 ncurses 6.4 User commands

infocmp 1m 2023-12-30 ncurses 6.4 User commands

 infocmp(1m)                      User commands                     infocmp(1m)
 
@@ -62,7 +62,7 @@
        infocmp  can  be  used  to  compare  a binary terminfo entry with other
        terminfo entries, rewrite a terminfo description to take  advantage  of
        the  use=  terminfo field, or print out a terminfo description from the
-       binary file (term) in a variety of formats.  In all cases, the  boolean
+       binary file (term) in a variety of formats.  In all cases, the  Boolean
        fields  will be printed first, followed by the numeric fields, followed
        by the string fields.
 
@@ -80,7 +80,7 @@
        only  one  of  the terminals, the value returned depends on the type of
        the capability:
 
-       o   F for missing boolean variables
+       o   F for missing Boolean variables
 
        o   NULL for missing integer or string variables
 
@@ -531,7 +531,7 @@
 
 
 
-ncurses 6.4                       2023-12-23                       infocmp(1m)
+ncurses 6.4                       2023-12-30                       infocmp(1m)

ncurses 3x 2023-12-23 ncurses 6.4 Library calls

ncurses 3x 2023-12-30 ncurses 6.4 Library calls

ncurses 3x 2023-12-23 ncurses 6.4 Library calls

ncurses 3x 2023-12-30 ncurses 6.4 Library calls

 ncurses(3x)                      Library calls                     ncurses(3x)
 
@@ -62,7 +65,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 ncurses version 6.4 (patch 20231223).
+       This describes ncurses version 6.4 (patch 20231230).
 
        The  ncurses  library emulates the curses library of System V Release 4
        Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses  (also  known
@@ -75,58 +78,59 @@
        o   "NOTES"  describes  matters  and  caveats  of which any user of the
            ncurses API should be aware, such as limitations on the size of  an
            underlying  integral  type  or  the  availability of a preprocessor
-           macro for a function (which prevents its address from being taken).
-           This  section  also  describes  implementation details that will be
-           significant to the programmer but which are not standardized.
-
-       o   "EXTENSIONS" presents ncurses innovations beyond the X/Open  Curses
-           standard  and/or  the  SVr4 curses implementation.  They are termed
-           extensions to indicate that they cannot be  implemented  solely  by
+           macro exclusive  of  a  function  definition  (which  prevents  its
+           address   from   being   taken).    This   section  also  describes
+           implementation details that will be significant to  the  programmer
+           but which are not standardized.
+
+       o   "EXTENSIONS"  presents ncurses innovations beyond the X/Open Curses
+           standard and/or the SVr4 curses implementation.   They  are  termed
+           extensions  to  indicate  that they cannot be implemented solely by
            using the library API, but require access to the library's internal
            state.
 
        o   "PORTABILITY" discusses matters (beyond the exercise of extensions)
-           that  should be considered when writing to a curses standard, or to
+           that should be considered when writing to a curses standard, or  to
            multiple implementations.
 
-       o   "HISTORY" examines points of detail in  ncurses  and  other  curses
+       o   "HISTORY"  examines  points  of  detail in ncurses and other curses
            implementations over the decades of their development, particularly
            where precedent or inertia have frustrated better design (and, in a
            few cases, where such inertia has been overcome).
 
-       A  program  using  these  routines  must  be  linked with the -lncurses
-       option, or (if it  has  been  generated)  with  the  debugging  library
-       -lncurses_g.   (Your  system  integrator  may also have installed these
-       libraries under the names  -lcurses  and  -lcurses_g.)   The  ncurses_g
-       library  generates  trace logs (in a file called "trace" in the current
+       A program using these  routines  must  be  linked  with  the  -lncurses
+       option,  or  (if  it  has  been  generated)  with the debugging library
+       -lncurses_g.  (Your system integrator may  also  have  installed  these
+       libraries  under  the  names  -lcurses  and -lcurses_g.)  The ncurses_g
+       library generates trace logs (in a file called "trace" in  the  current
        directory)  that  describe  curses  actions.   See  section  "ALTERNATE
        CONFIGURATIONS" below.
 
-       The   ncurses   package   supports:  overall  screen,  window  and  pad
-       manipulation; output to  windows  and  pads;  reading  terminal  input;
-       control  over terminal and curses input and output options; environment
-       query routines; color manipulation; use of soft  label  keys;  terminfo
+       The  ncurses  package  supports:  overall  screen,   window   and   pad
+       manipulation;  output  to  windows  and  pads;  reading terminal input;
+       control over terminal and curses input and output options;  environment
+       query  routines;  color  manipulation; use of soft label keys; terminfo
        capabilities; and access to low-level terminal-manipulation routines.

Initialization

-       The  library uses the locale which the calling program has initialized.
+       The library uses the locale which the calling program has  initialized.
        That is normally done with setlocale(3):
 
            setlocale(LC_ALL, "");
 
-       If the locale is not initialized, the library assumes  that  characters
-       are  printable  as in ISO-8859-1, to work with certain legacy programs.
-       You should initialize the locale and not rely on  specific  details  of
+       If  the  locale is not initialized, the library assumes that characters
+       are printable as in ISO-8859-1, to work with certain  legacy  programs.
+       You  should  initialize  the locale and not rely on specific details of
        the library when the locale has not been setup.
 
-       The  function  initscr  or  newterm  must  be  called to initialize the
-       library before any of the other routines that  deal  with  windows  and
-       screens  are  used.   The  routine  endwin(3x)  must  be  called before
+       The function initscr or  newterm  must  be  called  to  initialize  the
+       library  before  any  of  the other routines that deal with windows and
+       screens are  used.   The  routine  endwin(3x)  must  be  called  before
        exiting.
 
-       To get character-at-a-time input  without  echoing  (most  interactive,
-       screen  oriented  programs want this), the following sequence should be
+       To  get  character-at-a-time  input  without echoing (most interactive,
+       screen oriented programs want this), the following sequence  should  be
        used:
 
            initscr(); cbreak(); noecho();
@@ -137,101 +141,101 @@
            keypad(stdscr, TRUE);
 
        Before a curses program is run, the tab stops of the terminal should be
-       set  and  its initialization strings, if defined, must be output.  This
-       can be done  by  executing  the  tput  init  command  after  the  shell
-       environment  variable  TERM  has been exported.  (The BSD-style tset(1)
+       set and its initialization strings, if defined, must be  output.   This
+       can  be  done  by  executing  the  tput  init  command  after the shell
+       environment variable TERM has been exported.   (The  BSD-style  tset(1)
        utility  also  performs  this  function.)   See  subsection  "Tabs  and
        Initialization" of terminfo(5).

Overview

-       A  curses  library abstracts the terminal screen by representing all or
-       part of it as a WINDOW data structure.  A window is a rectangular  grid
-       of  character  cells,  addressed  by row and column coordinates (y, x),
+       A curses library abstracts the terminal screen by representing  all  or
+       part  of it as a WINDOW data structure.  A window is a rectangular grid
+       of character cells, addressed by row and  column  coordinates  (y,  x),
        with the upper left corner as (0, 0).  A window called stdscr, the same
-       size  as  the terminal screen, is always available.  Create others with
+       size as the terminal screen, is always available.  Create  others  with
        newwin(3x).
 
-       A curses library does not manage overlapping windows.   (See  panel(3x)
-       if  you  desire this.)  You can either use stdscr to manage one screen-
+       A  curses  library does not manage overlapping windows.  (See panel(3x)
+       if you desire this.)  You can either use stdscr to manage  one  screen-
        filling window, or tile the screen into non-overlapping windows and not
-       use   stdscr  at  all.   Mixing  the  two  approaches  will  result  in
+       use  stdscr  at  all.   Mixing  the  two  approaches  will  result   in
        unpredictable, and undesired, effects.
 
-       Functions permit manipulation of a window and  the  cursor  identifying
-       the  cell  within  it  at  which  the next output operation will occur.
+       Functions  permit  manipulation  of a window and the cursor identifying
+       the cell within it at which  the  next  output  operation  will  occur.
        Among those, the most basic are move(3x) and addch(3x): these place the
-       cursor  and  write  a  character  to  stdscr, respectively.  As a rule,
-       window-addressing functions feature names  prefixed  (or  infixed,  see
+       cursor and write a character  to  stdscr,  respectively.   As  a  rule,
+       window-addressing  functions  feature  names  prefixed (or infixed, see
        below) with "w"; these allow the user to specify a pointer to a WINDOW.
-       Counterparts not thus prefixed (or  infixed)  affect  stdscr.   Because
-       moving  the  cursor  prior  to  another  operation is so common, curses
-       generally also provides functions with a "mv" prefix as a  convenience.
-       Thus,  the library defines all of addch, waddch, mvaddch, and mvwaddch.
-       When both prefixes are present, the order  of  arguments  is  a  WINDOW
+       Counterparts  not  thus  prefixed  (or infixed) affect stdscr.  Because
+       moving the cursor prior to  another  operation  is  so  common,  curses
+       generally  also provides functions with a "mv" prefix as a convenience.
+       Thus, the library defines all of addch, waddch, mvaddch, and  mvwaddch.
+       When  both  prefixes  are  present,  the order of arguments is a WINDOW
        pointer first, then a y and x coordinate pair.
 
-       Updating   the  terminal  screen  with  every  curses  call  can  cause
-       unpleasant flicker or inefficient use of the communications channel  to
-       the  device.   Therefore,  after using curses functions to accumulate a
-       set of desired updates  that  make  sense  to  present  together,  call
-       refresh(3x)  to  tell  the  library to make the user's screen look like
-       stdscr.  ncurses optimizes its output by computing a minimal number  of
-       operations  to mutate the screen from its state at the previous refresh
-       to the new one.  Effective optimization  demands  accurate  information
-       about  the  terminal  device: the management of such information is the
-       province of the terminfo(3x) API, a feature of  every  standard  curses
+       Updating  the  terminal  screen  with  every  curses  call  can   cause
+       unpleasant  flicker or inefficient use of the communications channel to
+       the device.  Therefore, after using curses functions  to  accumulate  a
+       set  of  desired  updates  that  make  sense  to present together, call
+       refresh(3x) to tell the library to make the  user's  screen  look  like
+       stdscr.   ncurses optimizes its output by computing a minimal number of
+       operations to mutate the screen from its state at the previous  refresh
+       to  the  new  one.  Effective optimization demands accurate information
+       about the terminal device: the management of such  information  is  the
+       province  of  the  terminfo(3x) API, a feature of every standard curses
        implementation.
 
        Special windows called pads may also be manipulated.  These are windows
-       that are not constrained to the size of the terminal screen  and  whose
+       that  are  not constrained to the size of the terminal screen and whose
        contents need not be completely displayed.  See curs_pad(3x).
 
-       In  addition  to drawing characters on the screen, rendering attributes
-       and colors may be supported, causing the characters to show up in  such
-       modes  as  underlined,  in reverse video, or in color on terminals that
+       In addition to drawing characters on the screen,  rendering  attributes
+       and  colors may be supported, causing the characters to show up in such
+       modes as underlined, in reverse video, or in color  on  terminals  that
        support such display enhancements.  See curs_attr(3x).
 
-       curses predefines constants for a small set of line-drawing  and  other
-       graphics  corresponding  to  the  DEC  Alternate Character Set (ACS), a
+       curses  predefines  constants for a small set of line-drawing and other
+       graphics corresponding to the DEC  Alternate  Character  Set  (ACS),  a
        feature of VT100 and other terminals.  See waddch(3x) and wadd_wch(3x).
 
-       curses is implemented using the  operating  system's  terminal  driver;
-       keystroke  events are received not as scan codes but as byte sequences.
-       Graphical keycaps (alphanumeric and punctuation keys,  and  the  space)
+       curses  is  implemented  using  the operating system's terminal driver;
+       keystroke events are received not as scan codes but as byte  sequences.
+       Graphical  keycaps  (alphanumeric  and punctuation keys, and the space)
        appear  as-is.   Everything  else,  including  the  tab,  enter/return,
-       keypad, arrow, and function keys, appears as a control character  or  a
-       multibyte  escape  sequence.   curses  translates these into unique key
+       keypad,  arrow,  and function keys, appears as a control character or a
+       multibyte escape sequence.  curses translates  these  into  unique  key
        codes.  See getch(3x).

Effects of GUIs and Environment Variables

        The selection of an approprate value of TERM in the process environment
        is essential to correct curses and terminfo library operation.  A well-
-       configured system selects a correct TERM value  automatically;  tset(1)
+       configured  system  selects a correct TERM value automatically; tset(1)
        may assist with troubleshooting exotic situations.
 
-       If  the  environment  variables  LINES  and  COLUMNS are set, or if the
-       curses program is executing in a graphical windowing  environment,  the
-       information  obtained  thence  overrides that obtained by terminfo.  An
+       If the environment variables LINES and  COLUMNS  are  set,  or  if  the
+       curses  program  is executing in a graphical windowing environment, the
+       information obtained thence overrides that obtained  by  terminfo.   An
        ncurses extension supports resizable terminals; see wresize(3x).
 
-       If the environment variable  TERMINFO  is  defined,  a  curses  program
-       checks  first  for  a  terminal  type  description  in  the location it
+       If  the  environment  variable  TERMINFO  is  defined, a curses program
+       checks first for  a  terminal  type  description  in  the  location  it
        identifies.   TERMINFO  is  useful  for  developing  experimental  type
-       descriptions  or  when  write  permission to /usr/share/terminfo is not
+       descriptions or when write permission  to  /usr/share/terminfo  is  not
        available.
 
        See section "ENVIRONMENT" below.

Naming Conventions

-       Many curses functions have two or more versions.  Those  prefixed  with
-       "w"  require  a  window  argument.   Four  functions  prefixed with "p"
-       require a pad argument.  Those without a prefix  generally  operate  on
+       Many  curses  functions have two or more versions.  Those prefixed with
+       "w" require a  window  argument.   Four  functions  prefixed  with  "p"
+       require  a  pad  argument.  Those without a prefix generally operate on
        stdscr.
 
-       In  function  synopses,  ncurses man pages apply the following names to
+       In function synopses, ncurses man pages apply the  following  names  to
        parameters.
 
                         bf    bool (TRUE or FALSE)
@@ -240,55 +244,54 @@

Wide and Non-wide Character Configurations

-       This manual page describes functions that appear in  any  configuration
-       of  the  library.   There  are  two  common configurations; see section
+       This  manual  page describes functions that appear in any configuration
+       of the library.  There  are  two  common  configurations;  see  section
        "ALTERNATE CONFIGURATIONS" below.
 
        ncurses   is the library in its "non-wide" configuration, handling only
-                 eight-bit  characters.   It  stores a character combined with
-                 attributes in a chtype datum.
+                 eight-bit characters.  It stores a  character  combined  with
+                 attributes in a chtype datum, which is often an alias of int.
 
-                 Attributes alone (with no  corresponding  character)  can  be
-                 stored  in  variables  of  chtype  or attr_t type.  In either
+                 Attributes  alone  (with  no  corresponding character) can be
+                 stored in variables of chtype  or  attr_t  type.   In  either
                  case, they are represented as an integral bit mask.
 
                  Each cell of a WINDOW is stored as a chtype.
 
-       ncursesw  is the library in its  "wide"  configuration,  which  handles
+       ncursesw  is  the  library  in  its "wide" configuration, which handles
                  character encodings requiring a larger data type than char (a
                  byte-sized type) can represent.  It adds about one third more
                  calls  using  additional  data  types  that  can  store  such
                  multibyte characters.
 
-                 cchar_t  corresponds to the non-wide configuration's  chtype.
-                          It  always  a structure type, because it stores more
-                          data than can fit into an integer.  A character code
-                          may be larger than can fit in a C char, and moreover
-                          more than one character may occupy a cell  (as  with
-                          accent  marks and other diacritics).  Each character
-                          is of type wchar_t; a complex character contains one
-                          spacing  character  and  zero  or  more  non-spacing
-                          characters (see below).  Attributes and  color  data
-                          are  stored in separate fields of the structure, not
-                          combined as in chtype.
-
-                          Each cell (row and column) WINDOW  is  stored  as  a
-                          cchar_t.
+                 cchar_t  corresponds  to the non-wide configuration's chtype.
+                          It always a structure type, because it  stores  more
+                          data  than  fits into an integral type.  A character
+                          code  may  not  be  representable  as  a  char,  and
+                          moreover  more  than one character may occupy a cell
+                          (as with accent marks and other  diacritics).   Each
+                          character  is  of  type wchar_t; a complex character
+                          contains one spacing character and zero or more non-
+                          spacing  characters  (see  below).   Attributes  and
+                          color data are stored  in  separate  fields  of  the
+                          structure, not combined as in chtype.
+
+                 Each cell of a WINDOW is stored as a cchar_t.
 
                  The   setcchar(3x)   and  getcchar(3x)  functions  store  and
                  retrieve the data from a cchar_t structure.  The wide library
                  API  of ncurses depends on two data types standardized by ISO
                  C95.
 
-                 wchar_t  stores a wide character.  Like chtype, this  may  be
-                          an  integer.  Depending on the character encoding, a
-                          wide character  may  be  spacing,  meaning  that  it
+                 wchar_t  stores a wide character.  Like chtype, it may be  an
+                          alias  of int.  Depending on the character encoding,
+                          a wide character may be  spacing,  meaning  that  it
                           occupies  a  character  cell by itself and typically
-                          accompanies  cursor   advancement   on   input,   or
-                          combining, meaning that it occupies the same cell as
-                          a  spacing  character,  is  often  regarded   as   a
-                          "modifier" of the base glyph with which it combines,
-                          and typically does not advance the cursor on input.
+                          accompanies  cursor  advancement,  or   non-spacing,
+                          meaning  that it occupies the same cell as a spacing
+                          character, is often regarded as a "modifier" of  the
+                          base  glyph  with  which  it combines, and typically
+                          does not advance the cursor.
 
                  wint_t   can  store  a  wchar_t   or   the   constant   WEOF,
                           analogously  to the int-sized character manipulation
@@ -318,7 +321,8 @@
                     curses Function Name     Man Page
                     ---------------------------------------------
                     COLOR_PAIR               curs_color(3x)
-                    PAIR_NUMBER              curs_attr(3x)
+
+                    PAIR_NUMBER              curs_color(3x)
                     add_wch                  curs_add_wch(3x)
                     add_wchnstr              curs_add_wchstr(3x)
                     add_wchstr               curs_add_wchstr(3x)
@@ -382,9 +386,9 @@
                     erasewchar               curs_termattrs(3x)
                     exit_curses              curs_memleaks(3x)*
                     exit_terminfo            curs_memleaks(3x)*
-
                     extended_color_content   curs_color(3x)*
                     extended_pair_content    curs_color(3x)*
+
                     extended_slk_color       curs_slk(3x)*
                     filter                   curs_util(3x)
                     find_pair                new_pair(3x)*
@@ -448,10 +452,10 @@
                     insertln                 curs_deleteln(3x)
                     insnstr                  curs_insstr(3x)
                     insstr                   curs_insstr(3x)
-
                     instr                    curs_instr(3x)
                     intrflush                curs_inopts(3x)
                     inwstr                   curs_inwstr(3x)
+
                     is_cbreak                curs_inopts(3x)*
                     is_cleared               curs_opaque(3x)*
                     is_echo                  curs_inopts(3x)*
@@ -514,11 +518,11 @@
                     mvin_wchnstr             curs_in_wchstr(3x)
                     mvin_wchstr              curs_in_wchstr(3x)
                     mvinch                   curs_inch(3x)
-
                     mvinchnstr               curs_inchstr(3x)
                     mvinchstr                curs_inchstr(3x)
                     mvinnstr                 curs_instr(3x)
                     mvinnwstr                curs_inwstr(3x)
+
                     mvins_nwstr              curs_ins_wstr(3x)
                     mvins_wch                curs_ins_wch(3x)
                     mvins_wstr               curs_ins_wstr(3x)
@@ -580,12 +584,12 @@
                     nocbreak                 curs_inopts(3x)
                     nodelay                  curs_inopts(3x)
                     noecho                   curs_inopts(3x)
-
                     nofilter                 curs_util(3x)*
                     nonl                     curs_inopts(3x)
                     noqiflush                curs_inopts(3x)
                     noraw                    curs_inopts(3x)
                     notimeout                curs_inopts(3x)
+
                     overlay                  curs_overlay(3x)
                     overwrite                curs_overlay(3x)
                     pair_content             curs_color(3x)
@@ -646,13 +650,13 @@
                     subpad                   curs_pad(3x)
                     subwin                   curs_window(3x)
                     syncok                   curs_window(3x)
-
                     term_attrs               curs_termattrs(3x)
                     termattrs                curs_termattrs(3x)
                     termname                 curs_termattrs(3x)
                     tgetent                  curs_termcap(3x)
                     tgetflag                 curs_termcap(3x)
                     tgetnum                  curs_termcap(3x)
+
                     tgetstr                  curs_termcap(3x)
                     tgoto                    curs_termcap(3x)
                     tigetflag                curs_terminfo(3x)
@@ -712,7 +716,6 @@
                     wbkgrndset               curs_bkgrnd(3x)
                     wborder                  curs_border(3x)
                     wborder_set              curs_border_set(3x)
-
                     wchgat                   curs_attr(3x)
                     wclear                   curs_clear(3x)
                     wclrtobot                curs_clear(3x)
@@ -720,6 +723,7 @@
                     wcolor_set               curs_attr(3x)
                     wcursyncup               curs_window(3x)
                     wdelch                   curs_delch(3x)
+
                     wdeleteln                curs_deleteln(3x)
                     wecho_wchar              curs_add_wch(3x)
                     wechochar                curs_addch(3x)
@@ -788,26 +792,14 @@

RETURN VALUE

-       Routines that return an integer return ERR upon failure and an  integer
-       value other than ERR upon successful completion, unless otherwise noted
-       in the routine descriptions.
-
-       As  a  general  rule,  routines  check  for  null  pointers  passed  as
-       parameters, and handle this as an error.
-
-       All  macros  return  the  value  of  the  w  version, except setscrreg,
-       wsetscrreg, getyx,  getbegyx,  and  getmaxyx.   The  return  values  of
-       setscrreg,  wsetscrreg,  getyx,  getbegyx,  and  getmaxyx are undefined
-       (i.e., these should not be used as the right-hand  side  of  assignment
-       statements).
+       Unless otherwise noted, functions that return an integer return  OK  on
+       success and ERR on failure.  Functions that return pointers return NULL
+       on failure.  Typically, ncurses treats  a  null  pointer  passed  as  a
+       function parameter as a failure.
 
        Functions  with a "mv" prefix first perform cursor movement using wmove
-       and return an error if the position is  outside  the  window,  or  (for
-       "mvw"  functions)  if  the  WINDOW pointer is null.  Most "mv"-prefixed
-       functions (except variadic functions such  as  mvprintw)  are  provided
-       both as macros and functions.
-
-       Routines that return pointers return NULL on error.
+       and fail  if  the  position  is  outside  the  window,  or  (for  "mvw"
+       functions) if the WINDOW pointer is null.

ENVIRONMENT

@@ -817,9 +809,9 @@

CC command-character

-       When  set, change occurrences of the command_character (i.e., the cmdch
-       capability) of the  loaded  terminfo  entries  to  the  value  of  this
-       variable.  Very few terminfo entries provide this feature.
+       When  set,  change  the  command_character  (cmdch) capability value of
+       loaded terminfo entries to the value of this variable.  Very few  term-
+       info entries provide this feature.
 
        Because this name is also used in development environments to represent
        the C compiler's name, ncurses ignores it if it does not happen to be a
@@ -1273,19 +1265,19 @@
 
             Those functions are described in these pages:
 
-            o   curs_extend(3x) - miscellaneous curses extensions
+            o   curs_extend(3x) - miscellaneous curses extensions
 
-            o   curs_inopts(3x) - curses input options
+            o   curs_inopts(3x) - curses input options
 
-            o   curs_kernel(3x) - low-level curses routines
+            o   curs_kernel(3x) - low-level curses routines
 
-            o   curs_termattrs(3x) - curses environment query routines
+            o   curs_termattrs(3x) - curses environment query routines
 
-            o   curs_termcap(3x) - curses emulation of termcap
+            o   curs_termcap(3x) - curses emulation of termcap
 
-            o   curs_terminfo(3x) - curses interfaces to terminfo database
+            o   curs_terminfo(3x) - curses interface to terminfo database
 
-            o   curs_util(3x) - miscellaneous curses utility routines
+            o   curs_util(3x) - miscellaneous curses utility routines
 
        --with-trace
             The  trace  function normally resides in the debug library, but it
@@ -1303,105 +1295,103 @@

NOTES

-       If standard output from a ncurses program is re-directed  to  something
-       which  is not a tty, screen updates will be directed to standard error.
-       This was an undocumented feature of AT&T System V Release 3 curses.
+       X/Open Curses permits most functions it specifies to be made  available
+       as macros as well.  ncurses does so
+
+       o   for functions that return values via their parameters,
+
+       o   to support obsolete features,
+
+       o   to  reuse functions (for example, those that move the cursor before
+           another operation), and
 
-       See subsection  "Header  files"  below  regarding  symbols  exposed  by
+       o   a few special cases.
+
+       If the standard  output  file  descriptor  of  an  ncurses  program  is
+       redirected  to  something  that  is  not a terminal device, the library
+       writes screen updates to the standard error file descriptor.  This  was
+       an undocumented feature of SVr3.
+
+       See  subsection  "Header  files"  below  regarding  symbols  exposed by
        inclusion of curses.h.

EXTENSIONS

-       The  ncurses library can be compiled with an option (-DUSE_GETCAP) that
-       falls back to the old-style /etc/termcap file  if  the  terminal  setup
-       code  cannot  find a terminfo entry corresponding to TERM.  Use of this
-       feature is not  recommended,  as  it  essentially  includes  an  entire
-       termcap  compiler  in  the ncurses startup code, at significant cost in
-       core and startup cycles.
-
-       The ncurses library includes facilities for capturing mouse  events  on
-       certain  terminals  (including  xterm).   See the curs_mouse(3x) manual
-       page for details.
-
-       The ncurses  library  includes  facilities  for  responding  to  window
-       resizing   events,   e.g.,   when   running   in  an  xterm.   See  the
-       resizeterm(3x) and wresize(3x) manual pages for details.  In  addition,
-       the library may be configured with a SIGWINCH handler.
-
-       The  ncurses library extends the fixed set of function key capabilities
-       of terminals by allowing the application designer to define  additional
-       key  sequences at runtime.  See the define_key(3x) key_defined(3x), and
-       keyok(3x) manual pages for details.
-
-       The ncurses library can exploit the  capabilities  of  terminals  which
-       implement  the  ISO-6429  SGR  39  and  SGR 49 controls, which allow an
-       application to reset  the  terminal  to  its  original  foreground  and
-       background  colors.   From  the  users' perspective, the application is
-       able  to  draw  colored  text  on  a  background  whose  color  is  set
-       independently,  providing better control over color contrasts.  See the
-       default_colors(3x) manual page for details.
-
-       The ncurses library  includes  a  function  for  directing  application
-       output  to  a  printer  attached  to  the  terminal  device.   See  the
-       curs_print(3x) manual page for details.
+       ncurses enables an application  to  capture  mouse  events  on  certain
+       terminals, including xterm; see curs_mouse(3x).
 
+       ncurses  provides  a  means of responding to window resizing events, as
+       when running in a GUI terminal emulator application such as xterm;  see
+       resizeterm(3x) and wresize(3x).
 
-

PORTABILITY

-       The ncurses library is intended to be BASE-level  conformant  with  XSI
-       Curses.    The  EXTENDED  XSI  Curses  functionality  (including  color
-       support) is supported.
+       ncurses allows an application to query the terminal for the presence of
+       a wide variety of special keys; see has_key(3x).
 
-       A small number of local differences (that  is,  individual  differences
-       between  the XSI Curses and ncurses calls) are described in PORTABILITY
-       sections of the library man pages.
+       ncurses extends the fixed set of function key capabilities specified by
+       X/Open   Curses  by  allowing  the  application  programmer  to  define
+       additional   key   sequences   at    runtime;    see    define_key(3x),
+       key_defined(3x), and keyok(3x).
 
+       ncurses   can   exploit  the  capabilities  of  terminals  implementing
+       ISO 6429/ECMA-48  SGR 39  and  SGR 49   sequences,   which   allow   an
+       application  to  reset  the  terminal  to  its  original foreground and
+       background colors.  From a user's perspective, the application is  able
+       to  draw colored text on a background whose color is set independently,
+       providing better control over color contrasts.  See default_colors(3x).
 
-

Error Checking

-       In many cases, X/Open Curses is vague about error conditions,  omitting
-       some of the SVr4 documentation.
+       An ncurses application can choose  to  hide  the  internal  details  of
+       WINDOW   structures,   instead   using   accessor   functions  such  as
+       is_scrollok(3x).
 
-       Unlike  other  implementations,  this  one  checks  parameters  such as
-       pointers to WINDOW structures to ensure they are not  null.   The  main
-       reason  for  providing  this  behavior  is  to guard against programmer
-       error.  The standard interface does not provide a way for  the  library
-       to  tell an application which of several possible errors were detected.
-       Relying on this (or some other) extension  will  adversely  affect  the
-       portability of curses applications.
+       ncurses enables an  application  to  direct  application  output  to  a
+       printer attached to the terminal device; see curs_print(3x).
+
+       ncurses  offers slk_attr(3x) as a counterpart of attr_get(3x) for soft-
+       label key lines, and extended_slk_color(3x) as a form of  slk_color(3x)
+       that  can  gather  color  information  from  them  when many colors are
+       supported.
+
+       Some extensions are only available if ncurses is  compiled  to  support
+       them; see section "ALTERNATE CONFIGURATIONS" above.
 
+       o   Rudimentary   support   for   multi-threaded  applications  may  be
+           available; see curs_threads(3x).
 
-

Extensions Versus Portability

-       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:
+       o   Functions that ease the  management  of  multiple  screens  can  be
+           exposed; see curs_sp_funcs(3x).
 
-       o   The routine has_key is not part of XPG4, nor is it present in SVr4.
-           See the curs_getch(3x) manual page for details.
+       o   The compiler option -DUSE_GETCAP causes the library to fall back to
+           reading /etc/termcap if the terminal setup code cannot find a term-
+           info  entry  corresponding  to  TERM.   Use  of this feature is not
+           recommended, as it essentially includes an entire termcap  compiler
+           in  the  ncurses  startup  code,  at  a  cost  in  memory usage and
+           application launch latency.
 
-       o   The routine slk_attr is not part of XPG4,  nor  is  it  present  in
-           SVr4.  See the curs_slk(3x) manual page for details.
+       PDCurses  and  NetBSD  curses  incorporate  some  ncurses   extensions.
+       Individual man pages indicate where this is the case.
 
-       o   The  routines  getmouse,  mousemask, ungetmouse, mouseinterval, and
-           wenclose relating to mouse interfacing are not part  of  XPG4,  nor
-           are  they  present in SVr4.  See the curs_mouse(3x) manual page for
-           details.
 
-       o   The  routine  mcprint  was  not  present  in  any  previous  curses
-           implementation.  See the curs_print(3x) manual page for details.
+

PORTABILITY

+       X/Open Curses defines two levels of conformance, "base" and "enhanced".
+       The latter includes several additional features, such as wide-character
+       and  color support.  ncurses intends base-level conformance with X/Open
+       Curses, and supports nearly all its enhanced features.
 
-       o   The routine wresize is not part of XPG4, nor is it present in SVr4.
-           See the wresize(3x) manual page for details.
+       Differences between X/Open Curses and ncurses  are  documented  in  the
+       "PORTABILITY" sections of applicable man pages.
 
-       o   The  WINDOW  structure's  internal  details  can  be  hidden   from
-           application  programs.   See  curs_opaque(3x) for the discussion of
-           is_scrollok, etc.
 
-       o   This  implementation  can  be  configured  to  provide  rudimentary
-           support  for multi-threaded applications.  See curs_threads(3x) for
-           details.
+

Error Checking

+       In  many cases, X/Open Curses is vague about error conditions, omitting
+       some of the SVr4 documentation.
 
-       o   This implementation can also be configured  to  provide  a  set  of
-           functions  which  improve  the  ability to manage multiple screens.
-           See curs_sp_funcs(3x) for details.
+       Unlike other  implementations,  this  one  checks  parameters  such  as
+       pointers  to  WINDOW  structures to ensure they are not null.  The main
+       reason for providing this  behavior  is  to  guard  against  programmer
+       error.   The  standard interface does not provide a way for the library
+       to tell an application which of several possible errors were  detected.
+       Relying  on  this  (or  some other) extension will adversely affect the
+       portability of curses applications.

Padding Differences

@@ -1514,7 +1504,7 @@
 
 
 
-ncurses 6.4                       2023-12-23                       ncurses(3x)
+ncurses 6.4                       2023-12-30                       ncurses(3x)

PORTABILITY

Error Checking
-
Extensions Versus Portability

Padding Differences

Header Files

diff --git a/doc/html/man/scr_dump.5.html b/doc/html/man/scr_dump.5.html index 53b9508a..e460448c 100644 --- a/doc/html/man/scr_dump.5.html +++ b/doc/html/man/scr_dump.5.html @@ -27,19 +27,20 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp @ + * @Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp @ + *SH SYNOPSIS --> -scr_dump 5 2023-12-23 ncurses 6.4 File formats +scr_dump 5 2023-12-30 ncurses 6.4 File formats -
scr_dump 5 2023-12-23 ncurses 6.4 File formats
+
scr_dump 5 2023-12-30 ncurses 6.4 File formats

scr_dump(5) File formats scr_dump(5) @@ -50,10 +51,6 @@ scr_dump - curses screen dump -
SYNOPSIS
- scr_dump - -
DESCRIPTION
The curses library provides applications with the ability to write the contents of a window to an external file using scr_dump or putwin, and @@ -129,48 +126,34 @@
PORTABILITY
- There is no standard format for putwin. This section gives a brief - description of the existing formats. + There is no standard format for curses screen dumps. A brief survey of + the existing implementations follows.
X/Open Curses
- Refer to X/Open Curses, Issue 7 (2009). - - X/Open's documentation for enhanced curses says only: + X/Open Curses, Issue 7 specifies little. It says (boldface emphasis + added) - The getwin( ) function reads window-related data stored in the file - by putwin( ). The function then creates and initializes a new + "[t]he getwin() function reads window-related data stored in the + file by putwin(). The function then creates and initializes a new window using that data. - The putwin( ) function writes all data associated with win into the - stdio(3) stream to which filep points, using an unspecified format. - This information can be retrieved later using getwin( ). - - In the mid-1990s when the X/Open Curses document was written, there - were still systems using older, less capable curses libraries (aside - from the BSD curses library which was not relevant to X/Open because it - did not meet the criteria for base curses). The document explained the - term "enhanced" as follows: - - o Shading is used to identify X/Open Enhanced Curses material, - relating to interfaces included to provide enhanced capabilities - for applications originally written to be compiled on systems - based on the Unix operating system. Therefore, the features - described may not be present on systems that conform to XPG4 or - to earlier XPG releases. The relevant reference pages may - provide additional or more specific portability warnings about - use of the material. + The putwin() function writes all data associated with win into the + stdio stream to which filep points, using an unspecified format. + This information can be retrieved later using getwin()." - In the foregoing, emphasis was added to unspecified format and to XPG4 - or to earlier XPG releases, for clarity. + In the mid-1990s when the X/Open Curses document was written, there + were still System V systems using older, less capable curses libraries. + BSD curses was not relevant to X/Open because it did not meet the + criteria for base-level conformance; see ncurses(3x). -
Unix System V
- Unix System V curses identified the file format by writing a "magic - number" at the beginning of the dump. The WINDOW data and the lines of - text follow, all in binary form. +
System V
+ System V curses identified the file format by writing a "magic number" + at the beginning of the dump. The WINDOW data and the lines of text + follow, all in binary form. - The Solaris curses source has these definitions: + Solaris curses has the following definitions. /* terminfo magic number */ #define MAGNUM 0432 @@ -180,28 +163,28 @@ #define SVR3_DUMP_MAGIC_NUMBER 0434 That is, the feature was likely introduced in SVr2 (1984), and improved - in SVr3 (1987). The Solaris curses source has no magic number for SVr4 - (1989). Other operating systems (AIX and HP-UX) use a magic number - which would correspond to this definition: + in SVr3 (1987). Solaris curses has no magic number for SVr4 (1989). + Other System V operating systems (AIX and HP-UX) use a magic number + that would correspond to the following. /* curses screen dump magic number */ #define SVR4_DUMP_MAGIC_NUMBER 0435 - That octal number in bytes is 001, 035. Because most Unix vendors use - big-endian hardware, the magic number is written with the high-order - byte first, e.g., + That octal number in bytes is 001, 035. Because most Unix vendors at + the time used big-endian hardware, the magic number is written with the + high-order byte first. \001\035 - After the magic number, the WINDOW structure and line-data are written - in binary format. While the magic number used by the Unix systems can - be seen using od(1), none of the Unix systems documents the format used - for screen-dumps. + After the magic number, the WINDOW structure and line data are written + in binary format. While the magic number used by these systems can be + observed with od(1), none of them documents the format used for screen + dumps. - The Unix systems do not use identical formats. While collecting - information for for this manual page, the savescreen test-program - produced dumps of different size (all on 64-bit hardware, on 40x80 - screens): + Nor do they use an identical format, even with the System V family. + The ncurses savescreen test program was used to collect information for + this manual page. It produced dumps of different size (all on 64-bit + hardware, on 40x80 screens): o AIX (51817 bytes) @@ -213,53 +196,54 @@
Solaris
- As noted above, Solaris curses has no magic number corresponding to - SVr4 curses. This is odd since Solaris was the first operating system - to pass the SVr4 guidelines. Solaris has two versions of curses: + As noted above, Solaris curses has no magic number corresponding to + SVr4 curses. This is odd, since Solaris was the first operating system + to meet the SVr4 guidelines. Solaris furthermore supplies two versions + of curses. - o The default curses library uses the SVr3 magic number. + o The default curses library uses the SVr3 magic number. - o There is an alternate curses library in /usr/xpg4. This uses a - textual format with no magic number. + o An alternate curses library (which we term xcurses), available in + /usr/xpg4, uses a textual format with no magic number. - According to the copyright notice, the xpg4 Solaris curses library - was developed by MKS (Mortice Kern Systems) from 1990 to 1995. + According to its copyright notice, this xcurses library was + developed by MKS (Mortice Kern Systems) from 1990 to 1995. - Like ncurses6, there is a file-header with parameters. Unlike - ncurses6, the contents of the window are written piecemeal, with - coordinates and attributes for each chunk of text rather than + Like ncurses6, it includes a header with parameters. Unlike + ncurses6, the contents of the window are written piecemeal, with + coordinates and attributes for each chunk of text rather than writing the whole window from top to bottom.
PDCurses
- PDCurses added support for screen dumps in version 2.7 (2005). Like - Unix System V and ncurses5, it writes the WINDOW structure in binary, - but begins the file with its three-byte identifier "PDC", followed by a - one-byte version, e.g., + PDCurses added support for screen dumps in version 2.7 (2005). Like + System V and ncurses5, it writes the WINDOW structure in binary, but + begins the file with its three-byte identifier "PDC", followed by a + single-byte version number. "PDC\001"
NetBSD
- As of April 2017, NetBSD curses does not support scr_dump and + As of April 2017, NetBSD curses does not support scr_dump and scr_restore (or scr_init, scr_set), although it has putwin and getwin. - Like ncurses5, NetBSD putwin does not identify its dumps with a useful + Like ncurses5, NetBSD putwin does not identify its dumps with a useful magic number. It writes - o the curses shared library major and minor versions as the first two - bytes (e.g., 7 and 1), + o the curses shared library major and minor versions as the first two + bytes (for example, 7 and 1), o followed by a binary dump of the WINDOW, - o some data for wide-characters referenced by the WINDOW structure, + o some data for wide characters referenced by the WINDOW structure, and o finally, lines as done by other implementations.
EXAMPLES
- Given a simple program which writes text to the screen (and for the + Given a simple program which writes text to the screen (and for the sake of example, limiting the screen-size to 10x20): #include <curses.h> @@ -317,13 +301,13 @@ o The actual color pair values are not written to the file. - o All characters are shown in printable form; spaces are "\s" to + o All characters are shown in printable form; spaces are "\s" to ensure they are not overlooked. - o Attributes are written in escaped curly braces, e.g., "\{BOLD}", + o Attributes are written in escaped curly braces, e.g., "\{BOLD}", and may include a color pair (C1 or C2 in this example). - o The parameters in the header are written out only if they are + o The parameters in the header are written out only if they are nonzero. When reading back, order does not matter. Running the same program with Solaris xpg4 curses gives this dump: @@ -362,12 +346,12 @@ 9,19,0,0, CUR=11,5 - Solaris getwin requires that all parameters are present, and in the - same order. The xpg4 curses library does not know about the bce (back + Solaris getwin requires that all parameters are present, and in the + same order. The xpg4 curses library does not know about the bce (back color erase) capability, and does not color the window background. - On the other hand, the SVr4 curses library does know about the - background color. However, its screen dumps are in binary. Here is + On the other hand, the SVr4 curses library does know about the + background color. However, its screen dumps are in binary. Here is the corresponding dump (using "od -t x1"): 0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00 @@ -407,12 +391,11 @@ -ncurses 6.4 2023-12-23 scr_dump(5) +ncurses 6.4 2023-12-30 scr_dump(5)

NAME
-
SYNOPSIS

DESCRIPTION

ncurses6
@@ -422,7 +405,7 @@ ncurses 6.4 2023-12-23 PORTABILITY

X/Open Curses
-
Unix System V
+
System V

Solaris

PDCurses

NetBSD
diff --git a/doc/html/man/term.5.html b/doc/html/man/term.5.html index 4509b95a..6c5b96a6 100644 --- a/doc/html/man/term.5.html +++ b/doc/html/man/term.5.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp @ + * @Id: term.5,v 1.70 2023/12/30 21:36:32 tom Exp @ --> -term 5 2023-12-23 ncurses 6.4 File formats +term 5 2023-12-30 ncurses 6.4 File formats -
term 5 2023-12-23 ncurses 6.4 File formats
+
term 5 2023-12-30 ncurses 6.4 File formats

term(5) File formats term(5) @@ -99,7 +99,7 @@ b) terminal names, - c) boolean flags, + c) Boolean flags, d) numbers, @@ -114,7 +114,7 @@ (2) the size, in bytes, of the terminal names section; - (3) the number of bytes in the boolean flags section; + (3) the number of bytes in the Boolean flags section; (4) the number of short integers in the numbers section; @@ -122,7 +122,7 @@ (6) the size, in bytes, of the string table. - The capabilities in the boolean flags, numbers, and strings sections + The capabilities in the Boolean flags, numbers, and strings sections are in the same order as the file <term.h>. Short integers are signed, in the range -32768 to 32767. They are @@ -145,13 +145,13 @@ the corresponding table. The integer value -1 is represented by two bytes 0377, 0377. - Absent boolean values are represented by the byte 0 (false). + Absent Boolean values are represented by the byte 0 (false). o If a capability has been canceled from this terminal, tic stores a -2 in the corresponding table. The integer value -2 is represented by two bytes 0377, 0376. - The boolean value -2 is represented by the byte 0376. + The Boolean value -2 is represented by the byte 0376. o Other negative values are illegal. @@ -160,18 +160,18 @@ the terminal, separated by the "|" character. The terminal names section is terminated with an ASCII NUL character. - The boolean flags section has one byte for each flag. Boolean + The Boolean flags section has one byte for each flag. Boolean capabilities are either 1 or 0 (true or false) according to whether the terminal supports the given capability or not. - Between the boolean flags section and the number section, a null byte + Between the Boolean flags section and the number section, a null byte will be inserted, if necessary, to ensure that the number section begins on an even byte This is a relic of the PDP-11's word-addressed architecture, originally designed to avoid traps induced by addressing a word on an odd byte boundary. All short integers are aligned on a short word boundary. - The numbers section is similar to the boolean flags section. Each + The numbers section is similar to the Boolean flags section. Each capability takes up two bytes, and is stored as a little-endian short integer. @@ -190,7 +190,7 @@ The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. Each system uses a - predefined set of boolean, number or string capabilities. + predefined set of Boolean, number or string capabilities. The ncurses libraries and applications support extended terminfo binary format, allowing users to define capabilities which are loaded at @@ -202,7 +202,7 @@ First, it reads the extended header (5 short integers): - (1) count of extended boolean capabilities + (1) count of extended Boolean capabilities (2) count of extended numeric capabilities @@ -220,7 +220,7 @@ The extended string table contains values for string capabilities. After the end of these values, it contains the names for each of the - extended capabilities in order, e.g., booleans, then numbers and + extended capabilities in order, e.g., Booleans, then numbers and finally strings. By storing terminal descriptions in this way, ncurses is able to @@ -267,7 +267,7 @@ (resulting in missing entries). The routine setupterm must be prepared for both possibilities - this is why the numbers and sizes are included. Also, new capabilities must always be added at the end of - the lists of boolean, number, and string capabilities. + the lists of Boolean, number, and string capabilities.
Binary Format
@@ -399,7 +399,7 @@ -ncurses 6.4 2023-12-23 term(5) +ncurses 6.4 2023-12-30 term(5)

diff --git a/doc/html/man/terminfo.5.html b/doc/html/man/terminfo.5.html index 813b96f9..fc98e7fa 100644 --- a/doc/html/man/terminfo.5.html +++ b/doc/html/man/terminfo.5.html @@ -32,7 +32,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp @ + * @Id: terminfo.head,v 1.60 2023/12/30 22:21:45 tom Exp @ * Head of terminfo man page ends here **************************************************************************** * Copyright 2018-2022,2023 Thomas E. Dickey * @@ -62,7 +62,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp @ + * @Id: terminfo.tail,v 1.141 2023/12/30 21:36:32 tom Exp @ *.in -2 *.in +2 *.in -2 @@ -73,12 +73,12 @@ -terminfo 5 2023-12-23 ncurses 6.4 File formats +terminfo 5 2023-12-30 ncurses 6.4 File formats -
terminfo 5 2023-12-23 ncurses 6.4 File formats
+
terminfo 5 2023-12-30 ncurses 6.4 File formats

terminfo(5) File formats terminfo(5) @@ -105,7 +105,7 @@ have, by specifying how to perform screen operations, and by specifying padding requirements and initialization sequences. - This manual describes ncurses version 6.4 (patch 20231223). + This manual describes ncurses version 6.4 (patch 20231230).
terminfo Entry Syntax
@@ -184,11 +184,11 @@ features. After the first field (giving the name(s) of the terminal entry), there - should be one or more capability fields. These are boolean, numeric or + should be one or more capability fields. These are Boolean, numeric or string names with corresponding values: o Boolean capabilities are true when present, false when absent. - There is no explicit value for boolean capabilities. + There is no explicit value for Boolean capabilities. o Numeric capabilities have a "#" following the name, then an unsigned decimal integer value. @@ -282,7 +282,7 @@ (#i) indicates the ith parameter. - These are the boolean capabilities: + These are the Boolean capabilities: Variable Cap- TCap Description @@ -1146,7 +1146,7 @@ capabilities. The tic and infocmp programs provide the -x option for this purpose. When -x is set, tic treats unknown capabilities as user- defined. That is, if tic encounters a capability name which it does - not recognize, it infers its type (boolean, number or string) from the + not recognize, it infers its type (Boolean, number or string) from the syntax and makes an extended table entry for that capability. The use_extended_names(3x) function makes this information conditionally available to applications. The ncurses library provides the data @@ -1155,7 +1155,7 @@ o User-defined capability strings whose name begins with "k" are treated as function keys. - o The types (boolean, number, string) determined by tic can be + o The types (Boolean, number, string) determined by tic can be inferred by successful calls on tigetflag, etc. o If the capability name happens to be two characters, the capability @@ -1165,7 +1165,7 @@ predefined set of capabilities, in practice it has been limited to the capabilities defined by terminfo implementations. As a rule, user- defined capabilities intended for use by termcap applications should be - limited to booleans and numbers to avoid running past the 1023 byte + limited to Booleans and numbers to avoid running past the 1023 byte limit assumed by termcap implementations and their applications. In particular, providing extended sets of function keys (past the 60 numbered keys and the handful of special named keys) is best done using @@ -1786,7 +1786,7 @@ using ri or ind on many terminals without a true insert/delete line, and is often faster even on terminals with those features. - The boolean non_dest_scroll_region should be set if each scrolling + The Boolean non_dest_scroll_region should be set if each scrolling window is effectively a view port on a screen-sized canvas. To test for this capability, create a scrolling region in the middle of the screen, write something to the bottom line, move the cursor to the top @@ -2228,7 +2228,7 @@ A command to erase or blank the status line may be specified as dsl. - The boolean capability eslok specifies that escape sequences, tabs, + The Boolean capability eslok specifies that escape sequences, tabs, etc., work ordinarily in the status line. The ncurses implementation does not yet use any of these capabilities. @@ -2329,7 +2329,7 @@ color pairs to their default values for the terminal. Some terminals (including many PC terminal emulators) erase screen areas with the current background color rather than the power-up default background; - these should have the boolean capability bce. + these should have the Boolean capability bce. While the curses library works with color pairs (reflecting the inability of some devices to set foreground and background colors @@ -2394,7 +2394,7 @@ indicate that colors can be modified. If so, the initc capability will take a color number (0 to colors - 1)and three more parameters which describe the color. These three parameters default to being - interpreted as RGB (Red, Green, Blue) values. If the boolean + interpreted as RGB (Red, Green, Blue) values. If the Boolean capability hls is present, they are instead as HLS (Hue, Lightness, Saturation) indices. The ranges are terminal-dependent. @@ -2694,7 +2694,7 @@ -ncurses 6.4 2023-12-23 terminfo(5) +ncurses 6.4 2023-12-30 terminfo(5)

diff --git a/doc/html/man/tic.1m.html b/doc/html/man/tic.1m.html index 50fc7fb0..1d5b8f47 100644 --- a/doc/html/man/tic.1m.html +++ b/doc/html/man/tic.1m.html @@ -27,19 +27,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp @ + * @Id: tic.1m,v 1.106 2023/12/30 21:36:32 tom Exp @ --> -tic 1m 2023-12-23 ncurses 6.4 User commands +tic 1m 2023-12-30 ncurses 6.4 User commands -
tic 1m 2023-12-23 ncurses 6.4 User commands
+
tic 1m 2023-12-30 ncurses 6.4 User commands

tic(1m) User commands tic(1m) @@ -309,7 +309,7 @@ -x Treat unknown capabilities as user-defined (see user_caps(5)). That is, if you supply a capability name which tic does not - recognize, it will infer its type (boolean, number or string) from + recognize, it will infer its type (Boolean, number or string) from the syntax and make an extended table entry for that. User- defined capability strings whose name begins with "k" are treated as function keys. @@ -482,7 +482,7 @@ -ncurses 6.4 2023-12-23 tic(1m) +ncurses 6.4 2023-12-30 tic(1m)

diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html index c313b5af..ecca62eb 100644 --- a/doc/html/man/tput.1.html +++ b/doc/html/man/tput.1.html @@ -28,7 +28,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp @ + * @Id: tput.1,v 1.97 2023/12/31 00:16:41 tom Exp @ * longname was added in October 1989. --> @@ -36,12 +36,12 @@ -tput 1 2023-12-23 ncurses 6.4 User commands +tput 1 2023-12-30 ncurses 6.4 User commands -
tput 1 2023-12-23 ncurses 6.4 User commands
+
tput 1 2023-12-30 ncurses 6.4 User commands

tput(1) User commands tput(1) @@ -53,7 +53,7 @@
SYNOPSIS
- tput [-T terminal-type] cap-code [parameter ...] + tput [-T terminal-type] {cap-code [parameter ...]} ... tput [-T terminal-type] [-x] clear @@ -200,113 +200,124 @@ Otherwise, reset acts identically to init. longname - If the terminal database is present and an entry for the user's + A terminfo entry begins with one or more names by which an + application can refer to the entry, before the list of terminal + capabilities. The names are separated by "|" characters. + X/Open states that the last name is the "long name" and also + that it may include blanks. + + tic warns if the last name does not include blanks, to + accommodate old terminfo entries which treated the long name as + an optional feature. The long name is often referred to as the + description field. + + If the terminal database is present and an entry for the user's terminal exists (see -T type above), tput reports the terminal's - description (or "long name") to the standard output, without a - trailing newline. See term(5). + description (or "long name") to the standard output, without a + trailing newline. See terminfo(5).
Aliases
- tput handles the clear, init and reset commands specially: it allows + tput handles the clear, init and reset commands specially: it allows for the possibility that it is invoked by a link with those names. - If tput is invoked by a link named reset, this has the same effect as - tput reset. The tset(1) utility also treats a link named reset + If tput is invoked by a link named reset, this has the same effect as + tput reset. The tset(1) utility also treats a link named reset specially. Before ncurses 6.1, the two utilities were different from each other: - o tset utility reset the terminal modes and special characters (not + o tset utility reset the terminal modes and special characters (not done with tput). - o On the other hand, tset's repertoire of terminal capabilities for - resetting the terminal was more limited, i.e., only reset_1string, - reset_2string and reset_file in contrast to the tab-stops and + o On the other hand, tset's repertoire of terminal capabilities for + resetting the terminal was more limited, i.e., only reset_1string, + reset_2string and reset_file in contrast to the tab-stops and margins which are set by this utility. - o The reset program is usually an alias for tset, because of this + o The reset program is usually an alias for tset, because of this difference with resetting terminal modes and special characters. - With the changes made for ncurses 6.1, the reset feature of the two + With the changes made for ncurses 6.1, the reset feature of the two programs is (mostly) the same. A few differences remain: - o The tset program waits one second when resetting, in case it + o The tset program waits one second when resetting, in case it happens to be a hardware terminal. - o The two programs write the terminal initialization strings to - different streams (i.e., the standard error for tset and the + o The two programs write the terminal initialization strings to + different streams (i.e., the standard error for tset and the standard output for tput). - Note: although these programs write to different streams, - redirecting their output to a file will capture only part of their - actions. The changes to the terminal modes are not affected by + Note: although these programs write to different streams, + redirecting their output to a file will capture only part of their + actions. The changes to the terminal modes are not affected by redirecting the output. - If tput is invoked by a link named init, this has the same effect as + If tput is invoked by a link named init, this has the same effect as tput init. Again, you are less likely to use that link because another program named init has a more well-established use.
Terminal Size
Besides the special commands (e.g., clear), tput treats certain - terminfo capabilities specially: lines and cols. tput calls + terminfo capabilities specially: lines and cols. tput calls setupterm(3x) to obtain the terminal size: o first, it gets the size from the terminal database (which generally - is not provided for terminal emulators which do not have a fixed + is not provided for terminal emulators which do not have a fixed window size) - o then it asks the operating system for the terminal's size (which + o then it asks the operating system for the terminal's size (which generally works, unless connecting via a serial line which does not support NAWS: negotiations about window size). - o finally, it inspects the environment variables LINES and COLUMNS + o finally, it inspects the environment variables LINES and COLUMNS which may override the terminal size. - If the -T option is given tput ignores the environment variables by - calling use_tioctl(TRUE), relying upon the operating system (or + If the -T option is given tput ignores the environment variables by + calling use_tioctl(TRUE), relying upon the operating system (or finally, the terminal database).
EXIT STATUS
If the -S option is used, tput checks for errors from each line, and if - any errors are found, will set the exit status to 4 plus the number of - lines with errors. If no errors are found, the exit status is 0. No - indication of which line failed can be given so exit status 1 will - never appear. Exit statuses 2, 3, and 4 retain their usual - interpretation. If the -S option is not used, the exit status depends + any errors are found, will set the exit status to 4 plus the number of + lines with errors. If no errors are found, the exit status is 0. No + indication of which line failed can be given so exit status 1 will + never appear. Exit statuses 2, 3, and 4 retain their usual + interpretation. If the -S option is not used, the exit status depends on the type of cap-code: Boolean a value of 0 is set for TRUE and 1 for FALSE. - string a value of 0 is set if the cap-code is defined for this - terminal type (the value of cap-code is returned on standard - output); a value of 1 is set if cap-code is not defined for + string a value of 0 is set if the cap-code is defined for this + terminal type (the value of cap-code is returned on standard + output); a value of 1 is set if cap-code is not defined for this terminal type (nothing is written to standard output). integer - a value of 0 is always set, whether or not cap-code is - defined for this terminal type. To determine if cap-code is - defined for this terminal type, the user must test the value - written to standard output. A value of -1 means that cap- + a value of 0 is always set, whether or not cap-code is + defined for this terminal type. To determine if cap-code is + defined for this terminal type, the user must test the value + written to standard output. A value of -1 means that cap- code is not defined for this terminal type. - other reset or init may fail to find their respective files. In + other reset or init may fail to find their respective files. In that case, the exit status is set to 4 + errno. - Any other exit status indicates an error; see section "DIAGNOSTICS" + Any other exit status indicates an error; see section "DIAGNOSTICS" below.
DIAGNOSTICS
- tput prints the following error messages and sets the corresponding + tput prints the following error messages and sets the corresponding exit statuses. exit status error message ------------------------------------------------------------------------ - 0 (cap-code is a numeric variable that is not specified in - the terminfo(5) database for this terminal type, e.g. + 0 (cap-code is a numeric variable that is not specified in + the terminfo(5) database for this terminal type, e.g. tput -T450 lines and tput -Thp2621 xmc) 1 no error message is printed, see the EXIT STATUS section. 2 usage error @@ -325,115 +336,115 @@
PORTABILITY
- This implementation of tput differs from AT&T tput in two important + This implementation of tput differs from AT&T tput in two important areas: - o tput cap-code writes to the standard output. That need not be a - regular terminal. However, the subcommands which manipulate + o tput cap-code writes to the standard output. That need not be a + regular terminal. However, the subcommands which manipulate terminal modes may not use the standard output. - The AT&T implementation's init and reset commands use the BSD - (4.1c) tset source, which manipulates terminal modes. It - successively tries standard output, standard error, standard input + The AT&T implementation's init and reset commands use the BSD + (4.1c) tset source, which manipulates terminal modes. It + successively tries standard output, standard error, standard input before falling back to "/dev/tty" and finally just assumes a 1200Bd terminal. When updating terminal modes, it ignores errors. - Until changes made after ncurses 6.0, tput did not modify terminal + Until changes made after ncurses 6.0, tput did not modify terminal modes. tput now uses a similar scheme, using functions shared with - tset (and ultimately based on the 4.4BSD tset). If it is not able + tset (and ultimately based on the 4.4BSD tset). If it is not able to open a terminal, e.g., when running in cron(1), tput will return an error. - o AT&T tput guesses the type of its cap-code operands by seeing if + o AT&T tput guesses the type of its cap-code operands by seeing if all of the characters are numeric, or not. - Most implementations which provide support for cap-code operands - use the tparm function to expand parameters in it. That function - expects a mixture of numeric and string parameters, requiring tput + Most implementations which provide support for cap-code operands + use the tparm function to expand parameters in it. That function + expects a mixture of numeric and string parameters, requiring tput to know which type to use. - This implementation uses a table to determine the parameter types + This implementation uses a table to determine the parameter types for the standard cap-code operands, and an internal library function to analyze nonstandard cap-code operands. - Besides providing more reliable operation than AT&T's utility, a - portability problem is introduced by this analysis: An OpenBSD - developer adapted the internal library function from ncurses to - port NetBSD's termcap-based tput to terminfo. That had been - modified to interpret multiple commands on a line. Portable + Besides providing more reliable operation than AT&T's utility, a + portability problem is introduced by this analysis: An OpenBSD + developer adapted the internal library function from ncurses to + port NetBSD's termcap-based tput to terminfo. That had been + modified to interpret multiple commands on a line. Portable applications should not rely upon this feature; ncurses provides it to support applications written specifically for OpenBSD. This implementation (unlike others) can accept both termcap and terminfo names for the cap-code feature, if termcap support is compiled - in. However, the predefined termcap and terminfo names have two + in. However, the predefined termcap and terminfo names have two ambiguities in this case (and the terminfo name is assumed): - o The termcap name dl corresponds to the terminfo name dl1 (delete + o The termcap name dl corresponds to the terminfo name dl1 (delete one line). - The terminfo name dl corresponds to the termcap name DL (delete a + The terminfo name dl corresponds to the termcap name DL (delete a given number of lines). - o The termcap name ed corresponds to the terminfo name rmdc (end + o The termcap name ed corresponds to the terminfo name rmdc (end delete mode). - The terminfo name ed corresponds to the termcap name cd (clear to + The terminfo name ed corresponds to the termcap name cd (clear to end of screen). - The longname and -S options, and the parameter-substitution features - used in the cup example, were not supported in AT&T/USL curses before + The longname and -S options, and the parameter-substitution features + used in the cup example, were not supported in AT&T/USL curses before SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for longname, and NetBSD (1994) added support for the parameter-substitution features. - IEEE Std 1003.1/The Open Group Base Specifications Issue 7 - (POSIX.1-2008) documents only the operands for clear, init and reset. + IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + (POSIX.1-2008) documents only the operands for clear, init and reset. There are a few interesting observations to make regarding that: o In this implementation, clear is part of the cap-code support. The - others (init and longname) do not correspond to terminal + others (init and longname) do not correspond to terminal capabilities. o Other implementations of tput on SVr4-based systems such as - Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64 + Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64 provide support for cap-code operands. o A few platforms such as FreeBSD recognize termcap names rather than terminfo capability names in their respective tput commands. Since - 2010, NetBSD's tput uses terminfo names. Before that, it (like + 2010, NetBSD's tput uses terminfo names. Before that, it (like FreeBSD) recognized termcap names. - Beginning in 2021, FreeBSD uses the ncurses tput, configured for + Beginning in 2021, FreeBSD uses the ncurses tput, configured for both terminfo (tested first) and termcap (as a fallback). Because (apparently) all of the certified Unix systems support the full - set of capability names, the reasoning for documenting only a few may + set of capability names, the reasoning for documenting only a few may not be apparent. o X/Open Curses Issue 7 documents tput differently, with cap-code and the other features used in this implementation. - o That is, there are two standards for tput: POSIX (a subset) and - X/Open Curses (the full implementation). POSIX documents a subset - to avoid the complication of including X/Open Curses and the + o That is, there are two standards for tput: POSIX (a subset) and + X/Open Curses (the full implementation). POSIX documents a subset + to avoid the complication of including X/Open Curses and the terminal capabilities database. - o While it is certainly possible to write a tput program without - using curses, no system with a curses implementation provides a + o While it is certainly possible to write a tput program without + using curses, no system with a curses implementation provides a tput utility that does not also supply the cap-code feature. X/Open Curses Issue 7 (2009) is the first version to document utilities. However that part of X/Open Curses does not follow existing practice (that is, System V curses behavior). - o It assigns exit status 4 to "invalid operand", which may be the - same as unknown capability. For instance, the source code for + o It assigns exit status 4 to "invalid operand", which may be the + same as unknown capability. For instance, the source code for Solaris' xcurses uses the term "invalid" in this case. - o It assigns exit status 255 to a numeric variable that is not + o It assigns exit status 255 to a numeric variable that is not specified in the terminfo database. That likely is a documentation - error, confusing the -1 written to the standard output for an + error, confusing the -1 written to the standard output for an absent or cancelled numeric value versus an (unsigned) exit status. - The various Unix systems (AIX, HP-UX, Solaris) use the same exit + The various Unix systems (AIX, HP-UX, Solaris) use the same exit statuses as ncurses. NetBSD curses documents different exit statuses which do not correspond @@ -441,62 +452,62 @@
HISTORY
- The tput command was begun by Bill Joy in 1980. The initial version + The tput command was begun by Bill Joy in 1980. The initial version only cleared the screen. AT&T System V provided a different tput command: - o SVr2 provided a rudimentary tput which checked the parameter - against each predefined capability and returned the corresponding - value. This version of tput did not use tparm(3x) for the + o SVr2 provided a rudimentary tput which checked the parameter + against each predefined capability and returned the corresponding + value. This version of tput did not use tparm(3x) for the capabilities which are parameterized. o SVr3 replaced that, a year later, by a more extensive program whose - init and reset subcommands (more than half the program) were - incorporated from the reset feature of BSD tset written by Eric + init and reset subcommands (more than half the program) were + incorporated from the reset feature of BSD tset written by Eric Allman. o SVr4 added color initialization using the orig_colors and orig_pair capabilities in the init subcommand. - Keith Bostic replaced the BSD tput command in 1989 with a new - implementation based on the AT&T System V program tput. Like the AT&T - program, Bostic's version accepted some parameters named for terminfo - capabilities (clear, init, longname and reset). However (because he - had only termcap available), it accepted termcap names for other - capabilities. Also, Bostic's BSD tput did not modify the terminal I/O + Keith Bostic replaced the BSD tput command in 1989 with a new + implementation based on the AT&T System V program tput. Like the AT&T + program, Bostic's version accepted some parameters named for terminfo + capabilities (clear, init, longname and reset). However (because he + had only termcap available), it accepted termcap names for other + capabilities. Also, Bostic's BSD tput did not modify the terminal I/O modes as the earlier BSD tset had done. At the same time, Bostic added a shell script named "clear", which used tput to clear the screen. - Both of these appeared in 4.4BSD, becoming the "modern" BSD + Both of these appeared in 4.4BSD, becoming the "modern" BSD implementation of tput. - This implementation of tput began from a different source than AT&T or - BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in - December 1992. Ridge's program made more sophisticated use of the - terminal capabilities than the BSD program. Eric Raymond used that - tput program (and other parts of mytinfo) in ncurses in June 1995. - Using the portions dealing with terminal capabilities almost without - change, Raymond made improvements to the way the command-line + This implementation of tput began from a different source than AT&T or + BSD: Ross Ridge's mytinfo package, published on comp.sources.unix in + December 1992. Ridge's program made more sophisticated use of the + terminal capabilities than the BSD program. Eric Raymond used that + tput program (and other parts of mytinfo) in ncurses in June 1995. + Using the portions dealing with terminal capabilities almost without + change, Raymond made improvements to the way the command-line parameters were handled.
EXAMPLES
tput init - Initialize the terminal according to the type of terminal in the - environment variable TERM. This command should be included in - everyone's .profile after the environment variable TERM has been + Initialize the terminal according to the type of terminal in the + environment variable TERM. This command should be included in + everyone's .profile after the environment variable TERM has been exported, as illustrated on the profile(5) manual page. tput -T5620 reset - Reset an AT&T 5620 terminal, overriding the type of terminal in + Reset an AT&T 5620 terminal, overriding the type of terminal in the environment variable TERM. tput cup 0 0 Send the sequence to move the cursor to row 0, column 0 (the upper - left corner of the screen, usually known as the "home" cursor + left corner of the screen, usually known as the "home" cursor position). tput clear @@ -509,8 +520,8 @@ Print the number of columns for the 450 terminal. bold=`tput smso` offbold=`tput rmso` - Set the shell variables bold, to begin stand-out mode sequence, - and offbold, to end standout mode sequence, for the current + Set the shell variables bold, to begin stand-out mode sequence, + and offbold, to end standout mode sequence, for the current terminal. This might be followed by a prompt: echo "${bold}Please type in your name: ${offbold}\c" @@ -522,11 +533,11 @@ Send the sequence to move the cursor to row 23, column 4. tput cup - Send the terminfo string for cursor-movement, with no parameters + Send the terminfo string for cursor-movement, with no parameters substituted. tput longname - Print the long name from the terminfo database for the type of + Print the long name from the terminfo database for the type of terminal specified in the environment variable TERM. tput -S @@ -542,10 +553,8 @@ clears the screen, moves the cursor to position (10, 10) and turns on bold (extra bright) mode. - The same sequence of commands can be combined using the OpenBSD - feature: - - $ tput clear cup 10 10 bold + tput clear cup 10 10 bold + Perform the same actions as the foregoing "tput -S" example.
SEE ALSO
@@ -553,7 +562,7 @@ -ncurses 6.4 2023-12-23 tput(1) +ncurses 6.4 2023-12-30 tput(1)

diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html index 98ae2ec9..4fa5bd0a 100644 --- a/doc/html/man/user_caps.5.html +++ b/doc/html/man/user_caps.5.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp @ + * @Id: user_caps.5,v 1.44 2023/12/30 21:36:32 tom Exp @ --> -user_caps 5 2023-12-23 ncurses 6.4 File formats +user_caps 5 2023-12-30 ncurses 6.4 File formats -
user_caps 5 2023-12-23 ncurses 6.4 File formats
+
user_caps 5 2023-12-30 ncurses 6.4 File formats

user_caps(5) File formats user_caps(5) @@ -66,7 +66,7 @@ Single Unix Specification beginning in 1995. Most of the extensions in this fixed repertoire were additions to the - tables of boolean, numeric and string capabilities. Rather than change + tables of Boolean, numeric and string capabilities. Rather than change the meaning of an existing capability, a new name was added. The terminfo database uses a binary format; binary compatibility was ensured by using a header which gave the number of items in the tables @@ -184,7 +184,7 @@ terminfo database may have other extensions, ncurses makes explicit checks for these: - AX boolean, asserts that the terminal interprets SGR 39 and SGR 49 + AX Boolean, asserts that the terminal interprets SGR 39 and SGR 49 by resetting the foreground and background color, respectively, to the default. @@ -196,13 +196,13 @@ The command "tput clear" does the same thing. - NQ boolean, used to suppress a consistency check in tic for the + NQ Boolean, used to suppress a consistency check in tic for the ncurses capabilities in user6 through user9 (u6, u7, u8 and u9) which tell how to query the terminal's cursor position and its device attributes. RGB - boolean, number or string, used to assert that the + Boolean, number or string, used to assert that the set_a_foreground and set_a_background capabilities correspond to direct colors, using an RGB (red/green/blue) convention. This capability allows the color_content function to return @@ -211,7 +211,7 @@ The capability type determines the values which ncurses sees: - boolean + Boolean implies that the number of bits for red, green and blue are the same. Using the maximum number of colors, ncurses adds two, divides that sum by three, and assigns the result to red, @@ -224,7 +224,7 @@ number tells ncurses what result to add to red, green and blue. If ncurses runs out of bits, blue (and green) lose just as in the - boolean case. + Boolean case. string explicitly list the number of bits used for red, green and @@ -396,7 +396,7 @@ -ncurses 6.4 2023-12-23 user_caps(5) +ncurses 6.4 2023-12-30 user_caps(5)

diff --git a/include/Caps b/include/Caps index ceff65af..e21d5924 100644 --- a/include/Caps +++ b/include/Caps @@ -30,7 +30,7 @@ # Author: Zeyd M. Ben-Halim 1992,1995 # and: Eric S. Raymond # -# $Id: Caps,v 1.49 2023/10/14 20:54:32 tom Exp $ +# $Id: Caps,v 1.50 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is the master termcap/terminfo capability table. # @@ -48,7 +48,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -206,7 +206,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H diff --git a/include/Caps.aix4 b/include/Caps.aix4 index ce6069f0..3b2389be 100644 --- a/include/Caps.aix4 +++ b/include/Caps.aix4 @@ -29,7 +29,7 @@ # # Author: Thomas Dickey # -# $Id: Caps.aix4,v 1.21 2023/10/14 21:47:17 tom Exp $ +# $Id: Caps.aix4,v 1.22 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is an adaptation of ncurses' termcap/terminfo capability table, which # is designed to align with AIX 4.x's terminfo. @@ -48,7 +48,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -206,7 +206,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H diff --git a/include/Caps.hpux11 b/include/Caps.hpux11 index 4d61364d..f9633f4c 100644 --- a/include/Caps.hpux11 +++ b/include/Caps.hpux11 @@ -29,7 +29,7 @@ # # Author: Thomas Dickey # -# $Id: Caps.hpux11,v 1.19 2023/10/14 21:50:28 tom Exp $ +# $Id: Caps.hpux11,v 1.20 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is an adaptation of ncurses' termcap/terminfo capability table, which # is designed to align with HPUX 11.x's terminfo. @@ -48,7 +48,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -206,7 +206,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H @@ -237,7 +237,7 @@ dest_tabs_magic_smso xt bool xt - - YBCGE tabs destructive, magic so char (t106 tilde_glitch hz bool hz - - YB-GE cannot print ~'s (Hazeltine) transparent_underline ul bool ul - - YBCGE underline character overstrikes xon_xoff xon bool xo - - YB--- terminal uses xon/xoff handshaking -# end booleans for HPUX 9, 10 (non-color curses) +# end Booleans for HPUX 9, 10 (non-color curses) needs_xon_xoff nxon bool nx - - ----- padding will not work, xon/xoff required prtr_silent mc5i bool 5i - - ----- printer will not echo on screen hard_cursor chts bool HC - - ----- cursor is hard to see diff --git a/include/Caps.keys b/include/Caps.keys index f3e6dc3b..48da83bc 100644 --- a/include/Caps.keys +++ b/include/Caps.keys @@ -30,7 +30,7 @@ # Author: Thomas Dickey # and: Ilya Zakharevich # -# $Id: Caps.keys,v 1.18 2023/10/14 21:48:29 tom Exp $ +# $Id: Caps.keys,v 1.19 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is an adaptation of ncurses' termcap/terminfo capability table, which # is illustrates an experimental extension to describe alt-, shift- and @@ -50,7 +50,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -208,7 +208,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H diff --git a/include/Caps.osf1r5 b/include/Caps.osf1r5 index 30e350a2..04d8f55f 100644 --- a/include/Caps.osf1r5 +++ b/include/Caps.osf1r5 @@ -29,7 +29,7 @@ # # Author: Thomas Dickey # -# $Id: Caps.osf1r5,v 1.17 2023/10/14 21:48:39 tom Exp $ +# $Id: Caps.osf1r5,v 1.18 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is an adaptation of ncurses' termcap/terminfo capability table, which # is designed to align with OSF/1 version 5 (Tru64) terminfo. @@ -48,7 +48,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -206,7 +206,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H diff --git a/include/Caps.uwin b/include/Caps.uwin index 59332c4e..6214f59a 100644 --- a/include/Caps.uwin +++ b/include/Caps.uwin @@ -29,7 +29,7 @@ # # Author: Thomas Dickey # -# $Id: Caps.uwin,v 1.16 2023/10/14 21:48:58 tom Exp $ +# $Id: Caps.uwin,v 1.17 2023/12/30 21:36:32 Branden.Robinson Exp $ # # This is an adaptation of ncurses' termcap/terminfo capability table, which # is designed to align with U/Win's terminfo. @@ -48,7 +48,7 @@ # # Column 1: terminfo variable name # Column 2: terminfo capability name -# Column 3: capability type (boolean, numeric, or string) +# Column 3: capability type (Boolean, numeric, or string) # Column 4: termcap capability name # Column 5: KEY_xxx name, if any, `-' otherwise # Column 6: value for KEY_xxx name, if any, `-' otherwise @@ -206,7 +206,7 @@ #%indicates the \fIi\fP\uth\d parameter. #% #%.PP -#% These are the boolean capabilities: +#% These are the Boolean capabilities: #% #%.na #%.TS H diff --git a/man/curs_color.3x b/man/curs_color.3x index 73dce9ca..0fb6dcc4 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.95 2023/12/23 20:18:13 tom Exp $ -.TH curs_color 3X 2023-12-23 "ncurses 6.4" "Library calls" +.\" $Id: curs_color.3x,v 1.96 2023/12/30 21:20:01 tom Exp $ +.TH curs_color 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -142,7 +142,7 @@ as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X) window attributes, as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X) .bP -window background character atttributes, +window background character attributes, as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X) .PP Per-character and window attributes are usually set through a function diff --git a/man/curs_inwstr.3x b/man/curs_inwstr.3x index fd748d08..b11cb21f 100644 --- a/man/curs_inwstr.3x +++ b/man/curs_inwstr.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_inwstr.3x,v 1.35 2023/11/25 11:31:49 tom Exp $ -.TH curs_inwstr 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: curs_inwstr.3x,v 1.36 2023/12/30 21:32:48 tom Exp $ +.TH curs_inwstr 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -107,8 +107,9 @@ All routines except \fBwinnwstr\fP may be macros. .PP -Each cell in the window holds a complex character (i.e., base- -and combining-characters) together with attributes and color. +Each cell in the window holds a complex character +(a spacing character and zero or more non-spacing characters) +together with attributes and color. These functions store only the wide characters, ignoring attributes and color. Use \fBin_wchstr\fP to return the complex characters from a window. diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x index ceb27fe0..16c802a1 100644 --- a/man/curs_scr_dump.3x +++ b/man/curs_scr_dump.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scr_dump.3x,v 1.36 2023/12/16 21:10:18 tom Exp $ -.TH curs_scr_dump 3X 2023-12-16 "ncurses 6.4" "Library calls" +.\" $Id: curs_scr_dump.3x,v 1.37 2023/12/30 21:34:11 tom Exp $ +.TH curs_scr_dump 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -60,55 +60,88 @@ read/write a \fIcurses\fR screen from/to a file \fBint scr_set(const char *\fIfilename\fP); .fi .SH DESCRIPTION +.I curses +provides applications the ability to write the contents of the screen +to a file and read them back. +To read/write a window +(rather than the whole screen) +from/to a file, +use \fB\%getwin\fP(3X) and +\fB\%putwin\fP(3X), +respectively. .SS scr_dump -The \fBscr_dump\fP routine dumps the current contents -of the \fIvirtual screen\fP -to the file \fIfilename\fP. +\fB\%scr_dump\fP writes to +.I filename +the contents of the virtual screen; +see \fB\%curscr\fP(3X). .SS scr_restore -The \fBscr_restore\fP routine sets the \fIvirtual screen\fP to the contents -of \fIfilename\fP, which must have been written using \fBscr_dump\fP. -The next call to \fBdoupdate\fP restores -the \fIphysical screen\fP to the way it looked in the dump file. +\fB\%scr_restore\fP updates the virtual screen to contain the contents +of +.I filename +(if it was validly written with \fB\%scr_dump\fP). +No refresh is performed; +after performing any further desired updates, +call \fB\%doupdate\fP(3X) or similar. .SS scr_init -The \fBscr_init\fP routine reads in the contents of \fIfilename\fP and uses -them to initialize the \fBcurses\fP data structures about what the terminal -currently has on its screen. -If the data is determined to be valid, -\fBcurses\fP bases its next update of the screen on this information rather -than clearing the screen and starting from scratch. -\fBscr_init\fP is used -after \fBinitscr\fP(3X) or a \fBsystem\fP(3) call to share -the screen with another process which has done a \fBscr_dump\fP after its -\fBendwin\fP(3X) call. -The data is declared invalid +\fB\%scr_init\fP reads +.I filename, +using it to initialize +.I curses +data structures describing the state of the terminal screen. +If these data are valid, +.I curses +bases its next update of the screen on this information rather than +clearing it and starting from scratch. +.PP +The data fail the validity check .bP -if the terminfo capabilities \fBrmcup\fP and \fBnrrmc\fP exist, also +if the terminal employs +.I \%term\%info +capabilities +.B \%exit_ca_mode +.RB ( \%rmcup ) +or +.B \%non_rev_rmcup +.RB ( \%nrrmc ) +are defined, +or .bP -if the terminal has been written to since the preceding \fBscr_dump\fP call. +if +.I curses +knows that the terminal has been written to since the preceding +\fB\%scr_dump\fP call. +.PP +\fB\%scr_init\fP could be used after \fB\%initscr\fP(3X) or +\fB\%system\fP(3) to share the screen with another process that has +done a \fBscr_dump\fP after \fB\%endwin\fP(3X). .SS scr_set The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and \fBscr_init\fP. It tells the program that the information in \fIfilename\fP is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. -.PP -To read (write) a window from (to) a file, use the \fBgetwin\fP and -\fBputwin\fP routines [see \fBcurs_util\fP(3X)]. .SH RETURN VALUE -These routines return the integer \fBERR\fP upon failure and \fBOK\fP -upon success. +These functions return \fBOK\fP on success and \fBERR\fP on failure. .PP -X/Open defines no error conditions. +X/Open defines no failure conditions. In this implementation, -each will return an error if the file cannot be opened. +each function fails if it cannot open +.I filename. .SH NOTES -Note that \fBscr_init\fP, \fBscr_set\fP, and \fBscr_restore\fP may be macros. +\fB\%scr_init\fP, +\fB\%scr_set\fP, +and +\fB\%scr_restore\fP may be macros. .SH PORTABILITY -These functions are described in the XSI Curses standard, Issue 4, -which adds \fI\%const\fP qualifiers to the arguments. +X/Open Curses, Issue 4, describes these functions. +.PP +.\" SVID 4, p. 529 +SVr4 omitted the +.I \%const +qualifiers. .PP -The SVr4 docs merely say under \fBscr_init\fP that the dump data is also -considered invalid \*(``if the time-stamp of the tty is old\*('' but do -not define \*(``old\*(''. +SVr4 documentation describes \fB\%scr_init\fP such that the dump data is +also considered invalid \*(``if the time-stamp of the tty is old\*('' +but does not define \*(``old\*(''. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_initscr\fP(3X), diff --git a/man/curs_termcap.3x b/man/curs_termcap.3x index 464209f9..1c176e01 100644 --- a/man/curs_termcap.3x +++ b/man/curs_termcap.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_termcap.3x,v 1.80 2023/12/23 20:19:05 tom Exp $ -.TH curs_termcap 3X 2023-12-23 "ncurses 6.4" "Library calls" +.\" $Id: curs_termcap.3x,v 1.81 2023/12/30 21:27:22 tom Exp $ +.TH curs_termcap 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -415,7 +415,8 @@ refactored it, leaving the API unchanged. .PP Function prototypes were a feature of ANSI C (1989). -Thus the library itself provided no header file declaring them. +The library long antedated the standard and thus provided no header file +declaring them. Nevertheless, the BSD sources included two different \fI\%termcap.h\fP header files over time. @@ -434,7 +435,7 @@ One was used internally by \fBjove\fP(1) from 4.3BSD onward. .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\ .\" jove/Makefile .\" --much too late for 2BSD (1979). -It delcared global symbols for the \fItermcap\fP variables that it used. +It declared global symbols for the \fItermcap\fP variables that it used. .bP The other appeared in 4.4BSD-Lite Release 2 (June 1995) diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x index 88f5b97f..e5affc46 100644 --- a/man/curs_terminfo.3x +++ b/man/curs_terminfo.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp $ -.TH curs_terminfo 3X 2023-12-23 "ncurses 6.4" "Library calls" +.\" $Id: curs_terminfo.3x,v 1.125 2023/12/30 23:46:56 tom Exp $ +.TH curs_terminfo 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -65,7 +65,7 @@ \fB\%vid_puts\fP, \fB\%vidattr\fP, \fB\%vidputs\fP \- -\fIcurses\fR interfaces to \fIterminfo\fR database +\fIcurses\fR interfaces to \fI\%term\%info\fR database .SH SYNOPSIS .nf \fB#include @@ -117,38 +117,53 @@ .fi .SH DESCRIPTION These low-level routines must be called by programs that have to deal -directly with the \fIterminfo\fP database to handle certain terminal -capabilities, such as programming function keys. -For all other -functionality, \fIcurses\fP routines are more suitable and their use is -recommended. +directly with the +.I \%term\%info +database to handle certain terminal capabilities, +such as programming function keys. +For all other functionality, +.I curses +routines are more suitable and their use is recommended. .PP -None of these functions use (or are aware of) multibyte character strings -such as UTF-8: +None of these functions use +(or are aware of) +multibyte character strings such as UTF-8. .bP -capability names use the POSIX portable character set +Capability names and codes use the POSIX portable character set. .bP -capability string values have no associated encoding; +Capability string values have no associated encoding; they are strings of 8-bit characters. .SS Initialization -Initially, \fBsetupterm\fP should be called. -The high-level curses functions \fBinitscr\fP and -\fBnewterm\fP call \fBsetupterm\fP to initialize the -low-level set of terminal-dependent variables -[listed in \fBterminfo\fP(5)]. +Initially, +\fB\%setupterm\fP should be called. +The high-level +.I curses +functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to +initialize the low-level set of terminal-dependent variables +listed in \fB\%term_variables\fP(3X). .PP Applications can use the -terminal capabilities either directly (via header definitions), +terminal capabilities either directly +(via header definitions), or by special functions. -The header files \fBcurses.h\fP and \fBterm.h\fP should be included (in this -order) to get the definitions for these strings, numbers, and flags. -.PP -The \fBterminfo\fP variables -\fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as +The header files +.I \%curses.h +and +.I \%term.h +should be included +(in that order) +to get the definitions for these strings, numbers, and flags. +.PP +The +.I \%term\%info +variables +\fBlines\fP and \fBcolumns\fP are initialized by \fB\%setupterm\fP as follows: .bP -If \fBuse_env(FALSE)\fP has been called, values for -\fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used. +If \fB\%use_env(FALSE)\fP has been called, +values for \fBlines\fP and \fBcolumns\fP specified in +.I \%term\%info +are used. .bP Otherwise, if the environment variables \fILINES\fP and \fI\%COLUMNS\fP exist, @@ -158,10 +173,13 @@ exist and the program is running in a window, the current window size is used. Otherwise, if the environment variables do not exist, the values for \fBlines\fP and \fBcolumns\fP specified in the -\fBterminfo\fP database are used. +.I \%term\%info +database are used. .PP Parameterized strings should be passed through \fBtparm\fP to instantiate them. -All \fBterminfo\fP strings +All +.I \%term\%info +strings (including the output of \fBtparm\fP) should be printed with \fBtputs\fP or \fBputp\fP. @@ -184,9 +202,14 @@ is called and output \fBenter_ca_mode\fP and call \fBreset_prog_mode\fP after returning from the shell. .PP -The \fBsetupterm\fP routine reads in the \fBterminfo\fP database, -initializing the \fBterminfo\fP structures, but does not set up the -output virtualization structures used by \fBcurses\fP. +The \fB\%setupterm\fP routine reads in the +.I \%term\%info +database, +initializing the +.I \%term\%info +structures, +but does not set up the output virtualization structures used by +.I curses. These are its parameters: .RS 3 .TP 5 @@ -232,16 +255,20 @@ having too little information for \fIcurses\fP applications to run. checking the \fBgn\fP \%(\fBgeneric_type\fP) capability. .TP 5 .B \-1 -means that the \fIterminfo\fP database could not be found. +means that the +.I \%term\%info +database could not be found. .RE .IP If \fIerrret\fP is null, \fB\%setupterm\fP prints an error message upon finding an error and exits. Thus, the simplest call is: +.RS +.IP +\fBsetupterm((char *)0, 1, (int *)0);\fP +.RE .IP -\fBsetupterm((char *)0, 1, (int *)0);\fP, -.PP which uses all the defaults and sends the output to \fBstdout\fP. .RE .\" *************************************************************************** @@ -259,17 +286,29 @@ It maintains only one copy of a given terminal's capabilities in memory. If it is called for different terminal types, \fBsetupterm\fP allocates new storage for each set of terminal capabilities. .PP -The \fBset_curterm\fP routine sets \fBcur_term\fP to -\fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and -string variables use the values from \fInterm\fP. -It returns the old value of \fBcur_term\fP. -.PP -The \fBdel_curterm\fP routine frees the space pointed to by -\fIoterm\fP and makes it available for further use. -If \fIoterm\fP is -the same as \fBcur_term\fP, references to any of the \fBterminfo\fP -boolean, numeric, and string variables thereafter may refer to invalid -memory locations until another \fBsetupterm\fP has been called. +\fB\%set_curterm\fP sets \fB\%cur_term\fP to +.I \%nterm, +and makes all of the +.I \%term\%info +Boolean, +numeric, +and string variables use the values from +.I \%nterm. +It returns the old value of \fB\%cur_term\fP. +.PP +\fB\%del_curterm\fP routine frees the space pointed to by +.I \%oterm +and makes it available for further use. +If +.I \%oterm +is +the same as \fB\%cur_term\fP, +references to any of the +.I \%term\%info +Boolean, +numeric, +and string variables thereafter may refer to invalid memory locations +until another \fB\%setupterm\fP has been called. .PP The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP, except that it is called after restoring memory to a previous state (for @@ -298,9 +337,13 @@ it is interpreted by \fBtputs\fP. The capability string is null-terminated. Use \*(``\e200\*('' where an ASCII NUL is needed in the output. .PP -\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI\fP +\fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses +.I \%stdarg.h rather than a fixed-parameter list. -Its numeric parameters are integers (int) rather than longs. +Its numeric parameters are +.IR int s +rather than +.IR long s. .PP Both \fBtparm\fP and \fBtiparm\fP assume that the application passes parameters consistent with the terminal description. @@ -337,7 +380,9 @@ variable or the return value from .IP The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP interface, -which happens to share this function name with the \fIterminfo\fP interface. +which happens to share this function name with the +.I \%term\%info +interface. .bP \fIaffcnt\fP is the number of lines affected, or 1 if not applicable. @@ -362,23 +407,40 @@ the \fI\%putchar\fP-like function \fIputc\fP. The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except that it outputs through \fI\%putchar\fP. .PP -The \fBvid_attr\fP and \fBvid_puts\fP routines correspond -to vidattr and vidputs, respectively. -They use a set of arguments for representing the video attributes plus color, -i.e., -.bP -\fIattrs\fP of type \fBattr_t\fP for the attributes and -.bP -\fIpair\fP of type \fBshort\fP for the color pair number. -.PP -The \fBvid_attr\fP and \fBvid_puts\fP routines -are designed to use the attribute constants with the \fBWA_\fP prefix. -.PP -X/Open Curses reserves the \fIopts\fP argument for future use, -saying that applications must provide a null pointer for that argument. -As an extension, -this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP, -which overrides the \fIpair\fP (\fBshort\fP) argument. +.B \%vid_attr +and +.B \%vid_puts +correspond to +.B \%vidattr +and +.BR \%vidputs , +respectively. +They use multiple parameters to represent the character attributes and +color; +namely, +.bP +.I \%attrs, +of type +.I \%attr_t, +for the attributes and +.bP +.I pair, +of type +.I short, +for the color pair number. +.PP +Use the attribute constants prefixed with +.RB \*(`` WA_ \*('' +with +.B \%vid_attr +and +.BR \%vid_puts . +.PP +X/Open Curses reserves the +.I opts +argument for future use, +saying that applications must provide a null pointer for that argument; +but see section \*(``EXTENSIONS\*('' below. .PP The \fBmvcur\fP routine provides low-level cursor motion. It takes effect immediately (rather than at the next refresh). @@ -389,22 +451,25 @@ the output stream parameter of \fBnewterm\fP(3X). .PP While \fBputp\fP and \fBmvcur\fP are low-level functions which do not use the high-level curses state, -they are declared in \fB\%\fP because System\ V did this +they are declared in +.I \%curses.h +because System\ V did this (see \fIHISTORY\fP). .\" *************************************************************************** .SS "Terminal Capability Functions" The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return -the value of the capability corresponding to the \fBterminfo\fP +the value of the capability corresponding to the +.I \%term\%info \fIcapname\fP passed to them, such as \fBxenl\fP. The \fIcapname\fP for each capability is given in the table column entitled -\fIcapname\fP code in the capabilities section of \fBterminfo\fP(5). +\fIcapname\fP code in the capabilities section of \fB\%terminfo\fP(5). .PP These routines return special values to denote errors. .PP The \fBtigetflag\fP routine returns .TP \fB\-1\fP -if \fIcapname\fP is not a boolean capability, +if \fIcapname\fP is not a Boolean capability, or .TP \fB0\fP @@ -430,13 +495,15 @@ if it is canceled or absent from the terminal description. .SS "Terminal Capability Names" These null-terminated arrays contain .bP -the short \fIterminfo\fP names (\*(``codes\*(''), +the short \fI\%term\%info\fP names (\*(``codes\*(''), .bP the \fItermcap\fP names (\*(``names\*(''), and .bP -the long \fIterminfo\fP names (\*(``fnames\*('') +the long \fI\%term\%info\fP names (\*(``fnames\*('') .PP -for each of the predefined \fIterminfo\fP variables: +for each of the predefined +.I \%term\%info +variables: .PP .RS .nf @@ -462,7 +529,7 @@ allocated by \fBsetupterm\fP: the \*(``static\*('' terminfo variables [a-z]. Before \fI\%ncurses\fP 6.3, those were shared by all screens. With \fI\%ncurses\fP 6.3, those are allocated per screen. -See \fBterminfo\fP(5) for details. +See \fB\%terminfo\fP(5) for details. .bP to improve performance, \fI\%ncurses\fP 6.3 caches the result of analyzing terminfo @@ -474,16 +541,9 @@ Normally they do not free this memory, but it is possible to do that using the \fBdelscreen\fP(3X) function. .\" *************************************************************************** .SH RETURN VALUE -Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP -(SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('') -upon successful completion, -unless otherwise noted in the preceding routine descriptions. -.PP -Routines that return pointers always return \fBNULL\fP on error. -.PP -X/Open defines no error conditions. -In this implementation -.RS 3 +X/Open defines no failure conditions. +In +.I \%ncurses, .TP 5 \fBdel_curterm\fP returns an error @@ -499,7 +559,11 @@ if the associated call to \fBsetupterm\fP returns an error. \fBsetupterm\fP returns an error if it cannot allocate enough memory, or -create the initial windows (stdscr, curscr, newscr). +create the initial windows +.RB ( \%stdscr , +.BR \%curscr , +and +.BR \%newscr ) Other error conditions are documented above. .TP 5 \fBtparm\fP @@ -510,44 +574,44 @@ e.g., too many, too few, or incorrect types \fBtputs\fP returns an error if the string parameter is null. It does not detect I/O errors: -X/Open states that \fBtputs\fP ignores the return value +X/Open Curses states that \fBtputs\fP ignores the return value of the output function \fIputc\fP. -.RE .\" *************************************************************************** .SH NOTES -.\" See X/Open Curses Issue 4, Version 2, pp. 227-234. -.\" See X/Open Curses Issue 7, pp. 311-318. -According to X/Open Curses, -any of the \fIenhanced curses\fP functions may be implemented as macros. -The term \*(``enhanced\*('' refers to features not found in SVr4 curses. -.PP -\fB\%ncurses\fP uses macros -.bP -for functions which return values via their parameters, -.bP -to support obsolete features, -.bP -to reuse functions, -e.g., those that move the cursor before another operation, and -.bP -a few special cases. -.PP -The \fB\%vid_puts\fP function in \fB\%ncurses\fP is a special case. +The +.B \%vid_attr +function in +.I \%ncurses +is a special case. It was originally implemented based on a draft of X/Open Curses, as a macro, -before other parts of the \fB\%ncurses\fP wide-character API were developed. +before other parts of the +.I \%ncurses +wide-character API were developed, +and unlike the other wide-character functions, +is also provided in the non-wide-character configuration. .\" *************************************************************************** .SH EXTENSIONS The functions marked as extensions were designed for -\fB\%ncurses\fP(3X), +.I \%ncurses, and are not found in SVr4 .IR curses , 4.4BSD .IR curses , or any other previous curses implementation. +.PP +.I \%ncurses +allows +.I opts +to be a pointer to +.I int, +which overrides the +.I pair +.RI ( short ) +argument. .\" *************************************************************************** .SH PORTABILITY -\fBsetterm\fP is not described by X/Open and must be considered +\fB\%setterm\fP is not described by X/Open and must be considered non-portable. All other functions are as described by X/Open. .SS "Compatibility Macros" @@ -575,60 +639,81 @@ It further notes that \fB\%setterm\fP was replaced by \fB\%setupterm\fP, stating that the call .RS .EX -setupterm(\fIterm\fB, 1, (int *)0)\fP +setupterm(\fIterm\fP, 1, (int *)0) .EE .RE -provides the same functionality as \fBsetterm(\fIterm\fB)\fR, +provides the same functionality as \fB\%setterm(\fIterm\fB)\fR, discouraging the latter for new programs. .I \%ncurses implements each of these symbols as macros for BSD .I curses compatibility. .SS "Legacy Data" -\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP. +\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP. This is not part of X/Open Curses, but is assumed by some applications. .PP Other implementions may not declare the capability name arrays. Some provide them without declaring them. X/Open does not specify them. .PP -Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP, +Extended terminal capability names, +as defined by +.RB \%\*(`` "@TIC@\ \-x" \*('', are not stored in the arrays described here. .SS "Output Buffering" Older versions of \fI\%ncurses\fP assumed that the file descriptor -passed to \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses +passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP uses buffered I/O, and would write to the corresponding stream. -In addition to the limitation that the terminal was left in block-buffered -mode on exit (like System V curses), -it was problematic because \fI\%ncurses\fP -did not allow a reliable way to cleanup on receiving SIGTSTP. +In addition to the limitation that the terminal was left in +block-buffered mode on exit +(like System\ V +.IR curses ), +it was problematic because +.I \%ncurses +did not allow a reliable way to cleanup on receiving +.BR SIGTSTP . .PP The current version (ncurses6) -uses output buffers managed directly by \fI\%ncurses\fP. +uses output buffers managed directly by +.I \%ncurses. Some of the low-level functions described in this manual page write to the standard output. They are not signal-safe. -The high-level functions in \fI\%ncurses\fP use -alternate versions of these functions -using the more reliable buffering scheme. +The high-level functions in +.I \%ncurses +employ alternate versions of these functions using the more reliable +buffering scheme. .SS "Function Prototypes" -The X/Open Curses prototypes are based on the SVr4 curses header declarations, -which were defined at the same time the C language was first standardized in -the late 1980s. +The X/Open Curses prototypes are based on the SVr4 +.I curses +header declarations, +which were defined at the same time the C language was first +standardized in the late 1980s. .bP -X/Open Curses uses \fBconst\fP less effectively than a later design might, +X/Open Curses uses +.I \%const +less effectively than a later design might, in some cases applying it needlessly to values are already constant, -and in most cases overlooking parameters which normally would use \fBconst\fP. -Using constant parameters for functions which do not use \fBconst\fP +and in most cases overlooking parameters which normally would use +.I \%const. +Using constant parameters for functions which do not use +.I \%const may prevent the program from compiling. -On the other hand, \fIwritable strings\fP are an obsolescent feature. +On the other hand, +\*(``writable strings\*('' are an obsolescent feature. .IP -As an extension, this implementation can be configured to change the -function prototypes to use the \fBconst\fP keyword. -The \fI\%ncurses\fP ABI 6 enables this feature by default. +As an extension, +this implementation can be configured to change the function prototypes +to use the +.I \%const +keyword. +The +.I \%ncurses +ABI 6 enables this feature by default. .bP -X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters, +X/Open Curses prototypes \fB\%tparm\fP with a fixed number of +parameters, rather than a variable argument list. .IP This implementation uses a variable argument list, but can be @@ -637,64 +722,101 @@ Portable applications should provide 9 parameters after the format; zeroes are fine for this purpose. .IP In response to review comments by Thomas E. Dickey, -X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009. +X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009. .IP -While \fBtiparm\fP is always provided in \fI\%ncurses\fP, +While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP, the older form is only available as a build-time configuration option. -If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP. +If not specially configured, +\fB\%tparm\fP is the same as \fB\%tiparm\fP. .PP -Both forms of \fBtparm\fP have drawbacks: +Both forms of \fB\%tparm\fP have drawbacks: .bP -Most of the calls to \fBtparm\fP use only one or two parameters. +Most of the calls to \fB\%tparm\fP use only one or two parameters. Passing nine on each call is awkward. .IP -Using \fBlong\fP for the numeric parameter type is a workaround -to make the parameter use the same amount of stack as a pointer. +Using +.I long +for the numeric parameter type is a workaround to make the parameter use +the same amount of stack as a pointer. That approach dates back to the mid-1980s, before C was standardized. Since then, there is a standard (and pointers are not required to fit in a long). .bP Providing the right number of parameters for a variadic function -such as \fBtiparm\fP can be a problem, in particular for string parameters. +such as \fB\%tiparm\fP can be a problem, +in particular for string parameters. However, only a few terminfo capabilities use string parameters (e.g., the ones used for programmable function keys). .IP The \fI\%ncurses\fP library checks usage of these capabilities, and returns an error if the capability mishandles string parameters. But it cannot check if a calling program provides strings in the right -places for the \fBtparm\fP calls. +places for the \fB\%tparm\fP calls. .IP -The \fB@TPUT@\fR(1) program checks its use of these capabilities with a table, -so that it calls \fBtparm\fP correctly. +The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with +a table, +so that it calls \fB\%tparm\fP correctly. .SS "Special \fITERM\fP treatment" If configured to use the terminal-driver, e.g., for the MinGW port, .bP -\fBsetupterm\fP interprets a missing/empty \fITERM\fP variable as the +\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the special value \*(``unknown\*(''. .IP SVr4 curses uses the special value \*(``dumb\*(''. .IP The difference between the two is that -the former uses the \fBgn\fP (\fBgeneric_type\fR) terminfo capability, +the former uses the \fBgn\fP (\fB\%generic_type\fR) terminfo capability, while the latter does not. A generic terminal is unsuitable for full-screen applications. .bP -\fBsetupterm\fP allows explicit use of the +\fB\%setupterm\fP allows explicit use of the the windows console driver by checking if \fB$TERM\fP is set to \*(``#win32con\*('' or an abbreviation of that string. .SS "Other Portability Issues" -In System V Release 4, \fBset_curterm\fP has an \fBint\fP return type and -returns \fBOK\fP or \fBERR\fP. We have chosen to implement the X/Open Curses -semantics. +In SVr4, +\fB\%set_curterm\fP returns an +.I int, +.B OK +or +.BR ERR . +We have chosen to implement the X/Open Curses semantics. .PP -In System V Release 4, the third argument of \fBtputs\fP has the type -\fBint (*putc)(char)\fP. +In SVr4, +the third argument of \fB\%tputs\fP has the type +.RB \*(`` "int (*putc)(char)" \*(''. .PP At least one implementation of X/Open Curses (Solaris) returns a value -other than \fBOK\fP/\fBERR\fP from \fBtputs\fP. -That returns the length of the string, and does no error-checking. +other than +.B OK +or +.B ERR +from \fB\%tputs\fP. +It instead returns the length of the string, +and does no error checking. +.PP +X/Open Curses notes that after calling \fB\%mvcur\fP, +the +.I curses +state may not match the actual terminal state, +and that an application should touch and refresh the window before +resuming normal +.I curses +calls. +Both +.I \%ncurses +and SVr4 +.I curses +implement \fB\%mvcur\fP using the +.I SCREEN +data allocated in either \fB\%initscr\fP or \fB\%newterm\fP. +So though it is documented as a +.I \%term\%info +function, +\fB\%mvcur\fP is really a +.I curses +function that is not well specified. .PP X/Open notes that after calling \fBmvcur\fP, the curses state may not match the actual terminal state, and that an application should touch and refresh @@ -705,12 +827,23 @@ using the \fISCREEN\fP data allocated in either \fBinitscr\fP or So though it is documented as a terminfo function, \fBmvcur\fP is really a curses function which is not well specified. .PP -X/Open states that the old location must be given for \fBmvcur\fP. -This implementation allows the caller to use \-1's for the old ordinates. -In that case, the old location is unknown. +X/Open Curses states that the old location must be given for +\fB\%mvcur\fP to accommodate terminals that lack absolute cursor +positioning. +.\" X/Open Curses Issue 7, p. 161 +.I \%ncurses +allows the caller to use \-1 for either or both old coordinates. +The \-1 tells +.I \%ncurses +that the old location is unknown, +and that it must use only absolute motion +(such as \fI\%cursor_address\fP) +rather than the least costly combination of absolute and relative motion. .\" *************************************************************************** .SH HISTORY -SVr2 introduced the terminfo feature. +SVr2 (1984) introduced the +.I \%term\%info +feature. Its programming manual mentioned the following low-level functions. .PP .TS @@ -721,26 +854,23 @@ _ fixterm restore tty to \*(``in curses\*('' state gettmode establish current tty modes mvcur low level cursor motion -putp T{ -utility function that uses \fBtputs\fP to send characters via -\fI\%putchar\fP. -T} +putp use \fBtputs\fP to send characters via \fI\%putchar\fP resetterm set tty modes to \*(``out of curses\*('' state resetty reset tty flags to stored value saveterm save current modes as \*(``in curses\*('' state savetty store current tty flags setterm establish terminal with given type setupterm establish terminal with given type -tparm instantiate a string expression with parameters +tparm interpolate parameters into string capability tputs apply padding information to a string -vidattr like \fBvidputs\fP, but outputs through \fIputchar\fP -vidputs T{ -output a string to put terminal in a specified video attribute mode -T} +vidattr like \fBvidputs\fP, but output through \fIputchar\fP +vidputs write string to terminal, applying specified attributes .TE .PP The programming manual also mentioned -functions provided for \fItermcap\fP compatibility +functions provided for +.I termcap +compatibility (commenting that they \*(``may go away at a later date\*(''). .PP .TS @@ -749,34 +879,42 @@ lB lx. Function Description _ tgetent look up \fItermcap\fP entry for given \fIname\fP -tgetflag get boolean entry for given \fIid\fP +tgetflag get Boolean entry for given \fIid\fP tgetnum get numeric entry for given \fIid\fP tgetstr get string entry for given \fIid\fP tgoto apply parameters to given capability -tputs T{ -apply padding to capability, calling a function to put characters -T} +tputs write characters via a function parameter, applying padding .TE .PP -Early terminfo programs obtained capability values from the -\fI\%TERMINAL\fP structure initialized by \fBsetupterm\fP. +Early +.I \%term\%info +programs obtained capability values from the +.I \%TERMINAL +structure initialized by \fB\%setupterm\fP. .PP -SVr3 extended terminfo by adding functions to retrieve capability values -(like the termcap interface), -and reusing \fBtgoto\fP and \fBtputs\fP: +SVr3 (1987) extended +.I \%term\%info +by adding functions to retrieve capability values +(like the +.I termcap +interface), +and reusing \fB\%tgoto\fP and \fB\%tputs\fP. .PP .TS lB lB lB lx. Function Description _ -tigetflag get boolean entry for given \fIid\fP +tigetflag get Boolean entry for given \fIid\fP tigetnum get numeric entry for given \fIid\fP tigetstr get string entry for given \fIid\fP .TE .PP -SVr3 also replaced several of the SVr2 \fIterminfo\fP functions -which had no counterpart in the \fItermcap\fP interface, +SVr3 also replaced several of the SVr2 +.I \%term\%info +functions that had no counterpart in the +.I termcap +interface, documenting them as obsolete. .PP .TS @@ -793,30 +931,41 @@ saveterm def_prog_mode setterm setupterm .TE .PP -SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions, -along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP. +SVr3 kept the \fB\%mvcur\fP, +\fB\%vidattr\fP, +and \fB\%vidputs\fP functions, +along with \fB\%putp\fP, +\fB\%tparm\fP, +and \fB\%tputs\fP. The latter were needed to support padding, -and handling functions such as \fBvidattr\fP -(which used more than the two parameters supported by \fBtgoto\fP). +and to handle capabilities accessed by functions such as \fB\%vidattr\fP +(which used more than the two parameters supported by \fB\%tgoto\fP). .PP SVr3 introduced the functions for switching between terminal -descriptions, e.g., \fBset_curterm\fP. -Some of that was incremental improvements to the SVr2 library: -.bP -The \fI\%TERMINAL\fP type definition was introduced in SVr3.01, -for the \fBterm\fP structure provided in SVr2. -.bP -The various global variables such as \fBboolnames\fP were mentioned +descriptions; +for example, +\fB\%set_curterm\fP. +Some changes reflected incremental improvements to the SVr2 library. +.bP +The +.I \%TERMINAL +type definition was introduced in SVr3.01, +for the +.I term +structure provided in SVr2. +.bP +Various global variables such as \fB\%boolnames\fP were mentioned in the programming manual at this point, -though the variables were provided in SVr2. +though the variables had been provided in SVr2. .PP -SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions. +SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions. .PP -There are other low-level functions declared in the \fIcurses\fP header files -on Unix systems, -but none were documented. -The functions marked \*(``obsolete\*('' remained in use -by the Unix \fBvi\fP(1) editor. +Other low-level functions are declared in the +.I curses +header files of Unix systems, +but none are documented. +Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's +\fIvi\fP(1) editor. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_initscr\fP(3X), diff --git a/man/infocmp.1m b/man/infocmp.1m index 11241bde..a6818944 100644 --- a/man/infocmp.1m +++ b/man/infocmp.1m @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: infocmp.1m,v 1.103 2023/12/23 16:08:25 tom Exp $ -.TH @INFOCMP@ 1M 2023-12-23 "ncurses 6.4" "User commands" +.\" $Id: infocmp.1m,v 1.104 2023/12/30 21:36:32 tom Exp $ +.TH @INFOCMP@ 1M 2023-12-30 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -87,7 +87,7 @@ x\ terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the \fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the binary file (\fBterm\fP) in a variety of formats. -In all cases, the boolean +In all cases, the Boolean fields will be printed first, followed by the numeric fields, followed by the string fields. .SS "Default Options" @@ -104,7 +104,7 @@ for the other terminal's \fIterminal-types\fP. If a capability is defined for only one of the terminals, the value returned depends on the type of the capability: .bP -\fBF\fP for missing boolean variables +\fBF\fP for missing Boolean variables .bP \fBNULL\fP for missing integer or string variables .PP diff --git a/man/man_db.renames.in b/man/man_db.renames.in index 7780b9d4..801892fd 100644 --- a/man/man_db.renames.in +++ b/man/man_db.renames.in @@ -26,7 +26,7 @@ # use or other dealings in this Software without prior written # # authorization. # ############################################################################## -# $Id: man_db.renames.in,v 1.66 2023/12/23 16:14:04 tom Exp $ +# $Id: man_db.renames.in,v 1.67 2023/12/30 21:34:11 tom Exp $ # Manual-page renamings for the man_db program # # Files: @@ -190,17 +190,23 @@ delscreen.3x delscreen.3ncurses derwin.3x derwin.3ncurses doupdate.3x doupdate.3ncurses endwin.3x endwin.3ncurses +extended_slk_color.3x extended_slk_color.3ncurses filter.3x filter.3ncurses flushinp.3x flushinp.3ncurses get_wch.3x get_wch.3ncurses +getattr.3x getattr.3ncurses getcchar.3x getcchar.3ncurses getch.3x getch.3ncurses +getwin.3x getwin.3ncurses +has_key.3x has_key.3ncurses idcok.3x idcok.3ncurses idlok.3x idlok.3ncurses immedok.3x immedok.3ncurses in_wch.3x in_wch.3ncurses inch.3x inch.3ncurses initscr.3x initscr.3ncurses +is_scrollok.3x is_scrollok.3ncurses +keyname.3x keyname.3ncurses keypad.3x keypad.3ncurses leaveok.3x leaveok.3ncurses longname.3x longname.3ncurses @@ -213,6 +219,7 @@ newterm.3x newterm.3ncurses newwin.3x newwin.3ncurses nodelay.3x nodelay.3ncurses notimeout.3x notimeout.3ncurses +putwin.3x putwin.3ncurses refresh.3x refresh.3ncurses reset_shell_mode.3x reset_shell_mode.3ncurses restartterm.3x restartterm.3ncurses @@ -221,6 +228,8 @@ set_curterm.3x set_curterm.3ncurses set_term.3x set_term.3nses setcchar.3x setcchar.3ncurses setupterm.3x setupterm.3ncurses +slk_attr.3x slk_attr.3ncurses +slk_color.3x slk_color.3ncurses slk_init.3x slk_init.3ncurses slk_touch.3x slk_touch.3ncurses start_color.3x start_color.3ncurses diff --git a/man/manhtml.aliases b/man/manhtml.aliases index dd099751..4baaaad3 100644 --- a/man/manhtml.aliases +++ b/man/manhtml.aliases @@ -1,4 +1,4 @@ -# $Id: manhtml.aliases,v 1.30 2023/12/23 21:21:06 tom Exp $ +# $Id: manhtml.aliases,v 1.31 2023/12/31 00:46:44 tom Exp $ #*************************************************************************** # Copyright 2019-2022,2023 Thomas E. Dickey * # Copyright 2013,2017 Free Software Foundation, Inc. * @@ -31,6 +31,7 @@ add_wch(3X) curs_add_wch(3X) addch(3X) curs_addch(3X) assume_default_colors(3X) default_colors(3X) +attr_get(3X) curs_attr(3X) attr_on(3X) curs_attr(3X) attron(3X) curs_attr(3X) baudrate(3X) curs_termattrs(3X) @@ -46,11 +47,14 @@ delay_output(3X) curs_util(3X) delscreen(3X) curs_initscr(3X) doupdate(3X) curs_refresh(3X) endwin(3X) curs_initscr(3X) +extended_slk_color(3X) curs_slk(3X) filter(3X) curs_util(3X) flushinp(3X) curs_util(3X) get_wch(3X) curs_get_wch(3X) getcchar(3X) curs_getcchar(3X) getch(3X) curs_getch(3X) +getwin(3X) curs_util(3X) +has_key(3X) curs_getch(3X) immedok(3X) curs_outopts(3X) in_wch(3X) curs_in_wch(3X) inch(3X) curs_inch(3X) @@ -66,6 +70,7 @@ mvcur(3X) curs_terminfo(3X) mvwin(3X) curs_window(3X) newterm(3X) curs_initscr(3X) newwin(3X) curs_window(3X) +putwin(3X) curs_util(3X) refresh(3X) curs_refresh(3X) reset_shell_mode(3X) curs_kernel(3X) restartterm(3X) curs_terminfo(3X) @@ -73,6 +78,8 @@ set_curterm(3X) curs_terminfo(3X) set_term(3X) curs_initscr(3X) setcchar(3X) curs_getcchar(3X) setupterm(3X) curs_terminfo(3X) +slk_attr(3X) curs_slk(3X) +slk_color(3X) curs_slk(3X) slk_init(3X) curs_slk(3X) slk_touch(3X) curs_slk(3X) start_color(3X) curs_color(3X) diff --git a/man/ncurses.3x b/man/ncurses.3x index ec0e39ba..9f937aaf 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: ncurses.3x,v 1.189 2023/12/23 16:32:37 tom Exp $ -.TH ncurses 3X 2023-12-23 "ncurses 6.4" "Library calls" +.\" $Id: ncurses.3x,v 1.192 2023/12/31 00:46:04 tom Exp $ +.TH ncurses 3X 2023-12-30 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -76,7 +76,7 @@ usage and interoperability with other \fIcurses\fP implementations. \*(``NOTES\*('' describes matters and caveats of which any user of the \fI\%ncurses\fP API should be aware, such as limitations on the size of an underlying integral type or the -availability of a preprocessor macro for a function +availability of a preprocessor macro exclusive of a function definition (which prevents its address from being taken). This section also describes implementation details that will be significant to the programmer but which are not standardized. @@ -358,7 +358,9 @@ is the library in its \*(``non-wide\*('' configuration, handling only eight-bit characters. It stores a character combined with attributes in a .I \%chtype -datum. +datum, +which is often an alias of +.I int. .IP Attributes alone (with no corresponding character) @@ -391,8 +393,8 @@ characters. corresponds to the non-wide configuration's .I \%chtype. It always a structure type, -because it stores more data than can fit into an integer. -A character code may be larger than can fit in a C +because it stores more data than fits into an integral type. +A character code may not be representable as a .I \%char, and moreover more than one character may occupy a cell (as with accent marks and other diacritics). @@ -405,9 +407,8 @@ Attributes and color data are stored in separate fields of the structure, not combined as in .I \%chtype. -.IP -Each cell -(row and column) +.PP +Each cell of a .I \%WINDOW is stored as a .I \%cchar_t. @@ -424,18 +425,19 @@ depends on two data types standardized by ISO C95. stores a wide character. Like .I \%chtype, -this may be an integer. +it may be an alias of +.I int. Depending on the character encoding, a wide character may be .I spacing, meaning that it occupies a character cell by itself and typically -accompanies cursor advancement on input, +accompanies cursor advancement, or -.I combining, +.I non-spacing, meaning that it occupies the same cell as a spacing character, is often regarded as a \*(``modifier\*('' of the base glyph with which it combines, -and typically does not advance the cursor on input. +and typically does not advance the cursor. .TP 9 .I \%wint_t can store a @@ -481,7 +483,7 @@ l l . \f(BIcurses\fP Function Name/Man Page _ COLOR_PAIR/\fBcurs_color\fP(3X) -PAIR_NUMBER/\fBcurs_attr\fP(3X) +PAIR_NUMBER/\fBcurs_color\fP(3X) add_wch/\fBcurs_add_wch\fP(3X) add_wchnstr/\fBcurs_add_wchstr\fP(3X) add_wchstr/\fBcurs_add_wchstr\fP(3X) @@ -946,44 +948,36 @@ additional sets of functions may be available: \fBcurs_trace\fP(3X) - curses debugging routines .RE .SH RETURN VALUE -Routines that return an integer return \fBERR\fP upon failure and an -integer value other than \fBERR\fP upon successful completion, unless -otherwise noted in the routine descriptions. -.PP -As a general rule, routines check for null pointers passed as parameters, -and handle this as an error. -.PP -All macros return the value of the \fBw\fP version, except \fBsetscrreg\fP, -\fBwsetscrreg\fP, \fBgetyx\fP, \fBgetbegyx\fP, and \fBgetmaxyx\fP. -The return values of -\fBsetscrreg\fP, -\fBwsetscrreg\fP, -\fBgetyx\fP, -\fBgetbegyx\fP, and -\fBgetmaxyx\fP are undefined (i.e., these should not be used as the -right-hand side of assignment statements). +Unless otherwise noted, +functions that return an integer return \fBOK\fP on success and +\fBERR\fP on failure. +Functions that return pointers return \fBNULL\fP on failure. +Typically, +.I \%ncurses +treats a null pointer passed as a function parameter as a failure. .PP Functions with a \*(``mv\*('' prefix first perform cursor movement using -\fB\%wmove\fP and return an error if the position is outside the window, +\fB\%wmove\fP and fail if the position is outside the window, or (for \*(``mvw\*('' functions) if the .I \%WINDOW pointer is null. -Most \*(``mv\*(''-prefixed functions -(except variadic functions such as \fB\%mvprintw\fP) -are provided both as macros and functions. -.PP -Routines that return pointers return \fBNULL\fP on error. .SH ENVIRONMENT The following environment symbols are useful for customizing the runtime behavior of the \fI\%ncurses\fP library. The most important ones have been already discussed in detail. .SS \fICC\fP command-character -When set, change occurrences of the command_character -(i.e., the \fBcmdch\fP capability) -of the loaded terminfo entries to the value of this variable. -Very few terminfo entries provide this feature. +When set, +change the +.B \%command_character +.RB ( \%cmdch ) +capability value of loaded +.I \%term\%info +entries to the value of this variable. +Very few +.I \%term\%info +entries provide this feature. .PP Because this name is also used in development environments to represent the C compiler's name, @@ -1516,19 +1510,20 @@ when only low-level functions are needed. Those functions are described in these pages: .RS .bP -\fBcurs_extend\fP(3X) \- miscellaneous curses extensions +\fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions .bP -\fBcurs_inopts\fP(3X) \- \fBcurses\fP input options +\fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options .bP -\fBcurs_kernel\fP(3X) \- low-level \fBcurses\fP routines +\fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines .bP -\fBcurs_termattrs\fP(3X) \- \fBcurses\fP environment query routines +\fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines .bP -\fBcurs_termcap\fP(3X) \- \fBcurses\fP emulation of termcap +\fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP .bP -\fBcurs_terminfo\fP(3X) \- \fBcurses\fP interfaces to terminfo database +\fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP +database .bP -\fBcurs_util\fP(3X) \- miscellaneous \fBcurses\fP utility routines +\fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines .RE .TP 5 \-\-with\-trace @@ -1544,64 +1539,138 @@ tab stop initialization database .I \*d compiled terminal capability database .SH NOTES -If standard output from a \fI\%ncurses\fP program is re-directed to -something which is not a tty, -screen updates will be directed to standard error. -This was an undocumented feature of AT&T System V Release 3 curses. +X/Open Curses permits most functions it specifies to be made available +as macros as well. +.\" See X/Open Curses Issue 4, Version 2, pp. 227-234. +.\" See X/Open Curses Issue 7, pp. 311-318. +\fI\%ncurses\fP does so +.bP +for functions that return values via their parameters, +.bP +to support obsolete features, +.bP +to reuse functions +(for example, +those that move the cursor before another operation), +and +.bP +a few special cases. +.PP +If the standard output file descriptor of an +.I \%ncurses +program is redirected to something that is not a terminal device, +the library writes screen updates to the standard error file descriptor. +This was an undocumented feature of SVr3. .PP See subsection \*(``Header files\*('' below regarding symbols exposed by inclusion of \fI\%curses.h\fP. .SH EXTENSIONS -The \fI\%ncurses\fP library can be compiled with an option -(\fB\-DUSE_GETCAP\fP) -that falls back to the old-style /etc/termcap file if the terminal setup code -cannot find a terminfo entry corresponding to \fITERM\fP. -Use of this feature is not recommended, -as it essentially includes an entire termcap compiler in the -\fI\%ncurses\fP startup code, -at significant cost in core and startup cycles. -.PP -The \fI\%ncurses\fP library includes facilities for capturing mouse -events on certain terminals -(including xterm). -See the \fBcurs_mouse\fP(3X) -manual page for details. -.PP -The \fI\%ncurses\fP library includes facilities for responding to window -resizing events, e.g., when running in an xterm. -See the \fBresizeterm\fP(3X) -and \fBwresize\fP(3X) manual pages for details. -In addition, the library may be configured with a \fBSIGWINCH\fP handler. -.PP -The \fI\%ncurses\fP library extends the fixed set of function key -capabilities of terminals by allowing the application designer to define -additional key sequences at runtime. -See the \fBdefine_key\fP(3X) -\fBkey_defined\fP(3X), -and \fBkeyok\fP(3X) manual pages for details. -.PP -The \fI\%ncurses\fP library can exploit the capabilities of terminals -which implement the ISO\-6429 SGR 39 and SGR 49 controls, +.I \%ncurses +enables an application to capture mouse events on certain terminals, +including +.I \%xterm; +see \fB\%curs_mouse\fP(3X). +.PP +.I \%ncurses +provides a means of responding to window resizing events, +as when running in a GUI terminal emulator application such as +.I \%xterm; +see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X). +.PP +.I \%ncurses +allows an application to query the terminal for the presence of a wide +variety of special keys; +see \fB\%has_key\fP(3X). +.PP +.I \%ncurses +extends the fixed set of function key capabilities specified by X/Open +Curses by allowing the application programmer to define additional key +sequences at runtime; +see +\fB\%define_key\fP(3X), +\fB\%key_defined\fP(3X), +and +\fB\%keyok\fP(3X). +.PP +.I \%ncurses +can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48 +SGR\ 39 and SGR\ 49 sequences, which allow an application to reset the terminal to its original foreground and background colors. -From the users' perspective, the application is able to draw colored -text on a background whose color is set independently, providing better -control over color contrasts. -See the \fBdefault_colors\fP(3X) manual page for details. -.PP -The \fI\%ncurses\fP library includes a function for directing -application output to a printer attached to the terminal device. -See the \fBcurs_print\fP(3X) manual page for details. +From a user's perspective, +the application is able to draw colored text on a background whose color +is set independently, +providing better control over color contrasts. +See \fB\%default_colors\fP(3X). +.PP +An +.I \%ncurses +application can choose to hide the internal details of +.I \%WINDOW +structures, +instead using accessor functions such as +\fB\%is_scrollok\fP(3X). +.PP +.I \%ncurses +enables an application to direct application output to a printer +attached to the terminal device; +see \fB\%curs_print\fP(3X). +.PP +.I \%ncurses +offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for +soft-label key lines, +and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X) +that can gather color information from them when many colors are +supported. +.PP +Some extensions are only available if +.I \%ncurses +is compiled to support them; +see section \*(``ALTERNATE CONFIGURATIONS\*('' above. +.bP +Rudimentary support for multi-threaded applications may be available; +see \fBcurs_threads\fP(3X). +.bP +Functions that ease the management of multiple screens can be exposed; +see \fBcurs_sp_funcs\fP(3X). +.bP +The compiler option +.B \%\-DUSE_GETCAP +causes the library to fall back to reading +.I \%/etc/termcap +if the terminal setup code cannot find a +.I \%term\%info +entry corresponding to +.I TERM. +Use of this feature is not recommended, +as it essentially includes an entire +.I termcap +compiler in the +.I \%ncurses +startup code, +at a cost in memory usage and application launch latency. +.PP +.I \%PDCurses +and NetBSD +.I curses +incorporate some +.I \%ncurses +extensions. +Individual man pages indicate where this is the case. .SH PORTABILITY -The \fI\%ncurses\fP library is intended to be BASE-level conformant with -XSI Curses. -The EXTENDED XSI Curses functionality -(including color support) is supported. -.PP -A small number of local differences -(that is, -individual differences between the XSI Curses and \fI\%ncurses\fP calls) -are described in \fBPORTABILITY\fP sections of the library man pages. +X/Open Curses defines two levels of conformance, +\*(``base\*('' and \*(``enhanced\*(''. +The latter includes several additional features, +such as wide-character and color support. +.I \%ncurses +intends base-level conformance with X/Open Curses, +and supports nearly all its enhanced features. +.\" XXX: What's missing? GBR counts untic(1), and that's all. +.PP +Differences between X/Open Curses and +.I \%ncurses +are documented in the \*(``PORTABILITY\*('' sections of applicable man +pages. .SS "Error Checking" In many cases, X/Open Curses is vague about error conditions, omitting some of the SVr4 documentation. @@ -1614,41 +1683,6 @@ 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. -.SS "Extensions Versus Portability" -Most of the extensions provided by \fI\%ncurses\fP have not been -standardized. -Some have been incorporated into other implementations, such as -PDCurses or NetBSD curses. -Here are a few to consider: -.bP -The routine \fBhas_key\fP is not part of XPG4, nor is it present in SVr4. -See the \fBcurs_getch\fP(3X) manual page for details. -.bP -The routine \fBslk_attr\fP is not part of XPG4, nor is it present in SVr4. -See the \fBcurs_slk\fP(3X) manual page for details. -.bP -The routines \fBgetmouse\fP, \fBmousemask\fP, \fBungetmouse\fP, -\fBmouseinterval\fP, and \fBwenclose\fP relating to mouse interfacing are not -part of XPG4, nor are they present in SVr4. -See the \fBcurs_mouse\fP(3X) manual page for details. -.bP -The routine \fBmcprint\fP was not present in any previous curses implementation. -See the \fBcurs_print\fP(3X) manual page for details. -.bP -The routine \fBwresize\fP is not part of XPG4, nor is it present in SVr4. -See the \fBwresize\fP(3X) manual page for details. -.bP -The \fI\%WINDOW\fP structure's internal details can be hidden from application -programs. -See \fBcurs_opaque\fP(3X) for the discussion of \fBis_scrollok\fP, etc. -.bP -This implementation can be configured to provide rudimentary support -for multi-threaded applications. -See \fBcurs_threads\fP(3X) for details. -.bP -This implementation can also be configured to provide a set of functions which -improve the ability to manage multiple screens. -See \fBcurs_sp_funcs\fP(3X) for details. .SS "Padding Differences" In historic curses versions, delays embedded in the capabilities \fBcr\fP, \fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay diff --git a/man/scr_dump.5 b/man/scr_dump.5 index d976fae8..505fca52 100644 --- a/man/scr_dump.5 +++ b/man/scr_dump.5 @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp $ -.TH scr_dump 5 2023-12-23 "ncurses 6.4" "File formats" +.\" $Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp $ +.TH scr_dump 5 2023-12-30 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -47,8 +47,7 @@ .SH NAME scr_dump \- \fIcurses\fR screen dump -.SH SYNOPSIS -.B scr_dump +.\"SH SYNOPSIS .SH DESCRIPTION The curses library provides applications with the ability to write the contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP, @@ -131,51 +130,46 @@ and adjust the \fI\%WINDOW\fP structure which was read back into memory. This is similar to Unix System\ V, but does not write a \*(``magic number\*('' to identify the file format. .SH PORTABILITY -There is no standard format for \fBputwin\fP. -This section gives a brief description of the existing formats. +There is no standard format for +.I curses +screen dumps. +A brief survey of the existing implementations follows. .SS "X/Open Curses" -Refer to \fIX/Open Curses, Issue 7\fP (2009). -.PP -X/Open's documentation for \fIenhanced curses\fP says only: +X/Open Curses, Issue 7 specifies little. +It says +(boldface emphasis added) .RS 3 .PP -The \fBgetwin(\ ) \fPfunction reads window-related data -stored in the file by \fIputwin(\ )\fP. -The function -then creates and initializes a new window using that data. +\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in +the file by \fI\%putwin()\fP. +The function then creates and initializes a new window using that data. .PP -The \fBputwin(\ )\fP function writes all data associated -with \fIwin\fP into the \fI\%stdio\fP(3) stream to which \fIfilep\fP -points, using an \fBunspecified format\fP. -This information can be retrieved later using \fBgetwin(\ )\fP. +The \fI\%putwin()\fP function writes all data associated with \fIwin\fP +into the \fI\%stdio\fP stream to which \fIfilep\fP points, +using an \fBunspecified format\fP. +This information can be retrieved later using \fI\%getwin()\fP.\*('' .RE .PP In the mid-1990s when the X/Open Curses document was written, -there were still systems using older, less capable curses libraries -(aside from the BSD curses library which was not relevant to X/Open -because it did not meet the criteria for \fIbase curses\fP). -The document explained the term \*(``enhanced\*('' as follows: -.RS 3 -.bP -Shading is used to identify \fIX/Open Enhanced Curses\fP material, -relating to interfaces included to provide enhanced capabilities -for applications originally written to be compiled on systems -based on the Unix operating system. -Therefore, the features described may not be present on systems -that conform to \fBXPG4 or to earlier XPG releases\fP. -The relevant reference pages may provide additional -or more specific portability warnings about use of the material. -.RE -.PP -In the foregoing, emphasis was added to \fBunspecified format\fP -and to \fBXPG4 or to earlier XPG releases\fP, -for clarity. -.SS "Unix System V" -Unix System\ V curses identified the file format by writing a -\*(``magic number\*('' at the beginning of the dump. +there were still System\ V systems using older, +less capable +.I curses +libraries. +BSD +.I curses +was not relevant to X/Open because it did not meet the criteria +for base-level conformance; +see \fB\%ncurses\fP(3X). +.SS "System V" +System\ V +.I curses +identified the file format by writing a \*(``magic number\*('' at the +beginning of the dump. The \fI\%WINDOW\fP data and the lines of text follow, all in binary form. .PP -The Solaris curses source has these definitions: +Solaris +.I curses +has the following definitions. .PP .RS 4 .EX @@ -190,9 +184,12 @@ The Solaris curses source has these definitions: .PP That is, the feature was likely introduced in SVr2 (1984), and improved in SVr3 (1987). -The Solaris curses source has no magic number for SVr4 (1989). -Other operating systems (AIX and HP-UX) use a magic number which would -correspond to this definition: +Solaris +.I curses +has no magic number for SVr4 (1989). +Other System\ V operating systems +(AIX and HP-UX) +use a magic number that would correspond to the following. .PP .RS 4 .EX @@ -202,8 +199,8 @@ correspond to this definition: .RE .PP That octal number in bytes is 001, 035. -Because most Unix vendors use big-endian hardware, -the magic number is written with the high-order byte first, e.g., +Because most Unix vendors at the time used big-endian hardware, +the magic number is written with the high-order byte first. .PP .RS 4 .EX @@ -211,16 +208,21 @@ the magic number is written with the high-order byte first, e.g., .EE .RE .PP -After the magic number, the \fI\%WINDOW\fP structure and line-data are -written in binary format. -While the magic number used by the Unix systems can be seen using \fBod\fP(1), -none of the Unix systems documents the format used for screen-dumps. +After the magic number, +the \fI\%WINDOW\fP structure and line data are written in binary format. +While the magic number used by these systems can be observed with +\fIod\fP(1), +none of them documents the format used for screen dumps. .PP -The Unix systems do not use identical formats. -While collecting information for for this manual page, -the \fIsavescreen\fP test-program -produced dumps of different size -(all on 64-bit hardware, on 40x80 screens): +Nor do they use an identical format, +even with the System\ V family. +The +.I \%ncurses +.I \%savescreen +test program was used to collect information for this manual page. +It produced dumps of different size +(all on 64-bit hardware, +on 40x80 screens): .bP AIX (51817 bytes) .bP @@ -230,31 +232,49 @@ Solaris 10 (13273 bytes) .bP \fI\%ncurses\fP5 (12888 bytes) .SS Solaris -As noted above, Solaris curses has no magic number corresponding -to SVr4 curses. -This is odd since Solaris was the first operating system -to pass the SVr4 guidelines. -Solaris has two versions of curses: +As noted above, +Solaris +.I curses +has no magic number corresponding to SVr4 +.I curses. +This is odd, +since Solaris was the first operating system to meet the SVr4 +guidelines. +Solaris furthermore supplies two versions of +.I curses. .bP -The default curses library uses the SVr3 magic number. +The default +.I curses +library uses the SVr3 magic number. .bP -There is an alternate curses library in \fB/usr/xpg4\fP. -This uses a textual format with no magic number. +An alternate +.I curses +library +(which we term +.I \%xcurses), +available in +.I /usr/xpg4, +uses a textual format with no magic number. .IP -According to the copyright notice, the \fIxpg4\fP Solaris curses library was -developed by MKS (Mortice Kern Systems) from 1990 to 1995. +According to its copyright notice, +this +.I \%xcurses +library was developed by MKS +(Mortice Kern Systems) from 1990 to 1995. .IP -Like ncurses6, there is a file-header with parameters. -Unlike ncurses6, the contents of the window are written piecemeal, -with coordinates and attributes for each chunk of text rather -than writing the whole window from top to bottom. +Like ncurses6, +it includes a header with parameters. +Unlike ncurses6, +the contents of the window are written piecemeal, +with coordinates and attributes for each chunk of text rather than +writing the whole window from top to bottom. .SS PDCurses -PDCurses added support for screen dumps in version 2.7 (2005). -Like Unix System\ V and ncurses5, +.I \%PDCurses +added support for screen dumps in version 2.7 (2005). +Like System\ V and ncurses5, it writes the \fI\%WINDOW\fP structure in binary, but begins the file with its three-byte identifier \*(``PDC\*('', -followed by a one-byte version, -e.g., +followed by a single-byte version number. .PP .RS 4 .EX @@ -262,23 +282,33 @@ e.g., .EE .RE .SS NetBSD -As of April 2017, NetBSD curses does -not support \fBscr_dump\fP and \fBscr_restore\fP -(or \fBscr_init\fP, \fBscr_set\fP), -although it has \fBputwin\fP and \fBgetwin\fP. +As of April 2017, +NetBSD +.I curses +does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP +(or \fB\%scr_init\fP, +\fB\%scr_set\fP), +although it has \fB\%putwin\fP and \fB\%getwin\fP. .PP -Like ncurses5, NetBSD \fBputwin\fP does not identify its dumps with a -useful magic number. +Like ncurses5, +NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic +number. It writes .bP -the curses shared library major and minor versions -as the first two bytes (e.g., 7 and 1), +the +.I curses +shared library major and minor versions as the first two bytes +(for example, +7 and 1), .bP followed by a binary dump of the \fI\%WINDOW\fP, .bP -some data for wide-characters referenced by the \fI\%WINDOW\fP structure, and +some data for wide characters referenced by the \fI\%WINDOW\fP +structure, +and .bP -finally, lines as done by other implementations. +finally, +lines as done by other implementations. .SH EXAMPLES Given a simple program which writes text to the screen (and for the sake of example, limiting the screen-size to 10x20): diff --git a/man/term.5 b/man/term.5 index ede2eb1c..79aa2164 100644 --- a/man/term.5 +++ b/man/term.5 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp $ -.TH term 5 2023-12-23 "ncurses 6.4" "File formats" +.\" $Id: term.5,v 1.70 2023/12/30 21:36:32 tom Exp $ +.TH term 5 2023-12-30 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -111,7 +111,7 @@ a) \fIheader\fP, .TP 3 b) \fIterminal names\fP, .TP 3 -c) \fIboolean flags\fP, +c) \fIBoolean flags\fP, .TP 3 d) \fInumbers\fP, .TP 3 @@ -130,7 +130,7 @@ These integers are .TP 5 (2) the size, in bytes, of the \fIterminal names\fP section; .TP 5 -(3) the number of bytes in the \fIboolean flags\fP section; +(3) the number of bytes in the \fIBoolean flags\fP section; .TP 5 (4) the number of short integers in the \fInumbers\fP section; .TP 5 @@ -140,7 +140,7 @@ These integers are .RE .PP The capabilities in the -\fIboolean flags\fP, +\fIBoolean flags\fP, \fInumbers\fP, and \fIstrings\fP sections are in the same order as the file . @@ -168,14 +168,14 @@ If a capability is absent from this terminal, .IP The integer value \-1 is represented by two bytes 0377, 0377. .br -Absent boolean values are represented by the byte 0 (false). +Absent Boolean values are represented by the byte 0 (false). .bP If a capability has been canceled from this terminal, @TIC@ stores a \-2 in the corresponding table. .IP The integer value \-2 is represented by two bytes 0377, 0376. .br -The boolean value \-2 is represented by the byte 0376. +The Boolean value \-2 is represented by the byte 0376. .br .bP Other negative values are illegal. @@ -187,11 +187,11 @@ separated by the \*(``|\*('' character. The \fIterminal names\fP section is terminated with an \s-1ASCII NUL\s+1 character. .PP -The \fIboolean flags\fP section has one byte for each flag. +The \fIBoolean flags\fP section has one byte for each flag. Boolean capabilities are either 1 or 0 (true or false) according to whether the terminal supports the given capability or not. .PP -Between the \fIboolean flags\fP section and the \fInumber\fP section, +Between the \fIBoolean flags\fP section and the \fInumber\fP section, a null byte will be inserted, if necessary, to ensure that the \fInumber\fP section begins on an even byte This is a relic of the PDP\-11's word-addressed architecture, @@ -199,7 +199,7 @@ originally designed to avoid traps induced by addressing a word on an odd byte boundary. All short integers are aligned on a short word boundary. .PP -The \fInumbers\fP section is similar to the \fIboolean flags\fP section. +The \fInumbers\fP section is similar to the \fIBoolean flags\fP section. Each capability takes up two bytes, and is stored as a little-endian short integer. .PP @@ -219,7 +219,7 @@ stored intact in uninterpreted form. The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. -Each system uses a predefined set of boolean, number or string capabilities. +Each system uses a predefined set of Boolean, number or string capabilities. .PP The \fI\%ncurses\fP libraries and applications support extended terminfo binary format, @@ -236,7 +236,7 @@ First, it reads the extended header (5 short integers): .RS 5 .TP 5 (1) -count of extended boolean capabilities +count of extended Boolean capabilities .TP 5 (2) count of extended numeric capabilities @@ -261,7 +261,7 @@ capabilities in the same order as the header information. .PP The extended string table contains values for string capabilities. After the end of these values, it contains the names for each of -the extended capabilities in order, e.g., booleans, then numbers and +the extended capabilities in order, e.g., Booleans, then numbers and finally strings. .PP By storing terminal descriptions in this way, @@ -314,7 +314,7 @@ The routine must be prepared for both possibilities \- this is why the numbers and sizes are included. Also, new capabilities must always be added at the end of the lists -of boolean, number, and string capabilities. +of Boolean, number, and string capabilities. .SS "Binary Format" X/Open Curses does not specify a format for the terminfo database. System V curses used a directory-tree of binary files, diff --git a/man/terminfo.head b/man/terminfo.head index 712da62c..ae3d7e54 100644 --- a/man/terminfo.head +++ b/man/terminfo.head @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp $ -.TH terminfo 5 2023-12-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" +.\" $Id: terminfo.head,v 1.60 2023/12/30 22:21:45 tom Exp $ +.TH terminfo 5 2023-12-30 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -163,10 +163,10 @@ or methods for exercising the terminal's features. .PP After the first field (giving the name(s) of the terminal entry), there should be one or more \fIcapability\fP fields. -These are boolean, numeric or string names with corresponding values: +These are Boolean, numeric or string names with corresponding values: .bP Boolean capabilities are true when present, false when absent. -There is no explicit value for boolean capabilities. +There is no explicit value for Boolean capabilities. .bP Numeric capabilities have a \*(``#\*('' following the name, then an unsigned decimal integer value. diff --git a/man/terminfo.tail b/man/terminfo.tail index dc527831..bc761404 100644 --- a/man/terminfo.tail +++ b/man/terminfo.tail @@ -27,7 +27,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp $ +.\" $Id: terminfo.tail,v 1.141 2023/12/30 21:36:32 tom Exp $ .ps +1 .SS "User-Defined Capabilities" . @@ -46,7 +46,7 @@ When \fB\-x\fP is set, \fB@TIC@\fP treats unknown capabilities as user-defined. That is, if \fB@TIC@\fP encounters a capability name which it does not recognize, -it infers its type (boolean, number or string) from the syntax +it infers its type (Boolean, number or string) from the syntax and makes an extended table entry for that capability. The \fBuse_extended_names\fP(3X) function makes this information conditionally available to applications. @@ -56,7 +56,7 @@ behavior to applications: User-defined capability strings whose name begins with \*(``k\*('' are treated as function keys. .bP -The types (boolean, number, string) determined by \fB@TIC@\fP +The types (Boolean, number, string) determined by \fB@TIC@\fP can be inferred by successful calls on \fBtigetflag\fP, etc. .bP If the capability name happens to be two characters, @@ -68,7 +68,7 @@ in practice it has been limited to the capabilities defined by terminfo implementations. As a rule, user-defined capabilities intended for use by termcap applications should -be limited to booleans and numbers to avoid running past the 1023 byte +be limited to Booleans and numbers to avoid running past the 1023 byte limit assumed by termcap implementations and their applications. In particular, providing extended sets of function keys (past the 60 numbered keys and the handful of special named keys) is best done using @@ -883,7 +883,7 @@ or on many terminals without a true insert/delete line, and is often faster even on terminals with those features. .PP -The boolean \fBnon_dest_scroll_region\fP should be set if each scrolling +The Boolean \fBnon_dest_scroll_region\fP should be set if each scrolling window is effectively a view port on a screen-sized canvas. To test for this capability, create a scrolling region in the middle of the screen, @@ -1536,7 +1536,7 @@ capability \fBwsl\fP. .PP A command to erase or blank the status line may be specified as \fBdsl\fP. .PP -The boolean capability \fBeslok\fP specifies that escape sequences, tabs, +The Boolean capability \fBeslok\fP specifies that escape sequences, tabs, etc., work ordinarily in the status line. .PP The \fI\%ncurses\fP implementation does not yet use any of these @@ -1648,7 +1648,7 @@ The \fBoc\fP string resets all colors or color pairs to their default values for the terminal. Some terminals (including many PC terminal emulators) erase screen areas with the current background color rather -than the power-up default background; these should have the boolean capability +than the power-up default background; these should have the Boolean capability \fBbce\fP. .PP While the curses library works with \fIcolor pairs\fP @@ -1730,7 +1730,7 @@ take a color number (0 to \fBcolors\fP \- 1)and three more parameters which describe the color. These three parameters default to being interpreted as RGB (Red, Green, Blue) values. -If the boolean capability \fBhls\fP is present, +If the Boolean capability \fBhls\fP is present, they are instead as HLS (Hue, Lightness, Saturation) indices. The ranges are terminal-dependent. diff --git a/man/tic.1m b/man/tic.1m index 7471ad8b..b1476823 100644 --- a/man/tic.1m +++ b/man/tic.1m @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp $ -.TH @TIC@ 1M 2023-12-23 "ncurses 6.4" "User commands" +.\" $Id: tic.1m,v 1.106 2023/12/30 21:36:32 tom Exp $ +.TH @TIC@ 1M 2023-12-30 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -398,7 +398,7 @@ If it is omitted, it defaults to 60. \fB\-x\fP Treat unknown capabilities as user-defined (see \fBuser_caps\fP(5)). That is, if you supply a capability name which \fB@TIC@\fP does not recognize, -it will infer its type (boolean, number or string) from the syntax and +it will infer its type (Boolean, number or string) from the syntax and make an extended table entry for that. User-defined capability strings whose name begins with \*(``k\*('' are treated as function keys. diff --git a/man/tput.1 b/man/tput.1 index e1e9d9d4..48ad00c9 100644 --- a/man/tput.1 +++ b/man/tput.1 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp $ -.TH @TPUT@ 1 2023-12-23 "ncurses 6.4" "User commands" +.\" $Id: tput.1,v 1.97 2023/12/31 00:16:41 tom Exp $ +.TH @TPUT@ 1 2023-12-30 "ncurses 6.4" "User commands" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -51,7 +51,8 @@ \fB\%reset\fP \- initialize a terminal or query \fI\%term\%info\fP database .SH SYNOPSIS -\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fIcap-code\fP [\fIparameter\fP .\|.\|.] +\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] +{\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|. .PP \fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP .PP @@ -249,6 +250,18 @@ strings are, the \fIinitialization\fP strings will be output. Otherwise, \fBreset\fP acts identically to \fBinit\fP. .TP .B longname +A terminfo entry begins with one or more names by which an +application can refer to the entry, +before the list of terminal capabilities. +The names are separated by \*(``|\*('' characters. +X/Open states that the last name is the \*(``long name\*('' +and also that it may include blanks. +.IP +\fB\%@TIC@\fP warns if the last name does not include blanks, +to accommodate old terminfo entries which treated +the long name as an optional feature. +The long name is often referred to as the description field. +.IP If the terminal database is present and an entry for the user's terminal exists (see @@ -259,7 +272,7 @@ above), (or \*(``long name\*('') to the standard output, without a trailing newline. -See \fBterm\fP(5). +See \fB\%term\%info\fP(5). .SS Aliases \fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP commands specially: @@ -645,12 +658,12 @@ moves the cursor to position and turns on bold (extra bright) mode. -.IP -The same sequence of commands can be combined using the OpenBSD feature: -.IP -.EX -$ \fB@TPUT@ \fBclear\fP \fBcup 10 10\fP \fBbold\fP -.EE +.TP 5 +.B @TPUT@ clear cup 10 10 bold +Perform the same actions as the foregoing +.RB \%\[lq] @TPUT@ +.BR \-S \[rq] +example. .SH SEE ALSO \fB\%@CLEAR@\fP(1), \fB\%stty\fP(1), diff --git a/man/user_caps.5 b/man/user_caps.5 index 978edbc4..ac4da9f7 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp $ -.TH user_caps 5 2023-12-23 "ncurses 6.4" "File formats" +.\" $Id: user_caps.5,v 1.44 2023/12/30 21:36:32 tom Exp $ +.TH user_caps 5 2023-12-30 "ncurses 6.4" "File formats" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -61,7 +61,7 @@ and extended in stages through SVr4 (1989), and standardized in the Single Unix Specification beginning in 1995. .PP Most of the \fIextensions\fP in this fixed repertoire were additions -to the tables of boolean, numeric and string capabilities. +to the tables of Boolean, numeric and string capabilities. Rather than change the meaning of an existing capability, a new name was added. The terminfo database uses a binary format; binary compatibility was ensured by using a header which gave the number of items in the @@ -192,7 +192,7 @@ While the terminfo database may have other extensions, .RS 3 .TP 3 AX -\fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49 +\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49 by resetting the foreground and background color, respectively, to the default. .IP This is a feature recognized by the \fBscreen\fP program as well. @@ -205,7 +205,7 @@ the terminal. The command \*(``\fBtput clear\fP\*('' does the same thing. .TP 3 NQ -\fIboolean\fP, +\fIBoolean\fP, used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP capabilities in user6 through user9 (u6, u7, u8 and u9) @@ -213,7 +213,7 @@ which tell how to query the terminal's cursor position and its device attributes. .TP 3 RGB -\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, +\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, used to assert that the \fBset_a_foreground\fP and \fBset_a_background\fP capabilities correspond to \fIdirect colors\fP, @@ -225,7 +225,7 @@ to initialize colors using \fBinit_color\fP. The capability type determines the values which \fI\%ncurses\fP sees: .RS 3 .TP 3 -\fIboolean\fP +\fIBoolean\fP implies that the number of bits for red, green and blue are the same. Using the maximum number of colors, \fI\%ncurses\fP adds two, @@ -239,7 +239,7 @@ of three, the blue (and green) components lose in comparison to red. \fInumber\fP tells \fI\%ncurses\fP what result to add to red, green and blue. If \fI\%ncurses\fP runs out of bits, -blue (and green) lose just as in the \fIboolean\fP case. +blue (and green) lose just as in the \fIBoolean\fP case. .TP 3 \fIstring\fP explicitly list the number of bits used for red, green and blue components diff --git a/misc/terminfo.src b/misc/terminfo.src index 9f9cb545..fc14735e 100644 --- a/misc/terminfo.src +++ b/misc/terminfo.src @@ -6,8 +6,8 @@ # Report bugs and new terminal descriptions to # bug-ncurses@gnu.org # -# $Revision: 1.1085 $ -# $Date: 2023/12/16 13:48:44 $ +# $Revision: 1.1092 $ +# $Date: 2023/12/30 18:05:02 $ # # The original header is preserved below for reference. It is noted that there # is a "newer" version which differs in some cosmetic details (but actually @@ -4632,6 +4632,78 @@ ms-vt100+|vt100+|windows XP VT100+ (sic), ms-vt-utf8|vt-utf8|UTF-8 flavor of VT100+, use=ms-vt100+, +# VT-UTF-8 and VT100+ Protocols +# https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-vuvp/969416c0-ccd6-4a75-a9b3-597d7713845b +# +# This Microsoft "protocol" adapted the aixterm 16-color feature from xterm's +# documentation in 2015, as seen in successive revisions: +# +# 2013/07/22 has 8 colors +# 2015/10/16 has 16 colors using SGR 90-97, 100-107 as well as SGR 24 and 27, +# adds "informative" reference to xterm's ctlseqs +# +# The cnorm/civis definitions added in 2015 are unrelated to any standard. +ms-vt100-16color|VT-UTF-8 and VT100+, + civis=\E[?h, cnorm=\E[?l, rmso=\E[27m, rmul=\E[24m, + use=ibm+16color, use=ms-vt100+, + +# Based on +# https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences +# We use this scheme to map function keys +# terminfo modifier code keys +# kf13-kf24 shift 2 F1 to F12 +# kf25-kf36 alt 3 F1 to F12 +# kf37-kf48 control 4 F1 to F12 +# kf49-kf60 ctrl-alt 7 F1 to F12 +# +# Unclear: smam and rmam implemented? +# Unclear: rmkx, smkx, rmir, smir - irrelevant? +# +# TD: +# + According to tack, tbc and cbt fail. +# + The line-drawing (acsc) does not work in telnet or ssh. I added the +# U8 extension to tell ncurses to use UTF-8 for line-drawing (when the +# locale uses UTF-8). That won't work for telnet (which uses ASCII), +# but seems to work for OpenSSH's ssh. I set the codepage to 65001, +# of course. +# + Function keys... do not work consistently in telnet and ssh. With +# telnet, kf1-kf4 are \EOP to \EOS, and kf5-kf12 match the terminfo. +# But with ssh, it's entirely different (reminds me of rxvt). +winconsole|Windows 10 new console, + am, km, mir, msgr, xenl, AX, + ncv@, U8#1, + acsc=++\,\,--..00``aaffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxy + yzz~~, + bel=^G, blink@, cr=\r, ech=\E[%p1%dX, el1=\E[0K, ich1@, ind=\n, + invis@, is1=\E[!p, kdch1=\E[3~, kend=\E[4~, kf1=\E[11~, + kf10=\E[21~, kf11=\E[23~, kf12=\E[24~, kf13=\E[11;2~, + kf14=\E[12;2~, kf15=\E[13;2~, kf16=\E[14;2~, + kf17=\E[15;2~, kf18=\E[17;2~, kf19=\E[18;2~, kf2=\E[12~, + kf20=\E[19;2~, kf21=\E[20;2~, kf22=\E[21;2~, + kf23=\E[24;2~, kf24=\E[25;2~, kf25=\E[11;3~, + kf26=\E[12;3~, kf27=\E[13;3~, kf28=\E[14;3~, + kf29=\E[15;3~, kf3=\E[13~, kf30=\E[17;3~, kf31=\E[18;3~, + kf32=\E[19;3~, kf33=\E[20;3~, kf34=\E[21;3~, + kf35=\E[24;3~, kf36=\E[25;3~, kf37=\E[11;4~, + kf38=\E[12;4~, kf39=\E[13;4~, kf4=\E[14~, kf40=\E[14;4~, + kf41=\E[15;4~, kf42=\E[17;4~, kf43=\E[18;4~, + kf44=\E[19;4~, kf45=\E[20;4~, kf46=\E[21;4~, + kf47=\E[24;4~, kf48=\E[25;4~, kf49=\E[11;7~, kf5=\E[15~, + kf50=\E[12;7~, kf51=\E[13;7~, kf52=\E[14;7~, + kf53=\E[15;7~, kf54=\E[17;7~, kf55=\E[18;7~, + kf56=\E[19;7~, kf57=\E[20;7~, kf58=\E[21;7~, + kf59=\E[24;7~, kf6=\E[17~, kf60=\E[25;7~, kf7=\E[18~, + kf8=\E[19~, kf9=\E[20~, khome=\E[1~, kich1=\E[2~, + knp=\E[6~, kpp=\E[5~, nel=\r\n, ri=\E[T, rmacs=\E(B, rmir@, + rmpch@, rs1=\E[!p, + sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;m%?%p9%t + \E(0%e\E(B%;, + sgr0=\E[0m\E(B, smacs=\E(0, smir@, smpch@, use=ansi+arrows, + use=ansi+csr, use=ansi+cup, use=ansi+erase, use=ansi+idc, + use=ansi+idl, use=ecma+index, use=ansi+inittabs, + use=ansi+local, use=ecma+sgr, use=ecma+color, + use=vt220+cvis, + # Windows Terminal (Preview) # https://github.com/microsoft/terminal # @@ -6035,6 +6107,23 @@ xterm-pcolor|xterm with color used for highlights and status line, %t;7;31%;%?%p3%t;7;34%;m, smso=\E[7;31m, smul=\E[4;42m, use=xterm+sl, use=xterm-r6, +# This was mentioned +# http://unix.stackexchange.com/questions/119/colors-in-man-pages +# pointing to +# http://nion.modprobe.de/blog/archives/569-colored-manpages.html +# (blog posting by Nico Golde, June 24 2007) +# archive: +# https://web-beta.archive.org/web/20070921042430/http://nion.modprobe.de/mostlike.txt +# The comment hints where it started, but there are differences: +# Reconstructed via infocmp from file: /usr/share/terminfo/x/xterm-pcolor +mostlike|manpages with color looking like most, + OTbs@, + bold=\E[1m\E[31m, + is2=\E7\E[r\E[m\E[?7h\E[?1;3;4;6l\E[4l\E8\E>, kbs=^H, + meml@, memu@, rev=\E[7m\E[34m, + rs2=\E7\E[r\E8\E[m\E[?7h\E[?1;3;4;6l\E[4l\E>, sgr@, + smso=\E[1;30m\E[47m, smul=\E[32m, TS@, use=xterm-pcolor, + # This describes the capabilities of color_xterm, an xterm variant from # before ECMA-48 color support was folded into the main-line xterm release. # This entry is straight from color_xterm's maintainer. @@ -7806,6 +7895,13 @@ alacritty+common|base fragment for alacritty, use=xterm+sl-twm, use=ecma+italics, use=xterm+pce2, use=xterm+pcc2, use=xterm+pcf2, use=bracketed+paste, +# https://github.com/raphamorim/rio +# derived from alacritty +rio|fork of alacritty, + use=alacritty, +rio-direct|fork of alacritty, + use=alacritty-direct, + #### Kitty # https://github.com/kovidgoyal/kitty # Project started in 2016/10 (see alacritty), but is a Python script rather @@ -8069,6 +8165,149 @@ domterm|DomTerm web client, use=xterm+pcfkeys, use=xterm-basic, use=bracketed+paste, +######## Miscellaneous + +#### WezTerm +# https://wezfurlong.org/wezterm/ +# https://github.com/wez/wezterm +# +# which says: +# "wezterm is a terminal emulator with support for modern features +# such as fonts with ligatures, hyperlinks, tabs and multiple windows." +# +# wezterm-20230712_072601_f4abf8fd-1.fedora38.x86_64 +# tested with MacOS and Fedora 38/39. +# +# General: +# + written in Rust. +# + initial screensize is odd, i.e., 81x24 +# provides no visual feedback on resize +# ignores "resize -s" +# manual resize and then running resize got off-by-one adjustment +# + leaves debris (unerased cells) when switching between normal/alternate +# screens. +# + sets TERM=xterm-256color +# tack: +# + misplaced message in "am" screen +# + fails xenl (should be false) +# + cvvis is same as cnorm, block +# + has blink and dim +# + in bce test, blue isn't really blue but some pale purple +# + modified keys mostly work, but its tab control interferes with some +# + rmm/smm don't work (always uses escape-prefix) +# wraptest: +# + poor (doesn't copy anyone, most of the results are wrong) +# vttest: +# + DA is VT5xx with sixel, selective erase, user windows, color +# + DA2 is VT220 version 277 +# + only the VT100 character set works, contrary to DA/DA2. +# + no NRCS, either +# + double-sized character work, with some debris +# + doesn't switch between 80/132 columns. +# + numeric keypad ANSI application mode escapes don't work. +# + numeric keypad ANSI mode misses "0", ".", "," +# + uses PC-style editing keypad \E[H and \E[F for Find and Select +# + no VT52 +# + DECSED selective erase doesn't work +# + SRM doesn't work +# + 8-bit controls don't work +# + DECNCSM doesn't work +# + most DECRQSS do not work (DECSCL, DECSTBM, DECSLRM respond) +# + DECRQM/DECRPM don't work (most reply permanently reset) +# + DECLRMM responds to DECRPM, but VT420 rectangle tests do not work. +# Some of the left/right margin tests work with the cursor-movement screen, +# but DECFI/DECBI do not work. The other cursor-movement tests are buggy. +# + implements ECMA-48 cursor movement, but not SL/SR or protected area +# + implements xterm normal, any-event and button-event mouse, none of the rest +# + reports window size, none of the other window reports +wezterm|Wez's Terminal Emulator, + km@, xenl@, + cvvis@, rmkx=\E[?1l, rmm@, smkx=\E[?1h, smm@, + use=xterm-256color, + +#### Contour +# https://github.com/contour-terminal/contour +# +# "Modern C++ Terminal Emulator" +# Contour is a modern and actually fast, modal, virtual terminal emulator, +# for everyday use. It is aiming for power users with a modern feature mindset. +# +# That is three occurrences of "modern" too many -TD +# +# MacOS +# - cannot run, because the package is not signed. +# +# Fedora rawhide +# contour-terminal-0.3.12.262-6.fc39.x86_64 +# - dumps core, cannot test +# +# Fedora 39 +# contour-terminal-0.4.0.6245-1.fc38.x86_64 +# - starts but doesn't display +# +# Fedora 38 +# contour-terminal-0.4.0.6245-1.fc38.x86_64 +# - starts but doesn't display +# contour-terminal-0.3.12.262-1.fc38.x86_64 +# + testable (see below) +# + initial screensize 62x23, no visual feedback on resize, no "resize -s" +# +# Sets TERM=contour (which is preferable to xterm). +# +# tack: +# + cvvis is same as cnorm, "|" +# + sitm/ritm don't work +# + rmm/smm don't work (always uses escape, but terminfo defines km) +# + initp interchanges red/blue (bug in tack?) +# + modified F1-F4 are wrong, sending SS3 with modifier numbers +# + shifted editing-keypad doesn't send anything +# + meta key doesn't work +# + status-line works (based on xterm, including window-resizing) +# + dots don't line up for home test +# +# wraptest: +# + poor 7/25 differences from xterm (perhaps copying iTerm2) +# +# vttest: +# + hangs in menu 1, etc., when it tries to resize +# +# infocmp vs xterm-256color +# + missing XM/xm +# + rmcup/smcup doesn't use title-stack (but is implemented) +# + doesn't use SGR mouse (but is implemented) +# + sgr doesn't define dim, but dim capability is in terminfo (implemented) +# +# Developer's terminfo (compiled-in) uses some extensions. +contour|contour-latest|Contour Terminal Emulator, + am, bce, eslok, hs, km, mc5i, mir, msgr, npc, xenl, xvpa, + cols#80, it#8, lines#24, pairs#0x7fff, + acsc=``aaffggiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~, + bel=^G, bold=\E[1m, cbt=\E[Z, clear=\E[H\E[2J, cr=\r, + cub=\E[%p1%dD, cub1=^H, cud=\E[%p1%dB, cud1=\n, + cuf=\E[%p1%dC, cuf1=\E[C, cuu=\E[%p1%dA, cuu1=\E[A, + dim=\E[2m, dsl=\E[$~, ech=\E[%p1%dX, el1=\E[1K, + flash=\E[?5h$<100/>\E[?5l, fsl=\E[$}, hpa=\E[%i%p1%dG, + ht=^I, hts=\EH, ind=\n, indn=\E[%p1%dS, invis=\E[8m, ka1=, + ka3=, kbs=^?, kc1=, kc3=, kcbt=\E[Z, kend=\EOF, khlp=, + kmous=\E[M, kund=, oc=\E]104\E\\, op=\E[39;49m, rev=\E[7m, + ri=\EM, rin=\E[%p1%dT, rmacs=\E(B, rmam=\E[?7l, + rmkx=\E[?1l, rmso=\E[27m, rmul=\E[24m, rs1=\E]\E\\\Ec, + sgr=%?%p9%t\E(0%e\E(B%;\E[0%?%p6%t;1%;%?%p2%t;4%;%?%p1%p3%| + %t;7%;%?%p4%t;5%;%?%p7%t;8%;m, + sgr0=\E(B\E[m, smacs=\E(0, smam=\E[?7h, smkx=\E[?1h, + smso=\E[7m, smul=\E[4m, tbc=\E[3g, + tsl=\E[2$~\E[1$}\E[H\E[2J, vpa=\E[%i%p1%dd, + Cs=\E]12;%p1%s\E\\, E3=\E[3J, Rmol=\E[55m, Se=\E[ q, + Smol=\E[53m, Smulx=\E[4:%p1%dm, Ss=\E[%p1%d q, + use=ansi+apparrows, use=ansi+cup, use=ansi+csr, + use=ansi+erase, use=ansi+idc, use=ansi+idl, use=ansi+rep, + use=att610+cvis, use=ecma+italics, use=ecma+strikeout, + use=xterm+256color, use=xterm+alt1049, use=xterm+pcc2, + use=xterm+pce2, use=xterm+pcf2, + +contour-direct|Contour terminal with direct colors, + use=xterm+direct, use=contour, + ######## UNIX VIRTUAL TERMINALS, VIRTUAL CONSOLES, AND TELNET CLIENTS # @@ -27781,4 +28020,10 @@ v3220|LANPAR Vision II model 3220/3221/3222, # 2023-12-16 # + used "infocmp -u" to help trim redundant capabilities -TD # +# 2023-12-30 +# + add ms-vt100-16color, winconsole -TD +# + add rio, rio-direct -TD +# + add mostlike -TD +# + add wezterm, contour -TD +# ######## SHANTIH! SHANTIH! SHANTIH! diff --git a/package/debian-mingw/changelog b/package/debian-mingw/changelog index 604dfb49..9459746b 100644 --- a/package/debian-mingw/changelog +++ b/package/debian-mingw/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231223) unstable; urgency=low +ncurses6 (6.4+20231230) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 + -- Thomas E. Dickey Fri, 29 Dec 2023 05:35:26 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian-mingw64/changelog b/package/debian-mingw64/changelog index 604dfb49..9459746b 100644 --- a/package/debian-mingw64/changelog +++ b/package/debian-mingw64/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231223) unstable; urgency=low +ncurses6 (6.4+20231230) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 + -- Thomas E. Dickey Fri, 29 Dec 2023 05:35:26 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian/changelog b/package/debian/changelog index 52315841..c761be36 100644 --- a/package/debian/changelog +++ b/package/debian/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.4+20231223) unstable; urgency=low +ncurses6 (6.4+20231230) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 23 Dec 2023 06:35:00 -0500 + -- Thomas E. Dickey Fri, 29 Dec 2023 05:35:25 -0500 ncurses6 (5.9+20120608) unstable; urgency=low diff --git a/package/mingw-ncurses.nsi b/package/mingw-ncurses.nsi index d6da23ae..d3d794f7 100644 --- a/package/mingw-ncurses.nsi +++ b/package/mingw-ncurses.nsi @@ -1,4 +1,4 @@ -; $Id: mingw-ncurses.nsi,v 1.625 2023/12/23 11:35:00 tom Exp $ +; $Id: mingw-ncurses.nsi,v 1.626 2023/12/29 10:35:26 tom Exp $ ; TODO add examples ; TODO bump ABI to 6 @@ -10,7 +10,7 @@ !define VERSION_MAJOR "6" !define VERSION_MINOR "4" !define VERSION_YYYY "2023" -!define VERSION_MMDD "1223" +!define VERSION_MMDD "1230" !define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD} !define MY_ABI "5" diff --git a/package/mingw-ncurses.spec b/package/mingw-ncurses.spec index 9f0736e3..bb234212 100644 --- a/package/mingw-ncurses.spec +++ b/package/mingw-ncurses.spec @@ -3,7 +3,7 @@ Summary: shared libraries for terminal handling Name: mingw32-ncurses6 Version: 6.4 -Release: 20231223 +Release: 20231230 License: X11 Group: Development/Libraries URL: https://invisible-island.net/ncurses/ diff --git a/package/ncurses.spec b/package/ncurses.spec index 391eed7a..38bf5ff5 100644 --- a/package/ncurses.spec +++ b/package/ncurses.spec @@ -1,7 +1,7 @@ Summary: shared libraries for terminal handling Name: ncurses6 Version: 6.4 -Release: 20231223 +Release: 20231230 License: X11 Group: Development/Libraries URL: https://invisible-island.net/ncurses/ diff --git a/package/ncursest.spec b/package/ncursest.spec index cfe212cb..274293d4 100644 --- a/package/ncursest.spec +++ b/package/ncursest.spec @@ -1,7 +1,7 @@ Summary: Curses library with POSIX thread support. Name: ncursest6 Version: 6.4 -Release: 20231223 +Release: 20231230 License: X11 Group: Development/Libraries Source: ncurses-%{version}-%{release}.tgz

curs_color 3x 2023-12-23 ncurses 6.4 Library calls

curs_color 3x 2023-12-30 ncurses 6.4 Library calls

curs_inwstr 3x 2023-11-25 ncurses 6.4 Library calls

curs_inwstr 3x 2023-12-30 ncurses 6.4 Library calls

curs_scr_dump 3x 2023-12-16 ncurses 6.4 Library calls

curs_scr_dump 3x 2023-12-30 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls

curs_termcap 3x 2023-12-30 ncurses 6.4 Library calls

curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls

curs_terminfo 3x 2023-12-30 ncurses 6.4 Library calls

infocmp 1m 2023-12-23 ncurses 6.4 User commands

infocmp 1m 2023-12-30 ncurses 6.4 User commands

ncurses 3x 2023-12-23 ncurses 6.4 Library calls

ncurses 3x 2023-12-30 ncurses 6.4 Library calls

scr_dump 5 2023-12-23 ncurses 6.4 File formats

scr_dump 5 2023-12-30 ncurses 6.4 File formats

term 5 2023-12-23 ncurses 6.4 File formats

term 5 2023-12-30 ncurses 6.4 File formats

terminfo 5 2023-12-23 ncurses 6.4 File formats

terminfo 5 2023-12-30 ncurses 6.4 File formats

tic 1m 2023-12-23 ncurses 6.4 User commands

tic 1m 2023-12-30 ncurses 6.4 User commands

tput 1 2023-12-23 ncurses 6.4 User commands

tput 1 2023-12-30 ncurses 6.4 User commands

user_caps 5 2023-12-23 ncurses 6.4 File formats

user_caps 5 2023-12-30 ncurses 6.4 File formats