doc/html/man/scr_dump.5.html

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