ncurses 6.5 - patch 20240622

[ncurses.git] / man / curs_scr_dump.3x

diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index 66603f1a13c53bee8171932d40355de152fb6afd..ba9881e53ae7269bdfd45f8e6be826d81b06dd6e 100644 (file)
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *

 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_scr_dump.3x,v 1.33 2023/11/11 11:47:41 tom Exp $
-.TH curs_scr_dump 3X 2023-11-11 "ncurses 6.4" "Library calls"
+.\" $Id: curs_scr_dump.3x,v 1.47 2024/06/08 20:33:56 tom Exp $
+.TH curs_scr_dump 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"

 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq


@@ -54,65 +54,167 @@ read/write a \fIcurses\fR screen from/to a file
 .nf
 \fB#include <curses.h>
 .PP
 .nf
 \fB#include <curses.h>
 .PP

-\fBint scr_dump(const char *\fIfilename\fP);
-\fBint scr_restore(const char *\fIfilename\fP);
-\fBint scr_init(const char *\fIfilename\fP);
-\fBint scr_set(const char *\fIfilename\fP);
+\fBint scr_dump(const char * \fIfilename\fP);
+\fBint scr_restore(const char * \fIfilename\fP);
+\fBint scr_init(const char * \fIfilename\fP);
+\fBint scr_set(const char * \fIfilename\fP);

 .fi
 .SH DESCRIPTION
 .fi
 .SH DESCRIPTION

+.I 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 \fB\%getwin\fP(3X) and
+\fB\%putwin\fP(3X),
+respectively.

 .SS scr_dump
 .SS scr_dump

-The \fBscr_dump\fP routine dumps the current contents
-of the \fIvirtual screen\fP
-to the file \fIfilename\fP.
+.B \%scr_dump
+writes to
+.I filename
+the contents of the virtual screen;
+see \fB\%curscr\fP(3X).

 .SS scr_restore
 .SS scr_restore

-The \fBscr_restore\fP routine sets the \fIvirtual screen\fP to the contents
-of \fIfilename\fP, which must have been written using \fBscr_dump\fP.
-The next call to \fBdoupdate\fP restores
-the \fIphysical screen\fP to the way it looked in the dump file.
+.B \%scr_restore
+updates the virtual screen to match the contents of
+.I filename
+(if validly written with
+.BR \%scr_dump ")."
+.I curses
+does not perform a refresh;
+after making any desired changes,
+call \fB\%doupdate\fP(3X) or similar.

 .SS scr_init
 .SS scr_init

-The \fBscr_init\fP routine reads in the contents of \fIfilename\fP and uses
-them to initialize the \fBcurses\fP data structures about what the terminal
-currently has on its screen.
-If the data is determined to be valid,
-\fBcurses\fP bases its next update of the screen on this information rather
-than clearing the screen and starting from scratch.
-\fBscr_init\fP is used
-after \fBinitscr\fP(3X) or a \fBsystem\fP(3) call to share
-the screen with another process which has done a \fBscr_dump\fP after its
-\fBendwin\fP(3X) call.
-The data is declared invalid
+.B \%scr_init
+reads
+.IR filename ","
+using it to initialize
+.I curses
+data structures describing the state of the terminal screen.
+.I 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.
+.PP
+.I curses
+regards the terminal as in an invalid state for computation of updates
+based on the contents of
+.I filename
+if

 .bP
 .bP

-if the terminfo capabilities \fBrmcup\fP and \fBnrrmc\fP exist, also
+.I curses
+knows that the terminal has been written to since the preceding
+.B \%scr_dump
+call,
+or

 .bP
 .bP

-if the terminal has been written to since the preceding \fBscr_dump\fP call.
-.SS scr_set
-The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and
-\fBscr_init\fP.  It tells the program that the information in \fIfilename\fP 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.
+the terminal type supports the
+.I \%term\%info
+capabilities
+.B \%exit_ca_mode
+.RB \%( rmcup )
+or
+.B \%non_rev_rmcup
+.RB \%( nrrmc ).
+.PP
+Either of the foregoing conditions means that
+.I curses
+cannot assume that the terminal's contents
+match their representation in
+.IR filename "."
+The former is due to terminal features
+(such as \fI\%xterm\fP(1)'s \*(``alternate screen\*('')
+that couple cursor-positioning mode with a local cache of screen
+contents.
+.I curses
+cannot know whether the terminal is displaying from that local cache
+at the time the application calls
+.BR \%scr_init ","
+so it makes a pessimistic assumption that a full redraw is required;
+see subsection \*(``Cursor Motions\*('' of \fB\%terminfo\fP(5).

 .PP
 .PP

-To read (write) a window from (to) a file, use the \fBgetwin\fP and
-\fBputwin\fP routines [see \fBcurs_util\fP(3X)].
+.B \%scr_init
+could be used after \fB\%initscr\fP(3X) or \fI\%system\fP(3) to share
+the screen with another process that has done a
+.B \%scr_dump
+after \fB\%endwin\fP(3X).
+An application that supports suspending its state on exit and subsequent
+resumption upon later execution might use
+.B \%scr_dump
+and
+.B \%scr_init
+thus.
+.SS scr_set
+.B \%scr_set
+combines
+.B \%scr_restore
+and
+.BR \%scr_init ","
+synchronizing the contents of
+.I filename
+with the virtual screen.
+It can be regarded as a screen inheritance function;
+consider a real-time screen-sharing application.

 .SH RETURN VALUE
 .SH RETURN VALUE

-All routines return the integer \fBERR\fP upon failure and \fBOK\fP
-upon success.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.

 .PP
 .PP

-X/Open defines no error conditions.
-In this implementation,
-each will return an error if the file cannot be opened.
+In
+.IR \%ncurses ","
+each function returns
+.B ERR
+if it cannot open
+.IR filename "."
+.BR \%scr_init ","
+.BR \%scr_restore ","
+and
+.B \%scr_set
+return
+.B ERR
+if the contents of
+.I filename
+are invalid.

 .SH NOTES
 .SH NOTES

-Note that \fBscr_init\fP, \fBscr_set\fP, and \fBscr_restore\fP may be macros.
+.BR \%scr_init ","
+.BR \%scr_restore ","
+and
+.B \%scr_set
+may be implemented as macros.

 .SH PORTABILITY
 .SH PORTABILITY

-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.
+.\" Unusually, SVID 4 explicitly indicated "OK" as a possible return
+.\" value, rather than the "integer other than ERR" refrain (p. 529).
+.PP
+.\" SVID 4, p. 529
+SVr4 omitted the
+.I \%const
+qualifiers.

 .PP
 .PP

-The SVr4 docs merely say under \fBscr_init\fP that the dump data is also
-considered invalid "if the time-stamp of the tty is old" but do not define
-\*(``old\*(''.
+SVr4 documentation describes
+.B \%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\*(''.
+.SH HISTORY
+SVr3 (1987) introduced
+.BR \%scr_dump ","
+.BR \%scr_init ","
+and
+.BR \%scr_restore "."
+SVr3.1 added
+.BR \%scr_set "."

 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_util\fP(3X),
 \fB\%system\fP(3),
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_initscr\fP(3X),
 \fB\%curs_refresh\fP(3X),
 \fB\%curs_util\fP(3X),
 \fB\%system\fP(3),

-\fB\%scr_dump\fP(5)
+\fB\%scr_dump\fP(5),
+\fB\%terminfo\fP(5)