File

Table of Contents

• Dependencies
• Features
• Status
• Blog
• Description
• Roadmap
• Statistics

🟩 Synchronous Disk File I/O

SaneCppFile.h is a library implementing synchronous I/O operations on files and pipes.

Dependencies

• Dependencies: Foundation
• All dependencies: Foundation

Features

SC::FileDescriptor	[UniqueHandleDeclaration2Snippet]
SC::FileDescriptor::read	Reads bytes at offset into user supplied span.
SC::FileDescriptor::write	Writes bytes at offset from start of the file descriptor.
SC::FileDescriptor::seek	Changes the current position in the file descriptor, if seekable.
SC::FileDescriptor::open	Opens a file descriptor handle from a file system path.
SC::FileDescriptor::openStdInDuplicate	Opens a duplicated file descriptor handle for reading from stdin.
SC::FileDescriptor::openStdOutDuplicate	Opens a duplicated file descriptor handle for reading from stdout.
SC::FileDescriptor::openStdErrDuplicate	Opens a duplicated file descriptor handle for reading from stderr.
SC::FileDescriptor::readUntilEOF	Reads into a given dynamic buffer until End of File (EOF) is signaled.
SC::FileDescriptor::stat	Obtains richer metadata associated with the currently open descriptor.
SC::FileDescriptor::chmod	Change file permission bits for the currently open descriptor.
SC::FileDescriptor::chown	Change owner and group for the currently open descriptor.
SC::FileDescriptor::sync	Flush file data and metadata to stable storage.
SC::FileDescriptor::syncData	Flush file data to stable storage.
SC::FileDescriptor::truncate	Resize the underlying file to the specified size in bytes.

SC::PipeDescriptor	Read / Write pipe (Process stdin/stdout and IPC communication)
SC::PipeDescriptor::readPipe	The read side of the pipe.
SC::PipeDescriptor::writePipe	The write side of the pipe.

SC::NamedPipeServer	Named pipe server endpoint.
SC::NamedPipeServer::create	Creates a named pipe server endpoint.
SC::NamedPipeServer::accept	Accept one client connection and return it as a connected PipeDescriptor.
SC::NamedPipeServer::close	Closes the listening endpoint.
SC::NamedPipeServerOptions
SC::NamedPipeClient	Named pipe client endpoint creator.
SC::NamedPipeClient::connect	Connects to an existing named pipe server endpoint.
SC::NamedPipeClientOptions
SC::NamedPipeName	Utility for building platform-native named pipe endpoint names from logical names.
SC::NamedPipeName::build	Builds a platform-native named pipe endpoint path.
SC::NamedPipeNameOptions

Status

🟩 Usable
This library now covers synchronous descriptor I/O together with descriptor metadata, synchronization and descriptor-bound permission/ownership updates. sendfile is still intentionally deferred until a dependency-safe cross-library API is defined.

Blog

Some relevant blog posts are:

• July 2025 Update
• August 2025 Update
• February 2026 Update
• March 2026 Update

Description

SC::FileDescriptor object can be created by SC::FileDescriptor::open-ing a path on file system and it can be SC::FileDescriptor::read or SC::FileDescriptor::write.
Also non-blocking mode can be controlled with SC::FileDescriptor::setBlocking.
A file can be marked as inheritable with SC::FileDescriptor::setInheritable so that in can be accessed by child processes. SC::PipeDescriptor creates a pipe for InterProcess communication.
A pipe has read and write SC::FileDescriptor endpoints and it's used by Process library to redirect standard input, output or error to other processes.
It can also be used to read or write the standard input, output or error from current process into a binary buffer or a string (as done by SC::ProcessChain::readStdOutUntilEOFSync or other similar methods).

SC::NamedPipeServer and SC::NamedPipeClient provide named endpoint creation and connection. Accepted/connected named pipe endpoints are exposed as SC::PipeDescriptor, so they can be used with the same read/write APIs and with Async / Async Streams compositions. SC::NamedPipeName::build can be used to compose platform-native endpoint names from a logical pipe name, avoiding platform-specific #if path conventions at call sites.

Open, read and write to/from a file descriptor (like a file or pipe).

Roadmap

🟦 Complete Features:

• sendfile deferred until a dependency-safe API is defined

💡 Unplanned Features:

• None for now

Statistics

Type	Lines Of Code	Comments	Sum
Headers	189	203	392
Sources	1292	200	1492
Sum	1481	403	1884