Struct StdFilesystem 

pub struct StdFilesystem;

Filesystem implementation backed by std::fs.

Every method delegates directly to the standard library. Symlink semantics, depth caps, and platform-specific path normalisation are whatever std::fs provides on the host platform.

OS errors are translated to the trait-level vocabulary by inspecting raw_os_error:

• ELOOP on Unix and ERROR_CANT_RESOLVE_FILENAME (1921) on Windows map to FsError::SymlinkLoop.
• EISDIR on Unix maps to FsError::NotAFile when surfaced from read; on Windows ERROR_ACCESS_DENIED is overloaded with genuine permission failures and is NOT remapped here.
• ENOTDIR on Unix and ERROR_DIRECTORY (267) on Windows map to FsError::NotADirectory when surfaced from read_dir.

Every other I/O error falls through to FsError::Io.

read performs an additional Filesystem::metadata pre-check before delegating to std::fs::read: the OS does not surface “not a regular file” through a single error code (FIFO opens block, char-device opens succeed, sockets emit ENXIO), so a kind check by stat is the only way to honour the FsError::NotAFile contract for those kinds. The EISDIR translation remains in place as a TOCTOU backstop.

Implementations

impl StdFilesystem

pub const fn new() -> Self

Construct a new StdFilesystem.

Trait Implementations

impl Clone for StdFilesystem

fn clone(&self) -> StdFilesystem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for StdFilesystem

impl Debug for StdFilesystem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StdFilesystem

fn default() -> StdFilesystem

Returns the “default value” for a type.

impl Filesystem for StdFilesystem

type CanonicalPath = StdCanonicalPath

The implementation-specific canonical-path type produced by Filesystem::canonicalize.

fn metadata(&self, path: &Path) -> Result<FsMetadata, FsError>

Return metadata for the entry at path, FOLLOWING symlinks. If path is a symlink, the returned metadata describes the target.

fn symlink_metadata(&self, path: &Path) -> Result<FsMetadata, FsError>

Return metadata for the entry at path, WITHOUT following a trailing symlink. Intermediate symlinks in the path are followed; only the last component is returned as-is.

fn read_dir(&self, path: &Path) -> Result<Vec<DirEntry>, FsError>

Read all entries in the directory at path. The order of the returned entries is implementation-defined; callers MUST NOT depend on a particular order.

fn read(&self, path: &Path) -> Result<Vec<u8>, FsError>

Read the entire file at path and return its raw bytes. Symlinks in any component (including the last) are followed.

fn permissions(&self, path: &Path) -> Result<u32, FsError>

Return the Unix permission bits of the regular file at path, masked to the low 12 bits (the conventional S_IRWXU | S_IRWXG | S_IRWXO | S_ISUID | S_ISGID | S_ISVTX range). Symlinks in any component (including the last) are followed, matching Self::read’s semantics.

fn canonicalize(&self, path: &Path) -> Result<Self::CanonicalPath, FsError>

Resolve all symlinks and . / .. components in path and return the canonical absolute path as the implementation’s Self::CanonicalPath type. Every intermediate and terminal symlink is followed; the implementation MUST detect cycles and depth-cap exhaustion as FsError::SymlinkLoop.

fn read_link(&self, path: &Path) -> Result<PathBuf, FsError>

Read the target of the symlink at path. Does NOT follow the symlink itself (that would defeat the purpose); intermediate components ARE resolved as usual.

impl WritableFilesystem for StdFilesystem

fn create_dir_all(&self, path: &Path) -> Result<(), FsError>

Create the directory at path along with any missing intermediate components. Idempotent: succeeds when path already exists as a directory.

fn write_file(&self, path: &Path, contents: &[u8]) -> Result<(), FsError>

Write contents to path, overwriting any existing file. The immediate parent directory MUST already exist; the method does NOT create it (use Self::create_dir_all beforehand).

fn rename(&self, from: &Path, to: &Path) -> Result<(), FsError>

Rename from to to. On Unix this is rename(2); on Windows it is MoveFileExW with MOVEFILE_REPLACE_EXISTING. When to exists, it is atomically replaced (subject to the host platform’s guarantees; same filesystem only on Unix).

fn remove_dir_all(&self, path: &Path) -> Result<(), FsError>

Recursively remove path and every entry below it. Idempotent on missing paths: a path that does not exist returns FsError::NotFound; callers that want a true “remove if exists” pre-check with Filesystem::metadata.

fn set_permissions(&self, path: &Path, mode: u32) -> Result<(), FsError>

Set the Unix permission bits on path to mode (the low 12 bits of mode correspond to the POSIX S_IRWXU, S_IRWXG, S_IRWXO, S_ISUID, S_ISGID, S_ISVTX bits).

fn fsync_file(&self, path: &Path) -> Result<(), FsError>

Flush the contents and metadata of the file at path to durable storage. On Unix this is fsync(2) on an open(2)-ed descriptor; on Windows this is FlushFileBuffers. On in-memory implementations this is a documented no-op.

fn fsync_dir(&self, path: &Path) -> Result<(), FsError>

Flush the entry list of the directory at path to durable storage. POSIX requires this after rename(2) to make the rename itself durable across power loss. On Windows this MAY be a no-op (the platform does not expose the operation for directories). On in-memory implementations this is a documented no-op.