OpenOptionsExt in std::os::windows::fs - Rust (original) (raw)

Trait OpenOptionsExt

1.10.0 · Source

pub trait OpenOptionsExt {
    // Required methods
    fn access_mode(&mut self, access: u32) -> &mut Self;
    fn share_mode(&mut self, val: u32) -> &mut Self;
    fn custom_flags(&mut self, flags: u32) -> &mut Self;
    fn attributes(&mut self, val: u32) -> &mut Self;
    fn security_qos_flags(&mut self, flags: u32) -> &mut Self;
}

Available on Windows only.

Expand description

1.10.0 · Source

Overrides the dwDesiredAccess argument to the call to CreateFilewith the specified value.

This will override the read, write, and append flags on theOpenOptions structure. This method provides fine-grained control over the permissions to read, write and append data, attributes (like hidden and system), and extended attributes.

§Examples

use std::fs::OpenOptions;
use std::os::windows::prelude::*;

// Open without read and write permission, for example if you only need
// to call `stat` on the file
let file = OpenOptions::new().access_mode(0).open("foo.txt");

Overrides the dwShareMode argument to the call to CreateFile with the specified value.

By default share_mode is set toFILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE. This allows other processes to read, write, and delete/rename the same file while it is open. Removing any of the flags will prevent other processes from performing the corresponding operation until the file handle is closed.

§Examples

use std::fs::OpenOptions;
use std::os::windows::prelude::*;

// Do not allow others to read or modify this file while we have it open
// for writing.
let file = OpenOptions::new()
    .write(true)
    .share_mode(0)
    .open("foo.txt");

1.10.0 · Source

Sets extra flags for the dwFileFlags argument to the call toCreateFile2 to the specified value (or combines it withattributes and security_qos_flags to set the dwFlagsAndAttributesfor CreateFile).

Custom flags can only set flags, not remove flags set by Rust’s options. This option overwrites any previously set custom flags.

§Examples

extern crate winapi;

use std::fs::OpenOptions;
use std::os::windows::prelude::*;

let file = OpenOptions::new()
    .create(true)
    .write(true)
    .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE)
    .open("foo.txt");

1.10.0 · Source

Sets the dwFileAttributes argument to the call to CreateFile2 to the specified value (or combines it with custom_flags andsecurity_qos_flags to set the dwFlagsAndAttributes forCreateFile).

If a new file is created because it does not yet exist and.create(true) or .create_new(true) are specified, the new file is given the attributes declared with .attributes().

If an existing file is opened with .create(true).truncate(true), its existing attributes are preserved and combined with the ones declared with .attributes().

In all other cases the attributes get ignored.

§Examples

extern crate winapi;

use std::fs::OpenOptions;
use std::os::windows::prelude::*;

let file = OpenOptions::new()
    .write(true)
    .create(true)
    .attributes(winapi::FILE_ATTRIBUTE_HIDDEN)
    .open("foo.txt");

1.10.0 · Source

Sets the dwSecurityQosFlags argument to the call to CreateFile2 to the specified value (or combines it with custom_flags and attributesto set the dwFlagsAndAttributes for CreateFile).

By default security_qos_flags is not set. It should be specified when opening a named pipe, to control to which degree a server process can act on behalf of a client process (security impersonation level).

When security_qos_flags is not set, a malicious program can gain the elevated privileges of a privileged Rust process when it allows opening user-specified paths, by tricking it into opening a named pipe. So arguably security_qos_flags should also be set when opening arbitrary paths. However the bits can then conflict with other flags, specificallyFILE_FLAG_OPEN_NO_RECALL.

For information about possible values, see Impersonation Levels on the Windows Dev Center site. The SECURITY_SQOS_PRESENT flag is set automatically when using this method.

§Examples

extern crate winapi;
use std::fs::OpenOptions;
use std::os::windows::prelude::*;

let file = OpenOptions::new()
    .write(true)
    .create(true)

    // Sets the flag value to `SecurityIdentification`.
    .security_qos_flags(winapi::SECURITY_IDENTIFICATION)

    .open(r"\\.\pipe\MyPipe");

This trait is not dyn compatible.

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

1.10.0 · Source§