C Systems Programming skill for Claude Code

Done well means: every buffer travels with its capacity, every allocation and size computation is checked, every acquired resource is released on every path, the API documents who frees what, and the code builds warning-free with hardening flags and runs clean under ASan+UBSan and Valgrind.

Before changing anything

1. Identify the standard and compilers: -std= in the build, CI images, embedded toolchains. GCC 15 defaults to gnu23; older code may break on bool, true, nullptr or unprototyped f() now meaning f(void). Pin -std=c17 or -std=c23 explicitly.
2. Build once with the warning set below and record the count; fix real bugs before style.
3. Run the hazard scan for a quick map of risky calls: python3 scripts/c_hazards.py src/ (add --warn-only to report without failing).
4. Run the tests under sanitizers to get a baseline before refactoring.

Compiler flags

CSTD     = -std=c17
WARN     = -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Wsign-conversion \
           -Wstrict-prototypes -Wmissing-prototypes -Wformat=2 -Wformat-truncation \
           -Wnull-dereference -Wcast-qual -Wvla -Wimplicit-fallthrough -Wundef
HARDEN   = -O2 -D_FORTIFY_SOURCE=3 -fstack-protector-strong -fstack-clash-protection \
           -fPIE
LDHARDEN = -pie -Wl,-z,relro,-z,now
DEBUG    = -O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined -fno-sanitize-recover=all

• -Werror in CI only, so new compiler versions do not break user builds.
• GCC 14+ already turns implicit function declarations, implicit int and int-to-pointer conversions into errors; on older compilers add -Werror=implicit-function-declaration -Werror=incompatible-pointer-types.
• x86-64 adds -fcf-protection=full; AArch64 adds -mbranch-protection=standard.
• _FORTIFY_SOURCE needs optimization (-O1+) to do anything.
• MSVC: /W4 /sdl /guard:cf /analyze and /fsanitize=address.

Buffers and strings

Task	Use	Never
Copy or format into a fixed buffer	snprintf(buf, sizeof buf, "%s", src) and check the return	strcpy, sprintf, strcat
Copy known-length bytes	memcpy(dst, src, n) after checking n <= cap	strncpy as a “safe strcpy” (no terminator on truncation)
Read a line	fgets(buf, sizeof buf, f) or POSIX getline(&line, &cap, f)	gets, scanf("%s")
Parse an integer	strtol/strtoull with errno, endptr and range checks	atoi, atol, sscanf("%d") without checks
Tokenize	strtok_r or a manual scan with lengths	strtok in libraries or threads
Temp file	mkstemp	tmpnam, mktemp

/* Returns 0 on success, -1 if truncated. */
static int copy_str(char *dst, size_t cap, const char *src) {
    int n = snprintf(dst, cap, "%s", src);
    return (n < 0 || (size_t)n >= cap) ? -1 : 0;
}

static int parse_port(const char *s, uint16_t *out) {
    char *end;
    errno = 0;
    long v = strtol(s, &end, 10);
    if (errno != 0 || end == s || *end != '\0' || v < 1 || v > 65535) return -1;
    *out = (uint16_t)v;
    return 0;
}

• Pass (ptr, len) or (ptr, cap) pairs; prefer a struct (struct buf { uint8_t *p; size_t len, cap; };) once the pair travels through more than one function.
• Use size_t for sizes and indices; compare signed with unsigned only after checking the signed value is non-negative.
• sizeof array / sizeof array[0] works only on real arrays, not on pointer parameters. Wrap it in a macro and never use it inside a function that received a pointer.

Allocation and arithmetic

/* n * size overflow-checked: calloc does it for you */
struct item *items = calloc(count, sizeof *items);
if (!items) return -ENOMEM;

/* growing: never assign realloc's result straight back */
size_t new_cap;
if (ckd_mul(&new_cap, cap, 2)) return -EOVERFLOW;              /* C23 <stdckdint.h> */
void *tmp = realloc(buf, new_cap * sizeof *buf);               /* check this product too */
if (!tmp) return -ENOMEM;                                      /* buf still valid, still owned */
buf = tmp; cap = new_cap;

• ckd_add/ckd_sub/ckd_mul from C23 <stdckdint.h> (GCC 14+, Clang 18+); on older compilers use __builtin_add_overflow / __builtin_mul_overflow.
• sizeof *ptr instead of sizeof(struct foo) so the type cannot drift.
• free(NULL) is a no-op; set pointers to NULL after free when the variable outlives the call.
• Signed overflow is undefined behavior; the optimizer deletes checks written as if (a + b < a). Check before the operation or use the checked builtins.
• No VLAs for sizes that come from input (-Wvla); a large n smashes the stack.

Cleanup: one exit path

int load_config(const char *path, struct config **out) {
    int rc = -1;
    FILE *f = NULL;
    char *text = NULL;
    struct config *cfg = NULL;

    f = fopen(path, "rb");
    if (!f) goto done;
    text = read_all(f, MAX_CONFIG_BYTES);
    if (!text) goto done;
    cfg = config_parse(text);
    if (!cfg) goto done;

    *out = cfg;
    cfg = NULL;          /* ownership transferred */
    rc = 0;
done:
    config_free(cfg);    /* safe on NULL */
    free(text);
    if (f) fclose(f);
    return rc;
}

• Initialize every resource variable to NULL/-1 at the top so the cleanup block is always safe.
• Make every *_free function accept NULL.
• __attribute__((cleanup(fn))) (GCC/Clang) is fine inside a codebase that already uses it; do not introduce it into portable libraries.

Designing a C API

/* mylib.h */
typedef struct mylib_ctx mylib_ctx;                 /* opaque: fields in .c only */

typedef enum { MYLIB_OK = 0, MYLIB_ENOMEM, MYLIB_EINVAL, MYLIB_EIO } mylib_status;

mylib_status mylib_open(const char *path, mylib_ctx **out);   /* caller frees with mylib_close */
void         mylib_close(mylib_ctx *ctx);                     /* NULL-safe */
mylib_status mylib_read(mylib_ctx *ctx, uint8_t *buf, size_t cap, size_t *nread);
const char  *mylib_strerror(mylib_status s);                  /* static string, do not free */

• Opaque structs keep ABI stable; expose versioned option structs (struct mylib_opts { uint32_t size; ... }) when you must pass many settings.
• Return a status; deliver results through out-parameters. Do not overload return values as “pointer or NULL” when the caller needs to know why it failed.
• Document ownership on every pointer: borrowed for the call, borrowed until close, or transferred to the caller.
• No hidden global state; take a context. If globals are unavoidable, document thread safety and protect them.
• Prefix every exported symbol (mylib_) and build with -fvisibility=hidden, exporting the public API explicitly.
• const on every pointer parameter the function does not write through.

errno and error reporting

• Read errno only immediately after a call that documents setting it and returned failure; set errno = 0 before calls like strtol whose success value is ambiguous.
• Library code returns status codes and never calls exit() or prints to stderr on behalf of the caller.
• Check return values of close, fclose and fflush on files you wrote; buffered write errors surface there.
• Mark must-check functions [[nodiscard]] (C23) or __attribute__((warn_unused_result)).

Concurrency and signals

• Shared mutable state: pthread_mutex_t or C11 <stdatomic.h>; volatile is not a synchronization primitive.
• Signal handlers may only call async-signal-safe functions and write volatile sig_atomic_t flags; no printf, malloc or locks inside.
• Use sigaction, not signal.

Debugging and verification tools

Problem	Tool
Overflow, use-after-free, double free	ASan: -fsanitize=address (rebuild everything, including tests)
Signed overflow, bad shift, misaligned access, null deref	UBSan: -fsanitize=undefined -fno-sanitize-recover=all
Leaks, uninitialized reads without rebuilding	valgrind --leak-check=full --error-exitcode=1 --track-origins=yes ./prog
Data races	TSan: -fsanitize=thread (separate build from ASan)
Static path analysis	gcc -fanalyzer, scan-build make, clang-tidy, cppcheck --enable=warning,portability
Input-dependent crashes	libFuzzer with -fsanitize=fuzzer,address

Valgrind and ASan cannot run together; run Valgrind on a non-sanitized build.

Gotchas

• char signedness is implementation-defined; cast to unsigned char before isdigit, toupper and table lookups.
• strlen is O(n); calling it in a loop condition makes the loop O(n^2).
• realloc(p, 0) behavior is implementation-defined and undefined in C23; never use it as free.
• Struct padding: never memcmp structs or write them to disk/network directly; serialize field by field with explicit widths and endianness.
• memset of a secret before free can be optimized away; use explicit_bzero or memset_explicit (C23).
• Macros: parenthesize parameters and the whole body; wrap multi-statement macros in do { ... } while (0); prefer static inline functions.
• printf("%d", size_t_value) is wrong; use %zu, and <inttypes.h> macros (PRIu64) for fixed-width types.

Verification

- [ ] Build clean with WARN flags (+ -Werror in CI) on every target compiler
- [ ] python3 scripts/c_hazards.py src/ reports no errors (justify remaining warnings)
- [ ] Tests pass under ASan+UBSan (DEBUG flags) with zero reports
- [ ] valgrind --leak-check=full --error-exitcode=1 on the test binary: no leaks
- [ ] gcc -fanalyzer or scan-build shows no new findings on changed files
- [ ] Every new pointer parameter or return documents ownership in the header

If a sanitizer fires, fix the first report only, rebuild, and rerun; later reports are often consequences of the first.