Debian Codegraph @

upstream/debian-unstable/man3/scr_dump.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_scr_dump.3x,v 1.55 2025/01/19 00:51:10 tom Exp $
31 .TH scr_dump 3NCURSES 2025-01-18 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%scr_dump\fP,
49 \fB\%scr_restore\fP,
50 \fB\%scr_init\fP,
51 \fB\%scr_set\fP \-
52 read/write a \fIcurses\fR screen from/to a file
53 .SH SYNOPSIS
54 .nf
55 \fB#include <curses.h>
56 .PP
57 \fBint scr_dump(const char * \fIfilename\fP);
58 \fBint scr_restore(const char * \fIfilename\fP);
59 \fBint scr_init(const char * \fIfilename\fP);
60 \fBint scr_set(const char * \fIfilename\fP);
61 .fi
62 .SH DESCRIPTION
63 .I curses
64 provides applications the ability to write the contents of the screen
65 to a file and read them back.
66 To read/write a window
67 (rather than the whole screen)
68 from/to a file,
69 use \fB\%getwin\fP(3NCURSES) and
70 \fB\%putwin\fP(3NCURSES),
71 respectively.
72 .SS scr_dump
73 .B \%scr_dump
74 writes to
75 .I filename
76 the contents of the virtual screen;
77 see \fB\%curscr\fP(3NCURSES).
78 .SS scr_restore
79 .B \%scr_restore
80 updates the virtual screen to match the contents of
81 .I filename
82 (if validly written with
83 .BR \%scr_dump ")."
84 .I curses
85 does not perform a refresh;
86 after making any desired changes,
87 call \fB\%doupdate\fP(3NCURSES) or similar.
88 .SS scr_init
89 .B \%scr_init
90 reads
91 .IR filename ","
92 using it to initialize
93 .I curses
94 data structures describing the state of the terminal screen.
95 .I curses
96 then,
97 if it decides the terminal state is valid,
98 bases its next update of the screen on this information rather than
99 clearing it and starting from scratch.
100 .PP
101 .I curses
102 regards the terminal as in an invalid state for computation of updates
103 based on the contents of
104 .I filename
105 if
106 .bP
107 .I curses
108 knows that the terminal has been written to since the preceding
109 .B \%scr_dump
110 call,
111 or
112 .bP
113 the terminal type supports the
114 .I \%term\%info
115 capabilities
116 .B \%exit_ca_mode
117 .RB \%( rmcup )
118 or
119 .B \%non_rev_rmcup
120 .RB \%( nrrmc ).
121 .PP
122 Either of the foregoing conditions means that
123 .I curses
124 cannot assume that the terminal's contents
125 match their representation in
126 .IR filename "."
127 The former is due to terminal features
128 (such as \fI\%xterm\fP(1)'s \*(``alternate screen\*('')
129 that couple cursor-positioning mode with a local cache of screen
130 contents.
131 .I curses
132 cannot know whether the terminal is displaying from that local cache
133 at the time the application calls
134 .BR \%scr_init ","
135 so it makes a pessimistic assumption that a full redraw is required;
136 see subsection \*(``Cursor Motions\*('' of \fB\%terminfo\fP(5).
137 .PP
138 .B \%scr_init
139 could be used after \fB\%initscr\fP(3NCURSES) or \fI\%system\fP(3) to share
140 the screen with another process that has done a
141 .B \%scr_dump
142 after \fB\%endwin\fP(3NCURSES).
143 An application that supports suspending its state on exit and subsequent
144 resumption upon later execution might use
145 .B \%scr_dump
146 and
147 .B \%scr_init
148 thus.
149 .SS scr_set
150 .B \%scr_set
151 combines
152 .B \%scr_restore
153 and
154 .BR \%scr_init ","
155 synchronizing the contents of
156 .I filename
157 with the virtual screen.
158 It can be regarded as a screen inheritance function;
159 consider a real-time screen-sharing application.
160 .SH RETURN VALUE
161 These functions return
162 .B OK
163 on success and
164 .B ERR
165 on failure.
166 .PP
167 In
168 .IR \%ncurses ","
169 each function returns
170 .B ERR
171 if it cannot open
172 .IR filename "."
173 .BR \%scr_init ","
174 .BR \%scr_restore ","
175 and
176 .B \%scr_set
177 return
178 .B ERR
179 if the contents of
180 .I filename
181 are invalid.
182 .SH NOTES
183 .BR \%scr_init ","
184 .BR \%scr_restore ","
185 and
186 .B \%scr_set
187 may be implemented as macros.
188 .SH PORTABILITY
189 X/Open Curses Issue\ 4 describes these functions.
190 It specifies no error conditions for them.
191 .\" Unusually, SVID 4 explicitly indicated "OK" as a possible return
192 .\" value, rather than the "integer other than ERR" refrain (p. 529).
193 .PP
194 .\" SVID 4, p. 529
195 SVr4 omitted the
196 .I \%const
197 qualifiers.
198 .PP
199 SVr4 documentation describes
200 .I \%scr_init
201 such that the dump data is also considered invalid
202 \*(``if the time-stamp of the tty is old\*(''
203 but does not define \*(``old\*(''.
204 .PP
205 As of 2024,
206 .I \%PDCurses
207 provides these functions.
208 NetBSD
209 .I curses
210 does not.
211 .PP
212 Other implementations of
213 .I curses
214 store the window in binary form,
215 which makes the dump dependent
216 upon the
217 .I curses
218 library's internal data structures.
219 .I \%ncurses
220 avoids this drawback by storing the dump in textual form,
221 allowing more flexible use of the data.
222 For instance,
223 the
224 .I \%scr_restore
225 of SVr4
226 .I curses
227 requires that the dumped window have the same dimensions
228 as the restored window.
229 .I \%ncurses
230 uses its
231 \fB\%wresize\fP(3NCURSES)
232 extension
233 to adjust the restored window size.
234 .SH HISTORY
235 SVr3 (1987) introduced
236 .IR \%scr_dump ","
237 .IR \%scr_init ","
238 and
239 .IR \%scr_restore "."
240 SVr3.1 added
241 .IR \%scr_set "."
242 .SH SEE ALSO
243 .na
244 \fB\%ncurses\fP(3NCURSES),
245 \fB\%initscr\fP(3NCURSES),
246 \fB\%refresh\fP(3NCURSES),
247 \fB\%util\fP(3NCURSES),
248 \fB\%system\fP(3),
249 \fB\%scr_dump\fP(5),
250 \fB\%terminfo\fP(5),
251 \fB\%wresize\fP(3NCURSES)
252 .ad