zd/zd.1

   1 .\" Copyright (c) 2011 Chris Spiegel.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd May 3, 2011
  26 .Dt ZD 1
  27 .Os
  28 .Sh NAME
  29 .Nm zd
  30 .Nd disassemble Z\-machine stories
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl bdDinv
  34 .Op Fl a Ar address
  35 .Op Fl A Ar address_file
  36 .Op Fl w Ar width
  37 .Ar file
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility disassembles Z\-machine stories, displaying the results in a
  42 manner similar to the
  43 .Xr txd 1
  44 disassembler.  The main difference to
  45 .Xr txd 1
  46 is that
  47 .Xr txd 1
  48 has knowledge of how Infocom and Inform lay out story files.  As such,
  49 .Xr txd 1
  50 can get confused by stories that do not conform to a layout it expects.
  51 On the other hand,
  52 .Xr txd 1
  53 is able to find code (such as action routines) that
  54 .Nm
  55 will not detect, because
  56 .Nm
  57 only finds code that is reachable directly from the initial program
  58 counter address.  If you know the address of code that is not reachable
  59 from the initial program counter address,
  60 .Nm
  61 can decode it if you use the
  62 .Fl a
  63 or
  64 .Fl A
  65 option.
  66 .Pp
  67 The following options are available:
  68 .Bl -tag -width indent
  69 .It Fl a Ar address
  70 By default,
  71 .Nm
  72 starts disassembling at the address at byte
  73 .Li 0x06
  74 in the header, which is the starting location of the program counter.
  75 The
  76 .Fl a
  77 option allows other addresses to be used as a starting location.
  78 Any number of
  79 .Fl a
  80 options can be given, allowing multiple addresses to be examined.
  81 Addresses must be specified in hexadecimal, with an optional leading
  82 .Li 0x .
  83 .Pp
  84 If the
  85 .Fl a
  86 option is used, the story's reported program counter starting address
  87 will not be examined.  If you wish to include it as well, specify an
  88 address of 0.
  89 .It Fl A Ar address_file
  90 This is identical to the
  91 .Fl a
  92 option, except that addresses are read, one per line, from the file
  93 .Ar address_file .
  94 If
  95 .Ar address_file
  96 is a single dash
  97 .Pq Sq Fl ,
  98 read from standard input.
  99 .It Fl b
 100 Disable buffered output.  This is intended to be used with the
 101 .Fl v
 102 option, to ensure that in case of abnormal program termination (such as
 103 a segfault), the last-processed instruction will be seen.  Such abnormal
 104 terminations are the result of bugs in
 105 .Nm ,
 106 so this is primarily an option to aid in development and debugging.
 107 .It Fl d
 108 In addition to the instructions, print out a hexadecimal representation
 109 of the constituent bytes of each instruction.  See also the
 110 .Fl D
 111 option.
 112 .It Fl D
 113 By default, the
 114 .Fl d
 115 option will not dump the constituent bytes of strings, because these
 116 tend to be very long.  The
 117 .Fl D
 118 option instructs
 119 .Nm
 120 to dump the strings as well as instructions.
 121 .It Fl i
 122 If an unknown opcode is found or an attempt is made to jump outside of
 123 memory,
 124 .Nm
 125 will exit with an error message.  This option instructs it to continue
 126 to attempt to disassemble.  All bets are off at this point, although in
 127 some cases
 128 .Nm
 129 will continue to disassemble correctly.
 130 .It Fl n
 131 When printing strings, use a
 132 .Li ^
 133 character to represent a newline instead
 134 of an actual newline characer.
 135 .It Fl v
 136 .Nm
 137 runs in two phases.  First, it scans through a story file, decoding
 138 everything that appears to be an instruction.  Next, it displays the
 139 decoded instructions in order.  This second phase is what's normally
 140 displayed.  The
 141 .Fl v
 142 option also displays the first phase.
 143 .It Fl w Ar width
 144 When the
 145 .Fl d
 146 option is selected, the display of bytes is wrapped at
 147 .Ar width
 148 bytes per line, so the screen is less cluttered.  If no
 149 .Fl w
 150 option is given, a default of 8 is used.
 151 .El
 152 .Sh AUTHORS
 153 .An "Chris Spiegel" Aq cspiegel@gmail.com
 154 .Sh SEE ALSO
 155 .Xr txd 1 ,
 156 .Xr za 1