A shell is a command-interpreter used widely on Unix-based systems. Most shells receive character-based input, typically read from a keyboard or a textfile, parse their input into a token sequence forming the syntax recognised by the shell (command names, command arguments, and controlflow delimiters), and then attempt to execute the token sequence. The shell used by most CSSE students under macOS and Linux is named bash (the Bourne Again Shell); a former CSSE graduate is the author of a very popular book describing the Bash shell.
The goal of this project is to implement a program named myshell supporting a small subset of the features of a standard Unix-based shell. Successful completion of the project will develop your understanding of some advanced features of the C99 programming language, and your understanding of the role of a number of system-calls responsible for process invocation and monitoring, and input and output management using file and pipe descriptors.
NOTE - this is a systems-specific project. You will find this project significantly easier to complete on macOS or Linux. You will likely have great difficulty completing it on Windows, and it is recommended that you don’t try. As for the 1st project, your submission will be tested and marked on CSSE macOS laboratory machines.
A number of C99 source code files are provided as a starting skeleton for the project. The most challenging-to-write part of the project, the command parser, has been written for you, and should be used without modification (and need not be understood). The parser returns a pointer to a binary tree of shell commands which your code will traverse and execute.
In summary, the function parse_shellcmd(FILE *fp) accepts a FILE pointer as its only input, and attempts to read and parse its input. If successful, function parse_shellcmd() returns a pointer to a user-defined datatype named SHELLCMD, a self-referential structure holding all information necessary to execute the requested command-sequence. Your role is to execute the commands in the structure by (implementing and) calling your own function named execute_shellcmd().
The project only requires implementation of a small subset of a traditional Unix shell. However, that subset will be quite faithful to standard shells. For this reason, this project description does not specify all details in great detail. If unsure about the role and action of shell features listed in these steps, you should experiment with the same feature in your standard shell, bash (or obviously ask on help2002).
The approach taken to develop the sample solution has been broken into 9 independent steps, presented below. There’s no requirement for you to follow these steps, but they are described here to provide an obvious pathway to a solution, and to explain the project’s required features.
Develop a Makefile, employing variable definitions and automatic variables, to compile and link the project’s files.
- execute commands without arguments, such as /bin/ls
- execute commands with arguments, such as /usr/bin/cal -y
Helpful C99 and POSIX functions: fork(), execv(), exit(), wait(). DO NOT use the functions: system(), popen(), execlp(), or execvp() anywhere in your project.
The global variable PATH points to a character string which is interpreted as a colon separated list of directory names.
If the user enters a command name which does not contain a ‘/‘ character, then the members of the search path list are considered as directories from which to attempt to execute the required command. Once the required command is found and executed, the search terminates.
Helpful C99 and POSIX functions: strchr().
Internal commands are performed by myshell, itself, rather than by external commands. myshell does not create a new process, with fork(), before running an internal command. Three internal commands are to be supported:
exit - terminate myshell by calling the function exit(). When an additional argument is provided, it should be interpreted as the numeric exit-status. When requested without any arguments, the exit-status of the recently executed command should be used.
cd - change from the current working (default) directory to the directory specified as the first argument to the cd command. If the command cd is given without arguments, then the variable HOME should be used as the new directory. As with the role of PATH for command execution, the variable CDPATH points to a character string which is interpreted as a colon separated list of directory names. If the user enters a directory-name which does not contain commence with a ‘/‘ character, then the members of CDPATH are considered as directories to locate the required directory.
time - the ‘following’ command’s execution time should be reported in milliseconds (e.g. 84msec) to myshell’s stderr stream.
Helpful C99 and POSIX functions: exit(), chdir(), gettimeofday().
There are three forms of sequential execution, and thus three subparts to this step. The three forms differ in the action they take when a command fails. By convention, a command which fails will return a non-zero exit status.
A sequence of commands separated by the “;” token requires myshell to execute each command sequentially, waiting until each command has finished before beginning the next. In this form, myshell should continue to the next command regardless of the result of earlier commands. The sequence ls ; date monday ; ps would execute ls, then on its completion execute date monday (which will fail), then execute ps (even though the previous command failed). The exit value of sequential execution is the exit status of the command sequence to the right of the “;” token.
If the commands are separated by the token “&&” then myshell should continue with further commands only if the command sequence to the left of the token returns an exit value indicating success. For the command sequence a && b, myshell should wait for command a to terminate, test its return value and execute b if and only if a’s return value indicates success. The exit value of an “&&” command sequence is the exit status of the last command executed.
If the token “
||“ is used to separate commands then myshell should continue to the next command only if the first command sequence returns an exit value indicating failure. This is the converse of part 2. For the command sequence
a || b, myshell should wait for command a to terminate, test its return value and execute b if and only if a’s return value indicates failure. The exit value of a “
||“ command sequence is /the exit status of the last command executed.
The sequence ( commands ) should cause commands to be executed in a subshell. A subshell is created by forking a copy of myshell to execute the commands. The exit value for a subshell is the exit value of the command sequence inside the parentheses.
Commands may redirect their standard input and standard output from and to files, respectively, before the command is executed.
- The sequence
command < infilerequests that the command use infile as its standard input.
- The sequence
command > outfilerequests that the command use outfile as its standard output. If the file outfile does not exist then it is created. If it does exist it is truncated to zero then rewritten.
- The sequence
command >> outfilerequests that the command appends its standard output to the file outfile. If outfile does not exist it is created.
NOTE: in all of the above cases command could be a subshell. It is valid to have both input and output redirection for the same command. Thus the sequence
( sort ; ps ) < junk1 >> junk2 would take input from the file junk1 and append output to the file junk2.
Helpful C99 and POSIX functions: open(), close(), dup2().
command1 | command2 requests that the stdout of command1 be presented as stdin to command2. By default, the stderr output of command1 is not redirected and appears at its default location (typically the terminal). With reference to this example, the myshell parser will not permit the stdout of command1 to be redirected to a file (with
>), nor the stdin of command2 to be received from a file (with
<). Note that the sequence
command1 | command2 | command3 requests that a pipeline of two different pipes be established.
Helpful C99 and POSIX functions: pipe(), dup2().
Once an executable file name has been found (possibly using the search path) the standard function execv() can be called to try to execute it. If execv() fails, you should assume that the file is a shell script (a text file) containing more myshell commands. In this case you should execute another copy of myshell to read its input from the shell script. No specific filename extension is required.
Helpful C99 and POSIX functions: access(), fopen(), fclose().
The token “&” causes the preceding command to be executed without myshell waiting for it to finish (asynchronously). Thus the sequence
ls ; ps & date should start the command sequence ls, once this has completed start ps and immediately proceed to the command date. The exit value of background execution is success unless the fork call fails, in which case the exit value should indicate failure.
Commands placed into the background may take a long time to execute and, thus, we wish to know when they have completed. The parent is informed of the termination of child processes using asynchronous signal-passing. When so informed, myshell should report which background process has terminated.
Similarly, when myshell exits, it should first terminate all of its still-running background processes, and wait for them to finish.
The amount of code to be written for this project is similar to that of the 1st project, although less needs to be designed “from scratch” because you’re extending an (incomplete) code skeleton.
Start your project by downloading, reading, and understanding the files in the archive myshell.zip.
- myshell.h - provides the definition of myshell’s user-defined datatypes and the declaration of global variables.
- myshell.c - provides the main() function, and calls the parse_shellcmd() function.
- globals.c - defines global variables, and the helpful print_shellcmd0() function.
- execute.c - where you define your execute_shellcmd() function.
- parser.c - defines the parse_shellcmd() and free_shellcmd() functions, which should be used without modification (and need not be understood).
You may modify any file or add any additional files to your project.
- Your project, and its executable program, must be named myshell.
- Your project must be developed using multiple C99 source files and must employ a Makefile, employing variable definitions and automatic variables, to compile and link the project’s files.
- If any error is detected during its execution, your project must use fprintf(stderr, ….) or perror() (as appropriate) to print an error message.
- Your project must employ sound programming practices, including the use of meaningful comments, well chosen identifier names, appropriate choice of basic data-structures and data-types, and appropriate choice of control-flow constructs.
This project is worth 15% of your final mark for CITS2002. It will be marked out of 40. The project may be completed individually or in teams of two. You are strongly encouraged to work with someone else - this will enable you to discuss your initial design, and to assist each other to develop and debug your joint solution.
During the marking, attention will obviously be given to the correctness of your solution. However, a correct and efficient solution should not be considered as the perfect, nor necessarily desirable, form of solution. Preference will be given to well presented, well documented solutions that use the appropriate features of the language to complete tasks in an easy to understand and easy to follow manner. That is, do not expect to receive full marks for your project simply because it works correctly. Remember, a computer program should not only convey a message to the computer, but also to other human programmers.
Up to half of the possible marks will come from the correctness of your solution. The remaining marks will come from your programming style, including your use of meaningful comments, well chosen identifier names, appropriate choice of basic data-structures and data-types, and appropriate choice of control-flow constructs.
Your project will be marked on the computers in CSSE Lab 2.03, using the macOS environment. No allowance will be made for a program that “works at home” but not on CSSE Lab 2.03 computers, so be sure that your code compiles and executes correctly on these machines before you submit it.