Debian Codegraph @

upstream/debian-trixie/man3/util.3ncurses

raw
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.139 2025/02/15 18:38:01 tom Exp $
32 .TH util 3NCURSES 2025-02-15 "ncurses 6.5" "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 \fB\%getch\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 \fB\%meta\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 \fI\%curses\fP also updates the screen size in response to
233 \fBSIGWINCH\fP,
234 unless overridden by the \fILINES\fP or \fI\%COLUMNS\fP environment
235 variables,
236 .SS use_tioctl
237 The \fBuse_tioctl\fP routine,
238 if used,
239 should be called before \fBinitscr\fP or \fBnewterm\fP are called
240 (because those compute the screen size).
241 After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument,
242 \fI\%ncurses\fP modifies the last step in its computation
243 of screen size as follows:
244 .bP
245 checks whether the \fILINES\fP and \fI\%COLUMNS\fP environment variables
246 are set to a number greater than zero.
247 .bP
248 for each,
249 \fI\%ncurses\fP updates the corresponding environment variable
250 with the value that it has obtained via operating system call
251 or from the terminal database.
252 .bP
253 \fI\%ncurses\fP re-fetches the value of the environment variables so
254 that it is still the environment variables that set the screen size.
255 .PP
256 The \fB\%use_env\fP and \fB\%use_tioctl\fP routines combine as follows.
257 .IP
258 .TS
259 lB lB lB
260 lB lB lx.
261 use_env use_tioctl Summary
262 _
263 TRUE FALSE T{
264 \fI\%ncurses\fP uses operating system calls
265 unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
266 variables;
267 default.
268 T}
269 TRUE TRUE T{
270 \fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on
271 operating system calls.
272 T}
273 FALSE TRUE T{
274 \fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
275 using operating system calls to obtain size.
276 T}
277 .TE
278 .SS "putwin, getwin"
279 The \fBputwin\fP routine writes all data associated
280 with window
281 (or pad)
282 \fIwin\fP into
283 the file to which \fIfilep\fP points.
284 This information can be later retrieved
285 using the \fBgetwin\fP function.
286 .PP
287 The \fBgetwin\fP routine reads window related data stored in the file by
288 \fBputwin\fP.
289 The routine then creates and initializes a new window using that
290 data.
291 It returns a pointer to the new window.
292 There are a few caveats:
293 .bP
294 the data written is a copy of the \fI\%WINDOW\fP structure,
295 and its associated character cells.
296 The format differs between the wide-character \%(\fIncursesw\fP) and
297 non-wide \%(\fIncurses\fP) libraries.
298 You can transfer data between the two,
299 however.
300 .bP
301 the retrieved window is always created as a top-level window
302 (or pad),
303 rather than a subwindow.
304 .bP
305 the window's character cells contain the color pair \fIvalue\fP,
306 but not the actual color \fInumbers\fP.
307 If cells in the retrieved window use color pairs that have not been
308 created in the application using \fBinit_pair\fP,
309 they will not be colored when the window is refreshed.
310 .SS delay_output
311 The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause
312 in output.
313 Employ this function judiciously when terminal output uses padding,
314 because \fI\%ncurses\fP transmits null characters
315 (consuming CPU and I/O resources)
316 instead of sleeping and requesting resumption from the operating system.
317 Padding is used unless:
318 .bP
319 the terminal description has \fBnpc\fP (\fBno_pad_char\fP) capability,
320 or
321 .bP
322 the environment variable \fB\%NCURSES_NO_PADDING\fP is set.
323 .PP
324 If padding is not in use,
325 \fI\%ncurses\fP uses \fBnapms\fP to perform the delay.
326 If the value of \fIms\fP exceeds 30,000
327 (thirty seconds),
328 it is capped at that value.
329 .SS flushinp
330 The \fBflushinp\fP routine throws away any typeahead
331 that has been typed by the user
332 and has not yet been read by the program.
333 .SH RETURN VALUE
334 Except for
335 .BR \%flushinp ","
336 functions that return integers return
337 .B ERR
338 upon failure and
339 .B OK
340 upon success.
341 .PP
342 Functions that return pointers return
343 .I NULL
344 on error.
345 .PP
346 In
347 .IR \%ncurses ","
348 .bP
349 .B \%flushinp
350 returns
351 .B ERR
352 if the terminal was not initialized,
353 and
354 .bP
355 .B \%putwin
356 returns
357 .B ERR
358 if its associated \fIwrite\fP(2) calls return
359 .BR ERR "."
360 .SH NOTES
361 .B \%wunctrl
362 is part of
363 .IR \%ncurses "'s"
364 wide-character API,
365 and is not available in its non-wide configuration.
366 .SH PORTABILITY
367 X/Open Curses Issue\ 4 describes these functions.
368 It specifies no error conditions for them.
369 .PP
370 SVr4 describes a successful return value only as
371 \*(``an integer value other than
372 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 542
373 .SS filter
374 The SVr4 documentation describes the action of \fBfilter\fP
375 only in the vaguest terms.
376 The description here is adapted from X/Open Curses
377 (which erroneously fails to describe the disabling of \fBcuu\fP).
378 .SS "delay_output padding"
379 The limitation to 30 seconds
380 and the use of \fBnapms\fP
381 differ from other implementations.
382 .bP
383 SVr4 curses does not delay if no padding character is available.
384 .bP
385 NetBSD curses uses \fBnapms\fP when no padding character is available,
386 but does not take timing into account when using the padding character.
387 .PP
388 Neither limits the delay.
389 .SS keyname
390 The \fBkeyname\fP function may return the names of user-defined
391 string capabilities that are defined in the terminfo entry
392 via the \fB\-x\fP
393 option of \fBtic\fP.
394 This implementation automatically assigns at run-time key codes to
395 user-defined strings that begin with \*(``k\*(''.
396 The key codes start at KEY_MAX,
397 but are not guaranteed to be the same value for different runs
398 because user-defined codes are merged
399 from all terminal descriptions that have been loaded.
400 The \fB\%use_extended_names\fP(3NCURSES) function controls whether this data is
401 loaded when the terminal description is read by the library.
402 .SS "nofilter, use_tioctl"
403 The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to
404 \fI\%ncurses\fP.
405 They were not supported on Version 7,
406 BSD or System V implementations.
407 It is recommended that any code depending on \fI\%ncurses\fP extensions
408 be conditioned using \fBNCURSES_VERSION\fP.
409 .SS "putwin/getwin file-format"
410 The \fBputwin\fP and \fBgetwin\fP functions have several issues with
411 portability:
412 .bP
413 The files written and read by these functions
414 use an implementation-specific format.
415 Although the format is an obvious target for standardization,
416 it has been overlooked.
417 .IP
418 Interestingly enough,
419 according to the copyright dates in Solaris source,
420 the functions
421 (along with \fBscr_init\fP,
422 etc.\&)
423 originated with the University of California,
424 Berkeley
425 (in 1982)
426 and were later
427 (in 1988)
428 incorporated into SVr4.
429 Oddly,
430 there are no such functions in the 4.3BSD curses sources.
431 .bP
432 Most implementations simply dump the binary \fI\%WINDOW\fP structure
433 to the file.
434 These include SVr4
435 .IR curses ,
436 NetBSD
437 .IR curses ,
438 and
439 .IR \%PDCurses ,
440 as well as older \fI\%ncurses\fP versions.
441 This implementation
442 (as well as the X/Open variant of Solaris curses,
443 dated 1995)
444 uses textual dumps.
445 .IP
446 The implementations that use binary dumps use block-I/O
447 (\fIwrite\fP(2) and \fIread\fP(2) functions).
448 Those that use textual dumps use buffered-I/O.
449 A few applications may happen to write extra data in the file using
450 these functions.
451 Doing that can run into problems mixing block- and buffered-I/O.
452 This implementation reduces the problem on writes by flushing the
453 output.
454 However,
455 reading from a file written using mixed schemes may not be successful.
456 .SS "unctrl, wunctrl"
457 X/Open Curses Issue\ 4 describes these functions.
458 It specifies no error conditions for them.
459 It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer
460 if unsuccessful.
461 This implementation checks for three cases:
462 .bP
463 the parameter is a 7-bit US\-ASCII code.
464 This is the case that X/Open Curses documented.
465 .bP
466 the parameter is in the range 128\-159,
467 i.e.,
468 a C1 control code.
469 If \fB\%use_legacy_coding\fP(3NCURSES) has been called with a \fB2\fP parameter,
470 \fBunctrl\fP returns the parameter,
471 i.e.,
472 a one-character string with
473 the parameter as the first character.
474 Otherwise,
475 it returns \*(``\*~@\*('',
476 \*(``\*~A\*('',
477 etc.,
478 analogous to \*(``\*^@\*('',
479 \*(``\*^A\*('',
480 C0 controls.
481 .IP
482 X/Open Curses does not document whether \fBunctrl\fP can be called
483 before initializing curses.
484 This implementation permits that,
485 and returns the \*(``\*~@\*('',
486 etc.,
487 values in that case.
488 .bP
489 parameter values outside the 0 to 255 range.
490 \fBunctrl\fP returns a null pointer.
491 .PP
492 The strings returned by \fBunctrl\fP in this implementation
493 are determined at compile time,
494 showing C1 controls from the upper-128 codes
495 with a \*(``\*~\*('' prefix rather than \*(``\*^\*(''.
496 Other implementations have different conventions.
497 For example,
498 they may show both sets of control characters with \*(``\*^\*('',
499 and strip the parameter to 7 bits.
500 Or they may ignore C1 controls and treat all of the upper-128 codes as
501 printable.
502 This implementation uses 8 bits
503 but does not modify the string to reflect locale.
504 The \fB\%use_legacy_coding\fP(3NCURSES) function allows the caller to
505 change the output of \fBunctrl\fP.
506 .PP
507 Likewise,
508 the \fB\%meta\fP(3NCURSES) function allows the caller to change the output
509 of \fBkeyname\fP,
510 i.e.,
511 it determines whether to use the \*(``M\-\*('' prefix
512 for \*(``meta\*('' keys (codes in the range 128 to 255).
513 Both \fB\%use_legacy_coding\fP(3NCURSES) and \fB\%meta\fP(3NCURSES) succeed only after
514 curses is initialized.
515 X/Open Curses does not document the treatment of codes 128 to 159.
516 When treating them as \*(``meta\*('' keys
517 (or if \fBkeyname\fP is called before initializing curses),
518 this implementation returns strings \*(``M\-\*^@\*('',
519 \*(``M\-\*^A\*('',
520 etc.
521 .PP
522 X/Open Curses documents \fBunctrl\fP as declared in \fB<unctrl.h>\fP,
523 which \fI\%ncurses\fP does.
524 However,
525 \fI\%ncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
526 matching the behavior of SVr4 curses.
527 Other implementations may not do that.
528 .SS "use_env, use_tioctl"
529 If \fI\%ncurses\fP is configured to provide the sp-functions extension,
530 the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before
531 creating each \fIscreen\fP rather than once only
532 (\fB\%sp_funcs\fP(3NCURSES)).
533 This feature of \fBuse_env\fP
534 is not provided by other implementations of curses.
535 .SH HISTORY
536 4BSD (1980)
537 introduced
538 .IR \%unctrl ","
539 defining it as a macro
540 in
541 .IR \%unctrl.h "."
542 .PP
543 SVr2 (1984)
544 added
545 .IR \%delay_output ","
546 .IR \%flushinp ","
547 and
548 .IR \%keyname "."
549 .PP
550 SVr3 (1987) supplied
551 .IR \%filter "."
552 Later that year,
553 SVr3.1 brought
554 .I \%getwin
555 and
556 .IR \%putwin ","
557 reading and writing window dumps
558 with \fI\%fread\fP(3) and \fI\%fwrite\fP(3),
559 respectively.
560 .PP
561 SVr4 (1989) supplied
562 .IR \%use_env "."
563 .PP
564 X/Open Curses Issue\ 4 (1995) specified
565 .I \%key_name
566 and
567 .IR \%wunctrl "."
568 .PP
569 .I \%ncurses
570 5.6 (2006) added
571 .IR \%nofilter "," \" 20060107
572 and 6.0 (2015)
573 .IR \%use_tioctl "." \" 20120714
574 .SH SEE ALSO
575 .na
576 \fB\%ncurses\fP(3NCURSES),
577 \fB\%initscr\fP(3NCURSES),
578 \fB\%inopts\fP(3NCURSES),
579 \fB\%kernel\fP(3NCURSES),
580 \fB\%scr_dump\fP(3NCURSES),
581 \fB\%sp_funcs\fP(3NCURSES),
582 \fB\%curses_variables\fP(3NCURSES),
583 \fB\%legacy_coding\fP(3NCURSES)
584 .ad