1curs_util(3X) curs_util(3X)
2
6 delay_output, filter, flushinp, getwin, key_name, keyname, nofilter,
7 putwin, unctrl, use_env, wunctrl - miscellaneous curses utility
8 routines
9
11 #include <curses.h>
12 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 int putwin(WINDOW *win, FILE *filep);
21 WINDOW *getwin(FILE *filep);
22 int delay_output(int ms);
23 int flushinp(void);
24
26 The unctrl routine returns a character string which is a printable rep‐
27 resentation of the character c, ignoring attributes. Control charac‐
28 ters are displayed in the ^X notation. Printing characters are dis‐
29 played as is. The corresponding wunctrl returns a printable represen‐
30 tation of a wide-character.
31 The keyname routine returns a character string corresponding to the key
33 c. Control characters are displayed in the ^X notation. Values above
34 128 are either meta characters, shown in the M-X notation, or the names
35 of function keys, or null. The corresponding key_name returns a char‐
36 acter string corresponding to the wide-character value w. The two
37 functions do not return the same set of strings; the latter returns
38 null where the former would display a meta character.
39 The filter routine, if used, must be called before initscr or newterm
41 are called. The effect is that, during those calls, LINES is set to 1;
42 the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled;
43 and the home string is set to the value of cr.
44 The nofilter routine cancels the effect of a preceding filter call.
46 That allows the caller to initialize a screen on a different device,
47 using a different value of $TERM. The limitation arises because the
48 filter routine modifies the in-memory copy of the terminal information.
49 The use_env routine, if used, is called before initscr or newterm are
51 called. When called with FALSE as an argument, the values of lines and
52 columns specified in the terminfo database will be used, even if envi‐
53 ronment variables LINES and COLUMNS (used by default) are set, or if
54 curses is running in a window (in which case default behavior would be
55 to use the window size if LINES and COLUMNS are not set). Note that
56 setting LINES or COLUMNS overrides the corresponding size which may be
57 obtained from the operating system.
58 The putwin routine writes all data associated with window win into the
60 file to which filep points. This information can be later retrieved
61 using the getwin function.
62 The getwin routine reads window related data stored in the file by
64 putwin. The routine then creates and initializes a new window using
65 that data. It returns a pointer to the new window.
66 The delay_output routine inserts an ms millisecond pause in output.
68 This routine should not be used extensively because padding characters
69 are used rather than a CPU pause. If no padding character is speci‐
70 fied, this uses napms to perform the delay.
71 The flushinp routine throws away any typeahead that has been typed by
73 the user and has not yet been read by the program.
74
76 Except for flushinp, routines that return an integer return ERR upon
77 failure and OK (SVr4 specifies only "an integer value other than ERR")
78 upon successful completion.
79 Routines that return pointers return NULL on error.
81 X/Open does not define any error conditions. In this implementation
83 flushinp
85 returns an error if the terminal was not initialized.
86 putwin
88 returns an error if the associated fwrite calls return an
89 error.
90
92 The XSI Curses standard, Issue 4 describes these functions. It states
93 that unctrl and wunctrl will return a null pointer if unsuccessful, but
94 does not define any error conditions. This implementation checks for
95 three cases:
96 - the parameter is a 7-bit US-ASCII code. This is the case
98 that X/Open Curses documented.
99 - the parameter is in the range 128-159, i.e., a C1 control
101 code. If use_legacy_coding has been called with a 2 param‐
102 eter, unctrl returns the parameter, i.e., a one-character
103 string with the parameter as the first character. Other‐
104 wise, it returns ``~@'', ``~A'', etc., analogous to ``^@'',
105 ``^A'', C0 controls.
106 X/Open Curses does not document whether unctrl can be
108 called before initializing curses. This implementation
109 permits that, and returns the ``~@'', etc., values in that
110 case.
111 - parameter values outside the 0 to 255 range. unctrl re‐
113 turns a null pointer.
114 The SVr4 documentation describes the action of filter only in the
116 vaguest terms. The description here is adapted from the XSI Curses
117 standard (which erroneously fails to describe the disabling of cuu).
118 The strings returned by unctrl in this implementation are determined at
120 compile time, showing C1 controls from the upper-128 codes with a `~'
121 prefix rather than `^'. Other implementations have different conven‐
122 tions. For example, they may show both sets of control characters with
123 `^', and strip the parameter to 7 bits. Or they may ignore C1 controls
124 and treat all of the upper-128 codes as printable. This implementation
125 uses 8 bits but does not modify the string to reflect locale. The
126 use_legacy_coding function allows the caller to change the output of
127 unctrl.
128 Likewise, the meta function allows the caller to change the output of
130 keyname, i.e., it determines whether to use the `M-' prefix for
131 ``meta'' keys (codes in the range 128 to 255). Both use_legacy_coding
132 and meta succeed only after curses is initialized. X/Open Curses does
133 not document the treatment of codes 128 to 159. When treating them as
134 ``meta'' keys (or if keyname is called before initializing curses),
135 this implementation returns strings ``M-^@'', ``M-^A'', etc.
136 The keyname function may return the names of user-defined string capa‐
138 bilities which are defined in the terminfo entry via the -x option of
139 tic. This implementation automatically assigns at run-time keycodes to
140 user-defined strings which begin with "k". The keycodes start at
141 KEY_MAX, but are not guaranteed to be the same value for different runs
142 because user-defined codes are merged from all terminal descriptions
143 which have been loaded.
144 The nofilter routine is specific to ncurses. It was not supported on
146 Version 7, BSD or System V implementations. It is recommended that any
147 code depending on ncurses extensions be conditioned using NCURSES_VER‐
148 SION.
149
151 legacy_coding(3X), curses(3X), curs_initscr(3X), curs_kernel(3X),
152 curs_scr_dump(3X), legacy_coding(3X).
153 curs_util(3X)