* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp @
+ * @Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp @
+ *SH SYNOPSIS
-->
<!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 2023-12-23 ncurses 6.4 File formats</TITLE>
+<TITLE>scr_dump 5 2023-12-30 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">scr_dump 5 2023-12-23 ncurses 6.4 File formats</H1>
+<H1 class="no-header">scr_dump 5 2023-12-30 ncurses 6.4 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>
scr_dump - <EM>curses</EM> screen dump
-</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
</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.
+ 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>
- 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:
+ X/Open Curses, Issue 7 specifies little. It says (boldface emphasis
+ added)
- 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
+ "[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 <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.
+ 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 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.
+ 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-
Unix-System-V">Unix System V</a></H3><PRE>
- Unix System V curses 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.
+</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.
- The Solaris curses source has these definitions:
+ Solaris <EM>curses</EM> has the following definitions.
/* terminfo magic number */
#define MAGNUM 0432
#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 HP-UX) use a magic number
- which would correspond to this definition:
+ 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 use
- big-endian hardware, the magic number is written with the high-order
- byte first, e.g.,
+ 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 the Unix systems can
- be seen using <STRONG>od(1)</STRONG>, none of the Unix systems documents the format used
- for screen-dumps.
+ 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.
- 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):
+ 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)
</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:
+ 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 curses library uses the SVr3 magic number.
+ <STRONG>o</STRONG> The default <EM>curses</EM> 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.
+ <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 the copyright notice, the <EM>xpg4</EM> Solaris curses library
- was developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+ According to its copyright notice, this <EM>xcurses</EM> 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
+ 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>
- PDCurses added support for screen dumps in version 2.7 (2005). Like
- Unix 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
- one-byte version, e.g.,
+ <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 curses does not support <STRONG>scr_dump</STRONG> and
+ 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
+ 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> 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,
+ <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
+ 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>
<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
+ <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}",
+ <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
+ <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:
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
+ 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
+ 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
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
+ncurses 6.4 2023-12-
30 <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="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-X_Open-Curses">X/Open Curses</a></li>
-<li><a href="#h3-Unix-System-V">Unix System V</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>
projects / ncurses.git / blobdiff