diff options
Diffstat (limited to 'doc/html/man/scr_dump.5.html')
| -rw-r--r-- | doc/html/man/scr_dump.5.html | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/doc/html/man/scr_dump.5.html b/doc/html/man/scr_dump.5.html new file mode 100644 index 0000000..e73ebc0 --- /dev/null +++ b/doc/html/man/scr_dump.5.html @@ -0,0 +1,436 @@ +<!-- + **************************************************************************** + * Copyright 2018,2020 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.16 2020/02/02 23:34:34 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"> +<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> 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>std-</STRONG> + <STRONG>scr</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 num- + ber 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> pro- + gram: + + # + # 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- con- + figurations. + + 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 differ- + ent 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 win- + dow 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 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 pro- + vide 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 num- + ber" 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 infor- + mation 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 writ- + ing 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 back- + ground 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> |