# libbacktrace

Библиотека для генерации трассировок стека (backtraces) в программах на C и C++. Она предоставляет функции для получения списка вызовов функций в стеке, символизации адресов (преобразования адресов памяти в имена функций и номера строк) и работы с отладочной информацией. Библиотека разработана как часть проекта GCC, но может использоваться независимо в других компиляторах и средах выполнения.

## Особенности

- получение трассировок стека для текущего потока или другого потока в процессе;
- символизация адресов (имена функций, имена файлов, номера строк) при наличии отладочной информации;
- поддержка различных форматов отладочной информации (DWARF, STABS, COFF, PE, ELF, Mach-O);
- минимальные зависимости и возможность сборки как автономной библиотеки;
- поддержка работы в условиях ограниченной памяти и без выделения динамической памяти.

## Основные компоненты

libbacktrace предоставляет простой, но мощный API для работы с трассировками стека и символизацией (подробнее с документацией можно ознакомиться [здесь](https://github.com/ianlancetaylor/libbacktrace)).

### Инициализация и деинициализация

Библиотека предоставляет функции для создания и уничтожения контекста работы с трассировками. Контекст содержит информацию о состоянии программы и необходим для большинства операций.

Основные функции инициализации:

- `backtrace_create_state()` — создание контекста для работы с трассировками стека;
- `backtrace_release_state()` — освобождение ресурсов контекста (опционально, зависит от реализации);
- Автоматическое определение местоположения исполняемого файла и отладочной информации.

### Получение трассировок стека

Библиотека позволяет получить текущую трассировку стека или трассировку другого потока (если платформа это поддерживает). Функции возвращают массив адресов вызовов, которые затем могут быть символизированы.

Функции получения трассировок:

- `backtrace_full()` — получение полной трассировки стека с символизацией;
- `backtrace_simple()` — получение простой трассировки (только адреса);
- `backtrace_trace()` — альтернативный интерфейс для получения трассировки;
- Поддержка указания контекста (регистры, состояние потока) для анализа неактивных потоков.

### Символизация адресов

Одна из ключевых возможностей библиотеки — преобразование адресов памяти в символическую информацию (имена функций, исходные файлы, номера строк). Это требует наличия отладочной информации в исполняемом файле или отдельных файлах отладки.

Функции символизации:

- `backtrace_syminfo()` — получение символической информации для адреса (только имя функции);
- `backtrace_pcinfo()` — получение полной информации об адресе (функция, файл, строка);
- `backtrace_syminfo_callback` и `backtrace_full_callback` — callback-интерфейсы для обработки результатов;
- Поддержка различных источников отладочной информации (встроенная, отдельные файлы .debug, dSYM).

### Работа с отладочной информацией

libbacktrace умеет работать с различными форматами отладочной информации, что позволяет ей функционировать на разных платформах и с разными компиляторами.

Поддерживаемые форматы отладки:

- **DWARF** (версии 2-5) — основной формат для Linux, macOS, BSD;
- **STABS** — устаревший формат, поддерживается для совместимости;
- **COFF/PE** — формат для Windows (PE-файлы);
- **Mach-O** — формат для macOS и iOS;
- **ECOFF** — устаревший формат для некоторых UNIX-систем.

### Обработка ошибок и состояния

Библиотека предоставляет механизмы для обработки ошибок и получения информации о состоянии. Это полезно для отладки и создания надежных систем сбора трассировок.

Функции обработки ошибок:

- `backtrace_set_allocator()` — установка пользовательских функций выделения памяти;
- `backtrace_set_fileio()` — установка пользовательских функций для работы с файлами;
- Callback-функции для сообщения об ошибках в процессе работы;
- Возможность работы в условиях, где стандартные операции ввода-вывода недоступны.
