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