curs\_initscr(3X) Library calls curs\_initscr(3X)

# [NAME](#NAME)

**initscr**, **newterm**, **endwin**, **isendwin**, **set\_term**, **delscreen** - initialize, manipulate, or tear down *curses* terminal interface

# [SYNOPSIS](#SYNOPSIS)

```
#include <curses.h>
```

```
WINDOW * initscr(void);
int endwin(void);
```

```
bool isendwin(void);
```

```
SCREEN * newterm(const char * type, FILE * outf, FILE * inf);
SCREEN * set_term(SCREEN * new);
void delscreen(SCREEN * sp);
```

# [DESCRIPTION](#DESCRIPTION)

## [initscr](#initscr)

**initscr** determines the terminal type and initializes the library's *SCREEN*, *WINDOW*, and other data structures. It is normally the first *curses* function call a program performs. However, an application with unusual needs might employ a few other *curses* functions beforehand:

- [**slk\_init**(3X)](/man/os/ncurses/slk_init.3X) to set up soft-label keys;
- [**filter**(3X)](/man/os/ncurses/filter.3X) if the program is designed to operate in a process pipeline;
- [**ripoffline**(3X)](/man/os/ncurses/ripoffline.3X) to reserve up to five lines at the top and/or bottom of the screen from management by **stdscr**, the standard *curses* window; and
- [**use\_env**(3X)](/man/os/ncurses/use_env.3X) and/or [**use\_tioctl**(3X)](/man/os/ncurses/use_tioctl.3X) to configure use of the process environment and operating system's terminal driver, respectively, when determining the dimensions of the terminal display.

Further, a *curses* program might call **newterm** prior to or instead of **initscr** in two specialized cases described in its subsection below.

**initscr** causes the first [**refresh**(3X)](/man/os/ncurses/refresh.3X) call to clear the screen. If errors occur, **initscr** writes an appropriate diagnostic message to the standard error stream and exits; otherwise, it returns **stdscr** (see [**curs\_variables**(3X)](/man/os/ncurses/curs_variables.3X)).

## [newterm](#newterm)

An application that manages multiple terminals should call **newterm** once for each such device *instead* of **initscr**. **newterm**'s arguments are

- the *type* of the associated terminal, or a null pointer to use the *TERM* environment variable;
- an output stream *outf* connected to the terminal; and
- an input stream *inf* connected to the terminal.

**newterm** returns a value of pointer-to-*SCREEN* type, which should be saved for later use with **set\_term** and **delscreen**.

**newterm** passes the file descriptor of the output stream to the *terminfo* function [**setupterm**(3X)](/man/os/ncurses/setupterm.3X), which returns a pointer to a *TERMINAL* structure that **newterm** stores in the *SCREEN* it returns to the application.

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 **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 **delscreen** on the pointer returned by **newterm**, and proceed with either **initscr** or a non-*curses* interface.

## [endwin](#endwin)

The program must also call **endwin** for each terminal being used before exiting from *curses*. If **newterm** is called more than once for the same terminal, the first terminal referred to must be the last one for which **endwin** is called.

A program should always call **endwin** before exiting the application or temporarily suspending *curses*'s management of the terminal. **endwin**:

- (if [**start\_color**(3X)](/man/os/ncurses/start_color.3X) has been called) resets the terminal's foreground and background colors to correspond with those of color pair 0 (the default pair),
- moves the cursor to the lower left-hand corner of the screen,
- (if [**start\_color**(3X)](/man/os/ncurses/start_color.3X) has been called) restores the default color pair,
- clears the line,
- sets the cursor to normal visibility (see [**curs\_set**(3X)](/man/os/ncurses/curs_set.3X)),
- if applicable, stops cursor-addressing mode using the **exit\_ca\_mode** (**rmcup**) terminal capability, and
- restores terminal modes (see [**reset\_shell\_mode**(3X)](/man/os/ncurses/reset_shell_mode.3X)).

Calling [**refresh**(3X)](/man/os/ncurses/refresh.3X) or [**doupdate**(3X)](/man/os/ncurses/doupdate.3X) after a temporary suspension causes *curses* to resume managing the terminal.

## [isendwin](#isendwin)

**isendwin** returns **TRUE** if [**wrefresh**(3X)](/man/os/ncurses/wrefresh.3X) has not been called since the most recent **endwin** call, and **FALSE** otherwise.

## [set\_term](#set_term)

**set\_term** re-orients the *curses* library's operations to another terminal when the application has arranged to manage more than one with **newterm**. **set\_term** expects a *SCREEN* pointer previously returned by **newterm** as an argument, and returns the previous one. **set\_term** is the only standard *curses* API function that manipulates *SCREEN* pointers; all others affect only the current terminal (but see [**curs\_sp\_funcs**(3X)](/man/os/ncurses/curs_sp_funcs.3X)).

## [delscreen](#delscreen)

**delscreen** frees the storage backing the supplied *SCREEN* pointer argument. **endwin** does not, so that an application can resume managing a terminal with *curses* after a (possibly conditional or temporary) suspension; see [**curs\_kernel**(3X)](/man/os/ncurses/curs_kernel.3X). Use **delscreen** after **endwin** when the application has no more need of a terminal device but will not soon exit.

# [RETURN VALUE](#RETURN_VALUE)

**initscr** returns **stdscr**, or does not return at all (but see section “PORTABILITY” below regarding BSD *curses*). **delscreen** returns no value. **endwin** returns **OK** on success and **ERR** on failure. **isendwin** returns **TRUE** or **FALSE** as described above.

In *ncurses*,

•

**endwin** returns **ERR** if

- the terminal was not initialized,
- it is called more than once without updating the screen, or
- its call of [**reset\_shell\_mode**(3X)](/man/os/ncurses/reset_shell_mode.3X) returns **ERR**; and

•

**newterm** returns **ERR** if it cannot allocate storage for the *SCREEN* structure or the *WINDOW* structures automatically associated with it: **curscr**, **newscr**, and **stdscr**.

Functions that return pointers return null pointers on error. In *ncurses*, **set\_term** does not fail, and **initscr** exits the application if it does not operate successfully.

# [NOTES](#NOTES)

*ncurses* establishes signal handlers when a function that initializes a *SCREEN*, either **initscr** or **newterm**, is first called. Applications that wish to handle the following signals themselves should set up their corresponding handlers *after* initializing the screen.

[*SIGINT*](#SIGINT)

*ncurses*'s handler *attempts* to clean up the screen on exit. Although it *usually* works as expected, there are limitations.

- Walking the *SCREEN* list is unsafe, since all list management is done without any signal blocking.
- When an application has been built with the *\_REENTRANT* macro defined (and corresponding system support), **set\_term** uses functions that could deadlock or misbehave in other ways.
- **endwin** calls other functions, many of which use [*stdio*(3)](/man/os/ncurses/stdio.3) or other library functions that are clearly unsafe.

[*SIGTERM*](#SIGTERM)

*ncurses* uses the same handler as for *SIGINT*, with the same limitations. It is not mentioned in X/Open Curses, but is more suitable for this purpose than *SIGQUIT* (which is used in debugging).

[*SIGTSTP*](#SIGTSTP)

*ncurses*'s handler manages the terminal-generated stop signal, used in job control. When resuming the process, *ncurses* discards pending input with [**flushinp**(3X)](/man/os/ncurses/flushinp.3X) and repaints the screen, assuming that it has been completely altered. It also updates the saved terminal modes with [**def\_shell\_mode**(3X)](/man/os/ncurses/def_shell_mode.3X).

[*SIGWINCH*](#SIGWINCH)

*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 [**wgetch**(3X)](/man/os/ncurses/wgetch.3X) and [**wget\_wch**(3X)](/man/os/ncurses/wget_wch.3X).

- **wgetch** returns the key code **KEY\_RESIZE**.
- **wget\_wch** returns **KEY\_CODE\_YES** and sets its *wch* parameter to **KEY\_RESIZE**.

At the same time, *ncurses* calls [**resizeterm**(3X)](/man/os/ncurses/resizeterm.3X) to adjust the standard screen **stdscr** and update global variables such as **LINES** and **COLS**.

# [PORTABILITY](#PORTABILITY)

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them.

## [Differences](#Differences)

X/Open Curses specifies that portable applications must not call *initscr* more than once.

- The portable way to use *initscr* is once only, using *refresh* to restore the screen after *endwin*.
- *ncurses* permits use of *initscr* after *endwin*.

*initscr* in BSD, from its inception (1980) through the Net/2 release (1991) returned *ERR* cast to a *WINDOW* pointer when detecting an error. 4.4BSD (1995) instead returned a null pointer. Neither exited the application. It is safe but redundant to check the return value of *initscr* in implementations conforming to X/Open Curses.

Calling *endwin* does not dispose of the memory allocated by *initscr* or *newterm*. Deleting a *SCREEN* provides a way to do this.

- X/Open Curses does not say what happens to *WINDOW*s when *delscreen* “frees storage associated with the *SCREEN*” nor does the SVr4 documentation help, adding that it should be called after *endwin* if a *SCREEN* is no longer needed.
- However, every *WINDOW* is implicitly associated with a *SCREEN*, so it is reasonable to expect *delscreen* to dispose of them.
- SVr4 deletes the standard *WINDOW* structures *stdscr* and *curscr* as well as a work area *newscr*. It ignores other windows.
- Since version 4.0 (1996), *ncurses* has maintained a list of all windows for each screen, using that information to delete those windows when *delscreen* is called.
- NetBSD copied this feature of *ncurses* in 2001. *PDCurses* follows the SVr4 model, deleting only the standard *WINDOW* structures and *newscr*.

## [High-level versus Low-level Functions](#High-level_versus_Low-level_Functions)

Implementations disagree regarding the level of abstraction applicable to a function or property. For example, *SCREEN* (returned by *newterm*) and *TERMINAL* (returned by [**setupterm**(3X)](/man/os/ncurses/setupterm.3X)) hold file descriptors for the output stream. If an application switches screens using *set\_term*, or switches terminals using [**set\_curterm**(3X)](/man/os/ncurses/set_curterm.3X), applications using the output file descriptor can behave differently depending on the structure holding the corresponding descriptor.

- NetBSD's *baudrate* function uses the descriptor in *TERMINAL*. *ncurses* and SVr4 use the descriptor in *SCREEN*.
- NetBSD and *ncurses* use the descriptor in *TERMINAL* for terminal I/O modes, e.g., [**def\_shell\_mode**(3X)](/man/os/ncurses/def_shell_mode.3X), [**def\_prog\_mode**(3X)](/man/os/ncurses/def_prog_mode.3X). SVr4 uses the descriptor in *SCREEN*.

## [Unset *TERM* Environment Variable](#Unset_)

If the *TERM* variable is not set in the environment or has an empty value, *initscr* uses the value “unknown”, which normally corresponds to a terminal entry with the **generic** (**gn**) capability. Generic entries are detected by [**setupterm**(3X)](/man/os/ncurses/setupterm.3X) and cannot be used for full-screen operation. Other implementations may handle a missing or empty *TERM* variable differently.

## [Signal Handlers](#Signal_Handlers)

Quoting X/Open Curses Issue 7, section 3.1.1:

Curses implementations may provide for special handling of the SIGINT, SIGQUIT, and SIGTSTP signals if their disposition is SIG\_DFL at the time *initscr*() is called...

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.

None of the Curses functions are required to be safe with respect to signals...

Section “NOTES” above discusses *ncurses*'s signal handlers.

# [HISTORY](#HISTORY)

4BSD (1980) introduced *initscr* and *endwin*.

SVr2 (1984) added *newterm* and *set\_term*.

SVr3.1 (1987) supplied *delscreen* and *isendwin*.

# [SEE ALSO](#SEE_ALSO)

[**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_kernel**(3X)](/man/os/ncurses/curs_kernel.3X), [**curs\_refresh**(3X)](/man/os/ncurses/curs_refresh.3X), [**curs\_slk**(3X)](/man/os/ncurses/curs_slk.3X), [**curs\_terminfo**(3X)](/man/os/ncurses/curs_terminfo.3X), [**curs\_util**(3X)](/man/os/ncurses/curs_util.3X), [**curs\_variables**(3X)](/man/os/ncurses/curs_variables.3X)

2026-09-12 ncurses 6.6

---

Document: delscreen(3x) from ncurses 6.6.20261024-r0 (Chainguard OS)
Source: https://github.com/ThomasDickey/ncurses-snapshots