ncurses 6.0 - patch 20171118
[ncurses.git] / doc / html / man / scr_dump.5.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 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   * @Id: scr_dump.5,v 1.11 2017/11/18 23:51:59 tom Exp @
30 -->
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
32 <HTML>
33 <HEAD>
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>scr_dump 5</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 </HEAD>
40 <BODY>
41 <H1 class="no-header">scr_dump 5</H1>
42 <PRE>
43 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>                                                        <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
44
45
46
47
48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
49        scr_dump - format of curses screen-dumps.
50
51
52 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
53        <STRONG>scr_dump</STRONG>
54
55
56 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
57        The  curses library provides applications with the ability to write the
58        contents of a window to an external file using <STRONG>scr_dump</STRONG> or <STRONG>putwin</STRONG>,  and
59        read it back using <STRONG>scr_restore</STRONG> or <STRONG>getwin</STRONG>.
60
61        The  <STRONG>putwin</STRONG>  and  <STRONG>getwin</STRONG>  functions  do  the  work;  while <STRONG>scr_dump</STRONG> and
62        <STRONG>scr_restore</STRONG> conveniently save and restore the whole screen, i.e.,  <STRONG>std-</STRONG>
63        <STRONG>scr</STRONG>.
64
65
66 </PRE><H3><a name="h3-ncurses6">ncurses6</a></H3><PRE>
67        A  longstanding implementation of screen-dump was revised with ncurses6
68        to remedy problems with the earlier approach:
69
70        <STRONG>o</STRONG>   A "magic number" is written to the  beginning  of  the  dump  file,
71            allowing  applications  (such  as <STRONG>file(1)</STRONG>) to recognize curses dump
72            files.
73
74            Because ncurses6 uses a new format, that requires a new magic  num-
75            ber  was  unused  by  other  applications.   This 16-bit number was
76            unused:
77
78                0x8888 (octal "\210\210")
79
80            but to be more certain, this 32-bit number was chosen:
81
82                0x88888888 (octal "\210\210\210\210")
83
84            This is the pattern submitted to the maintainers of the  <STRONG>file</STRONG>  pro-
85            gram:
86
87                #
88                # ncurses5 (and before) did not use a magic number,
89                # making screen dumps "data".
90                #
91                # ncurses6 (2015) uses this format, ignoring byte-order
92                0    string    \210\210\210\210ncurses    ncurses6 screen image
93                #
94
95        <STRONG>o</STRONG>   The screen dumps are written in textual form, so that internal data
96            sizes are not directly related to the dump-format, and enabling the
97            library  to  read dumps from either narrow- or wide-character- con-
98            figurations.
99
100            The  <EM>narrow</EM>  library  configuration  holds  characters  and   video
101            attributes  in  a  32-bit  <STRONG>chtype</STRONG>, while the <EM>wide-character</EM> library
102            stores this information in the <STRONG>cchar_t</STRONG>  structure,  which  is  much
103            larger than 32-bits.
104
105        <STRONG>o</STRONG>   It is possible to read a screen dump into a terminal with a differ-
106            ent screen-size, because the library truncates or fills the  screen
107            as necessary.
108
109        <STRONG>o</STRONG>   The ncurses6 <STRONG>getwin</STRONG> reads the legacy screen dumps from ncurses5.
110
111
112 </PRE><H3><a name="h3-ncurses5-_legacy_">ncurses5 (legacy)</a></H3><PRE>
113        The screen-dump feature was added to ncurses in June 1995.  While there
114        were fixes and improvements in succeeding years, the basic  scheme  was
115        unchanged:
116
117        <STRONG>o</STRONG>   The <STRONG>WINDOW</STRONG> structure was written in binary form.
118
119        <STRONG>o</STRONG>   The <STRONG>WINDOW</STRONG> structure refers to lines of data, which were written as
120            an array of binary data following the <STRONG>WINDOW</STRONG>.
121
122        <STRONG>o</STRONG>   When <STRONG>getwin</STRONG> restored the window, it would  keep  track  of  offsets
123            into  the  array of line-data and adjust the <STRONG>WINDOW</STRONG> structure which
124            was read back into memory.
125
126        This is similar to Unix SystemV, but does not write a "magic number" to
127        identify the file format.
128
129
130 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
131        There  is  no  standard  format for <STRONG>putwin</STRONG>.  This section gives a brief
132        description of the existing formats.
133
134
135 </PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE>
136        Refer to <EM>X/Open</EM> <EM>Curses,</EM> <EM>Issue</EM> <EM>7</EM> (2009).
137
138        X/Open's documentation for <EM>enhanced</EM> <EM>curses</EM> says only:
139
140           The <EM>getwin(</EM> <EM>)</EM> function reads window-related data stored in the  file
141           by  <EM>putwin(</EM> <EM>)</EM>.  The function then creates and initializes a new win-
142           dow using that data.
143
144           The <EM>putwin(</EM> <EM>)</EM> function writes all data associated with <EM>win</EM> into  the
145           <EM>stdio</EM>  stream  to  which  <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>.
146           This information can be retrieved later using <EM>getwin(</EM> <EM>)</EM>.
147
148        In the mid-1990s when the X/Open Curses  document  was  written,  there
149        were  still  systems  using older, less capable curses libraries (aside
150        from the BSD curses library which was not relevant to X/Open because it
151        did not meet the criteria for <EM>base</EM> <EM>curses</EM>).  The document explained the
152        term "enhanced" as follows:
153
154           <STRONG>o</STRONG>   Shading is used to identify  <EM>X/Open</EM>  <EM>Enhanced</EM>  <EM>Curses</EM>  material,
155               relating to interfaces included to provide enhanced capabilities
156               for applications originally written to be  compiled  on  systems
157               based  on  the  UNIX  operating  system. Therefore, the features
158               described may not be present on systems that conform to <STRONG>XPG4</STRONG>  <STRONG>or</STRONG>
159               <STRONG>to</STRONG>  <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>.  The relevant reference pages may pro-
160               vide additional or more specific portability warnings about  use
161               of the material.
162
163        In  the foregoing, emphasis was added to <STRONG>unspecified</STRONG> <STRONG>format</STRONG> and to <STRONG>XPG4</STRONG>
164        <STRONG>or</STRONG> <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>, for clarity.
165
166
167 </PRE><H3><a name="h3-Unix-SystemV">Unix SystemV</a></H3><PRE>
168        Unix SystemV curses identified the file format by writing a "magic num-
169        ber"  at  the  beginning of the dump.  The <STRONG>WINDOW</STRONG> data and the lines of
170        text follow, all in binary form.
171
172        The Solaris curses source has these definitions:
173
174            /* terminfo magic number */
175            #define MAGNUM  0432
176
177            /* curses screen dump magic number */
178            #define SVR2_DUMP_MAGIC_NUMBER  0433
179            #define SVR3_DUMP_MAGIC_NUMBER  0434
180
181        That is, the feature was likely introduced in SVr2 (1984), and improved
182        in SVr3 (1987).  The Solaris curses source has no magic number for SVr4
183        (1989).  Other operating systems (AIX and  HPUX)  use  a  magic  number
184        which would correspond to this definition:
185
186            /* curses screen dump magic number */
187            #define SVR4_DUMP_MAGIC_NUMBER  0435
188
189        That  octal number in bytes is 001, 035.  Because most Unix vendors use
190        big-endian hardware, the magic number is written  with  the  high-order
191        byte first, e.g.,
192
193             01 35
194
195        After  the magic number, the <STRONG>WINDOW</STRONG> structure and line-data are written
196        in binary format.  While the magic number used by the Unix systems  can
197        be seen using <STRONG>od(1)</STRONG>, none of the Unix systems documents the format used
198        for screen-dumps.
199
200        The Unix systems do not use identical formats.  While collecting infor-
201        mation  for  for this manual page, the <EM>savescreen</EM> test-program produced
202        dumps of different size (all on 64-bit hardware, on 40x80 screens):
203
204        <STRONG>o</STRONG>   AIX (51817 bytes)
205
206        <STRONG>o</STRONG>   HPUX (90093 bytes)
207
208        <STRONG>o</STRONG>   Solaris 10 (13273 bytes)
209
210        <STRONG>o</STRONG>   ncurses5 (12888 bytes)
211
212
213 </PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE>
214        As noted above, Solaris curses has no  magic  number  corresponding  to
215        SVr4  curses.  This is odd since Solaris was the first operating system
216        to pass the SVr4 guidelines.  Solaris has two versions of curses:
217
218        <STRONG>o</STRONG>   The default curses library uses the SVr3 magic number.
219
220        <STRONG>o</STRONG>   There is an alternate curses library in  <STRONG>/usr/xpg4</STRONG>.   This  uses  a
221            textual format with no magic number.
222
223            According  to the copyright notice, the <EM>xpg4</EM> Solaris curses library
224            was developed by MKS (Mortice Kern Systems) from 1990 to 1995.
225
226            Like ncurses6, there is  a  file-header  with  parameters.   Unlike
227            ncurses6,  the  contents  of the window are written piecemeal, with
228            coordinates and attributes for each chunk of text rather than writ-
229            ing the whole window from top to bottom.
230
231
232 </PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE>
233        PDCurses  added  support  for screen dumps in version 2.7 (2005).  Like
234        Unix SystemV and ncurses5, it writes the <STRONG>WINDOW</STRONG>  structure  in  binary,
235        but begins the file with its three-byte identifier "PDC", followed by a
236        one-byte version, e.g.,
237
238                 "PDC\001"
239
240
241 </PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE>
242        As  of  April  2017,  NetBSD  curses  does  not  support  <STRONG>scr_dump</STRONG>  and
243        <STRONG>scr_restore</STRONG> (or <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>), although it has <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>.
244
245        Like  ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful
246        magic number.  It writes
247
248        <STRONG>o</STRONG>   the curses shared library major and minor versions as the first two
249            bytes (e.g., 7 and 1),
250
251        <STRONG>o</STRONG>   followed by a binary dump of the <STRONG>WINDOW</STRONG>,
252
253        <STRONG>o</STRONG>   some  data  for wide-characters referenced by the <STRONG>WINDOW</STRONG> structure,
254            and
255
256        <STRONG>o</STRONG>   finally, lines as done by other implementations.
257
258
259 </PRE><H2><a name="h2-EXAMPLE">EXAMPLE</a></H2><PRE>
260        Given a simple program which writes text to the  screen  (and  for  the
261        sake of example, limiting the screen-size to 10x20):
262
263            #include &lt;curses.h&gt;
264
265            int
266            main(void)
267            {
268                putenv("LINES=10");
269                putenv("COLUMNS=20");
270                initscr();
271                start_color();
272                init_pair(1, COLOR_WHITE, COLOR_BLUE);
273                init_pair(2, COLOR_RED, COLOR_BLACK);
274                bkgd(<STRONG>COLOR_PAIR(1)</STRONG>);
275                move(4, 5);
276                attron(A_BOLD);
277                addstr("Hello");
278                move(5, 5);
279                attroff(A_BOLD);
280                attrset(A_REVERSE | <STRONG>COLOR_PAIR(2)</STRONG>);
281                addstr("World!");
282                refresh();
283                scr_dump("foo.out");
284                endwin();
285                return 0;
286            }
287
288        When run using ncurses6, the output looks like this:
289
290            \210\210\210\210ncurses 6.0.20170415
291            _cury=5
292            _curx=11
293            _maxy=9
294            _maxx=19
295            _flags=14
296            _attrs=\{REVERSE|C2}
297            flag=_idcok
298            _delay=-1
299            _regbottom=9
300            _bkgrnd=\{NORMAL|C1}\s
301            rows:
302            1:\{NORMAL|C1}\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
303            2:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
304            3:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
305            4:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
306            5:\s\s\s\s\s\{BOLD}Hello\{NORMAL}\s\s\s\s\s\s\s\s\s\s
307            6:\s\s\s\s\s\{REVERSE|C2}World!\{NORMAL|C1}\s\s\s\s\s\s\s\s\s
308            7:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
309            8:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
310            9:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
311            10:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
312
313        The first four octal escapes are actually nonprinting characters, while
314        the remainder of the file is printable text.  You may notice:
315
316        <STRONG>o</STRONG>   The actual color pair values are not written to the file.
317
318        <STRONG>o</STRONG>   All characters are shown in printable  form;  spaces  are  "\s"  to
319            ensure they are not overlooked.
320
321        <STRONG>o</STRONG>   Attributes  are  written  in escaped curly braces, e.g., "\{BOLD}",
322            and may include a color-pair (C1 or C2 in this example).
323
324        <STRONG>o</STRONG>   The parameters in the header are  written  out  only  if  they  are
325            nonzero.  When reading back, order does not matter.
326
327        Running the same program with Solaris <EM>xpg4</EM> curses gives this dump:
328
329            MAX=10,20
330            BEG=0,0
331            SCROLL=0,10
332            VMIN=1
333            VTIME=0
334            FLAGS=0x1000
335            FG=0,0
336            BG=0,0,
337            0,0,0,1,
338            0,19,0,0,
339            1,0,0,1,
340            1,19,0,0,
341            2,0,0,1,
342            2,19,0,0,
343            3,0,0,1,
344            3,19,0,0,
345            4,0,0,1,
346            4,5,0x20,0,Hello
347            4,10,0,1,
348            4,19,0,0,
349            5,0,0,1,
350            5,5,0x4,2,World!
351            5,11,0,1,
352            5,19,0,0,
353            6,0,0,1,
354            6,19,0,0,
355            7,0,0,1,
356            7,19,0,0,
357            8,0,0,1,
358            8,19,0,0,
359            9,0,0,1,
360            9,19,0,0,
361            CUR=11,5
362
363        Solaris  <STRONG>getwin</STRONG>  requires  that  all parameters are present, and in the
364        same order.  The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG>  (back
365        color erase) capability, and does not color the window background.
366
367        On  the  other  hand, the SVr4 curses library does know about the back-
368        ground color.  However, its screen dumps are in binary.   Here  is  the
369        corresponding dump (using "od -t x1"):
370
371            0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
372            0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
373            0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
374            0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
375            0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
376            0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
377            *
378            0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
379            0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
380            0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
381            *
382            0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
383            0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
384            0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
385            0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
386            *
387            0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
388            0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
389            0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
390            0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
391            *
392            0002371
393
394
395 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
396        <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>.
397
398
399 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
400        Thomas E. Dickey
401        extended screen-dump format for ncurses 6.0 (2015)
402
403        Eric S. Raymond
404        screen dump feature in ncurses 1.9.2d (1995)
405
406
407
408                                                                    <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
409 </PRE>
410 <div class="nav">
411 <ul>
412 <li><a href="#h2-NAME">NAME</a></li>
413 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
414 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
415 <ul>
416 <li><a href="#h3-ncurses6">ncurses6</a></li>
417 <li><a href="#h3-ncurses5-_legacy_">ncurses5 (legacy)</a></li>
418 </ul>
419 </li>
420 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
421 <ul>
422 <li><a href="#h3-X_Open-Curses">X/Open Curses</a></li>
423 <li><a href="#h3-Unix-SystemV">Unix SystemV</a></li>
424 <li><a href="#h3-Solaris">Solaris</a></li>
425 <li><a href="#h3-PDCurses">PDCurses</a></li>
426 <li><a href="#h3-NetBSD">NetBSD</a></li>
427 </ul>
428 </li>
429 <li><a href="#h2-EXAMPLE">EXAMPLE</a></li>
430 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
431 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
432 </ul>
433 </div>
434 </BODY>
435 </HTML>