lsbtw

A small C learning project built around implementing parts of ls, specifically -a and -l, to understand how Unix directory listing and file metadata actually work under the hood.

This repo is intentionally narrow in scope. The focus is not on recreating all of ls, but on learning the mechanics behind:

• traversing directories with opendir and readdir
• understanding how directory entries relate to lower-level concepts like getdents
• reading file metadata with lstat
• decoding st_mode using bit operations
• turning raw mode bits into human-readable Unix permission strings
• resolving UID/GID into owner and group names
• formatting timestamps and sizes for a long listing view

Why this exists

This project is a learning attempt in C.

The goal was to move beyond using shell tools as black boxes and instead understand what happens when a program like ls:

• reads a directory
• decides whether to hide dotfiles
• fetches metadata for each entry
• parses permission bits
• prints a long-format listing

It is best read as a systems programming exercise rather than a finished utility.

What is implemented

The repository centers on one source file:

• ls.c — a minimal ls-style implementation

Currently supported flags:

• -a to include hidden entries
• -l to print a long-format view

Current long-format output includes:

• file type indicator
• rwx permissions
• owner
• group
• size
• last modified time
• filename

Repository layout

.
├── ls.c
└── README.md

Concepts explored in the code

Directory traversal

The program opens a directory with opendir and iterates entries using readdir. This is the user-space interface typically used for directory listing, and it helps build intuition for lower-level directory entry retrieval such as getdents.

Metadata lookup

For long-format output, the program calls lstat on each directory entry to retrieve file metadata from the kernel, including mode bits, ownership, file size, and modification time.

Permission parsing

One of the main learning goals here is understanding how Unix permissions are encoded in st_mode.

The code manually checks:

• file type bits
• user read/write/execute bits
• group read/write/execute bits
• other read/write/execute bits

and converts them into a string such as:

-rwxr-xr-x

This is the core bitmasking exercise in the project.

Ownership resolution

The program maps:

• st_uid to a username using getpwuid
• st_gid to a group name using getgrgid

This is part of understanding how raw metadata becomes human-readable command output.

Build

Compile with:

make

Direct compilation is also fine:

cc -D_DEFAULT_SOURCE -Wall -Wextra -Wpedantic -std=c11 ls.c -o ls

Usage

make run
./ls
./ls -a
./ls -l
./ls -la
./ls -la /some/path

What this project demonstrates

• learning C through direct use of POSIX filesystem APIs
• understanding the relationship between directory entries and file metadata
• working with structs like dirent and stat
• using bitwise checks to decode permissions
• translating low-level system data into a CLI interface

Current limitations

This is still a learning implementation, so some things are intentionally incomplete:

• only -a and -l are implemented
• output formatting is simple and tab-based
• permission parsing does not yet cover every special case
• there is no sorting layer
• build/test automation is not present yet

Scope for improvement

If this evolves further, the most useful next steps would be:

1. improve formatting to more closely match real ls
2. handle special permission bits like setuid, setgid, and sticky bit
3. support more file types in the permission prefix
4. add a Makefile
5. compile cleanly under stricter feature-macro and warning settings
6. add tests for option parsing and output behavior

Summary

lsbtw is a compact C learning project about implementing a small part of ls to understand directory traversal, metadata inspection, and Unix permission parsing at the systems level.