X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fscr_dump.5;h=95b2142ee6af005e24d725b645456b61d241475d;hb=382c1d0c3c8959d2e5ffb69e86469d00937aa4ae;hp=d976fae88afc7a97bc1993eb274fc38aa00b9a92;hpb=159cd0555e0efc14be66c9c3a1548f58908b6a1d;p=ncurses.git

diff --git a/man/scr_dump.5 b/man/scr_dump.5
index d976fae8..95b2142e 100644
--- a/man/scr_dump.5
+++ b/man/scr_dump.5
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2021,2023 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
 .\" Copyright 2017 Free Software Foundation, Inc.                            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,8 +27,8 @@
 .\" 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.46 2024/03/23 20:42:29 tom Exp $
+.TH scr_dump 5 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -47,8 +47,7 @@
 .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,
@@ -131,51 +130,46 @@ and adjust the \fI\%WINDOW\fP structure which was read back into memory.
 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
@@ -190,9 +184,12 @@ The Solaris curses source has these definitions:
 .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
@@ -202,8 +199,8 @@ correspond to this definition:
 .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
@@ -211,16 +208,21 @@ the magic number is written with the high-order byte first, e.g.,
 .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
@@ -230,31 +232,49 @@ Solaris 10 (13273 bytes)
 .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
+.IR curses .
+This is odd,
+since Solaris was the first operating system to meet the SVr4
+guidelines.
+Solaris furthermore supplies two versions of
+.IR 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
+.IR /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
@@ -262,23 +282,33 @@ e.g.,
 .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):