Project 2: Custom ls Command with Win32

A command-line tool that mimics the basic functionality of the ls or dir command, listing files and directories in a given path using the core Win32 API.

Quick Reference

Attribute Value
Primary Language C
Alternative Languages C++
Difficulty Level 1: Beginner
Time Estimate Weekend
Knowledge Area Win32 API / File System
Tooling Win32 API
Prerequisites Project 1, solid understanding of C pointers and structs.

What You Will Build

A command-line tool that mimics the basic functionality of the ls or dir command, listing files and directories in a given path using the core Win32 API.

Why It Matters

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

Core Challenges

  • Using FindFirstFileW and FindNextFileW → maps to the standard pattern for directory iteration
  • Handling HANDLE objects → maps to understanding and correctly closing kernel object references with FindClose
  • Working with WIN32_FIND_DATAW → maps to accessing file attributes, sizes, and names
  • Unicode vs. ANSI → maps to why wchar_t and W functions are standard on Windows
  • Error checking with GetLastError() → maps to the fundamental Win32 error reporting mechanism

Key Concepts

  • File I/O: “Windows System Programming, 4th Edition” by Johnson M. Hart - Chapter 6
  • Unicode Support in the Win32 API: Microsoft Docs - “Working with Strings”
  • Error Handling: Microsoft Docs - GetLastError function

Real-World Outcome

> ./my_ls.exe C:\Windows
[D]      Boot
[D]      System32
[F]      win.ini        (1 KB)
[F]      explorer.exe   (4,321 KB)
...

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: LEARN_WINDOWS_SYSTEMS_PROGRAMMING_CPP.md
  • “Programming Windows, 5th Edition” by Charles Petzold