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.

Do not mix owners for one handle. If a constructor adopts a native handle, the handle is now owned by that object. Wrapping it again in another owner will double-close it. Use an observer when you only need to borrow.

Key Takeaways