{"id":19709221,"url":"https://github.com/ndryden/shbt","last_synced_at":"2026-04-21T16:31:41.646Z","repository":{"id":149713940,"uuid":"203008157","full_name":"ndryden/shbt","owner":"ndryden","description":"Signal handler/backtrace library","archived":false,"fork":false,"pushed_at":"2019-09-09T20:16:43.000Z","size":40,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-03T15:13:09.537Z","etag":null,"topics":["c","cpp","debugging"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ndryden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-18T13:39:12.000Z","updated_at":"2022-07-16T15:01:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"65d589af-00b9-4e54-90be-6c526fc124c2","html_url":"https://github.com/ndryden/shbt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ndryden/shbt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndryden%2Fshbt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndryden%2Fshbt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndryden%2Fshbt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndryden%2Fshbt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ndryden","download_url":"https://codeload.github.com/ndryden/shbt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndryden%2Fshbt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262963626,"owners_count":23391861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cpp","debugging"],"created_at":"2024-11-11T21:46:57.278Z","updated_at":"2026-04-21T16:31:36.603Z","avatar_url":"https://github.com/ndryden.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHBT: Signal Handler/Backtrace library\n\n_Note: SHBT is still in early development and APIs may change._\n\nSHBT provides a simple API for collecting backtraces and installing\nsignal handlers for C/C++ applications. The signal handlers provide\ndetailed signal information and a backtrace.\n\n### Motivation\n\nI find it a very useful debugging aide to get a backtrace whenever\nfatal signals (e.g. SIGSEGV) occur. However, writing a signal handler\nthat is _actually_ safe (`async-signal-safe`) is difficult; memory\nmanagement (`malloc`, etc.) and buffered I/O are unsafe, as is the\nbuiltin `backtrace` method. In many cases, this doesn't matter; your\nprogram is going to crash and burn anyway, so you might as well get\nwhat information you can out of it. In some cases, however, this can\nlead to very weird behavior, like a segmentation fault causing a hang\nbecause of a deadlock between your application and the signal handler.\n\nSome major projects (Chromium, for example) have addressed this within\ntheir codebases, but I could not find any standalone libraries to\naccomplish this. Hopefully it is useful to someone.\n\n## Supported platforms\n\nSHBT has been tested on the following operating systems / hardware\ncombinations:\n\nOS | Architecture\n-- | ------------\nLinux | x86-64\nLinux | POWER / PPC64\nmacOS | x86-64\n\nIf you would like to test and/or port SHBT to a different OS / arch\ncombination, please feel free.\n\n## Getting Started\n\nSHBT uses the [CMake](https://cmake.org/) build system. To build you\nwill need a standard C/C++ toolchain and\n[libunwind](https://www.nongnu.org/libunwind/) (see also\n[the LLVM version](https://github.com/llvm-mirror/libunwind)),\nwhich is probably installed by default with your toolchain.\n\n_Note_: On macOS, libunwind is not installed automatically. The\neasiest solution is to use Homebrew to install LLVM and then point\nCMake to it with `-D LIBUNWIND_DIR`.\n\nA simple build and install is the following:\n```\ncd shbt\nmkdir build install\ncd build\ncmake -D CMAKE_INSTALL_PREFIX=../install ..\nmake\nmake install\n```\n\n### Example\n\nSHBT can add signal handlers for all the standard fatal signals.\nBasically:\n\n```C\n#include \"shbt/shbt.h\"\n\n// Inside your main/startup/init function:\nshbt_register_fatal_handlers();\n```\n\n### Build Options\n\nThere are a few options for customizing the build (beyond the standard\nCMake ones). They are passed as options when running `cmake`.\n\n* `-D SHBT_ENABLE_MPI=YES|NO` (default: `NO`): Build with MPI support,\n  which will have the signal handler print out which rank in\n  `MPI_COMM_WORLD` the signal occurred on. This requires an MPI\n  installation, which is located using the standard\n  [FindMPI](https://cmake.org/cmake/help/latest/module/FindMPI.html)\n  CMake package.\n* `-D SHBT_DEMANGLER=BUILTIN_IA64|ABI` (default: `BUILTIN_IA64`):\n  Select the symbol demangler to use for demangling symbols, in order\n  to provide more human-readable function names for C++ code. Options:\n  * `BUILTIN_IA64` (the default): Uses a built-in, signal-handler-safe\n    demangler. This currently does not support the full demangling\n    process, but can generally give a good indication. When using\n    this, the original, mangled symbol is printed as well, in case\n    demangling fails. Something like `c++filt` can then be used to\n    demangle it.\n  * `ABI`: Uses the builtin C++ ABI demangling facilities.\n    **WARNING**: This is unsafe within signal handlers (it uses memory\n    allocation internally), and is intended only for unusual cases.\n\n## Documentation\n\nComing soon...\n\n## Testing\n\nThere is no comprehensive set of tests (yet), but see `tests` for some\nexamples of triggering signals and catching them.\n\n## Versioning\n\nThis project uses [Semantic Versioning](https://semver.org/). The\nproject is currently in development. See\n[the tags](https://github.com/ndryden/shbt/tags) for available\nversions.\n\n## Authors\n\n* [Nikoli Dryden](https://ndryden.com/)\n\nSee also the\n[list of contributors](https://github.com/ndryden/shbt/contributors).\n\n## License\n\nThis project is licensed under the\n[Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\nSee LICENSE for details.\n\n## Acknowledgements\n\nThis project is somewhat based on the signal handler/backtrace\ninfrastructure in Chromium -- see\n[here](http://phajdan-jr.blogspot.com/2013/01/signal-handler-safety-re-entering-malloc.html)\nfor some details.\n\nThis project also includes code adapted from the\n[Chromium](https://github.com/chromium/chromium)\nand\n[glog](https://github.com/google/glog)\nprojects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndryden%2Fshbt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndryden%2Fshbt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndryden%2Fshbt/lists"}