path: root/man/curs_initscr.3x

.\"***************************************************************************
.\" Copyright 2018-2024,2025 Thomas E. Dickey                                *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_initscr.3x,v 1.112 2025/08/23 22:41:44 tom Exp $
.TH curs_initscr 3X 2025-08-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\}
.el \{\
.ie t .ds `` ``
.el   .ds `` ""
.ie t .ds '' ''
.el   .ds '' ""
.\}
.
.de bP
.ie n  .IP \(bu 4
.el    .IP \(bu 2
..
.SH NAME
\fB\%initscr\fP,
\fB\%newterm\fP,
\fB\%endwin\fP,
\fB\%isendwin\fP,
\fB\%set_term\fP,
\fB\%delscreen\fP \-
initialize, manipulate, or tear down \fIcurses\fR terminal interface
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBWINDOW * initscr(void);
\fBint endwin(void);
.PP
\fBbool isendwin(void);
.PP
\fBSCREEN * newterm(const char * \fItype\fP, FILE * \fIoutf\fP, FILE * \fIinf\fP);
\fBSCREEN * set_term(SCREEN * \fInew\fP);
\fBvoid delscreen(SCREEN * \fIsp\fP);
.fi
.SH DESCRIPTION
.SS initscr
.B \%initscr
determines the terminal type and initializes the library's
.IR SCREEN ","
.IR WINDOW ","
and other data structures.
It is normally the first
.I curses
function call a program performs.
However,
an application with unusual needs might employ a few other
.I curses
functions beforehand:
.bP
\fB\%slk_init\fP(3X) to set up soft-label keys;
.bP
\fB\%filter\fP(3X) if the program is designed to operate in a process
pipeline;
.bP
\fB\%ripoffline\fP(3X) to reserve up to five lines at the top and/or
bottom of the screen from management by
.BR \%stdscr ","
the standard
.I curses
window;
and
.bP
\fB\%use_env\fP(3X) and/or \fB\%use_tioctl\fP(3X) to configure use of
the process environment and operating system's terminal driver,
respectively,
when determining the dimensions of the terminal display.
.PP
Further,
a
.I curses
program might call
.B \%newterm
prior to or instead of
.B \%initscr
in two specialized cases described in its subsection below.
.PP
.B \%initscr
causes the first \fB\%refresh\fP(3X) call to clear the screen.
If errors occur,
.B \%initscr
writes an appropriate diagnostic message to the standard error stream
and exits;
otherwise,
it returns a pointer to
.BR stdscr "."
.SS newterm
An application that manages multiple terminals should call
.B \%newterm
once for each such device
.I instead
of
.BR \%initscr "."
.BR \%newterm 's
arguments are
.bP
the
.I type
of the associated terminal,
or a null pointer to use the
.I TERM
environment variable;
.bP
an output stream
.I outf
connected to the terminal;
and
.bP
an input stream
.I inf
connected to the terminal.
.PP
.B \%newterm
returns a variable of
.RI pointer-to- SCREEN
type,
which should be saved for later use with
.B \%set_term
and
.BR \%delscreen "."
.PP
.B \%newterm
passes the file descriptor of the output stream to the
.I \%term\%info
function \fB\%setupterm\fP(3X),
which returns a pointer to a
.I \%TERMINAL
structure that
.B \%newterm
stores in the
.I SCREEN
it returns to the application.
.PP
An application that needs to inspect a terminal type's capabilities,
so that it can continue to run in a line-oriented mode
if the terminal type does not support capabilities the application
demands,
would also use
.BR \%newterm "."
If at most one terminal connection is needed,
the programmer could perform such a capability test,
decide the mode in which to operate,
then call
.B \%delscreen
on the pointer returned by
.BR \%newterm ","
and proceed with either
.B \%initscr
or a
.RI non- curses
interface.
.SS endwin
The program must also call
.B \%endwin
for each terminal being used before exiting from
.IR curses "."
If
.B \%newterm
is called more than once for the same terminal,
the first terminal referred to must be the last one for which
.B \%endwin
is called.
.PP
A program should always call
.B \%endwin
before exiting the application
or temporarily suspending
.IR curses "'s"
management of the terminal.
.BR \%endwin ":"
.bP
(if \fB\%start_color\fP(3X) has been called)
resets the terminal's foreground and background colors
to correspond with those of color pair 0
(the default pair),
.bP
moves the cursor to the lower left-hand corner of the screen,
.bP
(if \fB\%start_color\fP(3X) has been called)
restores the default color pair,
.bP
clears the line,
.bP
sets the cursor to normal visibility
(see \fB\%curs_set\fP(3X)),
.bP
if applicable,
stops cursor-addressing mode using the
.B \%exit_ca_mode
.RB \%( rmcup )
terminal capability,
and
.bP
restores terminal modes (see \fB\%reset_shell_mode\fP(3X)).
.PP
Calling \fB\%refresh\fP(3X) or \fB\%doupdate\fP(3X) after a
temporary suspension causes
.I curses
to resume managing the terminal.
.SS isendwin
.B \%isendwin
returns
.B TRUE
if \fB\%wrefresh\fP(3X)
has not been called since the most recent
.B \%endwin
call,
and
.B FALSE
otherwise.
.SS set_term
.B \%set_term
re-orients the
.I curses
library's operations to another terminal
when the application has arranged to manage more than one with
.BR \%newterm "."
.B \%set_term
expects a
.I SCREEN
pointer previously returned by
.B \%newterm
as an argument,
and returns the previous one.
.B \%set_term
is the only standard
.I curses
API function that manipulates
.I SCREEN
pointers;
all others affect only the current terminal
(but see \fBcurs_sp_funcs\fP(3X)).
.SS delscreen
.B \%delscreen
frees the storage backing the supplied
.I SCREEN
pointer argument.
.B \%endwin
does not,
so that an application can resume managing a terminal with
.I curses
after a
(possibly conditional or temporary)
suspension;
see \fB\%curs_kernel\fP(3X).
Use
.B \%delscreen
after
.B \%endwin
when the application has no more need of a terminal device
but will not soon exit.
.SH RETURN VALUE
.B \%delscreen
returns no value.
.B \%endwin
returns
.B OK
on success and
.B ERR
on failure.
.B \%isendwin
returns
.B TRUE
or
.B FALSE
as described above.
.PP
In
.IR \%ncurses ","
.bP
.B \%endwin
returns
.B ERR
if
.RS
.bP
the terminal was not initialized,
.bP
it is called more than once without updating the screen,
or
.bP
its call of \fB\%reset_shell_mode\fP(3X) returns
.BR ERR ";"
and
.RE
.bP
.B \%newterm
returns
.B ERR
if it cannot allocate storage for the
.I SCREEN
structure
or the
.I WINDOW
structures automatically associated with it:
.BR \%curscr ","
.BR \%newscr ","
and
.BR \%stdscr "."
.PP
Functions that return pointers return null pointers on error.
In
.IR \%ncurses ","
.B \%set_term
does not fail,
and
.B \%initscr
exits the application if it does not operate successfully.
.SH NOTES
.I \%ncurses
establishes signal handlers when a function that initializes a
.IR SCREEN ","
either
.B \%initscr
or
.BR \%newterm ","
is first called.
Applications that wish to handle the following signals themselves
should set up their corresponding handlers
.I after
initializing the screen.
.TP
.I SIGINT
.IR \%ncurses 's
handler
.I attempts
to clean up the screen on exit.
Although it
.I usually
works as expected,
there are limitations.
.RS
.bP
Walking the
.I SCREEN
list is unsafe, since all list management
is done without any signal blocking.
.bP
When an application has been built with the
.I \%_REENTRANT
macro defined
(and corresponding system support),
.B \%set_term
uses functions that could deadlock or misbehave in other ways.
.bP
.B \%endwin
calls other functions,
many of which use \fI\%stdio\fP(3) or other library functions that are
clearly unsafe.
.RE
.TP
.I SIGTERM
.I \%ncurses
uses the same handler as for
.IR \%SIGINT ","
with the same limitations.
It is not mentioned in X/Open Curses,
but is more suitable for this purpose than
.I \%SIGQUIT
(which is used in debugging).
.TP
.I SIGTSTP
.IR \%ncurses 's
handler manages the terminal-generated stop signal,
used in job control.
When resuming the process,
.I \%ncurses
discards pending input with \fB\%flushinp\fP(3X)
and repaints the screen,
assuming that it has been completely altered.
It also updates the saved terminal modes with
\fB\%def_shell_mode\fP(3X).
.TP
.I SIGWINCH
.I \%ncurses
handles changes to the terminal's window size,
a phenomenon ignored in standardization efforts.
It sets a (signal-safe) variable
that is later tested by \fB\%wgetch\fP(3X) and \fB\%wget_wch\fP(3X).
.RS
.bP
.B \%wgetch
returns the key code
.BR \%KEY_RESIZE "."
.bP
.B \%wget_wch
returns
.B \%KEY_CODE_YES
and sets its
.I wch
parameter to
.BR \%KEY_RESIZE "."
.RE
.IP
At the same time,
.I \%ncurses
calls \fB\%resizeterm\fP(3X)
to adjust the standard screen
.B \%stdscr
and update global variables such as
.B LINES
and
.BR COLS "."
.SH PORTABILITY
X/Open Curses Issue\ 4 describes these functions.
It specifies no error conditions for them.
.SS Differences
X/Open Curses specifies that portable applications must not
call
.I \%initscr
more than once.
.bP
The portable way to use
.I \%initscr
is once only,
using
.I \%refresh
to restore the screen after
.IR \%endwin "."
.bP
.I \%ncurses
permits use of
.I \%initscr
after
.IR \%endwin "."
.PP
.I \%initscr
in BSD,
from its inception (1980) through the Net/2 release (1991) returned
.I ERR
cast to a
.I \%WINDOW
pointer when detecting an error.
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/initscr.c
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/lib/libcurses/initscr.c
4.4BSD (1995)
instead returned a null pointer.
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/lib/libcurses/initscr.c
Neither exited the application.
It is safe but redundant to check the return value of
.I \%initscr
in X/Open Curses.
.PP
Calling
.I \%endwin
does not dispose of the memory allocated by
.I \%initscr
or
.IR \%newterm "."
Deleting a
.I SCREEN
provides a way to do this.
.bP
X/Open Curses does not say what happens to
.IR \%WINDOW s
when
.I \%delscreen
\*(``frees storage associated with the
.IR SCREEN "\*(''"
nor does the SVr4 documentation help,
adding that it should be called after
.I \%endwin
if a
.I SCREEN
is no longer needed.
.bP
However,
every
.I \%WINDOW
is implicitly associated with a
.IR SCREEN ","
so it is reasonable to expect
.I \%delscreen
to dispose of them.
.bP
SVr4 deletes the standard
.I \%WINDOW
structures
.I \%stdscr
and
.I \%curscr
as well as a work area
.IR \%newscr "."
It ignores other windows.
.bP
Since version 4.0 (1996),
.I \%ncurses
has maintained a list of all windows for each screen,
using that information to delete those windows when
.I \%delscreen
is
called.
.bP
NetBSD copied this feature of
.I \%ncurses
in 2001.
.I \%PDCurses
follows the SVr4 model,
deleting only the standard
.I \%WINDOW
structures and
.IR \%newscr "."
.SS "High-level versus Low-level Functions"
Implementations disagree
regarding the level of abstraction applicable to a function or property.
For example,
.I SCREEN
(returned by
.IR \%newterm ")"
and
.I \%TERMINAL
(returned by \fB\%setupterm\fP(3X)) hold file
descriptors for the output stream.
If an application switches screens using
.IR \%set_term ","
or switches terminals using \fB\%set_curterm\fP(3X),
applications
using the output file descriptor can behave differently
depending on the structure holding the corresponding descriptor.
.bP
NetBSD's
.I \%baudrate
function uses the descriptor in
.IR \%TERMINAL "."
.I \%ncurses
and SVr4 use the descriptor in
.IR SCREEN "."
.bP
NetBSD and
.I \%ncurses
use the descriptor
in
.I \%TERMINAL
for terminal I/O modes,
e.g.,
\fB\%def_shell_mode\fP(3X),
\fB\%def_prog_mode\fP(3X).
SVr4 uses the descriptor in
.IR SCREEN "."
.SS "Unset \fITERM\fP Environment Variable"
If the
.I TERM
variable is not set in the environment or has an empty value,
.I \%initscr
uses the value \*(``unknown\*('',
which normally corresponds to a terminal entry with the
.B \%generic
.RB ( gn )
capability.
Generic entries are detected by \fB\%setupterm\fP(3X)
and cannot be used for full-screen operation.
Other implementations may handle
a missing or empty
.I TERM
variable differently.
.SS "Signal Handlers"
Quoting X/Open Curses Issue\ 7,
section 3.1.1:
.RS 5
.PP
Curses implementations may provide for special handling of the
\%SIGINT,
\%SIGQUIT,
and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
.IR \%initscr ()
is called.\|.\|.
.PP
Any special handling for these signals may remain in effect for the
life of the process or until the process changes the disposition of
the signal.
.PP
None of the Curses functions are required to be safe
with respect to signals.\|.\|.
.RE
.PP
Section \*(``NOTES\*('' above discusses
.IR \%ncurses 's
signal handlers.
.SH HISTORY
4BSD (1980)
introduced
.I \%initscr
and
.IR \%endwin "."
.PP
SVr2 (1984)
added
.I \%newterm
and
.IR \%set_term "."
.PP
SVr3.1 (1987)
supplied
.I \%delscreen
and
.IR \%isendwin "."
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_kernel\fP(3X),
\fB\%curs_refresh\fP(3X),
\fB\%curs_slk\fP(3X),
\fB\%curs_terminfo\fP(3X),
\fB\%curs_util\fP(3X),
\fB\%curs_variables\fP(3X)