This page lists every record of a Breakpad symbol file, as the symbol files document in the Breakpad repository defines them, with every field in order. Where a detail comes from the Breakpad source code or the tools rather than that document, the text says so.
General rules
- The file is plain ASCII text, one record per line. Fields are separated by a single space.
- The first field is the record type (
MODULE,FILE,FUNCand so on). Line records are the only records with no type word: a line that starts with a hexadecimal digit is a line record. - The last field of
MODULE,FILE,INLINE_ORIGIN,FUNCandPUBLICis a name that runs to the end of the line and may contain spaces. - Hexadecimal numbers are written with lower-case letters and no
0xprefix. Each field below says whether it is hexadecimal or decimal. - Every address is relative to the module’s load address.
| Record | Syntax | Purpose |
|---|---|---|
MODULE | MODULE os arch id name | Identifies the module; the first line. |
INFO | INFO kind … | Extra facts about the module, such as its code identifier. |
FILE | FILE number name | Numbers a source file. |
INLINE_ORIGIN | INLINE_ORIGIN number name | Numbers the name of an inlined function. |
FUNC | FUNC [m] address size parameter_size name | A function with debug information. |
INLINE | INLINE nest_level call_line call_file origin address size … | Code inlined into the function above. |
| line record | address size line filenum | Maps an address range to a source line. |
PUBLIC | PUBLIC [m] address parameter_size name | A linker symbol with no line information. |
STACK WIN | STACK WIN type rva code_size … | Windows x86 frame data for the stack walker. |
STACK CFI INIT | STACK CFI INIT address size rules | Starts a range of call frame information. |
STACK CFI | STACK CFI address rules | Changes the unwinding rules from an address on. |
MODULE
MODULE operatingsystem architecture id name.
When present it must be the first line of the file.
| Field | Form | Meaning |
|---|---|---|
| operatingsystem | word | The system the module was built for. The document names Linux, mac and windows. |
| architecture | word | The processor. The document names x86, x86_64, ppc, ppc64 and unknown; names for other processors are not listed there. |
| id | hexadecimal digits | Identifies the exact build of the module. The document says only that the way it is computed varies from platform to platform; its example has 33 digits. How each platform computes it is not documented there and is left out here. |
| name | text to end of line | The module’s file name without its directory; may contain spaces. |
INFO
The symbol files document does not describe INFO records. A comment in
Breakpad’s basic_source_line_resolver.cc gives the form
INFO CODE_ID code_id filename, and that reader skips
INFO lines. LLDB’s Breakpad parser treats the file name as optional and
rejects INFO CODE_ID with no value.
| Record | Meaning |
|---|---|
INFO CODE_ID code_id [code_file] | An identifier of the executable itself, distinct from the debug identifier in MODULE, and optionally the executable’s file name. How the identifier is computed on each platform is not documented in the sources read and is marked unknown here. |
Other INFO kinds | Other tools write further kinds (for example INFO GENERATOR); they are not documented in the sources read. |
FILE
FILE number name
| Field | Form | Meaning |
|---|---|---|
| number | decimal | The number that line and INLINE records use to refer to this file. |
| name | text to end of line | The source file’s name; may contain spaces. |
INLINE_ORIGIN
INLINE_ORIGIN number name
| Field | Form | Meaning |
|---|---|---|
| number | decimal | The number that INLINE records use to refer to this name. |
| name | text to end of line | The inlined function’s name; may contain spaces. |
FUNC
FUNC [m] address size parameter_size name.
The function’s code must be one contiguous range. The INLINE and line
records that follow belong to it, up to the next FUNC.
| Field | Form | Meaning |
|---|---|---|
m | optional flag | Several symbols refer to these same instructions, usually because the linker folded identical functions into one. Only one of the names is written. |
| address | hexadecimal | Start of the function. |
| size | hexadecimal | Length of its machine code in bytes. |
| parameter_size | hexadecimal | Bytes of arguments pushed on the stack for the function. |
| name | text to end of line | The function’s name, unmangled for languages such as C++; may contain spaces. |
INLINE
INLINE inline_nest_level call_site_line call_site_file_num origin_num [address size]+.
Each record says that some of the enclosing function’s code is really another
function, inlined at a call site.
| Field | Form | Meaning |
|---|---|---|
| inline_nest_level | decimal | Nesting depth. Level 0 is inlined directly into the preceding FUNC; level n is inlined into the preceding INLINE record of level n−1. |
| call_site_line | decimal | The source line of the call that was inlined. |
| call_site_file_num | decimal | The FILE number of the call site’s source file. |
| origin_num | decimal | The INLINE_ORIGIN number giving the inlined function’s name. |
| address size | hexadecimal pairs, one or more | The address ranges that hold the inlined code. They lie inside the ranges of the parent record. |
Line records
address size line filenum.
A line record belongs to the most recent FUNC, so none may come before the
first one. No two line records in a file may cover the same addresses.
| Field | Form | Meaning |
|---|---|---|
| address | hexadecimal | Start of the code for this line. |
| size | hexadecimal | Length of that code in bytes. |
| line | decimal | Source line number; the first line of a file is 1. |
| filenum | decimal | The FILE number of the source file. |
PUBLIC
PUBLIC [m] address parameter_size name.
A symbol from the linker’s table with no line information and no size: it is taken to
run up to the next address that any record mentions. Where a FUNC also
covers the address, the FUNC wins.
| Field | Form | Meaning |
|---|---|---|
m | optional flag | As for FUNC: several symbols share this code. |
| address | hexadecimal | Address of the symbol. |
| parameter_size | hexadecimal | As for FUNC, if known. |
| name | text to end of line | The symbol’s name; may contain spaces. |
STACK WIN
Windows x86 frame data, whose frame types come from Microsoft’s Debug Interface Access (DIA) library. All fields except the last are hexadecimal.
STACK WIN type rva code_size prologue_size epilogue_size parameter_size saved_register_size local_size max_stack_size has_program_string program_string_OR_allocates_base_pointer
| # | Field | Meaning |
|---|---|---|
| 1 | type | Frame type, a value of DIA’s StackFrameTypeEnum (below). |
| 2 | rva | Start of the code the record covers. |
| 3 | code_size | Length of that code in bytes. |
| 4 | prologue_size | Length of the function’s prologue. Not used by Breakpad. |
| 5 | epilogue_size | Length of the epilogue. Not used by Breakpad. |
| 6 | parameter_size | Bytes of stack arguments, as for FUNC. |
| 7 | saved_register_size | Bytes of the frame holding saved callee-saved registers. |
| 8 | local_size | Bytes of the frame holding local variables and temporaries. |
| 9 | max_stack_size | Most bytes the function pushes. Not used by Breakpad. |
| 10 | has_program_string | 0: the last field is the allocates_base_pointer flag. Non-zero: the last field is a program string. |
| 11 | program_string or allocates_base_pointer | A program string (to the end of the line, in the postfix language) that computes the caller’s registers; or a hexadecimal flag. When the flag is true, %ebp does not point to the frame base: the return address is at %esp + frame size, the caller’s %ebp is saved at %esp + next parameter size + saved_register_size − 8, and the caller’s %esp is %esp + frame size + 4. When false, the function does not use %ebp as a general register, so the caller’s %ebp equals this frame’s. |
Frame types
| Value | DIA name | Meaning |
|---|---|---|
| 0 | FrameTypeFPO | Frame pointer omitted; FPO information available. Expected to use the allocates_base_pointer flag. Used by Breakpad. |
| 1 | FrameTypeTrap | Kernel trap frame. Ignored by Breakpad. |
| 2 | FrameTypeTSS | Described by Microsoft also as a kernel trap frame. Ignored. |
| 3 | FrameTypeStandard | Standard EBP stack frame. Ignored. |
| 4 | FrameTypeFrameData | Frame pointer omitted; frame data available. Used by Breakpad, which prefers it where type 0 covers the same address. |
| −1 | FrameTypeUnknown | A frame without debug information (DIA only). |
Program string names
When the stack walker runs a program string for a frame, these names are set beforehand, and the string assigns the caller’s registers:
| Name | Meaning |
|---|---|
$eip, $esp, $ebp, $ebx, $esi, $edi | On entry, the frame’s registers; the string assigns the caller’s values to them. A caller $eip of 0 marks the end of the stack. |
.cbParams | The record’s parameter_size. |
.cbSavedRegs | The record’s saved_register_size. |
.cbLocals | The record’s local_size. |
.raSearchStart | Where to start searching the stack for the return address: the frame’s %esp plus the size of the frame. |
STACK CFI INIT and STACK CFI
Call frame information. Each rule says how to recover one register’s value in the caller.
STACK CFI INIT address size register: expression …
| Field | Form | Meaning |
|---|---|---|
| address | hexadecimal | Start of the range. |
| size | hexadecimal | Bytes covered by this record together with the STACK CFI records after it, up to the next INIT. |
register: expression | rules, one or more | The initial rules, valid from address to the next STACK CFI record. Callee-saved registers not mentioned keep their values; caller-saved registers are never mentioned. |
STACK CFI address register: expression …
| Field | Form | Meaning |
|---|---|---|
| address | hexadecimal | Where the new rules start. Greater than the previous record’s address, and inside the range of the latest INIT. |
register: expression | rules | Only the registers whose rules change here; all other rules carry on from the previous record. |
Rule names
A rule is a register name, a colon, then a postfix expression running up to the next
word that ends in a colon. Register names are those each architecture’s stack walker
in Breakpad defines (stackwalker_architecture.cc); the
document’s examples use $esp, $eip, $ebp,
$sp and $r0. Three names are special:
| Name | Meaning |
|---|---|
.cfa | Canonical frame address: the base of the frame; with no stack-pointer rule it is the caller’s stack pointer. Other rules may use it. Unlike every other name in an expression, it means the value at the current instruction rather than the callee’s register. |
.ra | The return address, which becomes the caller’s program counter. Breakpad needs .cfa and .ra rules at every address it unwinds from. |
.undef | Used as an expression: the register’s value in the caller cannot be recovered. |
Postfix expressions
STACK WIN program strings and STACK CFI rules are written in
the same postfix (reverse Polish) language, defined in Breakpad’s
postfix_evaluator.h. Tokens are separated by spaces; operands are pushed on
a stack and each operator takes its operands from it. Names starting with
$ are variables the expression may create and change; other names in the
walker’s dictionary (such as .cbParams) are constants; other operands are
literal values.
| Operator | Operands | Meaning |
|---|---|---|
+ | 2 | Addition. |
- | 2 | Subtraction (the first pushed operand is the left one). |
* | 2 | Multiplication. |
/ | 2 | Quotient of a division. |
% | 2 | Remainder of a division. |
@ | 2 | Alignment: the first value rounded down to a multiple of the second. |
^ | 1 | Dereference: the value stored in memory at that address. |
= | 2 | Assignment of a value to a variable. The header does not state the operand order. |
Evaluation fails if values are left on the stack; evaluating for a single value (as a CFI rule needs) succeeds only when exactly one value remains.
Examples
The document’s own example lines, copied as it gives them:
MODULE Linux x86 D3096ED481217FD4C16B29CD9BC208BA0 firefox-bin
FILE 2 /home/jimb/mc/in/browser/app/nsBrowserApp.cpp
FUNC m c184 30 0 nsQueryInterfaceWithError::operator()(nsID const&, void**) const
c184 7 59 4
PUBLIC m 2160 0 Public2_1m) at 0xc184, 0x30 bytes long, with one line record (0xc184, 7 bytes, line 59 of file 4), and a public symbol.STACK CFI INIT 804c4b0 40 .cfa: $esp 4 + $eip: .cfa 4 - ^
STACK CFI 804c4b1 .cfa: $esp 8 + $ebp: .cfa 8 - ^Read with the rules above: from 0x804c4b0 the frame base is $esp + 4
and the caller’s $eip is the value stored 4 bytes below the base. From
0x804c4b1 the base is $esp + 8 and the caller’s $ebp is
stored 8 bytes below it; the $eip rule carries on.
STACK WIN 4 2170 14 1 0 0 0 0 0 1 $eip 4 + ^ = $esp $ebp 8 + = $ebp $ebp ^ =STACK WIN example: type 4, code at 0x2170, 0x14 bytes long, prologue 1 byte, with a program string. It is reproduced as given.Sources
Breakpad, Symbol
files (docs/symbol_files.md): every record, field and example except
INFO. Breakpad source: src/processor/postfix_evaluator.h
(operators, variables, evaluation) and the comment on INFO CODE_ID in
basic_source_line_resolver.cc; LLDB’s BreakpadRecords.cpp
(optional code file). Microsoft,
StackFrameTypeEnum
(frame type names). Not documented in these sources and marked unknown: how the
MODULE identifier and the INFO CODE_ID value are computed,
architecture names beyond the document’s list, and other INFO kinds.