.\"***************************************************************************
-.\" Copyright 2018,2020 Thomas E. Dickey *
+.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: scr_dump.5,v 1.16 2020/02/02 23:34:34 tom Exp $
-.TH scr_dump 5
+.\" $Id: scr_dump.5,v 1.25 2023/07/01 15:46:10 tom Exp $
+.TH scr_dump 5 2023-07-01 "ncurses 6.4" "File formats"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.ie n .in +4
.el .in +2
.nf
-.ft C \" Courier
+.ft CR \" Courier
..
.de NE
.fi
.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:
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
+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,
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.
.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,
it writes the \fBWINDOW\fP structure in binary,
\*(``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
0002371
.NE
.SH SEE ALSO
-.PP
-\fBcurs_scr_dump\fR(3X),
-\fBcurs_util\fR(3X).
+\fBcurs_scr_dump\fP(3X),
+\fBcurs_util\fP(3X).
.SH AUTHORS
-.PP
Thomas E. Dickey
.br
extended screen-dump format for ncurses 6.0 (2015)