// Workers AI · dad joke modeWhy was the dwarf short? Small wonder.

For other uses, see Dwarf (disambiguation).

DWARF is a widely used, standardized debugging data format. DWARF was originally designed along with Executable and Linkable Format (ELF), although it is independent of object file formats. The name is a medieval fantasy complement to "ELF" that had no official meaning, although the name "Debugging With Arbitrary Record Formats" has since been proposed as a backronym.

DWARF originated with the C compiler and sdb debugger in Unix System V Release 4 (SVR4). Debugging information such as those in DWARF format are emitted when the -g compiler option is used.

History

The first version of DWARF proved to use excessive amounts of storage, and an incompatible successor, DWARF-2, superseded it and added various encoding schemes to reduce data size. DWARF did not immediately gain universal acceptance; for instance, when Sun Microsystems adopted ELF as part of their move to Solaris, they opted to continue using stabs, in an embedding known as "stabs-in-elf". Linux followed suit, and DWARF-2 did not become the default until the late 1990s.

The DWARF Workgroup of the Free Standards Group released DWARF version 3 in January 2006, adding (among other things) support for C++ namespaces, Fortran 90 allocatable data and additional compiler optimization techniques.

The DWARF committee published version 4 of DWARF, which offers "improved data compression, better description of optimized code, and support for new language features in C++", in 2010.

Version 5 of the DWARF format was published in February 2017. It "incorporates improvements in many areas: better data compression, separation of debugging data from executable files, improved description of macros and source files, faster searching for symbols, improved debugging of optimized code, as well as numerous improvements in functionality and performance."

Structure

In the object files (including executable ones), DWARF is stored as a number of sections named .debug_info, .debug_frame, etc., each with a different purpose.

List of main DWARF sections

Name	Description
.debug_info	Core section.
.debug_types	Contains the non-trivial types. Stored as a hash structure so that duplicate type definition can be removed easily.
.debug_abbrev	Provide the definitions for abbreviation codes used the .debug_info and .debug_types sections – a simple form of data comrpression.
.debug_str	Contains strings that are not placed in the .debug_info and .debug_types sections. The linker merges the string tables to eliminate duplicates.
.debug_frame	Call frame information, allows debuggers to locate frames on the call stack.
.debug_loc	Contain lists of DWARF expressions that describe to the debugger the location of a variable based on the PC value.
.debug_line	Contain a description of the mapping from PC (program counter) values / code addresses to source locations. Also specifies which instructions are part of function prologues and epilogues.
.debug_macinfo	Macro information
.debug_pubnames	Is an index to help fetching of symbol debug information without having to scan object files.
.debug_pubtypes	Is an index to help fetching of type information.

DWARF uses a data structure called a Debugging Information Entry (DIE) to represent each variable, type, procedure, etc. A DIE has a tag (e.g., DW_TAG_variable, DW_TAG_pointer_type, DW_TAG_subprogram) and attributes (key-value pairs). A DIE can have nested (child) DIEs, forming a tree structure. A DIE attribute can refer to another DIE anywhere in the tree—for instance, a DIE representing a variable would have a DW_AT_type entry pointing to the DIE describing the variable's type; this is a "local" reference. DIE also allows referencing an arbitrary other DWARF entry (even one that's in a different .debug_info section), or to reference an entry in the common block by name.

DWARF includes an encoding for arbitrary arithmetic expressions, a bytecode for a specialized DWARF expression stack machine. This expression is most commonly used to describe the location of an unmoving object in memory (DW_AT_location). The other way to describe the location is to use a location list .debug_loclist, which is mainly for objects with variable addresses (e.g. dynamically allocated).

.debug_line (and .debug_line_str) contain line number information, which is highly redundant yet not easily compressed using regular means. DWARF addressses this problem by defining another bytecode format that defines a simple, special-purpose finite-state machine. When the FSM embodied in such a line-number program is run, it yields the full line-number table.

Much of the excess size in DWARF is due to duplicate information, e.g. from numerous complex header inclusions in C and C++. The DWARF writer should take care to use the referencing facilities in DIE, e.g. by arranging code into compilation units and types into type units that can be deduplicated and referenced easily. It may also be reasonable to give each header file their own unit.

Adoption

ELF

In the ELF format, DWARF data is mainly stored wiith the standard section names starting with .debug in the same file as the executable code .text. An alternative is to create a separate code-less ELF file that contains only the debug information ("symbols"), so that DWARF data can be installed and loaded only when needed. debuginfod is a program for retriving sections stored in separate files.

In addition to naively storing as ELF sections, many tools also support a variant where the DWARF sections are compressed, in which they decompress the sections as needed. The old GNU style of has all sections renamed from "debug" to "zdebug"; the section would contain a header that describes the compression method (usually zlib) and original size. The new, standard gABI style adds an ELF_COMPRESSED flag to the section flags, allowing most ELF section to use this feature. Despite the clever encoding schemes built into DWARF, DWARF data remains highly compressible.

Support for the DWARF version depends on the compiler and debugger combination, but in most cases DWARF 5 is used.

Mach-O

The Mach-O format used by macOS supports stabs and DWARF. The stabs format, which directly embeds debugging information into the symbol table LC_SYMTAB, still sees active use in developmental contexts where it is stored directly with the code. Although it is technically also possible to store the DWARF data with the code, the system's tools generally expect debugging data to be provided in separate, code-less "dSYM" object files. Such object files only contain a "__DWARF" segment, under which there are sections labeled "__debug_info" etc., corresponding to the standard DWARF sections.

The DWARF version is 4 or 5, depending on the OS version. Compressed debug info is not used or understood by official tools.

Tools

Libdwarf is a library that provides access to the DWARF debugging information in executable files and object files.

elfutils contains tools for manipulating ELF sections, e.g. to merge debug information into a file or to split it out into a different file.

Further reading

Michael Eager, chair of the DWARF Standards Committee, has written an introduction to debugging formats and DWARF 3, Introduction to the DWARF Debugging Format.

External links

• Official website
• Libdwarf, a C library intended to simplify reading (and writing) applications using DWARF2, DWARF3.
• elfutils, another C library for ELF/DWARF file processing.
• How debuggers work: Part 3 - Debugging information
• Debugging formats DWARF and STAB