1scr_dump(5) File Formats Manual scr_dump(5)
2
6 scr_dump - format of curses screen-dumps.
7
9 scr_dump
10
12 The curses library provides applications with the ability to write the
13 contents of a window to an external file using scr_dump or putwin, and
14 read it back using scr_restore or getwin.
15 The putwin and getwin functions do the work; while scr_dump and scr_re‐
17 store conveniently save and restore the whole screen, i.e., stdscr.
18 ncurses6
20 A longstanding implementation of screen-dump was revised with ncurses6
21 to remedy problems with the earlier approach:
22 • A “magic number” is written to the beginning of the dump file, al‐
24 lowing applications (such as file(1)) to recognize curses dump
25 files.
26 Because ncurses6 uses a new format, that requires a new magic num‐
28 ber was unused by other applications. This 16-bit number was un‐
29 used:
30 0x8888 (octal “\210\210”)
32 but to be more certain, this 32-bit number was chosen:
34 0x88888888 (octal “\210\210\210\210”)
36 This is the pattern submitted to the maintainers of the file pro‐
38 gram:
39 #
41 # ncurses5 (and before) did not use a magic number,
42 # making screen dumps "data".
43 #
44 # ncurses6 (2015) uses this format, ignoring byte-order
45 0 string \210\210\210\210ncurses ncurses6 screen image
46 #
47 • The screen dumps are written in textual form, so that internal data
49 sizes are not directly related to the dump-format, and enabling the
50 library to read dumps from either narrow- or wide-character- con‐
51 figurations.
52 The narrow library configuration holds characters and video at‐
54 tributes in a 32-bit chtype, while the wide-character library
55 stores this information in the cchar_t structure, which is much
56 larger than 32-bits.
57 • It is possible to read a screen dump into a terminal with a differ‐
59 ent screen-size, because the library truncates or fills the screen
60 as necessary.
61 • The ncurses6 getwin reads the legacy screen dumps from ncurses5.
63 ncurses5 (legacy)
65 The screen-dump feature was added to ncurses in June 1995. While there
66 were fixes and improvements in succeeding years, the basic scheme was
67 unchanged:
68 • The WINDOW structure was written in binary form.
70 • The WINDOW structure refers to lines of data, which were written as
72 an array of binary data following the WINDOW.
73 • When getwin restored the window, it would keep track of offsets
75 into the array of line-data and adjust the WINDOW structure which
76 was read back into memory.
77 This is similar to Unix SystemV, but does not write a “magic number” to
79 identify the file format.
80
82 There is no standard format for putwin. This section gives a brief de‐
83 scription of the existing formats.
84 X/Open Curses
86 Refer to X/Open Curses, Issue 7 (2009).
87 X/Open's documentation for enhanced curses says only:
89 The getwin( ) function reads window-related data stored in the file
91 by putwin( ). The function then creates and initializes a new win‐
92 dow using that data.
93 The putwin( ) function writes all data associated with win into the
95 stdio(3) stream to which filep points, using an unspecified format.
96 This information can be retrieved later using getwin( ).
97 In the mid-1990s when the X/Open Curses document was written, there
99 were still systems using older, less capable curses libraries (aside
100 from the BSD curses library which was not relevant to X/Open because it
101 did not meet the criteria for base curses). The document explained the
102 term “enhanced” as follows:
103 • Shading is used to identify X/Open Enhanced Curses material, re‐
105 lating to interfaces included to provide enhanced capabilities
106 for applications originally written to be compiled on systems
107 based on the UNIX operating system. Therefore, the features de‐
108 scribed may not be present on systems that conform to XPG4 or to
109 earlier XPG releases. The relevant reference pages may provide
110 additional or more specific portability warnings about use of
111 the material.
112 In the foregoing, emphasis was added to unspecified format and to XPG4
114 or to earlier XPG releases, for clarity.
115 Unix SystemV
117 Unix SystemV curses identified the file format by writing a “magic num‐
118 ber” at the beginning of the dump. The WINDOW data and the lines of
119 text follow, all in binary form.
120 The Solaris curses source has these definitions:
122 /* terminfo magic number */
124 #define MAGNUM 0432
125 /* curses screen dump magic number */
127 #define SVR2_DUMP_MAGIC_NUMBER 0433
128 #define SVR3_DUMP_MAGIC_NUMBER 0434
129 That is, the feature was likely introduced in SVr2 (1984), and improved
131 in SVr3 (1987). The Solaris curses source has no magic number for SVr4
132 (1989). Other operating systems (AIX and HPUX) use a magic number
133 which would correspond to this definition:
134 /* curses screen dump magic number */
136 #define SVR4_DUMP_MAGIC_NUMBER 0435
137 That octal number in bytes is 001, 035. Because most Unix vendors use
139 big-endian hardware, the magic number is written with the high-order
140 byte first, e.g.,
141 01 35
143 After the magic number, the WINDOW structure and line-data are written
145 in binary format. While the magic number used by the Unix systems can
146 be seen using od(1), none of the Unix systems documents the format used
147 for screen-dumps.
148 The Unix systems do not use identical formats. While collecting infor‐
150 mation for for this manual page, the savescreen test-program produced
151 dumps of different size (all on 64-bit hardware, on 40x80 screens):
152 • AIX (51817 bytes)
154 • HPUX (90093 bytes)
156 • Solaris 10 (13273 bytes)
158 • ncurses5 (12888 bytes)
160 Solaris
162 As noted above, Solaris curses has no magic number corresponding to
163 SVr4 curses. This is odd since Solaris was the first operating system
164 to pass the SVr4 guidelines. Solaris has two versions of curses:
165 • The default curses library uses the SVr3 magic number.
167 • There is an alternate curses library in /usr/xpg4. This uses a
169 textual format with no magic number.
170 According to the copyright notice, the xpg4 Solaris curses library
172 was developed by MKS (Mortice Kern Systems) from 1990 to 1995.
173 Like ncurses6, there is a file-header with parameters. Unlike
175 ncurses6, the contents of the window are written piecemeal, with
176 coordinates and attributes for each chunk of text rather than writ‐
177 ing the whole window from top to bottom.
178 PDCurses
180 PDCurses added support for screen dumps in version 2.7 (2005). Like
181 Unix SystemV and ncurses5, it writes the WINDOW structure in binary,
182 but begins the file with its three-byte identifier “PDC”, followed by a
183 one-byte version, e.g.,
184 “PDC\001”
186 NetBSD
188 As of April 2017, NetBSD curses does not support scr_dump and scr_re‐
189 store (or scr_init, scr_set), although it has putwin and getwin.
190 Like ncurses5, NetBSD putwin does not identify its dumps with a useful
192 magic number. It writes
193 • the curses shared library major and minor versions as the first two
195 bytes (e.g., 7 and 1),
196 • followed by a binary dump of the WINDOW,
198 • some data for wide-characters referenced by the WINDOW structure,
200 and
201 • finally, lines as done by other implementations.
203
205 Given a simple program which writes text to the screen (and for the
206 sake of example, limiting the screen-size to 10x20):
207 #include <curses.h>
209 int
211 main(void)
212 {
213 putenv("LINES=10");
214 putenv("COLUMNS=20");
215 initscr();
216 start_color();
217 init_pair(1, COLOR_WHITE, COLOR_BLUE);
218 init_pair(2, COLOR_RED, COLOR_BLACK);
219 bkgd(COLOR_PAIR(1));
220 move(4, 5);
221 attron(A_BOLD);
222 addstr("Hello");
223 move(5, 5);
224 attroff(A_BOLD);
225 attrset(A_REVERSE | COLOR_PAIR(2));
226 addstr("World!");
227 refresh();
228 scr_dump("foo.out");
229 endwin();
230 return 0;
231 }
232 When run using ncurses6, the output looks like this:
234 \210\210\210\210ncurses 6.0.20170415
236 _cury=5
237 _curx=11
238 _maxy=9
239 _maxx=19
240 _flags=14
241 _attrs=\{REVERSE|C2}
242 flag=_idcok
243 _delay=-1
244 _regbottom=9
245 _bkgrnd=\{NORMAL|C1}\s
246 rows:
247 1:\{NORMAL|C1}\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
248 2:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
249 3:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
250 4:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
251 5:\s\s\s\s\s\{BOLD}Hello\{NORMAL}\s\s\s\s\s\s\s\s\s\s
252 6:\s\s\s\s\s\{REVERSE|C2}World!\{NORMAL|C1}\s\s\s\s\s\s\s\s\s
253 7:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
254 8:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
255 9:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
256 10:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
257 The first four octal escapes are actually nonprinting characters, while
259 the remainder of the file is printable text. You may notice:
260 • The actual color pair values are not written to the file.
262 • All characters are shown in printable form; spaces are “\s” to en‐
264 sure they are not overlooked.
265 • Attributes are written in escaped curly braces, e.g., “\{BOLD}”,
267 and may include a color-pair (C1 or C2 in this example).
268 • The parameters in the header are written out only if they are non‐
270 zero. When reading back, order does not matter.
271 Running the same program with Solaris xpg4 curses gives this dump:
273 MAX=10,20
275 BEG=0,0
276 SCROLL=0,10
277 VMIN=1
278 VTIME=0
279 FLAGS=0x1000
280 FG=0,0
281 BG=0,0,
282 0,0,0,1,
283 0,19,0,0,
284 1,0,0,1,
285 1,19,0,0,
286 2,0,0,1,
287 2,19,0,0,
288 3,0,0,1,
289 3,19,0,0,
290 4,0,0,1,
291 4,5,0x20,0,Hello
292 4,10,0,1,
293 4,19,0,0,
294 5,0,0,1,
295 5,5,0x4,2,World!
296 5,11,0,1,
297 5,19,0,0,
298 6,0,0,1,
299 6,19,0,0,
300 7,0,0,1,
301 7,19,0,0,
302 8,0,0,1,
303 8,19,0,0,
304 9,0,0,1,
305 9,19,0,0,
306 CUR=11,5
307 Solaris getwin requires that all parameters are present, and in the
309 same order. The xpg4 curses library does not know about the bce (back
310 color erase) capability, and does not color the window background.
311 On the other hand, the SVr4 curses library does know about the back‐
313 ground color. However, its screen dumps are in binary. Here is the
314 corresponding dump (using “od -t x1”):
315 0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
317 0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
318 0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
319 0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
320 0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
321 0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
322 *
323 0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
324 0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
325 0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
326 *
327 0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
328 0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
329 0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
330 0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
331 *
332 0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
333 0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
334 0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
335 0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
336 *
337 0002371
338
340 curs_scr_dump(3X), curs_util(3X).
341
343 Thomas E. Dickey
344 extended screen-dump format for ncurses 6.0 (2015)
345 Eric S. Raymond
347 screen dump feature in ncurses 1.9.2d (1995)
348 scr_dump(5)