Struct Dir

pub struct Dir { /* private fields */ }

A reference to an open directory on a filesystem.

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

Unlike async_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 async_std::fs::File.

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

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

pub fn into_std_file(self) -> File

Consumes self and returns an async_std::fs::File.

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

Attempts to open a file in read-only mode.

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

pub async 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 async_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.

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

Attempts to open a directory.

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

Creates a new, empty directory at the provided path.

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

TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51

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 async_std::fs::create_dir_all, but only accesses paths relative to self.

TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51

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

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

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

TODO: async: fix this when we fix https://github.com/bytecodealliance/cap-std/issues/51

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

Opens a file in write-only mode.

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

pub async 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 async_std::fs::canonicalize, but instead of returning an absolute path, returns a path relative to the directory represented by self.

pub async 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 async_std::fs::copy, but only accesses paths relative to self.

pub async 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 async_std::fs::hard_link, but only accesses paths relative to self.

pub async 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 async_std::fs::metadata, but only accesses paths relative to self.

pub async 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 async fn entries(&self) -> Result<ReadDir>

Returns an iterator over the entries within self.

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

Returns an iterator over the entries within a directory.

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

pub async 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 async_std::fs::read, but only accesses paths relative to self.

pub async 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 async_std::fs::read_link, but only accesses paths relative to self.

pub async 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 async_std::fs::read_to_string, but only accesses paths relative to self.

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

Removes an empty directory.

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

pub async 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 async_std::fs::remove_dir_all, but only accesses paths relative to self.

pub async 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.

pub async 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.

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

Removes a file from a filesystem.

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

pub async 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 async_std::fs::rename, but only accesses paths relative to self.

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

Changes the permissions found on a file or a directory.

This corresponds to async_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.

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

Query the metadata about a file without following symlinks.

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

pub async 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 async_std::fs::write, but only accesses paths relative to self.

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

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 async_std::os::unix::fs::symlink, but only accesses paths relative to self.

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

Creates a new UnixListener bound to the specified socket.

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

XXX: This function is not yet implemented.

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

Connects to the socket named by path.

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

XXX: This function is not yet implemented.

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

Creates a Unix datagram socket bound to the given path.

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

XXX: This function is not yet implemented.

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

Connects the socket to the specified address.

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

XXX: This function is not yet implemented.

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

Sends data on the socket to the specified address.

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

XXX: This function is not yet implemented.

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

Returns true if the path points at an existing entity.

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

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

Returns true if the path points at an existing entity.

This is an asynchronous version of [std::fs::try_exists], and also only accesses paths relative to self.

NOTE: This API is not yet part of async_std.

pub async 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 async_std::path::Path::is_file, but only accesses paths relative to self.

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

Checks if path is a directory.

This is similar to async_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.

pub async 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.

pub async 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.

pub async 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 async fn reopen_dir<Filelike: AsFilelike + Send>( 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

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

Borrows the file descriptor.

impl AsRawFd for Dir

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for Dir

fn clone(&self) -> Dir

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Dir

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

Formats the value using the given formatter.

impl From<Dir> for OwnedFd

fn from(dir: Dir) -> OwnedFd

Converts to this type from the input type.

impl From<OwnedFd> for Dir

fn from(fd: OwnedFd) -> Self

Converts to this type from the input type.

impl FromRawFd for Dir

unsafe fn from_raw_fd(fd: RawFd) -> Self

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

impl IntoRawFd for Dir

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.

impl FilelikeViewType for Dir