Debian Codegraph @

upstream/debian-trixie/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.92 2025/02/02 00:01:55 tom Exp $
31 .TH initscr 3NCURSES 2025-02-01 "ncurses 6.5" "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
133 .I NULL
134 to use the
135 .I TERM
136 environment variable;
137 .bP
138 an output stream
139 .I outf
140 connected to the terminal;
141 and
142 .bP
143 an input stream
144 .I inf
145 connected to the terminal.
146 It returns a variable of structure type
147 .I SCREEN
148 .BR * ","
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 cannot support a screen-oriented program,
169 would also use
170 .BR \%newterm "."
171 If at most one terminal connection is needed,
172 the programmer could perform such a capability test,
173 decide which mode in which to operate,
174 then call
175 .B \%delscreen
176 on the pointer returned by
177 .BR \%newterm ","
178 and proceed with either
179 .B \%initscr
180 or a
181 .RI non- curses
182 interface.
183 .SS endwin
184 The program must also call
185 .B \%endwin
186 for each terminal being used before exiting from
187 .IR curses "."
188 If
189 .B \%newterm
190 is called more than once for the same terminal,
191 the first terminal referred to must be the last one for which
192 .B \%endwin
193 is called.
194 .PP
195 A program should always call
196 .B \%endwin
197 before exiting the application
198 or temporarily suspending
199 .IR curses "'s"
200 management of the terminal.
201 .BR \%endwin ":"
202 .bP
203 resets colors to correspond with the default color pair 0,
204 .bP
205 moves the cursor to the lower left-hand corner of the screen,
206 .bP
207 clears the remainder of the line so that it uses the default colors,
208 .bP
209 sets the cursor to normal visibility
210 (see \fB\%curs_set\fP(3NCURSES)),
211 .bP
212 if applicable,
213 stops cursor-addressing mode using the
214 .B \%exit_ca_mode
215 .RB \%( rmcup )
216 terminal capability,
217 and
218 .bP
219 restores terminal modes (see \fB\%reset_shell_mode\fP(3NCURSES)).
220 .PP
221 Calling \fB\%refresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES) after a
222 temporary suspension causes
223 .I curses
224 to resume managing the terminal.
225 .SS isendwin
226 .B \%isendwin
227 returns
228 .B TRUE
229 if
230 .B \%endwin
231 has been called without any subsequent calls to \fB\%wrefresh\fP(3NCURSES),
232 and
233 .B FALSE
234 otherwise.
235 .SS set_term
236 .B \%set_term
237 re-orients the
238 .I curses
239 library's operations to another terminal
240 when the application has arranged to manage more than one with
241 .BR \%newterm "."
242 .B \%set_term
243 expects a
244 .I SCREEN
245 pointer previously returned by
246 .B \%newterm
247 as an argument,
248 and returns the previous one.
249 .B \%set_term
250 is the only
251 .I curses
252 API function that manipulates
253 .I SCREEN
254 pointers;
255 all others affect only the current terminal.
256 .SS delscreen
257 .B \%delscreen
258 frees the storage backing the supplied
259 .I SCREEN
260 pointer argument.
261 .B \%endwin
262 does not,
263 so that an application can resume managing a terminal with
264 .I curses
265 after a
266 (possibly conditional or temporary)
267 suspension;
268 see \fB\%kernel\fP(3NCURSES).
269 Call
270 .B \%delscreen
271 after
272 .B \%endwin
273 when a particular
274 .I SCREEN
275 structure
276 is no longer needed.
277 .SH RETURN VALUE
278 .B \%endwin
279 returns
280 .B OK
281 on success and
282 .B ERR
283 on failure.
284 .PP
285 In
286 .IR \%ncurses ","
287 .bP
288 .B \%endwin
289 returns
290 .B ERR
291 if
292 .RS
293 .bP
294 the terminal was not initialized,
295 .bP
296 .B \%endwin
297 is called more than once without updating the screen,
298 or
299 .bP
300 \fB\%reset_shell_mode\fP(3NCURSES) returns
301 .BR ERR "."
302 .RE
303 .bP
304 .B \%newterm
305 returns
306 .B ERR
307 if it cannot allocate storage for the
308 .I SCREEN
309 data structure
310 or the top-level windows thereof:
311 .BR \%curscr ","
312 .BR \%newscr ","
313 and
314 .BR \%stdscr "."
315 .PP
316 Functions that return pointers return
317 .I NULL
318 on error.
319 In
320 .IR \%ncurses ","
321 .B \%set_term
322 does not fail,
323 and
324 .B \%initscr
325 exits the application if it does not operate successfully.
326 .SH NOTES
327 .I \%ncurses
328 establishes signal handlers when a function that initializes a
329 .IR SCREEN ","
330 either
331 .B \%initscr
332 or
333 .BR \%newterm ","
334 is first called.
335 Applications that wish to handle the following signals themselves
336 should set up their corresponding handlers
337 .I after
338 initializing the screen.
339 .TP
340 .I SIGINT
341 .IR \%ncurses 's
342 handler
343 .I attempts
344 to clean up the screen on exit.
345 Although it
346 .I usually
347 works as expected,
348 there are limitations.
349 .RS
350 .bP
351 Walking the
352 .I SCREEN
353 list is unsafe, since all list management
354 is done without any signal blocking.
355 .bP
356 When an application has been built with the
357 .I \%_REENTRANT
358 macro defined
359 (and corresponding system support),
360 .B \%set_term
361 uses functions that could deadlock or misbehave in other ways.
362 .bP
363 .B \%endwin
364 calls other functions,
365 many of which use \fI\%stdio\fP(3) or other library functions that are
366 clearly unsafe.
367 .RE
368 .TP
369 .I SIGTERM
370 .I \%ncurses
371 uses the same handler as for
372 .IR \%SIGINT ","
373 with the same limitations.
374 It is not mentioned in X/Open Curses,
375 but is more suitable for this purpose than
376 .I \%SIGQUIT
377 (which is used in debugging).
378 .TP
379 .I SIGTSTP
380 .IR \%ncurses 's
381 handler manages the terminal-generated stop signal,
382 used in job control.
383 When resuming the process,
384 .I \%ncurses
385 discards pending input with \fB\%flushinp\fP(3NCURSES)
386 and repaints the screen,
387 assuming that it has been completely altered.
388 It also updates the saved terminal modes with
389 \fB\%def_shell_mode\fP(3NCURSES).
390 .TP
391 .I SIGWINCH
392 .I \%ncurses
393 handles changes to the terminal's window size,
394 a phenomenon ignored in standardization efforts.
395 It sets a (signal-safe) variable
396 that is later tested by \fB\%wgetch\fP(3NCURSES) and \fB\%wget_wch\fP(3NCURSES).
397 .RS
398 .bP
399 .B \%wgetch
400 returns the key code
401 .BR \%KEY_RESIZE "."
402 .bP
403 .B \%wget_wch
404 returns
405 .B \%KEY_CODE_YES
406 and sets its
407 .I wch
408 parameter to
409 .BR \%KEY_RESIZE "."
410 .RE
411 .IP
412 At the same time,
413 .I \%ncurses
414 calls \fB\%resizeterm\fP(3NCURSES)
415 to adjust the standard screen
416 .BR \%stdscr ","
417 and update global variables such as
418 .B LINES
419 and
420 .BR COLS "."
421 .SH PORTABILITY
422 X/Open Curses Issue\ 4 describes these functions.
423 It specifies no error conditions for them.
424 .SS Differences
425 X/Open Curses specifies that portable applications must not
426 call
427 .I \%initscr
428 more than once.
429 .bP
430 The portable way to use
431 .I \%initscr
432 is once only,
433 using
434 .I \%refresh
435 to restore the screen after
436 .IR \%endwin "."
437 .bP
438 .I \%ncurses
439 permits use of
440 .I \%initscr
441 after
442 .IR \%endwin "."
443 .PP
444 .I \%initscr
445 in BSD,
446 from its inception (1980) through the Net/2 release (1991) returned
447 .I ERR
448 cast to a
449 .I \%WINDOW
450 pointer when detecting an error.
451 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/initscr.c
452 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/lib/libcurses/initscr.c
453 4.4BSD (1995)
454 instead returned a null pointer.
455 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/lib/libcurses/initscr.c
456 Neither exited the application.
457 It is safe but redundant to check the return value of
458 .I \%initscr
459 in X/Open Curses.
460 .PP
461 Calling
462 .I \%endwin
463 does not dispose of the memory allocated by
464 .I \%initscr
465 or
466 .IR \%newterm "."
467 Deleting a
468 .I SCREEN
469 provides a way to do this.
470 .bP
471 X/Open Curses does not say what happens to
472 .IR \%WINDOW s
473 when
474 .I \%delscreen
475 \*(``frees storage associated with the
476 .IR SCREEN "\*(''"
477 nor does the SVr4 documentation help,
478 adding that it should be called after
479 .I \%endwin
480 if a
481 .I SCREEN
482 is no longer needed.
483 .bP
484 However,
485 .IR \%WINDOW s
486 are implicitly associated with a
487 .IR SCREEN ","
488 so it is reasonable to expect
489 .I \%delscreen
490 to dispose of them.
491 .bP
492 SVr4 deletes the standard
493 .I \%WINDOW
494 structures
495 .I \%stdscr
496 and
497 .I \%curscr
498 as well as a work area
499 .IR \%newscr "."
500 It ignores other windows.
501 .bP
502 Since version 4.0 (1996),
503 .I \%ncurses
504 has maintained a list of all windows for each screen,
505 using that information to delete those windows when
506 .I \%delscreen
507 is
508 called.
509 .bP
510 NetBSD copied this feature of
511 .I \%ncurses
512 in 2001.
513 .I \%PDCurses
514 follows the SVr4 model,
515 deleting only the standard
516 .I \%WINDOW
517 structures.
518 .SS "High-level versus Low-level"
519 Different implementations may disagree regarding the level of some functions.
520 For example,
521 .I SCREEN
522 (returned by
523 .IR \%newterm ")"
524 and
525 .I \%TERMINAL
526 (returned by \fB\%setupterm\fP(3NCURSES)) hold file
527 descriptors for the output stream.
528 If an application switches screens using
529 .IR \%set_term ","
530 or switches terminals using \fB\%set_curterm\fP(3NCURSES),
531 applications which use the output file descriptor can have different
532 behavior depending on which structure holds the corresponding descriptor.
533 .bP
534 NetBSD's
535 .I \%baudrate
536 function uses the descriptor in
537 .IR \%TERMINAL "."
538 .I \%ncurses
539 and SVr4 use the descriptor in
540 .IR SCREEN "."
541 .bP
542 NetBSD and
543 .I \%ncurses
544 use the descriptor
545 in
546 .I \%TERMINAL
547 for terminal I/O modes,
548 e.g.,
549 \fB\%def_shell_mode\fP(3NCURSES),
550 \fB\%def_prog_mode\fP(3NCURSES).
551 SVr4 uses the descriptor in
552 .IR SCREEN "."
553 .SS "Unset \fITERM\fP Variable"
554 If the
555 .I TERM
556 variable is missing or empty,
557 .I \%initscr
558 uses the value \*(``unknown\*('',
559 which normally corresponds to a terminal entry with the
560 .B \%generic
561 .RB ( gn )
562 capability.
563 Generic entries are detected by \fB\%setupterm\fP(3NCURSES)
564 and cannot be used for full-screen operation.
565 Other implementations may handle
566 a missing/empty
567 .I TERM
568 variable differently.
569 .SS "Signal Handlers"
570 Quoting X/Open Curses Issue\ 7,
571 section 3.1.1:
572 .RS 5
573 .PP
574 Curses implementations may provide for special handling of the
575 \%SIGINT,
576 \%SIGQUIT,
577 and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
578 .IR \%initscr ()
579 is called.\|.\|.
580 .PP
581 Any special handling for these signals may remain in effect for the
582 life of the process or until the process changes the disposition of
583 the signal.
584 .PP
585 None of the Curses functions are required to be safe
586 with respect to signals.\|.\|.
587 .RE
588 .PP
589 Section \*(``NOTES\*('' above discusses
590 .IR \%ncurses 's
591 signal handlers.
592 .SH SEE ALSO
593 \fB\%ncurses\fP(3NCURSES),
594 \fB\%kernel\fP(3NCURSES),
595 \fB\%refresh\fP(3NCURSES),
596 \fB\%slk\fP(3NCURSES),
597 \fB\%terminfo\fP(3NCURSES),
598 \fB\%util\fP(3NCURSES),
599 \fB\%curses_variables\fP(3NCURSES)