Project: µShell

Project: µShell
COSC 216.001

1 Overview
Each student will build their own micro-shell for executing command-line programs.
1.1 Objectives
ˆ Understanding processes and job control
ˆ Learn to interface with more advanced system calls
ˆ Increase familiarity with operating system functionality
2 Detailed Description
2.1 Introduction
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 rst word in the command
line is either the name of a built-in command or the pathname of an executable le. The remaining words
are command-line arguments. If the rst 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
1
msh> jobs
causes the shell to execute the built-in jobs command. Typing the command line
msh> /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[]) 1
the argc and argv arguments have the following values:
ˆ argc == 3,
ˆ argv[0] == /bin/ls,
ˆ argv[1]== -l,
ˆ argv[2]== -d.
Alternatively, typing the command line
msh> /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:
ˆ jobs: List the running and stopped background jobs.
ˆ bg <job>: Change a stopped background job to a running background job.
ˆ fg <job>: Change a stopped or running background job to a running in the foreground.
ˆ kill <job>: Terminate a job.
2.2 What to do
You are provided with compressed archive of les for this project. You will need to transfer these les
to the computer where you complete the project. For this project, it is important that your system
conform to the Unix system call interface. We have only tested this project on the course Linux server:
tpaclinux.montgomerycollege.edu
Start by copying the le uShell-handout.tgz to the directory in which you plan to do your work. Then do
the following:
2
ˆ Type the command tar xvzf uShell-handout.tgz to expand the tarle.
ˆ Type the command make to compile and link some test routines.
Looking at the msh.c (micro shell) le, 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 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).
ˆ eval: Main routine that parses and interprets the command line. [70 lines]
ˆ builtin_cmd: Recognizes and interprets the built-in commands: quit, fg, bg, and jobs. [25 lines]
ˆ do_bgfg: Implements the bg and fg built-in commands. [50 lines]
ˆ waitfg: Waits for a foreground job to complete. [20 lines]
ˆ sigchld_handler: Catches SIGCHILD signals. 80 lines]
ˆ sigint_handler: Catches SIGINT (ctrl-c) signals. [15 lines]
ˆ sigtstp_handler: Catches SIGTSTP (ctrl-z) signals. [15 lines]
Each time you modify your msh.c le, type make to recompile it. To run your shell, type msh to the command
line:
unix> ./msh
msh> [type commands to your shell here]
The msh Specication
Your msh shell should have the following features:
ˆ The prompt should be the string msh> .
ˆ The command line typed by the user should consist of a name and zero or more arguments, all separated
by one or more spaces. If name is a built-in command, then msh should handle it immediately and wait
for the next command line. Otherwise, msh should assume that name is the path of an executable le,
which it loads and runs in the context of an initial child process (In this context, the term job refers
to this initial child process).
ˆ msh need not support pipes (|) or I/O redirection (< and >).
ˆ Typing ctrl-c (ctrl-z) should cause a SIGINT (SIGTSTP) signal to be sent to the current foreground
job, as well as any descendents of that job (e.g., any child processes that it forked). If there is no
foreground job, then the signal should have no eect.
ˆ If the command line ends with an ampersand &, then msh should run the job in the background.
Otherwise, it should run the job in the foreground.
3
ˆ Each job can be identied by either a process ID (PID) or a job ID (JID), which is a positive integer
assigned by msh. JIDs should be denoted on the command line by the prex '%'. For example, %5
denotes JID 5, and 5 denotes PID 5. (We have provided you with all of the routines you need for
manipulating the job list.)
ˆ msh should support the following built-in commands:
 The quit command terminates the shell.
 The jobs command lists all background jobs.
 The bg <job> command restarts <job> by sending it a SIGCONT signal, and then runs it in the
background. The <job> argument can be either a PID or a JID.
 The fg <job> command restarts <job> by sending it a SIGCONT signal, and then runs it in the
foreground. The <job> argument can be either a PID or a JID.
ˆ msh should reap all of its zombie children. If any job terminates because it receives a signal that
it didn't catch, then msh should recognize this event and print a message with the job's PID and a
description of the oending signal.
Checking Your Work
We have provided some tools to help you check your work.
Reference solution. The Linux executable mshref 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 sdriver.pl program executes a shell as a child process, sends it commands and signals
as directed by a trace le, and captures and displays the output from the shell.
Use the -h argument to nd out the usage of sdriver.pl:
unix> ./sdriver.pl -h
Usage: sdriver.pl [-hv] -t <trace> -s <shellprog> -a <args>
Options:
-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 les (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 les do very simple tests, and the
higher-numbered tests do more complicated tests.
You can run the shell driver on your shell using trace le trace01.txt (for instance) by typing:
unix> ./sdriver.pl -t trace01.txt -s ./msh -a "-p"
(the -a "-p" argument tells your shell not to emit a prompt), or
4
unix> make test01
Similarly, to compare your result with the reference shell, you can run the trace driver on the reference shell
by typing:
unix> ./sdriver.pl -t trace01.txt -s ./mshref -a "-p"
or
unix> make rtest01
For your reference, mshref.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 les.
The neat thing about the trace les is that they generate the same output you would have gotten had you
run your shell interactively (except for an initial comment that identies the trace). For example:
bass> make test15
./sdriver.pl -t trace15.txt -s ./msh -a "-p"
#
# trace15.txt - Putting it all together
#
msh> ./bogus
./bogus: Command not found.
msh> ./myspin 10
Job (9721) terminated by signal 2
msh> ./myspin 3 &
[1] (9723) ./myspin 3 &
msh> ./myspin 4 &
[2] (9725) ./myspin 4 &
msh> jobs
[1] (9723) Running ./myspin 3 &
[2] (9725) Running ./myspin 4 &
msh> fg %1
Job [1] (9723) stopped by signal 20
msh> jobs
[1] (9723) Stopped ./myspin 3 &
[2] (9725) Running ./myspin 4 &
msh> bg %3
%3: No such job
msh> bg %1
[1] (9723) ./myspin 3 &
msh> jobs
[1] (9723) Running ./myspin 3 &
[2] (9725) Running ./myspin 4 &
msh> fg %1
msh> quit
bass>
Hints
ˆ Read every word of Chapter 8 (Exceptional Control Flow) in your textbook.
5
ˆ Use the trace les to guide the development of your shell. Starting with trace01.txt, make sure that
your shell produces the identical output as the reference shell. Then move on to trace le trace02.txt,
and so on.
ˆ The waitpid, kill, fork, execve, setpgid, and sigprocmask functions will come in very handy. The
WUNTRACED and WNOHANG options to waitpid will also be useful.
ˆ When you implement your signal handlers, be sure to send SIGINT and SIGTSTP signals to the entire
foreground process group, using -pid instead of pid in the argument to the kill function. The
sdriver.pl program tests for this error.
ˆ One of the tricky parts of the assignment is deciding on the allocation of work between the waitfg
and sigchld_handler functions. We recommend the following approach:
 In waitfg, use a busy loop around the sleep function.
 In sigchld_handler, use exactly one call to waitpid.
While other solutions are possible, such as calling waitpid in both waitfg and sigchld_handler,
these can be very confusing. It is simpler to do all reaping in the handler.
ˆ In eval, the parent must use sigprocmask to block SIGCHLD signals before it forks the child, and then
unblock these signals, again using sigprocmask after it adds the child to the job list by calling addjob.
Since children inherit the blocked vectors of their parents, the child must be sure to then unblock
SIGCHLD signals before it execs the new program.
The parent needs to block the SIGCHLD signals in this way in order to avoid the race condition where
the child is reaped by sigchld_handler (and thus removed from the job list) before the parent calls
addjob.
ˆ Programs such as more, less, vi, and emacs do strange things with the terminal settings. Don't run
these programs from your shell. Stick with simple text-based programs such as /bin/ls, /bin/ps, and
/bin/echo.
ˆ When you run your shell from the standard Unix shell, your shell is running in the foreground process
group. If your shell then creates a child process, by default that child will also be a member of the
foreground process group. Since typing ctrl-c sends a SIGINT to every process in the foreground
group, typing ctrl-c will send a SIGINT to your shell, as well as to every process that your shell
created, which obviously isn't correct.
Here is the workaround: After the fork, but before the execve, the child process should call setpgid(0,
0), which puts the child in a new process group whose group ID is identical to the child's PID. This
ensures that there will be only one process, your shell, in the foreground process group. When you type
ctrl-c, the shell should catch the resulting SIGINT and then forward it to the appropriate foreground
job (or more precisely, the process group that contains the foreground job).
3 Submission
Each of your source code les must have a comment near the top that contains your name, StudentID, and
M-number.
The project should be submitted via Blackboard by November 29, 2021, 11:59pm. Follow these instructions to turn in your project.
You should submit the following les:
6
ˆ msh.c
ˆ any other source les your project needs
The following submission directions use the instructions that we will use for all projects this semester.
1. create a directory for your project:
mkdir uShell 1
2. create (or copy) all of your source les in this directory. Example: To copy a le called example.c into
your uShell directory:
cp example.s uShell 1
3. Create a tar le named <user_name>.tar.gz, where <user_name> is your studentID and <proj_dir>
is the directory containing the code for your project, by typing:
tar -czf <user_name>.tar uShell
2
4. Finally, submit the compressed tar le to Blackboard in accordance with the class policies.
Late assignments will not be given credit.
4 Grading
Your score will be computed out of a maximum of 100 points based on the following distribution:
80 Correctness: 16 trace les at 5 points each.
20 Style points. We expect you to have good comments (10 pts) and to check the return value of EVERY
system call (10 pts).
Your solution shell will be tested for correctness on a Linux machine, using the same shell driver and trace
les that were included in your lab directory. Your shell should produce identical output on these traces
as the reference shell, with only two exceptions:
ˆ The PIDs can (and will) be dierent.
ˆ The output of the /bin/ps commands in trace11.txt, trace12.txt, and trace13.txt will be different from run to run. However, the running states of any mysplit processes in the output of the
/bin/ps command should be identical.
7