aboutsummaryrefslogtreecommitdiff
path: root/doc/html/man/scr_dump.5.html
diff options
context:
space:
mode:
authorBaptiste Daroussin <bapt@FreeBSD.org>2020-02-07 08:36:41 +0000
committerBaptiste Daroussin <bapt@FreeBSD.org>2020-02-07 08:36:41 +0000
commitf0179cb6083cc92e5947ae56e6a0a5c5328aead0 (patch)
treebcee0ba9c2149b71f0bfc036df1e61e3105bf980 /doc/html/man/scr_dump.5.html
parentcea297eb34d2361e79529034397465068ae34ecd (diff)
downloadsrc-f0179cb6083cc92e5947ae56e6a0a5c5328aead0.tar.gz
src-f0179cb6083cc92e5947ae56e6a0a5c5328aead0.zip
Vendor import ncurses 6.1-20200118vendor/ncurses/6.1-20200118
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=357645 svn path=/vendor/ncurses/6.1-20200118/; revision=357646; tag=vendor/ncurses/6.1-20200118
Diffstat (limited to 'doc/html/man/scr_dump.5.html')
-rw-r--r--doc/html/man/scr_dump.5.html435
1 files changed, 435 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 000000000000..55b0e85349e1
--- /dev/null
+++ b/doc/html/man/scr_dump.5.html
@@ -0,0 +1,435 @@
+<!--
+ ****************************************************************************
+ * Copyright (c) 2017,2018 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.15 2018/07/28 21:46:15 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 &lt;curses.h&gt;
+
+ 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>