curs\_window(3X) Library calls curs\_window(3X) # [NAME](#NAME) **newwin**, **delwin**, **mvwin**, **subwin**, **derwin**, **mvderwin**, **dupwin**, **wsyncup**, **syncok**, **wcursyncup**, **wsyncdown** - create and manipulate *curses* windows # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` WINDOW * newwin( int nlines, int ncols, int begin_y, int begin_x); int delwin(WINDOW * win); int mvwin(WINDOW * win, int y, int x); WINDOW * subwin(WINDOW * orig, int nlines, int ncols, int begin_y, int begin_x); WINDOW * derwin(WINDOW * orig, int nlines, int ncols, int begin_y, int begin_x); int mvderwin(WINDOW * win, int par_y, int par_x); WINDOW * dupwin(WINDOW * win); void wsyncup(WINDOW * win); int syncok(WINDOW * win, bool bf); void wcursyncup(WINDOW * win); void wsyncdown(WINDOW * win); ``` # [DESCRIPTION](#DESCRIPTION) ## [newwin](#newwin) Calling **newwin** creates and returns a pointer to a new window with the given number of lines and columns. The upper left-hand corner of the window is at line *begin*\_*y*, column *begin*\_*x* If either *nlines* or *ncols* is zero, they default to **LINES -** *begin*\_*y* and **COLS -** *begin*\_*x*. A new full-screen window is created by calling **newwin(0,0,0,0)**. Regardless of the function used for creating a new window (e.g., **newwin**, **subwin**, **derwin**, **newpad**), rather than a duplicate (with **dupwin**), all of the window modes are initialized to the default values. The following functions set a window's modes after it is created: **idcok**, **idlok**, **immedok**, **keypad**, **leaveok**, **nodelay**, **notimeout**, **scrollok**, **setscrreg**, **syncok**, **wbkgdset**, **wbkgrndset**, and **wtimeout**. ## [delwin](#delwin) Calling **delwin** deletes the named window, freeing all memory associated with it (it does not actually erase the window's screen image). Subwindows must be deleted before the main window can be deleted. ## [mvwin](#mvwin) Calling **mvwin** moves the window so that the upper left-hand corner is at position (*x*, *y*). If the move would cause the window to be off the screen, it is an error and the window is not moved. Moving subwindows is allowed, but should be avoided. ## [subwin](#subwin) Calling **subwin** creates and returns a pointer to a new window with the given number of lines, *nlines*, and columns, *ncols*. The window is at position (*begin*\_*y*, *begin*\_*x*) on the screen. The subwindow shares memory with the window *orig*, its *ancestor*, so that changes made to one window will affect both windows. When using this routine, it is necessary to call **touchwin** or **touchline** on *orig* before calling **wrefresh** on the subwindow. ## [derwin](#derwin) Calling **derwin** is the same as calling **subwin,** except that *begin*\_*y* and *begin*\_*x* are relative to the origin of the window *orig* rather than the screen. There is no difference between the subwindows and the derived windows. ## [mvderwin](#mvderwin) Calling **mvderwin** moves a derived window (or subwindow) inside its parent window. The screen-relative parameters of the window are not changed. This routine is used to display different parts of the parent window at the same physical position on the screen. ## [dupwin](#dupwin) Calling **dupwin** creates an exact duplicate of the window *win*. ## [wsyncup](#wsyncup) Calling **wsyncup** touches all locations in ancestors of *win* that are changed in *win*. If **syncok** is called with second argument **TRUE** then **wsyncup** is called automatically whenever there is a change in the window. ## [wsyncdown](#wsyncdown) The **wsyncdown** routine touches each location in *win* that has been touched in any of its ancestor windows. This routine is called by **wrefresh**, so it should almost never be necessary to call it manually. ## [wcursyncup](#wcursyncup) The routine **wcursyncup** updates the current cursor position of all the ancestors of the window to reflect the current cursor position of the window. # [RETURN VALUE](#RETURN_VALUE) Functions that return integers return **ERR** upon failure and **OK** upon success. Functions that return pointers return a null pointer on failure. *ncurses* defines several error conditions. • **delwin** returns **ERR** if *win* is a null pointer, or if it is the parent of another window. *ncurses* maintains a list of windows, and checks that the pointer passed to **delwin** is one that it created, returning **ERR** if it was not. - **derwin** returns **ERR** if *orig* is a null pointer, or if any of the ordinate or dimension arguments is negative, or if the resulting window does not fit inside the parent window. - **dupwin** returns **ERR** if *win* is a null pointer. - **mvderwin** returns **ERR** if *win* is a null pointer, or if any part of the window would be placed off-screen. - **mvwin** returns **ERR** if *win* is a null pointer, if *win* is a pad, or if any part of the window would be placed off-screen. - **newwin** returns **ERR** if any of its arguments is negative. - **subwin** returns **ERR** if *orig* is a null pointer, or if any of the ordinate or dimension arguments is negative, or if the resulting window does not fit inside the parent window. - **syncok** returns **ERR** if *win* is a null pointer. Functions that return a window pointer fail if memory allocation for their data structures fails. All of these functions fail if the screen has not been initialized; see [**initscr**(3X)](/man/os/ncurses/initscr.3X) or [**newterm**(3X)](/man/os/ncurses/newterm.3X). # [NOTES](#NOTES) **syncok** may be implemented as a macro. Calling **syncup** on a window and making many small changes to it could degrade performance. # [PORTABILITY](#PORTABILITY) X/Open Curses Issue 4 describes these functions. It specifies no error conditions for *delwin*, *derwin*, *dupwin*, *newwin*, *mvderwin*, or *syncok*. For functions returning integers (except *delwin*), SVr4 describes a successful return value only as “an integer value other than *ERR*”. Regarding *delwin*, X/Open Curses states that \[t]he application must delete subwindows before deleting the main window. If *delwin* is asked to delete a parent window, it can succeed only if the *curses* library keeps a list of its subwindows. SVr4 *curses* kept a count of the number of subwindows rather than a list. It simply returned **ERR** when asked to delete a subwindow. Solaris X/Open *curses* (*xcurses*) does not make even that check, and will delete a parent window that still has subwindows. *PDCurses* also behaves this way. *ncurses* 4.0 (1996) and later maintains a list of windows for each screen to ensure that a window has no subwindows before allowing its deletion. NetBSD *curses* has followed suit since 2003. SVr4 *curses* documentation is unclear about what *wsyncup* and *wsyncdown* actually do. It seems to imply that they are supposed to touch only those lines that are affected by changes to a window's ancestors. The description and behavior of these functions in *ncurses* is patterned on the X/Open Curses standard; this approach may result in slower updates. # [SEE ALSO](#SEE_ALSO) [**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_initscr**(3X)](/man/os/ncurses/curs_initscr.3X), [**curs\_refresh**(3X)](/man/os/ncurses/curs_refresh.3X), [**curs\_touch**(3X)](/man/os/ncurses/curs_touch.3X), [**curs\_variables**(3X)](/man/os/ncurses/curs_variables.3X) 2025-08-23 ncurses 6.6 --- Document: delwin(3x) from ncurses 6.6.20261010-r0 (Chainguard OS) Source: https://github.com/ThomasDickey/ncurses-snapshots