A clean-room Rust libc project that can interpose on glibc today for a meaningful but still incomplete workload set, applies a Transparent Safety Membrane at the ABI boundary, and incrementally replaces unsafe libc behavior with native Rust implementations and raw-syscall paths.

There is no curl installer or package-manager release yet. The current fast path is:

git clone https://github.com/Dicklesworthstone/frankenlibc.git
cd FrankenLibC
cargo build -p frankenlibc-abi --release
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/echo "hello from FrankenLibC"

glibc is enormous, security-critical, and written in a language that cannot enforce memory safety at the ABI boundary. Existing Linux software still expects glibc-compatible symbols, calling conventions, and process semantics.

FrankenLibC puts a Transparent Safety Membrane (TSM) behind a glibc-shaped ABI. Every libc entrypoint can validate, sanitize, repair, deny, and audit before handing control to safe Rust code, raw Linux syscalls, or, where the project is not done yet, a constrained host-glibc call-through.

Current source of truth: tests/conformance/support_matrix_maintenance_report.v1.json.

# 1. Build the interpose artifact
cargo build -p frankenlibc-abi --release

# 2. Inspect the current symbol reality
cargo run -p frankenlibc-harness --bin harness -- reality-report \
  --support-matrix support_matrix.json \
  --output /tmp/frankenlibc-reality.json

# 3. Run something small in strict mode
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/echo strict

# 4. Run the same idea in hardened mode
FRANKENLIBC_MODE=hardened \
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/echo hardened

# 5. Run the membrane verification campaign
cargo run -p frankenlibc-harness --bin harness -- verify-membrane \
  --mode both \
  --output /tmp/healing_oracle.json

# 6. Check support-matrix maintenance drift
bash scripts/check_support_matrix_maintenance.sh

# 7. Run the preload smoke suite
TIMEOUT_SECONDS=10 bash scripts/ld_preload_smoke.sh

These examples show the kind of work FrankenLibC is meant to support.

You have a prebuilt C or C++ binary, you do not want to rebuild it, and you want a safer libc boundary for experiments:

FRANKENLIBC_MODE=hardened \
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" \
./legacy_binary

Why it helps:

• no relink step
• no source-code rewrite requirement
• explicit artifact path
• membrane and verification tooling can be layered around the run

You convert a symbol from GlibcCallThrough to Implemented, but you need to know whether reports still agree:

bash scripts/check_support_matrix_maintenance.sh

This catches one of the standard failure modes in replacement-library work: code and status claims drifting apart.

Instead of arguing abstractly about whether hardened mode "works," the repo has an explicit membrane verification path:

cargo run -p frankenlibc-harness --bin harness -- verify-membrane \
  --mode both \
  --output /tmp/healing_oracle.json

That fits the project well: behavior captured as an artifact rather than asserted in prose.

This project is only interesting if existing binaries can talk to it. The ABI boundary is the contract: symbol names, calling conventions, version scripts, errno, mode semantics, and process-level behavior.

Unsafe C inputs are not trusted. The TSM sits at the libc boundary and classifies pointers, regions, fds, and contexts before anything meaningful happens.

The project does not pretend the whole world is already reimplemented. Each exported symbol is explicitly classified as Implemented, RawSyscall, or GlibcCallThrough, and the matrix is machine-checked.

The codebase is not a line-by-line Rust port of glibc. Behavior is driven by contracts, fixtures, and verification artifacts rather than transliterating legacy C.

Support claims, mode semantics, fixture coverage, drift checks, smoke tests, and release gates all live in code and machine-generated artifacts. The README should summarize them, not replace them.

These invariants are meant to hold as the codebase grows:

Current source of truth: tests/conformance/support_matrix_maintenance_report.v1.json.

Declared replacement level claim: L0 — Interpose.

Total currently classified exports: 3980. Current native coverage (Implemented + RawSyscall): 100.0%.

Source of truth: tests/conformance/reality_report.v1.json (generated 2026-02-18T04:49:26Z).

Reality snapshot: total_exported=3980, implemented=3576, raw_syscall=404, glibc_call_through=0, stub=0.

In practice:

• The current shipping artifact is the interpose shared library: target/release/libfrankenlibc_abi.so.
• The future replace artifact (libfrankenlibc_replace.so) is still planned, not done.
• The classified symbol surface no longer reports direct GlibcCallThrough symbols, but the current shipping artifact is still an interpose-first preload library rather than a full standalone libc replacement.
• The latest broad preload smoke run is not fully green yet. As of March 23, 2026, the checked smoke artifact recorded 23 passes / 35 fails / 6 skips, and hardened mode remained unstable on that broader workload set.
• Small strict-mode repros such as echo, env, ls, sort, git --version, and du -s have been brought up successfully, but that does not yet mean the interpose artifact is broadly production-ready.

FrankenLibC focuses on the kinds of failures that become visible at the libc boundary.

The status taxonomy is the control system for the project’s staged migration.

Why this taxonomy exists:

• it distinguishes real ownership from temporary delegation
• it prevents “mostly implemented” from being vague
• it makes interpose and replace claims mechanically checkable
• it gives every symbol promotion a precise meaning

The project is no longer just an architecture sketch. Today’s repo contains:

It is useful to think of FrankenLibC as three things at once:

1. A libc interposition artifact you can run today on many workloads, with broader stabilization still underway.
2. A memory-safety and repair substrate at the libc ABI edge.
3. A verification-heavy engineering program for turning more of glibc into native Rust without hiding the unfinished parts.

FrankenLibC is useful anywhere the libc boundary is the last realistic place to impose safety or observability without rewriting the whole program.

FrankenLibC treats libc replacement as a staged engineering problem with explicit measurements, evidence, and safety goals.

Requirements:

• Linux
• Rust nightly with rustfmt and clippy
• A normal Cargo toolchain; this repo is a Rust workspace, not a mixed package-manager project

git clone https://github.com/Dicklesworthstone/frankenlibc.git
cd FrankenLibC
rustup toolchain install nightly
cargo build -p frankenlibc-abi --release

Output:

target/release/libfrankenlibc_abi.so

install -d "$HOME/.local/lib/frankenlibc"
install -m 755 target/release/libfrankenlibc_abi.so "$HOME/.local/lib/frankenlibc/"
LD_PRELOAD="$HOME/.local/lib/frankenlibc/libfrankenlibc_abi.so" /bin/echo hello

sudo install -d /usr/lib/frankenlibc
sudo install -m 755 target/release/libfrankenlibc_abi.so /usr/lib/frankenlibc/
LD_PRELOAD=/usr/lib/frankenlibc/libfrankenlibc_abi.so /bin/echo hello

• No curl installer
• No Homebrew formula
• No crates.io install path for the interpose library
• No distro packages

Replacing libc is hard for reasons that compound:

Those constraints are why FrankenLibC is staged, report-heavy, and explicit about what is real today versus merely planned.

cargo build -p frankenlibc-abi --release

cargo run -p frankenlibc-harness --bin harness -- reality-report \
  --support-matrix support_matrix.json \
  --output /tmp/frankenlibc-reality.json
cat /tmp/frankenlibc-reality.json

LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/ls

FRANKENLIBC_MODE=hardened \
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/ls

cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

bash scripts/check_support_matrix_maintenance.sh
bash scripts/check_c_fixture_suite.sh
TIMEOUT_SECONDS=10 bash scripts/ld_preload_smoke.sh

These are simplified end-to-end sketches, but they reflect the intended structure of the system.

C caller
  ->
ABI entrypoint
  ->
runtime policy decision
  ->
membrane ownership / temporal checks
  ->
allocator path in core
  ->
evidence / metrics update
  ->
pointer or failure returned

Allocator surfaces are among the highest-risk parts of libc, and temporal safety and ownership checks are meaningful here, not decorative.

C caller
  ->
ABI boundary
  ->
pointer and region classification
  ->
size / bounds policy
  ->
strict: allow or compat-fail
    or
hardened: clamp / truncate / deny
  ->
native string kernel

String and memory APIs are both ubiquitous and dangerous; this is where hardened-mode repair stops being abstract.

C caller
  ->
stdio or io_internal ABI entrypoint
  ->
stream lookup and buffering policy
  ->
native stdio path or syscall-facing path
  ->
seek / flush / stat / internal _IO_* compatibility behavior
  ->
evidence and support reports keep the claims honest

The stdio and internal _IO_* surfaces are large enough that progress must be made incrementally and audited symbol by symbol.

This repo is a workspace with a library artifact plus a verification harness. The most useful commands are:

Interpretation note:

• Passing fixture, oracle, or CVE-pattern scripts is evidence about the membrane and targeted scenarios.
• That is not automatically end-to-end proof that FrankenLibC would have prevented the corresponding exploit in an arbitrary upstream program build.
• LD_PRELOAD-based deployment claims do not apply to setuid/setgid binaries because the loader ignores LD_PRELOAD there.

Performance matters because libc is on the hot path of almost every process. The project therefore tries to stage work so cheap, high-signal checks happen first and expensive reasoning is reserved for cases that deserve it.

Typical ordering rationale:

1. trivial null / immediate-fail checks
2. thread-local cache before global metadata
3. bloom-style plausibility before expensive ownership lookup
4. arena and integrity validation once plausibility is established
5. bounds and policy checks once the object is believed to be real

The ordering preserves three properties:

• fast paths stay fast
• suspicious paths get deeper scrutiny
• hardened mode costs more only when the extra scrutiny is justified

The important runtime knob is FRANKENLIBC_MODE. The broader environment inventory is machine-generated in tests/conformance/runtime_env_inventory.v1.json.

Example operator shell setup:

# Runtime behavior
export FRANKENLIBC_MODE=hardened          # strict | hardened
export FRANKENLIBC_LOG=/tmp/franken.jsonl # optional structured runtime log

# Build / verification convenience
export FRANKENLIBC_LIB="$PWD/target/release/libfrankenlibc_abi.so"
export FRANKENLIBC_EXTENDED_GATES=0
export FRANKENLIBC_E2E_SEED=42
export FRANKENLIBC_E2E_STRESS_ITERS=5

# Example invocation
LD_PRELOAD="$FRANKENLIBC_LIB" /bin/echo configured

Environment inventory:

                  C process
                      |
                      v
    +--------------------------------------------+
    | glibc-shaped extern "C" ABI                |
    | crates/frankenlibc-abi                     |
    +--------------------------------------------+
                      |
                      v
    +--------------------------------------------+
    | Transparent Safety Membrane                |
    | crates/frankenlibc-membrane                |
    |                                            |
    | null -> tls -> bloom -> arena              |
    |      -> fingerprint -> canary              |
    |      -> bounds -> policy                   |
    +--------------------------------------------+
                      |
            +---------+---------+
            |                   |
            v                   v
    +------------------+  +----------------------+
    | Native Rust      |  | Raw syscall veneers  |
    | kernels          |  | mostly unistd/io/... |
    | frankenlibc-core |  +----------------------+
    +------------------+
            |
            v
    +--------------------------------------------+
    | Verification and evidence                  |
    | crates/frankenlibc-harness                 |
    | tests/, scripts/, reports                  |
    +--------------------------------------------+

FrankenLibC is built on the idea that libc is one of the highest-leverage places to impose safety and observability on legacy Unix software.

Why this boundary is attractive:

• almost every nontrivial program crosses it constantly
• many memory and resource bugs surface there even when they originate elsewhere
• it is close enough to real behavior to matter, but abstract enough to instrument systematically
• LD_PRELOAD gives an immediate deployment story for experiments

Libc is not a total solution, but it is a strategically valuable intervention point.

To avoid the wrong mental model:

• it is not yet a full standalone libc replacement
• it is not just a hardened allocator
• it is not just an LD_PRELOAD trick with no deeper architecture
• it is not a kernel sandbox
• it is not a whole-program verifier
• it is not “done” simply because native coverage is high on the classified surface

The membrane’s pointer-safety model is a composition of several checks, not a single oracle.

Most real memory-unsafety incidents are mixed failures, not single clean categories. A useful system needs ownership, temporal, integrity, and bounds reasoning to cooperate.

The membrane is the main architectural idea in the project. Instead of trusting raw C pointers because the caller crossed an ABI boundary, FrankenLibC treats the ABI boundary as the place where unsafe information must be classified.

Typical validation path:

incoming pointer / region / fd / mode / context
    ->
null check
    ->
thread-local cache
    ->
bloom filter ownership precheck
    ->
arena / metadata lookup
    ->
fingerprint and canary validation
    ->
bounds / state checks
    ->
Allow | Repair | Deny

The classification outcome determines strict vs hardened behavior:

Examples of repair actions already modeled in the code:

• clamp a size to known allocation bounds
• truncate a string write with a guaranteed trailing NUL
• ignore a double-free instead of corrupting allocator state
• treat invalid realloc patterns as a safe malloc path
• switch to a safer semantic variant when policy demands it

FrankenLibC is unusually explicit about the algorithms it uses. Some of the important ones are:

Each of these solves a specific pressure point in libc replacement:

• compatibility pressure
• safety pressure
• performance pressure
• observability pressure
• staged-migration pressure

The runtime_math/ tree encodes runtime decision logic for validation depth, risk handling, admissibility, and control under pressure.

Representative families already present in the repo:

Offline proofs and synthesis can be heavyweight, but runtime behavior must stay compact and deterministic. The codebase ships controller kernels and evidence structures, not theorem provers in the hot path.

FrankenLibC is deliberately staged.

This staged model is why the symbol taxonomy matters so much. Without a machine-readable map of what is native and what is still delegated, a project like this would quickly become impossible to reason about honestly.

The repo is large enough that it helps to know where the major surfaces live.

Read these first:

1. crates/frankenlibc-abi/
2. crates/frankenlibc-membrane/
3. crates/frankenlibc-core/
4. crates/frankenlibc-harness/

That is the runtime stack from ABI boundary to semantic implementation to verification.

This table is intentionally qualitative. Exact numeric truth still belongs in the canonical artifacts and support matrix.

• startup: IMPLEMENTED_PARTIAL — implemented scope: phase-0 startup fixture path (__libc_start_main, __frankenlibc_startup_phase0, snapshot invariants). Deferred scope: full csu/TLS init-order hardening and secure-mode closure campaign.
• threading: IN_PROGRESS — implemented scope: runtime-math threading routing and selected pthread semantics are live, including lifecycle and rwlock native routing. Deferred scope: close lifecycle/TLS stress beads.
• resolver: IMPLEMENTED_PARTIAL — implemented scope: bootstrap numeric resolver ABI (getaddrinfo, freeaddrinfo, getnameinfo, gai_strerror). Deferred scope: full retry/cache/poisoning hardening campaign.
• nss: IMPLEMENTED_PARTIAL — implemented scope: passwd/group APIs are exported as Implemented via pwd_abi/grp_abi. Deferred scope: hosts/backend breadth plus NSS concurrency/cache-coherence closure.
• locale: IMPLEMENTED_PARTIAL — implemented scope: bootstrap setlocale/localeconv C/POSIX path. Deferred scope: catalog, collation, and transliteration parity expansion.
• iconv: IMPLEMENTED_PARTIAL — implemented scope: phase-1 iconv_open/iconv/iconv_close conversions for UTF-8/ISO-8859-1/UTF-16LE/UTF-32 with deterministic strict+hardened fixtures; codec scope/exclusions are locked in tests/conformance/iconv_codec_scope_ledger.v1.json. Deferred scope: full iconvdata breadth and deterministic table-generation closure.

crates/frankenlibc-membrane/src/heal.rs currently defines:

• ClampSize
• TruncateWithNull
• IgnoreDoubleFree
• IgnoreForeignFree
• ReallocAsMalloc
• ReturnSafeDefault
• UpgradeToSafeVariant

The project is organized around verification artifacts:

• support_matrix.json: per-symbol status taxonomy
• tests/conformance/support_matrix_maintenance_report.v1.json: canonical maintenance snapshot
• tests/conformance/fixtures/: host-libc fixture packs
• tests/runtime_math/golden/: runtime math snapshot goldens
• scripts/check_*.sh: drift, closure, smoke, and policy gates

Each artifact or gate answers a specific question:

If you want to judge the project seriously, do not rely on adjectives in the README. Use the artifacts and gates.

For a fast maturity check, this is a good sequence:

bash scripts/check_support_matrix_maintenance.sh
bash scripts/check_c_fixture_suite.sh
TIMEOUT_SECONDS=10 bash scripts/ld_preload_smoke.sh
bash scripts/check_release_gate.sh

It is easier to understand the repo’s verification model if you split tests by layer instead of by tool name.

Representative verification flows:

# Support-matrix maintenance
bash scripts/check_support_matrix_maintenance.sh

# Fixture pipeline
bash scripts/check_conformance_fixture_pipeline.sh

# LD_PRELOAD smoke
TIMEOUT_SECONDS=10 bash scripts/ld_preload_smoke.sh

# Runtime math snapshots
bash scripts/snapshot_gate.sh

# Release / closure-oriented checks
bash scripts/check_closure_contract.sh
bash scripts/check_release_gate.sh

The repo has many report artifacts. This table maps them to the questions they answer.

The project artifacts fall into three categories:

• claims about what exists
• evidence about what happened
• gates that compare the two

Keeping those categories separate helps when reading the repo.

Implementation changes in FrankenLibC are expected to leave an evidence trail.

Typical lifecycle:

code change
  ->
symbol classification change or semantic change
  ->
canonical artifact refresh
  ->
targeted tests and gates
  ->
smoke / fixture / maintenance evidence
  ->
release and closure reconciliation

Without that loop, a project like this drifts into self-deception quickly.

These two ideas should not be conflated.

The interpose artifact is valuable now because it enables:

• experimentation on existing binaries
• workload shadowing
• hardened-mode studies
• incremental symbol promotion

The replace artifact matters later because it raises the bar from “interpose safely” to “own libc behavior fully enough to stop depending on host glibc.”

• interpose shared library exists
• host glibc is still part of the deployment story because the shipping artifact is interpose-first, even though the current symbol matrix no longer reports GlibcCallThrough rows
• support taxonomy is machine-checked
• hardened mode and verification flows are already live

• keep the matrix-clean classification honest while closing the broader preload, hardened-mode, and artifact-packaging gaps
• keep maintenance artifacts synchronized as each promotion lands
• tighten replacement gates so "replace-ready" is mechanically enforced, not socially assumed

• standalone replacement artifact exists as a real product, not a README promise
• Implemented and RawSyscall are sufficient for the replacement artifact
• the project can make stronger deployment claims without hand-waving over unresolved host dependencies

This progression explains why the project has so many reports and gates: they are how a staged libc replacement stays honest.

Different readers will care about different ways of using the project.

The remaining hard areas are difficult for real systems reasons, not because they were forgotten.

If you want to understand the project deeply instead of just using it, this order works well:

1. README.md
2. AGENTS.md
3. support_matrix.json
4. crates/frankenlibc-abi/
5. crates/frankenlibc-membrane/
6. crates/frankenlibc-core/
7. crates/frankenlibc-harness/
8. tests/conformance/
9. scripts/check_*.sh

That sequence mirrors how the project itself works:

• claimed surface
• actual ABI boundary
• safety substrate
• semantic kernels
• verification and drift control

Check that you built the ABI crate in release mode and are pointing at the actual .so:

test -f target/release/libfrankenlibc_abi.so

This repo uses nightly Rust:

rustup toolchain install nightly
rustup override set nightly

Trust the machine artifact. The most useful current files are:

• support_matrix.json
• tests/conformance/support_matrix_maintenance_report.v1.json
• tests/conformance/runtime_env_inventory.v1.json

Set a log path explicitly:

FRANKENLIBC_LOG=/tmp/franken.jsonl \
FRANKENLIBC_MODE=hardened \
LD_PRELOAD="$PWD/target/release/libfrankenlibc_abi.so" /bin/echo test

You probably updated code or support_matrix.json without refreshing a canonical artifact. Start here:

bash scripts/check_support_matrix_maintenance.sh

• The current production artifact is the interpose shared library, not a full standalone libc replacement.
• Host glibc is still part of the deployment story because the shipping artifact is still LD_PRELOAD interposition, not a standalone libc drop-in.
• Broad preload smoke is still unstable; the latest checked March 23, 2026 run was not green.
• Hardened mode exists and has targeted validation/oracle coverage, but it is not yet broadly stable across the smoke workload set.
• Performance is not yet a settled success story; strict-mode perf regressions still show up in smoke/perf gates and must be measured rather than assumed away.
• The README can summarize current reality, but the canonical truth still lives in generated reports and gates.
• Linux is the real target. Multi-architecture and full replacement stories are still active work.
• Many verification scripts exist because this is an active research-heavy codebase, not a polished end-user product.

No. The practical artifact today is libfrankenlibc_abi.so used via LD_PRELOAD, and even that broad interpose story is still being stabilized. Full standalone replacement remains planned.

Yes. The current classified surface is 3980 symbols, with 3576 Implemented and 404 RawSyscall.

No. They provide targeted evidence for specific bug patterns and synthetic scenarios, which is useful, but weaker than an end-to-end proof against a real vulnerable upstream build. In particular, LD_PRELOAD claims do not apply to setuid/setgid binaries, so those cases need a different deployment story.

It allows the membrane to repair or deny unsafe patterns instead of just propagating failures, while recording evidence about what happened.

Yes. The architecture and implementation are spec-first and verification-driven rather than line-by-line glibc translation.

Real code. The frankenlibc-membrane/src/runtime_math/ tree is large and live, and the repo includes snapshot and linkage gates around it.

The generated reports. The README is a guide; the source of truth is the code plus the canonical artifacts under tests/conformance/.

musl solves a different problem. FrankenLibC is trying to preserve a glibc-shaped compatibility story while adding safety, classification, and staged replacement machinery.

Sanitizers are extremely useful, but they are development instrumentation. FrankenLibC is aimed at boundary-level safety and observability for deployed binaries and replacement-libc research.

Because libc risk is broader than allocation alone. String APIs, stdio, resolver paths, locale/iconv behavior, threading, startup, and loader behavior all matter.

Because this project is designed to reconcile implementation claims, evidence, and release readiness mechanically rather than socially.

Because standalone replacement depends not just on counts, but on which symbols remain delegated, which subsystems remain strategically hard, and whether the artifact-level guarantees are actually satisfied.

The custom allocator in crates/frankenlibc-core/src/malloc/ is a production-grade, membrane-integrated design with three tiers.

32 size classes span from 16 bytes to 32,768 bytes:

Each size class is backed by 64 KB slabs, and every individual allocation carries 64 bytes of per-object overhead (fingerprint header + trailing canary + alignment padding).

Each thread maintains a magazine-based cache with a LIFO stack of free objects per size class:

• 64 objects per class per thread, up to 2,048 cached objects per thread across all 32 classes
• Thread-local alloc/free stays entirely lock-free until a magazine overflows or drains
• Overflow spills back to the sharded central allocator

This design means that steady-state allocation patterns on a single thread never touch shared state at all.

Requests exceeding 32 KB bypass the slab system entirely:

• Routed to a dedicated LargeAllocator backed by mmap
• Page-aligned (4096-byte boundaries) with explicit base/mapped-size/user-size tracking
• Base address starts at 0x1_0000_0000 to prevent confusion with small-allocation address ranges

Every allocation flows through the membrane before returning a pointer:

• 20-byte SipHash fingerprint header prepended to each allocation
• 8-byte trailing canary appended after the user region
• The generational arena records ownership, generation counter, and safety state
• Double-free and use-after-free are caught by generation mismatch and quarantine queue membership

The printf implementation in crates/frankenlibc-core/src/stdio/ is a complete safe-Rust engine, not a wrapper around libc's vsnprintf.

Supported format directives:

• All POSIX conversion specifiers: %d, %i, %u, %o, %x, %X, %f, %F, %e, %E, %g, %G, %a, %A, %c, %s, %p, %n, %%
• All flags: - (left-justify), + (force sign), (space sign), # (alternate form), 0 (zero pad)
• Width and precision: literal values and * (from-argument) for both
• All length modifiers: hh, h, l, ll, z, t, j, L

Design invariant: no single format specifier can produce more than width + precision + 64 bytes. This bounds memory growth from format strings and prevents a class of denial-of-service where a crafted format string causes unbounded allocation.

Arguments are dispatched through a FormatArg enum (SignedInt(i64), UnsignedInt(u64), Float(f64), Char(u8)) with string arguments handled out-of-band as byte slices.

Stdio buffering follows POSIX semantics with three modes:

The default buffer size is 8192 bytes (BUFSIZ). The implementation enforces POSIX's requirement that setvbuf cannot be called after I/O has started on a stream; mode is monotonically locked after the first operation.

Line-buffered writes use a reverse scan (rposition) to find the last newline, flushing through that point and retaining the remainder. The unget() path supports pushing a single byte back for ungetc semantics.

The crates/frankenlibc-abi/src/ directory contains 39 ABI module files, each covering a distinct POSIX or glibc function family. Together they export the symbols defined in a 4,466-line GNU ld version script (version_scripts/libc.map) under the GLIBC_2.2.5 version tag.

Every ABI entrypoint follows a five-step pattern:

1. runtime_policy::decide()   -- membrane consults risk, mode, and context
2. check for Deny             -- blocked calls return EPERM immediately
3. validate inputs            -- core-layer checks on arguments
4. delegate                   -- call safe Rust kernel or raw syscall
5. runtime_policy::observe()  -- record outcome for metrics and healing

This pattern is not advisory. It is structurally enforced: the ABI module files are minimal glue, and the real work happens in the membrane and core layers.

The arena in crates/frankenlibc-membrane/src/arena.rs tracks every live allocation:

Freed allocations enter a quarantine queue before their memory is recycled. This window makes use-after-free detectable even if the slot is reused, because the generation counter will have incremented.

Each allocation is bracketed by integrity metadata:

[20-byte fingerprint header][user data region][8-byte trailing canary]

The fingerprint header contains:

The trailing canary is derived from the same SipHash computation. Corruption of either the header or canary signals tampering or buffer overflow. The probability of an undetected collision is bounded by 2^-64 (SipHash collision probability).

The ownership bloom filter in bloom.rs provides O(1) "is this pointer ours?" pre-checks:

The bloom filter sits early in the validation pipeline because it can reject most non-owned pointers before touching the arena or fingerprint logic.

The 8-state lattice in lattice.rs has a diamond structure where Readable and Writable are incomparable:

        Valid (6)
       /         \
Readable (5)  Writable (4)
       \         /
     Quarantined (3)
            |
         Freed (2)
            |
        Invalid (1)
            |
        Unknown (0)

• Join (new evidence arrives): always moves toward the more restrictive conclusion
• Meet (what is known to be safe): always moves toward the most permissive valid conclusion
• Both operations are commutative, associative, and idempotent
• State transitions are monotonically downward on new negative evidence; once a pointer is classified as Freed, it cannot return to Valid

The Galois connection in galois.rs formalizes the relationship between C's flat pointer model and the membrane's rich safety model:

• Alpha (abstraction): maps a raw C pointer + context into a PointerAbstraction with safety state, allocation base, remaining bytes, and generation
• Gamma (concretization): maps the abstract safety state back into a ConcreteAction (Proceed, Heal, Deny)
• Soundness guarantee: gamma(alpha(c)) >= c -- the safe interpretation is always at least as permissive as what a correct program needs

The membrane crate's build.rs (1,012 lines) performs substantial compile-time verification:

Sum-of-Squares (SOS) Certificate Generation:

Three polynomial invariant certificates are synthesized and verified at build time:

Each certificate undergoes:

1. Gram matrix construction
2. PSD (positive semi-definite) verification via Cholesky decomposition with tolerance 1e-9
3. Polynomial identity verification for barrier budget bounds
4. Artifact generation as Rust const values and JSON soundness reports

Memory Model Barrier Audit:

The build script scans source files for atomic operations and verifies minimum barrier coverage:

If any source file has fewer atomic sites than expected, the build fails. This prevents silent removal of synchronization barriers during refactoring.

The ABI crate's build.rs links the GNU ld version script (libc.map) via -Wl,--version-script, but only in release builds. Debug builds skip version-script linking to avoid symbol conflicts with the host libc during development.

The verification harness (cargo run -p frankenlibc-harness --bin harness) supports these subcommands:

Each subcommand produces structured artifacts that can be diffed, tracked in version control, or consumed by downstream gates.

The tests/integration/ directory contains 16 C test programs that are compiled against the produced libfrankenlibc_abi.so and exercised during integration testing:

The tests/conformance/fixtures/ directory contains 40+ JSON fixture families, each capturing input/output pairs from host glibc. Representative families:

• Allocator: allocator, stdlib_conversion, stdlib_numeric, stdlib_sort
• String: string_ops, string_memory_full, strlen_strict, string_strtok, memcpy_strict
• Wide string: wide_string, wide_memory, wide_string_ops
• Character/errno: ctype_ops, errno_ops
• Math: math_ops
• Threading: pthread_thread, pthread_mutex, pthread_tls_keys
• I/O: socket_ops, poll_ops, inet_ops, resolver, dirent_ops
• Process: process_ops, spawn_exec_ops, signal_ops, setjmp_ops
• System: time_ops, termios_ops, locale_ops, resource_ops, virtual_memory_ops, sysv_ipc_ops
• Loader: dlfcn_ops, elf_loader, backtrace_ops
• Membrane-specific: membrane_mode_split, pressure_sensing

These fixtures serve as the ground truth for differential verification: FrankenLibC's output for the same inputs must match glibc's behavior where conformance is claimed.

The scripts/ directory contains 148 shell scripts organized by purpose:

Every claim about the system (symbol ownership, conformance, performance, security) has a corresponding machine-checkable gate.

The membrane includes several lock-free and wait-free synchronization primitives beyond what parking_lot provides:

These exist because the membrane is called on every libc entrypoint. Global locks would create unacceptable contention under multithreaded workloads. The TLS validation cache (1,024-entry direct-mapped) is the first line of defense, and these primitives handle the cases where the cache misses and shared state must be consulted.

The project is explicit about which formal properties it claims and at what confidence level:

The pthread implementation in crates/frankenlibc-core/src/pthread/ is a clean-room futex-backed design, not a wrapper around glibc's NPTL.

Three mutex types are supported: NORMAL (0), RECURSIVE (1), and ERRORCHECK (2). Each mutex is modeled as a five-state contract machine:

The fast path is a single CAS on the uncontended case. When contended, the implementation classifies the wait via bounded spin before falling through to FUTEX_WAIT / FUTEX_WAKE with FUTEX_PRIVATE_FLAG (0x80). Unlock always wakes at least one waiter. Error reporting follows POSIX: EBUSY on double-init, EPERM on unlock-by-other, EDEADLK on recursive ERRORCHECK lock.

Condvars use a 20-byte internal layout (fits within the 48-byte pthread_cond_t on x86_64). Internal state consists of a sequence counter, associated mutex pointer, and waiter count.

Two clock modes are supported: CLOCK_REALTIME (default) and CLOCK_MONOTONIC. Timed waits use FUTEX_WAIT_BITSET with FUTEX_BITSET_MATCH_ANY (0xFFFF_FFFF) and FUTEX_CLOCK_REALTIME (256). Signal increments the sequence counter and wakes one waiter; broadcast wakes all.

Three preference modes: PREFER_READER_NP (0, default), PREFER_WRITER_NP (1), and PREFER_WRITER_NONRECURSIVE_NP (2). Unknown kinds are sanitized to the default.

Every ABI entrypoint consults runtime_policy::decide() before doing real work. The policy engine is where mode semantics, membrane decisions, and runtime math come together.

The process-wide mode is resolved exactly once from FRANKENLIBC_MODE:

Resolution uses a compare-and-swap state machine: UNRESOLVED (0) -> RESOLVING (255) -> STRICT (1) / HARDENED (2) / OFF (3). Reentrant calls during resolution return a passthrough decision so the process can finish initializing.

decide(family, ptr_or_addr, size, is_startup, is_null_likely, context_flags)
  -> (RuntimeKernelSnapshot, RuntimeDecision)

ApiFamily classifies the call site: Process, Memory, String, Alloc, Stdio, Socket, Thread, Signal, and others. The returned RuntimeDecision contains a MembraneAction (Allow, Check, Deny, or a specific healing directive) and a ValidationProfile indicating how deep the membrane should inspect.

After the call completes, observe(family, profile, latency, denied) feeds the outcome back into the runtime math kernel for sequential monitoring and threshold adjustment.

The standalone risk engine in crates/frankenlibc-membrane/src/risk_engine.rs implements online conformal risk control for adaptive validation depth.

Every pointer or region is scored along three axes:

The final score is capped at 1000. Scores below fast_threshold skip expensive validation entirely; scores above full_threshold trigger exhaustive checks.

The engine maintains a 256-entry circular buffer of recent scores. Thresholds are calibrated as quantiles of this empirical distribution:

• fast_threshold: the (1 - alpha) quantile, where alpha defaults to 0.01 (1% target false-skip rate)
• full_threshold: a higher quantile for triggering deep inspection

An e-process monitor accumulates evidence on the log scale. When the e-process exceeds 10.0, the engine enters alarm mode and forces full validation on every call until the evidence subsides. Recalibration happens periodically based on call volume.

The check oracle in crates/frankenlibc-membrane/src/check_oracle.rs uses Thompson sampling to learn the optimal ordering of validation stages at runtime.

Each stage maintains a Beta(alpha, beta) distribution initialized to Beta(1,1) (uniform prior). After each validation call, the stage that caused early termination gets its alpha incremented (success); stages that ran but did not terminate get beta incremented (failure).

Every 128 calls, the oracle recomputes the optimal ordering by sampling from each stage's posterior and ranking by expected information gain per nanosecond. The ordering is packed into a single u64 (4 bits per stage) for cache-friendly storage.

Over time, the oracle converges to an ordering that puts the cheapest high-rejection stages first, minimizing expected validation latency for the observed workload.

The healing oracle in crates/frankenlibc-harness/src/healing_oracle.rs verifies hardened-mode repairs by deliberately triggering unsafe conditions and checking that the membrane handles them correctly.

Seven categories of unsafe behavior are tested:

The oracle runs 14 test cases across string (strlen, strcmp, strcpy, strncpy, memmove, memcpy) and malloc (free, cfree, realloc, reallocarray) families, in both strict and hardened modes. Results are emitted as JSON with a per-case breakdown of expected vs. observed healing actions.

__libc_start_main runs before main() and controls process initialization, making it a high-value target for validation. FrankenLibC's implementation in startup_abi.rs uses a multi-checkpoint validation envelope.

1. membrane gate           -- runtime_policy::decide(ApiFamily::Process)
2. validate main pointer   -- null check, EINVAL + Deny on failure
3. validate argv pointer   -- null check, EINVAL + Deny on failure
4. scan argv vector        -- count entries up to MAX_STARTUP_SCAN, detect unterminated
5. validate argc bound     -- argv_count >= normalized_argc
6. scan envp vector        -- same count validation
7. scan auxv vector        -- parse key/value pairs, detect truncation
8. classify secure mode    -- via classify_secure_mode(&auxv_pairs)
9. call init hook
10. call main(argc, argv, envp)
11. call fini hook
12. call rtld_fini hook

If validation fails at any checkpoint, the startup policy decides whether to deny (abort) or fall back to the host glibc's __libc_start_main via dlvsym_next(), trying version symbols GLIBC_2.34, GLIBC_2.2.5, and GLIBC_2.17 in priority order.

Program name globals (program_invocation_name, __progname) are stored as AtomicPtr values extracted from argv[0].

setjmp and longjmp are inherently unsafe at the ABI level. FrankenLibC's implementation adds guard metadata to make corruption and misuse detectable.

The 128-byte JmpBuf (16 x u64) reserves the first six slots for membrane metadata:

Before restoring, phase1_longjmp_restore() checks:

1. Magic and non-zero metadata (catches uninitialized buffers)
2. Mode tag matches current process mode
3. Current thread owns the buffer (catches cross-thread longjmp)
4. Guard checksum validates (catches buffer corruption)

Failure produces a typed error (UninitializedContext, ForeignContext, CorruptedContext, ModeMismatch) rather than silent undefined behavior.

POSIX requires that longjmp(env, 0) behaves as if setjmp returned 1. The implementation normalizes this before the restore path.

The resolver in crates/frankenlibc-core/src/resolv/ takes a conservative bootstrap approach: no network I/O, no NSS plugins, no recursive resolution.

1. Parse the address as IPv4 or IPv6 literal (returns immediately if it is one)
2. Search /etc/hosts for a matching hostname or alias
3. Search /etc/services for port/protocol mapping
4. If none match, return EAI_NONAME (-2)

Network-based DNS resolution is explicitly out of scope for the bootstrap resolver. This is a deliberate design choice: the resolver that runs inside libc itself should not open sockets or depend on external services during early process initialization. A full NSS/DNS backend is a future milestone.

Thread-local errno is easy to get wrong. The implementation in crates/frankenlibc-core/src/errno/ uses Rust's thread_local! with a Cell<i32>:

• __errno_location() returns a pointer to the current thread's errno cell
• get_errno() / set_errno() for internal Rust code
• 50+ standard error constants (EPERM, ENOENT, EINTR, EIO, ENOMEM, EACCES, EINVAL, EDEADLK, ENOSYS, EOVERFLOW, etc.)
• strerror_message() does a static string lookup; unmapped codes return "Unknown error"

errno is per-thread state that C programs expect to survive across function calls. A global instead of thread-local implementation, or one that is not stable across FFI boundaries, will break real programs.

The smoke test (scripts/ld_preload_smoke.sh) verifies that real programs work under interposition. It runs actual binaries and compares their behavior against a baseline.

The release interpose artifact is built with cargo build -p frankenlibc-abi --release and emitted at target/release/libfrankenlibc_abi.so. The planned standalone replacement artifact is named libfrankenlibc_replace.so.

Interpose deployment uses LD_PRELOAD=target/release/libfrankenlibc_abi.so <program>. Hardened interpose deployment uses FRANKENLIBC_MODE=hardened LD_PRELOAD=target/release/libfrankenlibc_abi.so <program>.

Implemented + RawSyscall symbols apply to both artifacts. GlibcCallThrough + Stub symbols apply to Interpose only.

Each test case produces a classified failure signature:

Each case collects baseline and preload stdout/stderr, a metadata bundle (mode, exit code, failure signature, /proc/self/maps), and latency measurements in nanoseconds with a computed latency ratio.

The support_matrix.json file is the machine-readable source of truth for the project's implementation claims. Its structure:

{
  "version": 2,
  "total_exported": 3980,
  "taxonomy": {
    "Implemented": "Native Rust, no host libc dependency",
    "RawSyscall": "Direct syscall marshaling",
    "GlibcCallThrough": "Delegates to host glibc",
    "Stub": "Deterministic failure contract"
  },
  "symbols": [
    {
      "symbol": "_Exit",
      "status": "RawSyscall",
      "module": "unistd_abi",
      "perf_class": "O1",
      "strict_semantics": true,
      "hardened_semantics": true,
      "default_stub": false
    }
  ]
}

Every exported symbol has a classification, an owning ABI module, a performance class, and boolean flags for strict and hardened semantic coverage. The maintenance scripts compare this file against the actual symbols in the compiled .so and flag any drift as a build failure.

For readers unfamiliar with the mechanism: LD_PRELOAD tells the Linux dynamic linker to load a shared library before any others. When a program calls malloc, strlen, or any libc function, the linker resolves the symbol to FrankenLibC's implementation first. For symbols that FrankenLibC does not own yet, the project may still delegate to host glibc through constrained host-resolution and call-through paths.

FrankenLibC is already usable for many experiments without relinking anything: same binary, same kernel, same file system, different libc implementation behind the ABI boundary. That should not be confused with a claim that the full broad smoke matrix is already stable.

Limitations of interposition:

• Functions called internally within glibc (where the linker has already bound the symbol) are not intercepted
• Some startup-critical paths run before LD_PRELOAD takes effect
• LD_PRELOAD is ignored for setuid/setgid binaries (kernel security policy)
• The interpose library must export symbols with the correct version tags to match what binaries expect

The version script (crates/frankenlibc-abi/version_scripts/libc.map) handles the last point by exporting symbols under the GLIBC_2.2.5 version tag, which is what most dynamically linked Linux binaries expect.

Interpose (L0/L1): dlopen, dlsym, dlclose, and dlerror stay inside FrankenLibC's native phase-1 loader boundary for supported handles and exported symbols.

Hardened invalid dlopen flags heal to RTLD_NOW before local phase-1 resolution.

Replacement (L2/L3) forbids direct host dlopen/dlsym/dlclose fallback paths; any residual call-through is a release-blocking gate failure.

About Contributions: Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

FrankenLibC is available under the terms in LICENSE, currently MIT License (with OpenAI/Anthropic Rider).