.\"***************************************************************************
-.\" Copyright (c) 2017 Free Software Foundation, Inc. *
+.\" Copyright 2018-2020,2021 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.9 2017/04/22 18:44:25 tom Exp $
+.\" $Id: scr_dump.5,v 1.20 2021/12/25 21:13:38 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
+.ie n .sp
.el .sp .5
-.ie \n(.in +4
+.ie n .in +4
.el .in +2
.nf
.ft C \" Courier
.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.
.SH SYNOPSIS
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
.NE
.SS NetBSD
.PP
-As of April 2017, NetBSD curses does not yet support screen dumps.
+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
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
.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