doc/html/man/scr_dump.5.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   4   * Copyright 2017 Free Software Foundation, Inc.                            *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: scr_dump.5,v 1.46 2024/03/23 20:42:29 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>scr_dump 5 2024-03-23 ncurses 6.4 File formats</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">scr_dump 5 2024-03-23 ncurses 6.4 File formats</H1>
  43 <PRE>
  44 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>                      File formats                      <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        scr_dump - <EM>curses</EM> screen dump
  51
  52
  53 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  54        The  curses library provides applications with the ability to write the
  55        contents of a window to an external file using <STRONG>scr_dump</STRONG> or <STRONG>putwin</STRONG>,  and
  56        read it back using <STRONG>scr_restore</STRONG> or <STRONG>getwin</STRONG>.
  57
  58        The  <STRONG>putwin</STRONG>  and  <STRONG>getwin</STRONG>  functions  do  the  work;  while <STRONG>scr_dump</STRONG> and
  59        <STRONG>scr_restore</STRONG> conveniently save  and  restore  the  whole  screen,  i.e.,
  60        <STRONG>stdscr</STRONG>.
  61
  62
  63 </PRE><H3><a name="h3-ncurses6">ncurses6</a></H3><PRE>
  64        A  longstanding implementation of screen-dump was revised with ncurses6
  65        to remedy problems with the earlier approach:
  66
  67        <STRONG>o</STRONG>   A "magic number" is written to the  beginning  of  the  dump  file,
  68            allowing  applications  (such  as <STRONG>file(1)</STRONG>) to recognize curses dump
  69            files.
  70
  71            Because ncurses6 uses a new  format,  that  requires  a  new  magic
  72            number  was  unused  by other applications.  This 16-bit number was
  73            unused:
  74
  75                0x8888 (octal "\210\210")
  76
  77            but to be more certain, this 32-bit number was chosen:
  78
  79                0x88888888 (octal "\210\210\210\210")
  80
  81            This is the pattern  submitted  to  the  maintainers  of  the  <STRONG>file</STRONG>
  82            program:
  83
  84                #
  85                # ncurses5 (and before) did not use a magic number,
  86                # making screen dumps "data".
  87                #
  88                # ncurses6 (2015) uses this format, ignoring byte-order
  89                0    string    \210\210\210\210ncurses    ncurses6 screen image
  90                #
  91
  92        <STRONG>o</STRONG>   The screen dumps are written in textual form, so that internal data
  93            sizes are not directly related to the dump-format, and enabling the
  94            library  to  read  dumps  from  either  narrow-  or wide-character-
  95            configurations.
  96
  97            The  <EM>narrow</EM>  library  configuration  holds  characters  and   video
  98            attributes  in  a  32-bit  <STRONG>chtype</STRONG>, while the <EM>wide-character</EM> library
  99            stores this information in the <STRONG>cchar_t</STRONG>  structure,  which  is  much
 100            larger than 32-bits.
 101
 102        <STRONG>o</STRONG>   It  is  possible  to  read  a  screen  dump  into a terminal with a
 103            different screen-size, because the library truncates or  fills  the
 104            screen as necessary.
 105
 106        <STRONG>o</STRONG>   The ncurses6 <STRONG>getwin</STRONG> reads the legacy screen dumps from ncurses5.
 107
 108
 109 </PRE><H3><a name="h3-ncurses5-_Legacy_">ncurses5 (Legacy)</a></H3><PRE>
 110        The screen-dump feature was added to <EM>ncurses</EM> in June 1995.  While there
 111        were fixes and improvements in succeeding years, the basic  scheme  was
 112        unchanged:
 113
 114        <STRONG>o</STRONG>   The <EM>WINDOW</EM> structure was written in binary form.
 115
 116        <STRONG>o</STRONG>   The <EM>WINDOW</EM> structure refers to lines of data, which were written as
 117            an array of binary data following the <EM>WINDOW</EM>.
 118
 119        <STRONG>o</STRONG>   When <STRONG>getwin</STRONG> restored the window, it would  keep  track  of  offsets
 120            into  the  array of line-data and adjust the <EM>WINDOW</EM> structure which
 121            was read back into memory.
 122
 123        This is similar to Unix System V, but does not write a  "magic  number"
 124        to identify the file format.
 125
 126
 127 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 128        There is no standard format for <EM>curses</EM> screen dumps.  A brief survey of
 129        the existing implementations follows.
 130
 131
 132 </PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE>
 133        X/Open Curses, Issue 7 specifies little.  It  says  (boldface  emphasis
 134        added)
 135
 136           "[t]he  <EM>getwin()</EM>  function  reads  window-related data stored in the
 137           file by <EM>putwin()</EM>.  The function then creates and initializes  a  new
 138           window using that data.
 139
 140           The  <EM>putwin()</EM>  function writes all data associated with <EM>win</EM> into the
 141           <EM>stdio</EM> stream to which <EM>filep</EM> points,  using  an  <STRONG>unspecified</STRONG>  <STRONG>format</STRONG>.
 142           This information can be retrieved later using <EM>getwin()</EM>."
 143
 144        In  the  mid-1990s  when  the X/Open Curses document was written, there
 145        were still System V systems using older, less capable <EM>curses</EM> libraries.
 146        BSD  <EM>curses</EM>  was  not  relevant  to  X/Open because it did not meet the
 147        criteria for base-level conformance; see <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
 148
 149
 150 </PRE><H3><a name="h3-System-V">System V</a></H3><PRE>
 151        System V <EM>curses</EM> identified the file format by writing a "magic  number"
 152        at  the  beginning  of the dump.  The <EM>WINDOW</EM> data and the lines of text
 153        follow, all in binary form.
 154
 155        Solaris <EM>curses</EM> has the following definitions.
 156
 157            /* terminfo magic number */
 158            #define MAGNUM  0432
 159
 160            /* curses screen dump magic number */
 161            #define SVR2_DUMP_MAGIC_NUMBER  0433
 162            #define SVR3_DUMP_MAGIC_NUMBER  0434
 163
 164        That is, the feature was likely introduced in SVr2 (1984), and improved
 165        in  SVr3  (1987).   Solaris <EM>curses</EM> has no magic number for SVr4 (1989).
 166        Other System V operating systems (AIX and HP-UX)  use  a  magic  number
 167        that would correspond to the following.
 168
 169            /* curses screen dump magic number */
 170            #define SVR4_DUMP_MAGIC_NUMBER  0435
 171
 172        That  octal  number in bytes is 001, 035.  Because most Unix vendors at
 173        the time used big-endian hardware, the magic number is written with the
 174        high-order byte first.
 175
 176            \001\035
 177
 178        After  the magic number, the <EM>WINDOW</EM> structure and line data are written
 179        in binary format.  While the magic number used by these systems can  be
 180        observed  with <STRONG>od(1)</STRONG>, none of them documents the format used for screen
 181        dumps.
 182
 183        Nor do they use an identical format, even  with  the  System V  family.
 184        The <EM>ncurses</EM> <EM>savescreen</EM> test program was used to collect information for
 185        this manual page.  It produced dumps of different size (all  on  64-bit
 186        hardware, on 40x80 screens):
 187
 188        <STRONG>o</STRONG>   AIX (51817 bytes)
 189
 190        <STRONG>o</STRONG>   HP-UX (90093 bytes)
 191
 192        <STRONG>o</STRONG>   Solaris 10 (13273 bytes)
 193
 194        <STRONG>o</STRONG>   <EM>ncurses</EM>5 (12888 bytes)
 195
 196
 197 </PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE>
 198        As  noted  above,  Solaris  <EM>curses</EM> has no magic number corresponding to
 199        SVr4 <EM>curses</EM>.  This is odd, since Solaris was the first operating system
 200        to meet the SVr4 guidelines.  Solaris furthermore supplies two versions
 201        of <EM>curses</EM>.
 202
 203        <STRONG>o</STRONG>   The default <EM>curses</EM> library uses the SVr3 magic number.
 204
 205        <STRONG>o</STRONG>   An alternate <EM>curses</EM> library (which we term <EM>xcurses),</EM>  available  in
 206            <EM>/usr/xpg4</EM>, uses a textual format with no magic number.
 207
 208            According  to  its  copyright  notice,  this  <EM>xcurses</EM>  library  was
 209            developed by MKS (Mortice Kern Systems) from 1990 to 1995.
 210
 211            Like ncurses6,  it  includes  a  header  with  parameters.   Unlike
 212            ncurses6,  the  contents  of the window are written piecemeal, with
 213            coordinates and attributes for  each  chunk  of  text  rather  than
 214            writing the whole window from top to bottom.
 215
 216
 217 </PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE>
 218        <EM>PDCurses</EM>  added  support  for screen dumps in version 2.7 (2005).  Like
 219        System V and ncurses5, it writes the <EM>WINDOW</EM> structure  in  binary,  but
 220        begins  the  file  with  its three-byte identifier "PDC", followed by a
 221        single-byte version number.
 222
 223                 "PDC\001"
 224
 225
 226 </PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE>
 227        As  of  April  2017,  NetBSD  <EM>curses</EM>  does  not  support  <STRONG>scr_dump</STRONG>  and
 228        <STRONG>scr_restore</STRONG> (or <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>), although it has <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>.
 229
 230        Like  ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful
 231        magic number.  It writes
 232
 233        <STRONG>o</STRONG>   the <EM>curses</EM> shared library major and minor versions as the first two
 234            bytes (for example, 7 and 1),
 235
 236        <STRONG>o</STRONG>   followed by a binary dump of the <EM>WINDOW</EM>,
 237
 238        <STRONG>o</STRONG>   some  data  for wide characters referenced by the <EM>WINDOW</EM> structure,
 239            and
 240
 241        <STRONG>o</STRONG>   finally, lines as done by other implementations.
 242
 243
 244 </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
 245        Given a simple program which writes text to the  screen  (and  for  the
 246        sake of example, limiting the screen-size to 10x20):
 247
 248            #include &lt;curses.h&gt;
 249
 250            int
 251            main(void)
 252            {
 253                putenv("LINES=10");
 254                putenv("COLUMNS=20");
 255                initscr();
 256                start_color();
 257                init_pair(1, COLOR_WHITE, COLOR_BLUE);
 258                init_pair(2, COLOR_RED, COLOR_BLACK);
 259                bkgd(<STRONG>COLOR_PAIR(1)</STRONG>);
 260                move(4, 5);
 261                attron(A_BOLD);
 262                addstr("Hello");
 263                move(5, 5);
 264                attroff(A_BOLD);
 265                attrset(A_REVERSE | <STRONG>COLOR_PAIR(2)</STRONG>);
 266                addstr("World!");
 267                refresh();
 268                scr_dump("foo.out");
 269                endwin();
 270                return 0;
 271            }
 272
 273        When run using ncurses6, the output looks like this:
 274
 275            \210\210\210\210ncurses 6.0.20170415
 276            _cury=5
 277            _curx=11
 278            _maxy=9
 279            _maxx=19
 280            _flags=14
 281            _attrs=\{REVERSE|C2}
 282            flag=_idcok
 283            _delay=-1
 284            _regbottom=9
 285            _bkgrnd=\{NORMAL|C1}\s
 286            rows:
 287            1:\{NORMAL|C1}\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 288            2:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 289            3:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 290            4:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 291            5:\s\s\s\s\s\{BOLD}Hello\{NORMAL}\s\s\s\s\s\s\s\s\s\s
 292            6:\s\s\s\s\s\{REVERSE|C2}World!\{NORMAL|C1}\s\s\s\s\s\s\s\s\s
 293            7:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 294            8:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 295            9:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 296            10:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
 297
 298        The first four octal escapes are actually nonprinting characters, while
 299        the remainder of the file is printable text.  You may notice:
 300
 301        <STRONG>o</STRONG>   The actual color pair values are not written to the file.
 302
 303        <STRONG>o</STRONG>   All characters are shown in printable  form;  spaces  are  "\s"  to
 304            ensure they are not overlooked.
 305
 306        <STRONG>o</STRONG>   Attributes  are  written  in escaped curly braces, e.g., "\{BOLD}",
 307            and may include a color pair (C1 or C2 in this example).
 308
 309        <STRONG>o</STRONG>   The parameters in the header are  written  out  only  if  they  are
 310            nonzero.  When reading back, order does not matter.
 311
 312        Running the same program with Solaris <EM>xpg4</EM> curses gives this dump:
 313
 314            MAX=10,20
 315            BEG=0,0
 316            SCROLL=0,10
 317            VMIN=1
 318            VTIME=0
 319            FLAGS=0x1000
 320            FG=0,0
 321            BG=0,0,
 322            0,0,0,1,
 323            0,19,0,0,
 324            1,0,0,1,
 325            1,19,0,0,
 326            2,0,0,1,
 327            2,19,0,0,
 328            3,0,0,1,
 329            3,19,0,0,
 330            4,0,0,1,
 331            4,5,0x20,0,Hello
 332            4,10,0,1,
 333            4,19,0,0,
 334            5,0,0,1,
 335            5,5,0x4,2,World!
 336            5,11,0,1,
 337            5,19,0,0,
 338            6,0,0,1,
 339            6,19,0,0,
 340            7,0,0,1,
 341            7,19,0,0,
 342            8,0,0,1,
 343            8,19,0,0,
 344            9,0,0,1,
 345            9,19,0,0,
 346            CUR=11,5
 347
 348        Solaris  <STRONG>getwin</STRONG>  requires  that  all parameters are present, and in the
 349        same order.  The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG>  (back
 350        color erase) capability, and does not color the window background.
 351
 352        On  the  other  hand,  the  SVr4  curses  library  does  know about the
 353        background color.  However, its screen dumps are in  binary.   Here  is
 354        the corresponding dump (using "od -t x1"):
 355
 356            0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
 357            0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
 358            0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
 359            0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
 360            0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
 361            0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
 362            *
 363            0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
 364            0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
 365            0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
 366            *
 367            0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
 368            0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
 369            0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
 370            0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
 371            *
 372            0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
 373            0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
 374            0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
 375            0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 376            *
 377            0002371
 378
 379
 380 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 381        Thomas E. Dickey
 382        extended screen-dump format for <EM>ncurses</EM> 6.0 (2015)
 383
 384        Eric S. Raymond
 385        screen dump feature in <EM>ncurses</EM> 1.9.2d (1995)
 386
 387
 388 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 389        <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
 390
 391
 392
 393 ncurses 6.4                       2024-03-23                       <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
 394 </PRE>
 395 <div class="nav">
 396 <ul>
 397 <li><a href="#h2-NAME">NAME</a></li>
 398 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 399 <ul>
 400 <li><a href="#h3-ncurses6">ncurses6</a></li>
 401 <li><a href="#h3-ncurses5-_Legacy_">ncurses5 (Legacy)</a></li>
 402 </ul>
 403 </li>
 404 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 405 <ul>
 406 <li><a href="#h3-X_Open-Curses">X/Open Curses</a></li>
 407 <li><a href="#h3-System-V">System V</a></li>
 408 <li><a href="#h3-Solaris">Solaris</a></li>
 409 <li><a href="#h3-PDCurses">PDCurses</a></li>
 410 <li><a href="#h3-NetBSD">NetBSD</a></li>
 411 </ul>
 412 </li>
 413 <li><a href="#h2-EXAMPLES">EXAMPLES</a></li>
 414 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 415 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 416 </ul>
 417 </div>
 418 </BODY>
 419 </HTML>