ncurses 6.4 - patch 20240414

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

diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x
index 3a846ccf5b0357fbb8e12e500b90c9d7b17eb2b3..427ae2eba2c7bf9b438b10ab05ee1af206262910 100644 (file)
--- a/man/curs_scr_dump.3x
+++ b/man/curs_scr_dump.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 1998-2010,2017 Free Software Foundation, Inc.              *
+.\" 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  *
 .\" copy of this software and associated documentation files (the            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,75 +27,125 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_scr_dump.3x,v 1.11 2017/04/17 00:41:24 tom Exp $
-.TH curs_scr_dump 3X ""
-.na
-.hy 0
+.\" $Id: curs_scr_dump.3x,v 1.41 2024/03/23 20:41:15 tom Exp $
+.TH curs_scr_dump 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..

 .SH NAME
 .SH NAME

-\fBscr_dump\fR,
-\fBscr_restore\fR,
-\fBscr_init\fR,
-\fBscr_set\fR \- read (write) a \fBcurses\fR screen from (to) a file
-.ad
-.hy
+\fB\%scr_dump\fP,
+\fB\%scr_restore\fP,
+\fB\%scr_init\fP,
+\fB\%scr_set\fP \-
+read/write a \fIcurses\fR screen from/to a file

 .SH SYNOPSIS
 .SH SYNOPSIS

-\fB#include <curses.h>\fR
-.sp
-\fBint scr_dump(const char *filename);\fR
-.br
-\fBint scr_restore(const char *filename);\fR
-.br
-\fBint scr_init(const char *filename);\fR
-.br
-\fBint scr_set(const char *filename);\fR
-.br
-.SH DESCRIPTION
-The \fBscr_dump\fR routine dumps the current contents of the virtual screen
-to the file \fIfilename\fR.
+.nf
+\fB#include <curses.h>

 .PP
 .PP

-The \fBscr_restore\fR routine sets the virtual screen to the contents
-of \fIfilename\fR, which must have been written using \fBscr_dump\fR.  The next
-call to \fBdoupdate\fR restores the screen to the way it looked in the dump
-file.
+\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
+.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
+\fB\%scr_dump\fP writes to
+.I filename
+the contents of the virtual screen;
+see \fB\%curscr\fP(3X).
+.SS scr_restore
+\fB\%scr_restore\fP updates the virtual screen to contain the contents
+of
+.I filename
+(if it was validly written with \fB\%scr_dump\fP).
+No refresh is performed;
+after performing any further desired updates,
+call \fB\%doupdate\fP(3X) or similar.
+.SS scr_init
+\fB\%scr_init\fP reads
+.IR filename ,
+using it to initialize
+.I curses
+data structures describing the state of the terminal screen.
+If these data are valid,
+.I curses
+bases its next update of the screen on this information rather than
+clearing it and starting from scratch.

 .PP
 .PP

-The \fBscr_init\fR routine reads in the contents of \fIfilename\fR and uses
-them to initialize the \fBcurses\fR data structures about what the terminal
-currently has on its screen.  If the data is determined to be valid,
-\fBcurses\fR bases its next update of the screen on this information rather
-than clearing the screen and starting from scratch.  \fBscr_init\fR is used
-after \fBinitscr\fR or a \fBsystem\fR call to share
-the screen with another process which has done a \fBscr_dump\fR after its
-\fBendwin\fR(3X) call.  The data is declared invalid if the terminfo capabilities
-\fBrmcup\fR and \fBnrrmc\fR exist; also if the terminal has been written to
-since the preceding \fBscr_dump\fR call.
+The data fail the validity check
+.bP
+if the terminal employs
+.I \%term\%info
+capabilities
+.B \%exit_ca_mode
+.RB ( \%rmcup )
+or
+.B \%non_rev_rmcup
+.RB ( \%nrrmc )
+are defined,
+or
+.bP
+if
+.I curses
+knows that the terminal has been written to since the preceding
+\fB\%scr_dump\fP call.

 .PP
 .PP

-The \fBscr_set\fR routine is a combination of \fBscr_restore\fR and
-\fBscr_init\fR.  It tells the program that the information in \fIfilename\fR is
+\fB\%scr_init\fP could be used after \fB\%initscr\fP(3X) or
+\fB\%system\fP(3) to share the screen with another process that has
+done a \fBscr_dump\fP after \fB\%endwin\fP(3X).
+.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.
 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.

-.PP
-To read (write) a window from (to) a file, use the \fBgetwin\fR and
-\fBputwin\fR routines [see \fBcurs_util\fR(3X)].

 .SH RETURN VALUE
 .SH RETURN VALUE

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

 .PP
 .PP

-X/Open defines no error conditions.
+X/Open defines no failure conditions.

 In this implementation,
 In this implementation,

-each will return an error if the file cannot be opened.
+each function fails if it cannot open
+.IR filename .

 .SH NOTES
 .SH NOTES

-Note that \fBscr_init\fR, \fBscr_set\fR, and \fBscr_restore\fR may be macros.
+\fB\%scr_init\fP,
+\fB\%scr_set\fP,
+and
+\fB\%scr_restore\fP may be 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.
+.PP
+.\" SVID 4, p. 529
+SVr4 omitted the
+.I \%const
+qualifiers.

 .PP
 .PP

-The SVr4 docs merely say under \fBscr_init\fR 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 \fB\%scr_init\fP such that the dump data is
+also considered invalid \*(``if the time-stamp of the tty is old\*(''
+but does not define \*(``old\*(''.

 .SH SEE ALSO
 .SH SEE ALSO

-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_util\fR(3X),
-\fBscr_dump\fR(5),
-\fBsystem\fR(3)
+\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)