.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp $
-.TH scr_dump 5 2023-12-23 "ncurses 6.4" "File formats"
+.\" $Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp $
+.TH scr_dump 5 2023-12-30 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH NAME
scr_dump \-
\fIcurses\fR screen dump
-.SH SYNOPSIS
-.B scr_dump
+.\"SH SYNOPSIS
.SH DESCRIPTION
The curses library provides applications with the ability to write the
contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP,
This is similar to Unix System\ V,
but does not write a \*(``magic number\*('' to identify the file format.
.SH PORTABILITY
-There is no standard format for \fBputwin\fP.
-This section gives a brief description of the existing formats.
+There is no standard format for
+.I curses
+screen dumps.
+A brief survey of the existing implementations follows.
.SS "X/Open Curses"
-Refer to \fIX/Open Curses, Issue 7\fP (2009).
-.PP
-X/Open's documentation for \fIenhanced curses\fP says only:
+X/Open Curses, Issue 7 specifies little.
+It says
+(boldface emphasis added)
.RS 3
.PP
-The \fBgetwin(\ ) \fPfunction reads window-related data
-stored in the file by \fIputwin(\ )\fP.
-The function
-then creates and initializes a new window using that data.
+\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in
+the file by \fI\%putwin()\fP.
+The function then creates and initializes a new window using that data.
.PP
-The \fBputwin(\ )\fP function writes all data associated
-with \fIwin\fP into the \fI\%stdio\fP(3) stream to which \fIfilep\fP
-points, using an \fBunspecified format\fP.
-This information can be retrieved later using \fBgetwin(\ )\fP.
+The \fI\%putwin()\fP function writes all data associated with \fIwin\fP
+into the \fI\%stdio\fP stream to which \fIfilep\fP points,
+using an \fBunspecified format\fP.
+This information can be retrieved later using \fI\%getwin()\fP.\*(''
.RE
.PP
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 \fIbase curses\fP).
-The document explained the term \*(``enhanced\*('' as follows:
-.RS 3
-.bP
-Shading is used to identify \fIX/Open Enhanced Curses\fP 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 \fBXPG4 or to earlier XPG releases\fP.
-The relevant reference pages may provide additional
-or more specific portability warnings about use of the material.
-.RE
-.PP
-In the foregoing, emphasis was added to \fBunspecified format\fP
-and to \fBXPG4 or to earlier XPG releases\fP,
-for clarity.
-.SS "Unix System V"
-Unix System\ V curses identified the file format by writing a
-\*(``magic number\*('' at the beginning of the dump.
+there were still System\ V systems using older,
+less capable
+.I curses
+libraries.
+BSD
+.I curses
+was not relevant to X/Open because it did not meet the criteria
+for base-level conformance;
+see \fB\%ncurses\fP(3X).
+.SS "System V"
+System\ V
+.I curses
+identified the file format by writing a \*(``magic number\*('' at the
+beginning of the dump.
The \fI\%WINDOW\fP data and the lines of text follow, all in binary form.
.PP
-The Solaris curses source has these definitions:
+Solaris
+.I curses
+has the following definitions.
.PP
.RS 4
.EX
.PP
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:
+Solaris
+.I 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.
.PP
.RS 4
.EX
.RE
.PP
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.,
+Because most Unix vendors at the time used big-endian hardware,
+the magic number is written with the high-order byte first.
.PP
.RS 4
.EX
.EE
.RE
.PP
-After the magic number, the \fI\%WINDOW\fP structure and line-data are
-written in binary format.
-While the magic number used by the Unix systems can be seen using \fBod\fP(1),
-none of the Unix systems documents the format used for screen-dumps.
+After the magic number,
+the \fI\%WINDOW\fP structure and line data are written in binary format.
+While the magic number used by these systems can be observed with
+\fIod\fP(1),
+none of them documents the format used for screen dumps.
.PP
-The Unix systems do not use identical formats.
-While collecting information for for this manual page,
-the \fIsavescreen\fP 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
+.I \%ncurses
+.I \%savescreen
+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):
.bP
AIX (51817 bytes)
.bP
.bP
\fI\%ncurses\fP5 (12888 bytes)
.SS Solaris
-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
+.I curses
+has no magic number corresponding to SVr4
+.I curses.
+This is odd,
+since Solaris was the first operating system to meet the SVr4
+guidelines.
+Solaris furthermore supplies two versions of
+.I curses.
.bP
-The default curses library uses the SVr3 magic number.
+The default
+.I curses
+library uses the SVr3 magic number.
.bP
-There is an alternate curses library in \fB/usr/xpg4\fP.
-This uses a textual format with no magic number.
+An alternate
+.I curses
+library
+(which we term
+.I \%xcurses),
+available in
+.I /usr/xpg4,
+uses a textual format with no magic number.
.IP
-According to the copyright notice, the \fIxpg4\fP Solaris curses library was
-developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+According to its copyright notice,
+this
+.I \%xcurses
+library was developed by MKS
+(Mortice Kern Systems) from 1990 to 1995.
.IP
-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.
+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.
.SS PDCurses
-PDCurses added support for screen dumps in version 2.7 (2005).
-Like Unix System\ V and ncurses5,
+.I \%PDCurses
+added support for screen dumps in version 2.7 (2005).
+Like System\ V and ncurses5,
it writes the \fI\%WINDOW\fP structure in binary,
but begins the file with its three-byte identifier \*(``PDC\*('',
-followed by a one-byte version,
-e.g.,
+followed by a single-byte version number.
.PP
.RS 4
.EX
.EE
.RE
.SS NetBSD
-As of April 2017, NetBSD curses does
-not support \fBscr_dump\fP and \fBscr_restore\fP
-(or \fBscr_init\fP, \fBscr_set\fP),
-although it has \fBputwin\fP and \fBgetwin\fP.
+As of April 2017,
+NetBSD
+.I curses
+does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP
+(or \fB\%scr_init\fP,
+\fB\%scr_set\fP),
+although it has \fB\%putwin\fP and \fB\%getwin\fP.
.PP
-Like ncurses5, NetBSD \fBputwin\fP does not identify its dumps with a
-useful magic number.
+Like ncurses5,
+NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic
+number.
It writes
.bP
-the curses shared library major and minor versions
-as the first two bytes (e.g., 7 and 1),
+the
+.I curses
+shared library major and minor versions as the first two bytes
+(for example,
+7 and 1),
.bP
followed by a binary dump of the \fI\%WINDOW\fP,
.bP
-some data for wide-characters referenced by the \fI\%WINDOW\fP structure, and
+some data for wide characters referenced by the \fI\%WINDOW\fP
+structure,
+and
.bP
-finally, lines as done by other implementations.
+finally,
+lines as done by other implementations.
.SH EXAMPLES
Given a simple program which writes text to the screen
(and for the sake of example, limiting the screen-size to 10x20):
projects / ncurses.git / blobdiff