The curses library provides applications with the ability to write the
- contents of a window to an external file using scr_dump or putwin, and
- read it back using scr_restore or getwin.
+ contents of a window to an external file using scr_dump or putwin, and
+ read it back using scr_restore or getwin.
- The putwin and getwin functions do the work; while scr_dump and
- scr_restore conveniently save and restore the whole screen, i.e.,
- stdscr.
+ The putwin and getwin functions do the work; while scr_dump and
+ scr_restore conveniently save and restore the whole screen, i.e.,
+ stdscr.
A longstanding implementation of screen-dump was revised with ncurses6
to remedy problems with the earlier approach:
- o A "magic number" is written to the beginning of the dump file,
- allowing applications (such as file(1)) to recognize curses dump
+ o A "magic number" is written to the beginning of the dump file,
+ allowing applications (such as file(1)) to recognize curses dump
files.
Because ncurses6 uses a new format, that requires a new magic
@@ -82,7 +78,7 @@
0x88888888 (octal "\210\210\210\210")
- This is the pattern submitted to the maintainers of the file
+ This is the pattern submitted to the maintainers of the file
program:
#
@@ -93,84 +89,70 @@
0 string \210\210\210\210ncurses ncurses6 screen image
#
- o The screen dumps are written in textual form, so that internal data
+ o 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 narrow library configuration holds characters and video
- attributes in a 32-bit chtype, while the wide-character library
- stores this information in the cchar_t structure, which is much
+ The narrow library configuration holds characters and video
+ attributes in a 32-bit chtype, while the wide-character library
+ stores this information in the cchar_t structure, which is much
larger than 32-bits.
- o It is possible to read a screen dump into a terminal with a
+ o 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.
- o The ncurses6 getwin reads the legacy screen dumps from ncurses5.
+ o The ncurses6 getwin reads the legacy screen dumps from ncurses5.
-
+ 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:
- o The WINDOW structure was written in binary form.
+ o The WINDOW structure was written in binary form.
- o The WINDOW structure refers to lines of data, which were written as
- an array of binary data following the WINDOW.
+ o The WINDOW structure refers to lines of data, which were written as
+ an array of binary data following the WINDOW.
- o When getwin restored the window, it would keep track of offsets
- into the array of line-data and adjust the WINDOW structure which
+ o When getwin restored the window, it would keep track of offsets
+ into the array of line-data and adjust the WINDOW 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.
+ This is similar to Unix System V, but does not write a "magic number"
+ to identify the file format.
- There is no standard format for putwin. This section gives a brief
- description of the existing formats.
+ There is no standard format for curses screen dumps. A brief survey of
+ the existing implementations follows.
- Refer to X/OpenCurses,Issue7 (2009).
-
- X/Open's documentation for enhancedcurses says only:
+ X/Open Curses, Issue 7 specifies little. It says (boldface emphasis
+ added)
- The getwin() function reads window-related data stored in the file
- by putwin(). The function then creates and initializes a new
+ "[t]he getwin() function reads window-related data stored in the
+ file by putwin(). The function then creates and initializes a new
window using that data.
- The putwin() function writes all data associated with win into the
- stdio stream to which filep points, using an unspecifiedformat.
- This information can be retrieved later using getwin().
+ The putwin() function writes all data associated with win into the
+ stdio stream to which filep points, using an unspecifiedformat.
+ This information can be retrieved later using getwin()."
- 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 basecurses). The document explained the
- term "enhanced" as follows:
+ In the mid-1990s when the X/Open Curses document was written, there
+ were still System V systems using older, less capable curses libraries.
+ BSD curses was not relevant to X/Open because it did not meet the
+ criteria for base-level conformance; see ncurses(3x).
- o Shading is used to identify X/OpenEnhancedCurses 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 XPG4or
- toearlierXPGreleases. The relevant reference pages may
- provide additional or more specific portability warnings about
- use of the material.
- In the foregoing, emphasis was added to unspecifiedformat and to XPG4
- ortoearlierXPGreleases, for clarity.
+
+ System V curses identified the file format by writing a "magic number"
+ at the beginning of the dump. The WINDOW data and the lines of text
+ follow, all in binary form.
-
-
- Unix SystemV curses identified the file format by writing a "magic
- number" at the beginning of the dump. The WINDOW data and the lines of
- text follow, all in binary form.
-
- The Solaris curses source has these definitions:
+ Solaris curses has the following definitions.
/* terminfo magic number */
#define MAGNUM 0432
@@ -180,86 +162,87 @@
#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:
+ in SVr3 (1987). Solaris curses 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.
- 01 35
+ \001\035
- After the magic number, the WINDOW structure and line-data are written
- in binary format. While the magic number used by the Unix systems can
- be seen using od(1), none of the Unix systems documents the format used
- for screen-dumps.
+ After the magic number, the WINDOW structure and line data are written
+ in binary format. While the magic number used by these systems can be
+ observed with od(1), 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 savescreen 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 ncursessavescreen 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):
- o AIX (51817 bytes)
+ o AIX (51817 bytes)
- o HPUX (90093 bytes)
+ o HP-UX (90093 bytes)
- o Solaris 10 (13273 bytes)
+ o Solaris 10 (13273 bytes)
- o ncurses5 (12888 bytes)
+ oncurses5 (12888 bytes)
- 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 curses has no magic number corresponding to
+ SVr4 curses. This is odd, since Solaris was the first operating system
+ to meet the SVr4 guidelines. Solaris furthermore supplies two versions
+ of curses.
- o The default curses library uses the SVr3 magic number.
+ o The default curses library uses the SVr3 magic number.
- o There is an alternate curses library in /usr/xpg4. This uses a
- textual format with no magic number.
+ o An alternate curses library (which we term xcurses), available in
+ /usr/xpg4, uses a textual format with no magic number.
- According to the copyright notice, the xpg4 Solaris curses library
- was developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+ According to its copyright notice, this xcurses 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.
- PDCurses added support for screen dumps in version 2.7 (2005). Like
- Unix SystemV and ncurses5, it writes the WINDOW structure in binary,
- but begins the file with its three-byte identifier "PDC", followed by a
- one-byte version, e.g.,
+ PDCurses added support for screen dumps in version 2.7 (2005). Like
+ System V and ncurses5, it writes the WINDOW structure in binary, but
+ begins the file with its three-byte identifier "PDC", followed by a
+ single-byte version number.
"PDC\001"
- As of April 2017, NetBSD curses does not support scr_dump and
- scr_restore (or scr_init, scr_set), although it has putwin and getwin.
+ As of April 2017, NetBSD curses does not support scr_dump and
+ scr_restore (or scr_init, scr_set), although it has putwin and getwin.
- Like ncurses5, NetBSD putwin does not identify its dumps with a useful
+ Like ncurses5, NetBSD putwin does not identify its dumps with a useful
magic number. It writes
- o the curses shared library major and minor versions as the first two
- bytes (e.g., 7 and 1),
+ o the curses shared library major and minor versions as the first two
+ bytes (for example, 7 and 1),
- o followed by a binary dump of the WINDOW,
+ o followed by a binary dump of the WINDOW,
- o some data for wide-characters referenced by the WINDOW structure,
+ o some data for wide characters referenced by the WINDOW structure,
and
- o finally, lines as done by other implementations.
+ o finally, lines as done by other implementations.
-
+ 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>
@@ -273,13 +256,13 @@
start_color();
init_pair(1, COLOR_WHITE, COLOR_BLUE);
init_pair(2, COLOR_RED, COLOR_BLACK);
- bkgd(COLOR_PAIR(1));
+ bkgd(COLOR_PAIR(1));
move(4, 5);
attron(A_BOLD);
addstr("Hello");
move(5, 5);
attroff(A_BOLD);
- attrset(A_REVERSE | COLOR_PAIR(2));
+ attrset(A_REVERSE | COLOR_PAIR(2));
addstr("World!");
refresh();
scr_dump("foo.out");
@@ -315,18 +298,18 @@
The first four octal escapes are actually nonprinting characters, while
the remainder of the file is printable text. You may notice:
- o The actual color pair values are not written to the file.
+ o The actual color pair values are not written to the file.
- o All characters are shown in printable form; spaces are "\s" to
+ o All characters are shown in printable form; spaces are "\s" to
ensure they are not overlooked.
- o Attributes are written in escaped curly braces, e.g., "\{BOLD}",
- and may include a color-pair (C1 or C2 in this example).
+ o Attributes are written in escaped curly braces, e.g., "\{BOLD}",
+ and may include a color pair (C1 or C2 in this example).
- o The parameters in the header are written out only if they are
+ o 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 xpg4 curses gives this dump:
+ Running the same program with Solaris xpg4 curses gives this dump:
MAX=10,20
BEG=0,0
@@ -362,12 +345,12 @@
9,19,0,0,
CUR=11,5
- Solaris getwin requires that all parameters are present, and in the
- same order. The xpg4 curses library does not know about the bce (back
+ Solaris getwin requires that all parameters are present, and in the
+ same order. The xpg4 curses library does not know about the bce (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
@@ -394,43 +377,42 @@
0002371
-
Thomas E. Dickey
- extended screen-dump format for ncurses 6.0 (2015)
+ extended screen-dump format for ncurses 6.0 (2015)
Eric S. Raymond
- screen dump feature in ncurses 1.9.2d (1995)
+ screen dump feature in ncurses 1.9.2d (1995)
+