Workspace

fork, exec, exit codes and environment

3 day streakD

fork, exec, exit codes and environment

Unix creates a process in two steps: copy yourself, then replace the copy with a new program. Learn the steps, and what the exit status really carries.

BasicsLesson 2 of 713 min

fork() creates a child that is a near-copy of the parent: same memory contents, same open descriptors, same environment. It returns twice, once in each process. execve() then replaces the child's program with a new one while keeping its open descriptors. Between the two, the child can rearrange descriptors, change directory or drop privileges. That gap is how a shell sets up redirections and pipes.

Figure 2.1

From one process to a running command

fork, exec, exit and waitThe harness process forks a child. The child redirects stdout to a pipe with dup2, then calls execve to become bash, which runs npm test and exits with status 0. Until the harness calls waitpid, the child is a zombie. waitpid returns the status and the zombie is reaped.Harnesspid 4100Childpid 4101fork()returns 4101reads the pipestreams outputwaitpid(4101)status 0dup2(pipe, 1)stdout → pipeexecve(bash)same pid, new programnpm testruns…exit(0)zombie until reapedBetween fork and exec, the child can rearrange descriptors, change directory and drop privileges. exec keeps open descriptors.
The harness forks, the child sets up stdout as a pipe and execs bash, and bash eventually exits. The parent collects the exit status with waitpid. Until it does, the dead child lingers as a zombie.

Exit codes

A process exits with a status from 0 to 255. Zero means success; anything else is failure by convention. If a signal kills the process, there is no exit code. The parent sees the signal number instead, and shells report it as 128 plus the signal: 137 is SIGKILL, often from the OOM killer, and 143 is SIGTERM.

StatusUsually means
0Success
1General failure
2Misuse of a shell builtin or bad arguments
126Found but not executable
127Command not found
130Interrupted by SIGINT (Ctrl-C)
137Killed by SIGKILL, often out of memory
143Terminated by SIGTERM

Environment variables

The environment is a list of KEY=value strings copied into each child at exec time. Changing it later in the parent does not affect running children. Children inherit secrets too: if the harness has GITHUB_TOKEN in its environment, every command the model runs can read it unless you pass an explicit, filtered environment.

spawn.tsTypeScript
import { spawn } from "node:child_process";

const SAFE_ENV = ["PATH", "HOME", "LANG", "TERM"];

const child = spawn("bash", ["-lc", command], {
  cwd: workspace,
  // Pass an allowlist, never process.env wholesale
  env: Object.fromEntries(SAFE_ENV.map((k) => [k, process.env[k] ?? ""])),
  stdio: ["ignore", "pipe", "pipe"],
});

child.on("exit", (code, signal) => {
  // Exactly one of these is non-null
  report(signal ? `killed by ${signal}` : `exited with ${code}`);
});

Node's exit event gives code or signal. Report both, and the model can tell a test failure from an OOM kill.

Where you will meet it

OOM kills in CI

A job that ends with status 137 and no error message was usually killed by the kernel or the container runtime for exceeding its memory limit.

Secret leakage

Agent harnesses strip tokens from child environments and inject credentials through a proxy instead (Module 12).

posix_spawn

Modern runtimes often use posix_spawn or vfork instead of fork so a large parent does not pay to copy its page tables.

Check yourself

Answer out loud before you open each one.

What survives an execve call?

The PID, open descriptors not marked close-on-exec, the working directory and credentials. Memory and code are replaced.

A command exits with 137. What happened?

It received SIGKILL (128 + 9), commonly from the OOM killer or a hard timeout.

Why pass an explicit environment to model-run commands?

Children inherit the whole environment, including any secrets the harness holds.

Try it

Run bash -c 'sleep 30' & sleep 1; kill -TERM $!; wait $!; echo $?. Then repeat with kill -KILL. Explain both numbers.

A good place to start

Explore a pattern

A little guidance

Start with a pattern, read through a problem, and mark it solved when the idea clicks. Save anything you want to revisit.

New tutorials are added one at a time. Your bookmarks and solved checkmarks stay in this browser.

Explore the roadmap