curs\_scr\_dump(3X) Library calls curs\_scr\_dump(3X) # [NAME](#NAME) **scr\_dump**, **scr\_restore**, **scr\_init**, **scr\_set** - read/write a *curses* screen from/to a file # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` int scr_dump(const char * filename); int scr_restore(const char * filename); int scr_init(const char * filename); int scr_set(const char * filename); ``` # [DESCRIPTION](#DESCRIPTION) *curses* provides applications the ability to write the contents of the screen to a file and read them back. To read/write a window (rather than the whole screen) from/to a file, use [**getwin**(3X)](/man/os/ncurses/getwin.3X) and [**putwin**(3X)](/man/os/ncurses/putwin.3X), respectively. ## [scr\_dump](#scr_dump) **scr\_dump** writes to *filename* the contents of the virtual screen; see [**curscr**(3X)](/man/os/ncurses/curscr.3X). ## [scr\_restore](#scr_restore) **scr\_restore** updates the virtual screen to match the contents of *filename* (if validly written with **scr\_dump**). *curses* does not perform a refresh; after making any desired changes, call [**doupdate**(3X)](/man/os/ncurses/doupdate.3X) or similar. ## [scr\_init](#scr_init) **scr\_init** reads *filename*, using it to initialize *curses* data structures describing the state of the terminal screen. *curses* then, if it decides the terminal state is valid, bases its next update of the screen on this information rather than clearing it and starting from scratch. *curses* regards the terminal as in an invalid state for computation of updates based on the contents of *filename* if - *curses* knows that the terminal has been written to since the preceding **scr\_dump** call, or - the terminal type supports the *terminfo* capabilities **exit\_ca\_mode** (**rmcup**) or **non\_rev\_rmcup** (**nrrmc**). Either of the foregoing conditions means that *curses* cannot assume that the terminal's contents match their representation in *filename*. The former is due to terminal features (such as [*xterm*(1)](/man/os/ncurses/xterm.1)'s “alternate screen”) that couple cursor-positioning mode with a local cache of screen contents. *curses* cannot know whether the terminal is displaying from that local cache at the time the application calls **scr\_init**, so it makes a pessimistic assumption that a full redraw is required; see subsection “Cursor Motions” of [**terminfo**(5)](/man/os/ncurses/terminfo.5). **scr\_init** could be used after [**initscr**(3X)](/man/os/ncurses/initscr.3X) or [*system*(3)](/man/os/ncurses/system.3) to share the screen with another process that has done a **scr\_dump** after [**endwin**(3X)](/man/os/ncurses/endwin.3X). An application that supports suspending its state on exit and subsequent resumption upon later execution might use **scr\_dump** and **scr\_init** thus. ## [scr\_set](#scr_set) **scr\_set** combines **scr\_restore** and **scr\_init**, synchronizing the contents of *filename* with the virtual screen. It can be regarded as a screen inheritance function; consider a real-time screen-sharing application. # [RETURN VALUE](#RETURN_VALUE) These functions return **OK** on success and **ERR** on failure. In *ncurses*, each function returns **ERR** if it cannot open *filename*. **scr\_init**, **scr\_restore**, and **scr\_set** return **ERR** if the contents of *filename* are invalid. # [NOTES](#NOTES) **scr\_init**, **scr\_restore**, and **scr\_set** may be implemented as macros. # [PORTABILITY](#PORTABILITY) X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them. SVr4 omitted the *const* qualifiers. SVr4 documentation describes *scr\_init* such that the dump data is also considered invalid “if the time-stamp of the tty is old” but does not define “old”. As of 2024, *PDCurses* provides these functions. NetBSD *curses* does not. Other implementations of *curses* store the window in binary form, which makes the dump dependent upon the *curses* library's internal data structures. *ncurses* avoids this drawback by storing the dump in textual form, allowing more flexible use of the data. For instance, the *scr\_restore* of SVr4 *curses* requires that the dumped window have the same dimensions as the restored window. *ncurses* uses its [**wresize**(3X)](/man/os/ncurses/wresize.3X) extension to adjust the restored window size. # [HISTORY](#HISTORY) SVr3 (1987) introduced *scr\_dump*, *scr\_init*, and *scr\_restore*. SVr3.1 added *scr\_set*. # [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\_util**(3X)](/man/os/ncurses/curs_util.3X), [**system**(3)](/man/os/ncurses/system.3), [**scr\_dump**(5)](/man/os/ncurses/scr_dump.5), [**terminfo**(5)](/man/os/ncurses/terminfo.5), [**wresize**(3X)](/man/os/ncurses/wresize.3X) 2025-01-18 ncurses 6.6 --- Document: scr_init(3x) from ncurses 6.6.20261017-r0 (Chainguard OS) Source: https://github.com/ThomasDickey/ncurses-snapshots