| 1 |
'\" t |
| 2 |
.\"*************************************************************************** |
| 3 |
.\" Copyright 2018-2024,2025 Thomas E. Dickey * |
| 4 |
.\" Copyright 1998-2015,2017 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 |
.\" |
| 31 |
.\" $Id: curs_util.3x,v 1.151 2025/11/12 01:06:36 tom Exp $ |
| 32 |
.TH util 3NCURSES 2025-11-11 "ncurses 6.6" "Library calls" |
| 33 |
.ie \n(.g \{\ |
| 34 |
.ds `` \(lq |
| 35 |
.ds '' \(rq |
| 36 |
.ds ^ \(ha |
| 37 |
.ds ~ \(ti |
| 38 |
.\} |
| 39 |
.el \{\ |
| 40 |
.ie t .ds `` `` |
| 41 |
.el .ds `` "" |
| 42 |
.ie t .ds '' '' |
| 43 |
.el .ds '' "" |
| 44 |
.ds ^ ^ |
| 45 |
.ds ~ ~ |
| 46 |
.\} |
| 47 |
. |
| 48 |
.de bP |
| 49 |
.ie n .IP \(bu 4 |
| 50 |
.el .IP \(bu 2 |
| 51 |
.. |
| 52 |
.SH NAME |
| 53 |
\fB\%delay_output\fP, |
| 54 |
\fB\%filter\fP, |
| 55 |
\fB\%flushinp\fP, |
| 56 |
\fB\%getwin\fP, |
| 57 |
\fB\%key_name\fP, |
| 58 |
\fB\%keyname\fP, |
| 59 |
\fB\%nofilter\fP, |
| 60 |
\fB\%putwin\fP, |
| 61 |
\fB\%unctrl\fP, |
| 62 |
\fB\%use_env\fP, |
| 63 |
\fB\%use_tioctl\fP, |
| 64 |
\fB\%wunctrl\fP \- |
| 65 |
miscellaneous \fIcurses\fR utility routines |
| 66 |
.SH SYNOPSIS |
| 67 |
.nf |
| 68 |
\fB#include <curses.h> |
| 69 |
.PP |
| 70 |
\fBconst char * unctrl(chtype \fIch\fP); |
| 71 |
\fBwchar_t * wunctrl(cchar_t * \fIwch\fP); |
| 72 |
.PP |
| 73 |
\fBconst char * keyname(int \fIc\fP); |
| 74 |
\fBconst char * key_name(wchar_t \fIwc\fP); |
| 75 |
.PP |
| 76 |
\fBvoid filter(void); |
| 77 |
\fI/* extension */ |
| 78 |
\fBvoid nofilter(void); |
| 79 |
.PP |
| 80 |
\fBvoid use_env(bool \fIbf\fP); |
| 81 |
\fI/* extension */ |
| 82 |
\fBvoid use_tioctl(bool \fIbf\fP); |
| 83 |
.PP |
| 84 |
\fBint putwin(WINDOW * \fIwin\fP, FILE * \fIfilep\fP); |
| 85 |
\fBWINDOW * getwin(FILE * \fIfilep\fP); |
| 86 |
.PP |
| 87 |
\fBint delay_output(int \fIms\fP); |
| 88 |
.PP |
| 89 |
\fBint flushinp(void); |
| 90 |
.fi |
| 91 |
.SH DESCRIPTION |
| 92 |
.SS "unctrl, wunctrl" |
| 93 |
.B unctrl |
| 94 |
returns a null-terminated character string printably representing the |
| 95 |
.I curses |
| 96 |
character |
| 97 |
.IR ch , |
| 98 |
often one that originated in keyboard input; |
| 99 |
see \fBgetch\fP(3NCURSES). |
| 100 |
.bP |
| 101 |
Printable characters represent themselves as a one-character string. |
| 102 |
.bP |
| 103 |
Control characters are expressed in |
| 104 |
.BI \*^ X |
| 105 |
notation, |
| 106 |
where |
| 107 |
.I X |
| 108 |
is the printable symbol of the control code's value plus 32 |
| 109 |
in the ISO\ 646/\*(``ASCII\*('' character set. |
| 110 |
.bP |
| 111 |
DEL |
| 112 |
(character code 127) |
| 113 |
is represented as |
| 114 |
.BR \*^? . |
| 115 |
.bP |
| 116 |
A character code greater than 127 is represented in one of two ways. |
| 117 |
.IP |
| 118 |
If the screen has not been initialized or is in meta mode |
| 119 |
(see \fBmeta\fP(3NCURSES)), |
| 120 |
it is expressed in |
| 121 |
.BI M- X |
| 122 |
notation, |
| 123 |
where X |
| 124 |
is the representation of the code's value minus 128, |
| 125 |
as described above. |
| 126 |
.IP |
| 127 |
If the screen is not in meta mode, |
| 128 |
the character code is assumed to represent itself. |
| 129 |
It nevertheless may not be printable; |
| 130 |
this is the case for character codes 128-159 in ISO\ 8859 encodings. |
| 131 |
.IP |
| 132 |
.IR \%ncurses 's |
| 133 |
\fB\%use_legacy_coding\fP(3NCURSES) |
| 134 |
function configures |
| 135 |
.BR \%unctrl 's |
| 136 |
handling of these character codes. |
| 137 |
.PP |
| 138 |
.B \%wunctrl |
| 139 |
returns a null-terminated wide-character string printably representing |
| 140 |
the |
| 141 |
.I curses |
| 142 |
complex character |
| 143 |
.IR wch . |
| 144 |
.PP |
| 145 |
Both functions ignore the attributes and color pair selection |
| 146 |
of their argument. |
| 147 |
.SS "keyname, key_name" |
| 148 |
The \fBkeyname\fP routine returns a character string |
| 149 |
corresponding to the key \fIc\fP. |
| 150 |
Key codes are different from character codes. |
| 151 |
.bP |
| 152 |
Key codes below 256 are characters. |
| 153 |
They are displayed using \fBunctrl\fP. |
| 154 |
.bP |
| 155 |
Values above 256 may be the codes for function keys. |
| 156 |
The function key name is displayed. |
| 157 |
.bP |
| 158 |
Otherwise |
| 159 |
(if there is no corresponding name and the key is not a character) |
| 160 |
the function returns null, |
| 161 |
to denote an error. |
| 162 |
X/Open also lists an \*(``UNKNOWN KEY\*('' return value, |
| 163 |
which some implementations return rather than null. |
| 164 |
.LP |
| 165 |
The corresponding \fBkey_name\fP returns |
| 166 |
a multibyte character string corresponding |
| 167 |
to the wide-character value \fIwc\fP. |
| 168 |
The two functions |
| 169 |
(\fBkeyname\fP and \fBkey_name\fP) |
| 170 |
do not return the same set of strings: |
| 171 |
.bP |
| 172 |
\fBkeyname\fP returns null where \fBkey_name\fP |
| 173 |
would display a meta character. |
| 174 |
.bP |
| 175 |
\fBkey_name\fP does not return the name of a function key. |
| 176 |
.SS "filter, nofilter" |
| 177 |
The \fBfilter\fP routine, |
| 178 |
if used, |
| 179 |
must be called before \fBinitscr\fP or |
| 180 |
\fBnewterm\fP are called. |
| 181 |
Calling \fBfilter\fP causes these changes in initialization: |
| 182 |
.bP |
| 183 |
\fBLINES\fP is set to 1; |
| 184 |
.bP |
| 185 |
the capabilities |
| 186 |
\fBclear\fP, |
| 187 |
\fBcud1\fP, |
| 188 |
\fBcud\fP, |
| 189 |
\fBcup\fP, |
| 190 |
\fBcuu1\fP, |
| 191 |
\fBcuu\fP, |
| 192 |
\fBvpa\fP |
| 193 |
are disabled; |
| 194 |
.bP |
| 195 |
the capability \fBed\fP is disabled if \fBbce\fP is set; |
| 196 |
.bP |
| 197 |
and the \fBhome\fP string is set to the value of \fBcr\fP. |
| 198 |
.PP |
| 199 |
The \fBnofilter\fP routine cancels the effect |
| 200 |
of a preceding \fBfilter\fP call. |
| 201 |
That allows the caller to initialize a screen on a different device, |
| 202 |
using a different value of \fB$TERM\fP. |
| 203 |
The limitation arises because the \fBfilter\fP routine modifies the |
| 204 |
in-memory copy of the terminal information. |
| 205 |
.SS use_env |
| 206 |
The \fBuse_env\fP routine, |
| 207 |
if used, |
| 208 |
should be called before \fBinitscr\fP or |
| 209 |
\fBnewterm\fP are called |
| 210 |
(because those compute the screen size). |
| 211 |
It modifies the way \fI\%ncurses\fP treats environment variables |
| 212 |
when determining the screen size. |
| 213 |
.bP |
| 214 |
Normally \fI\%ncurses\fP looks first at the terminal database for the |
| 215 |
screen size. |
| 216 |
.IP |
| 217 |
If \fBuse_env\fP was called with \fBFALSE\fP for parameter, |
| 218 |
it stops here unless |
| 219 |
\fBuse_tioctl\fP was also called with \fBTRUE\fP for parameter. |
| 220 |
.bP |
| 221 |
Then it asks for the screen size via operating system calls. |
| 222 |
If successful, |
| 223 |
it overrides the values from the terminal database. |
| 224 |
.bP |
| 225 |
Finally |
| 226 |
(unless \fBuse_env\fP was called with \fBFALSE\fP parameter), |
| 227 |
\fI\%ncurses\fP examines the \fILINES\fP or \fI\%COLUMNS\fP environment |
| 228 |
variables, |
| 229 |
using a value in those to override the results |
| 230 |
from the operating system or terminal database. |
| 231 |
.IP |
| 232 |
.I curses |
| 233 |
also updates the screen size in response to |
| 234 |
.IR \%SIGWINCH "," |
| 235 |
unless overridden by the \fILINES\fP or \fI\%COLUMNS\fP environment |
| 236 |
variables, |
| 237 |
.SS use_tioctl |
| 238 |
The \fBuse_tioctl\fP routine, |
| 239 |
if used, |
| 240 |
should be called before \fBinitscr\fP or \fBnewterm\fP are called |
| 241 |
(because those compute the screen size). |
| 242 |
After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument, |
| 243 |
\fI\%ncurses\fP modifies the last step in its computation |
| 244 |
of screen size as follows: |
| 245 |
.bP |
| 246 |
checks whether the \fILINES\fP and \fI\%COLUMNS\fP environment variables |
| 247 |
are set to a number greater than zero. |
| 248 |
.bP |
| 249 |
for each, |
| 250 |
\fI\%ncurses\fP updates the corresponding environment variable |
| 251 |
with the value that it has obtained via operating system call |
| 252 |
or from the terminal database. |
| 253 |
.bP |
| 254 |
\fI\%ncurses\fP re-fetches the value of the environment variables so |
| 255 |
that it is still the environment variables that set the screen size. |
| 256 |
.PP |
| 257 |
The \fB\%use_env\fP and \fB\%use_tioctl\fP routines combine as follows. |
| 258 |
.IP |
| 259 |
.TS |
| 260 |
Lb Lb Lb |
| 261 |
Lb Lb Lw(29n)x. |
| 262 |
use_env use_tioctl Summary |
| 263 |
_ |
| 264 |
TRUE FALSE T{ |
| 265 |
\fI\%ncurses\fP uses operating system calls |
| 266 |
unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment |
| 267 |
variables; |
| 268 |
default. |
| 269 |
T} |
| 270 |
TRUE TRUE T{ |
| 271 |
\fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on |
| 272 |
operating system calls. |
| 273 |
T} |
| 274 |
FALSE TRUE T{ |
| 275 |
\fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP, |
| 276 |
using operating system calls to obtain size. |
| 277 |
T} |
| 278 |
.TE |
| 279 |
.SS "putwin, getwin" |
| 280 |
The \fBputwin\fP routine writes all data associated |
| 281 |
with window |
| 282 |
(or pad) |
| 283 |
\fIwin\fP into |
| 284 |
the file to which \fIfilep\fP points. |
| 285 |
This information can be later retrieved |
| 286 |
using the \fBgetwin\fP function. |
| 287 |
.PP |
| 288 |
The \fBgetwin\fP routine reads window related data stored in the file by |
| 289 |
\fBputwin\fP. |
| 290 |
The routine then creates and initializes a new window using that |
| 291 |
data. |
| 292 |
It returns a pointer to the new window. |
| 293 |
There are a few caveats: |
| 294 |
.bP |
| 295 |
the data written is a copy of the \fI\%WINDOW\fP structure, |
| 296 |
and its associated character cells. |
| 297 |
The format differs between the wide-character \%(\fIncursesw\fP) and |
| 298 |
non-wide \%(\fIncurses\fP) libraries. |
| 299 |
You can transfer data between the two, |
| 300 |
however. |
| 301 |
.bP |
| 302 |
the retrieved window is always created as a top-level window |
| 303 |
(or pad), |
| 304 |
rather than a subwindow. |
| 305 |
.bP |
| 306 |
the window's character cells contain the color pair \fIvalue\fP, |
| 307 |
but not the actual color \fInumbers\fP. |
| 308 |
If cells in the retrieved window use color pairs that have not been |
| 309 |
created in the application using \fBinit_pair\fP, |
| 310 |
they will not be colored when the window is refreshed. |
| 311 |
.SS delay_output |
| 312 |
The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause |
| 313 |
in output. |
| 314 |
Employ this function judiciously when terminal output uses padding, |
| 315 |
because \fI\%ncurses\fP transmits null characters |
| 316 |
(consuming CPU and I/O resources) |
| 317 |
instead of sleeping and requesting resumption from the operating system. |
| 318 |
Padding is used unless: |
| 319 |
.bP |
| 320 |
the terminal description has \fBnpc\fP (\fBno_pad_char\fP) capability, |
| 321 |
or |
| 322 |
.bP |
| 323 |
the environment variable \fB\%NCURSES_NO_PADDING\fP is set. |
| 324 |
.PP |
| 325 |
If padding is not in use, |
| 326 |
\fI\%ncurses\fP uses \fBnapms\fP to perform the delay. |
| 327 |
If the value of \fIms\fP exceeds 30,000 |
| 328 |
(thirty seconds), |
| 329 |
it is capped at that value. |
| 330 |
.SS flushinp |
| 331 |
The \fBflushinp\fP routine throws away any typeahead |
| 332 |
that has been typed by the user |
| 333 |
and has not yet been read by the program. |
| 334 |
.SH RETURN VALUE |
| 335 |
Except for |
| 336 |
.BR \%flushinp "," |
| 337 |
functions that return integers return |
| 338 |
.B ERR |
| 339 |
upon failure and |
| 340 |
.B OK |
| 341 |
upon success. |
| 342 |
.PP |
| 343 |
Functions that return pointers return a null pointer on failure. |
| 344 |
.PP |
| 345 |
In |
| 346 |
.IR \%ncurses "," |
| 347 |
.bP |
| 348 |
.B \%flushinp |
| 349 |
returns |
| 350 |
.B ERR |
| 351 |
if the terminal was not initialized, |
| 352 |
and |
| 353 |
.bP |
| 354 |
.B \%putwin |
| 355 |
returns |
| 356 |
.B ERR |
| 357 |
if its associated \fIwrite\fP(2) calls return |
| 358 |
.BR ERR "." |
| 359 |
.SH NOTES |
| 360 |
.B \%wunctrl |
| 361 |
is part of |
| 362 |
.IR \%ncurses "'s" |
| 363 |
wide-character API, |
| 364 |
and is not available in its non-wide-character configuration. |
| 365 |
.SH PORTABILITY |
| 366 |
X/Open Curses Issue\ 4 describes these functions. |
| 367 |
It specifies no error conditions for them. |
| 368 |
.PP |
| 369 |
SVr4 describes a successful return value only as |
| 370 |
\*(``an integer value other than |
| 371 |
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 542 |
| 372 |
.SS filter |
| 373 |
The SVr4 documentation describes the action of \fBfilter\fP |
| 374 |
only in the vaguest terms. |
| 375 |
The description here is adapted from X/Open Curses |
| 376 |
(which erroneously fails to describe the disabling of \fBcuu\fP). |
| 377 |
.SS "delay_output padding" |
| 378 |
The limitation to 30 seconds |
| 379 |
and the use of \fBnapms\fP |
| 380 |
differ from other implementations. |
| 381 |
.bP |
| 382 |
SVr4 |
| 383 |
.I curses |
| 384 |
does not delay if no padding character is available. |
| 385 |
.bP |
| 386 |
NetBSD |
| 387 |
.I curses |
| 388 |
uses \fBnapms\fP when no padding character is available, |
| 389 |
but does not take timing into account when using the padding character. |
| 390 |
.PP |
| 391 |
Neither limits the delay. |
| 392 |
.SS keyname |
| 393 |
The \fBkeyname\fP function may return the names of user-defined |
| 394 |
string capabilities that are defined in the terminfo entry |
| 395 |
via the \fB\-x\fP |
| 396 |
option of \fBtic\fP. |
| 397 |
This implementation automatically assigns at run-time key codes to |
| 398 |
user-defined strings that begin with \*(``k\*(''. |
| 399 |
The key codes start at KEY_MAX, |
| 400 |
but are not guaranteed to be the same value for different runs |
| 401 |
because user-defined codes are merged |
| 402 |
from all terminal descriptions that have been loaded. |
| 403 |
The \fBuse_extended_names\fP(3NCURSES) function controls whether this data is |
| 404 |
loaded when the terminal description is read by the library. |
| 405 |
.SS "nofilter, use_tioctl" |
| 406 |
The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to |
| 407 |
\fI\%ncurses\fP. |
| 408 |
They were not supported on Version 7, |
| 409 |
BSD or System V implementations. |
| 410 |
It is recommended that any code depending on \fI\%ncurses\fP extensions |
| 411 |
be conditioned using \fBNCURSES_VERSION\fP. |
| 412 |
.SS "putwin/getwin file-format" |
| 413 |
The \fBputwin\fP and \fBgetwin\fP functions have several issues with |
| 414 |
portability: |
| 415 |
.bP |
| 416 |
The files written and read by these functions |
| 417 |
use an implementation-specific format. |
| 418 |
Although the format is an obvious target for standardization, |
| 419 |
it has been overlooked. |
| 420 |
.IP |
| 421 |
Interestingly enough, |
| 422 |
according to the copyright dates in Solaris source, |
| 423 |
the functions |
| 424 |
(along with \fBscr_init\fP, |
| 425 |
etc.\&) |
| 426 |
originated with the University of California, |
| 427 |
Berkeley |
| 428 |
(in 1982) |
| 429 |
and were later |
| 430 |
(in 1988) |
| 431 |
incorporated into SVr4. |
| 432 |
Oddly, |
| 433 |
there are no such functions in the 4.3BSD |
| 434 |
.I curses |
| 435 |
sources. |
| 436 |
.bP |
| 437 |
Most implementations simply dump the binary |
| 438 |
.I \%WINDOW |
| 439 |
structure |
| 440 |
to the file. |
| 441 |
These include SVr4 |
| 442 |
.IR curses , |
| 443 |
NetBSD |
| 444 |
.IR curses , |
| 445 |
and |
| 446 |
.IR \%PDCurses , |
| 447 |
as well as older \fI\%ncurses\fP versions. |
| 448 |
This implementation |
| 449 |
(as well as |
| 450 |
.IR \%xcurses "," |
| 451 |
the X/Open variant of Solaris |
| 452 |
.IR curses "," |
| 453 |
dated 1995) |
| 454 |
uses textual dumps. |
| 455 |
.IP |
| 456 |
The implementations that use binary dumps use block I/O |
| 457 |
(\fIwrite\fP(2) and \fIread\fP(2) functions). |
| 458 |
Those that use textual dumps use buffered I/O. |
| 459 |
A few applications may happen to write extra data in the file using |
| 460 |
these functions. |
| 461 |
Doing that can run into problems mixing block and buffered I/O. |
| 462 |
This implementation reduces the problem on writes by flushing the |
| 463 |
output. |
| 464 |
However, |
| 465 |
reading from a file written using mixed schemes may not be successful. |
| 466 |
.SS "unctrl, wunctrl" |
| 467 |
X/Open Curses Issue\ 4 describes these functions. |
| 468 |
It specifies no error conditions for them. |
| 469 |
It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer |
| 470 |
if unsuccessful. |
| 471 |
This implementation checks for three cases: |
| 472 |
.bP |
| 473 |
the parameter is a 7-bit US\-ASCII code. |
| 474 |
This is the case that X/Open Curses documented. |
| 475 |
.bP |
| 476 |
the parameter is in the range 128\-159, |
| 477 |
i.e., |
| 478 |
a C1 control code. |
| 479 |
If \fB\%use_legacy_coding\fP(3NCURSES) has been called with a \fB2\fP parameter, |
| 480 |
\fBunctrl\fP returns the parameter, |
| 481 |
i.e., |
| 482 |
a one-character string with |
| 483 |
the parameter as the first character. |
| 484 |
Otherwise, |
| 485 |
it returns \*(``\*~@\*('', |
| 486 |
\*(``\*~A\*('', |
| 487 |
etc., |
| 488 |
analogous to \*(``\*^@\*('', |
| 489 |
\*(``\*^A\*('', |
| 490 |
C0 controls. |
| 491 |
.IP |
| 492 |
X/Open Curses does not document whether \fBunctrl\fP can be called |
| 493 |
before initializing |
| 494 |
.IR curses "." |
| 495 |
This implementation permits that, |
| 496 |
and returns the \*(``\*~@\*('', |
| 497 |
etc., |
| 498 |
values in that case. |
| 499 |
.bP |
| 500 |
parameter values outside the 0 to 255 range. |
| 501 |
\fBunctrl\fP returns a null pointer. |
| 502 |
.PP |
| 503 |
The strings returned by \fBunctrl\fP in this implementation |
| 504 |
are determined at compile time, |
| 505 |
showing C1 controls from the upper-128 codes |
| 506 |
with a \*(``\*~\*('' prefix rather than \*(``\*^\*(''. |
| 507 |
Other implementations have different conventions. |
| 508 |
For example, |
| 509 |
they may show both sets of control characters with \*(``\*^\*('', |
| 510 |
and strip the parameter to 7 bits. |
| 511 |
Or they may ignore C1 controls and treat all of the upper-128 codes as |
| 512 |
printable. |
| 513 |
This implementation uses 8 bits |
| 514 |
but does not modify the string to reflect locale. |
| 515 |
The \fB\%use_legacy_coding\fP(3NCURSES) function allows the caller to |
| 516 |
change the output of \fBunctrl\fP. |
| 517 |
.PP |
| 518 |
Likewise, |
| 519 |
the \fBmeta\fP(3NCURSES) function allows the caller to change the output |
| 520 |
of \fBkeyname\fP, |
| 521 |
i.e., |
| 522 |
it determines whether to use the \*(``M\-\*('' prefix |
| 523 |
for \*(``meta\*('' keys (codes in the range 128 to 255). |
| 524 |
Both \fB\%use_legacy_coding\fP(3NCURSES) and \fBmeta\fP(3NCURSES) succeed only after |
| 525 |
.I curses |
| 526 |
is initialized. |
| 527 |
X/Open Curses does not document the treatment of codes 128 to 159. |
| 528 |
When treating them as \*(``meta\*('' keys |
| 529 |
(or if \fBkeyname\fP is called before initializing |
| 530 |
.IR curses ")," |
| 531 |
this implementation returns strings \*(``M\-\*^@\*('', |
| 532 |
\*(``M\-\*^A\*('', |
| 533 |
etc. |
| 534 |
.PP |
| 535 |
X/Open Curses documents |
| 536 |
.I \%unctrl |
| 537 |
as declared in |
| 538 |
.IR \%unctrl.h "," |
| 539 |
which |
| 540 |
.I \%ncurses |
| 541 |
does. |
| 542 |
However, |
| 543 |
.IR \%ncurses 's |
| 544 |
.I \%curses.h |
| 545 |
includes |
| 546 |
.IR \%unctrl.h "," |
| 547 |
matching the behavior of SVr4 |
| 548 |
.IR curses "." |
| 549 |
Other implementations may not do that. |
| 550 |
.SS "use_env, use_tioctl" |
| 551 |
If \fI\%ncurses\fP is configured to provide the sp-functions extension, |
| 552 |
the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before |
| 553 |
creating each \fIscreen\fP rather than once only |
| 554 |
(\fBsp_funcs\fP(3NCURSES)). |
| 555 |
This feature of \fBuse_env\fP |
| 556 |
is not provided by other implementations of |
| 557 |
.IR curses "." |
| 558 |
.SH HISTORY |
| 559 |
4BSD (1980) |
| 560 |
introduced |
| 561 |
.IR \%unctrl "," |
| 562 |
defining it as a macro |
| 563 |
in |
| 564 |
.IR \%unctrl.h "." |
| 565 |
.PP |
| 566 |
SVr2 (1984) |
| 567 |
added |
| 568 |
.IR \%delay_output "," |
| 569 |
.IR \%flushinp "," |
| 570 |
and |
| 571 |
.IR \%keyname "." |
| 572 |
.PP |
| 573 |
SVr3 (1987) supplied |
| 574 |
.IR \%filter "." |
| 575 |
Later that year, |
| 576 |
SVr3.1 brought |
| 577 |
.I \%getwin |
| 578 |
and |
| 579 |
.IR \%putwin "," |
| 580 |
reading and writing window dumps |
| 581 |
with \fI\%fread\fP(3) and \fI\%fwrite\fP(3), |
| 582 |
respectively. |
| 583 |
.PP |
| 584 |
SVr4 (1989) furnished |
| 585 |
.IR \%use_env "." |
| 586 |
.PP |
| 587 |
X/Open Curses Issue\ 4 (1995) specified |
| 588 |
.I \%key_name |
| 589 |
and |
| 590 |
.IR \%wunctrl "." |
| 591 |
.PP |
| 592 |
.I \%ncurses |
| 593 |
5.6 (2006) added |
| 594 |
.IR \%nofilter "," \" 20060107 |
| 595 |
and 6.0 (2015) |
| 596 |
.IR \%use_tioctl "." \" 20120714 |
| 597 |
.SH SEE ALSO |
| 598 |
.na |
| 599 |
\fB\%ncurses\fP(3NCURSES), |
| 600 |
\fB\%initscr\fP(3NCURSES), |
| 601 |
\fB\%inopts\fP(3NCURSES), |
| 602 |
\fB\%kernel\fP(3NCURSES), |
| 603 |
\fB\%scr_dump\fP(3NCURSES), |
| 604 |
\fB\%sp_funcs\fP(3NCURSES), |
| 605 |
\fB\%curses_variables\fP(3NCURSES), |
| 606 |
\fB\%legacy_coding\fP(3NCURSES) |
| 607 |
.ad |