doc/html/man/scr_dump.5.html

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