Debian Codegraph @

upstream/mageia-cauldron/man3/ncurses.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: ncurses.3x,v 1.255 2025/07/05 12:42:14 tom Exp $
32 .TH ncurses 3X 2025-07-05 "ncurses 6.5" "Library calls"
33 .ie \n(.g \{\
34 .ds `` \(lq
35 .ds '' \(rq
36 .\}
37 .el \{\
38 .ie t .ds `` ``
39 .el .ds `` ""
40 .ie t .ds '' ''
41 .el .ds '' ""
42 .\}
43 .
44 .de bP
45 .ie n .IP \(bu 4
46 .el .IP \(bu 2
47 ..
48 .
49 .\" Add supplementary paragraph tag on its own line after TP.
50 .\" Adapted from TQ (which would produce mandoc warnings).
51 .de tQ
52 . br
53 . ns
54 . TP
55 ..
56 .
57 .SH NAME
58 \fB\%ncurses\fP \-
59 character-cell terminal interface with optimized output
60 .SH SYNOPSIS
61 .nf
62 \fB#include <curses.h>
63 .fi
64 .SH DESCRIPTION
65 The \*(``new curses\*('' library offers the programmer a
66 terminal-independent means of reading keyboard and mouse input and
67 writing to character-cell displays with output optimized to minimize
68 screen updates.
69 .I \%ncurses
70 replaces the
71 .I curses
72 libraries from
73 System V Release 4 Unix (\*(``SVr4\*('')
74 and
75 4.4BSD Unix,
76 the development of which ceased in the 1990s.
77 This document describes
78 .I \%ncurses
79 version 6.5
80 (patch 20250802).
81 .PP
82 .I \%ncurses
83 permits control of the terminal screen's contents;
84 abstraction and subdivision thereof with
85 .I windows
86 and
87 .IR pads ;
88 acquisition of keyboard and mouse events;
89 selection of color and rendering attributes
90 (such as bold or underline);
91 the definition and use of
92 .I "soft label"
93 keys;
94 access to the
95 .I \%term\%info
96 terminal capability database;
97 a
98 .I termcap
99 compatibility interface;
100 and an abstraction of the system's API for manipulating the terminal
101 (such as \fI\%termios\fP(3)).
102 .PP
103 .I \%ncurses
104 implements the interface described by X/Open Curses Issue\ 7.
105 In many behavioral details not standardized by X/Open,
106 .I \%ncurses
107 emulates the
108 .I curses
109 library of SVr4 and provides numerous useful extensions.
110 .PP
111 .I \%ncurses
112 man pages employ several sections to clarify matters of usage and
113 interoperability with other
114 .I curses
115 implementations.
116 .bP
117 \*(``NOTES\*('' describes issues and caveats of which any user of the
118 .I \%ncurses
119 API should be aware,
120 such as limitations on the size of an underlying integral type or the
121 availability of a preprocessor macro exclusive of a function definition
122 (which prevents its address from being taken).
123 This section also describes implementation details
124 of significance to the programmer but which are not standardized.
125 .bP
126 \*(``EXTENSIONS\*('' presents
127 .I \%ncurses
128 innovations beyond the X/Open Curses standard and/or the SVr4
129 .I curses
130 implementation.
131 They are termed
132 .I extensions
133 to indicate that they cannot be implemented solely by using the library
134 API,
135 but require access to the library's internal state.
136 .bP
137 \*(``PORTABILITY\*('' discusses matters
138 (beyond the exercise of extensions)
139 that should be considered when writing to a
140 .I curses
141 standard,
142 or for multiple implementations.
143 .bP
144 \*(``HISTORY\*('' examines points of detail in
145 .I \%ncurses
146 and other
147 .I curses
148 implementations over the decades of their development,
149 particularly where precedent or inertia have frustrated better design
150 (and,
151 in a few cases,
152 where such inertia has been overcome).
153 .PP
154 A
155 .I curses
156 application must be linked with the library;
157 use the
158 .B \-lncurses
159 option to your compiler or linker.
160 A debugging version of the library may be available;
161 if so,
162 link with it using
163 .BR \-lncurses_g .
164 (Your system integrator may have installed these libraries such that you
165 can use the options
166 .B \-lcurses
167 and
168 .BR \-lcurses_g ,
169 respectively.)
170 The
171 .I \%ncurses_g
172 library logs events describing
173 .I \%ncurses
174 actions
175 to a file called
176 .I \%trace
177 in the current directory.
178 See section \*(``ALTERNATE CONFIGURATIONS\*('' below.
179 .SS "Application Structure"
180 A
181 .I curses
182 application uses information from the system locale;
183 \fI\%setlocale\fP(3) prepares it for
184 .I curses
185 library calls.
186 .PP
187 .RS 4
188 .EX
189 setlocale(LC_ALL, "");
190 .EE
191 .RE
192 .PP
193 If the locale is not thus initialized,
194 the library assumes that characters are printable as in ISO\ 8859-1,
195 to work with certain legacy programs.
196 You should initialize the locale;
197 do not expect consistent behavior from the library when the locale has
198 not been set up.
199 .PP
200 \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)
201 must be called to initialize
202 .I curses
203 before use of any functions
204 that access or manipulate windows or screens.
205 .PP
206 To get character-at-a-time input without echoing \(em
207 most interactive,
208 screen-oriented programs want this \(em
209 use the following sequence.
210 .PP
211 .RS 4
212 .EX
213 initscr(); cbreak(); noecho();
214 .EE
215 .RE
216 .PP
217 Most applications would perform further setup as follows.
218 .PP
219 .RS 4
220 .EX
221 .nf
222 noqiflush();
223 keypad(stdscr, TRUE);
224 .fi
225 .EE
226 .RE
227 .PP
228 A
229 .I curses
230 program then often enters an event-handling loop.
231 Call \fB\%endwin\fP(3X) before exiting.
232 .SS Overview
233 A
234 .I curses
235 library abstracts the terminal with a
236 .I \%SCREEN
237 data structure,
238 and represents all or part of its display
239 with
240 .I \%WINDOW
241 structures.
242 Distinct properties apply to each;
243 for example,
244 the
245 .I "line discipline"
246 of a typical Unix terminal driver
247 is in one of three modes:
248 raw,
249 \%cbreak,
250 or canonical (\*(``cooked\*('').
251 In
252 .IR curses ","
253 the line discipline is a property of the screen,
254 applying identically to all windows associated with it.
255 .PP
256 A
257 .I window
258 is a rectangular grid of character cells,
259 addressed by line and column coordinates
260 .RI ( y ,
261 .IR x ),
262 with the upper left corner as (0, 0).
263 A window called
264 .BR \%stdscr ,
265 the same size as the terminal screen,
266 is always available.
267 Create others with \fB\%newwin\fP(3X).
268 .PP
269 A
270 .I curses
271 library does not manage overlapping windows
272 (but see below).
273 You can either use
274 .B \%stdscr
275 to manage one screen-filling window,
276 or tile the screen into non-overlapping windows and not use
277 .B \%stdscr
278 at all.
279 Mixing the two approaches will result in unpredictable and undesired
280 effects.
281 .PP
282 Functions permit manipulation of a window and the
283 .I cursor
284 identifying the cell within it at which the next operation will occur.
285 Among those,
286 the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
287 these place the cursor within and write a character to
288 .BR \%stdscr ,
289 respectively.
290 .PP
291 Frequent changes to the terminal screen can cause unpleasant flicker or
292 inefficient use of the communication channel to the device,
293 so as a rule the library does not update it automatically.
294 Therefore,
295 after using
296 .I curses
297 functions to accumulate a set of desired updates that make sense to
298 present together,
299 call \fB\%refresh\fP(3X) to tell the library to make the user's screen
300 look like \fBstdscr\fP.
301 The library
302 .\" X/Open Curses Issue 7 assumes some optimization will be done, but
303 .\" does not mandate it in any way.
304 .I optimizes
305 its output by computing a minimal volume of operations to mutate the
306 screen from its state at the previous refresh to the new one.
307 Effective optimization demands accurate information about the terminal
308 device:
309 the management of such information is the province of the
310 \fB\%terminfo\fP(3X) API,
311 a feature of every standard
312 .I curses
313 implementation.
314 .PP
315 Special windows called
316 .I pads
317 may also be manipulated.
318 These are not constrained to the size of the terminal screen and their
319 contents need not be completely displayed.
320 See \fB\%curs_pad\fP(3X).
321 .PP
322 Many terminals support configuration of character cell foreground and
323 background colors as well as
324 .IR attributes ","
325 which cause characters to render in such modes as
326 boldfaced,
327 underlined,
328 or in reverse video.
329 See \fB\%curs_color\fP(3X) and \fB\%curs_attr\fP(3X).
330 .PP
331 .I curses
332 predefines constants for a small set of forms-drawing graphics
333 corresponding to the DEC Alternate Character Set (ACS),
334 a feature of VT100 and other terminals.
335 See \fB\%addch\fP(3X).
336 .PP
337 .I curses
338 is implemented using the operating system's terminal driver;
339 key events are received not as scan codes but as byte sequences.
340 The driver reports graphical keycaps
341 (alphanumeric and punctuation keys,
342 and the space)
343 as-is.
344 Everything else,
345 including the tab,
346 enter/return,
347 keypad,
348 arrow,
349 and function keys,
350 appears to
351 .I curses
352 as a control character or a multibyte
353 .I "escape sequence."
354 .I curses
355 can translate the latter into unique
356 .I "key codes."
357 See \fB\%keypad\fP(3X) and \fB\%getch\fP(3X).
358 .PP
359 .I \%ncurses
360 provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
361 and \fBmenu\fP(3X) libraries;
362 they permit overlapping windows and ease construction of user interfaces
363 with
364 .IR curses .
365 .SS "Initialization"
366 The selection of an appropriate value of
367 .I TERM
368 in the process environment is essential to correct
369 .I curses
370 and
371 .I \%term\%info
372 library operation.
373 A well-configured system selects a correct
374 .I TERM
375 value automatically;
376 \fB\%tset\fP(1) may assist with troubleshooting exotic situations.
377 .PP
378 If you change the terminal type,
379 export the shell's
380 .I TERM
381 variable,
382 then run \fB\%tset\fP(1) or the
383 .RB \*(`` "tput init" \*(''
384 command.
385 See subsection \*(``Tabs and Initialization\*('' of \fB\%terminfo\fP(5).
386 .PP
387 If the environment variables
388 .I \%LINES
389 and
390 .I \%COLUMNS
391 are set,
392 or if the
393 .I curses
394 program is executing in a graphical windowing environment,
395 the information obtained thence overrides that obtained by
396 .IR \%term\%info .
397 An
398 .I \%ncurses
399 extension supports resizable terminal displays;
400 see \fB\%wresize\fP(3X).
401 .PP
402 If the environment variable
403 .I \%TERMINFO
404 is defined,
405 a
406 .I curses
407 program checks first for a terminal type description in the location it
408 identifies.
409 .I \%TERMINFO
410 is useful for developing type descriptions or when write permission to
411 .I \%/usr/share/terminfo
412 is not available.
413 .PP
414 See section \*(``ENVIRONMENT\*('' below.
415 .SS "Naming Conventions"
416 .I curses
417 offers many functions in variant forms using a regular set of
418 alternatives to the name of an elemental one.
419 Those prefixed with \*(``w\*('' require a
420 .I \%WINDOW
421 pointer argument;
422 those with a \*(``mv\*('' prefix first perform cursor movement using
423 \fB\%wmove\fP(3X);
424 a \*(``mvw\*('' prefix indicates both.
425 The \*(``w\*('' function is typically the elemental one;
426 the removal of this prefix usually indicates operation on
427 .BR \%stdscr .
428 .PP
429 Four functions prefixed with \*(``p\*('' require a
430 .I pad
431 argument;
432 see below.
433 .PP
434 In function synopses,
435 .I \%ncurses
436 man pages apply the following names to parameters.
437 We introduce the character types in the next subsection.
438 .PP
439 .TS
440 center;
441 Li L.
442 bf a \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
443 c a \fIchar\fP or \fIint\fP
444 ch a \fIchtype\fP
445 wc a \fIwchar_t\fP or \fIwint_t\fP
446 wch a \fIcchar_t\fP
447 win pointer to a \fIWINDOW\fP
448 pad pointer to a \fIWINDOW\fP that is a pad
449 pair a foreground/background color pair identifier
450 .TE
451 .SS "Wide and Non-wide Character Configurations"
452 This man page primarily surveys functions that appear in any
453 configuration of the library.
454 There are two common configurations;
455 for others,
456 see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
457 .TP 10 \" "ncursesw" + 2n
458 .I \%ncurses
459 is the library in its \*(``non-wide\*('' configuration,
460 handling only eight-bit characters.
461 It stores a character combined with attributes
462 and a color pair identifier
463 in a
464 .I \%chtype
465 datum,
466 which is often an alias of
467 .IR int .
468 A string of
469 .I curses
470 characters is similar to a C
471 .I char
472 string;
473 a
474 .I chtype
475 string ends with an integral
476 .BR 0 ","
477 the null
478 .I curses
479 character.
480 .IP
481 Attributes and a color pair identifier
482 (with no corresponding character)
483 can be stored in variables of
484 .I \%chtype
485 or
486 .I \%attr_t
487 type.
488 In either case,
489 they are accessed via an integral bit mask.
490 .IP
491 .I \%ncurses
492 stores each cell of a
493 .I \%WINDOW
494 as a
495 .IR \%chtype .
496 X/Open Curses does not specify the sizes of the character code or
497 color pair identifier,
498 nor the quantity of attribute bits,
499 in
500 .IR chtype ";"
501 these are implementation-dependent.
502 .I \%ncurses
503 uses eight bits for the character code.
504 An application requiring a wider character type,
505 for instance to represent Unicode,
506 should use the wide-character API.
507 .TP 10
508 .I \%ncursesw
509 is the library in its \*(``wide\*('' configuration,
510 which handles character encodings requiring a larger data type than
511 .I \%char
512 (a byte-sized type)
513 can represent.
514 It provides additional functions that complement those in
515 the non-wide library where the size of the underlying character type is
516 significant.
517 A somewhat regular naming convention relates many of the wide variants
518 to their non-wide counterparts;
519 where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
520 prefix it with \*(``_w\*('' to obtain the wide counterpart.
521 For example,
522 \fB\%waddch\fP becomes \fB\%wadd_wch\fP.
523 An exception is
524 .B \%ins_nwstr
525 (and its variants),
526 spelled thus instead of \*(``insn_wstr\*(''.
527 (Exceptions that add only \*(``w\*('' comprise
528 .BR \%addwstr ,
529 .BR \%inwstr ,
530 and their variants.)
531 .\" This is because they operate on "plain" wide-character strings
532 .\" (`wchar_t*`) and not curses complex character strings (`cchar_t*`).
533 .\" SVID 4 did specify functions like `addwch()` and `inswch()` that
534 .\" operated on `chtype`s assuming that they were wide enough for a
535 .\" `wchar_t` plus attribute and color pair bits; X/Open Curses did not
536 .\" standardize these.
537 .IP
538 This convention is inapplicable to some non-wide function names,
539 so other transformations are used for the wide configuration:
540 the window background management function \*(``bkgd\*('' becomes
541 \*(``bkgrnd\*('';
542 the window border-drawing and -clearing functions are suffixed with
543 \*(``_set\*('';
544 and character attribute manipulation functions like
545 \*(``attron\*('' become \*(``attr_on\*(''.
546 .RS 10 \" same as foregoing tag width
547 .TP 9 \" "cchar_t" + 2n
548 .I \%cchar_t
549 is a
550 .I "curses complex character"
551 and corresponds to the non-wide configuration's
552 .IR \%chtype .
553 It is a structure type
554 because it requires more storage than a standard scalar type offers.
555 A character code may not be representable as a
556 .IR \%char ,
557 and moreover more than one character may occupy a cell
558 (as with accent marks and other diacritics).
559 Each character is of type
560 .IR \%wchar_t ;
561 a complex character contains one spacing character and zero or more
562 non-spacing characters
563 (see below).
564 A string of complex characters ends with a
565 .I \%cchar_t
566 whose
567 .I \%wchar_t
568 member is the null wide character.
569 Attributes and a color pair identifier are stored in separate fields of
570 the structure,
571 not combined into an integer as in
572 .IR \%chtype .
573 .PP
574 .I \%ncurses
575 stores each cell of a
576 .I \%WINDOW
577 as a
578 .IR \%cchar_t .
579 \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
580 store and retrieve
581 .I \%cchar_t
582 data.
583 .PP
584 The wide library API of
585 .I \%ncurses
586 depends on two data types standardized by ISO C95.
587 .TP 9
588 .I \%wchar_t
589 stores a wide character.
590 Like
591 .IR \%chtype ,
592 it may be an alias of
593 .IR int .
594 Depending on the character encoding,
595 a wide character may be
596 .IR spacing ,
597 meaning that it occupies a character cell by itself and typically
598 accompanies cursor advancement,
599 or
600 .IR non-spacing ,
601 meaning that it occupies the same cell as a spacing character,
602 is often regarded as a \*(``modifier\*('' of the base glyph with which
603 it combines,
604 and typically does not advance the cursor.
605 .TP 9
606 .I \%wint_t
607 can store a
608 .I \%wchar_t
609 or the constant
610 .IR \%WEOF ,
611 analogously to the
612 .IR int -sized
613 character manipulation functions of ISO C and its constant
614 .IR \%EOF .
615 .RE
616 .\"
617 .SS "Function Name Index"
618 The following table lists the
619 .I curses
620 functions provided in the non-wide and wide APIs and the corresponding
621 man pages that describe them.
622 Those flagged with \*(``*\*(''
623 are
624 .IR \%ncurses "-specific,"
625 neither described by X/Open Curses nor present in SVr4.
626 .PP
627 .TS
628 center tab(/);
629 l l .
630 \fIcurses\fP Function Name/Man Page
631 _
632 COLOR_PAIR/\fBcurs_color\fP(3X)
633 PAIR_NUMBER/\fBcurs_color\fP(3X)
634 add_wch/\fBcurs_add_wch\fP(3X)
635 add_wchnstr/\fBcurs_add_wchstr\fP(3X)
636 add_wchstr/\fBcurs_add_wchstr\fP(3X)
637 addch/\fBcurs_addch\fP(3X)
638 addchnstr/\fBcurs_addchstr\fP(3X)
639 addchstr/\fBcurs_addchstr\fP(3X)
640 addnstr/\fBcurs_addstr\fP(3X)
641 addnwstr/\fBcurs_addwstr\fP(3X)
642 addstr/\fBcurs_addstr\fP(3X)
643 addwstr/\fBcurs_addwstr\fP(3X)
644 alloc_pair/\fBnew_pair\fP(3X)*
645 assume_default_colors/\fBdefault_colors\fP(3X)*
646 attr_get/\fBcurs_attr\fP(3X)
647 attr_off/\fBcurs_attr\fP(3X)
648 attr_on/\fBcurs_attr\fP(3X)
649 attr_set/\fBcurs_attr\fP(3X)
650 attroff/\fBcurs_attr\fP(3X)
651 attron/\fBcurs_attr\fP(3X)
652 attrset/\fBcurs_attr\fP(3X)
653 baudrate/\fBcurs_termattrs\fP(3X)
654 beep/\fBcurs_beep\fP(3X)
655 bkgd/\fBcurs_bkgd\fP(3X)
656 bkgdset/\fBcurs_bkgd\fP(3X)
657 bkgrnd/\fBcurs_bkgrnd\fP(3X)
658 bkgrndset/\fBcurs_bkgrnd\fP(3X)
659 border/\fBcurs_border\fP(3X)
660 border_set/\fBcurs_border_set\fP(3X)
661 box/\fBcurs_border\fP(3X)
662 box_set/\fBcurs_border_set\fP(3X)
663 can_change_color/\fBcurs_color\fP(3X)
664 cbreak/\fBcurs_inopts\fP(3X)
665 chgat/\fBcurs_attr\fP(3X)
666 clear/\fBcurs_clear\fP(3X)
667 clearok/\fBcurs_outopts\fP(3X)
668 clrtobot/\fBcurs_clear\fP(3X)
669 clrtoeol/\fBcurs_clear\fP(3X)
670 color_content/\fBcurs_color\fP(3X)
671 color_set/\fBcurs_attr\fP(3X)
672 copywin/\fBcurs_overlay\fP(3X)
673 curs_set/\fBcurs_kernel\fP(3X)
674 curses_trace/\fBcurs_trace\fP(3X)*
675 curses_version/\fBcurs_extend\fP(3X)*
676 def_prog_mode/\fBcurs_kernel\fP(3X)
677 def_shell_mode/\fBcurs_kernel\fP(3X)
678 define_key/\fBdefine_key\fP(3X)*
679 del_curterm/\fBcurs_terminfo\fP(3X)
680 delay_output/\fBcurs_util\fP(3X)
681 delch/\fBcurs_delch\fP(3X)
682 deleteln/\fBcurs_deleteln\fP(3X)
683 delscreen/\fBcurs_initscr\fP(3X)
684 delwin/\fBcurs_window\fP(3X)
685 derwin/\fBcurs_window\fP(3X)
686 doupdate/\fBcurs_refresh\fP(3X)
687 dupwin/\fBcurs_window\fP(3X)
688 echo/\fBcurs_inopts\fP(3X)
689 echo_wchar/\fBcurs_add_wch\fP(3X)
690 echochar/\fBcurs_addch\fP(3X)
691 endwin/\fBcurs_initscr\fP(3X)
692 erase/\fBcurs_clear\fP(3X)
693 erasechar/\fBcurs_termattrs\fP(3X)
694 erasewchar/\fBcurs_termattrs\fP(3X)
695 exit_curses/\fBcurs_memleaks\fP(3X)*
696 exit_terminfo/\fBcurs_memleaks\fP(3X)*
697 extended_color_content/\fBcurs_color\fP(3X)*
698 extended_pair_content/\fBcurs_color\fP(3X)*
699 extended_slk_color/\fBcurs_slk\fP(3X)*
700 filter/\fBcurs_util\fP(3X)
701 find_pair/\fBnew_pair\fP(3X)*
702 flash/\fBcurs_beep\fP(3X)
703 flushinp/\fBcurs_util\fP(3X)
704 free_pair/\fBnew_pair\fP(3X)*
705 get_escdelay/\fBcurs_threads\fP(3X)*
706 get_wch/\fBcurs_get_wch\fP(3X)
707 get_wstr/\fBcurs_get_wstr\fP(3X)
708 getattrs/\fBcurs_attr\fP(3X)
709 getbegx/\fBcurs_legacy\fP(3X)*
710 getbegy/\fBcurs_legacy\fP(3X)*
711 getbegyx/\fBcurs_getyx\fP(3X)
712 getbkgd/\fBcurs_bkgd\fP(3X)
713 getbkgrnd/\fBcurs_bkgrnd\fP(3X)
714 getcchar/\fBcurs_getcchar\fP(3X)
715 getch/\fBcurs_getch\fP(3X)
716 getcurx/\fBcurs_legacy\fP(3X)*
717 getcury/\fBcurs_legacy\fP(3X)*
718 getmaxx/\fBcurs_legacy\fP(3X)*
719 getmaxy/\fBcurs_legacy\fP(3X)*
720 getmaxyx/\fBcurs_getyx\fP(3X)
721 getmouse/\fBcurs_mouse\fP(3X)*
722 getn_wstr/\fBcurs_get_wstr\fP(3X)
723 getnstr/\fBcurs_getstr\fP(3X)
724 getparx/\fBcurs_legacy\fP(3X)*
725 getpary/\fBcurs_legacy\fP(3X)*
726 getparyx/\fBcurs_getyx\fP(3X)
727 getstr/\fBcurs_getstr\fP(3X)
728 getsyx/\fBcurs_kernel\fP(3X)
729 getwin/\fBcurs_util\fP(3X)
730 getyx/\fBcurs_getyx\fP(3X)
731 halfdelay/\fBcurs_inopts\fP(3X)
732 has_colors/\fBcurs_color\fP(3X)
733 has_ic/\fBcurs_termattrs\fP(3X)
734 has_il/\fBcurs_termattrs\fP(3X)
735 has_key/\fBcurs_getch\fP(3X)*
736 has_mouse/\fBcurs_mouse\fP(3X)*
737 hline/\fBcurs_border\fP(3X)
738 hline_set/\fBcurs_border_set\fP(3X)
739 idcok/\fBcurs_outopts\fP(3X)
740 idlok/\fBcurs_outopts\fP(3X)
741 immedok/\fBcurs_outopts\fP(3X)
742 in_wch/\fBcurs_in_wch\fP(3X)
743 in_wchnstr/\fBcurs_in_wchstr\fP(3X)
744 in_wchstr/\fBcurs_in_wchstr\fP(3X)
745 inch/\fBcurs_inch\fP(3X)
746 inchnstr/\fBcurs_inchstr\fP(3X)
747 inchstr/\fBcurs_inchstr\fP(3X)
748 init_color/\fBcurs_color\fP(3X)
749 init_extended_color/\fBcurs_color\fP(3X)*
750 init_extended_pair/\fBcurs_color\fP(3X)*
751 init_pair/\fBcurs_color\fP(3X)
752 initscr/\fBcurs_initscr\fP(3X)
753 innstr/\fBcurs_instr\fP(3X)
754 innwstr/\fBcurs_inwstr\fP(3X)
755 ins_nwstr/\fBcurs_ins_wstr\fP(3X)
756 ins_wch/\fBcurs_ins_wch\fP(3X)
757 ins_wstr/\fBcurs_ins_wstr\fP(3X)
758 insch/\fBcurs_insch\fP(3X)
759 insdelln/\fBcurs_deleteln\fP(3X)
760 insertln/\fBcurs_deleteln\fP(3X)
761 insnstr/\fBcurs_insstr\fP(3X)
762 insstr/\fBcurs_insstr\fP(3X)
763 instr/\fBcurs_instr\fP(3X)
764 intrflush/\fBcurs_inopts\fP(3X)
765 inwstr/\fBcurs_inwstr\fP(3X)
766 is_cbreak/\fBcurs_inopts\fP(3X)*
767 is_cleared/\fBcurs_opaque\fP(3X)*
768 is_echo/\fBcurs_inopts\fP(3X)*
769 is_idcok/\fBcurs_opaque\fP(3X)*
770 is_idlok/\fBcurs_opaque\fP(3X)*
771 is_immedok/\fBcurs_opaque\fP(3X)*
772 is_keypad/\fBcurs_opaque\fP(3X)*
773 is_leaveok/\fBcurs_opaque\fP(3X)*
774 is_linetouched/\fBcurs_touch\fP(3X)
775 is_nl/\fBcurs_inopts\fP(3X)*
776 is_nodelay/\fBcurs_opaque\fP(3X)*
777 is_notimeout/\fBcurs_opaque\fP(3X)*
778 is_pad/\fBcurs_opaque\fP(3X)*
779 is_raw/\fBcurs_inopts\fP(3X)*
780 is_scrollok/\fBcurs_opaque\fP(3X)*
781 is_subwin/\fBcurs_opaque\fP(3X)*
782 is_syncok/\fBcurs_opaque\fP(3X)*
783 is_term_resized/\fBresizeterm\fP(3X)*
784 is_wintouched/\fBcurs_touch\fP(3X)
785 isendwin/\fBcurs_initscr\fP(3X)
786 key_defined/\fBkey_defined\fP(3X)*
787 key_name/\fBcurs_util\fP(3X)
788 keybound/\fBkeybound\fP(3X)*
789 keyname/\fBcurs_util\fP(3X)
790 keyok/\fBkeyok\fP(3X)*
791 keypad/\fBcurs_inopts\fP(3X)
792 killchar/\fBcurs_termattrs\fP(3X)
793 killwchar/\fBcurs_termattrs\fP(3X)
794 leaveok/\fBcurs_outopts\fP(3X)
795 longname/\fBcurs_termattrs\fP(3X)
796 mcprint/\fBcurs_print\fP(3X)*
797 meta/\fBcurs_inopts\fP(3X)
798 mouse_trafo/\fBcurs_mouse\fP(3X)*
799 mouseinterval/\fBcurs_mouse\fP(3X)*
800 mousemask/\fBcurs_mouse\fP(3X)*
801 move/\fBcurs_move\fP(3X)
802 mvadd_wch/\fBcurs_add_wch\fP(3X)
803 mvadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
804 mvadd_wchstr/\fBcurs_add_wchstr\fP(3X)
805 mvaddch/\fBcurs_addch\fP(3X)
806 mvaddchnstr/\fBcurs_addchstr\fP(3X)
807 mvaddchstr/\fBcurs_addchstr\fP(3X)
808 mvaddnstr/\fBcurs_addstr\fP(3X)
809 mvaddnwstr/\fBcurs_addwstr\fP(3X)
810 mvaddstr/\fBcurs_addstr\fP(3X)
811 mvaddwstr/\fBcurs_addwstr\fP(3X)
812 mvchgat/\fBcurs_attr\fP(3X)
813 mvcur/\fBcurs_kernel\fP(3X)
814 mvdelch/\fBcurs_delch\fP(3X)
815 mvderwin/\fBcurs_window\fP(3X)
816 mvget_wch/\fBcurs_get_wch\fP(3X)
817 mvget_wstr/\fBcurs_get_wstr\fP(3X)
818 mvgetch/\fBcurs_getch\fP(3X)
819 mvgetn_wstr/\fBcurs_get_wstr\fP(3X)
820 mvgetnstr/\fBcurs_getstr\fP(3X)
821 mvgetstr/\fBcurs_getstr\fP(3X)
822 mvhline/\fBcurs_border\fP(3X)
823 mvhline_set/\fBcurs_border_set\fP(3X)
824 mvin_wch/\fBcurs_in_wch\fP(3X)
825 mvin_wchnstr/\fBcurs_in_wchstr\fP(3X)
826 mvin_wchstr/\fBcurs_in_wchstr\fP(3X)
827 mvinch/\fBcurs_inch\fP(3X)
828 mvinchnstr/\fBcurs_inchstr\fP(3X)
829 mvinchstr/\fBcurs_inchstr\fP(3X)
830 mvinnstr/\fBcurs_instr\fP(3X)
831 mvinnwstr/\fBcurs_inwstr\fP(3X)
832 mvins_nwstr/\fBcurs_ins_wstr\fP(3X)
833 mvins_wch/\fBcurs_ins_wch\fP(3X)
834 mvins_wstr/\fBcurs_ins_wstr\fP(3X)
835 mvinsch/\fBcurs_insch\fP(3X)
836 mvinsnstr/\fBcurs_insstr\fP(3X)
837 mvinsstr/\fBcurs_insstr\fP(3X)
838 mvinstr/\fBcurs_instr\fP(3X)
839 mvinwstr/\fBcurs_inwstr\fP(3X)
840 mvprintw/\fBcurs_printw\fP(3X)
841 mvscanw/\fBcurs_scanw\fP(3X)
842 mvvline/\fBcurs_border\fP(3X)
843 mvvline_set/\fBcurs_border_set\fP(3X)
844 mvwadd_wch/\fBcurs_add_wch\fP(3X)
845 mvwadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
846 mvwadd_wchstr/\fBcurs_add_wchstr\fP(3X)
847 mvwaddch/\fBcurs_addch\fP(3X)
848 mvwaddchnstr/\fBcurs_addchstr\fP(3X)
849 mvwaddchstr/\fBcurs_addchstr\fP(3X)
850 mvwaddnstr/\fBcurs_addstr\fP(3X)
851 mvwaddnwstr/\fBcurs_addwstr\fP(3X)
852 mvwaddstr/\fBcurs_addstr\fP(3X)
853 mvwaddwstr/\fBcurs_addwstr\fP(3X)
854 mvwchgat/\fBcurs_attr\fP(3X)
855 mvwdelch/\fBcurs_delch\fP(3X)
856 mvwget_wch/\fBcurs_get_wch\fP(3X)
857 mvwget_wstr/\fBcurs_get_wstr\fP(3X)
858 mvwgetch/\fBcurs_getch\fP(3X)
859 mvwgetn_wstr/\fBcurs_get_wstr\fP(3X)
860 mvwgetnstr/\fBcurs_getstr\fP(3X)
861 mvwgetstr/\fBcurs_getstr\fP(3X)
862 mvwhline/\fBcurs_border\fP(3X)
863 mvwhline_set/\fBcurs_border_set\fP(3X)
864 mvwin/\fBcurs_window\fP(3X)
865 mvwin_wch/\fBcurs_in_wch\fP(3X)
866 mvwin_wchnstr/\fBcurs_in_wchstr\fP(3X)
867 mvwin_wchstr/\fBcurs_in_wchstr\fP(3X)
868 mvwinch/\fBcurs_inch\fP(3X)
869 mvwinchnstr/\fBcurs_inchstr\fP(3X)
870 mvwinchstr/\fBcurs_inchstr\fP(3X)
871 mvwinnstr/\fBcurs_instr\fP(3X)
872 mvwinnwstr/\fBcurs_inwstr\fP(3X)
873 mvwins_nwstr/\fBcurs_ins_wstr\fP(3X)
874 mvwins_wch/\fBcurs_ins_wch\fP(3X)
875 mvwins_wstr/\fBcurs_ins_wstr\fP(3X)
876 mvwinsch/\fBcurs_insch\fP(3X)
877 mvwinsnstr/\fBcurs_insstr\fP(3X)
878 mvwinsstr/\fBcurs_insstr\fP(3X)
879 mvwinstr/\fBcurs_instr\fP(3X)
880 mvwinwstr/\fBcurs_inwstr\fP(3X)
881 mvwprintw/\fBcurs_printw\fP(3X)
882 mvwscanw/\fBcurs_scanw\fP(3X)
883 mvwvline/\fBcurs_border\fP(3X)
884 mvwvline_set/\fBcurs_border_set\fP(3X)
885 napms/\fBcurs_kernel\fP(3X)
886 newpad/\fBcurs_pad\fP(3X)
887 newterm/\fBcurs_initscr\fP(3X)
888 newwin/\fBcurs_window\fP(3X)
889 nl/\fBcurs_inopts\fP(3X)
890 nocbreak/\fBcurs_inopts\fP(3X)
891 nodelay/\fBcurs_inopts\fP(3X)
892 noecho/\fBcurs_inopts\fP(3X)
893 nofilter/\fBcurs_util\fP(3X)*
894 nonl/\fBcurs_inopts\fP(3X)
895 noqiflush/\fBcurs_inopts\fP(3X)
896 noraw/\fBcurs_inopts\fP(3X)
897 notimeout/\fBcurs_inopts\fP(3X)
898 overlay/\fBcurs_overlay\fP(3X)
899 overwrite/\fBcurs_overlay\fP(3X)
900 pair_content/\fBcurs_color\fP(3X)
901 pecho_wchar/\fBcurs_pad\fP(3X)
902 pechochar/\fBcurs_pad\fP(3X)
903 pnoutrefresh/\fBcurs_pad\fP(3X)
904 prefresh/\fBcurs_pad\fP(3X)
905 printw/\fBcurs_printw\fP(3X)
906 putp/\fBcurs_terminfo\fP(3X)
907 putwin/\fBcurs_util\fP(3X)
908 qiflush/\fBcurs_inopts\fP(3X)
909 raw/\fBcurs_inopts\fP(3X)
910 redrawwin/\fBcurs_refresh\fP(3X)
911 refresh/\fBcurs_refresh\fP(3X)
912 reset_color_pairs/\fBcurs_color\fP(3X)*
913 reset_prog_mode/\fBcurs_kernel\fP(3X)
914 reset_shell_mode/\fBcurs_kernel\fP(3X)
915 resetty/\fBcurs_kernel\fP(3X)
916 resize_term/\fBresizeterm\fP(3X)*
917 resizeterm/\fBresizeterm\fP(3X)*
918 restartterm/\fBcurs_terminfo\fP(3X)
919 ripoffline/\fBcurs_kernel\fP(3X)
920 savetty/\fBcurs_kernel\fP(3X)
921 scanw/\fBcurs_scanw\fP(3X)
922 scr_dump/\fBcurs_scr_dump\fP(3X)
923 scr_init/\fBcurs_scr_dump\fP(3X)
924 scr_restore/\fBcurs_scr_dump\fP(3X)
925 scr_set/\fBcurs_scr_dump\fP(3X)
926 scrl/\fBcurs_scroll\fP(3X)
927 scroll/\fBcurs_scroll\fP(3X)
928 scrollok/\fBcurs_outopts\fP(3X)
929 set_curterm/\fBcurs_terminfo\fP(3X)
930 set_escdelay/\fBcurs_threads\fP(3X)*
931 set_tabsize/\fBcurs_threads\fP(3X)*
932 set_term/\fBcurs_initscr\fP(3X)
933 setcchar/\fBcurs_getcchar\fP(3X)
934 setscrreg/\fBcurs_outopts\fP(3X)
935 setsyx/\fBcurs_kernel\fP(3X)
936 setupterm/\fBcurs_terminfo\fP(3X)
937 slk_attr/\fBcurs_slk\fP(3X)*
938 slk_attr_off/\fBcurs_slk\fP(3X)
939 slk_attr_on/\fBcurs_slk\fP(3X)
940 slk_attr_set/\fBcurs_slk\fP(3X)
941 slk_attroff/\fBcurs_slk\fP(3X)
942 slk_attron/\fBcurs_slk\fP(3X)
943 slk_attrset/\fBcurs_slk\fP(3X)
944 slk_clear/\fBcurs_slk\fP(3X)
945 slk_color/\fBcurs_slk\fP(3X)
946 slk_init/\fBcurs_slk\fP(3X)
947 slk_label/\fBcurs_slk\fP(3X)
948 slk_noutrefresh/\fBcurs_slk\fP(3X)
949 slk_refresh/\fBcurs_slk\fP(3X)
950 slk_restore/\fBcurs_slk\fP(3X)
951 slk_set/\fBcurs_slk\fP(3X)
952 slk_touch/\fBcurs_slk\fP(3X)
953 slk_wset/\fBcurs_slk\fP(3X)
954 standend/\fBcurs_attr\fP(3X)
955 standout/\fBcurs_attr\fP(3X)
956 start_color/\fBcurs_color\fP(3X)
957 subpad/\fBcurs_pad\fP(3X)
958 subwin/\fBcurs_window\fP(3X)
959 syncok/\fBcurs_window\fP(3X)
960 term_attrs/\fBcurs_termattrs\fP(3X)
961 termattrs/\fBcurs_termattrs\fP(3X)
962 termname/\fBcurs_termattrs\fP(3X)
963 tgetent/\fBcurs_termcap\fP(3X)
964 tgetflag/\fBcurs_termcap\fP(3X)
965 tgetnum/\fBcurs_termcap\fP(3X)
966 tgetstr/\fBcurs_termcap\fP(3X)
967 tgoto/\fBcurs_termcap\fP(3X)
968 tigetflag/\fBcurs_terminfo\fP(3X)
969 tigetnum/\fBcurs_terminfo\fP(3X)
970 tigetstr/\fBcurs_terminfo\fP(3X)
971 timeout/\fBcurs_inopts\fP(3X)
972 tiparm/\fBcurs_terminfo\fP(3X)
973 tiparm_s/\fBcurs_terminfo\fP(3X)*
974 tiscan_s/\fBcurs_terminfo\fP(3X)*
975 touchline/\fBcurs_touch\fP(3X)
976 touchwin/\fBcurs_touch\fP(3X)
977 tparm/\fBcurs_terminfo\fP(3X)
978 tputs/\fBcurs_termcap\fP(3X)
979 tputs/\fBcurs_terminfo\fP(3X)
980 trace/\fBcurs_trace\fP(3X)*
981 typeahead/\fBcurs_inopts\fP(3X)
982 unctrl/\fBcurs_util\fP(3X)
983 unget_wch/\fBcurs_get_wch\fP(3X)
984 ungetch/\fBcurs_getch\fP(3X)
985 ungetmouse/\fBcurs_mouse\fP(3X)*
986 untouchwin/\fBcurs_touch\fP(3X)
987 use_default_colors/\fBdefault_colors\fP(3X)*
988 use_env/\fBcurs_util\fP(3X)
989 use_extended_names/\fBcurs_extend\fP(3X)*
990 use_legacy_coding/\fBlegacy_coding\fP(3X)*
991 use_screen/\fBcurs_threads\fP(3X)*
992 use_tioctl/\fBcurs_util\fP(3X)*
993 use_window/\fBcurs_threads\fP(3X)*
994 vid_attr/\fBcurs_terminfo\fP(3X)
995 vid_puts/\fBcurs_terminfo\fP(3X)
996 vidattr/\fBcurs_terminfo\fP(3X)
997 vidputs/\fBcurs_terminfo\fP(3X)
998 vline/\fBcurs_border\fP(3X)
999 vline_set/\fBcurs_border_set\fP(3X)
1000 vw_printw/\fBcurs_printw\fP(3X)
1001 vw_scanw/\fBcurs_scanw\fP(3X)
1002 vwprintw/\fBcurs_printw\fP(3X)
1003 vwscanw/\fBcurs_scanw\fP(3X)
1004 wadd_wch/\fBcurs_add_wch\fP(3X)
1005 wadd_wchnstr/\fBcurs_add_wchstr\fP(3X)
1006 wadd_wchstr/\fBcurs_add_wchstr\fP(3X)
1007 waddch/\fBcurs_addch\fP(3X)
1008 waddchnstr/\fBcurs_addchstr\fP(3X)
1009 waddchstr/\fBcurs_addchstr\fP(3X)
1010 waddnstr/\fBcurs_addstr\fP(3X)
1011 waddnwstr/\fBcurs_addwstr\fP(3X)
1012 waddstr/\fBcurs_addstr\fP(3X)
1013 waddwstr/\fBcurs_addwstr\fP(3X)
1014 wattr_get/\fBcurs_attr\fP(3X)
1015 wattr_off/\fBcurs_attr\fP(3X)
1016 wattr_on/\fBcurs_attr\fP(3X)
1017 wattr_set/\fBcurs_attr\fP(3X)
1018 wattroff/\fBcurs_attr\fP(3X)
1019 wattron/\fBcurs_attr\fP(3X)
1020 wattrset/\fBcurs_attr\fP(3X)
1021 wbkgd/\fBcurs_bkgd\fP(3X)
1022 wbkgdset/\fBcurs_bkgd\fP(3X)
1023 wbkgrnd/\fBcurs_bkgrnd\fP(3X)
1024 wbkgrndset/\fBcurs_bkgrnd\fP(3X)
1025 wborder/\fBcurs_border\fP(3X)
1026 wborder_set/\fBcurs_border_set\fP(3X)
1027 wchgat/\fBcurs_attr\fP(3X)
1028 wclear/\fBcurs_clear\fP(3X)
1029 wclrtobot/\fBcurs_clear\fP(3X)
1030 wclrtoeol/\fBcurs_clear\fP(3X)
1031 wcolor_set/\fBcurs_attr\fP(3X)
1032 wcursyncup/\fBcurs_window\fP(3X)
1033 wdelch/\fBcurs_delch\fP(3X)
1034 wdeleteln/\fBcurs_deleteln\fP(3X)
1035 wecho_wchar/\fBcurs_add_wch\fP(3X)
1036 wechochar/\fBcurs_addch\fP(3X)
1037 wenclose/\fBcurs_mouse\fP(3X)*
1038 werase/\fBcurs_clear\fP(3X)
1039 wget_wch/\fBcurs_get_wch\fP(3X)
1040 wget_wstr/\fBcurs_get_wstr\fP(3X)
1041 wgetbkgrnd/\fBcurs_bkgrnd\fP(3X)
1042 wgetch/\fBcurs_getch\fP(3X)
1043 wgetdelay/\fBcurs_opaque\fP(3X)*
1044 wgetn_wstr/\fBcurs_get_wstr\fP(3X)
1045 wgetnstr/\fBcurs_getstr\fP(3X)
1046 wgetparent/\fBcurs_opaque\fP(3X)*
1047 wgetscrreg/\fBcurs_opaque\fP(3X)*
1048 wgetstr/\fBcurs_getstr\fP(3X)
1049 whline/\fBcurs_border\fP(3X)
1050 whline_set/\fBcurs_border_set\fP(3X)
1051 win_wch/\fBcurs_in_wch\fP(3X)
1052 win_wchnstr/\fBcurs_in_wchstr\fP(3X)
1053 win_wchstr/\fBcurs_in_wchstr\fP(3X)
1054 winch/\fBcurs_inch\fP(3X)
1055 winchnstr/\fBcurs_inchstr\fP(3X)
1056 winchstr/\fBcurs_inchstr\fP(3X)
1057 winnstr/\fBcurs_instr\fP(3X)
1058 winnwstr/\fBcurs_inwstr\fP(3X)
1059 wins_nwstr/\fBcurs_ins_wstr\fP(3X)
1060 wins_wch/\fBcurs_ins_wch\fP(3X)
1061 wins_wstr/\fBcurs_ins_wstr\fP(3X)
1062 winsch/\fBcurs_insch\fP(3X)
1063 winsdelln/\fBcurs_deleteln\fP(3X)
1064 winsertln/\fBcurs_deleteln\fP(3X)
1065 winsnstr/\fBcurs_insstr\fP(3X)
1066 winsstr/\fBcurs_insstr\fP(3X)
1067 winstr/\fBcurs_instr\fP(3X)
1068 winwstr/\fBcurs_inwstr\fP(3X)
1069 wmouse_trafo/\fBcurs_mouse\fP(3X)*
1070 wmove/\fBcurs_move\fP(3X)
1071 wnoutrefresh/\fBcurs_refresh\fP(3X)
1072 wprintw/\fBcurs_printw\fP(3X)
1073 wredrawln/\fBcurs_refresh\fP(3X)
1074 wrefresh/\fBcurs_refresh\fP(3X)
1075 wresize/\fBwresize\fP(3X)*
1076 wscanw/\fBcurs_scanw\fP(3X)
1077 wscrl/\fBcurs_scroll\fP(3X)
1078 wsetscrreg/\fBcurs_outopts\fP(3X)
1079 wstandend/\fBcurs_attr\fP(3X)
1080 wstandout/\fBcurs_attr\fP(3X)
1081 wsyncdown/\fBcurs_window\fP(3X)
1082 wsyncup/\fBcurs_window\fP(3X)
1083 wtimeout/\fBcurs_inopts\fP(3X)
1084 wtouchln/\fBcurs_touch\fP(3X)
1085 wunctrl/\fBcurs_util\fP(3X)
1086 wvline/\fBcurs_border\fP(3X)
1087 wvline_set/\fBcurs_border_set\fP(3X)
1088 .TE
1089 .PP
1090 .IR \%ncurses 's
1091 .I "screen-pointer extension"
1092 adds additional functions corresponding to many of the above,
1093 each with an \*(``_sp\*('' suffix;
1094 see \fBcurs_sp_funcs\fP(3X).
1095 .PP
1096 The availability of some extensions is configurable when
1097 .I \%ncurses
1098 is compiled;
1099 see sections \*(``ALTERNATE CONFIGURATIONS\*('' and \*(``EXTENSIONS\*(''
1100 below.
1101 .SH RETURN VALUE
1102 Unless otherwise noted,
1103 functions that return integers return the constants
1104 .B OK
1105 on success and
1106 .B ERR
1107 on failure;
1108 see \fB\%curs_variables\fP(3X).
1109 Functions that return pointers return
1110 .I NULL
1111 on failure.
1112 Typically,
1113 .I \%ncurses
1114 treats a null pointer passed as a function parameter as a failure.
1115 Functions prefixed with \*(``mv\*('' first perform cursor movement and
1116 fail if the position
1117 .RI ( y ,
1118 .IR x )
1119 is outside the window boundaries.
1120 .SH ENVIRONMENT
1121 The following symbols from the process environment customize the
1122 runtime behavior of
1123 .I \%ncurses
1124 applications.
1125 The library may be configured to disregard the variables
1126 .IR \%TERMINFO ,
1127 .IR \%TERMINFO_DIRS ,
1128 .IR \%TERMPATH ,
1129 and
1130 .IR HOME ,
1131 if the user is the superuser (root),
1132 or the application uses \fI\%setuid\fP(2) or \fI\%setgid\fP(2).
1133 .SS "\fIBAUDRATE\fP"
1134 The debugging library checks this variable when the application has
1135 redirected output to a file.
1136 .I \%ncurses
1137 interprets its integral value as the terminal's line speed
1138 in bits per second.
1139 If that value is absent or invalid,
1140 .I \%ncurses
1141 uses 9600.
1142 This feature allows developers to construct repeatable test cases
1143 that take into account optimization decisions that depend
1144 on the terminal's line speed.
1145 .SS "\fICC\fP (command character)"
1146 When set,
1147 the
1148 .B \%command_character
1149 .RB \%( cmdch )
1150 capability value of loaded
1151 .I \%term\%info
1152 entries changes to the value of this variable.
1153 Very few
1154 .I \%term\%info
1155 entries provide this feature.
1156 .PP
1157 Because this name is also used in development environments to store the
1158 C compiler's name,
1159 .I \%ncurses
1160 ignores its value if it is not one character in length.
1161 .SS "\fICOLUMNS\fP"
1162 This variable specifies the width of the screen in characters.
1163 Applications running in a windowing environment usually are able to
1164 obtain the width of the window in which they are executing.
1165 .I \%ncurses
1166 enforces an upper limit of 512 when reading the value.
1167 If
1168 .I \%COLUMNS
1169 is not defined and the terminal's screen size is not available from the
1170 terminal driver,
1171 .I \%ncurses
1172 uses the size specified by the
1173 .B \%columns
1174 .RB \%( cols )
1175 capability of the terminal type's entry in the
1176 .I \%term\%info
1177 database,
1178 if any.
1179 .PP
1180 It is important that your application use the correct screen size.
1181 Automatic detection thereof is not always possible because an
1182 application may be running on a host that does not honor NAWS
1183 (Negotiations About Window Size)
1184 or as a different user ID than the owner of the terminal device file.
1185 Setting
1186 .I \%COLUMNS
1187 and/or
1188 .I \%LINES
1189 overrides the library's use of the screen size obtained from the
1190 operating system.
1191 .PP
1192 The
1193 .I \%COLUMNS
1194 and
1195 .I \%LINES
1196 variables may be specified independently.
1197 This property is useful to circumvent misfeatures of legacy terminal
1198 type descriptions;
1199 \fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
1200 For best results,
1201 avoid specifying
1202 .B cols
1203 and
1204 .B lines
1205 capability codes in
1206 .I \%term\%info
1207 descriptions of terminal emulators.
1208 .PP
1209 \fBuse_env\fP(3X) can disable use of the process environment
1210 in determining the screen size.
1211 \fBuse_tioctl\fP(3X) can update
1212 .I \%COLUMNS
1213 and
1214 .I \%LINES
1215 to match the screen size obtained from system calls or the terminal
1216 database.
1217 .SS "\fIESCDELAY\fP"
1218 For
1219 .I curses
1220 to distinguish the ESC character resulting from a user's press of the
1221 \*(``Escape\*('' key on the input device from one beginning an
1222 .I "escape sequence"
1223 (as commonly produced by function keys),
1224 it waits after receiving the escape character to see if further
1225 characters are available on the input stream within a short interval.
1226 A global variable
1227 .B \%ESCDELAY
1228 stores this interval in milliseconds.
1229 The default value of 1000
1230 (one second)
1231 is adequate for most uses.
1232 This environment variable overrides it;
1233 .I \%ncurses
1234 enforces an upper limit of 30,000
1235 (30 seconds)
1236 when reading the value.
1237 .PP
1238 The most common instance where you may wish to change this value
1239 is to work with a remote host over a slow communication channel.
1240 If the host running a
1241 .I curses
1242 application does not receive the characters of an escape sequence in a
1243 timely manner,
1244 the library can interpret them as multiple key stroke events.
1245 .PP
1246 \fI\%xterm\fP(1) mouse events are a form of escape sequence;
1247 therefore,
1248 if your application makes heavy use of multiple-clicking,
1249 you may wish to lengthen the default value because the delay applies
1250 to the composite multi-click event as well as the individual clicks.
1251 .PP
1252 Portable applications should not rely upon the presence of
1253 .B \%ESCDELAY
1254 in either form,
1255 but setting the environment variable rather than the global variable
1256 does not create problems when compiling an application.
1257 .PP
1258 If \fB\%keypad\fP(3X) is disabled for the
1259 .I curses
1260 window receiving input,
1261 a program must disambiguate escape sequences itself.
1262 .SS "\fIHOME\fP"
1263 .I \%ncurses
1264 may read and write auxiliary terminal descriptions in
1265 .I \%.termcap
1266 and
1267 .I \%.terminfo
1268 files in the user's home directory.
1269 .SS "\fILINES\fP"
1270 This counterpart to
1271 .I \%COLUMNS
1272 specifies the height of the screen in characters.
1273 The corresponding
1274 .I \%term\%info
1275 capability and code is
1276 .BR \%lines .
1277 See the description of the
1278 .I \%COLUMNS
1279 variable above.
1280 .SS "\fIMOUSE_BUTTONS_123\fP"
1281 (OS/2 EMX port only)
1282 OS/2 numbers a three-button mouse inconsistently with other platforms,
1283 such that 1 is the left button,
1284 2 the right,
1285 and 3 the middle.
1286 This variable customizes the mouse button numbering.
1287 Its value must be three digits 1\-3 in any order.
1288 By default,
1289 .I \%ncurses
1290 assumes a numbering of \*(``132\*(''.
1291 .SS "\fINCURSES_ASSUMED_COLORS\fP"
1292 If set,
1293 this variable overrides the
1294 .I \%ncurses
1295 library's compiled-in assumption that the terminal's default colors are
1296 white on black;
1297 see \fB\%default_colors\fP(3X).
1298 Set the foreground and background color values with this environment
1299 variable by assigning it two integer values separated by a comma,
1300 indicating foregound and background color numbers,
1301 respectively.
1302 .PP
1303 For example,
1304 to tell
1305 .I \%ncurses
1306 not to assume anything about the colors,
1307 use a value of \*(``\-1,\-1\*(''.
1308 To make the default color scheme green on black,
1309 use \*(``2,0\*(''.
1310 .I \%ncurses
1311 accepts integral values from \-1 up to the value of the
1312 .I \%term\%info
1313 .B \%max_colors
1314 .RB ( colors )
1315 capability for the selected terminal type.
1316 .SS "\fINCURSES_CONSOLE2\fP"
1317 (MinGW port only)
1318 The
1319 .I \%Console2
1320 .\" https://www.hanselman.com/blog/console2-a-better-windows-command-prompt
1321 program defectively handles the Microsoft Console API call
1322 .IR \%Create\%Console\%Screen\%Buffer .
1323 Applications that use it will hang.
1324 However,
1325 it is possible to simulate the action of this call by mapping
1326 coordinates,
1327 explicitly saving and restoring the original screen contents.
1328 Setting the environment variable
1329 .I \%NCGDB
1330 has the same effect.
1331 .SS "\fINCURSES_GPM_TERMS\fP"
1332 (Linux only)
1333 When
1334 .I \%ncurses
1335 is configured to use the GPM interface,
1336 this variable may list one or more terminal type names,
1337 delimited by vertical bars
1338 .RB ( | )
1339 or colons
1340 .RB ( : ),
1341 against which the
1342 .I TERM
1343 variable
1344 (see below)
1345 is matched.
1346 An empty value disables the GPM interface,
1347 using
1348 .IR \%ncurses 's
1349 built-in support for \fI\%xterm\fP(1) mouse protocols instead.
1350 If the variable is absent,
1351 .I \%ncurses
1352 attempts to open GPM if
1353 .I TERM
1354 contains \*(``linux\*(''.
1355 .SS "\fINCURSES_NO_HARD_TABS\fP"
1356 .I \%ncurses
1357 may use tab characters in cursor movement optimization.
1358 In some cases,
1359 your terminal driver may not handle them properly.
1360 Set this environment variable to any value to disable the feature.
1361 You can also adjust your \fI\%stty\fP(1) settings to avoid the problem.
1362 .SS "\fINCURSES_NO_MAGIC_COOKIE\fP"
1363 Many terminals store video attributes as properties of a character cell,
1364 as
1365 .I curses
1366 does.
1367 Historically,
1368 some recorded changes in video attributes as data that logically
1369 .I occupied
1370 character cells on the display,
1371 switching attributes on or off,
1372 similarly to tags in a markup language,
1373 which then had to be overprinted to depict the cells' desired contents;
1374 these are termed \*(``magic cookies\*(''.
1375 If the
1376 .I \%term\%info
1377 entry for your terminal type does not adequately describe its handling
1378 of magic cookies,
1379 set this variable to any value to instruct
1380 .I \%ncurses
1381 to disable attributes entirely.
1382 .SS "\fINCURSES_NO_PADDING\fP"
1383 Most terminal type descriptions in the
1384 .I \%term\%info
1385 database detail hardware devices.
1386 Many people use
1387 .IR curses -based
1388 applications in terminal emulator programs that run in a windowing
1389 environment.
1390 These programs can duplicate all of the important features of a hardware
1391 terminal,
1392 but often lack their limitations.
1393 Chief among these absent drawbacks is the problem of data flow
1394 management;
1395 that is,
1396 limiting the speed of communication to what the hardware could handle.
1397 Unless a hardware terminal is interfaced into a terminal concentrator
1398 (which does flow control),
1399 an application must manage flow itself to prevent overruns and data
1400 loss.
1401 .PP
1402 A solution that comes at no hardware cost is for an application to pause
1403 after directing a terminal to execute an operation that it performs
1404 slowly,
1405 such as clearing the display.
1406 Many terminal type descriptions,
1407 including that for the VT100,
1408 embed delay specifications in capabilities.
1409 You may wish to use these terminal descriptions without paying the
1410 performance penalty.
1411 Set
1412 .I \%NCURSES_NO_PADDING
1413 to any value to disable all but mandatory padding.
1414 Mandatory padding is used by such terminal capabilities as
1415 .B \%flash_screen
1416 .RB ( flash ).
1417 .SS "\fINCURSES_NO_SETBUF\fP"
1418 (Obsolete)
1419 Prior to internal changes developed in
1420 .I \%ncurses
1421 5.9
1422 (patches 20120825 through 20130126),
1423 the library used \fI\%setbuf\fP(3) to enable fully buffered output when
1424 initializing the terminal.
1425 This was done,
1426 as in SVr4
1427 .IR curses ,
1428 to increase performance.
1429 For testing purposes,
1430 both of
1431 .I \%ncurses
1432 and of certain applications,
1433 this feature was made optional.
1434 Setting this variable disabled output buffering,
1435 leaving the output stream in the original
1436 (usually line-buffered)
1437 mode.
1438 .PP
1439 Nowadays,
1440 .I \%ncurses
1441 performs its own buffering and does not require this workaround;
1442 it does not modify the buffering of the standard output stream.
1443 This approach makes signal handling,
1444 as for interrupts,
1445 more robust.
1446 A drawback is that certain unconventional programs mixed
1447 \fI\%stdio\fP(3) calls with
1448 .I \%ncurses
1449 calls and (usually)
1450 got the behavior they expected.
1451 This is no longer the case;
1452 .I \%ncurses
1453 does not write to the standard output file descriptor through a
1454 .IR stdio -buffered
1455 stream.
1456 .PP
1457 As a special case,
1458 low-level API calls such as \fB\%putp\fP(3X) still use the
1459 standard output stream.
1460 High-level
1461 .I curses
1462 calls such as \fB\%printw\fP(3X) do not.
1463 .SS "\fINCURSES_NO_UTF8_ACS\fP"
1464 At initialization,
1465 .I \%ncurses
1466 inspects the
1467 .I TERM
1468 environment variable for special cases where VT100 forms-drawing
1469 characters
1470 (and the corresponding alternate character set
1471 .I \%term\%info
1472 capabilities)
1473 are known to be unsupported by terminal types that otherwise claim VT100
1474 compatibility.
1475 Specifically,
1476 when running in a UTF-8 locale,
1477 the Linux virtual console device and the GNU \fI\%screen\fP(1)
1478 program ignore them.
1479 Set this variable to a nonzero value to instruct
1480 .I \%ncurses
1481 that the terminal's ACS support is broken;
1482 the library then outputs Unicode code points that correspond to the
1483 forms-drawing
1484 characters.
1485 Set it to zero
1486 (or a non-integer)
1487 to disable the special check for terminal type names matching
1488 \*(``linux\*('' or \*(``screen\*('',
1489 directing
1490 .I \%ncurses
1491 to assume that the ACS feature works if the terminal type description
1492 advertises it.
1493 .PP
1494 As an alternative to use of this variable,
1495 .I \%ncurses
1496 checks for an extended
1497 .I \%term\%info
1498 numeric capability \fBU8\fP
1499 that can be compiled using
1500 .RB \*(`` "tic \-x" \*(''.
1501 Examples follow.
1502 .PP
1503 .RS 3
1504 .EX
1505 .nf
1506 # linux console, if patched to provide working
1507 # VT100 shift\-in/shift\-out, with corresponding font.
1508 linux\-vt100|linux console with VT100 line\-graphics,
1509 U8#0, use=linux,
1510 \&
1511 # uxterm with vt100Graphics resource set to false
1512 xterm\-utf8|xterm relying on UTF\-8 line\-graphics,
1513 U8#1, use=xterm,
1514 .fi
1515 .EE
1516 .RE
1517 .PP
1518 The two-character name \*(``U8\*('' was chosen to permit its use via
1519 .IR \%ncurses 's
1520 .I termcap
1521 interface.
1522 .SS "\fINCURSES_TRACE\fP"
1523 At initialization,
1524 .I \%ncurses
1525 (in its debugging configuration)
1526 checks for this variable's presence.
1527 If defined with an integral value,
1528 the library calls \fB\%curses_trace\fP(3X) with that value as the
1529 argument.
1530 .SS "\fITERM\fP"
1531 The
1532 .I TERM
1533 variable denotes the terminal type.
1534 Each is distinct,
1535 though many are similar.
1536 It is commonly set by terminal emulators to help applications find a
1537 workable terminal description.
1538 Some choose a popular approximation such as \*(``ansi\*('',
1539 \*(``vt100\*('', or \*(``xterm\*('' rather than an exact fit to their
1540 capabilities.
1541 Not infrequently,
1542 an application will have problems with that approach;
1543 for example,
1544 a key stroke may not operate correctly,
1545 or produce no effect but seeming garbage characters on the screen.
1546 .PP
1547 Setting
1548 .I TERM
1549 has no effect on hardware operation;
1550 it affects the way applications communicate with the terminal.
1551 Likewise,
1552 as a general rule
1553 (\fIxterm\fP(1) being a rare exception),
1554 terminal emulators that allow you to specify
1555 .I TERM
1556 as a parameter or configuration value do not change their behavior to
1557 match that setting.
1558 .SS "\fITERMCAP\fP"
1559 If
1560 .I \%ncurses
1561 is configured with
1562 .I termcap
1563 support,
1564 it checks for a terminal type description in
1565 .I termcap
1566 format if one in
1567 .I \%term\%info
1568 format is not available.
1569 Setting this variable directs
1570 .I \%ncurses
1571 to ignore the usual
1572 .I termcap
1573 database location,
1574 .IR \%/etc/termcap ;
1575 see
1576 .I \%TERMPATH
1577 below.
1578 .I \%TERMCAP
1579 should contain either a terminal description
1580 (with newlines stripped out),
1581 or a file name indicating where the information required by the
1582 .I TERM
1583 environment variable is stored.
1584 .SS "\fITERMINFO\fP"
1585 .I \%ncurses
1586 can be configured to read terminal type description databases in various
1587 locations using different formats.
1588 This variable overrides the default location.
1589 .bP
1590 Descriptions in
1591 .I \%term\%info
1592 format are normally stored in a directory tree using subdirectories
1593 named for the common first letters of the terminal types named therein.
1594 System\ V used this scheme.
1595 .bP
1596 If
1597 .I \%ncurses
1598 is configured to use hashed databases,
1599 then
1600 .I \%TERM\%INFO
1601 may name its location,
1602 such as
1603 .IR \%/usr/share/terminfo.db ,
1604 rather than
1605 .IR \%/usr/share/terminfo/ .
1606 .PP
1607 The hashed database uses less disk space and is a little faster than the
1608 directory tree.
1609 However,
1610 some applications assume the existence of the directory tree,
1611 and read it directly
1612 rather than using the
1613 .I \%term\%info
1614 API.
1615 .bP
1616 If
1617 .I \%ncurses
1618 is configured with
1619 .I termcap
1620 support,
1621 this variable may contain the location of a
1622 .I \%termcap
1623 file.
1624 .bP
1625 If the value of
1626 .I \%TERM\%INFO
1627 begins with \*(``hex:\*('' or \*(``b64:\*('',
1628 .I \%ncurses
1629 uses the remainder of the value as a compiled
1630 .I \%term\%info
1631 description.
1632 You might produce the base64 format using \fB\%infocmp\fP(1M).
1633 .RS 4
1634 .IP
1635 .EX
1636 .nf
1637 TERMINFO=$(infocmp \-0 \-Q2 \-q)
1638 export TERMINFO
1639 .fi
1640 .EE
1641 .RE
1642 .IP
1643 .I \%ncurses
1644 uses the compiled description only if it corresponds
1645 to the terminal type identified by
1646 .IR TERM .
1647 .PP
1648 Setting
1649 .I \%TERM\%INFO
1650 is the simplest,
1651 but not the only,
1652 way to direct
1653 .I \%ncurses
1654 to a terminal database.
1655 The search path is as follows.
1656 .bP
1657 the last terminal database to which the running
1658 .I \%ncurses
1659 application wrote,
1660 if any
1661 .bP
1662 the location specified by the
1663 .I \%TERM\%INFO
1664 environment variable
1665 .bP
1666 .I $HOME/.terminfo
1667 .bP
1668 locations listed in the
1669 .I \%TERMINFO_DIRS
1670 environment variable
1671 .ds td \" empty
1672 .if !'/usr/share/terminfo'no default value' .as td /usr/share/terminfo
1673 .if !'/usr/share/terminfo\*(td'' \{\
1674 .bP
1675 location(s) configured and compiled into
1676 .I \%ncurses
1677 .RS
1678 .if !'\*(td'' \{\
1679 .bP
1680 .I \%/usr/share/terminfo
1681 .\}
1682 .if !'@TERMINFO'' .if !'\*(td'/usr/share/terminfo' \{\
1683 .bP
1684 .I \%/usr/share/terminfo
1685 .\}
1686 .\}
1687 .RE
1688 .SS "\fITERMINFO_DIRS\fP"
1689 This variable specifies a list of locations,
1690 akin to
1691 .IR PATH ,
1692 in which
1693 .I \%ncurses
1694 searches for the terminal type descriptions described by
1695 .I \%TERMINFO
1696 above.
1697 The list items are separated by colons on Unix
1698 and semicolons on OS/2 EMX.
1699 System\ V
1700 .I \%term\%info
1701 lacks a corresponding feature;
1702 .I \%TERMINFO_DIRS
1703 is an
1704 .I \%ncurses
1705 extension.
1706 .SS "\fITERMPATH\fP"
1707 If
1708 .I \%TERMCAP
1709 does not hold a terminal type description or file name,
1710 then
1711 .I \%ncurses
1712 checks the contents of
1713 .IR \%TERMPATH ,
1714 a list of locations,
1715 akin to
1716 .IR PATH ,
1717 in which it searches for
1718 .I termcap
1719 terminal type descriptions.
1720 The list items are separated by colons on Unix
1721 and semicolons on OS/2 EMX.
1722 .PP
1723 If both
1724 .I \%TERMCAP
1725 and
1726 .I \%TERMPATH
1727 are unset or invalid,
1728 .I \%ncurses
1729 searches for the files
1730 .IR \%/etc/termcap ,
1731 .IR \%/usr/share/misc/termcap ,
1732 and
1733 .IR \%$HOME/.termcap ,
1734 in that order.
1735 .SH "ALTERNATE CONFIGURATIONS"
1736 Many different
1737 .I \%ncurses
1738 configurations are possible,
1739 determined by the options given to the
1740 .I \%configure
1741 script when building the library.
1742 Run the script with the
1743 .B \%\-\-help
1744 option to peruse them all.
1745 A few are of particular significance to the application developer
1746 employing
1747 .IR \%ncurses .
1748 .TP 5
1749 .B \-\-disable\-overwrite
1750 The standard C preprocessor inclusion for the
1751 .I curses
1752 library is as follows.
1753 .RS 5
1754 .PP
1755 .RS 4
1756 .EX
1757 .nf
1758 .\" The dummy character prevents undesired rewriting of the next line on
1759 .\" installation of the man page.
1760 \fB#\&include <curses.h>\fP
1761 .fi
1762 .EE
1763 .RE
1764 .PP
1765 This option is used to avoid file name conflicts between
1766 .I \%ncurses
1767 and an existing
1768 .I curses
1769 installation on the system.
1770 If
1771 .I \%ncurses
1772 is installed disabling overwrite,
1773 it puts its header files in a subdirectory.
1774 Here is an example.
1775 .PP
1776 .RS 4
1777 .EX
1778 .\" The dummy character prevents undesired rewriting of the next line on
1779 .\" installation of the man page.
1780 \fB#\&include <ncurses/curses.h>\fP
1781 .EE
1782 .RE
1783 .PP
1784 Installation also omits a symbolic link that would cause the compiler's
1785 .B \%\-lcurses
1786 option to link object files with
1787 .I \%ncurses
1788 instead of the system
1789 .I curses
1790 library.
1791 .PP
1792 The directory used by this configuration of
1793 .I \%ncurses
1794 is shown in section \*(``SYNOPSIS\*('' above.
1795 .RE
1796 .TP 5
1797 .B \-\-enable\-widec
1798 The configure script renames the library and
1799 (if the
1800 .B \%\-\-disable\-overwrite
1801 option is used)
1802 puts the header files in a different subdirectory.
1803 All of the library names have a \*(``w\*('' appended to them,
1804 i.e., instead of
1805 .RS 5
1806 .PP
1807 .RS 4
1808 .EX
1809 .B \-lncurses
1810 .EE
1811 .RE
1812 .PP
1813 you link with
1814 .PP
1815 .RS 4
1816 .EX
1817 .B \-lncursesw
1818 .EE
1819 .RE
1820 .PP
1821 You must also enable the wide-character features in the header file
1822 when compiling for the wide-character library
1823 to use the extended (wide-character) functions.
1824 The symbol which enables these features has changed
1825 since X/Open Curses Issue\ 4:
1826 .bP
1827 Originally,
1828 the wide-character feature required the symbol
1829 .B \%_XOPEN_SOURCE_EXTENDED
1830 but that was only valid for XPG4 (1996).
1831 .bP
1832 Later,
1833 that was deemed conflicting with an
1834 .B \%_XOPEN_SOURCE
1835 value of 500.
1836 .bP
1837 As of mid-2018,
1838 none of the features in this implementation require a
1839 .B \%_XOPEN_SOURCE
1840 feature greater than 600.
1841 However,
1842 X/Open Curses Issue\ 7 (2009) recommends defining it to 700.
1843 .bP
1844 Alternatively,
1845 you can enable the feature by defining
1846 .B \%NCURSES_WIDECHAR
1847 with the caveat that some header file other than
1848 .I \%curses.h
1849 may require a specific value for
1850 .B \%_XOPEN_SOURCE
1851 (or a system-specific symbol).
1852 .PP
1853 The
1854 .I \%curses.h
1855 header file installed
1856 for the wide-character library
1857 is designed to be compatible with the non-wide library's header.
1858 Only the size of the
1859 .I \%WINDOW
1860 structure differs;
1861 few applications require more than pointers to
1862 .IR \%WINDOW "."
1863 .PP
1864 If the headers are installed allowing overwrite,
1865 the wide-character library's headers should be installed last,
1866 to allow applications to be built using either library
1867 from the same set of headers.
1868 .RE
1869 .TP 5
1870 .B \-\-with\-pthread
1871 The configure script renames the library.
1872 All of the library names have a \*(``t\*('' appended to them
1873 (before any \*(``w\*('' added by
1874 .BR \%\-\-enable\-widec ).
1875 .IP
1876 .I \%ncursest
1877 and
1878 .I \%ncursestw
1879 replace global variables such as
1880 .B \%LINES
1881 with macros allowing read-only access.
1882 At the same time,
1883 they provide functions to set these values.
1884 Very few applications require changes
1885 to work with this convention.
1886 .\" see definition of NCURSES_WRAPPED_VAR
1887 .TP 5
1888 .B \-\-with\-shared
1889 .tQ
1890 .B \-\-with\-normal
1891 .tQ
1892 .B \-\-with\-debug
1893 .tQ
1894 .B \-\-with\-profile
1895 The shared and normal (static) library names differ by their suffixes,
1896 e.g.,
1897 .I \%libncurses.so
1898 and
1899 .IR \%libncurses.a "."
1900 The debug and profiling libraries add a \*(``_g\*(''
1901 and a \*(``_p\*('' to the roots of these respective names,
1902 forming
1903 .I \%libncurses_g.so
1904 and
1905 .IR \%libncurses_p.a ","
1906 for example.
1907 .TP 5
1908 .B \-\-with\-termlib
1909 This option configures
1910 .I \%ncurses
1911 to provide low-level functions that do not depend
1912 upon wide-character support in a library named
1913 .IR \%tinfo "."
1914 .IP
1915 This arrangement enables
1916 .I \%tinfo
1917 to be shared between
1918 .I \%ncurses
1919 and
1920 .I \%ncursesw
1921 libraries
1922 and reduces an application's linking and/or loading times
1923 when it requires only low-level functions.
1924 .IP
1925 The following pages describe low-level
1926 .I curses
1927 functions.
1928 .RS
1929 .bP
1930 \fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
1931 .bP
1932 \fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
1933 .bP
1934 \fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
1935 .bP
1936 \fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
1937 .bP
1938 \fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
1939 .bP
1940 \fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
1941 database
1942 .bP
1943 \fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
1944 .RE
1945 .TP 5
1946 .B \-\-with\-trace
1947 The
1948 .B trace
1949 function normally resides in the debug library,
1950 but it is sometimes useful to expose it in the shared or static library.
1951 Configuration scripts should check for the function's existence rather
1952 than assuming it is confined to the debug library.
1953 .SH FILES
1954 .TP
1955 .I /usr/share/tabset
1956 tab stop initialization database
1957 .TP
1958 .I /usr/share/terminfo
1959 compiled terminal capability database
1960 .SH NOTES
1961 X/Open Curses permits most functions it specifies to be made available
1962 as macros as well.
1963 .\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
1964 .\" See X/Open Curses Issue 7, pp. 311-318.
1965 \fI\%ncurses\fP does so
1966 .bP
1967 for functions that return values via their parameters,
1968 .bP
1969 to support obsolete features,
1970 .bP
1971 to reuse functions
1972 (for example,
1973 those that move the cursor before another operation),
1974 and
1975 .bP
1976 in a few special cases.
1977 .PP
1978 If the standard output file descriptor of an
1979 .I \%ncurses
1980 program is redirected to something that is not a terminal device,
1981 the library writes screen updates to the standard error file descriptor.
1982 This was an undocumented feature of SVr3
1983 .IR curses .
1984 .PP
1985 See subsection \*(``Header Files\*('' below regarding symbols exposed by
1986 inclusion of \fI\%curses.h\fP.
1987 .SH EXTENSIONS
1988 .I \%ncurses
1989 enables an application to capture mouse events on certain terminals,
1990 including \fI\%xterm\fP(1);
1991 see \fB\%curs_mouse\fP(3X).
1992 .PP
1993 .I \%ncurses
1994 provides a means of responding to window resizing events,
1995 as when running in a GUI terminal emulator application such as
1996 .IR \%xterm ;
1997 see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
1998 .PP
1999 .I \%ncurses
2000 allows an application to query the terminal for the presence of a wide
2001 variety of special keys;
2002 see \fB\%has_key\fP(3X).
2003 .PP
2004 .I \%ncurses
2005 extends the fixed set of function key capabilities specified by X/Open
2006 Curses by allowing the application programmer to define additional key
2007 events at runtime;
2008 see
2009 \fB\%define_key\fP(3X),
2010 \fB\%key_defined\fP(3X),
2011 \fB\%keybound\fP(3X),
2012 and
2013 \fB\%keyok\fP(3X).
2014 .PP
2015 .I \%ncurses
2016 can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
2017 SGR\ 39 and SGR\ 49 sequences,
2018 which allow an application to reset the terminal to its original
2019 foreground and background colors.
2020 From a user's perspective,
2021 the application is able to draw colored text on a background whose color
2022 is set independently,
2023 providing better control over color contrasts.
2024 See \fB\%default_colors\fP(3X).
2025 .PP
2026 An
2027 .I \%ncurses
2028 application can eschew knowledge of
2029 .I \%SCREEN
2030 and
2031 .I \%WINDOW
2032 structure internals,
2033 instead using accessor functions such as
2034 \fB\%is_cbreak\fP(3X) and
2035 \fB\%is_scrollok\fP(3X).
2036 .PP
2037 .I \%ncurses
2038 enables an application to direct its output to a printer attached to the
2039 terminal device;
2040 see \fB\%curs_print\fP(3X).
2041 .PP
2042 .I \%ncurses
2043 offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
2044 soft-label key lines,
2045 and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
2046 that can gather color information from them when many colors are
2047 supported.
2048 .PP
2049 .I \%ncurses
2050 permits modification of \fB\%unctrl\fP(3X)'s behavior;
2051 see \fB\%use_legacy_coding\fP(3X).
2052 .PP
2053 Rudimentary support for multi-threaded applications may be available;
2054 see \fBcurs_threads\fP(3X).
2055 .PP
2056 Functions that ease the management of multiple screens can be exposed;
2057 see \fBcurs_sp_funcs\fP(3X).
2058 .PP
2059 To aid applications to debug their memory usage,
2060 .I \%ncurses
2061 optionally offers functions to more aggressively free memory it
2062 dynamically allocates itself;
2063 see \fBcurs_memleaks\fP(3X).
2064 .PP
2065 The library facilitates auditing and troubleshooting of its behavior;
2066 see \fBcurs_trace\fP(3X).
2067 .PP
2068 Compiling
2069 .I \%ncurses
2070 with the option
2071 .B \%\-DUSE_GETCAP
2072 causes it to fall back to reading
2073 .I \%/etc/termcap
2074 if the terminal setup code cannot find a
2075 .I \%term\%info
2076 entry corresponding to
2077 .IR TERM .
2078 Use of this feature is not recommended,
2079 as it essentially includes an entire
2080 .I termcap
2081 compiler in the
2082 .I \%ncurses
2083 startup code,
2084 at a cost in memory usage and application launch latency.
2085 .PP
2086 .I \%PDCurses
2087 and NetBSD
2088 .I curses
2089 incorporate some
2090 .I \%ncurses
2091 extensions.
2092 Individual man pages indicate where this is the case.
2093 .SH PORTABILITY
2094 X/Open Curses defines two levels of conformance,
2095 \*(``base\*('' and \*(``enhanced\*(''.
2096 The latter includes several additional features,
2097 such as wide-character and color support.
2098 .I \%ncurses
2099 intends base-level conformance with X/Open Curses,
2100 and supports all features of its enhanced level
2101 except the
2102 .I \%untic
2103 utility.
2104 .PP
2105 Differences between X/Open Curses and
2106 .I \%ncurses
2107 are documented in the \*(``PORTABILITY\*('' sections of applicable man
2108 pages.
2109 .SS "Error Checking"
2110 In many cases, X/Open Curses is vague about error conditions,
2111 omitting some of the SVr4 documentation.
2112 .PP
2113 Unlike other implementations,
2114 .I \%ncurses
2115 checks pointer parameters,
2116 such as those to
2117 .I \%WINDOW
2118 structures,
2119 to ensure that they are not null.
2120 This is done primarily to guard against programmer error.
2121 The standard interface does not provide a way for the library
2122 to tell an application which of several possible errors occurred.
2123 An application that relies on
2124 .I \%ncurses
2125 to check its function parameters for validity limits its portability and
2126 robustness.
2127 .SS "Padding Differences"
2128 In historical
2129 .I curses
2130 implementations,
2131 delays embedded in the
2132 .I \%term\%info
2133 capabilities
2134 .B \%carriage_return
2135 .RB ( cr ),
2136 .B \%scroll_forward
2137 .RB ( ind ),
2138 .B \%cursor_left
2139 .RB ( cub1 ),
2140 .B \%form_feed
2141 .RB ( ff ),
2142 and
2143 .B \%tab
2144 .RB ( ht )
2145 activated corresponding delay bits in the Unix terminal driver.
2146 .I \%ncurses
2147 performs all padding by sending NUL bytes to the device.
2148 This method is slightly more expensive,
2149 but narrows the interface to the Unix kernel significantly and
2150 correspondingly increases the package's portability.
2151 .SS "Header Files"
2152 The header file
2153 .I \%curses.h
2154 itself includes the header files
2155 .I \%stdio.h
2156 and
2157 .IR \%unctrl.h .
2158 .PP
2159 X/Open Curses has more to say,
2160 .RS 4
2161 .PP
2162 The inclusion of
2163 .I \%curses.h
2164 may make visible all symbols from the headers
2165 .IR \%stdio.h ,
2166 .IR \%term.h ,
2167 .IR \%termios.h ,
2168 and
2169 .IR \%wchar.h .
2170 .RE
2171 .PP
2172 but does not finish the story.
2173 A more complete account follows.
2174 .bP
2175 The first
2176 .IR curses ","
2177 in 4BSD,
2178 provided a
2179 .I \%curses.h
2180 file.
2181 .IP
2182 BSD
2183 .I curses
2184 code included
2185 .I \%curses.h
2186 and
2187 .I \%unctrl.h
2188 from an internal header file
2189 .IR \%curses.ext ,
2190 where
2191 \*(``ext\*('' abbreviated \*(``externs\*(''.
2192 .IP
2193 The implementations of
2194 .I \%printw
2195 and
2196 .I \%scanw
2197 used undocumented internal functions of the standard I/O library
2198 .RI ( _doprnt
2199 and
2200 .IR _doscan ),
2201 but nothing in
2202 .I \%curses.h
2203 itself relied upon
2204 .IR \%stdio.h .
2205 .bP
2206 SVr2
2207 .I curses
2208 added
2209 .IR \%newterm ,
2210 which relies upon
2211 .I \%stdio.h
2212 because its function prototype employs the
2213 .I FILE
2214 type.
2215 .IP
2216 SVr4
2217 .I curses
2218 added
2219 .I \%putwin
2220 and
2221 .IR \%getwin ,
2222 which also use
2223 .IR \%stdio.h .
2224 .IP
2225 X/Open Curses specifies all three of these functions.
2226 .IP
2227 SVr4
2228 .I curses
2229 and X/Open Curses do not require the developer to include
2230 .I \%stdio.h
2231 before
2232 .IR \%curses.h .
2233 Both document use of
2234 .I curses
2235 as requiring only
2236 .IR \%curses.h .
2237 .IP
2238 As a result,
2239 standard
2240 .I \%curses.h
2241 always includes
2242 .IR \%stdio.h .
2243 .bP
2244 X/Open Curses and SVr4
2245 .I curses
2246 are inconsistent with respect to
2247 .IR \%unctrl.h .
2248 .IP
2249 As noted in \fBcurs_util\fP(3X),
2250 .I \%ncurses
2251 includes
2252 .I \%unctrl.h
2253 from
2254 .I \%curses.h
2255 (as SVr4 does).
2256 .bP
2257 X/Open Curses's comments about
2258 .I \%term.h
2259 and
2260 .I \%termios.h
2261 may refer to HP-UX and AIX.
2262 .IP
2263 HP-UX
2264 .I curses
2265 includes
2266 .I \%term.h
2267 from
2268 .I \%curses.h
2269 to declare
2270 .I \%setupterm
2271 in
2272 .IR \%curses.h ,
2273 but
2274 .I \%ncurses
2275 and Solaris
2276 .I curses
2277 do not.
2278 .IP
2279 AIX
2280 .I curses
2281 includes
2282 .I \%term.h
2283 and
2284 .IR \%termios.h .
2285 Again,
2286 .I \%ncurses
2287 and Solaris
2288 .I curses
2289 do not.
2290 .bP
2291 X/Open Curses says that
2292 .I \%curses.h
2293 .B may
2294 include
2295 .IR \%term.h ,
2296 but does not require it to do so.
2297 .IP
2298 Some programs use functions declared in both
2299 .I \%curses.h
2300 and
2301 .IR \%term.h ,
2302 and must include both header files in the same module.
2303 Very old versions of AIX
2304 .I curses
2305 required inclusion of
2306 .I \%curses.h
2307 before
2308 .IR \%term.h .
2309 .IP
2310 The header files supplied by
2311 .I \%ncurses
2312 include the standard library headers required for its declarations,
2313 so
2314 .IR \%ncurses 's
2315 own header files can be included in any order.
2316 For portability even to old AIX systems,
2317 include
2318 .I \%curses.h
2319 before
2320 .IR \%term.h .
2321 .bP
2322 X/Open Curses says \*(``may make visible\*('' because including a header
2323 file does not necessarily make visible all of the symbols in it
2324 (consider
2325 .B \%#ifdef
2326 and similar).
2327 .IP
2328 For instance,
2329 .IR \%ncurses 's
2330 .I \%curses.h
2331 .B may \" bold to contrast with preceding italic
2332 include
2333 .I \%wchar.h
2334 if the proper symbol is defined,
2335 and if
2336 .I \%ncurses
2337 is configured for wide-character support.
2338 If
2339 .I \%wchar.h
2340 is included,
2341 its symbols
2342 .B may \" bold for consistency in this paragraph
2343 be made visible depending on the value of the
2344 .B _XOPEN_SOURCE
2345 feature test macro.
2346 .bP
2347 X/Open Curses mandates an application's inclusion of one standard C
2348 library header in a special case:
2349 .I \%stdarg.h
2350 before
2351 .I \%curses.h
2352 to prototype the functions
2353 .I \%vw_printw
2354 and
2355 .I \%vw_scanw
2356 (as well as the obsolete
2357 .I \%vwprintw
2358 and
2359 .IR \%vwscanw ).
2360 Each of these takes a variadic argument list,
2361 a
2362 .I \%va_list
2363 parameter,
2364 like that of \fI\%printf\fP(3).
2365 .IP
2366 SVr3
2367 .I curses
2368 introduced
2369 the two obsolete functions,
2370 and X/Open Curses the others.
2371 In between,
2372 SVr4
2373 .I curses
2374 provided for the possibility that an application might include either
2375 .I \%varargs.h
2376 or
2377 .IR \%stdarg.h .
2378 These represented contrasting approaches to handling variadic
2379 argument lists.
2380 The older interface,
2381 .IR \%varargs.h ,
2382 used a pointer to
2383 .I char \" V7, 32V, System III, 3BSD
2384 for variadic functions'
2385 .I \%va_list
2386 parameter.
2387 Later,
2388 the list acquired its own standard data type,
2389 .IR \%va_list ,
2390 defined in
2391 .IR \%stdarg.h ,
2392 empowering the compiler to check the types of a function call's actual
2393 parameters against the formal ones declared in its prototype.
2394 .IP
2395 No conforming implementations of X/Open Curses require an application
2396 to include
2397 .I \%stdarg.h
2398 before
2399 .I \%curses.h
2400 because they either have allowed for a special type,
2401 or,
2402 like
2403 .IR \%ncurses ,
2404 they include
2405 .I \%stdarg.h
2406 themselves to provide a portable interface.
2407 .SH AUTHORS
2408 Zeyd M. Ben-Halim,
2409 Eric S. Raymond,
2410 Thomas E. Dickey.
2411 Based on
2412 .I \%pcurses
2413 by Pavel Curtis.
2414 .SH SEE ALSO
2415 \fB\%curs_variables\fP(3X),
2416 \fB\%terminfo\fP(5),
2417 \fB\%user_caps\fP(5)