HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |NOTES |BUGS |PORTABILITY |SEE ALSO |COLOPHON | |
curs_window(3X)curs_window(3X)newwin,delwin,mvwin,subwin,derwin,mvderwin,dupwin,wsyncup,syncok,wcursyncup,wsyncdown- createcurseswindows
#include <curses.h>WINDOW *newwin(intnlines, intncols,intbegin_y, intbegin_x);int delwin(WINDOW *win);int mvwin(WINDOW *win, inty, intx);WINDOW *subwin(WINDOW *orig,intnlines, intncols,intbegin_y, intbegin_x);WINDOW *derwin(WINDOW *orig,intnlines, intncols,intbegin_y, intbegin_x);int mvderwin(WINDOW *win, intpar_y, intpar_x);WINDOW *dupwin(WINDOW *win);void wsyncup(WINDOW *win);int syncok(WINDOW *win, boolbf);void wcursyncup(WINDOW *win);void wsyncdown(WINDOW *win);
newwin Callingnewwincreates 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 linebegin_y, columnbegin_x If eithernlines orncols is zero, they default toLINES -begin_y andCOLS -begin_x. A new full-screen window is created by callingnewwin(0,0,0,0). Regardless of the function used for creating a new window (e.g.,newwin,subwin,derwin,newpad), rather than a duplicate (withdupwin), all of the window modes are initialized to the default values. These functions set window modes after a window is creat‐ ed: idcok, idlok, immedok, keypad, leaveok, nodelay, scrollok, setscrreg, syncok, wbkgdset, wbkgrndset, and wtimeoutdelwin Callingdelwindeletes the named window, freeing all memory asso‐ ciated with it (it does not actually erase the window's screen im‐ age). Subwindows must be deleted before the main window can be deleted.mvwin Callingmvwinmoves 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. Mov‐ ing subwindows is allowed, but should be avoided.subwin Callingsubwincreates 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 windoworig, so that changes made to one window will affect both windows. When using this routine, it is necessary to calltouchwinortouchlineonorig before callingwrefreshon the subwindow.derwin Callingderwinis the same as callingsubwin,except thatbegin_y andbegin_x are relative to the origin of the windoworig rather than the screen. There is no difference between the subwindows and the derived windows. Callingmvderwinmoves 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 Callingdupwincreates an exact duplicate of the windowwin.wsyncup Callingwsyncuptouches all locations in ancestors ofwin that are changed inwin. Ifsyncokis called with second argumentTRUE thenwsyncupis called automatically whenever there is a change in the window.wsyncdown Thewsyncdownroutine touches each location inwin that has been touched in any of its ancestor windows. This routine is called bywrefresh, so it should almost never be necessary to call it manu‐ ally.wcursyncup The routinewcursyncupupdates the current cursor position of all the ancestors of the window to reflect the current cursor position of the window.
Routines that return an integer return the integerERRupon fail‐ ure andOK(SVr4 only specifies "an integer value other thanERR") upon successful completion. Routines that return pointers returnNULLon error. X/Open defines no error conditions. In this implementationdelwin returns an error if the window pointer is null, or if the window is the parent of another window.derwin returns an error if the parent window pointer is null, or if any of its ordinates or dimensions is negative, or if the re‐ sulting window does not fit inside the parent window.dupwin returns an error if the window pointer is null. This implementation also maintains a list of windows, and checks that the pointer passed todelwinis one that it cre‐ ated, returning an error if it was not..mvderwin returns an error if the window pointer is null, or if some part of the window would be placed off-screen.mvwin returns an error if the window pointer is null, or if the window is really a pad, or if some part of the window would be placed off-screen.newwin will fail if either of its beginning ordinates is negative, or if either the number of lines or columns is negative.syncok returns an error if the window pointer is null.subwin returns an error if the parent window pointer is null, or if any of its ordinates or dimensions is negative, or if the re‐ sulting window does not fit inside the parent window. The functions which return a window pointer may also fail if there is insufficient memory for its data structures. Any of these functions will fail if the screen has not been initialized, i.e., withinitscrornewterm.
If many small changes are made to the window, thewsyncupoption could degrade performance. Note thatsyncokmay be a macro.
The subwindow functions (subwin,derwin,mvderwin,wsyncup,wsync‐down,wcursyncup,syncok) are flaky, incompletely implemented, and not well tested. The System V curses documentation is very unclear about whatwsyn‐cupandwsyncdownactually do. It seems to imply that they are only supposed to touch exactly those lines that are affected by ancestor changes. The language here, and the behavior of thecursesimplementation, is patterned on the XPG4 curses standard. The weaker XPG4 spec may result in slower updates.
The XSI Curses standard, Issue 4 describes these functions. X/Open Curses states regardingdelwin: • It must delete subwindows before deleting their parent. • Ifdelwinis asked to delete a parent window, it can only suc‐ ceed if the curses library keeps a list of the subwindows. SVr4 curses kept a count of the number of subwindows rather than a list. It simply returnedERRwhen asked to delete a subwindow. Solaris X/Open curses does not even make that check, and will delete a parent window which still has subwin‐ dows. • Since release 4.0 (1996), ncurses maintains a list of windows for each screen, to ensure that a window has no subwindows be‐ fore allowing deletion. • NetBSD copied this feature of ncurses in 2003. PDCurses follows the scheme used in Solaris X/Open curses.
curses(3X),curs_initscr(3X),curs_refresh(3X),curs_touch(3X),curs_variables(3X)
This page is part of thencurses (new curses) project. Informa‐ tion about the project can be found at ⟨https://www.gnu.org/software/ncurses/ncurses.html⟩. If you have a bug report for this manual page, send it to bug-ncurses-request@gnu.org. This page was obtained from the project's upstream Git mirror of the CVS repository ⟨https://github.com/mirror/ncurses.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2023-03-12.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgcurs_window(3X)HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |