Ch26.11: Filesystem and OS Layers
1. Two Kinds of API
This page covers two related surfaces. The filesystem surface walks directories and opens entries relative to a directory handle. The OS layer surface exposes the native file types of each platform: POSIX file descriptors, Win32 handles, NT handles and Wine host descriptors.
They share one rule: a directory handle or native handle is an owner; an entry, observer
or at_entry is a borrow. The borrow must not outlive the handle that anchors
it.
2. Directory Handles and Entries
| Name | Role | Module |
|---|---|---|
dir_file |
Owning directory handle. Opens a path and closes it on destruction. | fast_io |
dir_io_observer |
Non-owning view of a directory handle. | fast_io |
at(df) |
An at_entry anchored at the directory; the base for relative
opens and traversal. |
fast_io |
current(at(df)) |
Range of immediate children. | fast_io |
recursive(at(df)) |
Range of all descendants. | fast_io |
::fast_io::dir_file df(u8"data");
for (auto const &ent : ::fast_io::current(::fast_io::at(df)))
{
if (::fast_io::is_dot(ent)) continue;
println(::fast_io::mnp::code_cvt(::fast_io::u8filename(ent)));
}
3. Directory Entry Functions
| Function | Returns | Module |
|---|---|---|
u8filename(ent) |
UTF-8 filename view. | fast_io |
u8extension(ent) |
UTF-8 extension view. | header-side |
u8stem(ent) |
UTF-8 filename without the extension. | header-side |
native_filename(ent) |
Filename in the platform's native encoding. | header-side |
type(ent) |
file_type. |
header-side |
is_dot(ent) |
True for . and ... |
fast_io |
drt(ent) |
A (directory handle, name) pair for opening the entry. | header-side |
file_type distinguishes regular, directory,
symlink, block, character, fifo,
socket, unknown and not_found.
for (auto const &ent : ::fast_io::current(::fast_io::at(df)))
{
if (::fast_io::is_dot(ent)) continue;
if (::fast_io::type(ent) == ::fast_io::file_type::regular)
{
::fast_io::native_file_loader loader(::fast_io::drt(ent));
println(::fast_io::mnp::code_cvt(::fast_io::u8filename(ent)),
": ", loader.size(), " bytes");
}
}
4. Opening Relative to a Directory
A relative open anchored at an at_entry avoids building a full path and
avoids the race between checking a path and opening it. The pattern is the same on every
platform: construct the file type with at(df) and the relative name.
::fast_io::dir_file df(u8"data");
::fast_io::native_file f(::fast_io::at(df), u8"record.bin",
::fast_io::open_mode::in);
at(ent) anchors at a specific directory entry, and drt(ent)
gives the (handle, name) pair that file constructors and loaders accept.
This is the preferred way to open a file discovered by traversal.
5. Temporary Files
::fast_io::io_temp is a tag, not a type. Pass it to any owning file
constructor. The file is created in the system temporary directory and is removed when the
object is destroyed:
::fast_io::iobuf_file tmp{::fast_io::io_temp};
println(tmp, "scratch data");
It works with native_file, obuf_file, iobuf_file,
c_file and the other owning file types. io_temp is header-side,
not in the module export list yet. The removal is tied to the object's
lifetime, not to a separate cleanup call.
6. Native OS Layers
| Type | Platform | Handle | Module |
|---|---|---|---|
posix_file |
POSIX | file descriptor | fast_io |
win32_file |
Windows | HANDLE |
fast_io |
nt_file |
Windows NT API | NT HANDLE |
fast_io |
zw_file |
Windows NT API | NT HANDLE |
fast_io |
wine_file |
Wine on POSIX | host descriptor | header-side |
c_file |
C stdio | FILE* |
fast_io_legacy |
filebuf_file |
C++ iostream | basic_filebuf* |
fast_io_legacy |
Use a native layer when you need the platform's own handle, flags or error semantics. Otherwise use the buffered alias, which hides the platform difference. The layer relationship is documented in Ch11.17.
Wrapping an existing handle is explicit: the owner type adopts it and closes it. An observer type borrows it and does not close it. Do not construct both for the same handle.
7. Memory Mapping and File Loaders
native_file_loader maps a file and exposes its bytes without a read loop.
It is the preferred way to load a large read-only file:
::fast_io::native_file_loader loader("big.bin");
auto *data{loader.data()};
auto size{loader.size()};
The loader owns the mapping and releases it on destruction. On platforms without a usable
mapping it falls back to an allocation loader with the same observable API. For writable
mappings and explicit flags, use the platform mmap options and the
allocation_file_loader family; the tutorial covers the details in
Ch11.8.
8. Module and Header Boundary
The fast_io module exports dir_file, at,
current, recursive, u8filename,
is_dot, file_type, posix_file_status,
native_file_loader, and the platform file types
posix_file, win32_file and nt_file.
Entry helpers such as u8extension, u8stem,
native_filename, type and drt are header-side
today.
Key Takeaways
dir_fileowns a directory;at_entryand entries borrow from it.at,currentandrecursiveare the traversal primitives.u8filenameandis_dotare module-exported; extension, stem, native name anddrtare header-side.- Open entries relative to
at(df)ordrt(ent), not by rebuilding full paths. io_tempis a tag for any owning file constructor; the file is removed when the object dies.- Native file types expose the platform handle; buffered aliases hide the platform.
native_file_loadermaps a file instead of copying it into a buffer.