Trait OpenatDirExt

pub trait OpenatDirExt {
    // Required methods
    fn open_file_optional<P: AsPath>(&self, p: P) -> Result<Option<File>>;
    fn read_to_string<P: AsPath>(&self, p: P) -> Result<String>;
    fn read_to_string_optional<P: AsPath>(&self, p: P) -> Result<Option<String>>;
    fn remove_file_optional<P: AsPath>(&self, p: P) -> Result<bool>;
    fn remove_dir_optional<P: AsPath>(&self, p: P) -> Result<bool>;
    fn sub_dir_optional<P: AsPath>(&self, p: P) -> Result<Option<Dir>>;
    fn metadata_optional<P: AsPath>(&self, p: P) -> Result<Option<Metadata>>;
    fn get_file_type(&self, e: &Entry) -> Result<SimpleType>;
    fn exists<P: AsPath>(&self, p: P) -> Result<bool>;
    fn ensure_dir<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>;
    fn ensure_dir_all<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>;
    fn remove_all<P: AsPath>(&self, p: P) -> Result<bool>;
    fn syncfs(&self) -> Result<()>;
    fn local_rename_optional<P: AsRef<Path>, R: AsRef<Path>>(
        &self,
        oldpath: P,
        newpath: R,
    ) -> Result<bool>;
    fn update_timestamps<P: AsPath>(&self, path: P) -> Result<()>;
    fn set_mode<P: AsPath>(&self, path: P, mode: mode_t) -> Result<()>;
    fn copy_file<S: AsPath, D: AsPath>(&self, s: S, d: D) -> Result<()>;
    fn copy_file_at<S: AsPath, D: AsPath>(
        &self,
        s: S,
        target_dir: &Dir,
        d: D,
    ) -> Result<()>;
    fn new_file_writer(&self, mode: mode_t) -> Result<FileWriter<'_>>;

    // Provided methods
    fn write_file_with<P: AsRef<Path>, F, T, E>(
        &self,
        destname: P,
        mode: mode_t,
        gen_content_fn: F,
    ) -> Result<T, E>
       where F: FnOnce(&mut BufWriter<File>) -> Result<T, E>,
             E: From<Error> { ... }
    fn write_file_with_sync<P: AsRef<Path>, F, T, E>(
        &self,
        destname: P,
        mode: mode_t,
        gen_content_fn: F,
    ) -> Result<T, E>
       where F: FnOnce(&mut BufWriter<File>) -> Result<T, E>,
             E: From<Error> { ... }
    fn write_file_contents<P: AsRef<Path>, C: AsRef<[u8]>>(
        &self,
        destname: P,
        mode: mode_t,
        contents: C,
    ) -> Result<()> { ... }
}

Helper functions for openat::Dir

Required Methods

fn open_file_optional<P: AsPath>(&self, p: P) -> Result<Option<File>>

Checking for nonexistent files (ENOENT) is by far the most common case of inspecting error codes in Unix. Rust has a nice Option<> type, so this helper makes use of it and returns Ok(None) for nonexistent files. All other errors are Err, and extant files are Ok(Some<file>)) of course.

fn read_to_string<P: AsPath>(&self, p: P) -> Result<String>

Like std::fs::read_to_string() but with a path relative to the openat::Dir.

fn read_to_string_optional<P: AsPath>(&self, p: P) -> Result<Option<String>>

Like read_to_string, but returns Ok(None) for nonexistent paths.

fn remove_file_optional<P: AsPath>(&self, p: P) -> Result<bool>

Remove a file from the given directory; does not error if the target does not exist. But will return an error if the target is a directory.

fn remove_dir_optional<P: AsPath>(&self, p: P) -> Result<bool>

Remove an empty sub-directory from the given directory; does not error if the target does not exist. But will return an error if the target is a file or symlink.

fn sub_dir_optional<P: AsPath>(&self, p: P) -> Result<Option<Dir>>

Like open_file_optional() except opens a directory via openat::dir::sub_dir.

fn metadata_optional<P: AsPath>(&self, p: P) -> Result<Option<Metadata>>

Like metadata() except returns Ok(None) for nonexistent paths.

fn get_file_type(&self, e: &Entry) -> Result<SimpleType>

On modern filesystems the directory entry contains the type; if available, return it. Otherwise invoke stat().

fn exists<P: AsPath>(&self, p: P) -> Result<bool>

Returns true iff file exists (may be a directory or symlink). Symbolic links are not followed.

fn ensure_dir<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>

Create a directory but don’t error if it already exists.

fn ensure_dir_all<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>

Create directory and all parents as necessary; no error is returned if directory already exists.

fn remove_all<P: AsPath>(&self, p: P) -> Result<bool>

Remove all content at the target path, returns true if something existed there.

fn syncfs(&self) -> Result<()>

Synchronize to disk the filesystem containing this directory.

fn local_rename_optional<P: AsRef<Path>, R: AsRef<Path>>( &self, oldpath: P, newpath: R, ) -> Result<bool>

If oldpath exists, rename it to newpath. Otherwise do nothing.

This returns true if the old path has been succesfully renamed, false otherwise.

fn update_timestamps<P: AsPath>(&self, path: P) -> Result<()>

Update timestamps (both access and modification) to the current time.

If the entry at path is a symlink, its direct timestamps are updated without following the link.

fn set_mode<P: AsPath>(&self, path: P, mode: mode_t) -> Result<()>

Update permissions for the given path (see fchmodat(2)).

If the entry at path is a symlink, no action is performed.

fn copy_file<S: AsPath, D: AsPath>(&self, s: S, d: D) -> Result<()>

Copy a regular file. The semantics here are intended to match std::fs::copy(). If the target exists, it will be overwritten. The mode bits (permissions) will match, but owner/group will be derived from the current process. Extended attributes are not copied. However, symbolic links will not be followed; instead an error is returned. If the filesystem supports it, reflinks will be used.

fn copy_file_at<S: AsPath, D: AsPath>( &self, s: S, target_dir: &Dir, d: D, ) -> Result<()>

Copy a regular file.

This is the same as copy_file, but can copy to an arbitrary target directory outside of self.

fn new_file_writer(&self, mode: mode_t) -> Result<FileWriter<'_>>

Create a FileWriter which provides a std::io::BufWriter and then atomically creates the file at the destination, renaming it over an existing one if necessary.

Provided Methods

fn write_file_with<P: AsRef<Path>, F, T, E>( &self, destname: P, mode: mode_t, gen_content_fn: F, ) -> Result<T, E>

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

Atomically create or replace the destination file, calling the provided function to generate the contents. Note that the contents of the file will not be explicitly sync’d to disk; if you want to do so you need to invoke writer.flush()?; writer.get_ref().sync_all() for example.

fn write_file_with_sync<P: AsRef<Path>, F, T, E>( &self, destname: P, mode: mode_t, gen_content_fn: F, ) -> Result<T, E>

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

Like write_file_with() but explicitly synchronizes the target to disk.

fn write_file_contents<P: AsRef<Path>, C: AsRef<[u8]>>( &self, destname: P, mode: mode_t, contents: C, ) -> Result<()>

Atomically create or replace the destination file with the provided contents.

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 OpenatDirExt for Dir

fn open_file_optional<P: AsPath>(&self, p: P) -> Result<Option<File>>

fn read_to_string<P: AsPath>(&self, p: P) -> Result<String>

fn read_to_string_optional<P: AsPath>(&self, p: P) -> Result<Option<String>>

fn remove_file_optional<P: AsPath>(&self, p: P) -> Result<bool>

fn remove_dir_optional<P: AsPath>(&self, p: P) -> Result<bool>

fn metadata_optional<P: AsPath>(&self, p: P) -> Result<Option<Metadata>>

fn sub_dir_optional<P: AsPath>(&self, p: P) -> Result<Option<Dir>>

fn get_file_type(&self, e: &Entry) -> Result<SimpleType>

fn exists<P: AsPath>(&self, p: P) -> Result<bool>

fn ensure_dir<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>

fn ensure_dir_all<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>

fn copy_file<S: AsPath, D: AsPath>(&self, s: S, d: D) -> Result<()>

fn copy_file_at<S: AsPath, D: AsPath>( &self, s: S, target_dir: &Dir, d: D, ) -> Result<()>

fn remove_all<P: AsPath>(&self, p: P) -> Result<bool>

fn syncfs(&self) -> Result<()>

fn local_rename_optional<P: AsRef<Path>, R: AsRef<Path>>( &self, oldpath: P, newpath: R, ) -> Result<bool>

fn update_timestamps<P: AsPath>(&self, p: P) -> Result<()>

fn set_mode<P: AsPath>(&self, p: P, mode: mode_t) -> Result<()>

fn new_file_writer(&self, mode: mode_t) -> Result<FileWriter<'_>>

Implementors