Mini Shell

A comprehensive Unix-like shell implementation in C++ featuring command parsing, I/O redirection, pipes, background processes, and wildcard expansion.

---

📋 Table of Contents

• Overview
• Project Structure
• Architecture & Workflow
• Features
• Building & Running
• Usage Examples
• Testing
• Implementation Details
• Error Handling

---

🎯 Overview

This mini shell is a command-line interpreter that provides core shell functionality similar to bash or sh. It parses user commands, handles I/O redirection and piping, manages processes, and supports advanced features like wildcard expansion.

Key Capabilities

• Execute system commands with arguments
• Input/Output/Error redirection
• Command piping (chaining multiple commands)
• Background process execution
• Built-in commands (cd, exit)
• Signal handling (Ctrl-C protection)
• Process logging
• Wildcard expansion (*, ?)

---

📁 Project Structure

mini-shell/
├── command.h          # Command data structures
├── command.cc         # Core implementation (parsing & execution)
├── tokenizer.h        # Token type definitions
├── tokenizer.cc       # Lexical analysis (tokenization)
├── Makefile          # Build configuration
├── log.txt           # Process termination log (created at runtime)
└── testcases/        # Test scripts
    ├── basic_ls_al.sh
    ├── echo_hello_os_lab.sh
    ├── redirect_create_output1.sh
    └── ... (10 test scripts total)

File Hierarchy & Responsibilities

┌─────────────────────────────────────────────┐
│           main() - Entry Point              │
│  - Signal handlers setup (SIGINT, SIGCHLD)  │
│  - Log file initialization                  │
│  - Main input loop                          │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         tokenizer.cc / tokenizer.h          │
│  - Lexical analysis of input string         │
│  - Converts input → vector<Token>           │
│  - Recognizes operators: | > >> < 2> >>& &  │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│          parse() - Syntax Analysis          │
│  - Builds Command & SimpleCommand structs   │
│  - Handles redirection operators            │
│  - Handles pipe operators                   │
│  - Expands wildcards                        │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│     Command::execute() - Execution Engine   │
│  - Built-in commands (cd, exit)             │
│  - Process creation (fork/exec)             │
│  - File descriptor management               │
│  - Pipe construction                        │
│  - Process waiting & logging                │
└─────────────────────────────────────────────┘

---

🏗️ Architecture & Workflow

1. Data Structures (command.h)

SimpleCommand

Represents a single command with its arguments.

struct SimpleCommand {
    int _numberOfArguments;
    char **_arguments;  // NULL-terminated array
    // Methods: insertArgument()
}

Example: ls -al → _arguments = ["ls", "-al", NULL]

Command

Represents a complete shell command (may contain multiple SimpleCommands connected by pipes).

struct Command {
    SimpleCommand **_simpleCommands;  // Array of simple commands
    int _numberOfSimpleCommands;
    char *_outFile;      // Output redirection file
    char *_inputFile;    // Input redirection file
    char *_errFile;      // Error redirection file
    int _background;     // Background flag
    int _append;         // Append mode flag
    int _out_error;      // Redirect stderr to stdout flag
    // Methods: execute(), print(), clear(), prompt()
}

Example: ls -al | grep txt > out.txt creates:

• 2 SimpleCommands: ["ls", "-al"] and ["grep", "txt"]
• _outFile = "out.txt"

---

2. Tokenization (tokenizer.cc)

Token Types (tokenizer.h)

enum TokenType {
    TOKEN_COMMAND,              // First word in command
    TOKEN_ARGUMENT,             // Arguments and filenames
    TOKEN_REDIRECT,             // >
    TOKEN_APPEND,               // >>
    TOKEN_INPUT,                // <
    TOKEN_ERROR,                // 2>
    TOKEN_PIPE,                 // |
    TOKEN_BACKGROUND,           // &
    TOKEN_REDIRECT_AND_ERROR,   // >>&
    TOKEN_EOF                   // End of input
}

Tokenization Process

Input: "ls -al | grep txt > output.txt"
         ↓
Tokenizer splits by whitespace and identifies operators
         ↓
Tokens: [
  {TOKEN_COMMAND, "ls"},
  {TOKEN_ARGUMENT, "-al"},
  {TOKEN_PIPE, "|"},
  {TOKEN_COMMAND, "grep"},
  {TOKEN_ARGUMENT, "txt"},
  {TOKEN_REDIRECT, ">"},
  {TOKEN_ARGUMENT, "output.txt"},
  {TOKEN_EOF, ""}
]

---

3. Parsing (command.cc::parse())

Parsing Algorithm

1. Initialize: Create empty Command and SimpleCommand
2. Iterate tokens:
   • Commands/Arguments: Add to current SimpleCommand (with wildcard expansion)
   • Pipe |: Finalize current SimpleCommand, start new one
   • Redirection >, >>, <, 2>, >>&: Mark next token as filename
   • Background &: Set background flag
3. Finalize: Add last SimpleCommand to Command
4. Execute: Call Command::execute()

Example Parsing Flow

Input: "cat < input.txt | grep error > output.txt"

Parse Steps:
1. "cat"          → Create SimpleCommand, add "cat"
2. "<"            → Set expectingFilename = true, redirectType = INPUT
3. "input.txt"    → Set _inputFile = "input.txt"
4. "|"            → Insert SimpleCommand #1, create new SimpleCommand
5. "grep"         → Add "grep" to SimpleCommand #2
6. "error"        → Add "error" to SimpleCommand #2
7. ">"            → Set expectingFilename = true, redirectType = REDIRECT
8. "output.txt"   → Set _outFile = "output.txt"
9. EOF            → Insert SimpleCommand #2, call execute()

Result Command:
- SimpleCommand[0]: ["cat"]
- SimpleCommand[1]: ["grep", "error"]
- _inputFile: "input.txt"
- _outFile: "output.txt"

---

4. Execution (command.cc::Command::execute())

Execution Workflow

┌─────────────────────────────────────┐
│ 1. Check for Built-in Commands     │
│    - exit → Quit shell              │
│    - cd   → Change directory        │
└────────────┬────────────────────────┘
             │ (External command)
             ▼
┌─────────────────────────────────────┐
│ 2. Save Default File Descriptors   │
│    defaultin  = dup(0)              │
│    defaultout = dup(1)              │
│    defaulterr = dup(2)              │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│ 3. Setup Input Redirection          │
│    if (_inputFile)                  │
│      fdin = open(_inputFile, RD)    │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│ 4. FOR EACH SimpleCommand:          │
│                                     │
│  A. Redirect stdin                  │
│     dup2(fdin, 0)                   │
│                                     │
│  B. Setup Output:                   │
│     - If LAST command:              │
│       * _outFile → open file        │
│       * _errFile → open error file  │
│     - Else (not last):              │
│       * Create pipe()               │
│       * fdout = pipe[1]             │
│       * fdin  = pipe[0] (for next)  │
│                                     │
│  C. Redirect stdout & stderr        │
│     dup2(fdout, 1)                  │
│     dup2(fderr, 2)                  │
│                                     │
│  D. Fork & Execute                  │
│     pid = fork()                    │
│     if (pid == 0)                   │
│       execvp(command, args)         │
│                                     │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│ 5. Restore Default File Descriptors│
│    dup2(defaultin, 0)               │
│    dup2(defaultout, 1)              │
│    dup2(defaulterr, 2)              │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│ 6. Wait for Process (if foreground) │
│    waitpid(last_pid, &status, 0)    │
│    Log termination to log.txt       │
└─────────────────────────────────────┘

Process Management

• Foreground: Shell waits using waitpid() and logs termination
• Background: Shell doesn't wait; SIGCHLD handler logs when process finishes

---

✨ Features

Core Features

1. Command Execution

myshell> ls -al
myshell> pwd
myshell> echo "Hello World"

2. I/O Redirection

# Output redirection (overwrite)
myshell> ls -al > output.txt

# Output redirection (append)
myshell> echo "new line" >> output.txt

# Input redirection
myshell> cat < input.txt

# Error redirection
myshell> ls nonexistent 2> error.txt

# Redirect both stdout and stderr
myshell> command >>& output.txt

3. Pipes

# Single pipe
myshell> ls -al | grep txt

# Multiple pipes
myshell> cat file.txt | grep error | wc -l

# Pipes with redirection
myshell> ls -al | grep txt > results.txt

4. Background Processes

myshell> sleep 10 &
myshell> long_running_command &

The shell returns immediately; process runs in background.

5. Built-in Commands

cd - Change Directory

myshell> cd /tmp              # Change to /tmp
myshell> cd ..                # Go up one directory
myshell> cd                   # Go to HOME directory
myshell> cd ~                 # Go to HOME directory

Output:

Changing to directory '/tmp'
You are now in /tmp

exit - Quit Shell

myshell> exit
Good bye!!

6. Signal Handling

• Ctrl-C (SIGINT): Shell ignores it; prints newline and new prompt
• SIGCHLD: Automatically logs child process terminations

7. Process Logging

Every terminated child process is logged to log.txt:

[Sun Oct 26 14:23:45 2025] Child process 12345 terminated with status 0
[Sun Oct 26 14:23:46 2025] Child process 12346 terminated with status 0

Bonus Feature: Wildcard Expansion

* - Matches Zero or More Characters

myshell> echo *               # All files in current directory
myshell> echo *.cc            # All .cc files
myshell> echo test*.txt       # Files starting with "test", ending with ".txt"
myshell> ls /tmp/*            # All files in /tmp

? - Matches Exactly One Character

myshell> echo file?.txt       # file1.txt, file2.txt, fileA.txt
myshell> ls test??.cc         # test01.cc, test23.cc

Combined Wildcards

myshell> echo M*f*            # Files starting with M, containing f
myshell> ls /*bin*/ls         # /bin/ls, /usr/bin/ls, etc.

Implementation: Uses glob() from <glob.h>, results are sorted alphabetically.

---

🔧 Building & Running

Prerequisites

• Compiler: g++ with C++11 support
• OS: Linux/Unix-based system
• Libraries: Standard C++ library, POSIX APIs

Build Commands

Compile the Shell

make

Output: Creates myshell executable

Clean Build Artifacts

make clean

Removes: *.o, myshell, log.txt

Rebuild from Scratch

make rebuild

Equivalent to: make clean && make

Compile and Run

make run

Equivalent to: make && ./myshell

Running the Shell

Start the Shell

./myshell

Output:

myshell>

Interactive Usage

myshell> ls -al
myshell> cat file.txt | grep pattern > results.txt
myshell> exit
Good bye!!

Scripted Input

echo -e "ls\npwd\nexit" | ./myshell

---

📝 Usage Examples

Example 1: Basic Command with Output Redirection

myshell> ls -al > files.txt

What happens:

1. Tokenize: ["ls", "-al", ">", "files.txt"]
2. Parse: Create SimpleCommand ["ls", "-al"], set _outFile = "files.txt"
3. Execute: Fork → Open files.txt for writing → Redirect stdout → execvp("ls", ["ls", "-al"])

Example 2: Pipeline with Multiple Commands

myshell> cat data.txt | grep ERROR | wc -l

What happens:

1. Parse: 3 SimpleCommands: ["cat", "data.txt"], ["grep", "ERROR"], ["wc", "-l"]
2. Execute:
   • Fork → cat data.txt → stdout → pipe1
   • Fork → pipe1 → stdin, grep ERROR, stdout → pipe2
   • Fork → pipe2 → stdin, wc -l, stdout → terminal

Example 3: Background Process

myshell> sleep 5 &

What happens:

1. Parse: Set _background = 1
2. Execute: Fork → execvp("sleep", ["sleep", "5"]) → Don't wait, return to prompt immediately
3. SIGCHLD handler logs when sleep finishes

Example 4: Wildcard Expansion

myshell> echo *.cc

What happens:

1. Tokenize: ["echo", "*.cc"]
2. Parse: Call expandWildcard("*.cc") → Returns ["command.cc", "tokenizer.cc"]
3. SimpleCommand: ["echo", "command.cc", "tokenizer.cc"]
4. Execute: Prints command.cc tokenizer.cc

---

🧪 Testing

Test Suite

Located in testcases/ directory with 10 automated tests:

Test Script	Description	Points
basic_ls_al.sh	Tests basic command execution	2
echo_hello_os_lab.sh	Tests echo with quoted strings	2
redirect_create_output1.sh	Tests output redirection creates file	2
cat_input_output1.sh	Tests input redirection	2
append_and_grep_line.sh	Tests append mode and piping	2
count_ls_wc.sh	Tests pipe with ls and wc	2
background_sleep2.sh	Tests background execution	2
cd_up_message.sh	Tests cd command with messages	2
stderr_redirection.sh	Tests stderr redirection (2>)	2
pwd_test.sh	Tests pwd command	2
log_file_linecount.sh	Tests log.txt has correct line count	2

Running Tests

Run All Tests

bash run_all_and_sum.sh

Output:

basic_ls_al.sh -> 2
echo_hello_os_lab.sh -> 2
redirect_create_output1.sh -> 2
...
TOTAL=22

Run Individual Test

cd testcases
bash basic_ls_al.sh

Test Dependencies

Some tests depend on previous tests:

1. redirect_create_output1.sh creates output1.txt
2. cat_input_output1.sh reads from output1.txt
3. append_and_grep_line.sh appends to output1.txt

Run tests in order specified in run_all_and_sum.sh.

---

🔍 Implementation Details

Memory Management

• Dynamic Allocation: Uses malloc()/realloc() for arrays
• Cleanup: Command::clear() frees all allocated memory
• String Duplication: Uses strdup() for storing strings

File Descriptor Management

// Save defaults
int defaultin = dup(0);
int defaultout = dup(1);
int defaulterr = dup(2);

// ... perform redirections ...

// Restore
dup2(defaultin, 0);
dup2(defaultout, 1);
dup2(defaulterr, 2);
close(defaultin);
close(defaultout);
close(defaulterr);

Why? Prevents side effects between commands.

Pipe Implementation

int fdpipe[2];
pipe(fdpipe);           // Create pipe
// Child 1: dup2(fdpipe[1], 1);  // Write end → stdout
// Child 2: dup2(fdpipe[0], 0);  // Read end → stdin

Signal Handlers

// SIGINT: Prevent Ctrl-C from killing shell
sa_int.sa_handler = sigint_handler;
sa_int.sa_flags = SA_RESTART;
sigaction(SIGINT, &sa_int, nullptr);

// SIGCHLD: Log terminated background processes
sa_chld.sa_handler = sigchld_handler;
sa_chld.sa_flags = SA_RESTART | SA_NOCLDSTOP;
sigaction(SIGCHLD, &sa_chld, nullptr);

---

⚠️ Error Handling

Error Cases Handled

1. Command Not Found: execvp() fails → Print "execvp: No such file or directory"
2. File Not Found: Input file doesn't exist → Print "open input file: No such file or directory"
3. Permission Denied: Can't open file → Print "open output file: Permission denied"
4. Invalid Pipe: Pipe before command → Print "Error: Invalid pipe usage"
5. Fork Failure: Can't create process → Print "fork: Resource temporarily unavailable"
6. Missing Redirection Filename: ls > with no filename → Print "Error: Expected filename after redirection operator"

Example Error Output

myshell> cat nonexistent.txt
cat: nonexistent.txt: No such file or directory

myshell> ls > /root/file.txt
open output file: Permission denied

myshell> | grep test
Error: Invalid pipe usage

---

📚 Additional Notes

Debugging

Uncomment print() in Command::execute() to see the parsed command table:

void Command::execute() {
    print();  // Uncomment this line
    // ...
}

Output:

              COMMAND TABLE
  #   Simple Commands
  --- ----------------------------------------------------------
  0   "ls"    "-al"

  Output       Input        Error        Err&Out       Background
  ------------ ------------ ------------ ------------ ------------
  output.txt   default      default      NO           NO

Limitations

1. No command history: Up/down arrows don't work
2. No tab completion: Can't auto-complete filenames
3. No job control: Can't use fg, bg, jobs commands
4. No aliases: Can't create command shortcuts
5. No environment variable expansion: $HOME not supported (except in cd)

Future Enhancements

• Add command history with readline library
• Implement job control (fg, bg, jobs)
• Support environment variables ($VAR)
• Add command aliases
• Implement command substitution ($(command))

---

👨‍💻 Author & Credits

Course: CC373 - Operating Systems
Institution: Alexandria University, Faculty of Engineering
Program: Computer & Communication Engineering
Lab: Lab 3 - Mini Shell

Implementation Features:

• ✅ Command parsing and execution
• ✅ I/O redirection (>, >>, <, 2>, >>&)
• ✅ Pipes (single and multiple)
• ✅ Background processes (&)
• ✅ Built-in commands (cd, exit)
• ✅ Signal handling (SIGINT, SIGCHLD)
• ✅ Process logging
• ✅ Bonus: Wildcard expansion (*, ?)

---

📄 License

This project is for educational purposes as part of the Operating Systems course curriculum.

---

Happy Shelling! 🐚# Mini-Shell

Mini-Shell

Mini-Shell