microsoft/lib0xc: Safe(ish) C programming library · GitHub

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.

That 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.

1. build with -Werror, and
2. avoid clumsy workarounds for things like portability

Concerns 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.

lib0xc’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.

#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

• C11 with GNU extensions (-std=gnu11)
• clang or gcc (clang recommended for -fbounds-safety support)
• GNUMake >= 3.81
• Supported platforms: macOS (arm64, x86_64), Linux (arm64, x86_64)

Build the POSIX static library:

This produces build/public/lib0xc.a for the host platform.

Run the full test suite (POSIX platforms):

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 value
• panicno: Panic with an error number
• panic0x: Panic with an associated integer value, expressed as hexadecimal
• panicx: Panic with only a message

Buffer 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 memory
• ZX_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.