Skip to main content
WinFsp-MemFs-Extended (memefs) is built on top of the WinFsp (Windows File System Proxy) framework, which enables user-mode file systems on Windows. Understanding this integration helps you work with memefs effectively.

​
Architecture overview

memefs implements a complete user-mode file system by:
  1. Creating a WinFsp file system instance via FspFileSystemCreate() in create.cpp:70
  2. Implementing the FSP_FILE_SYSTEM_INTERFACE callbacks in memfs-interface.h:129-161
  3. Running as a Windows service using the WinFsp service framework
The core integration happens through the FSP_FILE_SYSTEM structure, which memefs wraps in the MemFs class (memfs.h:27-80).

​
File system interface

memefs implements nearly all WinFsp callbacks to provide complete file system functionality:

​
Volume operations

  • GetVolumeInfo: Returns volume metadata including size, serial number, and label
  • SetVolumeLabel: Allows changing the volume label (accessible via -l CLI flag)

​
File operations

  • Create: Creates new files or directories
  • Open: Opens existing files
  • Overwrite: Replaces file contents
  • Read: Reads data from files (io.cpp:4-24)
  • Write: Writes data to files (io.cpp:26-65)
  • Flush: Flushes file data (io.cpp:67-75)

​
Metadata operations

  • GetFileInfo: Retrieves file attributes and timestamps
  • SetBasicInfo: Updates file attributes and timestamps
  • SetFileSize: Changes file size (allocation or actual size)
  • Rename: Renames files and directories
  • CanDelete: Checks if a file can be deleted

​
Security operations

  • GetSecurityByName: Gets security descriptor by file name
  • GetSecurity: Gets security descriptor for open file
  • SetSecurity: Updates security descriptor

​
Advanced features

  • ReadDirectory: Enumerates directory contents
  • GetDirInfoByName: Gets directory entry by name
  • GetReparsePoint/SetReparsePoint/DeleteReparsePoint: Manages reparse points (symlinks, junctions)
  • GetStreamInfo: Enumerates alternate data streams
  • GetEa/SetEa: Manages extended attributes
  • ResolveReparsePoints: Resolves symbolic links

​
Service integration

memefs runs as a Windows service using WinFsp’s service framework: 
int wmain(int argc, wchar_t** argv) {
    std::wstring progName{PROGNAME};
    return FspServiceRun(progName.data(), SvcStart, SvcStop, nullptr);
}
The service lifecycle (main.cpp:223-227):
  1. SvcStart (main.cpp:49-211): Parses CLI arguments, creates the memefs instance, mounts the file system
  2. Service runs: WinFsp dispatches file system operations to memefs callbacks
  3. SvcStop (main.cpp:213-221): Stops the dispatcher, destroys the memefs instance

​
Volume parameters

When creating the file system, memefs configures WinFsp with specific capabilities (create.cpp:34-58):
  • Sector size: 512 bytes (MEMFS_SECTOR_SIZE)
  • Sectors per allocation unit: Configurable via MEMFS_SECTORS_PER_ALLOCATION_UNIT
  • Case sensitivity: Configurable via -i flag
  • Unicode on disk: Enabled for proper filename handling
  • Persistent ACLs: Full security descriptor support
  • Reparse points: Symlink and junction support
  • Named streams: NTFS alternate data streams
  • Extended attributes: EA support
  • POSIX semantics: POSIX unlink/rename support
  • WSL features: Windows Subsystem for Linux compatibility

​
Dispatcher and threading

The WinFsp dispatcher handles multi-threading automatically: 
NTSTATUS MemFs::Start() const {
    return FspFileSystemStartDispatcher(this->fileSystem.get(), 0);
}

void MemFs::Stop() const {
    FspFileSystemStopDispatcher(this->fileSystem.get());
}
WinFsp creates a thread pool and dispatches operations concurrently. memefs handles concurrency using:
  • Shared mutexes for sector access (sectors.h:17)
  • Reference counting for file nodes (nodes.h:27-29)
  • Thread-safe maps for file node storage

​
Debug logging

WinFsp provides built-in debug logging that you can enable: 
memefs -d -1 -D memefs.log [other options]
This logs all WinFsp operations to memefs.log, which is invaluable for troubleshooting. The debug flags are set via FspFileSystemSetDebugLog() (main.cpp:152).

​
Mount points

memefs supports two mounting modes:

​
Disk mode (drive letter)

memefs -m R: [options]
Creates a virtual drive at R:

​
Network mode (UNC path)

memefs -u \\Server\Share -m * [options]
Creates a network share accessible as \\Server\Share The mount point is configured via FspFileSystemSetMountPoint() (main.cpp:155-161).

​
Memory management

memefs uses WinFsp in a unique way:
  • Original memfs: Used Windows heap functions, causing performance issues with unpreallocated files
  • memefs: Uses vector-based sector storage (sectors.h) with a private heap
This architectural change dramatically improves write performance for files that aren’t preallocated, making memefs suitable as a constantly-running RAM disk.

​
Error handling

All WinFsp callbacks return NTSTATUS codes:
  • STATUS_SUCCESS: Operation succeeded
  • STATUS_UNSUCCESSFUL: Generic failure
  • STATUS_END_OF_FILE: Read beyond file end
  • STATUS_DISK_FULL: No space available
  • And many others defined by Windows NT
memefs maps C++ exceptions to NTSTATUS codes using custom exception types (exceptions.h).

​
Further reading

Build docs developers (and LLMs) love

Get started for freeTalk to us