NAME

zd — disassemble Z-machine stories

SYNOPSIS

DESCRIPTION

The zd utility disassembles Z-machine stories, displaying the results in a manner similar to the txd(1) disassembler. The main difference to txd(1) is that txd(1) has knowledge of how Infocom and Inform lay out story files. As such, txd(1) can get confused by stories that do not conform to a layout it expects. On the other hand, txd(1) is able to find code (such as action routines) that zd will not detect, because zd only finds code that is reachable directly from the initial program counter address. If you know the address of code that is not reachable from the initial program counter address, zd can decode it if you use the -a or -A option.

There are two major modes of display: standard and visual. Standard mode operates much like the txd(1) disassembler, dumping a list of instructions. Visual mode diagrams each instruction at the bit level. Standard mode is default, and visual mode can be selected with the -v option.

The following options are available:

-a address

By default, zd starts disassembling at the address at byte 0x06 in the header, which is the starting location of the program counter. The -a option allows other addresses to be used as a starting location. Any number of -a options can be given, allowing multiple addresses to be examined. Addresses must be specified in hexadecimal, with an optional leading 0x.

If the -a option is used, the story's reported program counter starting address will not be examined. If you wish to include it as well, specify an address of 0.

Please note that any values passed to -a are assumed to be unpacked routine addresses.

-A address_file

This is identical to the -a option, except that addresses are read, one per line, from the file address_file. If address_file is a single dash (‘-’), read from standard input.

-b bytestring

Instead of a story file to disassemble, provide a string of hexadecimal-encoded bytes representing Z-machine instructions, such as ‘b211aac634’

-d

In addition to the instructions, print out a hexadecimal representation of the constituent bytes of each instruction. See also the -D option. This is available only in the standard display mode.

-D

By default, the -d option will not dump the constituent bytes of strings, because these tend to be very long. The -D option instructs zd to dump the strings as well as instructions. This is available only in the standard display mode.

-i

If an unknown opcode is found or an attempt is made to jump outside of memory, zd will exit with an error message. This option instructs it to continue to attempt to disassemble. All bets are off at this point, although in some cases zd will continue to disassemble correctly.

--max-instructions count

Specify the maximum number of instructions to decode. If this many instructions are decoded, then decoding will stop gracefully.

-n

When printing strings, use a ^ character to represent a newline instead of an actual newline characer.

--start-offset offset

Display disassembly starting at the specified address, which is an absolute (not packed) offset into the file. offset can be either decimal or hexadecimal, with hexadecimal requiring a leading 0x.

-v

Instead of displaying instructions in the traditional txd(1) style, use a more “visual” style. Individual bytes are diagrammed, displaying how they are interpreted.

In this mode, UTF-8 text is directly written, so a terminal capable of displaying UTF-8 is required.

-V

zd runs in two phases. First, it scans through a story file, decoding everything that appears to be an instruction. Next, it displays the decoded instructions in order. This second phase is what's normally displayed. The -V option also displays the first phase.

-w width

When the -d option is selected, the display of bytes is wrapped at width bytes per line, so the screen is less cluttered. If no -w option is given, a default of 8 is used.

-z zversion

In bytestring mode, the Z-machine version to disassemble must be known. By default, version 5 is assumed. The -z option allows the Z-machine version to be specified.

SEE ALSO

txd(1), za(1)

AUTHORS

Chris Spiegel ⟨cspiegel@gmail.com⟩