# curs_scr_dump 3x 2025-01-18 ncurses 6.5 Library calls

    curs_scr_dump(3x)                Library calls               curs_scr_dump(3x)

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

### scr_dump

           scr_dump  writes  to  filename  the contents of the virtual screen; see
           curscr(3x).

### 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)  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

           o   curses  knows  that  the  terminal  has  been  written to since the
               preceding scr_dump call, or

           o   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).

           scr_init  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).
           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(3x)
           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

           curses(3x), curs_initscr(3x), curs_refresh(3x), curs_util(3x),
           system(3), scr_dump(5), terminfo(5), wresize(3x)

    ncurses 6.5                       2025-01-18                 curs_scr_dump(3x)