b_stacktrace

A minimalistic single-header multi-platform C89 lib for stack tracing, by Borislav Stanimirov.

Installation

Run:

$ npm i b_stacktrace.c

And then include b_stacktrace.h as follows:

// main.c
#define B_STACKTRACE_IMPL  // or B_STACKTRACE_IMPLENTATION
#include "node_modules/b_stacktrace.c/b_stacktrace.h"

int main() { /* ... */ }

And then compile with clang or gcc as usual.

$ clang main.c  # or, use gcc
$ gcc   main.c

You may also use a simpler approach:

// main.c
#define B_STACKTRACE_IMPL  // or B_STACKTRACE_IMPLENTATION
#include <b_stacktrace.h>

int main() { /* ... */ }

If you add the path node_modules/b_stacktrace.c to your compiler's include paths.

$ clang -I./node_modules/b_stacktrace.c main.c  # or, use gcc
$ gcc   -I./node_modules/b_stacktrace.c main.c

Usage

C or C++

Including b_stacktrace.h provides:

• char* b_stacktrace_get_string();- Returns a human-readable stack-trace string from the point of view of the caller. The string is allocated with malloc and needs to be freed with free.
• b_stacktrace_handle b_stacktrace_get(); - Returns a stack-trace handle from the point of view of the caller which can be expanded to a string via b_stacktrace_to_string. The handle is allocated with malloc and needs to be freed with free.
• char* b_stacktrace_to_string(b_stacktrace_handle stacktrace); - Converts a stack-trace handle to a human-readable string. The string is allocated with malloc and needs to be freed with free.
• int b_stacktrace_depth(b_stacktrace_handle stacktrace); - Returns the number of entries (frames) in the stack-trace handle.

#define B_STACKTRACE_IMPL before including b_stacktrace.h in one C or C++ file to create the implementation

Optional wrapper for C++17 and newer

TBD

Examples

The subdirectory example/ contains several small examples:

• trace.c - creates a trace from a C program
• trace.cpp - creates a trace from a C++ program, demonstrating more complex symbols (classes, templates)
• crash.c - example usage of the provided stack trace: as a crash handler

License

The library is distributed under the MIT Software License. Copyright © 2020-2025 Borislav Stanimirov.