<div align="center">

mumsh: A Mini Shell Written in C

</div>

Documentation

This project is originated from a course project in VE482 Operating System @UM-SJTU Joint Institute. In general, a mini shell called mumsh is implemented with programming language C for Unix-like machine.

Change Log

For VE482 course project version, see Releases: VE482 Project 1 or Branches: VE482.

• [2022/2/19] Add feature: Command history auto-completion with smart search

• [2022/2/15] Add feature: Tab-triggered hint and auto-completion

• [2022/2/13] Add feature: Left & right cursor switch and dynamic insert & delete

• [2022/2/12] Add feature: Dynamic current path prompt in prefix

• Future upgrade list:

  1. Handle print overflow regarding terminal size
  2. CTRL-D keyboard capture and interruption
  3. Show Git status in prefix
  4. Auto translate ~ to home path in parser

Functionalities

mumsh supports some basic shell functionalities including:

• Tab-triggered hint and auto-completion
• Command history auto-completion with smart search
• Incomplete input waiting
• Syntax error handling
• Quotation mark parsing
• Internal commands exit/pwd/cd/jobs
• I/O redirection under bash style syntax
• Arbitrarily-deep pipes running in parallel
• CTRL-C interruption
• Background jobs

In this README, the following content will be included:

0. What files are related to mumsh
1. How to build and run mumsh
2. How to play with mumsh
3. How to implement mumsh

0. Files related to mumsh

We have 4 kinds of files in this project:

• README
  • It's strongly adviced to read README.md before running mumsh or reading source code, since it may give us more sense of what mumsh is doing in each stage.
• C Source files: (in executing order)
  • mumsh.c: where main read/parse/execute loop of mumsh locates
  • io.c: handle reading command line input of mumsh
  • hinter.c: input interface with tab-triggered hint and auto-completion
  • parser.c: parse user input into formatted commands for coming execution
  • process.c: execute commands in child process according to specifications
• C header files: (hierarchy from top to bottom)
  • mumsh.h
  • io.h
  • hinter.h
  • parser.h
  • process.h: store global variables regarding process
  • data.h: store extern global variables regarding read/parse/execute loop
• makefile
  • used for quick build and clean of executable files

1. Build and Run mumsh

mumsh is only available on Unix-like machine, as some libraries are not avaiable in Windows.

• build: $ make
• run: $ ./mumsh

If everything is normal, we can see in the terminal mumsh $ , which indicates that mumsh is up and running, waiting for our input.

2. Play with mumsh

Once mumsh is up and running, we can start inputting some commands such as ls or pwd to test the basic functionalities if you have already been familiar to shell.

Of course, mumsh is only a product of a course project supporting basic functions, and yet to be improved. For its detailed ability, please check the following sections.

---

2.1 Overall mumsh Grammar in Backus-­Naur Form

cmd [argv]* [| cmd [argv]* ]* [[> filename][< filename][>> filename]]* [&]

Seems abstract and maybe get a little bit confused? Let me explain a little more.

The input of mumsh can be made up of 4 components:

• command and argument: cmd, argv
• redirector and filename: <, >, >>, filename
• pipe indicator: |
• background job indicator: &

2.1.1 Command and Argument

• cmd is a must, or mumsh will raise error: missing program
• argv is optional, we can choose to call a command with arguments or not.

2.1.2 Redirector and Filename

• <, >, >> is optional, but we should input redirector along with filename
  • if any <, >, |, & instead of filename follows, mumsh will raise error: syntax error near unexpected token ...
  • if no character follows, mumsh will prompt us to keep input in newline
• > and >> can't exist in the same command, or mumsh will raise error: duplicated output redirection

2.1.3 Pipe Indicator

• | is optional, but we should input | after one command and followed by another command
  • if no command before |, mumsh will raise error: missing program
  • if no character after |, mumsh will prompt us to keep input in newline
• | is incompatible with having > or >> before it, and having < after it
  • if > or >> comes before |, mumsh will raise error: duplicated output redirection
  • if < comes after |, mumsh will raise error: duplicated input redirection

2.1.4 Background Job Indicator

• & is optional, but we should only input & at the end of input, or mumsh will ignore the character(s) after & is detected.

Now, we have our components of input to play with, and we can try it out in mumsh by assembling them into a whole input. As long as mumsh doesn't raise an error, our input syntax is valid, even though this input may give no output.

---

2.2 Simple Commands

• mumsh built-in commands
  • exit: exit mumsh
  • pwd: print working directory
  • cd: change working directory
  • jobs: print background jobs status
• executable commands (call other programs to do certain jobs)
  • ls: call program /bin/ls, which print files in current working directory
  • bash: call shell /bin/bash, which is also a shell like mumsh but with more powerful capabilities
  • we can input ls /bin to see more executable commands

---

2.3 I/0 Redirection (support bash style syntax)

• Input redirection

  • < filename: read from file named filename, or raise error if no filename exists

• Output redirection

  • > filename: overwrite if file named filename exists or create new file named filename
  • >> filename: append if file named filename exists or create new file named filename

• support bash style syntax

  • An arbitrary amount of space can exist between redirection symbols and arguments, starting from zero.
  • The redirection symbol can take place anywhere in the command.
  • for example: <1.txt>3.txt cat 2.txt 4.txt

---

2.4 Pipe

• takes output of one command as input of another command
  • basic pipe syntax: echo 123 | grep 1
• mumsh support parallel execution: all piped commands run in parallel
  • for example: sleep 1 | sleep 1 | sleep 1 only takes 1 second to finish instead of 3 seconds
• mumsh support arbitrarily deep “cascade pipes”
  • for example: echo hello world | grep h | grep h | ... | grep h

---

2.5 CTRL-C

• interrupt all executing commands in foreground with CTRL-C

• cases:

  • clear user input and prompt new line

    mumsh $ echo ^C
    mumsh $
    

  • interrupt single executing command

    mumsh $ sleep 10
    ^C
    mumsh $
    

  • interrupt multiple executing commands

    mumsh $ sleep 10 | sleep 10 | sleep 10
    ^C
    mumsh $
    

  • CTRL-C don't interrupt background jobs

    mumsh $ sleep 10 &
    [1] sleep 10 &
    mumsh $ ^C
    mumsh $ jobs
    [1] running sleep 10 &
    mumsh $
    

---

2.6 CTRL-D

• if mumsh has no user input, CTRL-D will exit mumsh

  mumsh $ exit
  $
  

• if mumsh has user input, do nothing

  mumsh $ echo ^D
  

---

2.7 Quotes

• mumsh takes any character between " or ' as ordinary character without special meaning.

  mumsh $ echo hello "| grep 'h' > 1.txt"
  hello | grep 'h' > 1.txt
  mumsh $
  

---

2.8 Background Jobs

• If & is added at the end of user input, mumsh will run jobs in background instead of waiting for execution to be done.

• Command jobs can keep track on every background jobs, no matter a job is done or running

• mumsh support pipe in background jobs

  mumsh $ sleep 10 &
  [1] sleep 10 &
  mumsh $ sleep 1 | sleep 1 | sleep 1 &
  [2] sleep 1 | sleep 1 | sleep 1 &
  mumsh $ jobs
  [1] running sleep 10 &
  [2] done sleep 1 | sleep 1 | sleep 1 &
  mumsh $
  

• mumsh support command formatting

  mumsh $ <'i'n   c"a"t|   cat   |ech'o'  "he"llo>out  world!&
  [1] cat < in | cat | echo hello world! > out &
  mumsh $ jobs
  [1] done cat < in | cat | echo hello world! > out &
  mumsh $
  

3. Implement mumsh Step by Step

In this section, we will go through the construction of mumsh step by step, giving us a general concept of how this shell work. This section is intended for helping beginners (just as me a week ago) grab some basic concept for implementing a shell.

However, some contents such as detailed data structure and marginal logic will be neglected. And the demo code is used for our better understanding instead of doing copy and paste. As a result, the grammar is not strictly follow the C standard. For more detail, we can read the source code directly. It's strongly recommended to understand the concept before doing any coding.

---

3.1 Main Read/Parse/Execute Loop

As we all know, a shell is a computer program which exposes an operating system's services to a human user or other program. It repeatedly takes commands from the keyboard, gives them to the operating system to perform and