1curs_util(3X)                                                    curs_util(3X)
2
3
4

NAME

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

SYNOPSIS

11       #include <curses.h>
12
13       char *unctrl(chtype c);
14       wchar_t *wunctrl(cchar_t *c);
15       char *keyname(int c);
16       char *key_name(wchar_t w);
17       void filter(void);
18       void nofilter(void);
19       void use_env(bool f);
20       void use_tioctl(bool f);
21       int putwin(WINDOW *win, FILE *filep);
22       WINDOW *getwin(FILE *filep);
23       int delay_output(int ms);
24       int flushinp(void);
25

DESCRIPTION

27       The unctrl routine returns a character string which is a printable rep‐
28       resentation of the character c, ignoring attributes.   Control  charac‐
29       ters  are  displayed  in the ^X notation.  Printing characters are dis‐
30       played as is.  The corresponding wunctrl returns a printable  represen‐
31       tation of a wide character.
32
33       The keyname routine returns a character string corresponding to the key
34       c:
35
36          ·   Printable characters are displayed as themselves, e.g.,  a  one-
37              character string containing the key.
38
39          ·   Control characters are displayed in the ^X notation.
40
41          ·   DEL (character 127) is displayed as ^?.
42
43          ·   Values  above  128 are either meta characters (if the screen has
44              not been initialized, or if meta has been called with a TRUE pa‐
45              rameter),  shown  in the M-X notation, or are displayed as them‐
46              selves.  In the latter case, the values may  not  be  printable;
47              this follows the X/Open specification.
48
49          ·   Values above 256 may be the names of the names of function keys.
50
51          ·   Otherwise  (if  there is no corresponding name) the function re‐
52              turns null, to denote an error.  X/Open also lists  an  "UNKNOWN
53              KEY" return value, which some implementations return rather than
54              null.
55
56       The corresponding key_name returns a character string corresponding  to
57       the  wide-character  value w.  The two functions do not return the same
58       set of strings; the latter returns null where the former would  display
59       a meta character.
60
61       The  filter  routine, if used, must be called before initscr or newterm
62       are called.  The effect is that, during those calls, LINES is set to 1;
63       the  capabilities  clear,  cup, cud, cud1, cuu1, cuu, vpa are disabled;
64       and the home string is set to the value of cr.
65
66       The nofilter routine cancels the effect of  a  preceding  filter  call.
67       That  allows  the  caller to initialize a screen on a different device,
68       using a different value of $TERM.  The limitation  arises  because  the
69       filter routine modifies the in-memory copy of the terminal information.
70
71       The  use_env  routine,  if  used,  should  be  called before initscr or
72       newterm are called (because those compute the screen size).   It  modi‐
73       fies  the way ncurses treats environment variables when determining the
74       screen size.
75
76       ·   Normally ncurses looks first  at  the  terminal  database  for  the
77           screen size.
78
79           If  use_env  was called with FALSE for parameter, it stops here un‐
80           less If use_tioctl was also called with TRUE for parameter.
81
82       ·   Then it asks for the screen size via operating  system  calls.   If
83           successful, it overrides the values from the terminal database.
84
85       ·   Finally  (unless  use_env was called with FALSE parameter), ncurses
86           examines the LINES or COLUMNS environment variables, using a  value
87           in  those to override the results from the operating system or ter‐
88           minal database.
89
90           Ncurses also updates the screen size in response to  SIGWINCH,  un‐
91           less overridden by the LINES or COLUMNS environment variables,
92
93       The  use_tioctl  routine,  if  used, should be called before initscr or
94       newterm are called (because those  compute  the  screen  size).   After
95       use_tioctl  is  called  with  TRUE as an argument, ncurses modifies the
96       last step in its computation of screen size as follows:
97
98       ·   checks if the LINES and COLUMNS environment variables are set to  a
99           number greater than zero.
100
101       ·   for  each,  ncurses  updates the corresponding environment variable
102           with the value that it has obtained via operating  system  call  or
103           from the terminal database.
104
105       ·   ncurses  re-fetches  the value of the environment variables so that
106           it is still the environment variables which set the screen size.
107
108       The use_env and use_tioctl routines combine as summarized here:
109
110           use_env   use_tioctl   Summary
111           ────────────────────────────────────────────────────────────────
112           TRUE      FALSE        This is the default  behavior.   ncurses
113                                  uses operating system calls unless over‐
114                                  ridden by $LINES or $COLUMNS environment
115                                  variables.
116           TRUE      TRUE         ncurses   updates  $LINES  and  $COLUMNS
117                                  based on operating system calls.
118           FALSE     TRUE         ncurses ignores $LINES and $COLUMNS, us‐
119                                  es  operating  system  calls  to  obtain
120                                  size.
121           FALSE     FALSE        ncurses relies on the terminal  database
122                                  to determine size.
123
124       The  putwin routine writes all data associated with window win into the
125       file to which filep points.  This information can  be  later  retrieved
126       using the getwin function.
127
128       The  getwin  routine  reads  window  related data stored in the file by
129       putwin.  The routine then creates and initializes a  new  window  using
130       that data.  It returns a pointer to the new window.
131
132       The  delay_output  routine  inserts  an ms millisecond pause in output.
133       This routine should not be used extensively because padding  characters
134       are  used  rather  than a CPU pause.  If no padding character is speci‐
135       fied, this uses napms to perform the delay.
136
137       The flushinp routine throws away any typeahead that has been  typed  by
138       the user and has not yet been read by the program.
139

RETURN VALUE

141       Except  for  flushinp,  routines that return an integer return ERR upon
142       failure and OK (SVr4 specifies only "an integer value other than  ERR")
143       upon successful completion.
144
145       Routines that return pointers return NULL on error.
146
147       X/Open does not define any error conditions.  In this implementation
148
149          flushinp
150               returns an error if the terminal was not initialized.
151
152          meta returns an error if the terminal was not initialized.
153
154          putwin
155               returns  an  error if the associated fwrite calls return an er‐
156               ror.
157

PORTABILITY

159       The XSI Curses standard, Issue 4 describes these functions.  It  states
160       that unctrl and wunctrl will return a null pointer if unsuccessful, but
161       does not define any error conditions.  This implementation  checks  for
162       three cases:
163
164          ·   the  parameter  is a 7-bit US-ASCII code.  This is the case that
165              X/Open Curses documented.
166
167          ·   the parameter is in the range 128-159, i.e., a C1 control  code.
168              If  use_legacy_coding has been called with a 2 parameter, unctrl
169              returns the parameter, i.e., a one-character string with the pa‐
170              rameter  as  the first character.  Otherwise, it returns ``~@'',
171              ``~A'', etc., analogous to ``^@'', ``^A'', C0 controls.
172
173              X/Open Curses does not document whether unctrl can be called be‐
174              fore initializing curses.  This implementation permits that, and
175              returns the ``~@'', etc., values in that case.
176
177          ·   parameter values outside the 0 to 255 range.  unctrl  returns  a
178              null pointer.
179
180       The  SVr4  documentation  describes  the  action  of filter only in the
181       vaguest terms.  The description here is adapted  from  the  XSI  Curses
182       standard (which erroneously fails to describe the disabling of cuu).
183
184       The strings returned by unctrl in this implementation are determined at
185       compile time, showing C1 controls from the upper-128 codes with  a  `~'
186       prefix  rather  than `^'.  Other implementations have different conven‐
187       tions.  For example, they may show both sets of control characters with
188       `^', and strip the parameter to 7 bits.  Or they may ignore C1 controls
189       and treat all of the upper-128 codes as printable.  This implementation
190       uses  8  bits  but  does  not modify the string to reflect locale.  The
191       use_legacy_coding function allows the caller to change  the  output  of
192       unctrl.
193
194       Likewise,  the  meta function allows the caller to change the output of
195       keyname, i.e., it  determines  whether  to  use  the  `M-'  prefix  for
196       ``meta''  keys (codes in the range 128 to 255).  Both use_legacy_coding
197       and meta succeed only after curses is initialized.  X/Open Curses  does
198       not  document the treatment of codes 128 to 159.  When treating them as
199       ``meta'' keys (or if keyname is  called  before  initializing  curses),
200       this implementation returns strings ``M-^@'', ``M-^A'', etc.
201
202       The  keyname function may return the names of user-defined string capa‐
203       bilities which are defined in the terminfo entry via the -x  option  of
204       tic.  This implementation automatically assigns at run-time keycodes to
205       user-defined strings which begin  with  "k".   The  keycodes  start  at
206       KEY_MAX, but are not guaranteed to be the same value for different runs
207       because user-defined codes are merged from  all  terminal  descriptions
208       which  have  been  loaded.   The  use_extended_names  function controls
209       whether this data is loaded when the terminal description  is  read  by
210       the library.
211
212       The  nofilter  and  use_tioctl  routines are specific to ncurses.  They
213       were not supported on Version 7, BSD or System V  implementations.   It
214       is  recommended that any code depending on ncurses extensions be condi‐
215       tioned using NCURSES_VERSION.
216

SEE ALSO

218       legacy_coding(3X),   curses(3X),   curs_initscr(3X),   curs_kernel(3X),
219       curs_scr_dump(3X), curs_variables(3X), legacy_coding(3X).
220
221
222
223                                                                 curs_util(3X)
Impressum