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       const char *unctrl(chtype c);
14       wchar_t *wunctrl(cchar_t *c);
15
16       const char *keyname(int c);
17       const char *key_name(wchar_t w);
18
19       void filter(void);
20       void nofilter(void);
21
22       void use_env(bool f);
23       void use_tioctl(bool f);
24
25       int putwin(WINDOW *win, FILE *filep);
26       WINDOW *getwin(FILE *filep);
27
28       int delay_output(int ms);
29       int flushinp(void);
30

DESCRIPTION

32   unctrl
33       The unctrl routine returns a character string which is a printable rep‐
34       resentation of the character c, ignoring attributes.   Control  charac‐
35       ters  are  displayed  in the ^X notation.  Printing characters are dis‐
36       played as is.  The corresponding wunctrl returns a printable  represen‐
37       tation of a wide character.
38
39   keyname/key_name
40       The keyname routine returns a character string corresponding to the key
41       c:
42
43       •   Printable characters are displayed as themselves, e.g., a one-char‐
44           acter string containing the key.
45
46       •   Control characters are displayed in the ^X notation.
47
48       •   DEL (character 127) is displayed as ^?.
49
50       •   Values  above 128 are either meta characters (if the screen has not
51           been initialized, or if meta(3X) has been called with a TRUE param‐
52           eter),  shown  in the M-X notation, or are displayed as themselves.
53           In the latter case, the values may not be printable;  this  follows
54           the X/Open specification.
55
56       •   Values above 256 may be the names of the names of function keys.
57
58       •   Otherwise  (if there is no corresponding name) the function returns
59           null, to denote an error.  X/Open also lists an “UNKNOWN  KEY”  re‐
60           turn value, which some implementations return rather than null.
61
62       The  corresponding key_name returns a character string corresponding to
63       the wide-character value w.  The two functions do not return  the  same
64       set  of strings; the latter returns null where the former would display
65       a meta character.
66
67   filter/nofilter
68       The filter routine, if used, must be called before initscr  or  newterm
69       are called.  Calling filter causes these changes in initialization:
70
71LINES is set to 1;
72
73       •   the  capabilities  clear,  cud1,  cud, cup, cuu1, cuu, vpa are dis‐
74           abled;
75
76       •   the capability ed is disabled if bce is set;
77
78       •   and the home string is set to the value of cr.
79
80       The nofilter routine cancels the effect of  a  preceding  filter  call.
81       That  allows  the  caller to initialize a screen on a different device,
82       using a different value of $TERM.  The limitation  arises  because  the
83       filter routine modifies the in-memory copy of the terminal information.
84
85   use_env
86       The  use_env  routine,  if  used,  should  be  called before initscr or
87       newterm are called (because those compute the screen size).   It  modi‐
88       fies  the way ncurses treats environment variables when determining the
89       screen size.
90
91       •   Normally ncurses looks first  at  the  terminal  database  for  the
92           screen size.
93
94           If  use_env  was called with FALSE for parameter, it stops here un‐
95           less use_tioctl was also called with TRUE for parameter.
96
97       •   Then it asks for the screen size via operating  system  calls.   If
98           successful, it overrides the values from the terminal database.
99
100       •   Finally  (unless  use_env was called with FALSE parameter), ncurses
101           examines the LINES or COLUMNS environment variables, using a  value
102           in  those to override the results from the operating system or ter‐
103           minal database.
104
105           Ncurses also updates the screen size in response to  SIGWINCH,  un‐
106           less overridden by the LINES or COLUMNS environment variables,
107
108   use_tioctl
109       The  use_tioctl  routine,  if  used, should be called before initscr or
110       newterm are called (because those  compute  the  screen  size).   After
111       use_tioctl  is  called  with  TRUE as an argument, ncurses modifies the
112       last step in its computation of screen size as follows:
113
114       •   checks if the LINES and COLUMNS environment variables are set to  a
115           number greater than zero.
116
117       •   for  each,  ncurses  updates the corresponding environment variable
118           with the value that it has obtained via operating  system  call  or
119           from the terminal database.
120
121ncurses  re-fetches  the value of the environment variables so that
122           it is still the environment variables which set the screen size.
123
124       The use_env and use_tioctl routines combine as summarized here:
125
126           use_env   use_tioctl   Summary
127           ────────────────────────────────────────────────────────────────
128           TRUE      FALSE        This is the default  behavior.   ncurses
129                                  uses operating system calls unless over‐
130                                  ridden by $LINES or $COLUMNS environment
131                                  variables.
132
133           TRUE      TRUE         ncurses   updates  $LINES  and  $COLUMNS
134                                  based on operating system calls.
135           FALSE     TRUE         ncurses ignores $LINES and $COLUMNS, us‐
136                                  es  operating  system  calls  to  obtain
137                                  size.
138           FALSE     FALSE        ncurses relies on the terminal  database
139                                  to determine size.
140
141   putwin/getwin
142       The  putwin routine writes all data associated with window (or pad) win
143       into the file to which filep points.  This information can be later re‐
144       trieved using the getwin function.
145
146       The  getwin  routine  reads  window  related data stored in the file by
147       putwin.  The routine then creates and initializes a  new  window  using
148       that  data.   It  returns a pointer to the new window.  There are a few
149       caveats:
150
151       •   the data written is a copy of the WINDOW structure, and its associ‐
152           ated  character cells.  The format differs between the wide-charac‐
153           ter (ncursesw) and non-wide (ncurses) libraries.  You can  transfer
154           data between the two, however.
155
156       •   the  retrieved  window  is always created as a top-level window (or
157           pad), rather than a subwindow.
158
159       •   the window's character cells contain the color pair value, but  not
160           the  actual  color  numbers.   If cells in the retrieved window use
161           color pairs which have not been created in  the  application  using
162           init_pair, they will not be colored when the window is refreshed.
163
164   delay_output
165       The  delay_output  routine  inserts  an ms millisecond pause in output.
166       This routine should not be used extensively because padding  characters
167       are  used  rather  than a CPU pause.  If no padding character is speci‐
168       fied, this uses napms to perform the delay.
169
170   flushinp
171       The flushinp routine throws away any typeahead that has been  typed  by
172       the user and has not yet been read by the program.
173

RETURN VALUE

175       Except  for  flushinp,  routines that return an integer return ERR upon
176       failure and OK (SVr4 specifies only "an integer value other than  ERR")
177       upon successful completion.
178
179       Routines that return pointers return NULL on error.
180
181       X/Open does not define any error conditions.  In this implementation
182
183          flushinp
184               returns an error if the terminal was not initialized.
185
186          putwin
187               returns  an  error if the associated fwrite calls return an er‐
188               ror.
189

PORTABILITY

191   filter
192       The SVr4 documentation describes the  action  of  filter  only  in  the
193       vaguest  terms.   The  description  here is adapted from the XSI Curses
194       standard (which erroneously fails to describe the disabling of cuu).
195
196   keyname
197       The keyname function may return the names of user-defined string  capa‐
198       bilities  which  are defined in the terminfo entry via the -x option of
199       tic.  This implementation automatically assigns at run-time keycodes to
200       user-defined  strings  which  begin  with  “k”.   The keycodes start at
201       KEY_MAX, but are not guaranteed to be the same value for different runs
202       because  user-defined  codes  are merged from all terminal descriptions
203       which have been loaded.  The use_extended_names(3X)  function  controls
204       whether  this  data  is loaded when the terminal description is read by
205       the library.
206
207   nofilter/use_tioctl
208       The nofilter and use_tioctl routines are  specific  to  ncurses.   They
209       were  not  supported on Version 7, BSD or System V implementations.  It
210       is recommended that any code depending on ncurses extensions be  condi‐
211       tioned using NCURSES_VERSION.
212
213   putwin/getwin file-format
214       The putwin and getwin functions have several issues with portability:
215
216       •   The  files  written  and read by these functions use an implementa‐
217           tion-specific format.  Although the format is an obvious target for
218           standardization, it has been overlooked.
219
220           Interestingly  enough,  according to the copyright dates in Solaris
221           source, the functions (along with scr_init, etc.)  originated  with
222           the University of California, Berkeley (in 1982) and were later (in
223           1988) incorporated into SVr4.  Oddly, there are no  such  functions
224           in the 4.3BSD curses sources.
225
226       •   Most implementations simply dump the binary WINDOW structure to the
227           file.  These include SVr4 curses, NetBSD and PDCurses, as  well  as
228           older ncurses versions.  This implementation (as well as the X/Open
229           variant of Solaris curses, dated 1995) uses textual dumps.
230
231           The implementations which  use  binary  dumps  use  block-I/O  (the
232           fwrite  and  fread  functions).   Those  that use textual dumps use
233           buffered-I/O.  A few applications may happen to write extra data in
234           the  file  using these functions.  Doing that can run into problems
235           mixing block- and buffered-I/O.  This  implementation  reduces  the
236           problem  on writes by flushing the output.  However, reading from a
237           file written using mixed schemes may not be successful.
238
239   unctrl/wunctrl
240       The XSI Curses standard, Issue 4 describes these functions.  It  states
241       that unctrl and wunctrl will return a null pointer if unsuccessful, but
242       does not define any error conditions.  This implementation  checks  for
243       three cases:
244
245       •   the  parameter  is  a  7-bit  US-ASCII code.  This is the case that
246           X/Open Curses documented.
247
248       •   the parameter is in the range 128-159, i.e., a C1 control code.  If
249           use_legacy_coding(3X)  has  been  called with a 2 parameter, unctrl
250           returns the parameter, i.e., a one-character string with the param‐
251           eter  as  the  first  character.  Otherwise, it returns “~@”, “~A”,
252           etc., analogous to “^@”, “^A”, C0 controls.
253
254           X/Open Curses does not document whether unctrl can be called before
255           initializing curses.  This implementation permits that, and returns
256           the “~@”, etc., values in that case.
257
258       •   parameter values outside the 0 to 255 range.  unctrl returns a null
259           pointer.
260
261       The strings returned by unctrl in this implementation are determined at
262       compile time, showing C1 controls from the upper-128 codes with  a  “~”
263       prefix  rather  than “^”.  Other implementations have different conven‐
264       tions.  For example, they may show both sets of control characters with
265       “^”, and strip the parameter to 7 bits.  Or they may ignore C1 controls
266       and treat all of the upper-128 codes as printable.  This implementation
267       uses  8  bits  but  does  not modify the string to reflect locale.  The
268       use_legacy_coding(3X) function allows the caller to change  the  output
269       of unctrl.
270
271       Likewise,  the meta(3X) function allows the caller to change the output
272       of keyname, i.e., it determines whether to  use  the  “M-”  prefix  for
273       “meta”  keys  (codes  in  the  range 128 to 255).  Both use_legacy_cod‐
274       ing(3X) and meta(3X) succeed only after curses is initialized.   X/Open
275       Curses  does  not  document  the  treatment  of codes 128 to 159.  When
276       treating them as “meta” keys (or if keyname is called before initializ‐
277       ing curses), this implementation returns strings “M-^@”, “M-^A”, etc.
278
279       X/Open Curses documents unctrl as declared in <unctrl.h>, which ncurses
280       does.  However, ncurses' <curses.h> includes <unctrl.h>,  matching  the
281       behavior of SVr4 curses.  Other implementations may not do that.
282
283   use_env/use_tioctl
284       If  ncurses  is  configured  to provide the sp-functions extension, the
285       state of use_env and use_tioctl may be  updated  before  creating  each
286       screen  rather  than  once  only  (curs_sp_funcs(3X)).  This feature of
287       use_env is not provided by other implementation of curses.
288

SEE ALSO

290       curses(3X),   curs_initscr(3X),    curs_inopts(3X),    curs_kernel(3X),
291       curs_scr_dump(3X),  curs_sp_funcs(3X),  curs_variables(3X), legacy_cod‐
292       ing(3X).
293
294
295
296                                                                 curs_util(3X)
Impressum