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