--- /dev/null
+<!--
+ ****************************************************************************
+ * Copyright (c) 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 *
+ * "Software"), to deal in the Software without restriction, including *
+ * without limitation the rights to use, copy, modify, merge, publish, *
+ * distribute, distribute with modifications, sublicense, and/or sell *
+ * copies of the Software, and to permit persons to whom the Software is *
+ * furnished to do so, subject to the following conditions: *
+ * *
+ * The above copyright notice and this permission notice shall be included *
+ * in all copies or substantial portions of the Software. *
+ * *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+ * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+ * *
+ * Except as contained in this notice, the name(s) of the above copyright *
+ * holders shall not be used in advertising or otherwise to promote the *
+ * sale, use or other dealings in this Software without prior written *
+ * authorization. *
+ ****************************************************************************
+ * @Id: scr_dump.5,v 1.9 2017/04/22 18:44:25 tom Exp @
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<HTML>
+<HEAD>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
+<TITLE>scr_dump 5</TITLE>
+<link rev=made href="mailto:bug-ncurses@gnu.org">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+</HEAD>
+<BODY>
+<H1 class="no-header">scr_dump 5</H1>
+<PRE>
+<STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
+
+
+
+
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
+ scr_dump - format of curses screen-dumps.
+
+
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+ <STRONG>scr_dump</STRONG>
+
+
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ The curses library provides applications with the ability
+ to write the contents of a window to an external file
+ using <STRONG>scr_dump</STRONG> or <STRONG>putwin</STRONG>, and read it back using
+ <STRONG>scr_restore</STRONG> or <STRONG>getwin</STRONG>.
+
+ The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions do the work; while
+ <STRONG>scr_dump</STRONG> and <STRONG>scr_restore</STRONG> conveniently save and restore the
+ whole screen, i.e., <STRONG>stdscr</STRONG>.
+
+
+</PRE><H3><a name="h3-ncurses6">ncurses6</a></H3><PRE>
+ A longstanding implementation of screen-dump was revised
+ with ncurses6 to remedy problems with the earlier
+ approach:
+
+ <STRONG>o</STRONG> A "magic number" is written to the beginning of the
+ dump file, allowing applications (such as <STRONG>file(1)</STRONG>) to
+ recognize curses dump files.
+
+ Because ncurses6 uses a new format, that requires a
+ new magic number was unused by other applications.
+ This 16-bit number was unused:
+
+ 0x8888 (octal "\210\210")
+
+ but to be more certain, this 32-bit number was chosen:
+
+ 0x88888888 (octal "\210\210\210\210")
+
+ This is the pattern submitted to the maintainers of
+ the <STRONG>file</STRONG> program:
+
+ #
+ # ncurses5 (and before) did not use a magic number,
+ # making screen dumps "data".
+ #
+ # ncurses6 (2015) uses this format, ignoring byte-order
+ 0 string \210\210\210\210ncurses ncurses6 screen image
+ #
+
+ <STRONG>o</STRONG> The screen dumps are written in textual form, so that
+ internal data sizes are not directly related to the
+ dump-format, and enabling the library to read dumps
+ from either narrow- or wide-character- configurations.
+
+ The <EM>narrow</EM> library configuration holds characters and
+ video attributes in a 32-bit <STRONG>chtype</STRONG>, while the <EM>wide-</EM>
+ <EM>character</EM> library stores this information in the
+ <STRONG>cchar_t</STRONG> structure, which is much larger than 32-bits.
+
+ <STRONG>o</STRONG> It is possible to read a screen dump into a terminal
+ with a different screen-size, because the library
+ truncates or fills the screen as necessary.
+
+ <STRONG>o</STRONG> The ncurses6 <STRONG>getwin</STRONG> reads the legacy screen dumps from
+ ncurses5.
+
+
+</PRE><H3><a name="h3-ncurses5-_legacy_">ncurses5 (legacy)</a></H3><PRE>
+ The screen-dump feature was added to ncurses in June 1995.
+ While there were fixes and improvements in succeeding
+ years, the basic scheme was unchanged:
+
+ <STRONG>o</STRONG> The <STRONG>WINDOW</STRONG> structure was written in binary form.
+
+ <STRONG>o</STRONG> The <STRONG>WINDOW</STRONG> structure refers to lines of data, which
+ were written as an array of binary data following the
+ <STRONG>WINDOW</STRONG>.
+
+ <STRONG>o</STRONG> When <STRONG>getwin</STRONG> restored the window, it would keep track
+ of offsets into the array of line-data and adjust the
+ <STRONG>WINDOW</STRONG> structure which was read back into memory.
+
+ This is similar to Unix SystemV, but does not write a
+ "magic number" to identify the file format.
+
+
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ There is no standard format for <STRONG>putwin</STRONG>. This section
+ gives a brief description of the existing formats.
+
+
+</PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE>
+ Refer to <EM>X/Open</EM> <EM>Curses,</EM> <EM>Issue</EM> <EM>7</EM> (2009).
+
+ X/Open's documentation for <EM>enhanced</EM> <EM>curses</EM> says only:
+
+ The <EM>getwin(</EM> <EM>)</EM> function reads window-related data stored
+ in the file by <EM>putwin(</EM> <EM>)</EM>. The function then creates
+ and initializes a new window using that data.
+
+ The <EM>putwin(</EM> <EM>)</EM> function writes all data associated with
+ <EM>win</EM> into the <EM>stdio</EM> stream to which <EM>filep</EM> points, using
+ an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>. This information can be
+ retrieved later using <EM>getwin(</EM> <EM>)</EM>.
+
+ In the mid-1990s when the X/Open Curses document was writ-
+ ten, there were still systems using older, less capable
+ curses libraries (aside from the BSD curses library which
+ was not relevant to X/Open because it did not meet the
+ criteria for <EM>base</EM> <EM>curses</EM>). The document explained the
+ term "enhanced" as follows:
+
+ <STRONG>o</STRONG> Shading is used to identify <EM>X/Open</EM> <EM>Enhanced</EM> <EM>Curses</EM>
+ material, relating to interfaces included to pro-
+ vide enhanced capabilities for applications origi-
+ nally written to be compiled on systems based on
+ the UNIX operating system. Therefore, the features
+ described may not be present on systems that con-
+ form to <STRONG>XPG4</STRONG> <STRONG>or</STRONG> <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>. The rele-
+ vant reference pages may provide additional or more
+ specific portability warnings about use of the
+ material.
+
+ In the foregoing, emphasis was added to <STRONG>unspecified</STRONG> <STRONG>format</STRONG>
+ and to <STRONG>XPG4</STRONG> <STRONG>or</STRONG> <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>, for clarity.
+
+
+</PRE><H3><a name="h3-Unix-SystemV">Unix SystemV</a></H3><PRE>
+ Unix SystemV curses identified the file format by writing
+ a "magic number" at the beginning of the dump. The <STRONG>WINDOW</STRONG>
+ data and the lines of text follow, all in binary form.
+
+ The Solaris curses source has these definitions:
+
+ /* terminfo magic number */
+ #define MAGNUM 0432
+
+ /* curses screen dump magic number */
+ #define SVR2_DUMP_MAGIC_NUMBER 0433
+ #define SVR3_DUMP_MAGIC_NUMBER 0434
+
+ That is, the feature was likely introduced in SVr2 (1984),
+ and improved in SVr3 (1987). The Solaris curses source
+ has no magic number for SVr4 (1989). Other operating sys-
+ tems (AIX and HPUX) use a magic number which would corre-
+ spond to this definition:
+
+ /* curses screen dump magic number */
+ #define SVR4_DUMP_MAGIC_NUMBER 0435
+
+ That octal number in bytes is 001, 035. Because most Unix
+ vendors use big-endian hardware, the magic number is writ-
+ ten with the high-order byte first, e.g.,
+
+ 01 35
+
+ After the magic number, the <STRONG>WINDOW</STRONG> structure and line-data
+ are written in binary format. While the magic number used
+ by the Unix systems can be seen using <STRONG>od(1)</STRONG>, none of the
+ Unix systems documents the format used for screen-dumps.
+
+ The Unix systems do not use identical formats. While col-
+ lecting information for for this manual page, the <EM>save-</EM>
+ <EM>screen</EM> test-program produced dumps of different size (all
+ on 64-bit hardware, on 40x80 screens):
+
+ <STRONG>o</STRONG> AIX (51817 bytes)
+
+ <STRONG>o</STRONG> HPUX (90093 bytes)
+
+ <STRONG>o</STRONG> Solaris 10 (13273 bytes)
+
+ <STRONG>o</STRONG> ncurses5 (12888 bytes)
+
+
+</PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE>
+ As noted above, Solaris curses has no magic number corre-
+ sponding to SVr4 curses. This is odd since Solaris was
+ the first operating system to pass the SVr4 guidelines.
+ Solaris has two versions of curses:
+
+ <STRONG>o</STRONG> The default curses library uses the SVr3 magic number.
+
+ <STRONG>o</STRONG> There is an alternate curses library in <STRONG>/usr/xpg4</STRONG>.
+ This uses a textual format with no magic number.
+
+ According to the copyright notice, the <EM>xpg4</EM> Solaris
+ curses library was developed by MKS (Mortice Kern Sys-
+ tems) from 1990 to 1995.
+
+ Like ncurses6, there is a file-header with parameters.
+ Unlike ncurses6, the contents of the window are writ-
+ ten piecemeal, with coordinates and attributes for
+ each chunk of text rather than writing the whole win-
+ dow from top to bottom.
+
+
+</PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE>
+ PDCurses added support for screen dumps in version 2.7
+ (2005). Like Unix SystemV and ncurses5, it writes the
+ <STRONG>WINDOW</STRONG> structure in binary, but begins the file with its
+ three-byte identifier "PDC", followed by a one-byte ver-
+ sion, e.g.,
+
+ "PDC\001"
+
+
+</PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE>
+ As of April 2017, NetBSD curses does not yet support
+ screen dumps.
+
+
+</PRE><H2><a name="h2-EXAMPLE">EXAMPLE</a></H2><PRE>
+ Given a simple program which writes text to the screen
+ (and for the sake of example, limiting the screen-size to
+ 10x20):
+
+ #include <curses.h>
+
+ int
+ main(void)
+ {
+ putenv("LINES=10");
+ putenv("COLUMNS=20");
+ initscr();
+ start_color();
+ init_pair(1, COLOR_WHITE, COLOR_BLUE);
+ init_pair(2, COLOR_RED, COLOR_BLACK);
+ bkgd(<STRONG>COLOR_PAIR(1)</STRONG>);
+ move(4, 5);
+ attron(A_BOLD);
+ addstr("Hello");
+ move(5, 5);
+ attroff(A_BOLD);
+ attrset(A_REVERSE | <STRONG>COLOR_PAIR(2)</STRONG>);
+ addstr("World!");
+ refresh();
+ scr_dump("foo.out");
+ endwin();
+ return 0;
+ }
+
+ When run using ncurses6, the output looks like this:
+
+ \210\210\210\210ncurses 6.0.20170415
+ _cury=5
+ _curx=11
+ _maxy=9
+ _maxx=19
+ _flags=14
+ _attrs=\{REVERSE|C2}
+ flag=_idcok
+ _delay=-1
+ _regbottom=9
+ _bkgrnd=\{NORMAL|C1}\s
+ rows:
+ 1:\{NORMAL|C1}\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 2:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 3:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 4:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 5:\s\s\s\s\s\{BOLD}Hello\{NORMAL}\s\s\s\s\s\s\s\s\s\s
+ 6:\s\s\s\s\s\{REVERSE|C2}World!\{NORMAL|C1}\s\s\s\s\s\s\s\s\s
+ 7:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 8:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 9:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+ 10:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
+
+ The first four octal escapes are actually nonprinting
+ characters, while the remainder of the file is printable
+ text. You may notice:
+
+ <STRONG>o</STRONG> The actual color pair values are not written to the
+ file.
+
+ <STRONG>o</STRONG> All characters are shown in printable form; spaces are
+ "\s" to ensure they are not overlooked.
+
+ <STRONG>o</STRONG> Attributes are written in escaped curly braces, e.g.,
+ "\{BOLD}", and may include a color-pair (C1 or C2 in
+ this example).
+
+ <STRONG>o</STRONG> The parameters in the header are written out only if
+ they are nonzero. When reading back, order does not
+ matter.
+
+ Running the same program with Solaris <EM>xpg4</EM> curses gives
+ this dump:
+
+ MAX=10,20
+ BEG=0,0
+ SCROLL=0,10
+ VMIN=1
+ VTIME=0
+ FLAGS=0x1000
+ FG=0,0
+ BG=0,0,
+ 0,0,0,1,
+ 0,19,0,0,
+ 1,0,0,1,
+ 1,19,0,0,
+ 2,0,0,1,
+ 2,19,0,0,
+ 3,0,0,1,
+ 3,19,0,0,
+ 4,0,0,1,
+ 4,5,0x20,0,Hello
+ 4,10,0,1,
+ 4,19,0,0,
+ 5,0,0,1,
+ 5,5,0x4,2,World!
+ 5,11,0,1,
+ 5,19,0,0,
+ 6,0,0,1,
+ 6,19,0,0,
+ 7,0,0,1,
+ 7,19,0,0,
+ 8,0,0,1,
+ 8,19,0,0,
+ 9,0,0,1,
+ 9,19,0,0,
+ CUR=11,5
+
+ Solaris <STRONG>getwin</STRONG> requires that all parameters are present,
+ and in the same order. The <EM>xpg4</EM> curses library does not
+ know about the <STRONG>bce</STRONG> (back color erase) capability, and does
+ not color the window background.
+
+ On the other hand, the SVr4 curses library does know about
+ the background color. However, its screen dumps are in
+ binary. Here is the corresponding dump (using "od -t
+ x1"):
+
+ 0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
+ 0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
+ 0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
+ 0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
+ 0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
+ 0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+ *
+ 0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
+ 0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
+ 0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+ *
+ 0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
+ 0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
+ 0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
+ 0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
+ *
+ 0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
+ 0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
+ 0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
+ 0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+ *
+ 0002371
+
+
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+ <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>.
+
+
+</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
+ Thomas E. Dickey
+ extended screen-dump format for ncurses 6.0 (2015)
+
+ Eric S. Raymond
+ screen dump feature in ncurses 1.9.2d (1995)
+
+
+
+ <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
+</PRE>
+<div class="nav">
+<ul>
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<ul>
+<li><a href="#h3-ncurses6">ncurses6</a></li>
+<li><a href="#h3-ncurses5-_legacy_">ncurses5 (legacy)</a></li>
+</ul>
+</li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a>
+<ul>
+<li><a href="#h3-X_Open-Curses">X/Open Curses</a></li>
+<li><a href="#h3-Unix-SystemV">Unix SystemV</a></li>
+<li><a href="#h3-Solaris">Solaris</a></li>
+<li><a href="#h3-PDCurses">PDCurses</a></li>
+<li><a href="#h3-NetBSD">NetBSD</a></li>
+</ul>
+</li>
+<li><a href="#h2-EXAMPLE">EXAMPLE</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+<li><a href="#h2-AUTHORS">AUTHORS</a></li>
+</ul>
+</div>
+</BODY>
+</HTML>
projects / ncurses.git / blobdiff