Struct cap_std::fs::Dir

pub struct Dir { /* private fields */ }

A reference to an open directory on a filesystem.

This does not directly correspond to anything in std, however its methods correspond to the functions in std::fs and the constructor methods for std::fs::File.

Unlike std::fs, this API’s canonicalize returns a relative path since absolute paths don’t interoperate well with the capability model.

Implementations

impl Dir

pub fn from_std_file(std_file: File) -> Self

Constructs a new instance of Self from the given std::fs::File.

To prevent race conditions on Windows, the file must be opened without FILE_SHARE_DELETE.

This grants access the resources the std::fs::File instance already has access to.

Examples found in repository

src/fs_utf8/dir.rs (line 47)

    pub fn from_std_file(std_file: fs::File) -> Self {
        Self::from_cap_std(crate::fs::Dir::from_std_file(std_file))
    }

src/fs/dir_entry.rs (line 44)

    pub fn open_dir(&self) -> io::Result<Dir> {
        let dir = self.inner.open_dir()?;
        Ok(Dir::from_std_file(dir))
    }

src/fs/dir.rs (line 108)

    pub fn open_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<Self> {
        let dir = open_dir(&self.std_file, path.as_ref())?;
        Ok(Self::from_std_file(dir))
    }

    /// Creates a new, empty directory at the provided path.
    ///
    /// This corresponds to [`std::fs::create_dir`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create_dir_one(path.as_ref(), &DirOptions::new())
    }

    /// Recursively create a directory and all of its parent components if they
    /// are missing.
    ///
    /// This corresponds to [`std::fs::create_dir_all`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create_dir_all(path.as_ref(), &DirOptions::new())
    }

    /// Creates the specified directory with the options configured in this
    /// builder.
    ///
    /// This corresponds to [`std::fs::DirBuilder::create`].
    #[cfg(not(target_os = "wasi"))]
    #[inline]
    pub fn create_dir_with<P: AsRef<Path>>(
        &self,
        path: P,
        dir_builder: &DirBuilder,
    ) -> io::Result<()> {
        let options = dir_builder.options();
        if dir_builder.is_recursive() {
            self._create_dir_all(path.as_ref(), options)
        } else {
            self._create_dir_one(path.as_ref(), options)
        }
    }

    fn _create_dir_one(&self, path: &Path, dir_options: &DirOptions) -> io::Result<()> {
        create_dir(&self.std_file, path, dir_options)
    }

    fn _create_dir_all(&self, path: &Path, dir_options: &DirOptions) -> io::Result<()> {
        if path == Path::new("") {
            return Ok(());
        }

        match self._create_dir_one(path, dir_options) {
            Ok(()) => return Ok(()),
            Err(ref e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(_) if self.is_dir(path) => return Ok(()),
            Err(e) => return Err(e),
        }
        match path.parent() {
            Some(p) => self._create_dir_all(p, dir_options)?,
            None => {
                return Err(io::Error::new(
                    io::ErrorKind::Other,
                    "failed to create whole tree",
                ))
            }
        }
        match self._create_dir_one(path, dir_options) {
            Ok(()) => Ok(()),
            Err(_) if self.is_dir(path) => Ok(()),
            Err(e) => Err(e),
        }
    }

    /// Opens a file in write-only mode.
    ///
    /// This corresponds to [`std::fs::File::create`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
        self.open_with(
            path,
            OpenOptions::new().write(true).create(true).truncate(true),
        )
    }

    /// Returns the canonical form of a path with all intermediate components
    /// normalized and symbolic links resolved.
    ///
    /// This corresponds to [`std::fs::canonicalize`], but instead of returning
    /// an absolute path, returns a path relative to the directory
    /// represented by `self`.
    #[inline]
    pub fn canonicalize<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf> {
        canonicalize(&self.std_file, path.as_ref())
    }

    /// Copies the contents of one file to another. This function will also
    /// copy the permission bits of the original file to the destination
    /// file.
    ///
    /// This corresponds to [`std::fs::copy`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        from: P,
        to_dir: &Self,
        to: Q,
    ) -> io::Result<u64> {
        copy(&self.std_file, from.as_ref(), &to_dir.std_file, to.as_ref())
    }

    /// Creates a new hard link on a filesystem.
    ///
    /// This corresponds to [`std::fs::hard_link`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        src: P,
        dst_dir: &Self,
        dst: Q,
    ) -> io::Result<()> {
        hard_link(
            &self.std_file,
            src.as_ref(),
            &dst_dir.std_file,
            dst.as_ref(),
        )
    }

    /// Given a path, query the file system to get information about a file,
    /// directory, etc.
    ///
    /// This corresponds to [`std::fs::metadata`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn metadata<P: AsRef<Path>>(&self, path: P) -> io::Result<cap_primitives::fs::Metadata> {
        stat(&self.std_file, path.as_ref(), FollowSymlinks::Yes)
    }

    /// Queries metadata about the underlying directory.
    ///
    /// This is similar to [`std::fs::File::metadata`], but for `Dir` rather
    /// than for `File`.
    #[inline]
    pub fn dir_metadata(&self) -> io::Result<Metadata> {
        Metadata::from_file(&self.std_file)
    }

    /// Returns an iterator over the entries within `self`.
    #[inline]
    pub fn entries(&self) -> io::Result<ReadDir> {
        read_base_dir(&self.std_file).map(|inner| ReadDir { inner })
    }

    /// Returns an iterator over the entries within a directory.
    ///
    /// This corresponds to [`std::fs::read_dir`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn read_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<ReadDir> {
        read_dir(&self.std_file, path.as_ref()).map(|inner| ReadDir { inner })
    }

    /// Read the entire contents of a file into a bytes vector.
    ///
    /// This corresponds to [`std::fs::read`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn read<P: AsRef<Path>>(&self, path: P) -> io::Result<Vec<u8>> {
        let mut file = self.open(path)?;
        let mut bytes = Vec::with_capacity(initial_buffer_size(&file));
        file.read_to_end(&mut bytes)?;
        Ok(bytes)
    }

    /// Reads a symbolic link, returning the file that the link points to.
    ///
    /// This corresponds to [`std::fs::read_link`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf> {
        read_link(&self.std_file, path.as_ref())
    }

    /// Read the entire contents of a file into a string.
    ///
    /// This corresponds to [`std::fs::read_to_string`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn read_to_string<P: AsRef<Path>>(&self, path: P) -> io::Result<String> {
        let mut s = String::new();
        self.open(path)?.read_to_string(&mut s)?;
        Ok(s)
    }

    /// Removes an empty directory.
    ///
    /// This corresponds to [`std::fs::remove_dir`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn remove_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        remove_dir(&self.std_file, path.as_ref())
    }

    /// Removes a directory at this path, after removing all its contents. Use
    /// carefully!
    ///
    /// This corresponds to [`std::fs::remove_dir_all`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        remove_dir_all(&self.std_file, path.as_ref())
    }

    /// Remove the directory referenced by `self` and consume `self`.
    ///
    /// Even though this implementation works in terms of handles as much as
    /// possible, removal is not guaranteed to be atomic with respect to a
    /// concurrent rename of the directory.
    #[inline]
    pub fn remove_open_dir(self) -> io::Result<()> {
        remove_open_dir(self.std_file)
    }

    /// Removes the directory referenced by `self`, after removing all its
    /// contents, and consume `self`. Use carefully!
    ///
    /// Even though this implementation works in terms of handles as much as
    /// possible, removal is not guaranteed to be atomic with respect to a
    /// concurrent rename of the directory.
    #[inline]
    pub fn remove_open_dir_all(self) -> io::Result<()> {
        remove_open_dir_all(self.std_file)
    }

    /// Removes a file from a filesystem.
    ///
    /// This corresponds to [`std::fs::remove_file`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        remove_file(&self.std_file, path.as_ref())
    }

    /// Rename a file or directory to a new name, replacing the original file
    /// if to already exists.
    ///
    /// This corresponds to [`std::fs::rename`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        from: P,
        to_dir: &Self,
        to: Q,
    ) -> io::Result<()> {
        rename(&self.std_file, from.as_ref(), &to_dir.std_file, to.as_ref())
    }

    /// Changes the permissions found on a file or a directory.
    ///
    /// This corresponds to [`std::fs::set_permissions`], but only accesses
    /// paths relative to `self`. Also, on some platforms, this function
    /// may fail if the file or directory cannot be opened for reading or
    /// writing first.
    #[cfg(not(target_os = "wasi"))]
    #[inline]
    pub fn set_permissions<P: AsRef<Path>>(&self, path: P, perm: Permissions) -> io::Result<()> {
        set_permissions(&self.std_file, path.as_ref(), perm)
    }

    /// Query the metadata about a file without following symlinks.
    ///
    /// This corresponds to [`std::fs::symlink_metadata`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn symlink_metadata<P: AsRef<Path>>(&self, path: P) -> io::Result<Metadata> {
        stat(&self.std_file, path.as_ref(), FollowSymlinks::No)
    }

    /// Write a slice as the entire contents of a file.
    ///
    /// This corresponds to [`std::fs::write`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(&self, path: P, contents: C) -> io::Result<()> {
        let mut file = self.create(path)?;
        file.write_all(contents.as_ref())
    }

    /// Creates a new symbolic link on a filesystem.
    ///
    /// The `original` argument provides the target of the symlink. The `link`
    /// argument provides the name of the created symlink.
    ///
    /// Despite the argument ordering, `original` is not resolved relative to
    /// `self` here. `link` is resolved relative to `self`, and `original` is
    /// not resolved within this function.
    ///
    /// The `link` path is resolved when the symlink is dereferenced, relative
    /// to the directory that contains it.
    ///
    /// This corresponds to [`std::os::unix::fs::symlink`], but only accesses
    /// paths relative to `self`.
    ///
    /// [`std::os::unix::fs::symlink`]: https://doc.rust-lang.org/std/os/unix/fs/fn.symlink.html
    #[cfg(not(windows))]
    #[inline]
    pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(&self, original: P, link: Q) -> io::Result<()> {
        symlink(original.as_ref(), &self.std_file, link.as_ref())
    }

    /// Creates a new file symbolic link on a filesystem.
    ///
    /// The `original` argument provides the target of the symlink. The `link`
    /// argument provides the name of the created symlink.
    ///
    /// Despite the argument ordering, `original` is not resolved relative to
    /// `self` here. `link` is resolved relative to `self`, and `original` is
    /// not resolved within this function.
    ///
    /// The `link` path is resolved when the symlink is dereferenced, relative
    /// to the directory that contains it.
    ///
    /// This corresponds to [`std::os::windows::fs::symlink_file`], but only
    /// accesses paths relative to `self`.
    ///
    /// [`std::os::windows::fs::symlink_file`]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_file.html
    #[cfg(windows)]
    #[inline]
    pub fn symlink_file<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        original: P,
        link: Q,
    ) -> io::Result<()> {
        symlink_file(original.as_ref(), &self.std_file, link.as_ref())
    }

    /// Creates a new directory symlink on a filesystem.
    ///
    /// The `original` argument provides the target of the symlink. The `link`
    /// argument provides the name of the created symlink.
    ///
    /// Despite the argument ordering, `original` is not resolved relative to
    /// `self` here. `link` is resolved relative to `self`, and `original` is
    /// not resolved within this function.
    ///
    /// The `link` path is resolved when the symlink is dereferenced, relative
    /// to the directory that contains it.
    ///
    /// This corresponds to [`std::os::windows::fs::symlink_dir`], but only
    /// accesses paths relative to `self`.
    ///
    /// [`std::os::windows::fs::symlink_dir`]: https://doc.rust-lang.org/std/os/windows/fs/fn.symlink_dir.html
    #[cfg(windows)]
    #[inline]
    pub fn symlink_dir<P: AsRef<Path>, Q: AsRef<Path>>(
        &self,
        original: P,
        link: Q,
    ) -> io::Result<()> {
        symlink_dir(original.as_ref(), &self.std_file, link.as_ref())
    }

    /// Creates a new `UnixListener` bound to the specified socket.
    ///
    /// This corresponds to [`std::os::unix::net::UnixListener::bind`], but
    /// only accesses paths relative to `self`.
    ///
    /// XXX: This function is not yet implemented.
    ///
    /// [`std::os::unix::net::UnixListener::bind`]: https://doc.rust-lang.org/std/os/unix/net/struct.UnixListener.html#method.bind
    #[cfg(unix)]
    #[inline]
    pub fn bind_unix_listener<P: AsRef<Path>>(&self, path: P) -> io::Result<UnixListener> {
        todo!(
            "Dir::bind_unix_listener({:?}, {})",
            self.std_file,
            path.as_ref().display()
        )
    }

    /// Connects to the socket named by path.
    ///
    /// This corresponds to [`std::os::unix::net::UnixStream::connect`], but
    /// only accesses paths relative to `self`.
    ///
    /// XXX: This function is not yet implemented.
    ///
    /// [`std::os::unix::net::UnixStream::connect`]: https://doc.rust-lang.org/std/os/unix/net/struct.UnixStream.html#method.connect
    #[cfg(unix)]
    #[inline]
    pub fn connect_unix_stream<P: AsRef<Path>>(&self, path: P) -> io::Result<UnixStream> {
        todo!(
            "Dir::connect_unix_stream({:?}, {})",
            self.std_file,
            path.as_ref().display()
        )
    }

    /// Creates a Unix datagram socket bound to the given path.
    ///
    /// This corresponds to [`std::os::unix::net::UnixDatagram::bind`], but
    /// only accesses paths relative to `self`.
    ///
    /// XXX: This function is not yet implemented.
    ///
    /// [`std::os::unix::net::UnixDatagram::bind`]: https://doc.rust-lang.org/std/os/unix/net/struct.UnixDatagram.html#method.bind
    #[cfg(unix)]
    #[inline]
    pub fn bind_unix_datagram<P: AsRef<Path>>(&self, path: P) -> io::Result<UnixDatagram> {
        todo!(
            "Dir::bind_unix_datagram({:?}, {})",
            self.std_file,
            path.as_ref().display()
        )
    }

    /// Connects the socket to the specified address.
    ///
    /// This corresponds to [`std::os::unix::net::UnixDatagram::connect`], but
    /// only accesses paths relative to `self`.
    ///
    /// XXX: This function is not yet implemented.
    ///
    /// [`std::os::unix::net::UnixDatagram::connect`]: https://doc.rust-lang.org/std/os/unix/net/struct.UnixDatagram.html#method.connect
    #[cfg(unix)]
    #[inline]
    pub fn connect_unix_datagram<P: AsRef<Path>>(
        &self,
        _unix_datagram: &UnixDatagram,
        path: P,
    ) -> io::Result<()> {
        todo!(
            "Dir::connect_unix_datagram({:?}, {})",
            self.std_file,
            path.as_ref().display()
        )
    }

    /// Sends data on the socket to the specified address.
    ///
    /// This corresponds to [`std::os::unix::net::UnixDatagram::send_to`], but
    /// only accesses paths relative to `self`.
    ///
    /// XXX: This function is not yet implemented.
    ///
    /// [`std::os::unix::net::UnixDatagram::send_to`]: https://doc.rust-lang.org/std/os/unix/net/struct.UnixDatagram.html#method.send_to
    #[cfg(unix)]
    #[inline]
    pub fn send_to_unix_datagram_addr<P: AsRef<Path>>(
        &self,
        _unix_datagram: &UnixDatagram,
        buf: &[u8],
        path: P,
    ) -> io::Result<usize> {
        todo!(
            "Dir::send_to_unix_datagram_addr({:?}, {:?}, {})",
            self.std_file,
            buf,
            path.as_ref().display()
        )
    }

    /// Creates a new `Dir` instance that shares the same underlying file
    /// handle as the existing `Dir` instance.
    #[inline]
    pub fn try_clone(&self) -> io::Result<Self> {
        let dir = self.std_file.try_clone()?;
        Ok(Self::from_std_file(dir))
    }

    /// Returns `true` if the path points at an existing entity.
    ///
    /// This corresponds to [`std::path::Path::exists`], but only
    /// accesses paths relative to `self`.
    #[inline]
    pub fn exists<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).is_ok()
    }

    /// Returns `true` if the path points at an existing entity.
    ///
    /// This corresponds to [`std::fs::try_exists`], but only
    /// accesses paths relative to `self`.
    ///
    /// # API correspondence with `std`
    ///
    /// This API is not yet stable in `std`, but is likely to be. For more
    /// information, see the [tracker issue](https://github.com/rust-lang/rust/issues/83186).
    #[inline]
    pub fn try_exists<P: AsRef<Path>>(&self, path: P) -> io::Result<bool> {
        match self.metadata(path) {
            Ok(_) => Ok(true),
            Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false),
            Err(error) => Err(error),
        }
    }

    /// Returns `true` if the path exists on disk and is pointing at a regular
    /// file.
    ///
    /// This corresponds to [`std::path::Path::is_file`], but only
    /// accesses paths relative to `self`.
    #[inline]
    pub fn is_file<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).map(|m| m.is_file()).unwrap_or(false)
    }

    /// Checks if `path` is a directory.
    ///
    /// This is similar to [`std::path::Path::is_dir`] in that it checks if
    /// `path` relative to `Dir` is a directory. This function will
    /// traverse symbolic links to query information about the destination
    /// file. In case of broken symbolic links, this will return `false`.
    #[inline]
    pub fn is_dir<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).map(|m| m.is_dir()).unwrap_or(false)
    }

    /// Constructs a new instance of `Self` by opening the given path as a
    /// directory using the host process' ambient authority.
    ///
    /// # Ambient Authority
    ///
    /// This function is not sandboxed and may access any path that the host
    /// process has access to.
    #[inline]
    pub fn open_ambient_dir<P: AsRef<Path>>(
        path: P,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let dir = open_ambient_dir(path.as_ref(), ambient_authority)?;
        Ok(Self::from_std_file(dir))
    }

    /// Constructs a new instance of `Self` by opening the parent directory
    /// (aka "..") of `self`, using the host process' ambient authority.
    ///
    /// # Ambient Authority
    ///
    /// This function accesses a directory outside of the `self` subtree.
    #[inline]
    pub fn open_parent_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Self> {
        let dir = open_parent_dir(&self.std_file, ambient_authority)?;
        Ok(Self::from_std_file(dir))
    }

    /// Recursively create a directory and all of its parent components if they
    /// are missing, using the host process' ambient authority.
    ///
    /// # Ambient Authority
    ///
    /// This function is not sandboxed and may access any path that the host
    /// process has access to.
    #[inline]
    pub fn create_ambient_dir_all<P: AsRef<Path>>(
        path: P,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<()> {
        let _ = ambient_authority;
        fs::create_dir_all(path)
    }

    /// Construct a new instance of `Self` from existing directory file
    /// descriptor.
    ///
    /// This can be useful when interacting with other libraries and or C/C++
    /// code which has invoked `openat(..., O_DIRECTORY)` external to this
    /// crate.
    pub fn reopen_dir<Filelike: AsFilelike>(dir: &Filelike) -> io::Result<Self> {
        cap_primitives::fs::open_dir(
            &dir.as_filelike_view::<std::fs::File>(),
            std::path::Component::CurDir.as_ref(),
        )
        .map(Self::from_std_file)
    }
}

// Safety: `FilelikeViewType` is implemented for `std::fs::File`.
unsafe impl io_lifetimes::views::FilelikeViewType for Dir {}

#[cfg(not(windows))]
impl FromRawFd for Dir {
    #[inline]
    unsafe fn from_raw_fd(fd: RawFd) -> Self {
        Self::from_std_file(fs::File::from_raw_fd(fd))
    }
}

#[cfg(not(windows))]
impl From<OwnedFd> for Dir {
    #[inline]
    fn from(fd: OwnedFd) -> Self {
        Self::from_std_file(fs::File::from(fd))
    }

pub fn into_std_file(self) -> File

Consumes self and returns a std::fs::File.

pub fn open<P: AsRef<Path>>(&self, path: P) -> Result<File>

Attempts to open a file in read-only mode.

This corresponds to std::fs::File::open, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 63)

    pub fn open<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<File> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.open(path).map(File::from_cap_std)
    }

src/fs/dir.rs (line 278)

    pub fn read<P: AsRef<Path>>(&self, path: P) -> io::Result<Vec<u8>> {
        let mut file = self.open(path)?;
        let mut bytes = Vec::with_capacity(initial_buffer_size(&file));
        file.read_to_end(&mut bytes)?;
        Ok(bytes)
    }

    /// Reads a symbolic link, returning the file that the link points to.
    ///
    /// This corresponds to [`std::fs::read_link`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf> {
        read_link(&self.std_file, path.as_ref())
    }

    /// Read the entire contents of a file into a string.
    ///
    /// This corresponds to [`std::fs::read_to_string`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn read_to_string<P: AsRef<Path>>(&self, path: P) -> io::Result<String> {
        let mut s = String::new();
        self.open(path)?.read_to_string(&mut s)?;
        Ok(s)
    }

pub fn open_with<P: AsRef<Path>>(
    &self,
    path: P,
    options: &OpenOptions
) -> Result<File>

Opens a file at path with the options specified by options.

This corresponds to std::fs::OpenOptions::open.

Instead of being a method on OpenOptions, this is a method on Dir, and it only accesses paths relative to self.

Examples found in repository

src/fs/dir.rs (line 76)

    pub fn open<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
        self.open_with(path, OpenOptions::new().read(true))
    }

    /// Opens a file at `path` with the options specified by `options`.
    ///
    /// This corresponds to [`std::fs::OpenOptions::open`].
    ///
    /// Instead of being a method on `OpenOptions`, this is a method on `Dir`,
    /// and it only accesses paths relative to `self`.
    #[inline]
    pub fn open_with<P: AsRef<Path>>(&self, path: P, options: &OpenOptions) -> io::Result<File> {
        self._open_with(path.as_ref(), options)
    }

    #[cfg(not(target_os = "wasi"))]
    #[inline]
    fn _open_with(&self, path: &Path, options: &OpenOptions) -> io::Result<File> {
        let dir = open(&self.std_file, path, options)?;
        Ok(File::from_std(dir))
    }

    #[cfg(target_os = "wasi")]
    #[inline]
    fn _open_with(&self, path: &Path, options: &OpenOptions) -> io::Result<File> {
        let dir = options.open_at(&self.std_file, path)?;
        Ok(File::from_std(dir))
    }

    /// Attempts to open a directory.
    #[inline]
    pub fn open_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<Self> {
        let dir = open_dir(&self.std_file, path.as_ref())?;
        Ok(Self::from_std_file(dir))
    }

    /// Creates a new, empty directory at the provided path.
    ///
    /// This corresponds to [`std::fs::create_dir`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create_dir_one(path.as_ref(), &DirOptions::new())
    }

    /// Recursively create a directory and all of its parent components if they
    /// are missing.
    ///
    /// This corresponds to [`std::fs::create_dir_all`], but only accesses
    /// paths relative to `self`.
    #[inline]
    pub fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
        self._create_dir_all(path.as_ref(), &DirOptions::new())
    }

    /// Creates the specified directory with the options configured in this
    /// builder.
    ///
    /// This corresponds to [`std::fs::DirBuilder::create`].
    #[cfg(not(target_os = "wasi"))]
    #[inline]
    pub fn create_dir_with<P: AsRef<Path>>(
        &self,
        path: P,
        dir_builder: &DirBuilder,
    ) -> io::Result<()> {
        let options = dir_builder.options();
        if dir_builder.is_recursive() {
            self._create_dir_all(path.as_ref(), options)
        } else {
            self._create_dir_one(path.as_ref(), options)
        }
    }

    fn _create_dir_one(&self, path: &Path, dir_options: &DirOptions) -> io::Result<()> {
        create_dir(&self.std_file, path, dir_options)
    }

    fn _create_dir_all(&self, path: &Path, dir_options: &DirOptions) -> io::Result<()> {
        if path == Path::new("") {
            return Ok(());
        }

        match self._create_dir_one(path, dir_options) {
            Ok(()) => return Ok(()),
            Err(ref e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(_) if self.is_dir(path) => return Ok(()),
            Err(e) => return Err(e),
        }
        match path.parent() {
            Some(p) => self._create_dir_all(p, dir_options)?,
            None => {
                return Err(io::Error::new(
                    io::ErrorKind::Other,
                    "failed to create whole tree",
                ))
            }
        }
        match self._create_dir_one(path, dir_options) {
            Ok(()) => Ok(()),
            Err(_) if self.is_dir(path) => Ok(()),
            Err(e) => Err(e),
        }
    }

    /// Opens a file in write-only mode.
    ///
    /// This corresponds to [`std::fs::File::create`], but only accesses paths
    /// relative to `self`.
    #[inline]
    pub fn create<P: AsRef<Path>>(&self, path: P) -> io::Result<File> {
        self.open_with(
            path,
            OpenOptions::new().write(true).create(true).truncate(true),
        )
    }

src/fs_utf8/dir.rs (line 80)

    pub fn open_with<P: AsRef<Utf8Path>>(
        &self,
        path: P,
        options: &OpenOptions,
    ) -> io::Result<File> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std
            .open_with(path, options)
            .map(File::from_cap_std)
    }

pub fn open_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self>

Attempts to open a directory.

Examples found in repository

src/fs_utf8/dir.rs (line 88)

    pub fn open_dir<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Self> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.open_dir(path).map(Self::from_cap_std)
    }

pub fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

Creates a new, empty directory at the provided path.

This corresponds to std::fs::create_dir, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 98)

    pub fn create_dir<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.create_dir(path)
    }

pub fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>

Recursively create a directory and all of its parent components if they are missing.

This corresponds to std::fs::create_dir_all, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 109)

    pub fn create_dir_all<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.create_dir_all(path)
    }

pub fn create_dir_with<P: AsRef<Path>>(
    &self,
    path: P,
    dir_builder: &DirBuilder
) -> Result<()>

Available on non-WASI only.

Creates the specified directory with the options configured in this builder.

This corresponds to std::fs::DirBuilder::create.

Examples found in repository

src/fs_utf8/dir.rs (line 124)

    pub fn create_dir_with<P: AsRef<Utf8Path>>(
        &self,
        path: P,
        dir_builder: &DirBuilder,
    ) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.create_dir_with(path, dir_builder)
    }

pub fn create<P: AsRef<Path>>(&self, path: P) -> Result<File>

Opens a file in write-only mode.

This corresponds to std::fs::File::create, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 134)

    pub fn create<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<File> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.create(path).map(File::from_cap_std)
    }

src/fs/dir.rs (line 395)

    pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(&self, path: P, contents: C) -> io::Result<()> {
        let mut file = self.create(path)?;
        file.write_all(contents.as_ref())
    }

pub fn canonicalize<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Returns the canonical form of a path with all intermediate components normalized and symbolic links resolved.

This corresponds to std::fs::canonicalize, but instead of returning an absolute path, returns a path relative to the directory represented by self.

Examples found in repository

src/fs_utf8/dir.rs (line 146)

    pub fn canonicalize<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Utf8PathBuf> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.canonicalize(path).and_then(to_utf8)
    }

pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
    &self,
    from: P,
    to_dir: &Self,
    to: Q
) -> Result<u64>

Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.

This corresponds to std::fs::copy, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 164)

    pub fn copy<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
        &self,
        from: P,
        to_dir: &Self,
        to: Q,
    ) -> io::Result<u64> {
        let from = from_utf8(from.as_ref())?;
        let to = from_utf8(to.as_ref())?;
        self.cap_std.copy(from, &to_dir.cap_std, to)
    }

pub fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(
    &self,
    src: P,
    dst_dir: &Self,
    dst: Q
) -> Result<()>

Creates a new hard link on a filesystem.

This corresponds to std::fs::hard_link, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 180)

    pub fn hard_link<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
        &self,
        src: P,
        dst_dir: &Self,
        dst: Q,
    ) -> io::Result<()> {
        let src = from_utf8(src.as_ref())?;
        let dst = from_utf8(dst.as_ref())?;
        self.cap_std.hard_link(src, &dst_dir.cap_std, dst)
    }

pub fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Metadata>

Given a path, query the file system to get information about a file, directory, etc.

This corresponds to std::fs::metadata, but only accesses paths relative to self.

Examples found in repository

src/fs/dir.rs (line 587)

    pub fn exists<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).is_ok()
    }

    /// Returns `true` if the path points at an existing entity.
    ///
    /// This corresponds to [`std::fs::try_exists`], but only
    /// accesses paths relative to `self`.
    ///
    /// # API correspondence with `std`
    ///
    /// This API is not yet stable in `std`, but is likely to be. For more
    /// information, see the [tracker issue](https://github.com/rust-lang/rust/issues/83186).
    #[inline]
    pub fn try_exists<P: AsRef<Path>>(&self, path: P) -> io::Result<bool> {
        match self.metadata(path) {
            Ok(_) => Ok(true),
            Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false),
            Err(error) => Err(error),
        }
    }

    /// Returns `true` if the path exists on disk and is pointing at a regular
    /// file.
    ///
    /// This corresponds to [`std::path::Path::is_file`], but only
    /// accesses paths relative to `self`.
    #[inline]
    pub fn is_file<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).map(|m| m.is_file()).unwrap_or(false)
    }

    /// Checks if `path` is a directory.
    ///
    /// This is similar to [`std::path::Path::is_dir`] in that it checks if
    /// `path` relative to `Dir` is a directory. This function will
    /// traverse symbolic links to query information about the destination
    /// file. In case of broken symbolic links, this will return `false`.
    #[inline]
    pub fn is_dir<P: AsRef<Path>>(&self, path: P) -> bool {
        self.metadata(path).map(|m| m.is_dir()).unwrap_or(false)
    }

src/fs_utf8/dir.rs (line 191)

    pub fn metadata<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Metadata> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.metadata(path)
    }

pub fn dir_metadata(&self) -> Result<Metadata>

Queries metadata about the underlying directory.

This is similar to std::fs::File::metadata, but for Dir rather than for File.

pub fn entries(&self) -> Result<ReadDir>

Returns an iterator over the entries within self.

Examples found in repository

src/fs_utf8/dir.rs (line 197)

    pub fn entries(&self) -> io::Result<ReadDir> {
        self.cap_std.entries().map(ReadDir::from_cap_std)
    }

pub fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<ReadDir>

Returns an iterator over the entries within a directory.

This corresponds to std::fs::read_dir, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 207)

    pub fn read_dir<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<ReadDir> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.read_dir(path).map(ReadDir::from_cap_std)
    }

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

Read the entire contents of a file into a bytes vector.

This corresponds to std::fs::read, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 217)

    pub fn read<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Vec<u8>> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.read(path)
    }

pub fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Reads a symbolic link, returning the file that the link points to.

This corresponds to std::fs::read_link, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 227)

    pub fn read_link<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Utf8PathBuf> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.read_link(path).and_then(to_utf8)
    }

pub fn read_to_string<P: AsRef<Path>>(&self, path: P) -> Result<String>

Read the entire contents of a file into a string.

This corresponds to std::fs::read_to_string, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 237)

    pub fn read_to_string<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<String> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.read_to_string(path)
    }

pub fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes an empty directory.

This corresponds to std::fs::remove_dir, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 247)

    pub fn remove_dir<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.remove_dir(path)
    }

pub fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes a directory at this path, after removing all its contents. Use carefully!

This corresponds to std::fs::remove_dir_all, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 258)

    pub fn remove_dir_all<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.remove_dir_all(path)
    }

pub fn remove_open_dir(self) -> Result<()>

Remove the directory referenced by self and consume self.

Even though this implementation works in terms of handles as much as possible, removal is not guaranteed to be atomic with respect to a concurrent rename of the directory.

Examples found in repository

src/fs_utf8/dir.rs (line 268)

    pub fn remove_open_dir(self) -> io::Result<()> {
        self.cap_std.remove_open_dir()
    }

pub fn remove_open_dir_all(self) -> Result<()>

Removes the directory referenced by self, after removing all its contents, and consume self. Use carefully!

Even though this implementation works in terms of handles as much as possible, removal is not guaranteed to be atomic with respect to a concurrent rename of the directory.

Examples found in repository

src/fs_utf8/dir.rs (line 279)

    pub fn remove_open_dir_all(self) -> io::Result<()> {
        self.cap_std.remove_open_dir_all()
    }

pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>

Removes a file from a filesystem.

This corresponds to std::fs::remove_file, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 289)

    pub fn remove_file<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.remove_file(path)
    }

pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
    &self,
    from: P,
    to_dir: &Self,
    to: Q
) -> Result<()>

Rename a file or directory to a new name, replacing the original file if to already exists.

This corresponds to std::fs::rename, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 306)

    pub fn rename<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
        &self,
        from: P,
        to_dir: &Self,
        to: Q,
    ) -> io::Result<()> {
        let from = from_utf8(from.as_ref())?;
        let to = from_utf8(to.as_ref())?;
        self.cap_std.rename(from, &to_dir.cap_std, to)
    }

pub fn set_permissions<P: AsRef<Path>>(
    &self,
    path: P,
    perm: Permissions
) -> Result<()>

Available on non-WASI only.

Changes the permissions found on a file or a directory.

This corresponds to std::fs::set_permissions, but only accesses paths relative to self. Also, on some platforms, this function may fail if the file or directory cannot be opened for reading or writing first.

Examples found in repository

src/fs_utf8/dir.rs (line 322)

    pub fn set_permissions<P: AsRef<Utf8Path>>(
        &self,
        path: P,
        perm: Permissions,
    ) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.set_permissions(path, perm)
    }

pub fn symlink_metadata<P: AsRef<Path>>(&self, path: P) -> Result<Metadata>

Query the metadata about a file without following symlinks.

This corresponds to std::fs::symlink_metadata, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 332)

    pub fn symlink_metadata<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<Metadata> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.symlink_metadata(path)
    }

pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(
    &self,
    path: P,
    contents: C
) -> Result<()>

Write a slice as the entire contents of a file.

This corresponds to std::fs::write, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 346)

    pub fn write<P: AsRef<Utf8Path>, C: AsRef<[u8]>>(
        &self,
        path: P,
        contents: C,
    ) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.write(path, contents)
    }

pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(
    &self,
    original: P,
    link: Q
) -> Result<()>

Available on non-Windows only.

Creates a new symbolic link on a filesystem.

The original argument provides the target of the symlink. The link argument provides the name of the created symlink.

Despite the argument ordering, original is not resolved relative to self here. link is resolved relative to self, and original is not resolved within this function.

The link path is resolved when the symlink is dereferenced, relative to the directory that contains it.

This corresponds to std::os::unix::fs::symlink, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 374)

    pub fn symlink<P: AsRef<Utf8Path>, Q: AsRef<Utf8Path>>(
        &self,
        original: P,
        link: Q,
    ) -> io::Result<()> {
        let original = from_utf8(original.as_ref())?;
        let link = from_utf8(link.as_ref())?;
        self.cap_std.symlink(original, link)
    }

pub fn bind_unix_listener<P: AsRef<Path>>(&self, path: P) -> Result<UnixListener>

Available on Unix only.

Creates a new UnixListener bound to the specified socket.

This corresponds to std::os::unix::net::UnixListener::bind, but only accesses paths relative to self.

XXX: This function is not yet implemented.

Examples found in repository

src/fs_utf8/dir.rs (line 445)

    pub fn bind_unix_listener<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<UnixListener> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.bind_unix_listener(path)
    }

pub fn connect_unix_stream<P: AsRef<Path>>(&self, path: P) -> Result<UnixStream>

Available on Unix only.

Connects to the socket named by path.

This corresponds to std::os::unix::net::UnixStream::connect, but only accesses paths relative to self.

XXX: This function is not yet implemented.

Examples found in repository

src/fs_utf8/dir.rs (line 460)

    pub fn connect_unix_stream<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<UnixStream> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.connect_unix_stream(path)
    }

pub fn bind_unix_datagram<P: AsRef<Path>>(&self, path: P) -> Result<UnixDatagram>

Available on Unix only.

Creates a Unix datagram socket bound to the given path.

This corresponds to std::os::unix::net::UnixDatagram::bind, but only accesses paths relative to self.

XXX: This function is not yet implemented.

Examples found in repository

src/fs_utf8/dir.rs (line 475)

    pub fn bind_unix_datagram<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<UnixDatagram> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.bind_unix_datagram(path)
    }

pub fn connect_unix_datagram<P: AsRef<Path>>(
    &self,
    _unix_datagram: &UnixDatagram,
    path: P
) -> Result<()>

Available on Unix only.

Connects the socket to the specified address.

This corresponds to std::os::unix::net::UnixDatagram::connect, but only accesses paths relative to self.

XXX: This function is not yet implemented.

Examples found in repository

src/fs_utf8/dir.rs (line 494)

    pub fn connect_unix_datagram<P: AsRef<Utf8Path>>(
        &self,
        unix_datagram: &UnixDatagram,
        path: P,
    ) -> io::Result<()> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std.connect_unix_datagram(unix_datagram, path)
    }

pub fn send_to_unix_datagram_addr<P: AsRef<Path>>(
    &self,
    _unix_datagram: &UnixDatagram,
    buf: &[u8],
    path: P
) -> Result<usize>

Available on Unix only.

Sends data on the socket to the specified address.

This corresponds to std::os::unix::net::UnixDatagram::send_to, but only accesses paths relative to self.

XXX: This function is not yet implemented.

Examples found in repository

src/fs_utf8/dir.rs (line 515)

    pub fn send_to_unix_datagram_addr<P: AsRef<Utf8Path>>(
        &self,
        unix_datagram: &UnixDatagram,
        buf: &[u8],
        path: P,
    ) -> io::Result<usize> {
        let path = from_utf8(path.as_ref())?;
        self.cap_std
            .send_to_unix_datagram_addr(unix_datagram, buf, path)
    }

pub fn try_clone(&self) -> Result<Self>

Creates a new Dir instance that shares the same underlying file handle as the existing Dir instance.

Examples found in repository

src/fs_utf8/dir.rs (line 523)

    pub fn try_clone(&self) -> io::Result<Self> {
        Ok(Self {
            cap_std: self.cap_std.try_clone()?,
        })
    }

pub fn exists<P: AsRef<Path>>(&self, path: P) -> bool

Returns true if the path points at an existing entity.

This corresponds to std::path::Path::exists, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 534)

    pub fn exists<P: AsRef<Utf8Path>>(&self, path: P) -> bool {
        match from_utf8(path.as_ref()) {
            Ok(path) => self.cap_std.exists(path),
            Err(_) => false,
        }
    }

pub fn try_exists<P: AsRef<Path>>(&self, path: P) -> Result<bool>

Returns true if the path points at an existing entity.

This corresponds to std::fs::try_exists, but only accesses paths relative to self.

API correspondence with std

This API is not yet stable in std, but is likely to be. For more information, see the tracker issue.

Examples found in repository

src/fs_utf8/dir.rs (line 545)

    pub fn try_exists<P: AsRef<Utf8Path>>(&self, path: P) -> io::Result<bool> {
        self.cap_std.try_exists(from_utf8(path.as_ref())?)
    }

pub fn is_file<P: AsRef<Path>>(&self, path: P) -> bool

Returns true if the path exists on disk and is pointing at a regular file.

This corresponds to std::path::Path::is_file, but only accesses paths relative to self.

Examples found in repository

src/fs_utf8/dir.rs (line 556)

    pub fn is_file<P: AsRef<Utf8Path>>(&self, path: P) -> bool {
        match from_utf8(path.as_ref()) {
            Ok(path) => self.cap_std.is_file(path),
            Err(_) => false,
        }
    }

pub fn is_dir<P: AsRef<Path>>(&self, path: P) -> bool

Checks if path is a directory.

This is similar to std::path::Path::is_dir in that it checks if path relative to Dir is a directory. This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links, this will return false.

Examples found in repository

src/fs_utf8/dir.rs (line 570)

    pub fn is_dir<P: AsRef<Utf8Path>>(&self, path: P) -> bool {
        match from_utf8(path.as_ref()) {
            Ok(path) => self.cap_std.is_dir(path),
            Err(_) => false,
        }
    }

src/fs/dir.rs (line 161)

    fn _create_dir_all(&self, path: &Path, dir_options: &DirOptions) -> io::Result<()> {
        if path == Path::new("") {
            return Ok(());
        }

        match self._create_dir_one(path, dir_options) {
            Ok(()) => return Ok(()),
            Err(ref e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(_) if self.is_dir(path) => return Ok(()),
            Err(e) => return Err(e),
        }
        match path.parent() {
            Some(p) => self._create_dir_all(p, dir_options)?,
            None => {
                return Err(io::Error::new(
                    io::ErrorKind::Other,
                    "failed to create whole tree",
                ))
            }
        }
        match self._create_dir_one(path, dir_options) {
            Ok(()) => Ok(()),
            Err(_) if self.is_dir(path) => Ok(()),
            Err(e) => Err(e),
        }
    }

pub fn open_ambient_dir<P: AsRef<Path>>(
    path: P,
    ambient_authority: AmbientAuthority
) -> Result<Self>

Constructs a new instance of Self by opening the given path as a directory using the host process’ ambient authority.

Ambient Authority

This function is not sandboxed and may access any path that the host process has access to.

Examples found in repository

src/fs_utf8/dir.rs (line 588)

    pub fn open_ambient_dir<P: AsRef<Utf8Path>>(
        path: P,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let path = from_utf8(path.as_ref())?;
        crate::fs::Dir::open_ambient_dir(path, ambient_authority).map(Self::from_cap_std)
    }

pub fn open_parent_dir(
    &self,
    ambient_authority: AmbientAuthority
) -> Result<Self>

Constructs a new instance of Self by opening the parent directory (aka “..”) of self, using the host process’ ambient authority.

Ambient Authority

This function accesses a directory outside of the self subtree.

Examples found in repository

src/fs_utf8/dir.rs (line 603)

    pub fn open_parent_dir<P: AsRef<Utf8Path>>(
        &self,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        self.cap_std
            .open_parent_dir(ambient_authority)
            .map(Self::from_cap_std)
    }

pub fn create_ambient_dir_all<P: AsRef<Path>>(
    path: P,
    ambient_authority: AmbientAuthority
) -> Result<()>

Recursively create a directory and all of its parent components if they are missing, using the host process’ ambient authority.

Ambient Authority

This function is not sandboxed and may access any path that the host process has access to.

pub fn reopen_dir<Filelike: AsFilelike>(dir: &Filelike) -> Result<Self>

Construct a new instance of Self from existing directory file descriptor.

This can be useful when interacting with other libraries and or C/C++ code which has invoked openat(..., O_DIRECTORY) external to this crate.

Trait Implementations

impl AsFd for Dir

Available on non-Windows only.

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for Dir

Available on non-Windows only.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Dir

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

Formats the value using the given formatter.

impl From<Dir> for OwnedFd

Available on non-Windows only.

fn from(dir: Dir) -> OwnedFd

Converts to this type from the input type.

impl From<OwnedFd> for Dir

Available on non-Windows only.

fn from(fd: OwnedFd) -> Self

Converts to this type from the input type.

impl FromRawFd for Dir

Available on non-Windows only.

unsafe fn from_raw_fd(fd: RawFd) -> Self

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for Dir

Available on non-Windows only.

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl FilelikeViewType for Dir