• Dependencies
• Usage
• Commands to work with debug information
• Unwinding-related gcc options
• Useful links

• The 1st goal of the project is to enable C/C++ (and in future other languages) developers to get informative stack trace in case of program crash, for example inside of segmentation fault handler. The key feature is to log not only function address/name/line but additionally (if DWARF .debug_info section is present) function's parameters and variables and their values.

• The 2nd goal is to enable C/C++ (and in future other languages) developers to provide an API to make their own debug facilities on base of PSTrace library.

• The 3rd goal is to enable C/C++ (and in future other languages) developers to provide an API to profile their programs internally instead of external tools.

Currently development is focused on x86_64 architecture and for Linux OS, but further may be expanded to other architectures and OS if it will be demanded and some people will like to contribute to the project to support this architecture and OS.

As a first sub-stage of 1st goal is to handle only C/C++ base types such as pointer, boolean, integer etc (done).

As a second sub-stage of 1st goal is to handle dereferenced pointers to data types with pointer validation (done).

As a third sub-stage of 1st goal is to handle composite types such as a C structures, arrays, C++ classes, etc (in progress).

Currently library mostly depends on libunwind library which used to unwind function's stack frames from stack in signal handler, libdw library which gives access to DWARF information of executed process if it present and libiberty which provides demangling of function names for C++ and other languages.

To build, install these packages:

1. sudo apt-get install libdw-dev libunwind-dev libiberty-dev

2. git clone https://github.com/nnosov/pstrace

3. cd pstrace

4. make

As an example how to use library, see tests/main.c

produce very simple debug info without sources echo 'void foo () {}' | gcc -g -O99 -o - -S -xc - -dA | grep frame_base

dump .debug_info section

readelf --debug-dump=info ./build/trace

objdump --dwarf=info ./build/trace

dump symbol tables of executable

readelf -s ./build/trace

dump file segment headers

readelf -l ./build/trace

dump .eh_frame section

readelf --debug-dump=frames simple

dump list of sections

readelf -S ./build/trace

dump lie section

objdump --dwarf=decodedline

disassemble executable

objdump --d ./build/trace

-funwind-tables tells linker to generate .eh_frame section containing CFI. enabled by default if gcc/g++ used for linking

-fexceptions Enable exception handling. Generates extra code needed to propagate exceptions.

-rdynamic exports the symbols of an executable, allows to print function names in backtrace

-fno-omit-frame-pointer instructs the compiler to store the stack frame pointer in a register RBP for x86_64.

Calling conventions

Functions and stack frames

x86 Assembli guide

GNU extended Asm

DWARF 5 Standard (DWARF comittee)

Introduction to the DWARF Debugging Format (DWARF comittee)

Exception handling (DWARF wiki)

Expression Operator For Constants (DWARF Wiki)

Very good explanation what's CFA on x86_64

Very informative discussion on dwarf mailing lists about DW_OP_regX vs. DW_OP_bregX 0

Very informative discussion on dwarf mailing list about Semantics of DW_OP_(b)reg

DW_AT_call_site_XXX (which currently is DW_AT_GNU_call_site_XXX) explanation

Exploring the DWARF debug format information (IBM)

DWARF: function return value types and parameter types (simple tutorial)

Exploiting the Hard-Working DWARF (slides)

Exploiting the Hard-Working DWARF (article)

Local variable location from DWARF info in ARM

Reliable and Fast DWARF-Based Stack Unwinding

Improving debug info for optimized away parameters (GCC summit 2012, GNU extensions)

VARIABLE TRACKING AT ASSIGNMENTS (Redhat, with link to GCC Wiki)

Good .eh_frame explanation

Good itroduction to Debug information

libdwarf example

System V ABI

Programmatic access to the call stack in C++

Where the top of the stack is on x86

Stack frame layout on x86-64

Retrieving function arguments while unwinding the stack

Deep Wizardry: Stack Unwinding (more-less helpful)

Writing a Linux Debugger Part 8: Stack unwinding (other related articles also interesting)

Testing pointers for validity (C/C++) (using system calls)

Another way for testing pointer to validity (via procfs)

Implementing a Debugger: The Fundamentals