doc/html/man/scr_dump.5.html

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