Assignment #3: Unix Shell

"Trivia" email to TA by 11:59pm, Monday, March 23.
Assignment due by 11:59pm, Monday, March 30.

Assignment Overview:

The purpose of this assignment is to become more familiar with the concepts of process control and signaling. You'll do this by writing a simple Unix shell program that supports job control.

The managing TA for this assignment is Sharanyan Srikanthan ( Please direct your questions about this assignment to the managing TA. The TA's office hours for this assignment are:

The office hours are held at CSB 726.

You can form a group of two for this assignment. You can also choose to work alone. You will be able to choose to work in a group of two for four assignments (assignments #2/#3/#4/#5). However, it is our policy that you can NOT work with the same team partner for more than two assignments. If you do, we will apply 50% penalty on your third and fourth assignments with the same grouping.

Hand Out Instructions:

Copy the file /u/cs252/labs15/shlab-handout.tar to the protected directory in which you plan to do your work. Then do the following:

Looking at the tsh.c (tiny shell) file, you will see that it contains 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. 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, type ./tsh to the command line:

    unix> ./tsh
    tsh> [type commands to your shell here]
If you want to exit your shell, but have not implemented the appropriate commands, you can type ctrl-D or ctrl-C to kill your shell.

General Overview of Unix Shells:

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 prompting for 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 ls 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:

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). Past experience indicates that obtaining exact correspondence is difficult. In some cases one might argue that different output would be equally “good;” even so, for the sake of the TA's sanity, you will receive full credit only for matching the reference solution.

Shell driver.  The program (a perl script) 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.

    unix> ./ -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:

    unix> ./ -t trace01.txt -s ./tsh -a "-p"
    unix> make test01
(The -a "-p" argument tells your shell not to emit a prompt.) And, if you want to run all of the tests on your shell, you can type:
    unix> make tests
Similarly, you can run the trace driver on the reference shell by typing:
    unix> ./ -t trace01.txt -s ./tshref -a "-p"
    unix> make rtest01
And you can run all the tests on the reference shell by typing
    unix> make rtests

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:

    unix> 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: Interrupt
    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: Stopped
    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



Your score will be computed out of a maximum of 90 points based on the following distribution:

Your solution shell will be tested for correctness on a CSUG Linux machine (likely cycle1), using the same shell driver and trace files that were included in your lab directory. Your shell should produce identical output on these traces as the reference shell, with only two exceptions: We reserve the right to run additional checks if we suspect that your program generates the "right" output for the wrong reason.

"Trivia" Assignment:

By 11:59pm on Monday, March 23, send email to TA Sharanyan Srikanthan ( with the subject line "[CSC252] Assign#3 Trivia - uname1 uname2" (without the quotes, where uname is your login name) containing answers to the following questions (a single email per team is expected):

  1. Please list your name (if you work alone) or the names of both team members.
  2. What output do you get when you run the trace driver on the reference shell? Use trace02.txt as the trace file.
  3. What do fork and execve system calls do?
  4. Explain the meaning of the WNOHANG option to the waitpid system call.


You should electronically turn in your solution through Blackboard. Before turn-in, be sure that you have

Late Turn-in Policy:

Late turn-ins will be accepted for up to three days, with 10% penalty for each late day. No turn-ins more than three-day late will be accepted.