Struct OpenOptions

pub struct OpenOptions { /* private fields */ }

Options to configure how an AtomicWriteFile is opened.

This struct mimics the standard struct std::fs::OpenOptions, and offers a subset of its features that are applicable to AtomicWriteFile.

Options can be set using methods like read(). Once the desired options are set, the file can be opened using open().

This crate offers some platform-specific extensions for OpenOptions in the form of traits:

• unix::OpenOptionsExt

Notable differences between std::fs::OpenOptions and atomic_write_file::OpenOptions

The OpenOptions provided in this crate opens all files for writing by default, and the opened file is always initially empty (“truncated”). As such, the following methods are not provided: write(), truncate(), append().

create() is not provided because a new file is always created if an original file does not exist.

create_new() is also not provided because there is no way to ensure that a file never exists from the time an AtomicWriteFile is opened to the time it is committed.

Behavior when opening a file that already exists

When passing a path to open() that points to a file that already exists, AtomicWriteFile may preserve some of the metadata of the existing file (permissions, ownership, and more). This behavior is platform-specific and can be controlled using the platform-specific OpenOptionsExt traits. See also the “notes and limitations” section on the module-level documentations for more information about what metadata is preserved, what is not preserved, and in what circumstances.

Examples

Opening a file for writing with default options (equivalent to a call to AtomicWriteFile::open()):

use atomic_write_file::OpenOptions;
let file = OpenOptions::new().open("foo.txt");

Opening a file for both reading and writing:

use atomic_write_file::OpenOptions;
let file = OpenOptions::new().read(true).open("foo.txt");

Implementations

impl OpenOptions

pub fn new() -> Self

Create a set of options set to their default values.

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

Sets the option for read access.

If true, the file will be readable (other than being writeable) once opened using, for example, the Read trait. Note that if opening an already-existing file, the original file contents will not be readable. Only the new contents of the file will be readable.

If false (the default), the file is opened in write-only mode.

Examples

use std::io::Seek;
use std::io::Write;
use std::io::read_to_string;
use atomic_write_file::OpenOptions;

let mut file = OpenOptions::new().read(true).open("foo.txt")?;
writeln!(file, "hello")?;

file.rewind()?;
assert_eq!(read_to_string(&file)?, "hello\n");

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

Opens the file at path with this set of options.

This has the same semantics as std::fs::OpenOptions::open(), except that it returns an AtomicWriteFile instead of a File.

Examples

use atomic_write_file::OpenOptions;
let file = OpenOptions::new().read(true).open("foo.txt");

Trait Implementations

impl Clone for OpenOptions

fn clone(&self) -> OpenOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for OpenOptions

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

Formats the value using the given formatter.

impl Default for OpenOptions

fn default() -> Self

Returns the “default value” for a type.

impl OpenOptionsExt for OpenOptions

fn mode(&mut self, mode: u32) -> &mut Self

Sets the mode bits that a new file will be created with.

fn custom_flags(&mut self, flags: i32) -> &mut Self

Pass custom flags to the flags argument of open.

impl OpenOptionsExt for OpenOptions

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

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

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.