Skip to content
Tutorials Center
My learning

Topics

Lesson 72 of 95 ยท Projects

Project: Write a Tiny Shell in C

Build a working mini shell in C: parse commands with quotes, run them with fork, execvp and waitpid, add cd and exit builtins, pipes and file redirection.

You type commands into a shell every day, so it can feel like magic. It is not. A shell is a loop that reads a line, splits it into words, and asks the kernel to start a program. In this project you write one in about 150 lines of C. When you finish, you will understand why cd cannot be a normal program, how a pipe connects two programs, what > really does to a file descriptor, and how a shell finds out whether a command succeeded.

You build tiny, the shell, in three steps. First a tokenizer that splits a line into words and respects quotes. Then the core: fork, execvp and waitpid, plus the builtins cd, status and exit. Finally pipes (a | b | c) and redirection (<, >, >>). The C code runs on the site's server runner (Linux, GCC 15). A program that reads the console gets its text from the "Program input" box, so each tiny session is fed a list of commands there, and the shell echoes them as if you had typed them.

You should know basic C (functions, pointers, strings) and the ideas from Processes, Pipes and Pipelines and Streams and Redirection. The C lesson Processes: fork, exec and Pipes covers the system calls in more depth.

The plan

flowchart TD
  P["print prompt, read a line"] --> T["tokenize: split into words"]
  T --> B{"builtin?<br/>cd, status, exit"}
  B -- yes --> H["run it inside the shell itself"]
  B -- no --> S["split on | into stages<br/>pull out redirections"]
  S --> F["fork one child per stage,<br/>connect them with pipes"]
  F --> W["child: dup2, then execvp<br/>parent: waitpid"]
  H --> P
  W --> P

One turn of the shell's loop. Everything except the builtins happens in child processes.

Step 1: split a line into words

A command line is text, but execvp wants an array of strings, argv, ending with a null pointer. The tokenizer walks the line, cuts it at spaces and tabs, and treats a quoted section as part of the current word, so echo "two words" is two words, not three. It works in place: it writes \0 over separators and removes the quote characters by copying the rest of the word backwards, so no extra memory is needed.

C Step 1: the tokenizer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Notice three details. The last word needs special care because the string ends there (ended). argv is terminated with NULL, as execvp requires. And a blank line gives zero words, which the shell will simply skip. A real shell also handles backslashes, $variables, wildcards and ;, but this core is enough for useful work.

Step 2: fork, exec, wait

To run a command, the shell needs a new process, because exec replaces the program that calls it. If the shell ran execvp("ls", ...) itself, it would turn into ls and vanish when ls finished. So the shell forks first:

  1. fork() makes a copy of the shell. It returns twice: 0 in the child and the child's PID in the parent.
  2. In the child, execvp(argv[0], argv) replaces the copy with the requested program, searching PATH for it. If it returns at all, the program was not found, so the child prints an error and exits with code 127, the traditional "command not found" status.
  3. In the parent, waitpid() blocks until the child ends and returns its exit status. WIFEXITED and WEXITSTATUS read the code; WIFSIGNALED says that a signal such as a segmentation fault killed it, and by convention the shell reports 128 + signal number.

Why cd is a builtin

A child process has its own working directory. If cd were a separate program, it would change its directory and then exit, leaving the shell where it was. The same reasoning applies to exit and to setting shell variables: anything that must change the shell's own state has to run inside the shell. That is why cd, exit and export are builtins. Our shell adds a status builtin that prints the exit status of the previous command, much like echo $? in Bash (see Exit Codes and Error Handling).

C Step 2: run commands, with cd, status and exit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Read the session in the output. ls /nonexistent fails with exit code 2 (GNU ls uses 2 for a serious problem), a missing program gives 127, and a failed cd gives 1. Also notice fflush(stdout) before every fork. The C library buffers output; without the flush, text still sitting in the buffer would be copied into the child and could be printed twice, or appear out of order with the child's output. Flushing before you fork is a habit worth keeping.

Step 3: pipes and redirection

Two ideas finish the shell, and both rest on file descriptors: small integers that name open files in a process. 0 is standard input, 1 is standard output, 2 is standard error (see Streams and Redirection). A program just reads fd 0 and writes fd 1, and has no idea where they lead. The shell decides that before exec, using dup2(old, new), which makes descriptor new refer to the same open file as old.

  • Redirection. For cmd > out.txt the child opens out.txt and calls dup2(fd, 1). After exec, cmd writes to fd 1 as usual, and the bytes land in the file. < does the same for fd 0. >> opens with O_APPEND instead of O_TRUNC.
  • Pipes. pipe(fd) creates a kernel buffer with two ends: fd[0] to read and fd[1] to write. For a | b, the child for a gets the write end as its stdout, and the child for b gets the read end as its stdin.
TEXT
      shell (parent)
        |  pipe() -> [read end] [write end]
   +----+------------------------+
   | fork                        | fork
 child A                       child B
 stdout = write end            stdin = read end
 exec "cat file"               exec "grep an"
        \__ kernel pipe buffer __/

There is one trap, and it is the most common pipe bug: every process that holds a copy of the write end keeps the pipe open. A reader only sees end-of-file when all write ends are closed. So the parent must close its copies right after forking, and each child closes the ends it does not use. Forget this and wc waits forever.

The final program keeps the tokenizer and the builtins and turns run_command into run_pipeline. It splits the words at every | into stages, extracts the redirections of each stage into a small struct, forks one child per stage while chaining pipes, then waits for all of them. The exit status of a pipeline is the status of its last stage, as in Bash without pipefail.

C Step 3: the complete tiny shell

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Follow the session. tr a-z A-Z < fruit.txt | tr ' ' - > shout.txt runs two programs: the first reads the file through < and writes into the pipe, the second reads the pipe and writes into shout.txt through >. Compare ls nope | wc -l: ls fails and prints an error on stderr (not in the pipe), wc counts zero lines, and status reports 0 because only the last stage counts. Finally cat < missing.txt fails inside the child, which prints the open error and exits with 1.

Limits, and how to grow it

Tiny is deliberately small. These are the gaps you may want to close, roughly from easiest to hardest:

  • Operators must be separate words. a|b and ls>out are not split, and a quoted "|" is still treated as a pipe, because quotes are removed before the pipe check. A better tokenizer records which words were quoted.
  • No $VARIABLES or ~. Expand them after tokenizing with getenv; then add export as a builtin with setenv.
  • No background jobs. Detect a trailing &, skip the waitpid, and collect finished children with waitpid(-1, &st, WNOHANG) before each prompt. Compare with Jobs and Background Processes.
  • Ctrl-C and signals. A real shell ignores SIGINT itself but restores the default in children (signal() or sigaction()), so Ctrl-C stops the running command and not the shell. See Kill and Signals.
  • &&, || and ;. Split the line into a list of pipelines and use the exit status of each to decide whether to run the next.
  • Globbing. Call glob() on every word that contains *, ? or [.
  • Memory and error handling. The fixed arrays and the 1,024-byte line limit are fine for a toy. Production shells use dynamic buffers and a real parser.

Test it like a real project. Write down a list of commands and the exact output you expect, and run it after each change. A shell is a perfect candidate for the same approach used in Project: A Bash Test Framework.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why must cd be implemented as a builtin inside the shell?

    The working directory belongs to a process. A separate cd program would change its own directory and exit, leaving the shell unchanged. Commands that alter shell state must run inside the shell.
  2. 2. What does execvp do when it succeeds?

    exec replaces the calling process's program. That is why the shell forks first: the child is replaced, the shell survives. execvp only returns when it fails, for example when the program is not found.
  3. 3. In a shell, what does dup2(fd, 1) before exec accomplish?

    dup2 makes descriptor 1 refer to the open file or pipe behind fd. The program keeps writing to fd 1 and never knows the difference.
  4. 4. A pipeline hangs forever: wc never prints. Which bug is the most likely cause?

    End-of-file arrives only when every copy of the write end is closed. The parent and the unused ends in each child must be closed.
  5. 5. What exit status does our shell report for cmd1 | cmd2 when cmd1 fails and cmd2 succeeds?

    Like Bash without pipefail, the status of a pipeline is the status of its last command, so a failure earlier in the pipeline can be hidden.

Summary

  • A shell is a read-eval loop: read a line, tokenize it, run builtins itself, and run everything else in child processes.
  • fork copies the shell, execvp replaces the child with the program (exit code 127 when not found), and waitpid collects the exit status.
  • Builtins such as cd, exit and export must run inside the shell because they change its own state.
  • Redirection opens a file and uses dup2 to put it on descriptor 0 or 1 before exec. A pipe is a kernel buffer with a read end and a write end, one per neighbouring stage.
  • Close every pipe end you do not use, in the parent and in each child, or readers never see end-of-file.
  • Flush output buffers before fork to avoid duplicated or misordered text.
  • A pipeline's status is the status of its last stage.

Next: Linux and Bash Cheat Sheet