atomic_write_file::unix

Trait OpenOptionsExt

Source 
pub trait OpenOptionsExt {
    // Required methods
    fn preserve_mode(&mut self, preserve_mode: bool) -> &mut Self;
    fn preserve_owner(&mut self, preserve_owner: bool) -> &mut Self;
    fn try_preserve_owner(&mut self, try_preserve_owner: bool) -> &mut Self;
}
Expand description

Unix-specific extensions to OpenOptions.

On Unix, AtomicWriteFile works by creating a temporary file, and then renaming the file to its final name at commit time. If a file with the same name already exists, it is often desiderable that the new file written by AtomicWriteFile preserves the same permissions, attributes, and other metadata as the original file. This extension trait allows you to control which metadata should be preserved, and which metadata should use default values instead.

Note: AtomicWriteFile samples and copies the metadata from the original file (if any) to the temporary file when the AtomicWriteFile is initially opened. If the original file metadata is changed, or the original file is deleted, or the original file gets (re-)created, before the AtomicWriteFile is committed, those changes won’t be reflected in the final result.

Required Methods§

Source

fn preserve_mode(&mut self, preserve_mode: bool) -> &mut Self

Specifies whether the atomically-written file should have the file permissions of the original file (if any).

If true (the default), the file permissions of the original file (if any) are copied over to the atomically-written file when OpenOptions::open() is called.

If false, or if no original file exists when OpenOptions::open() is called, the default mode 0o666 is used, which will be masked with the process umask. The default mask can be customized using std::os::unix::fs::OpenOptionsExt::mode().

This method only preserves the permissions that can be set through chmod(2). This method has no effect on ACLs (POSIX Access Control Lists).

§Examples
use atomic_write_file::OpenOptions;
use atomic_write_file::unix::OpenOptionsExt;

let mut options = OpenOptions::new();
options.preserve_mode(false);
let file = options.open("foo.txt")?;
file.commit()?; // "foo.txt" is saved with the default mode
Source

fn preserve_owner(&mut self, preserve_owner: bool) -> &mut Self

Specifies whether the atomically-written file should have the same ownership (user/group) of the original file (if any).

If true, the ownership of the original file (if any) is copied over to the atomically-written file when OpenOptions::open() is called.

If false, or if no original file exists when OpenOptions::open() is called, the ownership is set using the default platform-specific semantics.

Note: setting ownership of files generally requires root privileges on Unix platforms (or CAP_CHOWN on Linux). As such, using preserve_owner(true) when the process is not running as root may result in OpenOptions::open() to fail with an error.

The related method OpenOptionsExt::try_preserve_owner() allows to preserve ownership only if the process has sufficient privileges. It is a variant of this option that does not cause OpenOptions::open() to fail when the process does not have enough privileges to preserve ownership.

By default, try_preserve_owner(true) is used.

Calling preserve_owner() overrides any previous call to preserve_owner() or try_preserve_owner().

§Examples
use atomic_write_file::OpenOptions;
use atomic_write_file::unix::OpenOptionsExt;

let mut options = OpenOptions::new();
options.preserve_owner(true);
let file = options.open("foo.txt")?; // this fails if "foo.txt" exists and its ownership
                                     // cannot be preserved
file.commit()?; // "foo.txt" is saved with the same ownership as the original "foo.txt"
                // (if any)
Source

fn try_preserve_owner(&mut self, try_preserve_owner: bool) -> &mut Self

Specifies whether the atomically-written file should have the ownership information (user/group) of the original file (if any). If ownership information cannot be set on the atomically-written file, and if the process is not running as root, then OpenOptions::open() silently continues suppressing the error.

Using try_preserve_owner(true) is equivalent to using OpenOptionsExt::preserve_owner(true), with the exception that this option does not cause OpenOptions::open() to fail with a “Operation not permitted” (EPERM) error if the process is not running as root (effective UID 0).

Note that OpenOptions::open() may still fail with an error when setting ownership if an error other than “Operation not permitted” (EPERM) is thrown.

If the process is running as root, then all errors are reported by OpenOptions::open().

If false, or if no original file exists when OpenOptions::open() is called, the ownership is set using the default platform-specific semantics.

The default value for this option is true.

Calling try_preserve_owner() overrides any previous call to preserve_owner() or try_preserve_owner().

§Examples
use atomic_write_file::OpenOptions;
use atomic_write_file::unix::OpenOptionsExt;

let mut options = OpenOptions::new();
options.try_preserve_owner(true); // this is the default
let file = options.open("foo.txt")?; // this won't fail if "foo.txt" exists, its ownership
                                     // cannot be preserved, and the process is not running
                                     // as root
file.commit()?; // "foo.txt" is saved with the same ownership as the original "foo.txt"
                // (if any)

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.

Implementors§