Project 2: Command Line Shell (v 1.0)
Starter repository on GitHub: https://classroom.github.com/a/aaajIUi9
The outermost layer of the operating system is called the shell. In Unix-
based systems, the shell is generally a command line interface. Most
Linux distributions ship with bash as the default (there are several
others: csh , ksh , sh , tcsh , zsh ). In this project, we’ll be
implementing a shell of our own – see, I told you that you’d come to love
command line interfaces in this class!
You will need to come up with a name for your shell first. The only
requirement is that the name ends in ‘sh’, which is tradition in the
computing world. In the following examples, my shell is named crash
(Cool Really Awesome Shell) because of its tendency to crash.
The Basics
Upon startup, your shell will print its prompt and wait for user input. Your
shell should be able to run commands in both the current directory and
those in the PATH environment variable. Use execvp to do this. To run a
command in the current directory, you’ll need to prefix it with ./ as usual.
If a command isn’t found, print an error message:
[🙂]─[1]─[mmalensek@glitter-sparkle:~/P2-malensek]$ ./he
Hello world!
[🙂]─[2]─[mmalensek@glitter-sparkle:~/P2-malensek]$ ls /
bin include lib local sbin share src
[🙂]─[3]─[mmalensek@glitter-sparkle:~/P2-malensek]$ echo
hello there!
🙂
https://classroom.github.com/a/aaajIUi9
Prompt
The shell prompt displays some helpful information. At a minimum, you
must include:
Command number (starting from 1)
User name and host name: (username)@(hostname) followed by
:
The current working directory
Process exit status
In the example above, these are separated by dashes and brackets to
make it a little easier to read. The process exit status is shown as an emoji:
a smiling face for success (exit code 0 ) and a sick face for failure (any
nonzero exit code or failure to execute the child process). For this
assignment, you are allowed to invent your own prompt format as long as
it has the elements listed above. You can use colors, unicode characters,
etc. if you’d like. For instance, some shells highlight the next command in
red text after a nonzero exit code.
You will format the current working directory as follows: if the CWD is the
user’s home directory, then the entire path is replaced with ~ .
Subdirectories under the home directory are prefixed with ~ ; if I am in
/home/mmalensek/test , the prompt will show ~/test . Here’s a test
to make sure you’ve handled ~ correctly:
[🙂]─[4]─[mmalensek@glitter-sparkle:~/P2-malensek]$ ./b
crash: no such file or directory: ./blah
[🤮]─[5]─[mmalensek@glitter-sparkle:~/P2-malensek]$ cd /
chdir: no such file or directory: /this/does/not/exist
[🤮]─[6]─[mmalensek@glitter-sparkle:~/P2-malensek]$
Scripting
Your shell must support scripting mode to run the test cases. Scripting
mode reads commands from standard input and executes them without
showing the prompt.
You should check and make sure you can run a large script with your shell.
Note that the script should not have to end in exit .
[🙂]─[6]─[mmalensek@glitter-sparkle:~]$ whoami
mmalensek
[🙂]─[7]─[mmalensek@glitter-sparkle:~]$ cd P2-malensek
# Create a directory with our full home directory in it
# **Must use the username outputted above from whoami)*
[🙂]─[8]─[mmalensek@glitter-sparkle:~/P2-malensek]$ mkd
[🙂]─[9]─[mmalensek@glitter-sparkle:~/P2-malensek]$ cd /
# Note that the FULL path is shown here (no ~):
[🙂]─[10]─[mmalensek@glitter-sparkle:/tmp/home/mmalense
/tmp/home/mmalensek/test
cat <
#include
int main(void) {
if (isatty(STDIN_FILENO)) {
printf(“stdin is a TTY; entering interactive mo
} else {
printf(“data piped in on stdin; entering script
}
return 0;
}
history , which prints the last 100 commands entered with their
command numbers
! (history execution): entering !39 will re-run command number 39,
and !! re-runs the last command that was entered. !ls re-runs the
last command that starts with ‘ls.’ Note that command numbers are
NOT the same as the array positions; e.g., you may have 100 history
elements, with command numbers 600 – 699.
jobs to list currently-running background jobs.
exit to exit the shell.
Signal Handling
Your shell should gracefully handle the user pressing Ctrl+C:
The most important aspect of this is making sure ^C doesn’t terminate
your shell. To make the output look like the example above, in your signal
handler you can (1) print a newline character, (2) print the prompt only if no
command is currently executing, and (3) fflush(stdout) .
History
Here’s a demonstration of the history command:
[🙂]─[11]─[mmalensek@glitter-sparkle:~]$ hi there oh wa
[🙂]─[11]─[mmalensek@glitter-sparkle:~]$ ^C
[🙂]─[11]─[mmalensek@glitter-sparkle:~]$ ^C
[🙂]─[11]─[mmalensek@glitter-sparkle:~]$ ^C
[🙂]─[11]─[mmalensek@glitter-sparkle:~]$ sleep 100
^C
[🤮]─[12]─[mmalensek@glitter-sparkle:~]$ sleep 5
[🙂]─[142]─[mmalensek@glitter-sparkle:~]$ history
43 ls -l
43 top
44 echo “hi” # This prints out ‘hi’
… (commands removed for brevity) …
140 ls /bin
141 gcc -g crash.c
142 history
In this demo, the user has entered 142 commands. Only the last 100 are
kept, so the list starts at command 43. If the user enters a blank
command, it should not be shown in the history or increment the
command counter.
I/O Redirection
Your shell must support file input/output redirection and pipe redirection:
# Create/overwrite ‘my_file.txt’ and redirect the outpu
[🙂]─[14]─[mmalensek@glitter-sparkle:~]$ echo “hello wo
[🙂]─[15]─[mmalensek@glitter-sparkle:~]$ cat my_file.txt
hello world!
# Append text with ‘>>’:
[🙂]─[16]─[mmalensek@glitter-sparkle:~]$ echo “hello wo
[🙂]─[17]─[mmalensek@glitter-sparkle:~]$ cat my_file.txt
hello world!
hello world!
# Pipe redirection:
[🙂]─[18]─[mmalensek@glitter-sparkle:~]$ cat other_file
(sorted contents shown)
[🙂]─[19]─[mmalensek@glitter-sparkle:~]$ seq 100000 | w
10000
[🙂]─[20]─[mmalensek@glitter-sparkle:~]$ cat /etc/passwd
(sorted contents written to ‘sorted_pwd.txt’)
Use pipe and dup2 to achieve this. Your implementation should
support arbitrary numbers of pipes, but you only need to support one file
redirection per command line (i.e., a > or >> in the middle of a pipeline is
not something you need to consider).
Background Jobs
If a command ends in & , then it should run in the background. In other
words, don’t wait for the command to finish before prompting for the next
command. If you enter jobs , your shell should print out a list of
currently-running backgrounded processes (use the original command
line as it was entered, including the & character). The status of
background jobs is not shown in the prompt.
To implement this, you will need:
A signal handler for SIGCHLD . This signal is sent to a process any
time one of its children exit.
A non-blocking call to waitpid in your signal handler. Pass in pid
= -1 and options = WNOHANG .
The difference between a background job and a regular job is simply
whether or not a blocking call to waitpid() is performed. If you do a
standard waitpid() with options = 0 , then the job will run in the
# This is equivalent, but uses input redirection instea
[🙂]─[21]─[mmalensek@glitter-sparkle:~]$ sort < /etc/pa
# This is equivalent as well. Order of < and > don’t ma
[🙂]─[22]─[mmalensek@glitter-sparkle:~]$ sort > sorted_
# Here’s input redirection by itself (not redirecting t
[🙂]─[23]─[mmalensek@glitter-sparkle:~]$ sort < sorted_
(sorted contents shown)
foreground and the shell won’t prompt for a new command until the child
finishes (the usual case). Otherwise, the process will run and the shell will
prompt for the next command without waiting.
Each background process should be stored in a job array, with a maximum
of 10 background jobs. NOTE: your shell prompt output may print in the
wrong place when using background jobs. This is completely normal.
Incremental History Search
When the user presses the ‘up’ arrow key on the keyboard, display the
most recent history entry. If the user continues to press ‘up’, they should
be able to scroll through each history entry in reverse chronological order.
Pressing ‘down’ navigates back toward the most recently-entered
command in the history, ending back at the start (a blank line).
If the user enters a string prefix, e.g., ‘ec’ before pressing the ‘up’ arrow,
only show history entries that begin with ‘ec.’ For instance, these might
include various invocations of the ‘echo’ command. The ‘down’ key works
similarly in this case. If the user edits any of the displayed history entries,
start the process over again – in other words, if one of the history entries
was echo hello and the user changes the command line to read echo
helloworld then the history search is reset and pressing up will begin
searching for ‘echo helloworld’ as the prefix instead.
You can use the rl_line_buffer variable to determine what the user
has entered – this is a global variable defined in the readline library.
Tab Completion
When the user presses the tab key, autocomplete their command. Search
in this order:
1. Each executable entry in the user’s $PATH
2. The built-in commands your shell supports
3. Local files in the current working directory
Luckily the readline library we’re using provides support for local files
as a fallback mechanism, so you are only responsible for builtins and
items in the user’s $PATH . The command_generator function you will
implement acts somewhat like an iterator; the readline library will call it
continuously to receive each autocomplete suggestion (one per function
call) until it encounters NULL.
Helpful readline variables and functions
The readline documentation provides a good starting point for using the
library. However, you can probably focus on the following to help with your
implementation:
rl_line_buffer – global variable that contains the current
command line. You probably shouldn’t manipulate this directly, but
you can use it to get a copy of the command line string.
rl_point – cursor position (index) in rl_line_buffer
rl_end – The number of characters present in rl_line_buffer
rl_replace_line() – function that allows you to change the
command line, completely replacing whatever the user has entered.
Hints
Here’s some hints to guide your implementation:
https://tiswww.case.edu/php/chet/readline/readline.html
execvp will use the PATH environment variable (already set up by
your default shell) to find executable programs. You don’t need to
worry about setting up the PATH yourself.
Check out the getlogin , gethostname , and getpwuid
functions for constructing your prompt.
Don’t use getwd to determine the CWD – it is deprecated on Linux.
Use getcwd instead.
For the cd command, use the chdir syscall.
To replace the user home directory with ~ , the strstr function
may be useful. Some creative manipulation of character arrays and
pointer arithmetic can save you some work.
Testing Your Code
Check your code against the provided test cases. You should make sure
your code runs on your Arch Linux VM. We’ll have interactive grading for
projects, where you will demonstrate program functionality and walk
through your logic.
Submission: submit via GitHub by checking in your code before the
project deadline.
Grading
26 pts - Passing the test cases
(TBA) - Code review:
Prompt, UI, and general interactive functionality. We’ll run your
shell to test this with a few commands.
Code quality and stylistic consistency
Functions, structs, etc. must have documentation in Doxygen
format (similar to Javadoc). Describe inputs, outputs, and the
https://github.com/USF-OS/Shell-Tests
http://www.doxygen.nl/
purpose of each function. NOTE: this is included in the test
cases, but we will also look through your documentation.
No dead, leftover, or unnecessary code.
You must include a README.md file that describes your program,
how it works, how to build it, and any other relevant details. You’ll
be happy you did this later if/when your revisit the codebase.
Here is an example README.md file.
Restrictions: you may use any standard C library functionality. Other than
readline , external libraries are not allowed unless permission is
granted in advance (including the GNU history library). Your shell may
not call another shell (e.g., running commands via the system function or
executing bash , sh , etc.). Do not use strtok to tokenize input. Your
code must compile and run on your VM set up with Arch Linux as
described in class. Failure to follow these guidelines will will result in a
grade of 0.
Changelog
Initial project specification posted (10/7)
https://www.cs.usfca.edu/~mmalensek/cs326/schedule/materials/kylie-readme.html