Debian Codegraph @

upstream/debian-unstable/man3/curses_variables.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 2010-2015,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_variables.3x,v 1.73 2025/08/23 23:02:32 tom Exp $
31 .TH curses_variables 3NCURSES 2025-08-23 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .ie \n(.g .ds : \:
44 .el .ds : \" empty
45 .
46 .de bP
47 .ie n .IP \(bu 4
48 .el .IP \(bu 2
49 ..
50 .
51 .\" URL hyperlink support macros from groff's "an-ext.tmac"
52 .
53 .\" Save the automatic hyphenation mode.
54 .\"
55 .\" In AT&T troff, there was no register exposing the hyphenation mode,
56 .\" and no way to save and restore it. Set `mH` to a reasonable value
57 .\" for your implementation and preference.
58 .de mY
59 . ie !\\n(.g \
60 . nr mH 14
61 . el \
62 . do nr mH \\n[.hy] \" groff extension register
63 ..
64 .
65 .\" Prepare link text for mail/web hyperlinks. `MT` and `UR` call this.
66 .de mV
67 . ds mU \\$1\"
68 ..
69 .
70 .\" Emit hyperlink. The optional argument supplies trailing punctuation
71 .\" after link text. `ME` and `UE` call this.
72 .de mQ
73 . mY
74 . nh
75 <\\*(mU>\\$1
76 . hy \\n(mH
77 . rm mU
78 ..
79 .
80 .\" Start URL.
81 .\" .UR url
82 .if !\n(.g \{\
83 .de UR
84 . mV \\$1
85 ..
86 .\}
87 .
88 .\" End URL.
89 .\" .UE [punctuation]
90 .if !\n(.g \{\
91 .de UE
92 . mQ \\$1
93 ..
94 .\}
95 .
96 .SH NAME
97 \fI\%bool\fP,
98 \fI\%chtype\fP,
99 \fI\%cchar_t\fP,
100 \fI\%attr_t\fP,
101 \fI\%SCREEN\fP,
102 \fI\%WINDOW\fP,
103 \fB\%TRUE\fP,
104 \fB\%FALSE\fP,
105 \fB\%ERR\fP,
106 \fB\%OK\fP,
107 \fB\%CCHARW_MAX\fP,
108 \fB\%curscr\fP,
109 \fB\%newscr\fP,
110 \fB\%stdscr\fP,
111 \fB\%COLORS\fP,
112 \fB\%COLOR_PAIRS\fP,
113 \fB\%COLS\fP,
114 \fB\%LINES\fP,
115 \fB\%ESCDELAY\fP,
116 \fB\%TABSIZE\fP \-
117 \fIcurses\fR data types, constants, and global variables
118 .SH SYNOPSIS
119 .nf
120 \fB#include <curses.h>
121 .PP
122 \fI/* data types */
123 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;
124 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;
125 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;
126 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;
127 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN;
128 \fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;
129 .PP
130 \fI/* constants */
131 \fBconst bool TRUE;
132 \fBconst bool FALSE;
133 .PP
134 \fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;
135 \fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;
136 .PP
137 \fI/* extension */
138 \fBconst \fI/*\fP .\|.\|. \fI*/\fP CCHARW_MAX;
139 .PP
140 \fI/* variables */
141 \fBint COLORS;
142 \fBint COLOR_PAIRS;
143 \fBint COLS;
144 \fBint LINES;
145 \fBWINDOW * curscr;
146 \fBWINDOW * stdscr;
147 .PP
148 \fI/* extensions */
149 \fBint ESCDELAY;
150 \fBint TABSIZE;
151 \fBWINDOW * newscr;
152 .fi
153 .SH DESCRIPTION
154 This page summarizes data types,
155 constants,
156 and variables provided by the \fIcurses\fP library.
157 Locate further discussion in \fB\%ncurses\fP(3NCURSES).
158 .PP
159 Depending on \fI\%ncurses\fP's build-time configuration,
160 the variables may instead be
161 macros (see \fB\%threads\fP(3NCURSES) and \fB\%opaque\fP(3NCURSES))
162 that provide read-only access to the library's state.
163 In either case,
164 applications should treat them as read-only to avoid
165 confusing the library.
166 .SH CONSTANTS
167 .SS "TRUE, FALSE"
168 The
169 .I curses
170 library defines
171 .B TRUE
172 and
173 .B FALSE
174 to represent the values of the Boolean data type.
175 .SS "ERR, OK"
176 .I curses
177 and
178 .I \%term\%info
179 functions frequently return these constant integral values
180 indicating failure and success,
181 respectively.
182 .SS CCHARW_MAX
183 This integral value,
184 an
185 .I \%ncurses
186 extension,
187 indicates the maximum number of
188 .I \%wchar_t
189 wide characters that can be stored in a
190 .I curses
191 complex character
192 .IR \%cchar_t "."
193 .SH "DATA TYPES"
194 .SS "\fIbool\fP"
195 .I curses
196 defines an integral type
197 .IR bool "."
198 X/Open Issue\ 4
199 .I curses
200 (1996) preceded the ISO\ C99 and ISO\ C++98
201 standards,
202 each of which also defined a Boolean data type of the same name.
203 .PP
204 .IR \%ncurses 's
205 configure script attempts to discover the
206 data type used by the system's C and C++ compilers,
207 to reuse them as its own
208 .IR bool "."
209 .SS "\fIchtype\fP"
210 The \fI\%chtype\fP integral type combines a
211 (\*(``narrow\*('',
212 8-bit)
213 character with attributes encoding the character's \fIrendition\fP,
214 such as the styling of its typeface and/or foreground and background
215 colors.
216 See,
217 for example,
218 \fB\%addch\fP(3NCURSES),
219 \fB\%attron\fP(3NCURSES),
220 and
221 \fB\%inch\fP(3NCURSES).
222 .SS "\fIcchar_t\fP, \fIattr_t\fP"
223 \fI\%chtype\fP is too small for the standard C library's wide-character
224 type,
225 \fIwchar_t\fP.
226 \fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
227 enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
228 (a \*(``user-perceived character\*('' [UAX #29],
229 which may nevertheless require several character encoding units to
230 represent).
231 \fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
232 apply to \fI\%cchar_t\fPs.
233 See,
234 for example,
235 \fB\%add_wch\fP(3NCURSES),
236 \fB\%attr_on\fP(3NCURSES),
237 and
238 \fB\%in_wch\fP(3NCURSES).
239 .SS "\fISCREEN\fP"
240 .I curses
241 manages a terminal device with this structure type;
242 see \fB\%initscr\fP(3NCURSES).
243 .SS "\fIWINDOW\fP"
244 .I curses
245 represents rectangular portions of the terminal screen with the
246 .I \%WINDOW
247 structure type;
248 see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3NCURSES).
249 .SH "VARIABLES"
250 .SS "curscr, newscr, stdscr"
251 When a
252 .I curses
253 application calls
254 \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES),
255 the library creates a window named
256 .B \%stdscr
257 that is the same size as the terminal screen,
258 (minus any lines reserved by
259 \fB\%ripoffline\fP(3NCURSES) or \fB\%slk_init\fP(3NCURSES))
260 and is the implicit window used by functions
261 that interact with a window
262 but do not take a parameter identifying one;
263 many
264 .I curses
265 functions use it.
266 An application need not use
267 .BR \%stdscr ";"
268 it might prefer to tile the display into multiple windows instead.
269 .PP
270 The library records updates to the terminal screen in a window named
271 \fB\%curscr\fP.
272 This object is referred to as the \*(``physical screen\*('' in
273 \fB\%refresh\fP(3NCURSES) and
274 \fB\%outopts\fP(3NCURSES).
275 .PP
276 \fI\%ncurses\fP collects pending updates to the terminal screen in a
277 window named \fB\%newscr\fP.
278 This object is referred to as the \*(``virtual screen\*('' in the
279 \fB\%kernel\fP(3NCURSES),
280 \fB\%refresh\fP(3NCURSES),
281 and
282 \fB\%outopts\fP(3NCURSES).
283 When the screen is refreshed,
284 \fIcurses\fP determines a minimal set of updates using the terminal's
285 capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
286 .SS COLORS
287 Once a
288 .I curses
289 screen is initialized,
290 .B \%COLORS
291 contains the number of colors supported by the terminal;
292 see \fB\%color\fP(3NCURSES).
293 .SS COLOR_PAIRS
294 Once a
295 .I curses
296 screen is initialized,
297 .B \%COLOR_PAIRS
298 contains the number of color pairs supported by the terminal;
299 see \fB\%color\fP(3NCURSES).
300 .SS "COLS, LINES"
301 Once a
302 .I curses
303 screen is initialized,
304 .B \%COLS
305 and
306 .B LINES
307 contain its width and height in character cells,
308 respectively;
309 that is,
310 the number of columns and lines.
311 .SS ESCDELAY
312 When reading key strokes from a window in keypad mode,
313 .I curses
314 distinguishes the ESC character resulting from a user's press of the
315 \*(``Escape\*('' key on the input device
316 from one beginning an escape sequence
317 (commonly produced by function keys),
318 by waiting after receiving the escape character
319 to see if further characters are available
320 on the input stream within a short interval.
321 .B \%ESCDELAY
322 stores this interval in milliseconds.
323 .PP
324 If \fB\%keypad\fP(3NCURSES) is disabled for the
325 .I curses
326 window receiving input,
327 a program must disambiguate escape sequences itself.
328 .SS TABSIZE
329 The \fIcurses\fP library converts a tab character to this number of
330 spaces as it adds a tab to a window;
331 see \fB\%addch\fP(3NCURSES).
332 .SH NOTES
333 Initialize a
334 .I curses
335 screen with either \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES).
336 .PP
337 If
338 .I \%ncurses
339 is configured to provide separate
340 .I curses
341 and
342 .I \%tinfo
343 libraries,
344 most of these symbols reside in the former.
345 Both use the
346 .B bool
347 data type.
348 .SH EXTENSIONS
349 The
350 .B \%CCHARW_MAX
351 constant,
352 and
353 .BR \%ESCDELAY ","
354 .BR \%TABSIZE ","
355 and
356 .B \%newscr
357 variables,
358 are
359 extensions,
360 the first of these originating in
361 .\" Solaris xcurses calls it M_CCHAR_MAX.
362 .IR \%ncurses "."
363 .SH PORTABILITY
364 Applications employing
365 .I \%ncurses
366 extensions should condition their use on the visibility of the
367 .B \%NCURSES_VERSION
368 preprocessor macro.
369 .PP
370 The X/Open Curses standard documents all of the foregoing types and
371 symbols except for
372 .BR \%CCHARW_MAX ","
373 .BR \%newscr ","
374 .BR \%TABSIZE ","
375 and
376 .BR \%ESCDELAY "."
377 .PP
378 X/Open Curses describes \fB\%curscr\fP only as \*(``an internal data
379 structure\*('';
380 SVr4 gave more details,
381 noting its use \*(``for certain low-level operations like clearing and
382 redrawing a screen containing garbage\*(''.
383 .\" SVID 4, Volume 3, p. 408
384 Neither specified its interaction with the rest of the interface beyond
385 use as an argument to \fB\%clearok\fP(3NCURSES) and \fB\%wrefresh\fP(3NCURSES).
386 .PP
387 \fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
388 When refreshing the screen,
389 it is used as a working area for combining the standard window
390 \fB\%stdscr\fP with any others the application may have created with
391 \fB\%newwin\fP(3NCURSES).
392 When the update of \fB\%newscr\fP is complete,
393 \fIcurses\fP modifies \fB\%curscr\fP to match \fB\%newscr\fP.
394 .PP
395 .B \%TABSIZE
396 is a feature of SVr4
397 .IR curses "."
398 .bP
399 SVr4 initially sets
400 .B \%TABSIZE
401 from the terminal description's
402 .B \%init_tabs
403 .RB ( it )
404 capability.
405 After that,
406 it can be altered by applications using SVr4
407 .IR curses "."
408 .bP
409 SVr4
410 .I curses
411 uses
412 .BR \%TABSIZE 's
413 value to compute the position of tab stops when updating both
414 the virtual screen with \fB\%addch\fP(3NCURSES) and
415 the physical screen with \fB\%mvcur\fP(3NCURSES).
416 .bP
417 In
418 .IR \%ncurses ","
419 .BR \%TABSIZE 's
420 value affects only the virtual screen.
421 The library uses the terminal type description's
422 .B \%init_tabs
423 .RB ( it )
424 capability to compute hardware tabs
425 (that is,
426 tab stops on the physical screen).
427 .bP
428 Other implementations differ.
429 For instance,
430 NetBSD
431 .I curses
432 allows
433 .B \%TABSIZE
434 to be set through an environment variable.
435 .I \%ncurses
436 does not.
437 .IP
438 NetBSD
439 .I curses
440 does not support hardware tabs;
441 it uses the
442 .B \%init_tabs
443 .RB ( it )
444 capability and the
445 .B \%TABSIZE
446 variable only to update the virtual screen.
447 .PP
448 .B \%ESCDELAY
449 is a feature of AIX
450 .IR curses "."
451 .bP
452 AIX treats
453 .BR \%ESCDELAY 's
454 value as counting
455 .I fifths
456 of milliseconds.
457 .bP
458 AIX's default
459 .B \%ESCDELAY
460 equals 0.1 seconds.
461 .bP
462 AIX also enforces a limit of 10,000 seconds for
463 .BR \%ESCDELAY ";"
464 .I \%ncurses
465 does not enforce an upper limit.
466 .PP
467 .I \%ncurses
468 has long interpreted
469 .B \%ESCDELAY
470 as a count of milliseconds,
471 making it impossible to be completely compatible with AIX.
472 Consequently,
473 most users have decided either to override the value,
474 or to rely upon its default.
475 .SH SEE ALSO
476 .UR https://\*:unicode\*:.org/\*:reports/\*:tr29/
477 [UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
478 Segmentation\*(''
479 .UE
480 .PP
481 \fB\%getcchar\fP(3NCURSES)
482 further discusses the
483 .I \%ncurses
484 extension
485 .BR \%CCHARW_MAX "."
486 .PP
487 \fB\%ncurses\fP(3NCURSES),
488 \fB\%color\fP(3NCURSES),
489 \fB\%opaque\fP(3NCURSES),
490 \fB\%terminfo\fP(3NCURSES),
491 \fB\%threads\fP(3NCURSES),
492 \fB\%terminfo_variables\fP(3NCURSES),
493 \fB\%terminfo\fP(5)