UNIX System Calls

# UNIX System Calls

### CS 631 Systems Foundations — Apr 23, 2026

Nine small Octox programs, one big interface.

---

## Today's Agenda

1. What is a system call?
2. The Octox syscall surface
3. File descriptors & `omode` flags
4. `ex_args` — argv
5. `ex_count` — `open` + `read` loop
6. `ex_write` — `open(CREATE|TRUNC)` + `write`
7. `ex_fork` — `fork` / `wait` / `exit`
8. `ex_exec` — `fork` + `exec` + `wait`
9. `ex_redir`, `ex_redir2` — `dup2`
10. `ex_pipe`, `ex_pipe2` — kernel pipes
11. Building a shell from 7 syscalls

---

## Two Big UNIX Ideas

1. **Everything is a file descriptor.** Files, pipes, sockets, devices — all read and written with the same two syscalls.

2. **Making a new process is split in two.**
   `fork` duplicates the caller.
   `exec` replaces the program running inside the duplicate.

<div class="info-box">
The seam between <code>fork</code> and <code>exec</code> is where a shell sets up redirection and pipes — <em>without</em> cooperation from the program it runs.
</div>

---

## What Is a System Call?

<div class="mermaid">
flowchart LR
    U["user main()"] --> W["sys::fork wrapper<br/>(user mode)"]
    W --> E["ecall<br/>trap"]
    E --> K["kernel trap<br/>handler"]
    K --> S["fork impl<br/>(kernel)"]
    S --> R["sret"]
    R --> W
    W --> U
</div>

A function whose body runs in kernel mode. Hardware forces the transition.

---

## RISC-V `ecall` ABI

| Register | Holds |
|----------|-------|
| `a7` | syscall number |
| `a0`..`a5` | arguments |
| `a0` (after) | return value: `Ok` value or negative error |

The `ulib::sys` wrappers hide the `ecall`: you call `sys::fork()`, get back `Result<usize>`.

---

## The Octox Syscall Surface

```rust
fn fork()   -> Result<usize>        // child: 0; parent: child pid
fn exit(xstatus: i32) -> !
fn wait(x: &mut i32) -> Result<usize>
fn pipe(p: &mut [usize]) -> Result<()> // p[0]=read, p[1]=write
fn read(fd: usize, buf: &mut [u8])  -> Result<usize>
fn write(fd: usize, b: &[u8])       -> Result<usize>
fn exec(filename: &str, argv: &[&str],
        envp: Option<&[Option<&str>]>) -> Result<usize>
fn open(filename: &str, flags: usize) -> Result<usize>
fn close(fd: usize) -> Result<()>
fn dup(fd: usize) -> Result<usize>
fn dup2(src: usize, dst: usize) -> Result<usize>
fn getpid() -> Result<usize>
```

`print!`/`println!` are **not** syscalls — they call `sys::write` on fd 1.

---

## File Descriptors

A small integer indexing a per-process open-file table.

| fd | constant | normally |
|----|----------|----------|
| 0 | `STDIN_FILENO` | keyboard / pipe input |
| 1 | `STDOUT_FILENO` | terminal / pipe output |
| 2 | `STDERR_FILENO` | terminal |

- `fork` copies the whole fd table.
- `exec` **preserves** the fd table.
- Files, pipes, and devices are all just fds.

---

## `omode` Flags

| Flag | Value | Meaning |
|------|-------|---------|
| `RDONLY` | `0x000` | read only |
| `WRONLY` | `0x001` | write only |
| `RDWR`   | `0x002` | read and write |
| `CREATE` | `0x200` | create if missing |
| `TRUNC`  | `0x400` | shrink to 0 on open |
| `APPEND` | `0x800` | writes go at end |

Canonical "open for output": `WRONLY | CREATE | TRUNC`.

---

## 1. `ex_args` — Command-Line Arguments

```rust
#![no_std]
use ulib::{env, print, println};

fn main() {
    // Iterate every entry (including argv[0]) and echo it on its own line.
    for arg in env::args() {
        println!("{}", arg);
    }
}
```

`env::args()` walks the argv the kernel handed to `exec`. `argv[0]` is the program name by convention.

---

## argv Intuition

```
$ ex_args hello world
ex_args
hello
world
```

- The kernel sets up `argv` on the new program's stack during `exec`.
- `ulib`'s `lang_start` wrapper publishes it as `env::ARGS`.
- `env::args()` is a tiny iterator over that slice.

---

## 2. `ex_count` — `open` + `read` Loop

```rust
#![no_std]
use ulib::{env, print, println, sys, sys::fcntl::omode};

fn main() {
    let mut args = env::args().skip(1);
    let path = args.next().expect("usage: ex_count FILE");

let fd = sys::open(path, omode::RDONLY).expect("open");

let mut buf = [0u8; 512];
    let mut count: usize = 0;
    loop {
        let n = sys::read(fd, &mut buf).expect("read");
        if n == 0 { break; }   // EOF
        count += n;
    }
    sys::close(fd).expect("close");

println!("{}: {} bytes", path, count);
}
```

---

## Why the Read Loop?

<div class="info-box">
<code>read</code> may return <strong>fewer bytes</strong> than your buffer holds. <code>Ok(0)</code> means EOF. Always loop until you see zero.
</div>

- Each call = one trip into the kernel.
- The kernel gives you whatever is conveniently available right now.
- Partial reads are normal — not an error.
- Same for `write`.

---

## 3. `ex_write` — `open(CREATE|TRUNC)` + `write`

```rust
#![no_std]
use ulib::{env, sys, sys::fcntl::omode};

fn main() {
    let mut args = env::args().skip(1);
    let path = args.next().expect("usage: ex_write FILE TEXT");
    let text = args.next().expect("usage: ex_write FILE TEXT");

let fd = sys::open(path, omode::WRONLY | omode::CREATE | omode::TRUNC)
        .expect("open");

let bytes = text.as_bytes();
    let mut off = 0;
    while off < bytes.len() {
        let n = sys::write(fd, &bytes[off..]).expect("write");
        off += n;
    }

sys::close(fd).expect("close");
}
```

---

## Flag Combinations

<table>
<thead><tr><th>Intent</th><th>Flags</th></tr></thead>
<tbody>
<tr><td>read existing file</td><td><code>RDONLY</code></td></tr>
<tr><td>overwrite or create</td><td><code>WRONLY | CREATE | TRUNC</code></td></tr>
<tr><td>append (create if missing)</td><td><code>WRONLY | CREATE | APPEND</code></td></tr>
<tr><td>error if exists</td><td>(not in octox; needs <code>O_EXCL</code> on Linux)</td></tr>
<tr><td>read + write existing</td><td><code>RDWR</code></td></tr>
</tbody>
</table>

---

## 4. `ex_fork` — Two Processes from One

```rust
#![no_std]
use ulib::{print, println, sys};

fn main() {
    let mut x: i32 = 100;
    println!("before fork: x={}", x);

match sys::fork().expect("fork") {
        0 => {
            // --- child ---
            x += 1;
            println!("child : pid={} x={}", sys::getpid().unwrap(), x);
            sys::exit(0);
        }
        child_pid => {
            // --- parent ---
            let mut status: i32 = 0;
            sys::wait(&mut status).expect("wait");
            println!("parent: pid={} x={} (child {} exited with {})",
                sys::getpid().unwrap(), x, child_pid, status);
        }
    }
}
```

---

## `fork` Returns Twice

- Returns `Ok(0)` in the **child**.
- Returns `Ok(child_pid)` in the **parent**.
- After `fork`, parent and child are two independent processes with separate copies of every variable.

<div class="info-box">
<strong>Copy-on-write.</strong> The kernel doesn't literally duplicate memory. Pages are shared read-only until someone writes — then that page is copied.
</div>

Run it:

```
before fork: x=100
child : pid=6 x=101
parent: pid=5 x=100 (child 6 exited with 0)
```

Parent's `x` is still 100.

---

## 5. `ex_exec` — Replace the Program

```rust
#![no_std]
use ulib::{print, println, sys};

fn main() {
    match sys::fork().expect("fork") {
        0 => {
            // --- child ---
            let argv = ["sleep", "10"];
            sys::exec("/bin/sleep", &argv, None).expect("exec");
            sys::exit(1);  // unreachable on success
        }
        child => {
            // --- parent ---
            println!("parent: launched child pid={}, waiting...", child);
            let mut status: i32 = 0;
            let reaped = sys::wait(&mut status).expect("wait");
            println!("parent: child {} exited with {}", reaped, status);
        }
    }
}
```

---

## `exec` Semantics

- On **success**, `exec` does **not return** — the old program is gone.
- Code after `exec` only runs if `exec` *failed*.
- `argv[0]` is conventionally the program name; real args start at `argv[1]`.
- **File descriptors are preserved** across `exec` (unless marked close-on-exec).
- Octox binaries are *built* as `_<name>` to avoid clashing with host binaries; `mkfs` strips the `_` so they live at `/bin/<name>`. `exec` takes a full path; no PATH search.

<div class="info-box">
Between <code>fork</code> and <code>exec</code> is where a shell does setup work: open files, dup2, close, setuid, ...
</div>

---

## 6. `ex_redir` — Rewire Your Own Stdout

```rust
match sys::fork().expect("fork") {
    0 => {
        // --- child ---
        let fd = sys::open(path,
            omode::WRONLY | omode::CREATE | omode::TRUNC).expect("open");

// Redirect stdout. After this call, fd 1 refers to the file.
        sys::dup2(fd, STDOUT_FILENO).expect("dup2");
        sys::close(fd).expect("close");

println!("hello from child: my stdout is redirected");
        sys::exit(0);
    }
    _ => {
        let mut status: i32 = 0;
        sys::wait(&mut status).expect("wait");
        println!("parent: child finished; my stdout is still the terminal");
    }
}
```

---

## `dup2` Picture

Before `dup2(fd, 1)`:

```
fd 0  ─► terminal
fd 1  ─► terminal
fd 2  ─► terminal
fd 3  ─► /tmp/r     ← from open()
```

After `dup2(fd, 1)` then `close(fd)`:

```
fd 0  ─► terminal
fd 1  ─► /tmp/r     ← writes now land in the file
fd 2  ─► terminal
```

<div class="info-box">
<code>dup2(src, dst)</code> atomically closes <code>dst</code> and makes it an alias for <code>src</code>.
</div>

---

## 7. `ex_redir2` — fds Survive `exec`

```rust
match sys::fork().expect("fork") {
    0 => {
        let fd = sys::open(path,
            omode::WRONLY | omode::CREATE | omode::TRUNC).expect("open");
        sys::dup2(fd, STDOUT_FILENO).expect("dup2");
        sys::close(fd).expect("close");

// fd 1 is already the file. The execed program writes to
        // stdout "normally" and never knows it is being redirected.
        let argv = ["echo", "hello", "from", "exec"];
        sys::exec("/bin/echo", &argv, None).expect("exec");
        sys::exit(1);
    }
    _ => {
        let mut status: i32 = 0;
        sys::wait(&mut status).expect("wait");
    }
}
```

---

## How a Shell Does `cmd > file`

```
fork()
if child:
    fd = open(file, WRONLY | CREATE | TRUNC)
    dup2(fd, 1)
    close(fd)
    exec(cmd, argv)
else:
    wait()
```

- The program named by `cmd` never knows it's being redirected.
- Works for *any* program — no cooperation needed.
- Same pattern with `dup2(fd, 0)` implements `cmd < file`.

---

## 8. `ex_pipe` — Bytes Between Processes

```rust
let mut p = [0usize; 2];
sys::pipe(&mut p).expect("pipe");
let (read_fd, write_fd) = (p[0], p[1]);

match sys::fork().expect("fork") {
    0 => {
        // --- child: writer ---
        sys::close(read_fd).expect("close");
        sys::write(write_fd, b"hello from child\n").expect("write");
        sys::close(write_fd).expect("close");
        sys::exit(0);
    }
    _ => {
        // --- parent: reader ---
        sys::close(write_fd).expect("close");
        let mut buf = [0u8; 64];
        let n = sys::read(read_fd, &mut buf).expect("read");
        sys::close(read_fd).expect("close");
        sys::write(STDOUT_FILENO, &buf[..n]).expect("write");
        let mut st = 0i32;
        sys::wait(&mut st).expect("wait");
    }
}
```

---

## The Pipe Invariant

After `pipe` + `fork`, **both** processes hold **both** ends.

<div class="highlight-box">
<code>read</code> returns <strong>EOF</strong> on a pipe only when <em>every</em> open write-end fd has been closed. If the reader forgets to close its own copy of the write end, it will read its own EOF — never — and deadlock.
</div>

Convention: each side closes the end it does not use, immediately after `fork`.

---

## 9. `ex_pipe2` — `ls | wc` (1/2)

```rust
let mut p = [0usize; 2];
sys::pipe(&mut p).expect("pipe");
let (read_fd, write_fd) = (p[0], p[1]);

// --- child 1: producer (ls) ---
match sys::fork().expect("fork") {
    0 => {
        sys::dup2(write_fd, STDOUT_FILENO).expect("dup2");
        sys::close(read_fd).expect("close");
        sys::close(write_fd).expect("close");
        let argv = ["ls"];
        sys::exec("/bin/ls", &argv, None).expect("exec");
        sys::exit(1);
    }
    _ => {}
}
```

---

## `ex_pipe2` — `ls | wc` (2/2)

```rust
// --- child 2: consumer (wc) ---
match sys::fork().expect("fork") {
    0 => {
        sys::dup2(read_fd, STDIN_FILENO).expect("dup2");
        sys::close(read_fd).expect("close");
        sys::close(write_fd).expect("close");
        let argv = ["wc"];
        sys::exec("/bin/wc", &argv, None).expect("exec");
        sys::exit(1);
    }
    _ => {}
}

// --- parent: CLOSE BOTH ENDS or wc hangs forever ---
sys::close(read_fd).expect("close");
sys::close(write_fd).expect("close");

let mut status: i32 = 0;
sys::wait(&mut status).expect("wait 1");
sys::wait(&mut status).expect("wait 2");
```

---

## `ls | wc` Layout

<div class="mermaid">
flowchart LR
    P1["child1<br/>ls"] -- "stdout = write_fd" --> PIPE["pipe<br/>buffer"]
    PIPE -- "read_fd = stdin" --> P2["child2<br/>wc"]
    PARENT["parent<br/>(closes both ends,<br/>waits twice)"] -.-> P1
    PARENT -.-> P2
</div>

Each child `dup2`'s one pipe end onto stdin or stdout *before* `exec`, so `ls` and `wc` run as if they had a normal terminal on the other side.

---

## Why the Parent Must Close Both

<div class="highlight-box">
If <em>any</em> process still holds the write end open, <code>wc</code>'s final <code>read</code> will block forever waiting for EOF.
</div>

- The parent called `pipe` *before* the children existed, so the parent holds both ends too.
- Each child closes its own extras as part of setup.
- The parent must close the ends it held before the children's closes can "count."

---

## Building a Shell from 7 Syscalls

<table>
<thead><tr><th>Shell feature</th><th>Syscall recipe</th></tr></thead>
<tbody>
<tr><td>Run a command</td><td><code>fork</code> → child <code>exec</code>; parent <code>wait</code></td></tr>
<tr><td>Background</td><td><code>fork</code> → <code>exec</code>; parent does <strong>not</strong> <code>wait</code></td></tr>
<tr><td><code>cmd > file</code></td><td><code>fork</code> → <code>open</code> + <code>dup2(fd,1)</code> + <code>close</code> → <code>exec</code></td></tr>
<tr><td><code>cmd < file</code></td><td><code>fork</code> → <code>open</code> + <code>dup2(fd,0)</code> + <code>close</code> → <code>exec</code></td></tr>
<tr><td><code>a | b</code></td><td><code>pipe</code>; <code>fork</code>×2; each child <code>dup2</code>s one end; parent closes both, <code>wait</code>×2</td></tr>
</tbody>
</table>

The Octox shell is built from exactly this toolkit (see `src/user/bin/sh.rs`).

---

## Key Takeaways

- A **syscall** is a function whose body runs in kernel mode; reached via `ecall`.
- **Everything is a file descriptor** — `read`/`write` work uniformly.
- **`fork` returns twice**; parent and child have independent memory.
- **`exec` does not return** on success; fds survive it.
- **`dup2`** is how redirection works — *atomically* rewire an fd.
- **Pipes + fork + dup2** build pipelines.
- **Close every unused fd.** Pipe EOF depends on it.

---

## Further Reading

- The nine programs: `src/user/bin/ex_*.rs` in the [Octox repo](https://github.com/USF-CS631-S26/octox)
- [Octox Guide](../guides/octox-guide.md) — architecture, build, adding a user program
- xv6 book, ch. 1 (OS Interfaces), ch. 8 (File System)
- On Linux: `man 2 fork`, `man 2 execve`, `man 2 open`, `man 2 pipe`, `man 2 dup2`