Debian Codegraph @

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

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2016,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_initscr.3x,v 1.112 2025/08/23 22:41:44 tom Exp $
31 .TH initscr 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 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%initscr\fP,
49 \fB\%newterm\fP,
50 \fB\%endwin\fP,
51 \fB\%isendwin\fP,
52 \fB\%set_term\fP,
53 \fB\%delscreen\fP \-
54 initialize, manipulate, or tear down \fIcurses\fR terminal interface
55 .SH SYNOPSIS
56 .nf
57 \fB#include <curses.h>
58 .PP
59 \fBWINDOW * initscr(void);
60 \fBint endwin(void);
61 .PP
62 \fBbool isendwin(void);
63 .PP
64 \fBSCREEN * newterm(const char * \fItype\fP, FILE * \fIoutf\fP, FILE * \fIinf\fP);
65 \fBSCREEN * set_term(SCREEN * \fInew\fP);
66 \fBvoid delscreen(SCREEN * \fIsp\fP);
67 .fi
68 .SH DESCRIPTION
69 .SS initscr
70 .B \%initscr
71 determines the terminal type and initializes the library's
72 .IR SCREEN ","
73 .IR WINDOW ","
74 and other data structures.
75 It is normally the first
76 .I curses
77 function call a program performs.
78 However,
79 an application with unusual needs might employ a few other
80 .I curses
81 functions beforehand:
82 .bP
83 \fB\%slk_init\fP(3NCURSES) to set up soft-label keys;
84 .bP
85 \fB\%filter\fP(3NCURSES) if the program is designed to operate in a process
86 pipeline;
87 .bP
88 \fB\%ripoffline\fP(3NCURSES) to reserve up to five lines at the top and/or
89 bottom of the screen from management by
90 .BR \%stdscr ","
91 the standard
92 .I curses
93 window;
94 and
95 .bP
96 \fB\%use_env\fP(3NCURSES) and/or \fB\%use_tioctl\fP(3NCURSES) to configure use of
97 the process environment and operating system's terminal driver,
98 respectively,
99 when determining the dimensions of the terminal display.
100 .PP
101 Further,
102 a
103 .I curses
104 program might call
105 .B \%newterm
106 prior to or instead of
107 .B \%initscr
108 in two specialized cases described in its subsection below.
109 .PP
110 .B \%initscr
111 causes the first \fB\%refresh\fP(3NCURSES) call to clear the screen.
112 If errors occur,
113 .B \%initscr
114 writes an appropriate diagnostic message to the standard error stream
115 and exits;
116 otherwise,
117 it returns a pointer to
118 .BR stdscr "."
119 .SS newterm
120 An application that manages multiple terminals should call
121 .B \%newterm
122 once for each such device
123 .I instead
124 of
125 .BR \%initscr "."
126 .BR \%newterm 's
127 arguments are
128 .bP
129 the
130 .I type
131 of the associated terminal,
132 or a null pointer to use the
133 .I TERM
134 environment variable;
135 .bP
136 an output stream
137 .I outf
138 connected to the terminal;
139 and
140 .bP
141 an input stream
142 .I inf
143 connected to the terminal.
144 .PP
145 .B \%newterm
146 returns a variable of
147 .RI pointer-to- SCREEN
148 type,
149 which should be saved for later use with
150 .B \%set_term
151 and
152 .BR \%delscreen "."
153 .PP
154 .B \%newterm
155 passes the file descriptor of the output stream to the
156 .I \%term\%info
157 function \fB\%setupterm\fP(3NCURSES),
158 which returns a pointer to a
159 .I \%TERMINAL
160 structure that
161 .B \%newterm
162 stores in the
163 .I SCREEN
164 it returns to the application.
165 .PP
166 An application that needs to inspect a terminal type's capabilities,
167 so that it can continue to run in a line-oriented mode
168 if the terminal type does not support capabilities the application
169 demands,
170 would also use
171 .BR \%newterm "."
172 If at most one terminal connection is needed,
173 the programmer could perform such a capability test,
174 decide the mode in which to operate,
175 then call
176 .B \%delscreen
177 on the pointer returned by
178 .BR \%newterm ","
179 and proceed with either
180 .B \%initscr
181 or a
182 .RI non- curses
183 interface.
184 .SS endwin
185 The program must also call
186 .B \%endwin
187 for each terminal being used before exiting from
188 .IR curses "."
189 If
190 .B \%newterm
191 is called more than once for the same terminal,
192 the first terminal referred to must be the last one for which
193 .B \%endwin
194 is called.
195 .PP
196 A program should always call
197 .B \%endwin
198 before exiting the application
199 or temporarily suspending
200 .IR curses "'s"
201 management of the terminal.
202 .BR \%endwin ":"
203 .bP
204 (if \fB\%start_color\fP(3NCURSES) has been called)
205 resets the terminal's foreground and background colors
206 to correspond with those of color pair 0
207 (the default pair),
208 .bP
209 moves the cursor to the lower left-hand corner of the screen,
210 .bP
211 (if \fB\%start_color\fP(3NCURSES) has been called)
212 restores the default color pair,
213 .bP
214 clears the line,
215 .bP
216 sets the cursor to normal visibility
217 (see \fB\%curs_set\fP(3NCURSES)),
218 .bP
219 if applicable,
220 stops cursor-addressing mode using the
221 .B \%exit_ca_mode
222 .RB \%( rmcup )
223 terminal capability,
224 and
225 .bP
226 restores terminal modes (see \fB\%reset_shell_mode\fP(3NCURSES)).
227 .PP
228 Calling \fB\%refresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES) after a
229 temporary suspension causes
230 .I curses
231 to resume managing the terminal.
232 .SS isendwin
233 .B \%isendwin
234 returns
235 .B TRUE
236 if \fB\%wrefresh\fP(3NCURSES)
237 has not been called since the most recent
238 .B \%endwin
239 call,
240 and
241 .B FALSE
242 otherwise.
243 .SS set_term
244 .B \%set_term
245 re-orients the
246 .I curses
247 library's operations to another terminal
248 when the application has arranged to manage more than one with
249 .BR \%newterm "."
250 .B \%set_term
251 expects a
252 .I SCREEN
253 pointer previously returned by
254 .B \%newterm
255 as an argument,
256 and returns the previous one.
257 .B \%set_term
258 is the only standard
259 .I curses
260 API function that manipulates
261 .I SCREEN
262 pointers;
263 all others affect only the current terminal
264 (but see \fBsp_funcs\fP(3NCURSES)).
265 .SS delscreen
266 .B \%delscreen
267 frees the storage backing the supplied
268 .I SCREEN
269 pointer argument.
270 .B \%endwin
271 does not,
272 so that an application can resume managing a terminal with
273 .I curses
274 after a
275 (possibly conditional or temporary)
276 suspension;
277 see \fB\%kernel\fP(3NCURSES).
278 Use
279 .B \%delscreen
280 after
281 .B \%endwin
282 when the application has no more need of a terminal device
283 but will not soon exit.
284 .SH RETURN VALUE
285 .B \%delscreen
286 returns no value.
287 .B \%endwin
288 returns
289 .B OK
290 on success and
291 .B ERR
292 on failure.
293 .B \%isendwin
294 returns
295 .B TRUE
296 or
297 .B FALSE
298 as described above.
299 .PP
300 In
301 .IR \%ncurses ","
302 .bP
303 .B \%endwin
304 returns
305 .B ERR
306 if
307 .RS
308 .bP
309 the terminal was not initialized,
310 .bP
311 it is called more than once without updating the screen,
312 or
313 .bP
314 its call of \fB\%reset_shell_mode\fP(3NCURSES) returns
315 .BR ERR ";"
316 and
317 .RE
318 .bP
319 .B \%newterm
320 returns
321 .B ERR
322 if it cannot allocate storage for the
323 .I SCREEN
324 structure
325 or the
326 .I WINDOW
327 structures automatically associated with it:
328 .BR \%curscr ","
329 .BR \%newscr ","
330 and
331 .BR \%stdscr "."
332 .PP
333 Functions that return pointers return null pointers on error.
334 In
335 .IR \%ncurses ","
336 .B \%set_term
337 does not fail,
338 and
339 .B \%initscr
340 exits the application if it does not operate successfully.
341 .SH NOTES
342 .I \%ncurses
343 establishes signal handlers when a function that initializes a
344 .IR SCREEN ","
345 either
346 .B \%initscr
347 or
348 .BR \%newterm ","
349 is first called.
350 Applications that wish to handle the following signals themselves
351 should set up their corresponding handlers
352 .I after
353 initializing the screen.
354 .TP
355 .I SIGINT
356 .IR \%ncurses 's
357 handler
358 .I attempts
359 to clean up the screen on exit.
360 Although it
361 .I usually
362 works as expected,
363 there are limitations.
364 .RS
365 .bP
366 Walking the
367 .I SCREEN
368 list is unsafe, since all list management
369 is done without any signal blocking.
370 .bP
371 When an application has been built with the
372 .I \%_REENTRANT
373 macro defined
374 (and corresponding system support),
375 .B \%set_term
376 uses functions that could deadlock or misbehave in other ways.
377 .bP
378 .B \%endwin
379 calls other functions,
380 many of which use \fI\%stdio\fP(3) or other library functions that are
381 clearly unsafe.
382 .RE
383 .TP
384 .I SIGTERM
385 .I \%ncurses
386 uses the same handler as for
387 .IR \%SIGINT ","
388 with the same limitations.
389 It is not mentioned in X/Open Curses,
390 but is more suitable for this purpose than
391 .I \%SIGQUIT
392 (which is used in debugging).
393 .TP
394 .I SIGTSTP
395 .IR \%ncurses 's
396 handler manages the terminal-generated stop signal,
397 used in job control.
398 When resuming the process,
399 .I \%ncurses
400 discards pending input with \fB\%flushinp\fP(3NCURSES)
401 and repaints the screen,
402 assuming that it has been completely altered.
403 It also updates the saved terminal modes with
404 \fB\%def_shell_mode\fP(3NCURSES).
405 .TP
406 .I SIGWINCH
407 .I \%ncurses
408 handles changes to the terminal's window size,
409 a phenomenon ignored in standardization efforts.
410 It sets a (signal-safe) variable
411 that is later tested by \fB\%wgetch\fP(3NCURSES) and \fB\%wget_wch\fP(3NCURSES).
412 .RS
413 .bP
414 .B \%wgetch
415 returns the key code
416 .BR \%KEY_RESIZE "."
417 .bP
418 .B \%wget_wch
419 returns
420 .B \%KEY_CODE_YES
421 and sets its
422 .I wch
423 parameter to
424 .BR \%KEY_RESIZE "."
425 .RE
426 .IP
427 At the same time,
428 .I \%ncurses
429 calls \fB\%resizeterm\fP(3NCURSES)
430 to adjust the standard screen
431 .B \%stdscr
432 and update global variables such as
433 .B LINES
434 and
435 .BR COLS "."
436 .SH PORTABILITY
437 X/Open Curses Issue\ 4 describes these functions.
438 It specifies no error conditions for them.
439 .SS Differences
440 X/Open Curses specifies that portable applications must not
441 call
442 .I \%initscr
443 more than once.
444 .bP
445 The portable way to use
446 .I \%initscr
447 is once only,
448 using
449 .I \%refresh
450 to restore the screen after
451 .IR \%endwin "."
452 .bP
453 .I \%ncurses
454 permits use of
455 .I \%initscr
456 after
457 .IR \%endwin "."
458 .PP
459 .I \%initscr
460 in BSD,
461 from its inception (1980) through the Net/2 release (1991) returned
462 .I ERR
463 cast to a
464 .I \%WINDOW
465 pointer when detecting an error.
466 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/initscr.c
467 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/lib/libcurses/initscr.c
468 4.4BSD (1995)
469 instead returned a null pointer.
470 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/lib/libcurses/initscr.c
471 Neither exited the application.
472 It is safe but redundant to check the return value of
473 .I \%initscr
474 in X/Open Curses.
475 .PP
476 Calling
477 .I \%endwin
478 does not dispose of the memory allocated by
479 .I \%initscr
480 or
481 .IR \%newterm "."
482 Deleting a
483 .I SCREEN
484 provides a way to do this.
485 .bP
486 X/Open Curses does not say what happens to
487 .IR \%WINDOW s
488 when
489 .I \%delscreen
490 \*(``frees storage associated with the
491 .IR SCREEN "\*(''"
492 nor does the SVr4 documentation help,
493 adding that it should be called after
494 .I \%endwin
495 if a
496 .I SCREEN
497 is no longer needed.
498 .bP
499 However,
500 every
501 .I \%WINDOW
502 is implicitly associated with a
503 .IR SCREEN ","
504 so it is reasonable to expect
505 .I \%delscreen
506 to dispose of them.
507 .bP
508 SVr4 deletes the standard
509 .I \%WINDOW
510 structures
511 .I \%stdscr
512 and
513 .I \%curscr
514 as well as a work area
515 .IR \%newscr "."
516 It ignores other windows.
517 .bP
518 Since version 4.0 (1996),
519 .I \%ncurses
520 has maintained a list of all windows for each screen,
521 using that information to delete those windows when
522 .I \%delscreen
523 is
524 called.
525 .bP
526 NetBSD copied this feature of
527 .I \%ncurses
528 in 2001.
529 .I \%PDCurses
530 follows the SVr4 model,
531 deleting only the standard
532 .I \%WINDOW
533 structures and
534 .IR \%newscr "."
535 .SS "High-level versus Low-level Functions"
536 Implementations disagree
537 regarding the level of abstraction applicable to a function or property.
538 For example,
539 .I SCREEN
540 (returned by
541 .IR \%newterm ")"
542 and
543 .I \%TERMINAL
544 (returned by \fB\%setupterm\fP(3NCURSES)) hold file
545 descriptors for the output stream.
546 If an application switches screens using
547 .IR \%set_term ","
548 or switches terminals using \fB\%set_curterm\fP(3NCURSES),
549 applications
550 using the output file descriptor can behave differently
551 depending on the structure holding the corresponding descriptor.
552 .bP
553 NetBSD's
554 .I \%baudrate
555 function uses the descriptor in
556 .IR \%TERMINAL "."
557 .I \%ncurses
558 and SVr4 use the descriptor in
559 .IR SCREEN "."
560 .bP
561 NetBSD and
562 .I \%ncurses
563 use the descriptor
564 in
565 .I \%TERMINAL
566 for terminal I/O modes,
567 e.g.,
568 \fB\%def_shell_mode\fP(3NCURSES),
569 \fB\%def_prog_mode\fP(3NCURSES).
570 SVr4 uses the descriptor in
571 .IR SCREEN "."
572 .SS "Unset \fITERM\fP Environment Variable"
573 If the
574 .I TERM
575 variable is not set in the environment or has an empty value,
576 .I \%initscr
577 uses the value \*(``unknown\*('',
578 which normally corresponds to a terminal entry with the
579 .B \%generic
580 .RB ( gn )
581 capability.
582 Generic entries are detected by \fB\%setupterm\fP(3NCURSES)
583 and cannot be used for full-screen operation.
584 Other implementations may handle
585 a missing or empty
586 .I TERM
587 variable differently.
588 .SS "Signal Handlers"
589 Quoting X/Open Curses Issue\ 7,
590 section 3.1.1:
591 .RS 5
592 .PP
593 Curses implementations may provide for special handling of the
594 \%SIGINT,
595 \%SIGQUIT,
596 and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
597 .IR \%initscr ()
598 is called.\|.\|.
599 .PP
600 Any special handling for these signals may remain in effect for the
601 life of the process or until the process changes the disposition of
602 the signal.
603 .PP
604 None of the Curses functions are required to be safe
605 with respect to signals.\|.\|.
606 .RE
607 .PP
608 Section \*(``NOTES\*('' above discusses
609 .IR \%ncurses 's
610 signal handlers.
611 .SH HISTORY
612 4BSD (1980)
613 introduced
614 .I \%initscr
615 and
616 .IR \%endwin "."
617 .PP
618 SVr2 (1984)
619 added
620 .I \%newterm
621 and
622 .IR \%set_term "."
623 .PP
624 SVr3.1 (1987)
625 supplied
626 .I \%delscreen
627 and
628 .IR \%isendwin "."
629 .SH SEE ALSO
630 \fB\%ncurses\fP(3NCURSES),
631 \fB\%kernel\fP(3NCURSES),
632 \fB\%refresh\fP(3NCURSES),
633 \fB\%slk\fP(3NCURSES),
634 \fB\%terminfo\fP(3NCURSES),
635 \fB\%util\fP(3NCURSES),
636 \fB\%curses_variables\fP(3NCURSES)