Project 1: PTY Explorer Tool

A command-line tool that creates PTY pairs, shows their file descriptors, demonstrates master/slave communication, and visualizes what the TTY driver does.

Quick Reference

Attribute	Value
Primary Language	C
Alternative Languages	Rust, Go, Python
Difficulty	Level 2: Intermediate (The Developer)
Time Estimate	1 week
Knowledge Area	PTY / Unix System Programming
Tooling	PTY Debug Tool
Prerequisites	Basic C, understanding of fork/exec

---

What You Will Build

A command-line tool that creates PTY pairs, shows their file descriptors, demonstrates master/slave communication, and visualizes what the TTY driver does.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

• PTY creation → posix_openpt, grantpt, unlockpt, ptsname
• Session management → setsid, controlling terminal concepts
• File descriptor juggling → dup2, understanding stdin/stdout/stderr
• Process forking → Parent/child communication patterns
• Observing TTY driver → Seeing echo, line editing in action

Key Concepts

• PTY Fundamentals: “The Linux Programming Interface” Chapter 64 - Michael Kerrisk
• Sessions and Process Groups: “The Linux Programming Interface” Chapter 34 - Michael Kerrisk
• TTY Subsystem: Linux Terminals, TTY, PTY and Shell - DEV Community
• PTY Architecture: The Elegant Architecture of PTYs - Medium

Real-World Outcome

$ ./pty_explorer

=== PTY Explorer v1.0 ===

[1] Creating PTY pair...
    Master FD: 3
    Slave path: /dev/pts/5

[2] Current terminal: /dev/pts/2
    Session ID: 12345
    Process Group: 12345
    Foreground PG: 12345

[3] Forking shell on PTY slave...
    Child PID: 12350
    Child session: 12350 (new session!)
    Child controlling TTY: /dev/pts/5

[4] Demonstrating TTY driver (canonical mode):
    Type something and press Enter...
    > hello world<BACKSPACE><BACKSPACE>rld

    Characters received by shell: "hello world" (backspaces processed!)
    Raw bytes through master: "hello wo\x7f\x7frld\r" (backspaces visible!)

[5] Switching to raw mode...
    Type something (each keypress sent immediately)...
    'h' -> immediately sent
    'e' -> immediately sent
    'l' -> immediately sent
    Ctrl+C -> SIGINT sent to child!

[6] PTY window size: 80x24
    Setting to 120x40...
    SIGWINCH sent to child!

---

Implementation Guide

1. Reproduce the simplest happy-path scenario.
2. Build the smallest working version of the core feature.
3. Add input validation and error handling.
4. Add instrumentation/logging to confirm behavior.
5. Refactor into clean modules with tests.

Milestones

• Milestone 1: Minimal working program that runs end-to-end.
• Milestone 2: Correct outputs for typical inputs.
• Milestone 3: Robust handling of edge cases.
• Milestone 4: Clean structure and documented usage.

Validation Checklist

• Output matches the real-world outcome example
• Handles invalid inputs safely
• Provides clear errors and exit codes
• Repeatable results across runs

References

• Main guide: TERMINAL_EMULATOR_DEEP_DIVE_PROJECTS.md
• “The Linux Programming Interface” by Michael Kerrisk