X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fscr_dump.5;h=95b2142ee6af005e24d725b645456b61d241475d;hb=refs%2Fheads%2Fmaster;hp=7bc736dda2e3e8a7d8a1720abbd1ed24f948192a;hpb=894a177fd5228cdbe790bd1dc9435bd435c29681;p=ncurses.git diff --git a/man/scr_dump.5 b/man/scr_dump.5 index 7bc736dd..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.37 2023/10/07 21:19:07 tom Exp $ -.TH scr_dump 5 2023-10-07 "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, @@ -114,68 +113,63 @@ 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) -The screen-dump feature was added to ncurses in June 1995. +.SS "ncurses5 (Legacy)" +The screen-dump feature was added to \fI\%ncurses\fP 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. +The \fI\%WINDOW\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. +The \fI\%WINDOW\fP structure refers to lines of data, +which were written as an array of binary data following the \fI\%WINDOW\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. +and adjust the \fI\%WINDOW\fP structure which was read back into memory. .PP 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. -.SS X/Open Curses -Refer to \fIX/Open Curses, Issue 7\fP (2009). -.PP -X/Open's documentation for \fIenhanced curses\fP says only: +There is no standard format for +.I curses +screen dumps. +A brief survey of the existing implementations follows. +.SS "X/Open Curses" +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 \fBstdio\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. -The \fBWINDOW\fP data and the lines of text follow, all in binary form. +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 HPUX) 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,50 +208,73 @@ the magic number is written with the high-order byte first, e.g., .EE .RE .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. +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 -HPUX (90093 bytes) +HP-UX (90093 bytes) .bP Solaris 10 (13273 bytes) .bP -ncurses5 (12888 bytes) +\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, -it writes the \fBWINDOW\fP structure in binary, +.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,24 +282,34 @@ 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 \fBWINDOW\fP, +followed by a binary dump of the \fI\%WINDOW\fP, .bP -some data for wide-characters referenced by the \fBWINDOW\fP structure, and +some data for wide characters referenced by the \fI\%WINDOW\fP +structure, +and .bP -finally, lines as done by other implementations. -.SH EXAMPLE +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): .PP @@ -351,7 +381,7 @@ All characters are shown in printable form; spaces are \*(``\es\*('' to ensure they are not overlooked. .bP Attributes are written in escaped curly braces, e.g., \*(``\e{BOLD}\*('', -and may include a color-pair (C1 or C2 in this example). +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. @@ -436,11 +466,11 @@ Here is the corresponding dump (using \*(``od \-t x1\*(''): .SH AUTHORS Thomas E. Dickey .br -extended screen-dump format for ncurses 6.0 (2015) +extended screen-dump format for \fI\%ncurses\fP 6.0 (2015) .sp Eric S. Raymond .br -screen dump feature in ncurses 1.9.2d (1995) +screen dump feature in \fI\%ncurses\fP 1.9.2d (1995) .SH SEE ALSO \fB\%curs_scr_dump\fP(3X), \fB\%curs_util\fP(3X)