Struct Dir

pub struct Dir { /* private fields */ }

Available on crate feature sync only.

Expand description

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) -> Dir

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.

pub fn into_std_file(self) -> File

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

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

Attempts to open a file in read-only mode.

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

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

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.

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

Attempts to open a directory.

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

Creates a new, empty directory at the provided path.

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

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

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.

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

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

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

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

Opens a file in write-only mode.

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

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

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.

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

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.

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

Creates a new hard link on a filesystem.

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

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

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.

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

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, Error>

Returns an iterator over the entries within self.

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

Returns an iterator over the entries within a directory.

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

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

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

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

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

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. Unlike [read_link_contents], this method considers it an error if the link’s target is an absolute path.

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

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.

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

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.

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

Removes an empty directory.

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

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

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.

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

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 fn remove_open_dir_all(self) -> Result<(), Error>

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 fn remove_file(&self, path: P) -> Result<(), Error>
where P: AsRef<Path>,

Removes a file from a filesystem.

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

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

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.

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

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.

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

Query the metadata about a file without following symlinks.

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

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

Write a slice as the entire contents of a file.

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

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

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.

Unlike [symlink_contents] this method will return an error if original is an absolute path.

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

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.