Unix ls Command in Pure C

"Everything is a file, but not everything is presented equally."

A precision-engineered, from-scratch implementation of the Unix ls command in pure C. Built with a focus on systems programming excellence, modular architecture, and deep filesystem introspection.

---

The Philosophy

Modern command-line tools often hide the complex dance between the kernel and the user space. ls-c strips away the abstraction. It is designed not just to list files, but to serve as a reference implementation for how Unix metadata is extracted, buffered, and projected onto the terminal.

Key Engineering Pillars

• Strict Lint Compliance: Zero-warning policy with cppcheck and clang-format.
• Memory Integrity: Verified leak-free performance via valgrind and AddressSanitizer.
• Thread-Safety Aware: Utilizes modern primitives like scandir and localtime_r to ensure robustness in concurrent environments.
• Coverage Driven: Comprehensive unit and integration test suites with CI-integrated coverage reporting.

---

Architectural Blueprint

The codebase is strictly modular, separating the concerns of the filesystem, the data model, and the view layer.

graph TD
    Main[main.c: Orchestrator] --> Args[Argument Parsing]
    Main --> DirOps[dir_ops.c: Traversal Engine]
    DirOps --> Scandir[scandir: Recursive Discovery]
    Scandir --> FileInfo[file_info.c: Metadata Extraction]
    FileInfo --> Stat[lstat: Kernel Introspection]
    Main --> Sorting[sorting.c: Ordering Logic]
    Main --> Formatting[formatting.c: Presentation Layer]
    Formatting --> Colors[ANSI Color Projection]
    Formatting --> Columns[Dynamic Grid Calculation]

Loading

---

Capabilities

Feature	Implementation	Engineering Note
Long Format	-l	Detailed permission, ownership, and link resolution.
Recursion	-R	Depth-first traversal with path preservation.
Intelligent Sorting	-t, -r, -S	Pluggable comparators for time, size, and name.
Human Readable	-h	Context-aware scale selection (B, K, M, G, T).
Color Projection	Autodetect	tty-aware ANSI styling for directories, links, and executables.

---

Technical Deep-Dives

The project includes an extensive educational curriculum documentation in docs/:

1. Filesystem Fundamentals: The relationship between dentries, inodes, and user-space tools.
2. Metadata & Stat: Decoding the stat structure and Unix permissions.
3. Traversal Logic: Moving from readdir to scandir for safer discovery.
4. Formatting Theory: Grid math and terminal width orchestration.
5. Comparator Design: Implementing efficient qsort-compatible comparison functions.

---

Core Tooling

Verified components of the development lifecycle:

• Linter: cppcheck (all checks enabled, Werror)
• Formatter: clang-format (LLVM style)
• Memory Check: valgrind & ASan
• Coverage: gcov & lcov

---

Part of the implement-from-scratch series.