scr_dump(3NCURSES)

💖 scr_dump — the 3NCURSES girlies' guide to yeeting your screen into a file and getting it back 💖

okay bestie, so this is a library call page from the 3NCURSES manual — yes we're doing library calls today, main character energy fr fr.

---

✨ 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 🦋

so basically curses lets your app write the whole contents of the screen out to a file, and read them right back in. iconic behavior honestly 💅

quick side quest: if you wanna do that with a window instead of the whole entire screen, that's a whole different vibe — use getwin(3NCURSES) to read and putwin(3NCURSES) to write. different functions, different girlies.

💾 scr_dump

scr_dump writes the contents of the virtual screen into filename. the virtual screen is like, the concept of it — peep curscr(3NCURSES) for the deets. ✨

💾 scr_restore

scr_restore updates the virtual screen so it matches whatever's in filename — but only if that file was validly written with scr_dump, okay? no fake files allowed bestie.

and listen: curses does NOT refresh for you. it's giving "you're on your own" 😭 so after you make whatever changes you wanted, go ahead and call doupdate(3NCURSES) or something similar. periodt.

💾 scr_init

scr_init reads filename and uses it to initialize the curses data structures that describe the state of the terminal screen. then — if curses decides that terminal state is valid — it bases its next update of the screen on that info, instead of clearing everything and starting from absolute scratch. slay, less redrawing 🫶

now here's the tea, because curses considers the terminal in an invalid state for computing updates from filename when:

• curses knows 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 those conditions means curses can't assume the terminal's contents match their representation in filename. and why? because the first one is due to terminal features (like xterm(1)'s "alternate screen" — you know the one 👀) that couple cursor-positioning mode with a local cache of screen contents. curses literally cannot know whether the terminal is displaying from that local cache at the moment your app calls scr_init, so it makes a pessimistic assumption that a full redraw is required. pessimistic queen 💀 see subsection "Cursor Motions" of terminfo(5) if you want the full lore.

you could use scr_init after initscr(3NCURSES) or system(3) to share the screen with another process that already did a scr_dump after endwin(3NCURSES). and if your app supports suspending its state on exit and then resuming later when it runs again? that's the scr_dump + scr_init combo meal right there 🍓

💾 scr_set

scr_set is literally scr_restore + scr_init combined — it syncs up the contents of filename with the virtual screen. think of it as a screen inheritance function 👑 imagine a real-time screen-sharing app. yeah. that vibe.

---

🌈 RETURN VALUE 🌈

these functions return OK on success and ERR on failure. simple as that.

in ncurses, each function returns ERR if it can't open filename. and 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. iykyk.

---

⭐ PORTABILITY ⭐

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. wild, right?

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". bestie that is so unhelpful 😭

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 on the curses library's internal data structures. ncurses dodges that whole drawback by storing the dump in textual form, which lets you use the data way more flexibly. for instance: the scr_restore of SVr4 curses requires the dumped window to have the same dimensions as the restored window. ncurses instead uses its wresize(3NCURSES) extension to adjust the restored window size. we love a glow-up 💅✨

---

💜 HISTORY 💜

SVr3 (1987) introduced scr_dump, scr_init, and scr_restore. then SVr3.1 added scr_set. a classic sequel moment 🔥

---

👑 SEE ALSO 👑

ncurses(3NCURSES), initscr(3NCURSES), refresh(3NCURSES), util(3NCURSES), system(3), scr_dump(5), terminfo(5), wresize(3NCURSES)

---

and that's the whole page bestie!! 🫶 this was ncurses 6.6, dated 2025-01-18, from your girl scr_dump(3NCURSES). go dump a screen, you got this 💖🌈✨