symbol_files.md



Introduction
Given a minidump file, the Breakpad processor produces stack traces that include
function names and source locations. However, minidump files contain only the
byte-by-byte contents of threads' registers and stacks, without function names
or machine-code-to-source mapping data. The processor consults Breakpad symbol
files for the information it needs to produce human-readable stack traces from
the binary-only minidump file.
The platform-specific symbol dumping tools parse the debugging information the
compiler provides (whether as DWARF or STABS sections in an ELF file or as
stand-alone PDB files), and write that information back out in the Breakpad
symbol file format. This format is much simpler and less detailed than compiler
debugging information, and values legibility over compactness.

Overview
Breakpad symbol files are ASCII text files, with lines delimited as appropriate
for the host platform. Each line is a record, divided into fields by single
spaces; in some cases, the last field of the record can contain spaces. The
first field is a string indicating what sort of record the line represents
(except for line records; these are very common, making them the default saves
space). Some fields hold decimal or hexadecimal numbers; hexadecimal numbers
have no "0x" prefix, and use lower-case letters.
Breakpad symbol files contain the following record types. With some
restrictions, these may appear in any order.


A MODULE record describes the executable file or shared library from which
this data was derived, for use by symbol suppliers. A `MODULE' record should
be the first record in the file.


A FILE record gives a source file name, and assigns it a number by which
other records can refer to it.


A FUNC record describes a function present in the source code.


A line record indicates to which source file and line a given range of
machine code should be attributed. The line is attributed to the function
defined by the most recent FUNC record.


A PUBLIC record gives the address of a linker symbol.


A STACK record provides information necessary to produce stack traces.


MODULE records
A MODULE record provides meta-information about the module the symbol file
describes. It has the form:

MODULE operatingsystem architecture id name

For example: MODULE Linux x86 D3096ED481217FD4C16B29CD9BC208BA0 firefox-bin  These records provide meta-information about the executable or shared library
from which this symbol file was generated. A symbol supplier might use this
information to find the correct symbol files to use to interpret a given
minidump, or to perform other sorts of validation. If present, a MODULE record
should be the first line in the file.
The fields are separated by spaces, and cannot contain spaces themselves, except
for name.


The operatingsystem field names the operating system on which the
executable or shared library was intended to run. This field should have one
of the following values: | Value | Meaning |
|:----------|:--------------------| | Linux | Linux | | mac | Macintosh OSX
| | windows | Microsoft Windows |


The architecture field indicates what processor architecture the
executable or shared library contains machine code for. This field should
have one of the following values: | Value | Instruction Set
Architecture | |:----------|:---------------------------------| | x86 |
Intel IA-32 | | x86_64 | AMD64/Intel 64 | | ppc | 32-bit PowerPC | | ppc64
| 64-bit PowerPC | | unknown | unknown |


The id field is a sequence of hexadecimal digits that identifies the exact
executable or library whose contents the symbol file describes. The way in
which it is computed varies from platform to platform.


The name field contains the base name (the final component of the
directory path) of the executable or library. It may contain spaces, and
extends to the end of the line.


FILE records
A FILE record holds a source file name for other records to refer to. It has
the form:

FILE number name

For example: FILE 2 /home/jimb/mc/in/browser/app/nsBrowserApp.cpp 
A FILE record provides the name of a source file, and assigns it a number
which other records (line records, in particular) can use to refer to that file
name. The number field is a decimal number. The name field is the name of
the file; it may contain spaces.

FUNC records
A FUNC record describes a source-language function. It has the form:

FUNC address size parameter_size name

For example: FUNC c184 30 0 nsQueryInterfaceWithError::operator()(nsID const&, void**) const 
The address and size fields are hexadecimal numbers indicating the start
address and length in bytes of the machine code instructions the function
occupies. (Breakpad symbol files cannot accurately describe functions whose code
is not contiguous.) The start address is relative to the module's load address.
The parameter_size field is a hexadecimal number indicating the size, in
bytes, of the arguments pushed on the stack for this function. Some calling
conventions, like the Microsoft Windows stdcall convention, require the called
function to pop parameters passed to it on the stack from its caller before
returning. The stack walker uses this value, along with data from STACK
records, to step from the called function's frame to the caller's frame.
The name field is the name of the function. In languages that use linker
symbol name mangling like C++, this should be the source language name (the
"unmangled" form). This field may contain spaces.

Line records
A line record describes the source file and line number to which a given range
of machine code should be attributed. It has the form:

address size line filenum

For example: c184 7 59 4 
Because they are so common, line records do not begin with a string indicating
the record type. All other record types' names use upper-case letters;
hexadecimal numbers, like a line record's address, use lower-case letters.
The address and size fields are hexadecimal numbers indicating the start
address and length in bytes of the machine code. The address is relative to the
module's load address.
The line field is the line number to which the machine code should be
attributed, in decimal; the first line of the source file is line number 1. The
filenum field is a decimal number appearing in a prior FILE record; the name
given in that record is the source file name for the machine code.
The line is assumed to belong to the function described by the last preceding
FUNC record. Line records may not appear before the first `FUNC' record.
No two line records in a symbol file cover the same range of addresses. However,
there may be many line records with identical line and file numbers, as a given
source line may contribute many non-contiguous blocks of machine code.

PUBLIC records
A PUBLIC record describes a publicly visible linker symbol, such as that used
to identify an assembly language entry point or region of memory. It has the
form:

PUBLIC address parameter_size name

For example: PUBLIC 2160 0 Public2_1 
The Breakpad processor essentially treats a PUBLIC record as defining a
function with no line number data and an indeterminate size: the code extends to
the next address mentioned. If a given address is covered by both a PUBLIC
record and a FUNC record, the processor uses the FUNC data.
The address field is a hexadecimal number indicating the symbol's address,
relative to the module's load address.