Gleam - Simple File System

A lightweight, minimal file system implementation in C++ that simulates basic Unix-like file operations on a virtual disk image.

Overview

Gleam is a simple file system that operates on a single binary disk image file. It implements core file system concepts including:

• Inodes for file and directory metadata
• Directory entries
• Superblock for file system metadata
• Block-based storage allocation
• Direct block pointers

Features

• File Operations: Create, read, and write files
• Directory Operations: Create directories and navigate the file system
• Unix-like Commands: Familiar command interface (ls, cd, pwd, mkdir, touch, cat)
• Persistent Storage: All changes are saved to a disk image file

Building the Project

# Navigate to the build directory
cd build

# Configure with CMake
cmake ..

# Build the project
cmake --build .

Usage

Starting the File System

./gleam <disk_image>

If the disk image doesn't exist, it will be created automatically.

Example:

./gleam mydisk.gleam

Available Commands

Once the file system is running, you'll see the fs> prompt. The following commands are available:

format

Format the disk (reinitialize the file system). This will erase all data.

fs> format

ls

List contents of the current directory.

fs> ls

pwd

Print the current working directory path.

fs> pwd

cd <directory>

Change to the specified directory.

fs> cd mydir
fs> cd ..
fs> cd .

mkdir <directory>

Create a new directory.

fs> mkdir documents
fs> mkdir projects

touch <filename>

Create a new empty file.

fs> touch readme.txt
fs> touch notes.md

write <filename> <data>

Write data to an existing file.

fs> write readme.txt Hello, World!
fs> write notes.md This is my note

cat <filename>

Display the contents of a file.

fs> cat readme.txt

exit

Exit the file system shell.

fs> exit

Example Session

$ ./gleam test.gleam
Disk image not found. Creating a new one...
Formatting file system...
fs> ls
.
..
fs> mkdir documents
fs> mkdir photos
fs> touch readme.txt
fs> ls
.
..
documents
photos
readme.txt
fs> cd documents
fs> pwd
/documents
fs> touch notes.txt
fs> write notes.txt This is my first note in Gleam!
fs> cat notes.txt
This is my first note in Gleam!
fs> cd ..
fs> pwd
/
fs> exit

Technical Details

File System Structure

• Block Size: 4096 bytes
• Total Blocks: 100
• Direct Blocks per Inode: 4
• Maximum File Size: 16 KB (4 blocks × 4096 bytes)

Disk Layout

Block	Purpose
0	Superblock (metadata)
1	Reserved
2	Inode table
3+	Data blocks

Limitations

• Maximum file size is limited to 4 direct blocks (16 KB)
• No indirect blocks support
• Fixed number of inodes (determined by block size)
• No file permissions or ownership
• No timestamps
• Single-threaded, no concurrent access support

Project Structure

gleam/
├── CMakeLists.txt       # Build configuration
├── README.md            # This file
├── src/
│   └── main.cpp         # Main file system implementation
└── build/               # Build directory (generated)

Implementation Details

The file system uses several key components:

• Disk: Manages block-level I/O operations
• SuperBlock: Stores file system metadata
• Inode: Stores file/directory metadata and block pointers
• DirEntry: Directory entry structure (inode number + name)
• Constants Namespace: File system constants
• Fs Namespace: File system formatting and core operations
• Commands Namespace: User-facing command implementations

License

This is an educational project for learning file system concepts.

Contributing

This is a learning project. Feel free to fork and experiment with adding new features like:

• Indirect blocks for larger files
• File deletion
• File/directory renaming
• File permissions
• Symbolic links
• Better error handling