X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_scr_dump.3x;h=229acefd39d951270ed0b33cd318df352a9aec4a;hp=3a846ccf5b0357fbb8e12e500b90c9d7b17eb2b3;hb=HEAD;hpb=a8e3f06ac309504143cd56ac9ec55889bfdf4914 diff --git a/man/curs_scr_dump.3x b/man/curs_scr_dump.3x index 3a846ccf..5f14a228 100644 --- 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 * @@ -26,75 +27,126 @@ .\" 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.43 2024/04/20 18:54:36 tom Exp $ +.TH curs_scr_dump 3X 2024-04-20 "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 -\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 -\fB#include \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 .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 -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 -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. -.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 -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 -X/Open defines no error conditions. +X/Open defines no failure conditions. 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 -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 -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 -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 -\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)