e18651243e
While I didn't plan another upgrade, This version incorporate fixes from kevans@ so let's upgrade to it
430 lines
14 KiB
Groff
430 lines
14 KiB
Groff
.\"***************************************************************************
|
|
.\" Copyright 2018,2020 Thomas E. Dickey *
|
|
.\" Copyright 2017 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.16 2020/02/02 23:34:34 tom Exp $
|
|
.TH scr_dump 5
|
|
.ie \n(.g .ds `` \(lq
|
|
.el .ds `` ``
|
|
.ie \n(.g .ds '' \(rq
|
|
.el .ds '' ''
|
|
.de NS
|
|
.ie n .sp
|
|
.el .sp .5
|
|
.ie n .in +4
|
|
.el .in +2
|
|
.nf
|
|
.ft C \" Courier
|
|
..
|
|
.de NE
|
|
.fi
|
|
.ft R
|
|
.ie n .in -4
|
|
.el .in -2
|
|
..
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.SH NAME
|
|
scr_dump \- format of curses screen-dumps.
|
|
.SH SYNOPSIS
|
|
.B scr_dump
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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,
|
|
and read it back using \fBscr_restore\fP or \fBgetwin\fP.
|
|
.PP
|
|
The \fBputwin\fP and \fBgetwin\fP functions do the work;
|
|
while \fBscr_dump\fP and \fBscr_restore\fP conveniently save and restore
|
|
the whole screen, i.e., \fBstdscr\fP.
|
|
.SS ncurses6
|
|
.PP
|
|
A longstanding implementation of screen-dump was
|
|
revised with ncurses6 to remedy problems with the earlier approach:
|
|
.bP
|
|
A \*(``magic number\*('' is written to the beginning of the dump file,
|
|
allowing applications (such as \fBfile\fP(1)) to recognize curses dump files.
|
|
.IP
|
|
Because ncurses6 uses a new format,
|
|
that requires a new magic number
|
|
was unused by other applications.
|
|
This 16-bit number was unused:
|
|
.NS
|
|
0x8888 (octal \*(``\\210\\210\*('')
|
|
.NE
|
|
.IP
|
|
but to be more certain, this 32-bit number was chosen:
|
|
.NS
|
|
0x88888888 (octal \*(``\\210\\210\\210\\210\*('')
|
|
.NE
|
|
.IP
|
|
This is the pattern submitted to the maintainers of the \fBfile\fP program:
|
|
.NS
|
|
#
|
|
# 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
|
|
#
|
|
.NE
|
|
.bP
|
|
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.
|
|
.IP
|
|
The \fInarrow\fP library configuration holds characters and video attributes
|
|
in a 32-bit \fBchtype\fP, while the \fIwide-character\fP library stores
|
|
this information in the \fBcchar_t\fP structure, which is much larger than
|
|
32-bits.
|
|
.bP
|
|
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.
|
|
.bP
|
|
The ncurses6 \fBgetwin\fP reads the legacy screen dumps from ncurses5.
|
|
.SS ncurses5 (legacy)
|
|
.PP
|
|
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:
|
|
.bP
|
|
The \fBWINDOW\fP structure was written in binary form.
|
|
.bP
|
|
The \fBWINDOW\fP structure refers to lines of data,
|
|
which were written as an array of binary data following the \fBWINDOW\fP.
|
|
.bP
|
|
When \fBgetwin\fP restored the window,
|
|
it would keep track of offsets into the array of line-data
|
|
and adjust the \fBWINDOW\fP structure which was read back into memory.
|
|
.PP
|
|
This is similar to Unix SystemV,
|
|
but does not write a \*(``magic number\*('' to identify the file format.
|
|
.SH PORTABILITY
|
|
.PP
|
|
There is no standard format for \fBputwin\fP.
|
|
This section gives a brief description of the existing formats.
|
|
.SS X/Open Curses
|
|
.PP
|
|
Refer to \fIX/Open Curses, Issue 7\fP (2009).
|
|
.PP
|
|
X/Open's documentation for \fIenhanced curses\fP says only:
|
|
.RS 3
|
|
.PP
|
|
The \fIgetwin(\ ) \fPfunction reads window-related data
|
|
stored in the file by \fIputwin(\ )\fP.
|
|
The function
|
|
then creates and initializes a new window using that data.
|
|
.PP
|
|
The \fIputwin(\ )\fP function writes all data associated
|
|
with \fIwin\fP into the \fIstdio\fP stream to which \fIfilep\fP
|
|
points, using an \fBunspecified format\fP.
|
|
This information can be retrieved later using \fIgetwin(\ )\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 SystemV
|
|
.PP
|
|
Unix SystemV curses identified the file format by writing a
|
|
\*(``magic number\*('' at the beginning of the dump.
|
|
The \fBWINDOW\fP data and the lines of text follow, all in binary form.
|
|
.PP
|
|
The Solaris curses source has these definitions:
|
|
.NS
|
|
/* terminfo magic number */
|
|
#define MAGNUM 0432
|
|
|
|
/* curses screen dump magic number */
|
|
#define SVR2_DUMP_MAGIC_NUMBER 0433
|
|
#define SVR3_DUMP_MAGIC_NUMBER 0434
|
|
.NE
|
|
.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 HPUX) use a magic number which would
|
|
correspond to this definition:
|
|
.NS
|
|
/* curses screen dump magic number */
|
|
#define SVR4_DUMP_MAGIC_NUMBER 0435
|
|
.NE
|
|
.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.,
|
|
.NS
|
|
\001\035
|
|
.NE
|
|
.PP
|
|
After the magic number, the \fBWINDOW\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.
|
|
.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):
|
|
.bP
|
|
AIX (51817 bytes)
|
|
.bP
|
|
HPUX (90093 bytes)
|
|
.bP
|
|
Solaris 10 (13273 bytes)
|
|
.bP
|
|
ncurses5 (12888 bytes)
|
|
.SS Solaris
|
|
.PP
|
|
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:
|
|
.bP
|
|
The default 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.
|
|
.IP
|
|
According to the copyright notice, the \fIxpg4\fP Solaris curses 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.
|
|
.SS PDCurses
|
|
.PP
|
|
PDCurses added support for screen dumps in version 2.7 (2005).
|
|
Like Unix SystemV and ncurses5,
|
|
it writes the \fBWINDOW\fP structure in binary,
|
|
but begins the file with its three-byte identifier \*(``PDC\*('',
|
|
followed by a one-byte version,
|
|
e.g.,
|
|
.NS
|
|
\*(``PDC\\001\*(''
|
|
.NE
|
|
.SS NetBSD
|
|
.PP
|
|
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.
|
|
.PP
|
|
Like ncurses5, NetBSD \fBputwin\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),
|
|
.bP
|
|
followed by a binary dump of the \fBWINDOW\fP,
|
|
.bP
|
|
some data for wide-characters referenced by the \fBWINDOW\fP structure, and
|
|
.bP
|
|
finally, lines as done by other implementations.
|
|
.SH EXAMPLE
|
|
.PP
|
|
Given a simple program which writes text to the screen
|
|
(and for the sake of example, limiting the screen-size to 10x20):
|
|
.NS
|
|
#include <curses.h>
|
|
|
|
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(COLOR_PAIR(1));
|
|
move(4, 5);
|
|
attron(A_BOLD);
|
|
addstr("Hello");
|
|
move(5, 5);
|
|
attroff(A_BOLD);
|
|
attrset(A_REVERSE | COLOR_PAIR(2));
|
|
addstr("World!");
|
|
refresh();
|
|
scr_dump("foo.out");
|
|
endwin();
|
|
return 0;
|
|
}
|
|
.NE
|
|
.PP
|
|
When run using ncurses6, the output looks like this:
|
|
.NS
|
|
\\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
|
|
.NE
|
|
.PP
|
|
The first four octal escapes are actually nonprinting characters,
|
|
while the remainder of the file is printable text.
|
|
You may notice:
|
|
.bP
|
|
The actual color pair values are not written to the file.
|
|
.bP
|
|
All characters are shown in printable form; spaces are \*(``\\s\*('' to
|
|
ensure they are not overlooked.
|
|
.bP
|
|
Attributes are written in escaped curly braces, e.g., \*(``\\{BOLD}\*('',
|
|
and may include a color-pair (C1 or C2 in this example).
|
|
.bP
|
|
The parameters in the header are written out only if they are nonzero.
|
|
When reading back, order does not matter.
|
|
.ne 10
|
|
.PP
|
|
Running the same program with Solaris \fIxpg4\fP curses gives this dump:
|
|
.NS
|
|
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
|
|
.NE
|
|
.PP
|
|
Solaris \fBgetwin\fP requires that all parameters are present, and
|
|
in the same order.
|
|
The \fIxpg4\fP curses library does not know about the \fBbce\fP
|
|
(back color erase) capability, and does not color the window background.
|
|
.ne 10
|
|
.PP
|
|
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\*(''):
|
|
.NS
|
|
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
|
|
.NE
|
|
.SH SEE ALSO
|
|
.PP
|
|
\fBcurs_scr_dump\fR(3X),
|
|
\fBcurs_util\fR(3X).
|
|
.SH AUTHORS
|
|
.PP
|
|
Thomas E. Dickey
|
|
.br
|
|
extended screen-dump format for ncurses 6.0 (2015)
|
|
.sp
|
|
Eric S. Raymond
|
|
.br
|
|
screen dump feature in ncurses 1.9.2d (1995)
|