| <!-- |
| **************************************************************************** |
| * Copyright 2018-2023,2024 Thomas E. Dickey * |
| * Copyright 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.46 2024/03/23 20:42:29 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 https://invisible-island.net/scripts/readme.html#others_scripts"> |
| <TITLE>scr_dump 5 2024-03-23 ncurses 6.5 File formats</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">scr_dump 5 2024-03-23 ncurses 6.5 File formats</H1> |
| <PRE> |
| <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> File formats <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> |
| |
| |
| |
| |
| </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| scr_dump - <EM>curses</EM> screen dump |
| |
| |
| </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-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 <EM>ncurses</EM> in June 1995. While there |
| were fixes and improvements in succeeding years, the basic scheme was |
| unchanged: |
| |
| <STRONG>o</STRONG> The <EM>WINDOW</EM> structure was written in binary form. |
| |
| <STRONG>o</STRONG> The <EM>WINDOW</EM> structure refers to lines of data, which were written as |
| an array of binary data following the <EM>WINDOW</EM>. |
| |
| <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 <EM>WINDOW</EM> structure which |
| was read back into memory. |
| |
| This is similar to Unix System V, 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 <EM>curses</EM> screen dumps. A brief survey of |
| the existing implementations follows. |
| |
| |
| </PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE> |
| X/Open Curses, Issue 7 specifies little. It says (boldface emphasis |
| added) |
| |
| "[t]he <EM>getwin()</EM> function reads window-related data stored in the |
| file by <EM>putwin()</EM>. The function then creates and initializes a new |
| window using that data. |
| |
| The <EM>putwin()</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>." |
| |
| In the mid-1990s when the X/Open Curses document was written, there |
| were still System V systems using older, less capable <EM>curses</EM> libraries. |
| BSD <EM>curses</EM> was not relevant to X/Open because it did not meet the |
| criteria for base-level conformance; see <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. |
| |
| |
| </PRE><H3><a name="h3-System-V">System V</a></H3><PRE> |
| System V <EM>curses</EM> identified the file format by writing a "magic number" |
| at the beginning of the dump. The <EM>WINDOW</EM> data and the lines of text |
| follow, all in binary form. |
| |
| Solaris <EM>curses</EM> has the following 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). Solaris <EM>curses</EM> has no magic number for SVr4 (1989). |
| Other System V operating systems (AIX and HP-UX) use a magic number |
| that would correspond to the following. |
| |
| /* curses screen dump magic number */ |
| #define SVR4_DUMP_MAGIC_NUMBER 0435 |
| |
| That octal number in bytes is 001, 035. Because most Unix vendors at |
| the time used big-endian hardware, the magic number is written with the |
| high-order byte first. |
| |
| \001\035 |
| |
| After the magic number, the <EM>WINDOW</EM> structure and line data are written |
| in binary format. While the magic number used by these systems can be |
| observed with <STRONG>od(1)</STRONG>, none of them documents the format used for screen |
| dumps. |
| |
| Nor do they use an identical format, even with the System V family. |
| The <EM>ncurses</EM> <EM>savescreen</EM> test program was used to collect information for |
| this manual page. It produced dumps of different size (all on 64-bit |
| hardware, on 40x80 screens): |
| |
| <STRONG>o</STRONG> AIX (51817 bytes) |
| |
| <STRONG>o</STRONG> HP-UX (90093 bytes) |
| |
| <STRONG>o</STRONG> Solaris 10 (13273 bytes) |
| |
| <STRONG>o</STRONG> <EM>ncurses</EM>5 (12888 bytes) |
| |
| |
| </PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE> |
| As noted above, Solaris <EM>curses</EM> has no magic number corresponding to |
| SVr4 <EM>curses</EM>. This is odd, since Solaris was the first operating system |
| to meet the SVr4 guidelines. Solaris furthermore supplies two versions |
| of <EM>curses</EM>. |
| |
| <STRONG>o</STRONG> The default <EM>curses</EM> library uses the SVr3 magic number. |
| |
| <STRONG>o</STRONG> An alternate <EM>curses</EM> library (which we term <EM>xcurses),</EM> available in |
| <EM>/usr/xpg4</EM>, uses a textual format with no magic number. |
| |
| According to its copyright notice, this <EM>xcurses</EM> library was |
| developed by MKS (Mortice Kern Systems) from 1990 to 1995. |
| |
| Like ncurses6, it includes a header with parameters. Unlike |
| ncurses6, the contents of the window are written piecemeal, with |
| coordinates and attributes for each chunk of text rather than |
| writing the whole window from top to bottom. |
| |
| |
| </PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE> |
| <EM>PDCurses</EM> added support for screen dumps in version 2.7 (2005). Like |
| System V and ncurses5, it writes the <EM>WINDOW</EM> structure in binary, but |
| begins the file with its three-byte identifier "PDC", followed by a |
| single-byte version number. |
| |
| "PDC\001" |
| |
| |
| </PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE> |
| As of April 2017, NetBSD <EM>curses</EM> does not support <STRONG>scr_dump</STRONG> and |
| <STRONG>scr_restore</STRONG> (or <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>), although it has <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>. |
| |
| Like ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful |
| magic number. It writes |
| |
| <STRONG>o</STRONG> the <EM>curses</EM> shared library major and minor versions as the first two |
| bytes (for example, 7 and 1), |
| |
| <STRONG>o</STRONG> followed by a binary dump of the <EM>WINDOW</EM>, |
| |
| <STRONG>o</STRONG> some data for wide characters referenced by the <EM>WINDOW</EM> structure, |
| and |
| |
| <STRONG>o</STRONG> finally, lines as done by other implementations. |
| |
| |
| </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</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-AUTHORS">AUTHORS</a></H2><PRE> |
| Thomas E. Dickey |
| extended screen-dump format for <EM>ncurses</EM> 6.0 (2015) |
| |
| Eric S. Raymond |
| screen dump feature in <EM>ncurses</EM> 1.9.2d (1995) |
| |
| |
| </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> |
| |
| |
| |
| ncurses 6.5 2024-03-23 <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-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-System-V">System V</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-EXAMPLES">EXAMPLES</a></li> |
| <li><a href="#h2-AUTHORS">AUTHORS</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |