silk/os_filesystem

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.

Native FileSystem provider confined beneath one explicitly owned platform root.

When to use

Construct OsFileSystem at a native application edge and provide it to portable filesystem code. Supply an in-memory FileSystem in tests or on targets without native OS access.

Details

Portable / denotes the provider root rather than the host filesystem root. The native boundary rejects malformed portable paths and symlinks below the configured root. Whole-file reads and writes own or commit complete contents, directory listings retry oversized entries and sort complete child paths deterministically. Low-level failures become portable FileError values with retained native codes.

make copies its root. The root must be an absolute, non-empty, NUL-free native path. A root that violates this precondition traps. Open handles close on success and failure. If an operation and close both fail, the operation's original typed failure remains the reported result. The configured root and its ancestors must be trusted; confinement does not promise protection against hostile directory renames or privileged mount changes.

Constructing the provider performs no filesystem operation beyond owning the root bytes. Portable code uses FileSystem operations after the application supplies &mut OsFileSystem for the &mut FileSystem requirement.

Gotchas

This module publishes its provider only for the supported native profiles. WebAssembly selection leaves the module empty.

Examples

Construct a provider without accessing the filesystem

import silk.allocator { Allocator, OutOfMemoryError }

import silk.effect { Effect }

import silk.os_filesystem { OsFileSystem }

effect fn program() -> i32
! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let provider = run OsFileSystem.make(b"/tmp")
    |> Effect.provideMut<Allocator>(&mut allocator)
  drop provider
  return 42
}

effect fn recover(error: OutOfMemoryError) -> i32 {
  return 0
}

pub fn main() -> i32 {
  return run Effect.catchAll(program(), recover)
}

Import as OsFileSystem with import silk.os_filesystem { OsFileSystem }.

Public declarations: 1.

OsFileSystem

pub struct OsFileSystem

A native FileSystem provider confined beneath one independently owned platform root.

Details

Portable absolute paths resolve inside this root. The provider never exposes the root as a Path, and operations reject lexical or symbolic-link escape from the root.

Associated function OsFileSystem.make

pub effect<'life0> fn make<'life0>(root: &'life0 [u8]) -> OsFileSystem ! OutOfMemoryError ? &mut Allocator

Copies one absolute native root and creates a confined filesystem provider.

When to use

Use this function at a native application edge. Provide the result as &mut FileSystem to code that uses the portable filesystem service.

Details

Construction owns the root bytes but does not open the directory. Portable / then denotes this provider root instead of the host filesystem root.

Gotchas

root must be non-empty, absolute, and NUL-free. A value that violates this precondition traps. Allocation failure leaves no provider value.

Implementation FileSystem for OsFileSystem

impl FileSystem for OsFileSystem

Operation readFile

readFile = OsFileSystem.readFile

Operation writeFile

writeFile = OsFileSystem.writeFile

Operation stat

stat = OsFileSystem.stat

Operation listDirectory

listDirectory = OsFileSystem.listDirectory

Operation createDirectory

createDirectory = OsFileSystem.createDirectory

Operation removeFile

removeFile = OsFileSystem.removeFile

Operation removeDirectory

removeDirectory = OsFileSystem.removeDirectory

Operation createTemporaryDirectory

createTemporaryDirectory = OsFileSystem.createTemporaryDirectory