Debian Codegraph @

upstream/mageia-cauldron/man3/curs_util.3x

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.143 2025/07/05 13:06:45 tom Exp $
32 .TH curs_util 3X 2025-07-05 "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 \fBgetch\fP(3X).
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(3X)),
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(3X)
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 lx.
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
344 .I NULL
345 on error.
346 .PP
347 In
348 .IR \%ncurses ","
349 .bP
350 .B \%flushinp
351 returns
352 .B ERR
353 if the terminal was not initialized,
354 and
355 .bP
356 .B \%putwin
357 returns
358 .B ERR
359 if its associated \fIwrite\fP(2) calls return
360 .BR ERR "."
361 .SH NOTES
362 .B \%wunctrl
363 is part of
364 .IR \%ncurses "'s"
365 wide-character API,
366 and is not available in its non-wide configuration.
367 .SH PORTABILITY
368 X/Open Curses Issue\ 4 describes these functions.
369 It specifies no error conditions for them.
370 .PP
371 SVr4 describes a successful return value only as
372 \*(``an integer value other than
373 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 542
374 .SS filter
375 The SVr4 documentation describes the action of \fBfilter\fP
376 only in the vaguest terms.
377 The description here is adapted from X/Open Curses
378 (which erroneously fails to describe the disabling of \fBcuu\fP).
379 .SS "delay_output padding"
380 The limitation to 30 seconds
381 and the use of \fBnapms\fP
382 differ from other implementations.
383 .bP
384 SVr4
385 .I curses
386 does not delay if no padding character is available.
387 .bP
388 NetBSD
389 .I curses
390 uses \fBnapms\fP when no padding character is available,
391 but does not take timing into account when using the padding character.
392 .PP
393 Neither limits the delay.
394 .SS keyname
395 The \fBkeyname\fP function may return the names of user-defined
396 string capabilities that are defined in the terminfo entry
397 via the \fB\-x\fP
398 option of \fBtic\fP.
399 This implementation automatically assigns at run-time key codes to
400 user-defined strings that begin with \*(``k\*(''.
401 The key codes start at KEY_MAX,
402 but are not guaranteed to be the same value for different runs
403 because user-defined codes are merged
404 from all terminal descriptions that have been loaded.
405 The \fBuse_extended_names\fP(3X) function controls whether this data is
406 loaded when the terminal description is read by the library.
407 .SS "nofilter, use_tioctl"
408 The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to
409 \fI\%ncurses\fP.
410 They were not supported on Version 7,
411 BSD or System V implementations.
412 It is recommended that any code depending on \fI\%ncurses\fP extensions
413 be conditioned using \fBNCURSES_VERSION\fP.
414 .SS "putwin/getwin file-format"
415 The \fBputwin\fP and \fBgetwin\fP functions have several issues with
416 portability:
417 .bP
418 The files written and read by these functions
419 use an implementation-specific format.
420 Although the format is an obvious target for standardization,
421 it has been overlooked.
422 .IP
423 Interestingly enough,
424 according to the copyright dates in Solaris source,
425 the functions
426 (along with \fBscr_init\fP,
427 etc.\&)
428 originated with the University of California,
429 Berkeley
430 (in 1982)
431 and were later
432 (in 1988)
433 incorporated into SVr4.
434 Oddly,
435 there are no such functions in the 4.3BSD
436 .I curses
437 sources.
438 .bP
439 Most implementations simply dump the binary
440 .I \%WINDOW
441 structure
442 to the file.
443 These include SVr4
444 .IR curses ,
445 NetBSD
446 .IR curses ,
447 and
448 .IR \%PDCurses ,
449 as well as older \fI\%ncurses\fP versions.
450 This implementation
451 (as well as
452 .IR \%xcurses ","
453 the X/Open variant of Solaris
454 .IR curses ","
455 dated 1995)
456 uses textual dumps.
457 .IP
458 The implementations that use binary dumps use block I/O
459 (\fIwrite\fP(2) and \fIread\fP(2) functions).
460 Those that use textual dumps use buffered I/O.
461 A few applications may happen to write extra data in the file using
462 these functions.
463 Doing that can run into problems mixing block and buffered I/O.
464 This implementation reduces the problem on writes by flushing the
465 output.
466 However,
467 reading from a file written using mixed schemes may not be successful.
468 .SS "unctrl, wunctrl"
469 X/Open Curses Issue\ 4 describes these functions.
470 It specifies no error conditions for them.
471 It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer
472 if unsuccessful.
473 This implementation checks for three cases:
474 .bP
475 the parameter is a 7-bit US\-ASCII code.
476 This is the case that X/Open Curses documented.
477 .bP
478 the parameter is in the range 128\-159,
479 i.e.,
480 a C1 control code.
481 If \fB\%use_legacy_coding\fP(3X) has been called with a \fB2\fP parameter,
482 \fBunctrl\fP returns the parameter,
483 i.e.,
484 a one-character string with
485 the parameter as the first character.
486 Otherwise,
487 it returns \*(``\*~@\*('',
488 \*(``\*~A\*('',
489 etc.,
490 analogous to \*(``\*^@\*('',
491 \*(``\*^A\*('',
492 C0 controls.
493 .IP
494 X/Open Curses does not document whether \fBunctrl\fP can be called
495 before initializing
496 .IR curses "."
497 This implementation permits that,
498 and returns the \*(``\*~@\*('',
499 etc.,
500 values in that case.
501 .bP
502 parameter values outside the 0 to 255 range.
503 \fBunctrl\fP returns a null pointer.
504 .PP
505 The strings returned by \fBunctrl\fP in this implementation
506 are determined at compile time,
507 showing C1 controls from the upper-128 codes
508 with a \*(``\*~\*('' prefix rather than \*(``\*^\*(''.
509 Other implementations have different conventions.
510 For example,
511 they may show both sets of control characters with \*(``\*^\*('',
512 and strip the parameter to 7 bits.
513 Or they may ignore C1 controls and treat all of the upper-128 codes as
514 printable.
515 This implementation uses 8 bits
516 but does not modify the string to reflect locale.
517 The \fB\%use_legacy_coding\fP(3X) function allows the caller to
518 change the output of \fBunctrl\fP.
519 .PP
520 Likewise,
521 the \fBmeta\fP(3X) function allows the caller to change the output
522 of \fBkeyname\fP,
523 i.e.,
524 it determines whether to use the \*(``M\-\*('' prefix
525 for \*(``meta\*('' keys (codes in the range 128 to 255).
526 Both \fB\%use_legacy_coding\fP(3X) and \fBmeta\fP(3X) succeed only after
527 .I curses
528 is initialized.
529 X/Open Curses does not document the treatment of codes 128 to 159.
530 When treating them as \*(``meta\*('' keys
531 (or if \fBkeyname\fP is called before initializing
532 .IR curses "),"
533 this implementation returns strings \*(``M\-\*^@\*('',
534 \*(``M\-\*^A\*('',
535 etc.
536 .PP
537 X/Open Curses documents \fBunctrl\fP as declared in \fB<unctrl.h>\fP,
538 which \fI\%ncurses\fP does.
539 However,
540 \fI\%ncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
541 matching the behavior of SVr4
542 .IR curses "."
543 Other implementations may not do that.
544 .SS "use_env, use_tioctl"
545 If \fI\%ncurses\fP is configured to provide the sp-functions extension,
546 the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before
547 creating each \fIscreen\fP rather than once only
548 (\fBcurs_sp_funcs\fP(3X)).
549 This feature of \fBuse_env\fP
550 is not provided by other implementations of
551 .IR curses "."
552 .SH HISTORY
553 4BSD (1980)
554 introduced
555 .IR \%unctrl ","
556 defining it as a macro
557 in
558 .IR \%unctrl.h "."
559 .PP
560 SVr2 (1984)
561 added
562 .IR \%delay_output ","
563 .IR \%flushinp ","
564 and
565 .IR \%keyname "."
566 .PP
567 SVr3 (1987) supplied
568 .IR \%filter "."
569 Later that year,
570 SVr3.1 brought
571 .I \%getwin
572 and
573 .IR \%putwin ","
574 reading and writing window dumps
575 with \fI\%fread\fP(3) and \fI\%fwrite\fP(3),
576 respectively.
577 .PP
578 SVr4 (1989) furnished
579 .IR \%use_env "."
580 .PP
581 X/Open Curses Issue\ 4 (1995) specified
582 .I \%key_name
583 and
584 .IR \%wunctrl "."
585 .PP
586 .I \%ncurses
587 5.6 (2006) added
588 .IR \%nofilter "," \" 20060107
589 and 6.0 (2015)
590 .IR \%use_tioctl "." \" 20120714
591 .SH SEE ALSO
592 .na
593 \fB\%curses\fP(3X),
594 \fB\%curs_initscr\fP(3X),
595 \fB\%curs_inopts\fP(3X),
596 \fB\%curs_kernel\fP(3X),
597 \fB\%curs_scr_dump\fP(3X),
598 \fB\%curs_sp_funcs\fP(3X),
599 \fB\%curs_variables\fP(3X),
600 \fB\%legacy_coding\fP(3X)
601 .ad