Debian Codegraph @

upstream/mageia-cauldron/man3/curs_initscr.3x

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