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