.IL File Format – Labels, branches and exception handling

Labels

A code label is an Id followed by a colon, at the place of an instruction: it names the address of the instruction that comes next. Any Id will do: IL_0000, loop, 'my label'. A label may be on a line of its own or in front of an instruction (done: ret); it must be unique in its method; and it may be used before it is defined. A data label names a .data item and has no colon (Fields and data). A code label is never used as a data label or the reverse.

Branches and switch

Every branch has a long form with a four-byte offset (br) and a short form with a one-byte offset (br.s), which reaches only 128 bytes back or 127 forward from the end of the instruction. The operand is a label; ilasm also takes a number, which it uses as the relative offset itself. The offset of a short branch must fit in one signed byte; the ilasm option /OPTIMIZE (“optimize long instructions to short”) shortens the long forms that fit.

A branch must come after the instructions that put its operands on the stack, and the stack must have the same shape at the label as at the branch (the rules of the verifier, Partition III). A switch list can be empty and its items may be labels or numbers. The instruction set page lists every branch and the CIL opcode reference gives their encodings.

  ldarg.0
  switch (case0, case1, case2)
  br.s    other
case0:  ldstr "zero"  br.s done
case1:  ldstr "one"   br.s done
case2:  ldstr "two"
done:   ret
other:  ldnull
        ret

Exception blocks

An exception block is a protected block (.try) followed by one or more handlers. Each handler is a catch for one exception type, a filter that decides at run time, a finally that runs on every exit, or a fault that runs only when an exception passes through. Every range is written in one of two ways: as a block in braces, or as a range between two labels. The first label is the first instruction of the range, the second is the instruction just after it. (The grammar also accepts numbers instead of labels in each of these places, for offsets that ildasm prints with its /RAWEH option.)

.try
{
  ldstr "work"
  call void [mscorlib]System.Console::WriteLine(string)
  leave.s done
}
catch [mscorlib]System.FormatException
{
  pop
  leave.s done
}
finally
{
  ldstr "cleanup"
  call void [mscorlib]System.Console::WriteLine(string)
  endfinally
}
done: ret

// the same try range written with labels (ildasm's style):
// .try IL_0000 to IL_0010 catch [mscorlib]System.FormatException handler IL_0010 to IL_0018

The rules the standard sets (II.19, and Partition I and III for the details):

• A protected block is entered only at its first instruction and left only with leave (or by an exception or a throw); falling off its end is not allowed. leave empties the stack and runs the finally handlers it exits.
• A catch handler starts with the exception object on the stack: use it or pop it. It ends with leave (or rethrow, which throws the exception again).
• A filter block must come immediately before its handler. It ends with endfilter after pushing an int32 answer: 1 to run the handler, 0 to go on searching.
• A finally handler ends with endfinally; a fault handler with endfault (ilasm treats endfault as an alias of endfinally, which has the same encoding). Neither can be entered by a branch or by falling in.
• No two handlers have the same start address, and the blocks of a method nest properly.

Not described

Known, not yet covered

• Reference: the full verifier rules for branches and exception blocks (Partition III, III.1.7 and the Partition I clauses on exception handling) are summarised, not reproduced. Whether ilasm of .NET accepts a range label that is defined after its use in .try … to … was not tested; the standard requires the labels to be defined first.