| <!-- |
| **************************************************************************** |
| * Copyright 2018-2020,2021 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.20 2021/12/25 21:13:38 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</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">scr_dump 5</H1> |
| <PRE> |
| <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> File Formats Manual <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-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 <STRONG>getwin(</STRONG> <STRONG>)</STRONG> 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 <STRONG>putwin(</STRONG> <STRONG>)</STRONG> function writes all data associated with <EM>win</EM> into the |
| <STRONG>stdio(3)</STRONG> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>. |
| This information can be retrieved later using <STRONG>getwin(</STRONG> <STRONG>)</STRONG>. |
| |
| In the mid-1990s when the X/Open Curses document was written, 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 provide enhanced capabilities |
| for applications originally written to be compiled on systems |
| based on the UNIX operating system. Therefore, the features |
| described may not be present on systems that conform to <STRONG>XPG4</STRONG> <STRONG>or</STRONG> |
| <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>. The relevant 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 systems (AIX and HPUX) use a magic number |
| which would correspond 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 written 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 collecting |
| information for for this manual page, the <EM>savescreen</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 corresponding 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 Systems) from 1990 to 1995. |
| |
| Like ncurses6, there is a file-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> |
| 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 version, e.g., |
| |
| "PDC\001" |
| |
| |
| </PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE> |
| As of April 2017, NetBSD curses 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 curses shared library major and minor versions as the first two |
| bytes (e.g., 7 and 1), |
| |
| <STRONG>o</STRONG> followed by a binary dump of the <STRONG>WINDOW</STRONG>, |
| |
| <STRONG>o</STRONG> some data for wide-characters referenced by the <STRONG>WINDOW</STRONG> structure, |
| and |
| |
| <STRONG>o</STRONG> finally, lines as done by other implementations. |
| |
| |
| </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> |