Debian Codegraph @

upstream/debian-unstable/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.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