c_std: A Leak-Free, Cross-Platform Standard Library for Modern C

Bringing the comfort of the C++ STL and Python's standard library to C17 — without leaving C

A technical white paper.

Executive summary

C is still the substrate of the computing world — kernels, databases, language runtimes, embedded firmware, and the inner loops of nearly everything else. Yet the moment you step away from the kernel and try to write ordinary application code in C, you feel the gap: no growable vector, no hash map, no JSON parser, no string type that doesn't invite a buffer overflow. You either pull in a grab-bag of mismatched third-party libraries, each with its own conventions and failure modes, or you re-implement the same dynamic array for the hundredth time.

c_std is an attempt to close that gap deliberately and coherently. It is a single, consistent library — written in pure C17 — that reimplements a large slice of the C++ Standard Library (containers, algorithms, smart pointers) alongside many Python-style conveniences (json, regex, random, statistics, csv, config, even turtle graphics). It targets Windows and Linux from one source tree, compiles cleanly under -Wall -Wextra, and — this is the part I care about most — is verified leak-free under Valgrind, module by module, example by example.

This paper explains the design philosophy, the architecture, and the engineering discipline that makes a library like this trustworthy enough to build on.

1. The problem: C's missing middle

Every C programmer knows the two extremes. At the bottom, the language itself: pointers, malloc, memcpy, raw arrays. At the top, whatever the platform hands you — <windows.h> or POSIX, OpenSSL, a JSON library someone wrapped a decade ago. The middle — the layer the C++ STL and Python's batteries-included standard library occupy — is missing.

That missing middle has a real cost. It shows up as:

• Re-invention. Teams write their own vector, their own string builder, their own linked list, each subtly different.
• Inconsistency. One library returns 0 on success; another returns -1; a third sets errno; a fourth returns a pointer you must remember to free with its deallocator.
• Safety hazards. Hand-rolled string and buffer code is where C's reputation for footguns is earned.

c_std's thesis is simple: a C developer should be able to reach for a Vector, a HashMap, a String, a JSON document, a TCP client, or a big integer with the same fluency a C++ or Python developer has — and those building blocks should share one set of conventions for construction, ownership, error reporting, and teardown.

2. Design philosophy

Six principles shaped the library. They are worth stating explicitly, because the value of a standard library is as much in its consistency as in its feature list.

2.1 One mental model for ownership. Every module follows the same lifecycle: a *_create() / *_init() constructor, explicit operations, and a matching *_deallocate() / *_destroy() destructor. Containers that own heap values take a deallocator callback and call it on erase and teardown — and the contract for who frees what is documented and, crucially, tested. Where a function transfers ownership to the caller (for example, list_erase returns the removed value for you to free), that is stated in the header and demonstrated in the README.

2.2 Familiar APIs win. The container names map to their C++ analogues (vector, map, unordered_map → hashmap, unique_ptr → uniqueptr). The text and data utilities map to Python (random, statistics, json, regex). Familiarity is a feature: it shortens the distance between "I know what I want" and "I know what to type."

2.3 Portability is a first-class requirement, not an afterthought. Anything OS-specific lives behind a #if defined(_WIN32) … #else … #endif seam with a Win32 implementation and a POSIX implementation of the same public function. The caller never sees the difference. network, concurrent, sysinfo, dir, and crypto are all built this way.

2.4 Fail safe, never exit(). A library has no business terminating its host process. Constructors return NULL on allocation failure; operations return status codes; NULL inputs are tolerated rather than dereferenced. This sounds obvious and is routinely violated.

2.5 Document at the definition. Every public function carries a Doxygen contract directly above its implementation — purpose, parameters, return values, platform notes. The header is a clean index; the source is the source of truth.

2.6 No leaks. Ever. More on this below, because it is the principle that took the most work and yields the most trust.

3. Architecture at a glance

c_std is organized as ~40 independent modules, each in its own directory with a .c, a .h, a README.md with a full API reference and runnable examples, and a test suite. Grouped by domain:

• Containers — vector, array, string, list, forward_list, deque, queue, stack, priority_queue, span, bitset, map (red-black tree), hashmap (open-addressing-free chained table with automatic rehashing), tuple, variant, uniqueptr.
• Algorithms & numerics — algorithm, sort, statistics, random, secrets, numbers, matrix, bigint (GMP), bigfloat (MPFR), evalexpr.
• Text, data & I/O — fmt, encoding (Base16/32/64, URL), json, xml, csv, config (INI), regex, cli, log, file_io, dir.
• Time & date — time, date (Gregorian + Persian calendars).
• System & concurrency — sysinfo, concurrent (threads, mutexes, condition variables, a thread pool), serial_port.
• Security — crypto (OpenSSL-backed), jwt (HS/RS/ES/PS families).
• Networking & databases — network (TCP, UDP, a small HTTP server/client), database (PostgreSQL via libpq, built only when present).
• Graphics — plot (line/scatter/bar/pie/histogram) and turtle (Python-style turtle graphics), both on raylib.
• Testing — a small unittest framework.

The build is CMake-only, generator-agnostic (Ninja recommended), and works with GCC, Clang, and MSVC. You can build the whole library and all ~50 example programs at once, or compile a single module or example in isolation.

4. The two non-negotiables

A standard library earns trust by being boring in the right ways. Two properties matter more than any feature.

4.1 Memory safety, proven — not asserted

It is easy to claim a C library has no leaks. It is harder to mean it. The discipline here is mechanical and relentless:

• Every module's test suite and every runnable README example is executed under valgrind --leak-check=full --show-leak-kinds=definite,indirect --error-exitcode=99. The target is uniform: 0 leaks, 0 errors.
• Network and socket code is additionally run with --track-fds=yes, because a server that leaks file descriptors is just as dead as one that leaks memory — it simply takes longer to fall over.
• The same code is compiled with -Wall -Wextra and is expected to be warning-clean on both GCC and MSVC.

This methodology is not decoration. It routinely surfaces the exact class of bug that C is infamous for. A representative example: a double-ended queue whose reallocation guard checked size == capacity but ignored the front-padding offset that grows from the middle of the first block. For most access patterns it worked; under the right mix of front/back insertions it wrote one slot past the block array — an out-of-bounds write that Valgrind flagged as an invalid write of size 8, which in turn corrupted a stored pointer and produced a "lost" allocation downstream. The fix was a single corrected predicate, but the point is that the test harness found it deterministically rather than leaving it to crash in production six months later.

The lesson I would underline for anyone building C infrastructure: leak-checking is not a final QA step, it is part of the inner development loop. Wire it into the way you run the code from day one, and the cost of staying clean approaches zero.

4.2 Genuine cross-platform parity

Cross-platform support in C is usually aspirational — "it should build on Linux too." c_std treats Windows and Linux as co-equal first-class targets, and the test suites run on both. Several modules are interesting case studies in doing this honestly:

• regex auto-selects its backend at compile time via __has_include(<pcre.h>): PCRE where available, and a POSIX <regex.h> fallback otherwise, with a small translation shim so that common patterns (\d, \w, \s) behave consistently across the two engines. One API, two engines, same results.
• network presents one socket API over Winsock and BSD sockets. Sockets are created dual-stack IPv6 so a single code path serves IPv4 and IPv6 — which, as it happens, is exactly the kind of detail that bites you: binding a dual-stack AF_INET6 socket to an IPv4 wildcard address fails, and the fix is to resolve the bind address as IPv6 with AI_V4MAPPED.
• crypto leans on OpenSSL but guards legacy digests (MDC2) behind OPENSSL_NO_MDC2, because the distro you build on may have compiled them out. Portable code respects the configuration of its dependencies, not just their presence.

The recurring theme: the difference between "compiles on two platforms" and "works correctly on two platforms" is a long tail of small, specific, well-understood decisions. There is no shortcut; there is only the willingness to chase each one down.

5. Production-minded networking: a short case study

Because so much real-world C ends up talking to a network, the network stack received particular attention to the failure modes that actually take systems down in production.

Consider connect timeouts. A plain blocking connect() to an unreachable host can stall for the operating system's default — often minutes — and wedge a request thread the entire time. c_std provides tcp_connect_timeout(), which performs the connect in non-blocking mode, waits on select() for a caller-supplied budget, and confirms the result via SO_ERROR:

TcpSocket s;
tcp_socket_create(&s);

/* Never blocks longer than 2 seconds, on any platform. */
if (tcp_connect_timeout(s, "api.example.com", 443, 2000) == TCP_SUCCESS) {
    /* ... */
}

It is paired with readiness primitives (tcp_wait_readable, tcp_wait_writable), an exact-byte-count helper (tcp_bytes_available via FIONREAD), and tcp_get_socket_error for completing non-blocking operations. None of these allocate, so there is nothing to leak; all were validated with a stress harness that opened and closed thousands of sockets under Valgrind with descriptor tracking, plus a deliberate connect to a black-holed address to prove the timeout actually bounds the wait.

The HTTP layer is similarly pragmatic. Header lookup is case-insensitive per RFC 7230 (a real client will send content-type in the wrong case eventually), and Content-Length parsing is strict and overflow-safe rather than a naive atoi. These are not glamorous features. They are the difference between a demo and something you can put in front of untrusted input.

6. The API in practice

A few snippets convey the intended ergonomics better than prose. Note the uniform shape: create, use, destroy.

/* A growable typed array */
Vector* v = vector_create(sizeof(int));
for (int i = 1; i <= 5; ++i) vector_push_back(v, &i);
fmt_printf("size=%zu\n", vector_size(v));
vector_deallocate(v);

/* JSON, parsed and pretty-printed */
JsonElement* root = json_parse("{\"lib\":\"c_std\",\"version\":1.0}");
json_print(root);
json_deallocate(root);

/* RAII-style ownership with a smart pointer + a custom deleter,
   so a unique_ptr can own another c_std object and free it correctly */

The graphics modules deserve a mention because they show the library reaching beyond "data structures." plot renders line, scatter, bar, pie, and histogram charts to a PNG; turtle provides Python-style turtle graphics. Both are built on raylib, and both are testable headlessly — plot_export_image() and turtle_save_image() produce real image files, which makes them as amenable to automated verification as any other module, despite being graphical.

7. Performance posture

c_std optimizes for predictable performance and correct asymptotics rather than micro-benchmark bragging rights:

• vector grows geometrically with memory pooling to amortize reallocation.
• hashmap offers O(1) average insert/lookup with automatic rehashing as the load factor rises.
• map is a red-black tree with O(log n) ordered operations.
• bigint/bigfloat delegate to GMP and MPFR — mature, heavily optimized numeric libraries — rather than reinventing arbitrary-precision arithmetic.

The guiding judgment is that a general-purpose standard library should pick the right data structure with the right complexity class and implement it cleanly; specialized hot paths are the application's job, not the library's.

8. Limitations and honest caveats

A white paper that only lists strengths is marketing. In the interest of engineering honesty:

• It is not the C++ STL. C has no templates, no RAII, no operator overloading. Type-generic containers use void* and element sizes; you trade compile-time type safety for flexibility. uniqueptr approximates RAII but cannot match scope-based destruction enforced by the language.
• Graphics and database modules carry heavy dependencies (raylib; libpq). They are optional, and database is skipped automatically when libpq is absent — but they are not free.
• macOS is plausible but not a primary CI target. The POSIX paths should largely work; treat it as best-effort until proven.
• It is a large surface area. Forty-plus modules is a lot to keep uniformly excellent; the test-and-Valgrind discipline is what keeps that surface honest, but breadth always carries maintenance cost.

Knowing where a tool doesn't fit is part of using it well.

9. Roadmap

Natural next steps include broadening CI to macOS and to MSVC in automation, expanding fuzz testing on the parsers (json, xml, csv, regex) beyond the current adversarial-but-curated suites, and continuing to file down the long tail of platform-specific behavior. The architecture — independent modules behind consistent contracts — is deliberately friendly to incremental, low-risk evolution.

## 10. Conclusion

C does not need to be a language where you start every project by rewriting a dynamic array. c_std is a bet that the missing middle can be filled coherently: one library, one set of conventions, two first-class platforms, and a hard, verified line on memory and descriptor leaks. The interesting work was rarely the feature list — it was the discipline. Leak-check in the inner loop. Treat the second platform as equal to the first. Document ownership and then test it. Respect your dependencies' configuration. Fail safe.

Those habits are transferable to any serious C codebase. If this paper leaves you with one thing, let it be that: the tools to make C trustworthy already exist. What they require is the decision to use them on every commit, not just before the release.

— Written from hands-on experience building and hardening the library across Windows (MSYS2/MinGW, MSVC) and Linux (GCC/Clang) toolchains.