curs_util 3x

curs_util(3x)                                             curs_util(3x)




NAME

       delay_output, filter, flushinp, getwin, key_name, keyname,
       nofilter, putwin, unctrl, use_env, use_tioctl, wunctrl -
       miscellaneous curses utility routines


SYNOPSIS

       #include <curses.h>

       char *unctrl(chtype c);
       wchar_t *wunctrl(cchar_t *c);
       char *keyname(int c);
       char *key_name(wchar_t w);
       void filter(void);
       void nofilter(void);
       void use_env(bool f);
       void use_tioctl(bool f);
       int putwin(WINDOW *win, FILE *filep);
       WINDOW *getwin(FILE *filep);
       int delay_output(int ms);
       int flushinp(void);


DESCRIPTION


unctrl

       The  unctrl  routine returns a character string which is a
       printable representation of the character c, ignoring  at-
       tributes.   Control characters are displayed in the ^X no-
       tation.  Printing characters are  displayed  as  is.   The
       corresponding  wunctrl  returns a printable representation
       of a wide character.


keyname/key_name

       The keyname routine returns a character string correspond-
       ing to the key c:

       o   Printable  characters  are  displayed  as  themselves,
           e.g., a one-character string containing the key.

       o   Control characters are displayed in the ^X notation.

       o   DEL (character 127) is displayed as ^?.

       o   Values above 128 are either meta  characters  (if  the
           screen  has  not  been initialized, or if meta(3x) has
           been called with a TRUE parameter), shown in  the  M-X
           notation, or are displayed as themselves.  In the lat-
           ter case, the values may not be printable;  this  fol-
           lows the X/Open specification.

       o   Values  above  256  may  be  the names of the names of
           function keys.

       o   Otherwise (if there  is  no  corresponding  name)  the
           function returns null, to denote an error.  X/Open al-
           so lists an "UNKNOWN KEY" return value, which some im-
           plementations return rather than null.

       The corresponding key_name returns a character string cor-
       responding to the wide-character value w.  The  two  func-
       tions  do  not  return the same set of strings; the latter
       returns null where the former would display a meta charac-
       ter.


filter/nofilter

       The filter routine, if used, must be called before initscr
       or newterm are called.  The effect is that,  during  those
       calls,  LINES  is  set  to 1; the capabilities clear, cup,
       cud, cud1, cuu1, cuu,  vpa  are  disabled;  and  the  home
       string is set to the value of cr.

       The  nofilter  routine  cancels  the effect of a preceding
       filter call.  That  allows  the  caller  to  initialize  a
       screen  on  a different device, using a different value of
       $TERM.  The limitation arises because the  filter  routine
       modifies the in-memory copy of the terminal information.


use_env

       The  use_env  routine,  if  used,  should be called before
       initscr or newterm are called (because those  compute  the
       screen size).  It modifies the way ncurses treats environ-
       ment variables when determining the screen size.

       o   Normally ncurses looks first at the terminal  database
           for the screen size.

           If  use_env  was  called  with FALSE for parameter, it
           stops here unless If use_tioctl was also  called  with
           TRUE for parameter.

       o   Then  it asks for the screen size via operating system
           calls.  If successful, it overrides  the  values  from
           the terminal database.

       o   Finally  (unless use_env was called with FALSE parame-
           ter), ncurses examines the LINES or  COLUMNS  environ-
           ment variables, using a value in those to override the
           results from the operating system  or  terminal  data-
           base.

           Ncurses  also  updates  the screen size in response to
           SIGWINCH, unless overridden by the  LINES  or  COLUMNS
           environment variables,


use_tioctl

       The  use_tioctl  routine, if used, should be called before
       initscr or newterm are called (because those  compute  the
       screen  size).  After use_tioctl is called with TRUE as an
       argument, ncurses modifies the last step in  its  computa-
       tion of screen size as follows:

       o   checks  if the LINES and COLUMNS environment variables
           are set to a number greater than zero.

       o   for each, ncurses updates the  corresponding  environ-
           ment  variable with the value that it has obtained via
           operating system call or from the terminal database.

       o   ncurses re-fetches the value of the environment  vari-
           ables  so  that  it is still the environment variables
           which set the screen size.

       The use_env and use_tioctl routines combine as  summarized
       here:

     use_env   use_tioctl   Summary
     ----------------------------------------------------------------



     TRUE      FALSE        This  is  the default behavior.  ncurses
                            uses operating system calls unless over-
                            ridden by $LINES or $COLUMNS environment
                            variables.
     TRUE      TRUE         ncurses  updates  $LINES  and   $COLUMNS
                            based on operating system calls.
     FALSE     TRUE         ncurses ignores $LINES and $COLUMNS, us-
                            es  operating  system  calls  to  obtain
                            size.
     FALSE     FALSE        ncurses  relies on the terminal database
                            to determine size.


putwin/getwin

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

       The getwin routine reads window related data stored in the
       file by putwin.  The routine then creates and  initializes
       a new window using that data.  It returns a pointer to the
       new window.  There are a few caveats:

       o   the data written is a copy of  the  WINDOW  structure,
           and  its  associated character cells.  The format dif-
           fers between the wide-character  (ncursesw)  and  non-
           wide  (ncurses)  libraries.  You can transfer data be-
           tween the two, however.

       o   the retrieved window is always created as a  top-level
           window (or pad), rather than a subwindow.

       o   the  window's  character  cells contain the color pair
           value, but not the actual color numbers.  If cells  in
           the  retrieved  window  use color pairs which have not
           been created in the application using init_pair,  they
           will not be colored when the window is refreshed.


delay_output

       The  delay_output  routine inserts an ms millisecond pause
       in output.  This routine should not  be  used  extensively
       because  padding  characters  are  used  rather than a CPU
       pause.  If no padding character is  specified,  this  uses
       napms to perform the delay.


flushinp

       The  flushinp  routine  throws away any typeahead that has
       been typed by the user and has not yet been  read  by  the
       program.


RETURN VALUE

       Except  for  flushinp, routines that return an integer re-
       turn ERR upon failure and OK (SVr4 specifies only "an  in-
       teger value other than ERR") upon successful completion.

       Routines that return pointers return NULL on error.

       X/Open  does not define any error conditions.  In this im-
       plementation

          flushinp
               returns an error if the terminal was not  initial-
               ized.

          putwin
               returns  an  error  if the associated fwrite calls
               return an error.


PORTABILITY


filter

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


keyname

       The  keyname function may return the names of user-defined
       string capabilities which are defined in the terminfo  en-
       try  via  the -x option of tic.  This implementation auto-
       matically assigns at  run-time  keycodes  to  user-defined
       strings  which  begin  with  "k".   The  keycodes start at
       KEY_MAX, but are not guaranteed to be the same  value  for
       different  runs because user-defined codes are merged from
       all terminal descriptions which  have  been  loaded.   The
       use_extended_names  function controls whether this data is
       loaded when the terminal description is read  by  the  li-
       brary.


nofilter/use_tioctl

       The  nofilter  and  use_tioctl  routines  are  specific to
       ncurses.  They were not supported on  Version  7,  BSD  or
       System V implementations.  It is recommended that any code
       depending  on  ncurses  extensions  be  conditioned  using
       NCURSES_VERSION.


putwin/getwin

       The  putwin  and getwin functions have several issues with
       portability:

       o   The files written and read by these functions  use  an
           implementation-specific  format.   Although the format
           is an obvious target for standardization, it has  been
           overlooked.

           Interestingly enough, according to the copyright dates
           in Solaris source, the functions (along with scr_init,
           etc.)  originated  with  the University of California,
           Berkeley (in 1982) and were later (in  1988)  incorpo-
           rated  into  SVr4.  Oddly, there are no such functions
           in the 4.3BSD curses sources.

       o   Most implementations simply  dump  the  binary  WINDOW
           structure  to  the  file.   These include SVr4 curses,
           NetBSD and PDCurses, as well  as  older  ncurses  ver-
           sions.   This  implementation  (as  well as the X/Open
           variant of Solaris curses, dated  1995)  uses  textual
           dumps.

           The  implementations which use binary dumps use block-
           I/O (the fwrite and fread functions).  Those that  use
           textual  dumps  use  buffered-I/O.  A few applications
           may happen to write extra data in the file using these
           functions.   Doing  that  can run into problems mixing
           block- and buffered-I/O.  This implementation  reduces
           the  problem on writes by flushing the output.  Howev-
           er, reading from a file written  using  mixed  schemes
           may not be successful.


unctrl/wunctrl

       The  XSI  Curses  standard,  Issue 4 describes these func-
       tions.  It states that unctrl and wunctrl  will  return  a
       null  pointer if unsuccessful, but does not define any er-
       ror conditions.  This implementation checks for three cas-
       es:

       o   the  parameter  is a 7-bit US-ASCII code.  This is the
           case that X/Open Curses documented.

       o   the parameter is in the range 128-159, i.e., a C1 con-
           trol  code.  If use_legacy_coding has been called with
           a 2 parameter, unctrl returns the parameter,  i.e.,  a
           one-character  string  with the parameter as the first
           character.  Otherwise, it returns  "~@",  "~A",  etc.,
           analogous to "^@", "^A", C0 controls.

           X/Open  Curses does not document whether unctrl can be
           called before initializing curses.   This  implementa-
           tion  permits that, and returns the "~@", etc., values
           in that case.

       o   parameter values outside the 0 to 255  range.   unctrl
           returns a null pointer.

       The  strings returned by unctrl in this implementation are
       determined at compile time, showing C1 controls  from  the
       upper-128  codes with a "~" prefix rather than "^".  Other
       implementations have different conventions.  For  example,
       they  may  show  both sets of control characters with "^",
       and strip the parameter to 7 bits.  Or they may ignore  C1
       controls  and  treat  all of the upper-128 codes as print-
       able.  This implementation uses 8 bits but does not modify
       the string to reflect locale.  The use_legacy_coding func-
       tion allows the caller to change the output of unctrl.

       Likewise, the  meta(3x)  function  allows  the  caller  to
       change  the output of keyname, i.e., it determines whether
       to use the "M-" prefix for "meta" keys (codes in the range
       128 to 255).  Both use_legacy_coding and meta succeed only
       after curses is initialized.  X/Open Curses does not docu-
       ment  the  treatment  of  codes 128 to 159.  When treating
       them as "meta" keys (or if keyname is called  before  ini-
       tializing  curses),  this  implementation  returns strings
       "M-^@", "M-^A", etc.


use_env/use_tioctl

       If ncurses is configured to provide the  sp-functions  ex-
       tension, the state of use_env and use_tioctl may be updat-
       ed before creating  each  screen  rather  than  once  only
       (curs_sp_funcs(3x)).   This feature of use_env is not pro-
       vided by other implementation of curses.


SEE ALSO

       legacy_coding(3x), curses(3x), curs_initscr(3x),  curs_in-
       opts(3x),        curs_kernel(3x),       curs_scr_dump(3x),
       curs_sp_funcs(3x), curs_variables(3x), legacy_coding(3x).



                                                          curs_util(3x)