.\"***************************************************************************
-.\" Copyright (c) 2017 Free Software Foundation, Inc. *
+.\" Copyright 2018-2021,2023 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: scr_dump.5,v 1.10 2017/04/29 20:53:55 tom Exp $
-.TH scr_dump 5
+.\" $Id: scr_dump.5,v 1.36 2023/09/30 21:38:11 tom Exp $
+.TH scr_dump 5 2023-09-30 "ncurses 6.4" "File formats"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
+.ie n .ds CW R
+.el \{
+.ie \n(.g .ds CW CR
+.el .ds CW CW
+.\}
.de NS
-.ie \n(.sp
+.ie n .sp
.el .sp .5
-.ie \n(.in +4
+.ie n .in +4
.el .in +2
.nf
-.ft C \" Courier
+.ft \*(CW
..
.de NE
.fi
.ft R
-.in -4
+.ie n .in -4
+.el .in -2
..
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.ds n 5
-.ds d @TERMINFO@
.SH NAME
-scr_dump \- format of curses screen-dumps.
+scr_dump \-
+\fIcurses\fR screen dump
.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.
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
.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:
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,
+This is similar to Unix System\ V,
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
+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.
.PP
-The \fIputwin(\ )\fP function writes all data associated
-with \fIwin\fP into the \fIstdio\fP stream to which \fIfilep\fP
+The \fBputwin(\ )\fP function writes all data associated
+with \fIwin\fP into the \fBstdio\fP(3) stream to which \fIfilep\fP
points, using an \fBunspecified format\fP.
-This information can be retrieved later using \fIgetwin(\ )\fP.
+This information can be retrieved later using \fBgetwin(\ )\fP.
.RE
.PP
In the mid-1990s when the X/Open Curses document was written,
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.
+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
+.SS Unix System V
+Unix System\ V 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
.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
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,
+Like Unix System\ V 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,
\*(``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),
.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
VTIME=0
FLAGS=0x1000
FG=0,0
-BG=0,0,
+BG=0,0,
0,0,0,1,
-0,19,0,0,
+0,19,0,0,
1,0,0,1,
-1,19,0,0,
+1,19,0,0,
2,0,0,1,
-2,19,0,0,
+2,19,0,0,
3,0,0,1,
-3,19,0,0,
+3,19,0,0,
4,0,0,1,
4,5,0x20,0,Hello
4,10,0,1,
-4,19,0,0,
+4,19,0,0,
5,0,0,1,
5,5,0x4,2,World!
5,11,0,1,
-5,19,0,0,
+5,19,0,0,
6,0,0,1,
-6,19,0,0,
+6,19,0,0,
7,0,0,1,
-7,19,0,0,
+7,19,0,0,
8,0,0,1,
-8,19,0,0,
+8,19,0,0,
9,0,0,1,
-9,19,0,0,
+9,19,0,0,
CUR=11,5
.NE
.PP
(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.
+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
*
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)
Eric S. Raymond
.br
screen dump feature in ncurses 1.9.2d (1995)
+.SH SEE ALSO
+\fB\%curs_scr_dump\fP(3X),
+\fB\%curs_util\fP(3X)
projects / ncurses.git / blobdiff