getbytecode

Bytecode disassemby command, introduced in Tcl 8.6.3, intended to produce machine-readable disassembly of Tcl's bytecode. The machine-readable format is a dict.

tcl::unsupported::getbytecode proc procName
tcl::unsupported::getbytecode lambda lambdaTerm
tcl::unsupported::getbytecode script script
tcl::unsupported::getbytecode method class method
tcl::unsupported::getbytecode objmethod object method

The different arguments control how the command looks up the bytecode to take apart.

WARNING!
The output format of this command, beyond being a dictionary, is not defined.
Future releases of Tcl may change it at any time.


Description of output

Main dictionary

In 8.6.3, the following keys are in the dict:

literals
list of literal values
variables
list of descriptions of variables in the local variable table. Each variable is a pair, where the first element is a collection of flags (e.g., arg for “argument to procedure”, scalar for “simple non-array variable”, temp for “a temporary variable without name”), and the second is the name of the variable (omitted for temporaries).
exception
list of dicts describing the exception ranges.
instructions
dict of instructions, indexed by address (which is monotonically increasing, but not contiguous; bytecodes are not all the same). Each instruction is described by a list where the first element is the opcode and the subsequent elements are the arguments.
auxiliary
list of auxiliary metadata for instructions, used to store additional information for foreach, switch (in jump-table form), and dict update. Each entry in the auxiliary metadata is represented by a dict where name maps to a description of what sort of metadata it is, and other elements are defined by the type.
commands
list of dicts describing the commands found in the script that caused the bytecode to be generated.
script
The whole Tcl script that was parsed to generate the bytecode.
namespace
The namespace that the script is bound to. (Note that TclOO methods mutate this.)
stackdepth
The depth of value stack required to evaluate the bytecode.
exceptdepth
The depth of exception handler stack required to evaluate the bytecode.
initiallinenumber
The line number of the first line of the procedure body (typically the line of the proc call — or equivalent — and typically blank) within the file described by **sourcefile**. Not available for procedures with dynamically-generated bodies.
sourcefile
The name of the file that the proc — or equivalent — was sourced from, just as can be found with info frame when the procedure is executing. Not available for procedures with dynamically-generated bodies.

Variable meaning flags

scalar
This variable holds a single value.
array
This variable is an array.
link
This variable is a link (e.g., local variable bound for global, variable or upvar).
arg
This variable is an argument to the procedure or method.
temp
This variable is an unnamed temporary.
resolved
This variable is controlled by a variable resolver.

Exception dictionary entries

type
Type of exception range being described: loop or catch.
level
How deep in the stack of exception ranges is this one?
from
Instruction address at which this range starts.
to
Instruction address at which this range ends.
break
Location to jump to on TCL_BREAK. Only present for loop exception ranges.
catch
Location to jump to on any exception (including both TCL_BREAK and TCL_CONTINUE). Only present for catch exception ranges.
continue
Location to jump to on TCL_CONTINUE. Only present for loop exception ranges.

Argument meaning flags

Arguments may be:

  • an immediate integer (may be an index into the exception table if the instruction is beginCatch4),
  • a @ followed by an integer index into the literals list,
  • a % followed by an index into the variables list,
  • a . followed by an immediate list index (may be end-relative),
  • a = followed by an index into the table of string is classes,
  • a ? followed by an index into the auxiliary list, or
  • pc followed by an address (for jump-like instructions).

Auxiliary metadata types

The first pair in the dictionary defines the name key, which describes the meaning of the other elements

ForeachInfo

Old-style foreach information. Should not normally be seen.

data
List of variables used to store lists being iterated over.
loop
Loop counter variable.
assign
List of lists of indices of variables to be assigned each step around the loop.

NewForeachInfo

jumpOffset
Offset of the start of the foreach loop (instruction after foreach_start) relative to the end of the foreach loop (foreach_step).
assign
List of lists of indices of variables to be assigned each step around the loop.

DictUpdateInfo

variables
List of indices into the variables list of variables to be written (matching order for arguments to dict update).

JumptableInfo

mapping
Dictionary mapping the value to match to the jump offset to use (i.e., relative to the jumptable instruction).

Command dictionary entries

codefrom
The index into the instructions of the start of the command.
codeto
The index into the instructions of the end of the command.
scriptfrom
The index into the script of the start of the command.
scriptto
The index into the script of the end of the command.
script
The section of script defining the command, as a string.

See also