X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_scr_dump.3x;h=5f14a2287268818ad2915351956c5637d4100e63;hb=HEAD;hp=66603f1a13c53bee8171932d40355de152fb6afd;hpb=122d3739b3c11c83decc625d53f26fff6e825710;p=ncurses.git diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x index 66603f1a..ba9881e5 100644 --- 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 * @@ -27,8 +27,8 @@ .\" 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 @@ -54,65 +54,167 @@ read/write a \fIcurses\fR screen from/to a file .nf \fB#include .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 +.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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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), -\fB\%scr_dump\fP(5) +\fB\%scr_dump\fP(5), +\fB\%terminfo\fP(5)