Line Numbers

The Actual Detail

What the compiler actually does

Every section of the reference object, from llvm-readobj:

$ llvm-readobj --sections sample_msvc.obj | grep -E 'Name:|LineNumberCount'
    Name: .text            LineNumberCount: 0
    Name: .data            LineNumberCount: 0
    Name: .bss             LineNumberCount: 0
    Name: .xdata           LineNumberCount: 0
    Name: .rdata           LineNumberCount: 0
    Name: .rdata           LineNumberCount: 0
    Name: .debug$S         LineNumberCount: 0
    Name: .pdata           LineNumberCount: 0
    Name: .llvm_addrsig    LineNumberCount: 0

Nine sections, nine zeros. And it is not that clang lacks the feature: the same objects carry a .debug$S section holding CodeView debug data, and llvm-objdump can disassemble .text with line annotations. clang simply does not write COFF line numbers — it writes CodeView records into a section that the COFF section header has no field for, which is a different mechanism entirely.

The same is true of the GNU dialect. The i386 build, same source, same answer.

Verifying the field layout anyway

A field that is always zero cannot be verified by reading it, so the layout was verified by construction. A line-number table was appended to a real object and the section header patched to point at it:

$ python3 -c "
import struct, shutil
shutil.copy('sample_msvc.obj','lineno.obj')
d = bytearray(open('lineno.obj','rb').read())
entries = [(0,0x1000), (1,3), (0,0x2000), (1,4), (0,0)]
tbl = b''.join(struct.pack('<IH', s, l) for s, l in entries)
linptr = len(d)
d += tbl
struct.pack_into('<I', d, 0x14 + 28, linptr)   # PointerToLinenumbers
struct.pack_into('<H', d, 0x14 + 34, len(entries))  # NumberOfLinenumbers
open('lineno.obj','wb').write(d)
print('appended at 0x%x, %d entries, %d bytes' % (linptr, len(entries), len(tbl)))
"
$ llvm-readobj --sections lineno.obj | head -12
    Number: 1
    Name: .text
    PointerToRelocations: 0x1E8
    PointerToLinenumbers: 0x5AF     <- read back exactly what was written
    RelocationCount: 3
    LineNumberCount: 5

The reader reports PointerToLinenumbers: 0x5AF and LineNumberCount: 5, which is precisely what was written. That proves the two fields are where the specification says they are, and that the count is a record count rather than a byte count. It is shipped as lineno.obj alongside the other samples.

Why the values would not mean much anyway

This is the part worth understanding, because it explains a design that looks like an oversight.

In a COFF object, LineNumber cannot be a source line number in any useful sense. Consider what a debugger would have to do with the table above: symbol 0, line 0x1000 — 4096. Line 4096 of a 30-line file? The value is an ordinal into a line-number program that lives in the debug information, and that program is produced during the link, when the real source line for each address is finally known. In a standalone object the referent does not exist.

You can watch this go wrong. Disassemble the constructed file with line annotations enabled:

$ llvm-objdump -l --section=.text lineno.obj
0000000000000000 <add>:
; add():
       0: 50        pushq %rax
; g_ptr():
       8: 8b 04 24  movl (%rsp), %eax
; g_addr():
      10: c3        retq

The annotations name add, g_ptr and g_addr — functions that have nothing to do with the invented numbers, attached to instructions that are all from one function. The disassembler is resolving the ordinals against whatever symbol data it can find, and the result is confident, plausible, and meaningless. That output is the best possible argument for the discipline this course follows: a field whose meaning you cannot verify should not be taught, and a value that decodes without complaint is not thereby a value you understand.