https://github.com/aremmell/libsir
The Standard Incident Reporter library: A lightweight, cross-platform library for information distribution.
https://github.com/aremmell/libsir
ansi-colors c c17 cpp20 cross-platform log-to-anywhere log-to-console log-to-multiple-files log-to-syslog logging-library no-dependencies plugins thread-safe
Last synced: 4 months ago
JSON representation
The Standard Incident Reporter library: A lightweight, cross-platform library for information distribution.
- Host: GitHub
- URL: https://github.com/aremmell/libsir
- Owner: aremmell
- License: mit
- Created: 2013-08-13T02:12:28.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2025-12-04T04:27:35.000Z (7 months ago)
- Last Synced: 2025-12-06T00:58:31.268Z (7 months ago)
- Topics: ansi-colors, c, c17, cpp20, cross-platform, log-to-anywhere, log-to-console, log-to-multiple-files, log-to-syslog, logging-library, no-dependencies, plugins, thread-safe
- Language: C
- Homepage: https://libsir.rml.dev/
- Size: 10.5 MB
- Stars: 34
- Watchers: 3
- Forks: 5
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# libsir
libsir—a lightweight, cross-platform library for information distribution
[](https://github.com/aremmell/libsir/releases/latest)
[](https://github.com/aremmell/libsir/commits/master)
[](https://github.com/aremmell/libsir/blob/master/LICENSE)
[](https://www.openhub.net/p/libsir/)
[](https://gitlab.com/libsir/libsir/pipelines/master/latest)
[](https://coveralls.io/github/aremmell/libsir)
[](https://scan.coverity.com/projects/aremmell-libsir)
[](https://api.reuse.software/info/github.com/aremmell/libsir)
[](https://sonarcloud.io/component_measures?id=aremmell_libsir&metric=new_maintainability_rating&view=list)
[](https://sonarcloud.io/component_measures?id=aremmell_libsir&metric=new_reliability_rating&view=list)
[](https://sonarcloud.io/component_measures?id=aremmell_libsir&metric=new_security_rating&view=list)
[](https://securityscorecards.dev/viewer/?uri=github.com/aremmell/libsir)
[](https://www.bestpractices.dev/en/projects/7861)
- [Synopsis](#synopsis)
- [Notables](#notables)
- [Cross-platform compatibility](#cross-platform-compatibility)
- [System Loggers](#system-loggers)
- [C++ compatibility](#c---compatibility)
- [Language Bindings](#language-bindings)
- [An example](#an-example)
- [Building from source](#building-from-source)
- [Unix Makefile](#unix-makefile)
- [Environment Variables](#unix-makefile-envvars)
- [Recipes](#unix-makefile-recipes)
- [Visual Studio Code](#visual-studio-code)
- [Build Tasks](#vs-code-build-tasks)
- [Visual Studio 2022](#visual-studio-2022)
- [MSBuild](#ms-build-tools)
- [Dig in](#dig-in)
- [GNU Global](#gnu-global)
- [SAST Tools](#sast-tools)
- [Other Tools](#other-tools)
libsir is a cross-platform, thread-safe logging library written in C (*ISO/IEC 9899:2011 C11*) that is designed to simplify and streamline the generation and distribution of human-readable information in software.
Using libsir, you can make a single call that simultaneously sends information to multiple destinations, *each with their own individual preference for format and levels*.
Each 'level' or 'priority' of output can be visually styled however you wish for `stdio` destinations. This allows for immediate visual confirmation that a message appeared in the terminal that you should pay attention to, while less pressing information is more subtle in appearance.
- No dependencies (other than `libc` and `pthreads`). On Windows, libsir uses the native synchronization API.
- Accompanied by a robust test suite to ensure dependable behavior, even if you make modifications to the source.
- Won't fail silently—C library or platform level errors are captured and stored for posterity, on a per-thread basis. The *function, file, and line number from which it originated* are also captured. Additionally, libsir defines its own set of error messages to aid in troubleshooting.
- Hardened—every function contains sanity checks for internal state as well as arguments passed in through the external interfaces. libsir's standard make recipes use *‑Wall ‑Wextra ‑Wpedantic* (and pass with *‑Wmissing‑prototypes ‑Wdouble‑promotion ‑Wfloat‑conversion ‑Wmissing‑declarations ‑Wswitch‑enum ‑Wformat‑nonliteral ‑Wformat‑truncation ‑Wbad‑function‑cast ‑Wextra‑semi‑stmt*, too.)
- [Full documentation](https://libsir.rml.dev), thanks to Doxygen.
- Lightweight—the shared library comes in at around 70 KiB, and the static library around 50 KiB.
## Cross-platform compatibility
At this time, libsir is supported (*that is, it compiles and passes the test suites*) on at least the following operating system and toolchain combinations:
| System | Toolchain |
| ------:|:--------- |
| **Linux** ≳2.6.32
(glibc ≳2.4, musl ≳1.2.3, uClibc‑ng ≳1.0.43) | **GCC** (4.4.7 ‑ 15.0.1), **Clang** (3.8 ‑ 20.1.1), **Oracle Studio C/C++** (≳12.6), **Circle** (1.0.0‑210 ‑ 1.0.0‑226), **IBM Advance Toolchain** (14 ‑ 17), **IBM XL C/C++** (16.1.1.2 ‑ 16.1.1.15), **IBM Open XL C/C++** (17.1.1 ‑ 17.1.1.2), **NVIDIA HPC SDK C/C++** (23.5 ‑ 25.3), **Arm HPC C/C++** (22.1 ‑ 24.10.1), **DMD ImportC** (2.104.2 ‑ 2.111.0), **AMD Optimizing C/C++** (4.0.0 ‑ 5.0.0), **Intel oneAPI DPC++/C++** (2023.1 ‑ 2025.1.0), **Open64** (5, AMD 4.5.2.1), **Intel C++ Compiler Classic** (2021.9.0 ‑ 2021.10.0), **Portable C Compiler** (1.2.0.DEVEL‑20230730), **Kefir** (≳0.3.0), **Chibicc** (2020.12.6), **CompCert C** (3.11 ‑ 3.15, no‑TLS), **Chamois‑CompCert C** (3.14‑20231130+, TLS), **МЦСТ LCC** (1.25 ‑ 1.29) |
| **Android** ≳5 | **Android NDK** (r25c ‑ r28) |
| **QNX** 8.0 | **QCC** (GCC 12.2) |
| **IBM AIX** 7.2, 7.3 | **GCC** (8.3 ‑ 12.3), **Clang** (18.1.2 ‑ 20.1.0), **IBM XL C/C++** (16.1.0.3 ‑ 16.1.0.20), **IBM Open XL C/C++** (17.1.1.1 ‑ 17.1.3.1) |
| **IBM i** (**PASE**) 7.5 | **GCC** (10.3 ‑ 10.5), **IBM XL C/C++** (16.1.0.15 ‑ 16.1.0.20) |
| **macOS** ≳10.15 | **Xcode** (11.7 ‑ 16.3), **GCC** (10.4 ‑ 14.2), **Clang** (11.0.3 ‑ 19.1.7), **DMD ImportC** (2.105.0 ‑ 2.111.0), **Intel C++ Compiler Classic** (2021.9.0 ‑ 2021.10.0) |
| **Windows** ≳10, 11 | **Microsoft Visual C/C++** (17.6 ‑ 17.13.5), **Clang‑CL** (16.0.6 ‑ 20.1.1), **GCC‑MinGW** (12.2.1 ‑ 14.2.1), **LLVM‑MinGW** (15.0 ‑ 20.1.1), **Embarcadero C++** (7.20 ‑ 7.70), **OrangeC** (≳6.71.10) |
| **Cygwin** 3.4 | **GCC** (11.2 ‑ 15.0) |
| **FreeBSD** ≳11.3 | **GCC** (11.4 ‑ 14.2), **Clang** (10 ‑ 19.1.7), **DMD ImportC** (2.105.0 ‑ 2.111.0) |
| **NetBSD** 9.2, 10 | **GCC** (7.5 ‑ 14.2), **Clang** (15.0.7 ‑ 18.1.8) |
| **OpenBSD** 7.3 | **GCC** (11.2), **Clang** (13 ‑ 18.1.8), **DMD ImportC** (2.106.0 ‑ 2.111.0) |
| **DragonFly** **BSD** 6.4 | **GCC** (8.3 ‑ 13), **Clang** (10.0.1 ‑ 17.0.6) |
| **GNU/Hurd** | **GCC** (9.5 ‑ 13.2), **Clang** (9.0.1 ‑ 13.0.1) |
| **Haiku** R1b4 | **GCC** (11.2 ‑ 13.3), **Clang** (12.0.1 ‑ 20.1.0) |
| **Solaris** 11.4 | **GCC** (10.3 ‑ 11.2), **Clang** (6 ‑ 18.1.8), **Oracle Studio C/C++** (≳12.6) |
| **illumos** | **GCC** (7.5 ‑ 14.2), **Clang** (15.0.7 ‑ 19.1.7), **Oracle Studio C/C++** (≳12.6) |
| **SerenityOS** | **GCC** (13.1) |
| **Managarm** | **GCC** (14.2) |
| **WebAssembly/JS** | **Emscripten** (3.1.45 ‑ 4.0.5), **Node.js** (20.5.0 ‑ 23.10.0) |
* libsir is known to work on most common (and many uncommon) architectures. It has been built and tested on **Intel** (x86\_64, i686, x32), **ARM** (ARMv6, ARMv7HF, ARMv8‑A), **POWER** (PowerPC, PPC64, PPC64le), **MIPS** (MIPS64, MIPS32, 74Kc), **SPARC** (SPARC64, V8, LEON3), **z/Architecture** (S390X), **SuperH** (SH‑4A), **RISC‑V** (RV32, RV64), **OpenRISC** (OR1200), **Kalray MPPA®** (Coolidge™, KVX), **МЦСТ Эльбрус** (E2K), and **m68k** (ColdFire, 68020+).
* This table only lists toolchains that have been tested and is by no means exhaustive—newer (or older) versions are likely to work without fanfare. In fact, if it *doesn't* work on your machine, it's probably a bug.
libsir currently supports the following system logging facilities:
| **Log Facility** | **System** | **Description** |
|----------------------:|:-----------|:-------------------------------------------------------|
| **Event Log** | Windows | System log viewable with **Event Viewer** |
| **os_log** | macOS | System log viewable with **Console** (*or `log`*) |
| **syslog** | (*many*) | BSD-style system logging via `syslog()` (*local only*) |
* A C++20 [header-only wrapper](https://github.com/aremmell/libsir/blob/master/include/sir.hh) is available which allows for easy integration with C++ projects, including optional support for popular formatting libraries:
{fmt}
std::format
Boost.Format
std::iostream
* [Bindings](https://github.com/aremmell/libsir/tree/master/bindings) for scripting tools and other high-level programming languages are available, including support for:
Some sample terminal output from libsir demonstrating the default text styling settings for stdio (*note that this is just a sample; libsir supports 4, 8, and 24-bit color modes, so a virtually limitless number of configurations are possible*):
This output is from the `example` application, whose source code can be located in the [example](https://github.com/aremmell/libsir/tree/master/example) directory. If you're curious about a very basic implementation of libsir in a practical context, that's a good place to start.
**Coming soon:** A C++20 version of the example program.
There are several options available for building libsir from source:
The Makefiles are compatible with **GNU Make** version **3.81** and later (**4.4** *recommended*) and support both native and cross-compilation builds on most Unix-like operating systems: AIX, Solaris, illumos, Linux, macOS, Cygwin, BSD, GNU/Hurd, Haiku, QNX, etc.
A number of environment variables are available which affect the way in which libsir and its various build artifacts are created (*e.g., turning off optimizations and enabling debug symbols*). Information about these variables and how to use them with GNU make can be found in the [online documentation](https://libsir.rml.dev/config.html).
| Recipe Type | Command | Output file(s) |
|----------------------:|:----------------:|:-----------------------------------------------|
| Test suite (C) | `make tests` |
- *build/bin/sirtests[.exe]*
| Test suite (C++) | `make tests++` |
- *build/bin/sirtests++[.exe]*
| Example app | `make example` |
- *build/bin/sirexample[.exe]*
| Static library | `make static` |
- *build/lib/libsir_s.a*
| nShared library | `make shared` |
- *build/lib/libsir.so*
| Installation | `make install` |
- *$PREFIX/lib/libsir_s.a*
- *$PREFIX/lib/libsir.so*
- *$PREFIX/include/sir.h*
- *$PREFIX/include/sir/\*.h*
- See the [CI configuration file](https://github.com/aremmell/libsir/blob/master/.gitlab-ci.yml) for practical examples.
A VS Code workspace file is located in the root of the repository (`sir.code-workspace`). Build tasks are only configured for macOS and Linux. On other platforms, use the integrated terminal to run GNU [`make`](#unix-makefile) manually.
#### Build Tasks
To run a task, open the command list (⌘ + ⇧ + P on macOS, ⌃ + ⇧ + P on Linux), then start typing `"run task"` until you see `"Tasks: Run Task"`. Click the item or press the key combination listed next to it. You should then see a drop-down menu containing all of the build tasks for libsir, which are listed here:
| Build Task | Description |
|---------------------:|:-----------------------------------------------------------------|
| Clean | Deletes all intermediate files and previously compiled binaries. |
| Static Library | Compiles libsir as a static library. |
| Static Library [DBG] | Compiles libsir as a static library with debug symbols. |
| Shared Library | Compiles libsir as a shared library. |
| Shared Library [DBG] | Compiles libsir as a shared library with debug symbols. |
| C Test Suite | Compiles the C test suite. |
| C Test Suite [DBG] | Compiles the C test suite with debug symbols. |
| C++ Test Suite | Compiles the C++ test suite. |
| C++ Test Suite [DBG] | Compiles the C++ test suite with debug symbols. |
| C Example App | Compiles the C sample application. |
The VS Code build tasks execute `make` under the hood—the non-debug tasks map directly to the [recipes](#unix-makefile-recipes) listed under Unix Makefile; the debug tasks utilize libsir's custom [environment variables](#unix-makefile-envvars) to control the build process.
A Visual Studio 2022 solution containing appropriate project files can be found in the [msvs](https://github.com/aremmell/libsir/tree/master/msvs) directory. Tested on Windows 11 (*x86, x64, and Arm64*) with Visual Studio 17.6+. See the [README](https://github.com/aremmell/libsir/tree/master/msvs/README.md) for more information.
Visual Studio is technically not required in order to build the Visual Studio 2022 solution; this may also be accomplished using "Build Tools for Visual Studio 2022" ([download](https://aka.ms/vs/17/release/vs_BuildTools.exe), [reference](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-command-line-reference?view=vs-2022)). This is a stand-alone toolchain that does *not* require Visual Studio 2022 and includes compilers and MSBuild.
**Using MSBuild from the command-line**
Using MSBuild is pretty straightforward. Start a Developer Command Prompt, and then just supply the path to the `.sln` file, task (*e.g. `build`*), configuration (*e.g. `release`*), and platform (*e.g. `x64`*). Here's an example that builds libsir in release mode for x86_64 when executed from the root of the libsir repository:
```ps
MSBuild .\msvs\libsir.sln -t:Rebuild -p:Configuration=Release -p:Platform=x64
```
If you are genuinely interested in utilizing libsir, you are encouraged to read the [full online documentation](https://libsir.rml.dev) to get a better understanding of the library's capabilities and interfaces.
Suggested initial sections:
* [Public Functions](https://libsir.rml.dev/group__publicfuncs.html)
* [Public Types](https://libsir.rml.dev/group__publictypes.html)
* [Configuration](https://libsir.rml.dev/config.html)
* [Test suite](https://libsir.rml.dev/testsuite.html)
* [A GNU Global-generated tagged and cross-referenced hypertext source code listing is available.](https://libsir.gitlab.io/libsir)
* This tagged listing is a valuable aid for new developers seeking an understanding of the libsir source code.
The developers are obsessed with the quality, reliability, and correctness of libsir.
The following **SAST** (*static application*/*analysis security*/*software testing*) and dynamic verification tools are used—on **every commit**—as part of our comprehensive [continuous integration](https://gitlab.com/libsir/libsir/-/pipelines) testing process:
| Tool | Usage |
|-----:|:------|
| [**PVS-Studio**](https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source) | Static analysis tool for C, C++, C#, and Java code |
| [Clang Analyzer](https://clang-analyzer.llvm.org/), [Sanitizers](https://github.com/google/sanitizers) | Static and dynamic analysis tools for C, C++, and Objective-C code |
| [Coveralls](https://coveralls.io/github/aremmell/libsir), [gcovr](https://gcovr.com/) | Line-by-line test coverage reporting and statistical analysis |
| [Coverity® Scan](https://scan.coverity.com/projects/aremmell-libsir) | Find and fix defects in Java, C/C++, C#, JS, Ruby, and Python code |
| [Cppcheck](https://cppchecksolutions.com/) | Static analysis tool for C and C++ code |
| [DUMA](https://github.com/johnsonjh/duma) | Detect Unintended Memory Access, a memory debugger |
| [Flawfinder](https://dwheeler.com/flawfinder/) | Scans C and C++ source code for potential security weaknesses |
| [GCC Static Analyzer](https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html) | Coverage-guided symbolic execution static analyzer for C code |
| [GNU Cppi](https://www.gnu.org/software/cppi/) | C preprocessor directive linting, indenting, and regularization |
| [GNU Global](https://www.gnu.org/software/global/) | Source code indexing and tagging system |
| [OpenOSC](https://github.com/cisco/OpenOSC) | Object size checking library to detect buffer overflows in C/C++ code |
| [Oracle Developer Studio](https://www.oracle.com/application-development/developerstudio/) | Performance, security, and thread analysis tools for C, C++, and Fortran |
| [REUSE](https://api.reuse.software/info/github.com/aremmell/libsir) | Verifies compliance with the [REUSE](https://reuse.software/) licensing guidelines |
| [Semgrep](https://semgrep.dev/) | A fast, open-source, static analysis engine for many languages |
| [SonarCloud](https://sonarcloud.io/project/overview?id=aremmell_libsir) | Cloud-based code quality and security analysis tools |
| [Valgrind](https://valgrind.org/) | Tools for memory debugging, memory leak detection, and profiling |
| [Visual Studio Code Analyzer](https://learn.microsoft.com/en-us/cpp/code-quality/) | Tools to analyze and improve C/C++ source code quality |
Additional tools used for libsir development and testing include:
| Tool | Usage |
|-----:|:------|
| [CBMC](http://www.cprover.org/cbmc/), [ESBMC](http://esbmc.org/) | Bounded Model Checkers for C and C++ programs |
| [Dr. Memory](https://drmemory.org/) | Memory debugging tool for Windows, Linux, macOS, and Android |
| [Funcheck](https://github.com/tmatis/funcheck) | A tool for checking function call return protections |
| [Frama-C](https://frama-c.com/) | Framework for Modular Analysis of C programs |
| [Intel® VTune™ Profiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html) | Performance analysis and profiling tools for Intel systems |
| [Luke Stackwalker](https://lukestackwalker.sf.net/) | Sampling C/C++ code profiler for Microsoft Windows |
| [NetBSD lint(1)](https://man.netbsd.org/lint.1) | A C (C90/C99/C11/C17/C23) program verifier |
| [PurifyPlus™](https://www.teamblue.unicomsi.com/products/purifyplus/) | Run-time analysis tools for application reliability and performance |
| [ShellCheck](https://www.shellcheck.net/) | A static analysis tool for Unix shell scripts |
| [Smatch](https://repo.or.cz/w/smatch.git) | Smatch (Source Matcher) is a static analysis tool for C code |
| [SoftIntegration Ch](https://www.softintegration.com/) | C/C++ interpreter and interactive platform for scientific computing |
| [Very Sleepy](http://www.codersnotes.com/sleepy/) | Sampling CPU profiler for Microsoft Windows applications |
| [Vftrace](https://github.com/SX-Aurora/Vftrace) | A performance profiling library with a focus on HPC applications |