LEON / COMP2017 / PROJECT 02

A bounded process notebook

Run one local program, retain a bounded stdout prefix, drain every remaining byte, and explain exactly how the child ended.

Intermediate C: one parent, one child, one pipe; complete in five guided milestones. · C11 / POSIX · EN / ZH

Download the complete project ↓Read every source file ↓Download this guide ↓

LEON / BUILD ROUTE

Build one working piece at a time

01 →
1. Define what one run means
Validate the command line and give the buffer one owner.
02 →
2. Give the child its output channel
Replace child stdout with the pipe while preserving stdin and stderr.
03 →
3. Save a prefix and keep draining
Handle empty, exact-limit, over-limit, and newline-free output with bounded memory.
04 →
4. Reap and explain the outcome
Finish descriptor cleanup and distinguish normal exit from signal termination.
05 →
5. Check the notebook against controlled children
Verify bytes, truncation, stderr policy, and status without assuming scheduling.

Text size

Build and run this project ↓

Start with a complete story

Mei checks a sensor report before sharing it with her team. One checker prints a short success message; another prints pages of detail before returning an error. Copying terminal text loses the exit status, and saving every byte wastes memory. She builds a small notebook that keeps the first C bytes, says whether more arrived, and records the child outcome. Her first success is an echo with a space inside one argument. She then faces a full pipe, a missing executable, and a final line without a newline. By the end she can explain every descriptor, every captured byte, and the remaining limits of her tool. This is an original Leon learning project, independent of supplied course assignments.

Before this project

Strings, bounded input and parsing — Read argv as an array of separate strings and validate decimal capacity without overflow.
Dynamic allocation and object lifetime — The CLI allocates the buffer, lends it to the process module, then frees it exactly once.
Translation units, symbols and libraries — Compile main.c and process.c together through the contract in process.h.
Processes, virtual memory and fork — fork returns in two processes with separate memory and copied descriptor tables.
Execute programs and reap children — Replace the child program and collect its final status with waitpid.
Pipes, FIFO endpoints and byte framing — Use pipe EOF and descriptor ownership to coordinate output and completion.

By the end, you can

Preserve argument boundaries while executing a program with fork and execvp.
Bound captured memory while draining enough output to let a child make progress.
Separate EOF, successful wait, normal exit, signal termination, and runner failure.
Test observable bytes and status codes without depending on process scheduling.

Make requirements testable

Accept CAP -- PROGRAM [ARG ...], with CAP from 0 through 65536.

The memory budget must be explicit and validated before work starts.

Check: Malformed, negative, huge, missing, and partially numeric capacities return 2 without a stdout report.

Pass the existing argv slice directly to execvp.

Joining strings would erase argument boundaries and invite shell interpretation.

Check: The fixture receives two words as one argument and $HOME;* as literal characters.

Store at most CAP bytes; continue reading until EOF.

Stopping at the cap can leave the child blocked on a full pipe.

Check: A 1 MiB burst completes with a cap of 8 or 0, and reports truncation.

Capture stdout only; inherit stdin and stderr.

A single pipe keeps ownership visible and avoids pretending that two streams have one reliable order.

Check: The stderr fixture produces an ok report and a separate diagnostic.

Close unused descriptors, reap the direct child, and decode its wait status.

EOF requires every write end to close; termination still needs waitpid.

Check: Normal exit 0, exit 7, missing program 127, and SIGTERM are reported distinctly.

Display bytes with deterministic ASCII escapes.

A captured prefix may contain NUL, controls, or only part of a multibyte character.

Check: NUL, 0xFF, quotes, backslash, tab, carriage return, and newline retain their byte identities.

Follow the data and its owner

CLI and report: main.c
Parse capacity, allocate the byte buffer, borrow argv, call the process module, escape the retained bytes, and return the child outcome.
Process lifecycle: process.c / process.h
Create a pipe and child, redirect child stdout, drain the parent read end, and reap exactly that child. The public result stores a byte count, a truncation flag, and raw wait status.
Finite child: fixtures/child.c
Generate controlled outputs and outcomes without files, descendants, input, sleeps, or network access. Burst mode writes exactly 256 blocks of 4096 bytes.
Independent checks: test.py
Compile a temporary copy and compare real output and return codes with literal expectations. Each runner has an 8-second watchdog and a private process group.

Validate → allocate → pipe → fork. Child: close read end → dup2(write end, 1) → close original write end → execvp. Parent: close write end → read to EOF → close read end → waitpid → escape and report → free. Parent and child run concurrently; there is no chosen schedule. Reads observe bytes already written, EOF follows closure of all writers and draining of queued bytes, and the final report follows a successful wait.

Who owns each resource?
Resource	Owner	Release
Pipe read end	Parent after fork; child initially has a copy.	Child closes its copy before exec; parent closes after drain or read error.
Original pipe write end	Both processes briefly after fork.	Parent closes immediately. Child closes after dup2 leaves stdout referring to the same pipe.
Child stdout, descriptor 1	Executed program and any descendants that inherit it.	Program close or process termination; every writer must close before EOF.
Capture buffer and argument vector	main owns the allocation; process_run borrows it and the argv strings.	main frees the buffer on error or after the report; borrowed argv is never freed here.
Direct child and termination status	Parent owns the responsibility to reap its returned PID.	waitpid retries EINTR and consumes termination status; read errors also attempt kill and reap.

01 / 1. Define what one run means

Validate the command line and give the buffer one owner.

Mei chooses a byte budget before running a checker. A bounded decimal parser rejects overflow before multiplying; argv already supplies the required argument boundaries.

Build the complete project with make. Read process.h before following main.
Trace 65536 through parse_capacity, then see why 65537 and 8x are rejected.
Follow malloc, process_run(&argv[3], ...), and free. The process module must not free borrowed memory.

Teaching extract from the complete project. Build the full files below to run it.

static int parse_capacity(const char *text, size_t *capacity)
{
    size_t value = 0;
    if (*text == '\0') {
        return -1;
    }
    for (const char *p = text; *p != '\0'; ++p) {
        if (*p < '0' || *p > '9') {
            return -1;
        }
        size_t digit = (size_t)(*p - '0');
        if (value > (PROCESS_MAX_CAPTURE - digit) / 10) {
            return -1;
        }
        value = value * 10 + digit;
    }
    *capacity = value;
    return 0;
}

Extract from main.c, not a standalone program. digit is 0–9. The inequality value <= (MAX-digit)/10 ensures value*10+digit stays within the cap before computing it. Empty strings and any non-digit fail.

Why pass &argv[3] instead of combining the remaining strings?

It points to the program name followed by its existing arguments and the terminating NULL. Combining them would lose which spaces are inside an argument.

02 / 2. Give the child its output channel

Replace child stdout with the pipe while preserving stdin and stderr.

fork copies descriptors, so both processes initially hold both ends. Descriptor 1 must refer to the pipe in the child before exec changes the running program.

Draw two descriptor tables immediately after fork. Each has a read end and a write end.
In the child, close the read copy, dup2 the write copy onto descriptor 1, then close the original write descriptor.
Call execvp with the unchanged argument vector. On failure, write a fixed stderr diagnostic and call _exit(127).

Teaching extract from the complete project. Build the full files below to run it.

static void execute_child(int read_end, int write_end, char *const argv[])
{
    static const char setup_error[] = "process_runner: stdout setup failed\n";
    static const char exec_error[] = "process_runner: execvp failed\n";
    (void)close(read_end);
    int copied;
    do {
        copied = dup2(write_end, STDOUT_FILENO);
    } while (copied == -1 && errno == EINTR);
    if (copied == -1) {
        (void)close(write_end);
        child_failure(setup_error, sizeof(setup_error) - 1, 126);
    }
    (void)close(write_end);
    /* The original argument boundaries survive; no command string is built. */
    execvp(argv[0], argv);
    child_failure(exec_error, sizeof(exec_error) - 1, 127);
}

Extract from process.c. The caller verifies descriptors 0–2 are open, so the new pipe descriptors exceed 2. dup2 makes stdout another reference to the write end; closing the original does not close stdout. Successful exec never returns. _exit skips copied stdio buffers and atexit callbacks.

Does closing the original write descriptor destroy the child output connection?

No. Descriptor 1 still refers to the pipe after successful dup2. That reference survives exec and closes when the program closes it or exits.

03 / 3. Save a prefix and keep draining

Handle empty, exact-limit, over-limit, and newline-free output with bounded memory.

The pipe has finite kernel capacity too. If Mei stops reading after filling her buffer and then waits, a verbose child may be waiting for pipe space. Both sides would wait forever.

For each positive read, compute space = capacity - captured and keep = min(count, space).
Copy only keep bytes. Set truncated only when some actual bytes do not fit; reaching the cap alone is not truncation.
Continue reading until zero means EOF. Retry EINTR; a final fragment is data even without a newline.

Teaching extract from the complete project. Build the full files below to run it.

static int drain_output(int read_end, unsigned char *buffer, size_t capacity,
                        struct process_result *result)
{
    unsigned char chunk[4096];
    for (;;) {
        ssize_t received = read(read_end, chunk, sizeof(chunk));
        if (received == -1 && errno == EINTR) {
            continue;
        }
        if (received == -1) {
            return -1;
        }
        if (received == 0) {
            return 0;
        }
        size_t count = (size_t)received;
        size_t space = capacity - result->captured;
        size_t keep = count < space ? count : space;
        if (keep > 0) {
            memcpy(buffer + result->captured, chunk, keep);
            result->captured += keep;
        }
        if (keep < count) {
            result->truncated = true;
        }
        /* A full buffer stops copying, never reading. The child must progress. */
    }
}

Extract from process.c. The invariant is 0 <= captured <= capacity. Each read can be short; one write need not match one read. N bytes of child output require O(N) draining work, while storage is O(C+4096) for cap C. No total-discarded-byte counter can overflow.

The child emits tail, exactly four bytes. What changes between caps 4, 3, and 0?

Cap 4 retains tail with truncated=no. Cap 3 retains tai with truncated=yes. Cap 0 retains nothing with truncated=yes. All three still drain the same four bytes.

04 / 4. Reap and explain the outcome

Finish descriptor cleanup and distinguish normal exit from signal termination.

EOF does not prove a child has terminated: it can close stdout and continue running. Conversely, a descendant can hold the pipe open after the direct child ends. Mei needs waitpid as a second completion check.

Close the parent write end before draining; otherwise the parent itself prevents EOF.
After draining, close the read end and wait for the specific child PID. Retry waitpid only when errno is EINTR.
Use wait macros, print the escaped byte prefix and status, then free the buffer. On read failure, kill the direct child and still attempt to reap it.

Teaching extract from the complete project. Build the full files below to run it.

static int report(const unsigned char *data, const struct process_result *result)
{
    print_bytes(data, result->captured);
    printf("captured_bytes=%zu\ntruncated=%s\n", result->captured,
           result->truncated ? "yes" : "no");
    if (WIFEXITED(result->wait_status)) {
        int code = WEXITSTATUS(result->wait_status);
        printf("child_exit=%d\n", code);
        return code;
    }
    if (WIFSIGNALED(result->wait_status)) {
        int number = WTERMSIG(result->wait_status);
        printf("child_signal=%d\n", number);
        return 128 + number;
    }
    fputs("process_runner: unexpected wait status\n", stderr);
    return 125;
}

Extract from main.c. WEXITSTATUS is used only after WIFEXITED; WTERMSIG only after WIFSIGNALED. The raw wait integer is not itself the exit code. Normal exit returns the child code; a signal is displayed separately and maps to 128+signal on supported systems.

Is child_exit=127 enough to prove execvp failed?

No. The selected program could return 127 itself. This project adds a fixed stderr message on exec failure, but has no separate exec-error protocol. An extra close-on-exec error pipe is a possible extension.

05 / 5. Check the notebook against controlled children

Verify bytes, truncation, stderr policy, and status without assuming scheduling.

A real child is a better check than inspecting source text. The synthetic helper produces finite, known behavior, so Mei can compute expectations independently and place a watchdog around the whole run.

Run make test. It builds a temporary copy with strict warnings and invokes only the local fixture, /bin/echo, and a deliberately missing path.
Compare exact output, byte counts, child status, and separate stderr. The burst is 256*4096=1048576 bytes regardless of read chunk sizes.
Test zero, exact and over-limit caps, literal metacharacters, nonzero exit, signal exit, binary escapes, and missing programs. Timeouts clean up only the private test process group.

Teaching extract from the complete project. Build the full files below to run it.

int main(int argc, char **argv)
{
    if (argc < 2) {
        return 2;
    }
    if (strcmp(argv[1], "args") == 0) {
        for (int i = 2; i < argc; ++i) {
            printf("[%s]", argv[i]);
        }
    } else if (strcmp(argv[1], "burst") == 0) {
        char block[4096];
        memset(block, 'A', sizeof(block));
        for (int i = 0; i < 256; ++i) {
            if (fwrite(block, 1, sizeof(block), stdout) != sizeof(block)) {
                return 3;
            }
        }
    } else if (strcmp(argv[1], "fragment") == 0) {
        fputs("tail", stdout);
    } else if (strcmp(argv[1], "fail") == 0) {
        puts("check failed");
        return 7;
    } else if (strcmp(argv[1], "stderr") == 0) {
        fputs("diagnostic\n", stderr);
        puts("ok");
    } else if (strcmp(argv[1], "bytes") == 0) {
        const unsigned char bytes[] = {0, 255, '"', '\\', '\t', '\r', '\n'};
        if (fwrite(bytes, 1, sizeof(bytes), stdout) != sizeof(bytes)) {
            return 3;
        }
    } else if (strcmp(argv[1], "signal") == 0) {
        (void)raise(SIGTERM);
        return 3;
    } else if (strcmp(argv[1], "empty") != 0) {
        return 2;
    }
    return fflush(stdout) == 0 ? 0 : 3;
}

Extract from fixtures/child.c, a separate bounded executable used by the tests. The helper neither forks nor reads stdin. Its burst is finite, its fail mode returns 7, and fragment omits the newline. These examples test this project and are not supplied assignment solutions.

What does the successful burst test prove, and what does it leave unproved?

It shows that this run drained a finite large stream while retaining only the cap and reaped the child. It does not prove every schedule, forced EINTR/error path, descendant cleanup, or a production timeout policy.

Build it, run it, read the result

Use Clang with C11 support, make and Python 3 on macOS or Linux. On Windows use a Linux environment such as WSL. The supplied Makefiles use Clang. Open a terminal in the download directory. Unzip the archive, then enter its folder. make builds the executable; make test checks its behavior.

unzip comp2017-process-runner.zip
cd comp2017-process-runner
make
make test

A first run with one space argument

./process_runner 32 -- /bin/echo 'hello team'

Expected stdout

stdout="hello team\n"
captured_bytes=11
truncated=no
child_exit=0

Exit status: 0.

The shell quotes create one hello team argument before the runner starts. The child writes 11 bytes including the newline. The runner returns 0 after EOF and waitpid.

A megabyte through an eight-byte budget

./process_runner 8 -- ./fixture_child burst

Expected stdout

stdout="AAAAAAAA"
captured_bytes=8
truncated=yes
child_exit=0

Exit status: 0.

The helper writes 1,048,576 A bytes. Only eight are retained, but all remaining output is drained so the child can finish. Truncation does not make the child fail: the runner returns 0.

A checker that reports failure

./process_runner 32 -- ./fixture_child fail

Expected stdout

stdout="check failed\n"
captured_bytes=13
truncated=no
child_exit=7

Exit status: 7.

The 13-byte message is complete, yet the child exits with 7. The runner returns 7 too. Successful capture and a successful child are different claims.

A missing executable still has a lifecycle

./process_runner 16 -- ./absent-program

Expected stdout

stdout=""
captured_bytes=0
truncated=no
child_exit=127

Exit status: 127.

The child writes process_runner: execvp failed plus a newline to inherited stderr (not shown in the stdout block), then calls _exit(127). The parent sees EOF, reaps it, and returns 127. A real program could also return 127, so the status alone is ambiguous.

Exactly full without a final newline

./process_runner 4 -- ./fixture_child fragment

Expected stdout

stdout="tail"
captured_bytes=4
truncated=no
child_exit=0

Exit status: 0.

tail is exactly four bytes. No byte is discarded, so truncated=no even though capacity is full. A newline is not needed to finish a byte stream. The runner returns 0.

Literal spaces and shell metacharacters

./process_runner 64 -- ./fixture_child args 'two words' '$HOME;*'

Expected stdout

stdout="[two words][$HOME;*]"
captured_bytes=20
truncated=no
child_exit=0

Exit status: 0.

The fixture surrounds each argument with brackets. The 20-byte result shows that two words stayed together and $HOME;* stayed literal. The runner returns 0; it never formed a command string.

Preserve the received argv vector in the runner; use shell quoting only to construct the initial arguments.

Test behavior, including failure

One argument containing a space

echo prints hello team plus newline: 11 bytes, exit 0.

Detects accidental splitting and newline loss.

Literal $HOME;* argument

The args fixture prints [two words][$HOME;*]: 20 bytes.

Detects command-string construction or expansion.

1 MiB burst with caps 8, 0, and 65536

Keep exactly the cap, report truncated=yes, and exit 0 before the watchdog.

Tests progress after capacity is exhausted, including the two limit endpoints.

Empty output at cap 0

Keep zero bytes with truncated=no, exit 0.

A zero-size budget is not itself evidence of lost data.

Final fragment tail at caps 4 and 3

Retain tail/no and tai/yes respectively, without requiring a newline.

Separates exact capacity from overflow and byte streams from lines.

A checker returns 7

Capture check failed plus newline, print child_exit=7, return 7.

Runner success must not erase the child failure status.

Missing local executable

Empty capture, fixed execvp stderr diagnostic, child_exit=127, return 127.

Exercises the child _exit path and parent EOF/wait lifecycle.

Child stderr and binary stdout

stderr stays separate; the bytes fixture reports all seven bytes with reversible escapes.

Prevents stream mixing, NUL truncation, and raw terminal-control output.

Child terminates itself with SIGTERM

Report child_signal using the platform signal number; return 128 plus that number.

Exercises a different wait-status branch without timing assumptions.

Malformed CLI, negative or excessive cap, missing program

Return 2 with usage on stderr and no stdout report.

Checks rejection before allocation/fork and guards numeric overflow.

Leon's engineering decisions

A byte budget is not a time budget

Stored bytes=min(N,C); truncated=(N>C). Draining remains O(N) and memory O(C+4096). No timeout or process-tree control exists. A child waiting on input, a descendant keeping stdout open, a blocked stderr sink, or a child that never exits can stall the run. The test watchdog belongs to test.py, not the runner.

Two output streams, one capture

stdout is captured and displayed after completion. stdin and stderr are inherited, and stderr can appear before the later stdout report without defining a merged order. Bytes use ASCII escapes rather than Unicode decoding; a cap may split a UTF-8 sequence, but its retained bytes remain visible. This is not a raw binary-copy tool.

No command string is constructed

argv boundaries remain intact. A bare program name uses inherited PATH; an explicit path selects more predictably. POSIX execvp can invoke an interpreter for an executable text file in an unrecognized format. That fallback interprets the file, not a newly joined argument string. The program inherits authority, directory, environment, and unrelated non-close-on-exec descriptors; it is not a sandbox.

Status codes have deliberate limits

Normal child exit codes pass through. Signals are displayed separately and map to 128+N. CLI errors return 2, handled runner errors 125, child setup errors 126, and exec failures 127. A child can return any of those codes itself. No exec-error pipe exists, so 127 alone cannot identify exec failure. Fixed child diagnostics remain separate on stderr.

Small POSIX scope, explicit cleanup

The module assumes one thread, open descriptors 0–2, blocking I/O, default SIGCHLD handling, and no competing reaper. read/waitpid/dup2/child diagnostic write retry EINTR. On read error, cleanup kills only the direct child and attempts to reap it. close is best effort without retry; cross-platform recovery from interrupted close is omitted. There is no application signal handler, forwarding, or user-cancel policy. An interrupted runner can leave a child; a broken report pipe can cause default SIGPIPE termination.

Read the complete files in order

These are the complete files in the download. The numbers suggest a reading order. The file list links directly to each source block.

01 / README.md
02 / README.zh.md
03 / process.h
04 / main.c
05 / process.c
06 / fixtures/child.c
07 / test.py
08 / Makefile