---
name: "scr_dump"
section: "3ncurses"
platform: "linux"
package: "ncurses-doc"
version: "6.5+20250216-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/scr_dump/3ncurses"
---

# scr\_dump(3ncurses)

read/write a curses screen from/to a file

## NAME

**scr\_dump**, **scr\_restore**, **scr\_init**, **scr\_set** - read/write a *curses* screen from/to a file

## SYNOPSIS

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

**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

*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(3NCURSES) and** **putwin(3NCURSES),** **respectively.**

### scr\_dump

**scr\_dump** **writes to** *filename* **the contents of the virtual screen;** **see curscr(3NCURSES).**

### 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(3NCURSES) or similar.**

### 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)'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)](/terminfo/5.md).**

**scr\_init** **could be used after initscr(3NCURSES) or** *system***(3) to share** **the screen with another process that has done a** **scr\_dump** **after endwin(3NCURSES).** **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** **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

**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

**scr\_init**, **scr\_restore**, **and** **scr\_set** **may be implemented as macros.**

## 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(3NCURSES)** **extension** **to adjust the restored window size.**

## HISTORY

**SVr3 (1987) introduced** *scr\_dump*, *scr\_init*, **and** *scr\_restore*. **SVr3.1 added** *scr\_set*.

## SEE ALSO

**ncurses(3NCURSES),** **initscr(3NCURSES),** **refresh(3NCURSES),** **util(3NCURSES),** **[system(3)](/system/3.md),** **[scr\_dump(5)](/scr_dump/5.md),** **[terminfo(5)](/terminfo/5.md),** **wresize(3NCURSES)**