Struct WasiFs 

pub struct WasiFs {
    pub preopen_fds: RwLock<Vec<u32>>,
    pub fd_map: RwLock<FdList>,
    pub current_dir: Mutex<String>,
    pub root_fs: WasiFsRoot,
    pub root_inode: InodeGuard,
    pub has_unioned: Mutex<HashSet<PackageId>>,
    ephemeral_symlinks: Arc<RwLock<HashMap<PathBuf, EphemeralSymlinkEntry>>>,
    is_wasix: AtomicBool,
    pub(crate) init_preopens: Vec<PreopenedDir>,
    pub(crate) init_vfs_preopens: Vec<String>,
}

Warning, modifying these fields directly may cause invariants to break and should be considered unsafe. These fields may be made private in a future release

Lock order when touching both the fd map and an inode: fd_map first, then inode. Prefer the *_locked helpers on WasiFs (insert_fd_locked, clone_fd_locked, close_fd_locked, dup2_at) so handle counts and map slots stay consistent under concurrency.

Fields

preopen_fds: RwLock<Vec<u32>>

fd_map: RwLock<FdList>

current_dir: Mutex<String>

root_fs: WasiFsRoot

root_inode: InodeGuard

has_unioned: Mutex<HashSet<PackageId>>

ephemeral_symlinks: Arc<RwLock<HashMap<PathBuf, EphemeralSymlinkEntry>>>

is_wasix: AtomicBool

init_preopens: Vec<PreopenedDir>

init_vfs_preopens: Vec<String>

Implementations

impl WasiFs

fn writable_package_mount( fs: Arc<dyn FileSystem + Send + Sync>, limiter: Option<&DynFsMemoryLimiter>, ) -> Arc<dyn FileSystem + Send + Sync>

pub fn is_wasix(&self) -> bool

pub fn set_is_wasix(&self, is_wasix: bool)

pub(crate) fn register_ephemeral_symlink( &self, full_path: PathBuf, path_to_symlink: PathBuf, relative_path: PathBuf, )

pub(crate) fn ephemeral_symlink_at( &self, full_path: &Path, ) -> Option<(PathBuf, PathBuf)>

pub(crate) fn unregister_ephemeral_symlink(&self, full_path: &Path)

pub(crate) fn move_ephemeral_symlink( &self, old_full_path: &Path, new_full_path: &Path, path_to_symlink: PathBuf, relative_path: PathBuf, )

pub fn fork(&self) -> Self

Forking the WasiState is used when either fork or vfork is called

pub async fn close_cloexec_fds(&self)

Closes all file descriptors marked CLOEXEC (except stdio and preopens).

pub async fn close_all(&self)

Closes all file descriptors, flushing captured handles after dropping the map lock.

pub async fn conditional_union( &self, binary: &BinaryPackage, ) -> Result<(), FsError>

Will conditionally union the binary file system with this one if it has not already been unioned

pub(crate) fn new_with_preopen( inodes: &WasiInodes, preopens: &[PreopenedDir], vfs_preopens: &[String], fs_backing: WasiFsRoot, ) -> Result<Self, String>

Created for the builder API. like new but with more information

pub(crate) fn relative_path_to_absolute(&self, path: String) -> String

Converts a relative path into an absolute path

fn new_init( fs_backing: WasiFsRoot, inodes: &WasiInodes, st_ino: Inode, ) -> Result<Self, String>

Private helper function to init the filesystem, called in new and new_with_preopen

pub unsafe fn open_dir_all( &mut self, inodes: &WasiInodes, base: WasiFd, name: String, rights: Rights, rights_inheriting: Rights, flags: Fdflags, fd_flags: Fdflagsext, ) -> Result<WasiFd, FsError>

This function is like create dir all, but it also opens it. Function is unsafe because it may break invariants and hasn’t been tested. This is an experimental function and may be removed

Safety

• Virtual directories created with this function must not conflict with the standard operation of the WASI filesystem. This is vague and unlikely in practice. Join the discussion for what the newer, safer WASI FS APIs should look like.

pub fn open_file_at( &mut self, inodes: &WasiInodes, base: WasiFd, file: Box<dyn VirtualFile + Send + Sync + 'static>, open_flags: u16, name: String, rights: Rights, rights_inheriting: Rights, flags: Fdflags, fd_flags: Fdflagsext, ) -> Result<WasiFd, FsError>

Opens a user-supplied file in the directory specified with the name and flags given

pub fn swap_file( &self, fd: WasiFd, file: Box<dyn VirtualFile + Send + Sync + 'static>, ) -> Result<Option<Box<dyn VirtualFile + Send + Sync + 'static>>, FsError>

Change the backing of a given file descriptor Returns the old backing TODO: add examples

pub fn filestat_resync_size(&self, fd: WasiFd) -> Result<Filesize, Errno>

refresh size from filesystem

pub fn set_current_dir(&self, path: &str)

Changes the current directory

pub fn get_current_dir( &self, inodes: &WasiInodes, base: WasiFd, ) -> Result<(InodeGuard, String), Errno>

Gets the current directory

pub(crate) fn get_current_dir_inner( &self, inodes: &WasiInodes, base: WasiFd, symlink_count: u32, ) -> Result<(InodeGuard, String), Errno>

fn get_inode_at_path_inner( &self, inodes: &WasiInodes, cur_inode: InodeGuard, path_str: &str, symlink_count: &mut u32, follow_symlinks: bool, ) -> Result<InodeGuard, Errno>

Resolve a path in the POSIX namespace visible to the WASIX guest.

This function intentionally resolves guest paths, not host-native paths. A Windows host path may contain \, drive prefixes, or UNC prefixes, but those belong to mount setup and backing filesystem access. Once a host directory is mounted into WASIX, the guest observes a POSIX path tree where / is the only separator. Raw syscall paths must therefore be parsed with POSIX rules even when the runtime itself is running on Windows.

POSIX path resolution is stricter than Rust’s Path::components(): explicit ., explicit .., an empty pathname, and a trailing slash are all observable. In particular, file/ and file/. must fail with Errno::Notdir, lstat("symlink_to_dir/") must follow the symlink to prove the result is a directory, and lstat("symlink_to_file/") must fail with Errno::Notdir. For that reason this function uses a small POSIX component parser instead of Path::components().

Symlink following follows the POSIX rule used by openat-style APIs: intermediate symlinks are always followed, while the final component is followed only when follow_symlinks is true. Recursive symlink resolution increments symlink_count, and symlink depth exhaustion maps to Errno::Loop.

There are two loops here with different jobs. The outer loop walks the parsed path components. The inner component_lookup loop normally runs once, but has one virtual-root overlay case: when the current inode is Kind::Root and a component is not found directly, it can jump through the mounted entries["/"] inode and retry the same component. That is WASIX virtual-root behavior, not plain POSIX filesystem traversal.

Keep these edge cases intact when editing this function:

• Empty pathnames are Errno::Noent; they do not resolve to the base inode unless a separate AT_EMPTY_PATH-style extension is introduced.
• Absolute paths resolve from VIRTUAL_ROOT_FD, independent of the caller-provided starting inode.
• A literal root pathname (/, //, and so on) preserves historical WASIX behavior: if the virtual root contains a mounted entries["/"] directory, the literal root path resolves to that mounted directory. This special case is intentionally limited to an all-slashes pathname.
• Parent traversal is semantic, not a string rewrite. The virtual root’s parent is itself, but a mounted directory whose guest name is / still has the virtual root as its parent. Therefore /.. may resolve to Kind::Root after walking from the mounted / directory upward, and traversal that genuinely reaches Kind::Root must not be remapped back to entries["/"] at the end. That distinction lets WASI guests see the virtual root with all preopens via .. without changing the behavior of opening literal /.
• . and .. are semantic components: they require the current inode to be a directory or virtual root, otherwise they fail with Errno::Notdir.
• Special files may be returned only as the final component. As path prefixes, they fail with Errno::Notdir.

The returned InodeGuard is the inode for the resolved final object in the WASIX inode graph. It is not necessarily an already-open host file: file inodes discovered here are normally created with handle: None, and path_open or a similar caller opens the backing file later. If the final object is a symlink and follow_symlinks is false, the returned inode is the symlink itself; otherwise symlink targets are resolved recursively and the returned inode is the target.

Directory entries are a lazy cache over the backing filesystem. When a child name is already present in the current Kind::Dir or Kind::Root, that cached inode wins. When a child is missing from a Kind::Dir, this resolver builds the backing path for that one component, checks the ephemeral symlink table, then calls root_fs.symlink_metadata() without following symlinks. Based on that metadata it materializes a Kind::Dir, Kind::File, Kind::Symlink, or supported special-file inode. Persistent backing entries are inserted into the parent directory cache; ephemeral symlink inodes are transient and are not cached as directory entries.

Cached directory entries are part of the guest-visible directory model, not merely an implementation detail. A later fd_readdir over a backing directory must merge these cached children with host children instead of hiding non-preopen cache entries; otherwise cleanup and tree-walking code can miss inodes that this resolver can still reach.

This function is therefore not a full synchronization pass. It observes the backing filesystem on cache misses, but cached entries are reused without re-statting. Syscalls that mutate the filesystem are responsible for keeping the inode cache and ephemeral symlink map coherent with their changes.

pub(crate) fn resolve_symlink_target_path( &self, symlink_kind: SymlinkKind, path_to_symlink: &Path, relative_path: &Path, ) -> Result<(WasiFd, PathBuf), Errno>

pub(crate) fn rebase_symlink_location(&self, new_symlink_path: &Path) -> PathBuf

pub(crate) fn get_inode_at_path( &self, inodes: &WasiInodes, base: WasiFd, path: &str, follow_symlinks: bool, ) -> Result<InodeGuard, Errno>

gets a host file from a base directory and a path this function ensures the fs remains sandboxed

pub(crate) fn get_inode_at_path_from_inode( &self, inodes: &WasiInodes, base_inode: InodeGuard, path: &str, follow_symlinks: bool, ) -> Result<InodeGuard, Errno>

pub(crate) fn get_parent_inode_at_path( &self, inodes: &WasiInodes, base: WasiFd, path: &Path, follow_symlinks: bool, ) -> Result<(InodeGuard, String), Errno>

Returns the parent Dir or Root that the file at a given path is in and the file name stripped off

pub fn get_fd(&self, fd: WasiFd) -> Result<Fd, Errno>

pub fn get_fd_inode(&self, fd: WasiFd) -> Result<InodeGuard, Errno>

pub fn filestat_fd(&self, fd: WasiFd) -> Result<Filestat, Errno>

pub fn fdstat(&self, fd: WasiFd) -> Result<Fdstat, Errno>

pub fn prestat_fd(&self, fd: WasiFd) -> Result<Prestat, Errno>

pub(crate) fn prestat_fd_inner(&self, inode_val: &InodeVal) -> Prestat

pub(crate) fn create_inode( &self, inodes: &WasiInodes, kind: Kind, is_preopened: bool, name: String, ) -> Result<InodeGuard, Errno>

Creates an inode and inserts it given a Kind and some extra data

pub(crate) fn create_inode_with_default_stat( &self, inodes: &WasiInodes, kind: Kind, is_preopened: bool, name: Cow<'static, str>, ) -> InodeGuard

Creates an inode and inserts it given a Kind, does not assume the file exists.

pub(crate) fn create_inode_with_stat( &self, inodes: &WasiInodes, kind: Kind, is_preopened: bool, name: Cow<'static, str>, stat: Filestat, ) -> InodeGuard

Creates an inode with the given filestat and inserts it.

fn make_fd( rights: Rights, rights_inheriting: Rights, fs_flags: Fdflags, fd_flags: Fdflagsext, open_flags: u16, inode: InodeGuard, idx: Option<WasiFd>, ) -> Fd

pub(crate) fn insert_fd_locked( fd_map: &mut FdList, rights: Rights, rights_inheriting: Rights, fs_flags: Fdflags, fd_flags: Fdflagsext, open_flags: u16, inode: InodeGuard, idx: Option<WasiFd>, exclusive: bool, ) -> Result<WasiFd, Errno>

Insert a new fd into an already write-locked fd map.

Lock order: callers must hold fd_map.write() and must not hold any inode lock while acquiring the fd map lock.

pub(crate) fn clone_fd_locked( fs: &WasiFs, fd_map: &mut FdList, fd: WasiFd, min_result_fd: WasiFd, cloexec: Option<bool>, ) -> Result<WasiFd, Errno>

Duplicate an fd into an already write-locked fd map.

pub(crate) fn get_fd_from_locked_map( fs: &WasiFs, fd_map: &FdList, fd: WasiFd, ) -> Result<Fd, Errno>

Resolve an fd from a write-locked map (includes VIRTUAL_ROOT_FD fallback).

fn virtual_root_fd(root_inode: InodeGuard) -> Fd

fn ensure_file_handle_present(fd: &Fd) -> Result<(), Errno>

pub(crate) fn dup2_at( &self, src: WasiFd, dst: WasiFd, ) -> Result<Option<Arc<RwLock<Box<dyn VirtualFile + Send + Sync + 'static>>>>, Errno>

POSIX dup2: copy src onto exact slot dst, replacing any existing entry.

Holds fd_map.write() for the full remove+insert. Returns a flush target for the replaced dst entry (if any), captured while the lock is held and before remove calls drop_one_handle, which may clear the inode’s file handle.

pub fn create_fd( &self, rights: Rights, rights_inheriting: Rights, fs_flags: Fdflags, fd_flags: Fdflagsext, open_flags: u16, inode: InodeGuard, ) -> Result<WasiFd, Errno>

pub fn with_fd( &self, rights: Rights, rights_inheriting: Rights, fs_flags: Fdflags, fd_flags: Fdflagsext, open_flags: u16, inode: InodeGuard, idx: WasiFd, ) -> Result<(), Errno>

pub fn create_fd_ext( &self, rights: Rights, rights_inheriting: Rights, fs_flags: Fdflags, fd_flags: Fdflagsext, open_flags: u16, inode: InodeGuard, idx: Option<WasiFd>, exclusive: bool, ) -> Result<WasiFd, Errno>

pub fn clone_fd(&self, fd: WasiFd) -> Result<WasiFd, Errno>

pub fn clone_fd_ext( &self, fd: WasiFd, min_result_fd: WasiFd, cloexec: Option<bool>, ) -> Result<WasiFd, Errno>

pub unsafe fn remove_inode( &self, inodes: &WasiInodes, ino: Inode, ) -> Option<Arc<InodeVal>>

Low level function to remove an inode, that is it deletes the WASI FS’s knowledge of a file.

This function returns the inode if it existed and was removed.

Safety

• The caller must ensure that all references to the specified inode have been removed from the filesystem.

pub(crate) fn create_stdout(&self, inodes: &WasiInodes)

pub(crate) fn create_stdin(&self, inodes: &WasiInodes)

pub(crate) fn create_stderr(&self, inodes: &WasiInodes)

pub(crate) fn create_rootfd(&self) -> Result<(), String>

pub(crate) fn create_preopens( &self, inodes: &WasiInodes, ignore_duplicates: bool, ) -> Result<(), String>

pub(crate) fn create_std_dev_inner( &self, inodes: &WasiInodes, handle: Box<dyn VirtualFile + Send + Sync + 'static>, name: &'static str, raw_fd: WasiFd, rights: Rights, fd_flags: Fdflags, st_ino: Inode, )

pub fn get_stat_for_kind(&self, kind: &Kind) -> Result<Filestat, Errno>

pub(crate) fn close_fd_and_capture_flush(&self, fd: WasiFd) -> CloseFdOutcome

Closes an open FD under fd_map.write(), capturing a file handle for post-close flush while the map lock is held.

Lock order: fd_map write, then inode read (never the reverse).

fn close_fd_locked(fd_map: &mut FdList, fd: WasiFd) -> CloseFdOutcome

Closes an open FD in an already write-locked fd map.

pub(crate) async fn flush_file_best_effort( file: Arc<RwLock<Box<dyn VirtualFile + Send + Sync + 'static>>>, )

fn file_flush_target( inode: &InodeGuard, ) -> Option<Arc<RwLock<Box<dyn VirtualFile + Send + Sync + 'static>>>>

pub(crate) fn close_fd(&self, fd: WasiFd) -> Result<(), Errno>

Closes an open FD, handling all details such as FD being preopen

Trait Implementations

impl Debug for WasiFs

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

Formats the value using the given formatter.