Trait CapStdExtDirExt

pub trait CapStdExtDirExt {
    // Required methods
    fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>;
    fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>;
    fn open_dir_rooted_ext(&self, path: impl AsRef<Path>) -> Result<RootDir>;
    fn open_dir_noxdev(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>;
    fn ensure_dir_with(
        &self,
        p: impl AsRef<Path>,
        builder: &DirBuilder,
    ) -> Result<bool>;
    fn metadata_optional(
        &self,
        path: impl AsRef<Path>,
    ) -> Result<Option<Metadata>>;
    fn symlink_metadata_optional(
        &self,
        path: impl AsRef<Path>,
    ) -> Result<Option<Metadata>>;
    fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>;
    fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>;
    fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>;
    fn atomic_replace_with<F, T, E>(
        &self,
        destname: impl AsRef<Path>,
        f: F,
    ) -> Result<T, E>
       where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>,
             E: From<Error>;
    fn atomic_write(
        &self,
        destname: impl AsRef<Path>,
        contents: impl AsRef<[u8]>,
    ) -> Result<()>;
    fn atomic_write_with_perms(
        &self,
        destname: impl AsRef<Path>,
        contents: impl AsRef<[u8]>,
        perms: Permissions,
    ) -> Result<()>;
    fn reopen_as_ownedfd(&self) -> Result<OwnedFd>;
    fn is_mountpoint(&self, path: impl AsRef<Path>) -> Result<Option<bool>>;
    fn walk<C, E>(
        &self,
        config: &WalkConfiguration<'_>,
        callback: C,
    ) -> Result<(), E>
       where C: FnMut(&WalkComponent<'_, '_>) -> WalkResult<E>,
             E: From<Error>;
}

Extension trait for cap_std::fs::Dir.

Required Methods

fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>

Open a file read-only, but return Ok(None) if it does not exist.

fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

Open a directory, but return Ok(None) if it does not exist.

fn open_dir_rooted_ext(&self, path: impl AsRef<Path>) -> Result<RootDir>

Create a special variant of cap_std::fs::Dir which uses RESOLVE_IN_ROOT to support absolute symlinks.

fn open_dir_noxdev(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

Open the target directory, but return Ok(None) if this would cross a mount point.

fn ensure_dir_with( &self, p: impl AsRef<Path>, builder: &DirBuilder, ) -> Result<bool>

Create the target directory, but do nothing if a directory already exists at that path. The return value will be true if the directory was created. An error will be returned if the path is a non-directory. Symbolic links will be followed.

fn metadata_optional(&self, path: impl AsRef<Path>) -> Result<Option<Metadata>>

Gather metadata, but return Ok(None) if it does not exist.

fn symlink_metadata_optional( &self, path: impl AsRef<Path>, ) -> Result<Option<Metadata>>

Gather metadata (but do not follow symlinks), but return Ok(None) if it does not exist.

fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>

Remove (delete) a file, but return Ok(false) if the file does not exist.

fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>

Remove a file or directory but return Ok(false) if the file does not exist. Symbolic links are not followed.

fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>

Set the access and modification times to the current time. Symbolic links are not followed.

fn atomic_replace_with<F, T, E>( &self, destname: impl AsRef<Path>, f: F, ) -> Result<T, E>

where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>, E: From<Error>,

Atomically write a file by calling the provided closure.

This uses cap_tempfile::TempFile, which is wrapped in a std::io::BufWriter and passed to the closure.

Existing files and metadata

If the target path already exists and is a regular file (not a symbolic link or directory), then its access permissions (Unix mode) will be preserved. However, other metadata such as extended attributes will not be preserved automatically. To do this will require a higher level wrapper which queries the existing file and gathers such metadata before replacement.

Example, including setting permissions

The closure may also perform other file operations beyond writing, such as changing file permissions:

use cap_std_ext::prelude::*;
let contents = b"hello world\n";
somedir.atomic_replace_with("somefilename", |f| -> io::Result<_> {
    f.write_all(contents)?;
    f.flush()?;
    use cap_std::fs::PermissionsExt;
    let perms = cap_std::fs::Permissions::from_mode(0o600);
    f.get_mut().as_file_mut().set_permissions(perms)?;
    Ok(())
})

Any existing file will be replaced.

fn atomic_write( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, ) -> Result<()>

Atomically write the provided contents to a file.

fn atomic_write_with_perms( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, perms: Permissions, ) -> Result<()>

Atomically write the provided contents to a file, using specified permissions.

fn reopen_as_ownedfd(&self) -> Result<OwnedFd>

By default, cap-std Dir instances are opened using O_PATH. There are some operations such as fsync and fsetxattr that cannot be performed on O_PATH file descriptors. Use this function to create a non-O_PATH copy of the directory file descriptor.

fn is_mountpoint(&self, path: impl AsRef<Path>) -> Result<Option<bool>>

Returns Some(true) if the target is known to be a mountpoint, or Some(false) if the target is definitively known not to be a mountpoint.

In some scenarios (such as an older kernel) this currently may not be possible to determine, and None will be returned in those cases.

fn walk<C, E>( &self, config: &WalkConfiguration<'_>, callback: C, ) -> Result<(), E>

where C: FnMut(&WalkComponent<'_, '_>) -> WalkResult<E>, E: From<Error>,

Recursively walk a directory. If the function returns std::ops::ControlFlow::Break while inspecting a directory, traversal of that directory is skipped. If std::ops::ControlFlow::Break is returned when inspecting a non-directory, then all further entries in the directory are skipped.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl CapStdExtDirExt for Dir

fn open_dir_noxdev(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

Open the target directory, but return Ok(None) if this would cross a mount point.

fn open_optional(&self, path: impl AsRef<Path>) -> Result<Option<File>>

fn open_dir_optional(&self, path: impl AsRef<Path>) -> Result<Option<Dir>>

fn open_dir_rooted_ext(&self, path: impl AsRef<Path>) -> Result<RootDir>

fn ensure_dir_with( &self, p: impl AsRef<Path>, builder: &DirBuilder, ) -> Result<bool>

fn metadata_optional(&self, path: impl AsRef<Path>) -> Result<Option<Metadata>>

fn symlink_metadata_optional( &self, path: impl AsRef<Path>, ) -> Result<Option<Metadata>>

fn remove_file_optional(&self, path: impl AsRef<Path>) -> Result<bool>

fn remove_all_optional(&self, path: impl AsRef<Path>) -> Result<bool>

fn update_timestamps(&self, path: impl AsRef<Path>) -> Result<()>

fn atomic_replace_with<F, T, E>( &self, destname: impl AsRef<Path>, f: F, ) -> Result<T, E>

where F: FnOnce(&mut BufWriter<TempFile<'_>>) -> Result<T, E>, E: From<Error>,

fn atomic_write( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, ) -> Result<()>

fn atomic_write_with_perms( &self, destname: impl AsRef<Path>, contents: impl AsRef<[u8]>, perms: Permissions, ) -> Result<()>

fn reopen_as_ownedfd(&self) -> Result<OwnedFd>

fn is_mountpoint(&self, path: impl AsRef<Path>) -> Result<Option<bool>>

fn walk<C, E>( &self, config: &WalkConfiguration<'_>, callback: C, ) -> Result<(), E>

where C: FnMut(&WalkComponent<'_, '_>) -> WalkResult<E>, E: From<Error>,

Implementors