- The scr_dump routine dumps the current contents of the virtual screen
- to the file filename.
+ 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_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 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
- The scr_restore routine sets the virtual screen to the contents of
- filename, which must have been written using scr_dump. The next call
- to doupdate restores the screen to the way it looked in the dump file.
+ ocurses knows that the terminal has been written to since the
+ preceding scr_dump call, or
- The scr_init routine reads in the contents of filename and uses them to
- initialize the curses data structures about what the terminal currently
- has on its screen. If the data is determined to be valid, curses bases
- its next update of the screen on this information rather than clearing
- the screen and starting from scratch. scr_init is used after initscr
- or a system call to share the screen with another process which has
- done a scr_dump after its endwin(3x) call. The data is declared in-
- valid if the terminfo capabilities rmcup and nrrmc exist; also if the
- terminal has been written to since the preceding scr_dump call.
+ o the terminal type supports the terminfo capabilities exit_ca_mode
+ (rmcup) or non_rev_rmcup (nrrmc).
- The scr_set routine is a combination of scr_restore and scr_init. It
- tells the program that the information in filename is what is currently
- on the screen, and also what the program wants on the screen. This can
- be thought of as a screen inheritance function.
+ 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).
- To read (write) a window from (to) a file, use the getwin and putwin
- routines [see curs_util(3x)].
+ 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 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.
- All routines return the integer ERR upon failure and OK upon success.
+ These functions return OK on success and ERR on failure.
- X/Open defines no error conditions. In this implementation, each will
- return an error if the file cannot be opened.
+ 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.
- The XSI Curses standard, Issue 4, describes these functions (adding the
- const qualifiers).
+ 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".
- The SVr4 docs merely say under scr_init that the dump data is also con-
- sidered invalid "if the time-stamp of the tty is old" but do not define
- "old".
+
+