curs_scr_dump(3X)

💖 curs_scr_dump — the scr_dump girlies of the ncurses library calls 💖

okay bestie, so this is a page from the curs_scr_dump(3X) manual, aka the Library calls section, and it's all about yeeting your screen into a file and getting it back. no cap, it's giving time-travel for terminals. ✨

---

🌸 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);

like, four little functions, four little ints, all taking a const char * filename. the range? iconic. 👑

---

✨ DESCRIPTION ✨

so curses literally hands your app the ability to write what's on the screen into a file and then read it right back. it's the ultimate save-state. 💾

but wait — if you want to read/write a window (not the whole entire screen) from/to a file, that's a different girlies' job: use getwin(3X) and putwin(3X) respectively. iykyk.

🦋 scr_dump

scr_dump writes to filename the contents of the virtual screen — go check out curscr(3X) if you need the lore on that. it's the "take a pic of the screen and save it" one. 📸

🍓 scr_restore

scr_restore updates the virtual screen so it matches the contents of filename (assuming it was validly written with scr_dump, obvi). but — and this is the important part, bestie — curses does not perform a refresh. so after you make any changes you wanted to make, you gotta call doupdate(3X) or something similar. don't forget, or nothing will look different and you'll be like 😭.

💜 scr_init

scr_init reads filename and uses it to initialize curses' data structures describing the state of the terminal screen. then — if it decides the terminal state is valid — curses bases its next screen update on that info instead of clearing everything and starting from scratch. main character energy honestly.

now here's the vibe check: curses considers the terminal to be in an invalid state for computing updates based on filename's contents if either of these is true:

• 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 those conditions means curses cannot assume the terminal's contents match their representation in filename. the first one is because of terminal features — like 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 the subsection "Cursor Motions" of terminfo(5) for the deep dive.

so when would you even use scr_init? okay so it could be used after initscr(3X) or system(3) to share the screen with another process that has done a scr_dump after endwin(3X). and an application that supports suspending its state on exit and then resuming later upon subsequent execution might use scr_dump and scr_init like that. slay, honestly. 💅

🌈 scr_set

scr_set combines scr_restore and scr_init, synchronizing the contents of filename with the virtual screen. think of it as a screen inheritance function — imagine a real-time screen-sharing application. it's giving collab. 🫶

---

💖 RETURN VALUE 💖

these functions return OK on success and ERR on failure. periodt.

in ncurses, each function returns ERR if it cannot 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. sneaky little things. 🙈

---

⭐ PORTABILITY ⭐

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. no notes. 😌

SVr4 omitted the const qualifiers. (rude.)

SVr4 documentation describes scr_init such that the dump data is also considered invalid "if the time-stamp of the tty is old" — but it does not define "old". like, define your terms bestie?? 😭

As of 2024, PDCurses provides these functions. NetBSD curses does not. rip to NetBSD i guess 💀

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 instead uses its wresize(3X) extension to adjust the restored window size. flexible king behavior ✨

---

👑 HISTORY 👑

SVr3 (1987) introduced scr_dump, scr_init, and scr_restore. SVr3.1 added scr_set. vintage icons, all of them. 🎀

---

🌸 SEE ALSO 🌸

• curses(3X)
• curs_initscr(3X)
• curs_refresh(3X)
• curs_util(3X)
• system(3)
• scr_dump(5)
• terminfo(5)
• wresize(3X)

---

and that's the whole page, bestie!! this was brought to you by ncurses 6.6, dated 2025-01-18, and filed under curs_scr_dump(3X). go dump a screen, restore it, and live your truth. 🦋💜 mwah!