Designing Reliable C Interfaces Around Ownership and Failure

C gives programmers direct control over memory, resources, and operating-system interfaces. That control makes the language valuable for systems software, but it also removes many protections provided automatically by higher-level languages.

A reliable C program must make several facts clear:

• Who owns each resource?
• How long does that ownership last?
• Which operations can fail?
• How is failure communicated?
• Which cleanup operations remain necessary after failure?
• What assumptions must callers satisfy?
• What guarantees does a successful function provide?

These questions apply to memory, files, sockets, processes, threads, locks, and nearly every other resource used in systems programming.

The syntax of a C function may be small. Its behavioral contract is often much larger.

Begin With an Explicit Contract

Consider a function that allocates an integer array.

int *create_values(size_t count);

The declaration alone does not answer several important questions:

• What happens when count is zero?
• Can multiplication overflow?
• Who must release the returned memory?
• How is allocation failure reported?
• Are the elements initialized?
• Can the caller distinguish invalid input from resource exhaustion?

A stronger interface communicates more of its behavior directly.

#include <stddef.h>

enum values_status {
    VALUES_OK = 0,
    VALUES_INVALID_ARGUMENT,
    VALUES_SIZE_OVERFLOW,
    VALUES_ALLOCATION_FAILED
};

enum values_status create_values(
    size_t count,
    int **values_out
);

This version separates the operation's status from its result.

The function returns a defined status, while the allocated pointer is written through an output parameter. The caller can now distinguish several failure classes without relying on a single ambiguous null pointer.

Establishing Output Invariants

Output parameters should be initialized to a safe value before an operation that may fail.

#include <stdint.h>
#include <stdlib.h>

enum values_status create_values(
    size_t count,
    int **values_out
)
{
    if (values_out == NULL) {
        return VALUES_INVALID_ARGUMENT;
    }

    *values_out = NULL;

    if (count == 0) {
        return VALUES_INVALID_ARGUMENT;
    }

    if (count > SIZE_MAX / sizeof(int)) {
        return VALUES_SIZE_OVERFLOW;
    }

    int *values = calloc(count, sizeof(*values));

    if (values == NULL) {
        return VALUES_ALLOCATION_FAILED;
    }

    *values_out = values;

    return VALUES_OK;
}

The statement below establishes an important invariant:

*values_out = NULL;

After the function validates the output-parameter address, every later failure leaves the caller's result pointer in a known state.

If the function succeeds, the output contains a valid allocation. If it fails, the output remains NULL.

That is easier to reason about than an interface that may leave an old, uninitialized, or partially modified pointer behind.

Why Allocation Requires an Overflow Check

An allocation request often multiplies an element count by the size of one element.

Conceptually:

required bytes = element count × element size

If that multiplication exceeds the largest value representable by size_t, it wraps to a smaller value.

The allocator may then successfully reserve less memory than the caller expects. Later writes can exceed the allocation even though the original allocation call did not fail.

The defensive check is:

if (count > SIZE_MAX / sizeof(int)) {
    return VALUES_SIZE_OVERFLOW;
}

This verifies that the multiplication is representable before the allocation is attempted.

Using sizeof(*values) also ties the allocation size to the pointer's target type. If the type changes later, the allocation remains consistent without manually updating sizeof(int).

Ownership Must Transfer Deliberately

After a successful call, the caller owns the allocation.

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    int *values = NULL;

    enum values_status status =
        create_values(8, &values);

    if (status != VALUES_OK) {
        fprintf(
            stderr,
            "create_values failed with status %dn",
            status
        );

        return EXIT_FAILURE;
    }

    for (size_t index = 0; index < 8; index++) {
        values[index] = (int)(index * 10);
    }

    free(values);
    values = NULL;

    return EXIT_SUCCESS;
}

The ownership sequence is explicit:

1. values initially owns nothing.
2. create_values creates the allocation.
3. Successful completion transfers ownership to main.
4. main uses the allocation.
5. main releases it with free.
6. The pointer is set to NULL to remove the stale address from the local state.

Assigning NULL after free does not repair other aliases that may still reference the released allocation. It only helps prevent accidental reuse through that particular variable.

The deeper rule is that aliases must not outlive the resource they reference.

Resource Management Is Not Limited to Memory

A file descriptor is also an owned resource.

#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

int main(void)
{
    int fd = open(
        "systems_demo.txt",
        O_WRONLY | O_CREAT | O_TRUNC,
        0644
    );

    if (fd == -1) {
        perror("open");
        return EXIT_FAILURE;
    }

    static const char message[] =
        "Reliable interfaces make ownership visible.n";

    ssize_t bytes_written = write(
        fd,
        message,
        sizeof(message) - 1
    );

    if (bytes_written == -1) {
        perror("write");

        if (close(fd) == -1) {
            perror("close");
        }

        return EXIT_FAILURE;
    }

    if (close(fd) == -1) {
        perror("close");
        return EXIT_FAILURE;
    }

    return EXIT_SUCCESS;
}

After open succeeds, the program owns the descriptor. Every subsequent path must account for that ownership.

A failed write does not automatically close the file. The cleanup obligation still exists.

This is why error paths in systems software must be designed alongside successful paths rather than added afterward.

Handling Partial Writes

The previous example detects a failed write, but a successful write may still process fewer bytes than requested.

A reusable helper can continue until the complete buffer has been written.

#include <errno.h>
#include <stddef.h>
#include <unistd.h>

int write_all(
    int fd,
    const void *buffer,
    size_t length
)
{
    const unsigned char *cursor = buffer;
    size_t remaining = length;

    while (remaining > 0) {
        ssize_t result = write(
            fd,
            cursor,
            remaining
        );

        if (result > 0) {
            cursor += (size_t)result;
            remaining -= (size_t)result;
            continue;
        }

        if (result == -1 && errno == EINTR) {
            continue;
        }

        return -1;
    }

    return 0;
}

This function handles three important behaviors:

• A positive result advances the cursor.
• EINTR retries an interrupted system call.
• Other failures are returned to the caller.

The buffer is accepted through const void * because the function reads from it but does not modify it.

The descriptor remains caller-owned because the function did not open it and does not promise to close it.

One Cleanup Path Can Clarify Complex Functions

When a function acquires several resources, repeating cleanup code across every failure branch can become difficult to verify.

A controlled cleanup section can centralize release operations.

#include <stdio.h>
#include <stdlib.h>

int process_file(const char *path)
{
    FILE *input = NULL;
    unsigned char *buffer = NULL;
    int status = -1;

    if (path == NULL) {
        goto cleanup;
    }

    input = fopen(path, "rb");

    if (input == NULL) {
        perror("fopen");
        goto cleanup;
    }

    buffer = malloc(4096);

    if (buffer == NULL) {
        perror("malloc");
        goto cleanup;
    }

    size_t bytes_read =
        fread(buffer, 1, 4096, input);

    if (ferror(input)) {
        perror("fread");
        goto cleanup;
    }

    printf("Read %zu bytesn", bytes_read);
    status = 0;

cleanup:
    free(buffer);

    if (input != NULL && fclose(input) != 0) {
        perror("fclose");
        status = -1;
    }

    return status;
}

The goto statement is not being used for arbitrary control flow. It expresses one structured transition: stop normal processing and release everything acquired so far.

Because free(NULL) is valid and fclose is guarded, the cleanup section works for multiple partial-construction states.

Compiler Warnings Are Part of Interface Validation

Strict compilation helps expose assumptions that are easy to miss during manual review.

clang 
  -std=c17 
  -Wall 
  -Wextra 
  -Wpedantic 
  -Wconversion 
  -Wshadow 
  -Wformat=2 
  -Werror 
  reliable_interfaces.c 
  -o reliable_interfaces

Warnings-as-errors prevent suspicious constructs from quietly becoming accepted project behavior.

Useful diagnostics include:

• Implicit conversions that may lose information
• Shadowed identifiers
• Incorrect format specifiers
• Unused results or variables
• Missing declarations
• Nonportable language extensions

A successful strict build might produce:

$ clang -std=c17 -Wall -Wextra -Wpedantic -Wconversion -Wshadow -Wformat=2 -Werror reliable_interfaces.c -o reliable_interfaces
$ ./reliable_interfaces
Read 128 bytes

No compiler output is expected when the build succeeds.

Runtime Diagnostics Strengthen the Evidence

Compilation cannot prove that every memory access and resource transition is correct.

Sanitizers provide additional runtime evidence.

clang 
  -std=c17 
  -Wall 
  -Wextra 
  -Wpedantic 
  -fsanitize=address,undefined 
  -fno-omit-frame-pointer 
  -g 
  reliable_interfaces.c 
  -o reliable_interfaces_sanitized

./reliable_interfaces_sanitized

AddressSanitizer can detect problems such as:

• Out-of-bounds memory access
• Use after free
• Double free
• Some memory leaks

UndefinedBehaviorSanitizer can detect operations such as:

• Invalid shifts
• Signed-integer overflow
• Misaligned access
• Some invalid conversions and pointer operations

These tools do not replace clear ownership rules. They help test whether the implementation obeys those rules during observed executions.

Questions for Every Systems Interface

Before considering a C interface complete, I ask:

1. What inputs are valid?
2. What outputs are guaranteed?
3. Which resources are acquired?
4. Who owns each resource before and after the call?
5. How is failure represented?
6. What state remains after failure?
7. Are size calculations bounded?
8. Can an operation complete partially?
9. Are interruptions or retries relevant?
10. Which compiler, sanitizer, and test evidence supports the implementation?

These questions turn implicit assumptions into reviewable engineering decisions.

Building Toward Larger Systems

The same reasoning scales beyond small C programs.

Memory allocators must define ownership, lifetime, alignment, and failure behavior. Command-line tools must handle partial I/O, malformed input, and operating-system errors. Concurrent systems must add synchronization ownership and ordering constraints. Compilers and runtimes must manage arenas, intermediate representations, execution frames, and long-lived resources.

Reliable systems software begins by making these relationships explicit.

My continuing C and C++ project work focuses on precisely this discipline: developing modular interfaces, reasoning about memory and operating-system behavior, testing failure paths, using strict diagnostics, and preserving evidence that an implementation behaves as intended.