Various patterns for safer C programming have been cargo-culting around the industry for decades. Because the language evolves intentionally slowly, these patterns rarely get folded into the language as first-class constructs and are passed down through the generations in a sort of oral tradition of programming.
lib0xc leverages GNUC extensions and C11 features to codify safer C practices and patterns into real APIs with real documentation and real testing. Reduce your casts to and from `void *` with the `context_t` tagged pointer type. Enable type-checked, deferred function invocation with `call_t`. Interrogate structure descriptors with `struct_field_t`. Stop ignoring `-Wint-conversion` and praying you won't regret it when you assign a signed integer to an unsigned integer and use `__cast_signed_unsigned`. These are just a few of lib0xc's standard-library-adjacent offerings.
lib0xc also provides a basic systems programming toolkit that includes logging, unit tests, a buffer object designed to deal with types, a unified Mach-O and ELF linker set, and more.
Everything in lib0xc works with clang's bounds-safety extensions if they are enabled. Both gcc and clang are supported. Porting to another environment is a relatively trivial effort.
It's not Rust, and it's not type safety, but it's not supposed to be. It's supposed to help you make your existing C codebase significantly safer than it was yesterday.
My employer holds the copyright and has permitted its release under the MIT license.
Two notes: GCC has its "access" attributes which can give you similar bounds safety as clang.
Please see also my experimental library. https://codeberg.org/uecker/noplate/ While I do not had enough time to polish it yet, I think it provides some very nice interfaces with improve type and bounds safety, and are also rather convenient.
Also I wonder what parts are redundant if you have FORTIFY_SOURCE ?
(And thank you for working in this topic. If you continue, please reach out to us)
What do you think C would need in order to reach the user experience of those languages?
If you get compiler errors, it means you were printing to a heap-allocated buffer (or a buffer whose bounds you did not know), and you should be propagating bounds and using `snprintf`.
Integer conversion is the same way. If you have something like
int v1; uint64_t v2;
<stuff happens>
v2 = (uint64_t)v1;
Then you can replace it with
v2 = __cast_signed_unsigned(uint64_t, v1);
and you'll get a runtime trap when v1 is a negative value, meaning you can both enable -Wint-conversion and have defined behavior for when the value in a certain integer type is not representable in another.
The C committee at least seems to get it now. The C++ committee still doesn't, led in large part by Bjarne.
Anything needs to be demonstrated and used in practice before being included in the standard. The standard is only meant to codify existing practices, not introduce new ideas.
It's up to compiler developers to ship first, standardize later.
I really need to learn more about Zig, but from what I know, there are still worlds of possibilities that a modern, well-designed language offers over something like lib0xc. Zig's ability to evaluate any expression at compile-time is one such example.
But generally, lib0xc gives you bounds-safety everywhere it can. Languages like Zig and Rust give you type-safety to their own degrees, which I think is a superset.
> What do you think C would need in order to reach the user experience of those languages?
Not really having direct user experience, it's hard for me to say. But if I what I can give you is a list of features that would make large parts of lib0xc irrelevant:
1. Protocols/traits
2. Allocating from a caller's stack frame (think, returning the result of `alloca` to the caller)
3. printf format specifiers for stdint.h types and for octet strings
4. Ability to express function parameter lists as structures
5. New sprintf family that returns a value which is always less than or equal to the size passed (no negative values)
Basically, I think that the C standard should be working aggressively to cut down on the use cases for heap allocation and `void *`. And I think that the bounds safety annotations should become first-class language features.
A set of C standard library-adjacent APIs for safer systems programming. While C cannot be made completely type- and bounds-safe at the language level, its prevailing uses can be made much safer than they are today.
"Make C safer" is a nebulous and amorphous goal, and it is more apt as a programming language design statement than a modest set of utilities. With that in mind, lib0xc has the following concrete goals.
-Wall -Wextra -Werror -WeverywhereThat last one isn't real, but still, lib0xc's goal is to make it possible for projects to turn on as many warnings as possible and to fail to build if code introduces new warnings. Often, certain high-value warnings are disabled because a project wants to, e.g.
-Werror, andConcerns like this are frontmost in lib0xc's API design.
lib0xc's APIs are deliberately named and designed to look like functions they'd replace from the standard library and be drop-in replacements where appropriate.
None of lib0xc's APIs assume that an allocator is available (with the exception
of APIs which provide utility specifically for allocations). Many of lib0xc's
APIs are designed to be used with fixed-sized data structures (e.g. structs or
array types) and assert that size information for a particular argument is
available at compile-time.
To achieve this, lib0xc leans heavily on the C preprocessor to expose its API surface. Many of its APIs are macros. While not a panacea, restricting code to using fixed-size objects (and avoiding dynamic allocations) makes C generally much safer.
-fbounds-safetylib0xc's API surface fully embraces the clang bounds safety extensions, which leverage macros that can safely expand to nothing to indicate the bounds of memory referred to by pointers, making them source-compatible with existing C code.
Many of the APIs that lib0xc exposes have existed in various forms in the industry, perhaps for decades. lib0xc does not claim to have brilliantly conceived of the idea behind every API it exposes. Instead, it seeks to provide codified representations of these patterns which are well-documented and thoroughly-tested.
Related to the previous goal, the patterns encapsulated by lib0xc APIs should have a large "pit of success", that is, they are easier to use properly than they are to mis-use. Many of the C language's liabilities stem from poorly- designed API contracts, and where such APIs have lingered, lib0xc seeks to offer better thought-out replacements.
0xc/std/)| Module | Standard Library Analogue | Description |
|---|---|---|
| alloc.h | n/a | Typed allocation, automatic cleanup |
| call.h | n/a | Deferred function invocation |
| context.h | n/a | Bounds-checked context pointer |
| cursor.h | FILE * |
Allocation-free, in-memory input/output stream |
| int.h | stdint.h |
Safe integer conversions |
| io.h | stdio.h |
Formatted output utilities |
| pointer.h | n/a | Useful macros for clang -fbounds-safety |
| string.h | string.h |
Static variants of string functions |
| struct.h | n/a | Structure reflection and addressing |
| array.h | n/a | Utilities for array types |
| type.h | n/a | Type compatibility checks and compiler constant utilities |
| limits.h | limits.h |
Min/max value utilities for integer types |
0xc/sys/)| Module | POSIX Analogue | Description |
|---|---|---|
| buff.h | n/a | Bounded buffer encapsulation |
| log.h | syslog.h |
Object-oriented logging with simplified levels |
| hash.h | sys/queue.h |
BSD queue.h macro-style hash table |
| digest.h | n/a | Digest object |
| fourcc.h | n/a | Four-character codes |
| errno.h | errno.h |
POSIX error utilities |
| exit.h | sysexits.h |
sysexits(3) mappings to errno codes |
| queue.h | n/a | BSD queue(3) macros with bounds-safety annotations |
| linker_set.h | n/a | Unified, bounds-safe linker set for ELF and Mach-O |
| check.h | n/a | Simple unit test check functions |
| unit.h | n/a | Test harness with auto-discovery via linker sets |
CURSOR#include <0xc/std/cursor.h>
char buf[256];
CURSOR cur;
cbuffopen(&cur, buf, "w");
cprintf(&cur, "hello %s", "world"); // remaining space tracked automatically
#include <0xc/std/context.h>
struct my_state state;
context_t ctx = __context_export(struct my_state *, &state);
// Size is verified on import — mismatched type sizes will trap:
struct my_state *s = __context_import(struct my_state *, ctx);
#include <0xc/std/int.h>
// Traps at runtime on overflow instead of silently truncating:
size_t n = __cast_signed_unsigned(size_t, file_stat.st_size);
#include <0xc/std/io.h>
uint32_t v32 = 42;
uint64_t v64 = 100;
printf("%u %lu\n", oxou(v32), oxolu(v64)); // no PRIu32/PRIu64 needed
-std=gnu11)-fbounds-safety support)Build the POSIX static library:
make lib
This produces build/public/lib0xc.a for the host platform.
Run the full test suite (POSIX platforms):
make test
Tests are organized per-module and use the sys/unit.h API for registration and
the sys/check.h API for individual test case assertions.
src/ Portable source and headers (included by all targets)
0xc/std/ Standard library extension headers
0xc/std/call Call implementation
0xc/std/pointer Pointer tagging implementation
0xc/sys/ Systems programming utility headers
0xc/sys/buff Buffer object implementation and headers
0xc/sys/check Test case assertion implementation
0xc/sys/log Logging API implementation
posix/ POSIX target (macOS, Linux)
0xtest/ Test suite
unit/ Per-module unit tests
Each target directory contains a mk/ directory with its build files and a
0xc/ directory with any target-specific headers. Generally speaking, the src
directory's structure mirrors that of the final header hierarchy, with source
files living alongside their corresponding headers.
lib0xc can be adopted to new runtime environments and is not strictly tied to a POSIX-like environment. In order to build a lib0xc library for a new target, you need to provide the following:
std/alloc.h expects an implementation of __waiting_for_memory. Otherwise,
lib0xc assumes that malloc is provided by the host, if it is present at all.
If it is not present, then simply defined a stub for __waiting_for_memory and
avoid using the std/alloc.h header entirely.
sys/panic.h expects the following implementations:
panic: Panic with an associated integer valuepanicno: Panic with an error numberpanic0x: Panic with an associated integer value, expressed as hexadecimalpanicx: Panic with only a messageBuffer types specific for the target platform can be enumerated in a platform-
specific header in sys/buff/type. For example, the BUFF_TYPE_MMAP type is
specific to the POSIX library and encapsulates information for how to free the
underlying memory.
sys/log.h expects its error streams to be implemented as log_stream_t
objects. Error streams encapsulate the implementations for writing to the
platform's output device. For example, in the POSIX library, the streams are
mapped to the standard C standard output streams (standard input, output,
error) and are written to via vdprintf.
The platform header is expected to be in 0xc/platform.h and installed within
the public header hierarchy. This header contains publicly-visible configuration
parameters, currently:
ZX_WALLOC_LIMIT: The maximum limit at walloc will wait for memoryZX_LOG_LEVEL: The platform's log level; this can be different based on the
build variant of the library (e.g. the debug variant may have a higher level
than the release/production variant)This project welcomes contributions and suggestions. See CONTRIBUTING.md for details, including the Microsoft Contributor License Agreement (CLA) requirement.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
For instructions on reporting security vulnerabilities, see SECURITY.md. Please do not report security issues through public GitHub issues.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party's policies.
Copyright (c) Microsoft Corporation.
Licensed under the MIT License.
(We can do some stuff before this, but this is always a bit of a fight with the vendors, because they do not like it at all if we tell them what to do, especially clang folks)
Not all of the APIs were brain-dead. They just ignored all previous developments and in the proposal they didn't even remove the C++-related language.
Why Must C be safe, rather than people writing safer code in it or transfering to other languages if they cannot be bothered?
So the best hope is probably for a third party library that has safet APIs to get popular enough that it becomes a de facto standard.
Doesn't Apple have a nice `defer { }` block for cleanup? Did you include that in lib0xc? I didn't see in on your README.
I don't have any clue how to patch clang's front end. I'm not a language or compiler person. I just want to make stuff better. There needs to be a playground for people like me, and hopefully lib0xc can be that playground.
What lib0xc has is some cleanup attributes that you can apply to variables to e.g. automatically free a heap allocation or close a file descriptor, at end of scope. Personally, I like variable annotations much more than defer for these uses, but they accomplish the same thing. I've also found that using those attributes inherently pushes your code to make ownership more explicit. I personally stopped being terrified of double-pointers and started using them for ownership transfers, which eliminates a large class of bugs.
Maybe the compilers they support all have non-standard extensions that allow something like this though?
This is very interesting. Do you have a practical example?
And that suggested defer standard, is already available from GCC 9 and clang 22.
[0] https://www.open-std.org/JTC1/SC22/WG14/www/docs/n3734.pdf