REFERENCE SHEET / ED. 001
Visual system.
Warm field manual, hard system boundaries, one signal color for the thing that changed.
Material + signal
- paper
#f0eadb - ink
#1b1d19 - signal
#ee5b2b - process
#2e7254
Color reinforces a label, outline, position, or state word. It never carries meaning alone.
Editorial + data
The machine makes sense when its boundaries have names.
PID 2184 → FD 1 → PIPE C / BACKPRESSURE
Reading primitives
A boundary worth drawing
Ordinary prose names the owner of an action. Inline evidence --flagskeeps commands distinct from claims, while linked referenceskeep the route inspectable.
Model boundary: A diagram omits detail deliberately; its caption names what changed.
command -V ls
printf 'inspect before mutate\n'| State | Meaning | Encoding |
|---|---|---|
| active | Current transition | orange + label |
| flow | Healthy movement | green + direction |
| blocked | Waiting boundary | word + pattern |
Figure catalog
Every figure renders a complete static explanation, then adds keyboard controls, replay, reset, and a persistent static-mode switch.
FIG. 01 / INTERACTIVE MODEL
One command, seven boundaries
Select a layer to inspect what changes while ls -la travels from keyboard input to rendered output.
Active boundary
keys → bytesThe terminal emulator turns key events into bytes for the pseudo-terminal.
Text equivalent
Bytes move from the terminal to the shell. The shell parses and resolvesls, prepares a child, and asks execve to replace that child's program image. The program uses system calls to read directory entries and writes result bytes to stdout, which the terminal renders.
The exact process-creation path varies by shell and libc. The durable boundary is that execve replaces an existing process image.
FIG. 02 / INTERACTIVE MODEL
Directory permissions are capabilities
Change the selected identity and mode bits. The operation ledger explains the directory-specific result.
Text equivalent
On a directory, read controls listing names, execute controls pathname search, and write plus execute controls creating or removing directory entries. The selected owner, group, or other class supplies one triplet; the kernel does not combine the three classes.
This model intentionally omits ACLs, capabilities, read-only mounts, and sticky-directory ownership checks. Those can further restrict or permit an operation after the basic mode-bit choice.
FIG. 03 / INTERACTIVE MODEL
A pipe connects live processes
Slow the final consumer to see buffered records accumulate and upstream work pause.
stderr / fd 2Not connected by |; it still points at the terminal unless redirected.
Flowing
All four processes can run concurrently; each pipe temporarily holds unread bytes.
| Input record | grep 500 | Final count |
|---|---|---|
| GET / 200 | rejected | — |
| GET /api 500 | passed | 2 /api |
| POST /login 500 | passed | 1 /login |
| GET /api 500 | passed | 2 /api |
Text equivalent
The shell starts connected processes, not a sequence of temporary files. Each pipe has a read end, a write end, and a bounded kernel buffer. If the final reader stalls long enough, its input pipe fills, then sortblocks on write; pressure can propagate toward cat.
Buffer counts are illustrative, not the kernel's byte capacity. Linux pipe capacity varies; the invariant is that reads from empty pipes and writes to full blocking pipes wait.
FIG. 04 / INTERACTIVE MODEL
Allocation and reachability are different ledgers
Switch scenarios to see why filesystem-wide df and directory-walking du can count different things.
dfdudu --apparent-size- 00V
- 01V
- 02V
- 03V
- 04V
- 05V
- 06V
- 07V
- 08M
- 09M
- 10·
- 11·
- 12·
- 13·
- 14·
- 15·
- V visible file data
- O deleted-open data
- H hidden by mount
- M metadata / reserved
- · free or sparse hole
Most allocated data is reachable by walking the directory tree; metadata still makes the totals differ slightly.
Text equivalent
df asks a filesystem for allocation totals. duwalks reachable names and sums reported blocks. Deleted-open files and data hidden beneath a mount remain allocated without being reachable from that walk. Sparse files reverse the intuition: their logical length can exceed their allocated blocks.
Counts are a teaching model, not an ext4 layout. Metadata, reservations, compression, reflinks, snapshots, and copy-on-write behavior are filesystem-specific.
FIG. 05 / INTERACTIVE MODEL
Used memory is not one kind of memory
Move through a workload. Watch reclaimable cache, anonymous pages, swap, and local cgroup pressure diverge.
Physical RAM / 100 illustrative units
Plenty of MemAvailable; no meaningful stalls.
No local limit is constraining this workload.
- 0Idle headroom
- 1File read
- 2Process allocation
- 3Reclaim + swap
- 4Cgroup limit
Text equivalent
Anonymous pages hold process-private data. File-backed page cache can often be reclaimed and re-read. “Available” estimates usable headroom better than “free” alone. Swap can preserve cold anonymous pages, while a cgroup can experience local reclaim or OOM even when the host has headroom.
Categories are deliberately simplified and not additive to every/proc/meminfo counter. Shared pages, slabs, huge pages, tmpfs, zswap, and accounting overlap require workload-specific inspection.