Machine problem: Unix shell


  1. Create and manage UNIX processes with fork, exec, and wait
  2. Write signals handlers that handle exceptional control flow
  3. Implement a functional UNIX shell

Getting Files

As always, accept the GitHub invitation on the course homepage to create your private copy of the starter code repository. Clone your repository on the machine where you'll be working.

Before continuing, edit "tsh.c" and sign the header comment at the top of the file. This will serve both as an honor pledge and as a way for us to identify whose repository it is when evaluating your work.

The Shell

A shell is an interactive command-line interpreter that runs programs on behalf of the user. A shell repeatedly prints a prompt, waits for a command line on stdin, and then carries out some action, as directed by the contents of the command line.

The command line is a sequence of ASCII text words delimited by whitespace. The first word in the command line is either the name of a built-in command or the pathname of an executable file. The remaining words are command-line arguments. If the first word is a built-in command, the shell immediately executes the command in the current process. Otherwise, the word is assumed to be the pathname of an executable program. In this case, the shell forks a child process, then loads and runs the program in the context of the child. The child processes created as a result of interpreting a single command line are known collectively as a job. In general, a job can consist of multiple child processes connected by Unix pipes.

If the command line ends with an ampersand "&", then the job runs in the background, which means that the shell does not wait for the job to terminate before printing the prompt and awaiting the next command line. Otherwise, the job runs in the foreground, which means that the shell waits for the job to terminate before awaiting the next command line. Thus, at any point in time, at most one job can be running in the foreground. However, an arbitrary number of jobs can run in the background.

For example, typing the command line

tsh> jobs

causes the shell to execute the built-in jobs command.

Typing the command line

tsh> /bin/ls -l -d

runs the ls program in the foreground.

By convention, the shell ensures that when the program begins executing its main routine

int main(int argc, char *argv[])

the argc and argv arguments have the following values:

Alternatively, typing the command line

tsh> /bin/ls -l -d &

runs the ls program in the background.

Unix shells support the notion of job control, which allows users to move jobs back and forth between background and foreground, and to change the process state (running, stopped, or terminated) of the processes in a job. Typing ctrl-c causes a SIGINT signal to be delivered to each process in the foreground job. The default action for SIGINT is to terminate the process. Similarly, typing ctrl-z causes a SIGTSTP signal to be delivered to each process in the foreground job. The default action for SIGTSTP is to place a process in the stopped state, where it remains until it is awakened by the receipt of a SIGCONT signal. Unix shells also provide various built-in commands that support job control. For example:

The tsh Specification

Your tsh shell should have the following features:

Implementation details

In "tsh.c" you will find a functional skeleton of a simple Unix shell. To help you get started, we have already implemented the less interesting functions. Your assignment is to complete the remaining empty functions listed below. As a sanity check for you, we've listed the approximate number of lines of code for each of these functions in our reference solution (which includes lots of comments).

Each time you modify your "tsh.c" file, type make to recompile it. To run your shell, enter tsh at the command line:

$ ./tsh
tsh> [type commands to your shell here]

Checking Your Work

We have provided some tools to help you check your work.

Reference solution. The Linux executable tshref is the reference solution for the shell. Run this program to resolve any questions you have about how your shell should behave. Your shell should emit output that is identical to the reference solution (except for PIDs, of course, which change from run to run).

Shell driver. The program executes a shell as a child process, sends it commands and signals as directed by a trace file, and captures and displays the output from the shell.

Use the -h argument to find out the usage of

$ ./ -h
Usage: [-hv] -t <trace> -s <shellprog> -a <args>
  -h            Print this message
  -v            Be more verbose
  -t <trace>    Trace file
  -s <shell>    Shell program to test
  -a <args>     Shell arguments
  -g            Generate output for autograder

We have also provided 16 trace files ("trace{01-16}.txt") that you will use in conjunction with the shell driver to test the correctness of your shell. The lower-numbered trace files do very simple tests, and the higher-numbered tests do more complicated tests.

You can run the shell driver on your shell using trace file "trace01.txt" (for instance) by typing:

$ ./ -t trace01.txt -s ./tsh -a "-p"

(the -a "-p" argument tells your shell not to emit a prompt), or

$ make test01

Similarly, to compare your result with the reference shell, you can run the trace driver on the reference shell by typing:

$ ./ -t trace01.txt -s ./tshref -a "-p"


$ make rtest01

For your reference, tshref.out gives the output of the reference solution on all races. This might be more convenient for you than manually running the shell driver on all trace files.

The neat thing about the trace files is that they generate the same output you would have gotten had you run your shell interactively (except for an initial comment that identifies the trace). For example:

$ make test15
./ -t trace15.txt -s ./tsh -a "-p"
# trace15.txt - Putting it all together
tsh> ./bogus
./bogus: Command not found.
tsh> ./myspin 10
Job (9721) terminated by signal 2
tsh> ./myspin 3 &
[1] (9723) ./myspin 3 &
tsh> ./myspin 4 &
[2] (9725) ./myspin 4 &
tsh> jobs
[1] (9723) Running    ./myspin 3 &
[2] (9725) Running    ./myspin 4 &
tsh> fg %1
Job [1] (9723) stopped by signal 20
tsh> jobs
[1] (9723) Stopped    ./myspin 3 &
[2] (9725) Running    ./myspin 4 &
tsh> bg %3
%3: No such job
tsh> bg %1
[1] (9723) ./myspin 3 &
tsh> jobs
[1] (9723) Running    ./myspin 3 &
[2] (9725) Running    ./myspin 4 &
tsh> fg %1
tsh> quit


With 16 trace files worth 5 points each, this machine problem is worth a total of 80 points.

Your solution shell will be tested for correctness on, using the same shell driver and trace files provided to you. Your shell should produce identical output on these traces as the reference shell, with only two exceptions:

If you carefully check your shell's output against that of the reference shell before submission, you should know in advance what your grade will be!


To submit your work, commit all your changes to "tsh.c" and push to Github. Note that we will not be using any of the other files in your repository to evaluate your work (i.e., we will use a fresh set of supporting files), so be sure you're not relying on changes made outside "tsh.c"!