doc/html/man/curs_util.3x.html

   1 <!--
   2   * t
   3   ****************************************************************************
   4   * Copyright (c) 1998-2013,2015 Free Software Foundation, Inc.              *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_util.3x,v 1.42 2015/04/26 14:27:03 Sven.Joachim Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_util 3x</TITLE>
  38 <link rev=made href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_util 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>                                             <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE>
  50 <H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <STRONG>delay_output</STRONG>, <STRONG>filter</STRONG>, <STRONG>flushinp</STRONG>, <STRONG>getwin</STRONG>, <STRONG>key_name</STRONG>, <STRONG>keyname</STRONG>,
  52        <STRONG>nofilter</STRONG>, <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>use_tioctl</STRONG>, <STRONG>wunctrl</STRONG> -
  53        miscellaneous <STRONG>curses</STRONG> utility routines
  54
  55
  56 </PRE>
  57 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  58        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  59
  60        <STRONG>char</STRONG> <STRONG>*unctrl(chtype</STRONG> <STRONG>c);</STRONG>
  61        <STRONG>wchar_t</STRONG> <STRONG>*wunctrl(cchar_t</STRONG> <STRONG>*c);</STRONG>
  62        <STRONG>char</STRONG> <STRONG>*keyname(int</STRONG> <STRONG>c);</STRONG>
  63        <STRONG>char</STRONG> <STRONG>*key_name(wchar_t</STRONG> <STRONG>w);</STRONG>
  64        <STRONG>void</STRONG> <STRONG>filter(void);</STRONG>
  65        <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG>
  66        <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <STRONG>f);</STRONG>
  67        <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <STRONG>f);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>FILE</STRONG> <STRONG>*filep);</STRONG>
  69        <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*filep);</STRONG>
  70        <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <STRONG>ms);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG>
  72
  73
  74 </PRE>
  75 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  76        The  <STRONG>unctrl</STRONG>  routine returns a character string which is a
  77        printable representation of the character <EM>c</EM>, ignoring  at-
  78        tributes.   Control characters are displayed in the <STRONG>^</STRONG><EM>X</EM> no-
  79        tation.  Printing characters are  displayed  as  is.   The
  80        corresponding  <STRONG>wunctrl</STRONG>  returns a printable representation
  81        of a wide character.
  82
  83        The <STRONG>keyname</STRONG> routine returns a character string correspond-
  84        ing to the key <EM>c</EM>:
  85
  86        <STRONG>o</STRONG>   Printable  characters  are  displayed  as  themselves,
  87            e.g., a one-character string containing the key.
  88
  89        <STRONG>o</STRONG>   Control characters are displayed in the <STRONG>^</STRONG><EM>X</EM> notation.
  90
  91        <STRONG>o</STRONG>   DEL (character 127) is displayed as <STRONG>^?</STRONG>.
  92
  93        <STRONG>o</STRONG>   Values above 128 are either meta  characters  (if  the
  94            screen  has  not been initialized, or if <STRONG>meta</STRONG> has been
  95            called with a <STRONG>TRUE</STRONG> parameter), shown in the <STRONG>M-</STRONG><EM>X</EM>  nota-
  96            tion,  or  are displayed as themselves.  In the latter
  97            case, the values may not be  printable;  this  follows
  98            the X/Open specification.
  99
 100        <STRONG>o</STRONG>   Values  above  256  may  be  the names of the names of
 101            function keys.
 102
 103        <STRONG>o</STRONG>   Otherwise (if there  is  no  corresponding  name)  the
 104            function returns null, to denote an error.  X/Open al-
 105            so lists an "UNKNOWN KEY" return value, which some im-
 106            plementations return rather than null.
 107
 108        The corresponding <STRONG>key_name</STRONG> returns a character string cor-
 109        responding to the wide-character value <EM>w</EM>.  The  two  func-
 110        tions  do  not  return the same set of strings; the latter
 111        returns null where the former would display a meta charac-
 112        ter.
 113
 114        The <STRONG>filter</STRONG> routine, if used, must be called before <STRONG>initscr</STRONG>
 115        or <STRONG>newterm</STRONG> are called.  The effect is that,  during  those
 116        calls,  <STRONG>LINES</STRONG>  is  set  to 1; the capabilities <STRONG>clear</STRONG>, <STRONG>cup</STRONG>,
 117        <STRONG>cud</STRONG>, <STRONG>cud1</STRONG>, <STRONG>cuu1</STRONG>, <STRONG>cuu</STRONG>,  <STRONG>vpa</STRONG>  are  disabled;  and  the  <STRONG>home</STRONG>
 118        string is set to the value of <STRONG>cr</STRONG>.
 119
 120        The  <STRONG>nofilter</STRONG>  routine  cancels  the effect of a preceding
 121        <STRONG>filter</STRONG> call.  That  allows  the  caller  to  initialize  a
 122        screen  on  a different device, using a different value of
 123        <STRONG>$TERM</STRONG>.  The limitation arises because the  <STRONG>filter</STRONG>  routine
 124        modifies the in-memory copy of the terminal information.
 125
 126        The  <STRONG>use_env</STRONG>  routine,  if  used,  should be called before
 127        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> are called (because those  compute  the
 128        screen size).  It modifies the way <STRONG>ncurses</STRONG> treats environ-
 129        ment variables when determining the screen size.
 130
 131        <STRONG>o</STRONG>   Normally ncurses looks first at the terminal  database
 132            for the screen size.
 133
 134            If  <STRONG>use_env</STRONG>  was  called  with <STRONG>FALSE</STRONG> for parameter, it
 135            stops here unless If <STRONG>use_tioctl</STRONG> was also  called  with
 136            <STRONG>TRUE</STRONG> for parameter.
 137
 138        <STRONG>o</STRONG>   Then  it asks for the screen size via operating system
 139            calls.  If successful, it overrides  the  values  from
 140            the terminal database.
 141
 142        <STRONG>o</STRONG>   Finally  (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parame-
 143            ter), ncurses examines the <STRONG>LINES</STRONG> or  <STRONG>COLUMNS</STRONG>  environ-
 144            ment variables, using a value in those to override the
 145            results from the operating system  or  terminal  data-
 146            base.
 147
 148            Ncurses  also  updates  the screen size in response to
 149            SIGWINCH, unless overridden by the  <STRONG>LINES</STRONG>  or  <STRONG>COLUMNS</STRONG>
 150            environment variables,
 151
 152        The  <STRONG>use_tioctl</STRONG>  routine, if used, should be called before
 153        <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> are called (because those  compute  the
 154        screen  size).  After <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an
 155        argument, ncurses modifies the last step in  its  computa-
 156        tion of screen size as follows:
 157
 158        <STRONG>o</STRONG>   checks  if the <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> environment variables
 159            are set to a number greater than zero.
 160
 161        <STRONG>o</STRONG>   for each, ncurses updates the  corresponding  environ-
 162            ment  variable with the value that it has obtained via
 163            operating system call or from the terminal database.
 164
 165        <STRONG>o</STRONG>   ncurses re-fetches the value of the environment  vari-
 166            ables  so  that  it is still the environment variables
 167            which set the screen size.
 168
 169        The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as  summarized
 170        here:
 171
 172      <EM>use</EM><STRONG>_</STRONG><EM>env</EM>   <EM>use</EM><STRONG>_</STRONG><EM>tioctl</EM>   <EM>Summary</EM>
 173      ----------------------------------------------------------------
 174      TRUE      FALSE        This  is  the default behavior.  ncurses
 175                             uses operating system calls unless over-
 176                             ridden by $LINES or $COLUMNS environment
 177                             variables.
 178      TRUE      TRUE         ncurses  updates  $LINES  and   $COLUMNS
 179                             based on operating system calls.
 180
 181
 182      FALSE     TRUE         ncurses ignores $LINES and $COLUMNS, us-
 183                             es  operating  system  calls  to  obtain
 184                             size.
 185      FALSE     FALSE        ncurses  relies on the terminal database
 186                             to determine size.
 187
 188        The <STRONG>putwin</STRONG> routine writes all data associated with  window
 189        (or  pad)  <EM>win</EM>  into the file to which <EM>filep</EM> points.  This
 190        information can be later retrieved using the <STRONG>getwin</STRONG>  func-
 191        tion.
 192
 193        The <STRONG>getwin</STRONG> routine reads window related data stored in the
 194        file by <STRONG>putwin</STRONG>.  The routine then creates and  initializes
 195        a new window using that data.  It returns a pointer to the
 196        new window.  There are a few caveats:
 197
 198        <STRONG>o</STRONG>   the data written is a copy of  the  <STRONG>WINDOW</STRONG>  structure,
 199            and  its  associated character cells.  The format dif-
 200            fers between the wide-character  (ncursesw)  and  non-
 201            wide  (ncurses)  libraries.  You can transfer data be-
 202            tween the two, however.
 203
 204        <STRONG>o</STRONG>   the retrieved window is always created as a  top-level
 205            window (or pad), rather than a subwindow.
 206
 207        <STRONG>o</STRONG>   the  window's  character  cells contain the color pair
 208            <EM>value</EM>, but not the actual color <EM>numbers</EM>.  If cells  in
 209            the  retrieved  window  use color pairs which have not
 210            been created in the application using <STRONG>init_pair</STRONG>,  they
 211            will not be colored when the window is refreshed.
 212
 213        The  <STRONG>delay_output</STRONG>  routine inserts an <EM>ms</EM> millisecond pause
 214        in output.  This routine should not  be  used  extensively
 215        because  padding  characters  are  used  rather than a CPU
 216        pause.  If no padding character is  specified,  this  uses
 217        <STRONG>napms</STRONG> to perform the delay.
 218
 219        The  <STRONG>flushinp</STRONG>  routine  throws away any typeahead that has
 220        been typed by the user and has not yet been  read  by  the
 221        program.
 222
 223
 224 </PRE>
 225 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 226        Except  for  <STRONG>flushinp</STRONG>, routines that return an integer re-
 227        turn <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only "an  in-
 228        teger value other than <STRONG>ERR</STRONG>") upon successful completion.
 229
 230        Routines that return pointers return <STRONG>NULL</STRONG> on error.
 231
 232        X/Open  does not define any error conditions.  In this im-
 233        plementation
 234
 235           <STRONG>flushinp</STRONG>
 236                returns an error if the terminal was not  initial-
 237                ized.
 238
 239           <STRONG>meta</STRONG> returns  an error if the terminal was not initial-
 240                ized.
 241
 242           <STRONG>putwin</STRONG>
 243                returns an error if the  associated  <STRONG>fwrite</STRONG>  calls
 244                return an error.
 245
 246
 247 </PRE>
 248 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 249
 250 </PRE>
 251 <H3><a name="h3-filter">filter</a></H3><PRE>
 252        The SVr4 documentation describes the action of <STRONG>filter</STRONG> only
 253        in the vaguest terms.  The  description  here  is  adapted
 254        from  the  XSI Curses standard (which erroneously fails to
 255        describe the disabling of <STRONG>cuu</STRONG>).
 256
 257
 258 </PRE>
 259 <H3><a name="h3-keyname">keyname</a></H3><PRE>
 260        The <STRONG>keyname</STRONG> function may return the names of  user-defined
 261        string  capabilities which are defined in the terminfo en-
 262        try via the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>.  This  implementation  auto-
 263        matically  assigns  at  run-time  keycodes to user-defined
 264        strings which begin  with  "k".   The  keycodes  start  at
 265        KEY_MAX,  but  are not guaranteed to be the same value for
 266        different runs because user-defined codes are merged  from
 267        all  terminal  descriptions  which  have been loaded.  The
 268        <STRONG>use_extended_names</STRONG> function controls whether this data  is
 269        loaded  when  the  terminal description is read by the li-
 270        brary.
 271
 272
 273 </PRE>
 274 <H3><a name="h3-nofilter_use_tioctl">nofilter/use_tioctl</a></H3><PRE>
 275        The <STRONG>nofilter</STRONG>  and  <STRONG>use_tioctl</STRONG>  routines  are  specific  to
 276        ncurses.   They  were  not  supported on Version 7, BSD or
 277        System V implementations.  It is recommended that any code
 278        depending  on  ncurses  extensions  be  conditioned  using
 279        NCURSES_VERSION.
 280
 281
 282 </PRE>
 283 <H3><a name="h3-putwin_getwin">putwin/getwin</a></H3><PRE>
 284        The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions have several  issues  with
 285        portability:
 286
 287        <STRONG>o</STRONG>   The  files  written and read by these functions use an
 288            implementation-specific format.  Although  the  format
 289            is  an obvious target for standardization, it has been
 290            overlooked.
 291
 292            Interestingly enough, according to the copyright dates
 293            in Solaris source, the functions (along with <STRONG>scr_init</STRONG>,
 294            etc.) originated with the  University  of  California,
 295            Berkeley  (in  1982) and were later (in 1988) incorpo-
 296            rated into SVr4.  Oddly, there are no  such  functions
 297            in the 4.3BSD curses sources.
 298
 299        <STRONG>o</STRONG>   Most  implementations  simply  dump  the binary <STRONG>WINDOW</STRONG>
 300            structure to the file.   These  include  SVr4  curses,
 301            NetBSD  and  PDCurses,  as  well as older ncurses ver-
 302            sions.  This implementation (as  well  as  the  X/Open
 303            variant  of  Solaris  curses, dated 1995) uses textual
 304            dumps.
 305
 306            The implementations which use binary dumps use  block-
 307            I/O  (the <STRONG>fwrite</STRONG> and <STRONG>fread</STRONG> functions).  Those that use
 308            textual dumps use buffered-I/O.   A  few  applications
 309            may happen to write extra data in the file using these
 310            functions.  Doing that can run  into  problems  mixing
 311            block-  and buffered-I/O.  This implementation reduces
 312            the problem on writes by flushing the output.   Howev-
 313            er,  reading  from  a file written using mixed schemes
 314            may not be successful.
 315
 316
 317 </PRE>
 318 <H3><a name="h3-unctrl_wunctrl">unctrl/wunctrl</a></H3><PRE>
 319        The XSI Curses standard, Issue  4  describes  these  func-
 320        tions.   It  states  that <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a
 321        null pointer if unsuccessful, but does not define any  er-
 322        ror conditions.  This implementation checks for three cas-
 323        es:
 324
 325        <STRONG>o</STRONG>   the parameter is a 7-bit US-ASCII code.  This  is  the
 326            case that X/Open Curses documented.
 327
 328        <STRONG>o</STRONG>   the parameter is in the range 128-159, i.e., a C1 con-
 329            trol code.  If <STRONG>use_legacy_coding</STRONG> has been called  with
 330            a  <STRONG>2</STRONG>  parameter, <STRONG>unctrl</STRONG> returns the parameter, i.e., a
 331            one-character string with the parameter as  the  first
 332            character.   Otherwise,  it  returns "~@", "~A", etc.,
 333            analogous to "^@", "^A", C0 controls.
 334
 335            X/Open Curses does not document whether <STRONG>unctrl</STRONG> can  be
 336            called  before  initializing curses.  This implementa-
 337            tion permits that, and returns the "~@", etc.,  values
 338            in that case.
 339
 340        <STRONG>o</STRONG>   parameter  values  outside the 0 to 255 range.  <STRONG>unctrl</STRONG>
 341            returns a null pointer.
 342
 343        The strings returned by <STRONG>unctrl</STRONG> in this implementation  are
 344        determined  at  compile time, showing C1 controls from the
 345        upper-128 codes with a `~' prefix rather than `^'.   Other
 346        implementations  have different conventions.  For example,
 347        they may show both sets of control  characters  with  `^',
 348        and  strip the parameter to 7 bits.  Or they may ignore C1
 349        controls and treat all of the upper-128  codes  as  print-
 350        able.  This implementation uses 8 bits but does not modify
 351        the string to reflect locale.  The <STRONG>use_legacy_coding</STRONG> func-
 352        tion allows the caller to change the output of <STRONG>unctrl</STRONG>.
 353
 354        Likewise,  the  <STRONG>meta</STRONG>  function allows the caller to change
 355        the output of <STRONG>keyname</STRONG>, i.e., it determines whether to  use
 356        the `M-' prefix for "meta" keys (codes in the range 128 to
 357        255).  Both <STRONG>use_legacy_coding</STRONG> and <STRONG>meta</STRONG> succeed only  after
 358        curses  is  initialized.   X/Open Curses does not document
 359        the treatment of codes 128 to 159.  When treating them  as
 360        "meta"  keys  (or if <STRONG>keyname</STRONG> is called before initializing
 361        curses),  this  implementation  returns  strings   "M-^@",
 362        "M-^A", etc.
 363
 364
 365 </PRE>
 366 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 367        <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG>curs_ker-</STRONG>
 368        <STRONG><A HREF="curs_kernel.3x.html">nel(3x)</A></STRONG>,  <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>,   <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,   <STRONG>lega-</STRONG>
 369        <STRONG><A HREF="legacy_coding.3x.html">cy_coding(3x)</A></STRONG>.
 370
 371
 372
 373                                                           <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
 374 </PRE>
 375 <div class="nav">
 376 <ul>
 377 <li><a href="#h2-NAME">NAME</a></li>
 378 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 379 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 380 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 381 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 382 <ul>
 383 <li><a href="#h3-filter">filter</a></li>
 384 <li><a href="#h3-keyname">keyname</a></li>
 385 <li><a href="#h3-nofilter_use_tioctl">nofilter/use_tioctl</a></li>
 386 <li><a href="#h3-putwin_getwin">putwin/getwin</a></li>
 387 <li><a href="#h3-unctrl_wunctrl">unctrl/wunctrl</a></li>
 388 </ul>
 389 </li>
 390 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 391 </ul>
 392 </div>
 393 </BODY>
 394 </HTML>