Структура OpenOptions

Создаёт пустой набор параметров, готовый к настройке.

Изначально для всех параметров установлено значение false.

Это асинхронная версия std::fs::OpenOptions::new

Примеры

use tokio::fs::OpenOptions;

let mut options = OpenOptions::new();
let future = options.read(true).open("foo.txt");

Задаёт параметр доступа для чтения.

Если этот параметр имеет значение true, это означает, что при открытии файла его можно будет читать (read).

Это асинхронная версия std::fs::OpenOptions::read

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .read(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Задаёт параметр доступа для записи.

Если этот параметр имеет значение true, это означает, что при открытии файла в него можно будет записывать (write).

Это асинхронная версия std::fs::OpenOptions::write

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Задаёт параметр режима добавления.

Если этот параметр имеет значение true, данные будут добавляться в конец файла, а не перезаписывать его содержимое. Обратите внимание, что установка .write(true).append(true) даёт тот же эффект, что и установка только .append(true).

Для большинства файловых систем операционная система гарантирует атомарность всех операций записи: данные не будут повреждены, если другой процесс одновременно выполняет запись.

В режиме добавления следует учитывать одно, возможно, очевидное замечание: все связанные данные нужно записывать в файл одной операцией. Для этого можно объединить строки перед передачей их в write() или использовать буферизованный писатель (с буфером подходящего размера) и вызвать flush(), когда сообщение будет готово.

Если файл открыт для чтения и добавления, имейте в виду, что после открытия и после каждой операции записи позиция чтения может переместиться в конец файла. Поэтому перед записью сохраните текущую позицию (с помощью seek(SeekFrom::Current(0))), а перед следующим чтением восстановите её.

Это асинхронная версия std::fs::OpenOptions::append

Примечание

Эта функция не создаёт файл, если он не существует. Для этого используйте метод create.

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .append(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Задаёт параметр усечения существующего файла.

Если файл успешно открыт с включённым параметром, его длина будет равна 0, если он уже существует.

Для усечения файла он должен быть открыт для записи.

Это асинхронная версия std::fs::OpenOptions::truncate

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .truncate(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Задаёт параметр создания нового файла.

Этот параметр определяет, будет ли создан новый файл, если указанный файл ещё не существует.

Для создания файла необходимо использовать доступ для записи write или добавления append.

Это асинхронная версия std::fs::OpenOptions::create

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .create(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Задаёт параметр, который гарантирует создание нового файла.

Этот параметр указывает, будет ли создан новый файл. В целевом расположении не должно существовать никаких файлов, в том числе (висячих) символических ссылок.

Этот параметр полезен благодаря своей атомарности. В противном случае между проверкой существования файла и созданием нового файла другой процесс может успеть создать файл (состояние гонки / атака TOCTOU).

Если задан .create_new(true), параметры .create() и .truncate() игнорируются.

Для создания нового файла его необходимо открыть с правами на запись или добавление.

Это асинхронная версия std::fs::OpenOptions::create_new

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .create_new(true)
        .open("foo.txt")
        .await?;

    Ok(())
}

Открывает файл по пути path с параметрами, заданными в self.

Это асинхронная версия std::fs::OpenOptions::open

Ошибки

Эта функция может возвращать ошибку при различных обстоятельствах. Некоторые из этих условий перечислены ниже вместе с соответствующими им значениями ErrorKind. Сопоставление со значениями ErrorKind не входит в контракт совместимости функции; в частности, значение Other в будущем может быть заменено более конкретными значениями.

• NotFound: Указанный файл не существует, а параметры create и create_new не заданы.
• NotFound: Один из компонентов каталога в пути к файлу не существует.
• PermissionDenied: У пользователя нет разрешения на получение указанных прав доступа к файлу.
• PermissionDenied: У пользователя нет разрешения на открытие одного из компонентов каталога в указанном пути.
• AlreadyExists: Был задан параметр create_new, а файл уже существует.
• InvalidInput: Недопустимое сочетание параметров открытия (усечение без прав на запись, отсутствие заданного режима доступа и т. д.).
• Other: Один из компонентов каталога в указанном пути к файлу на самом деле не является каталогом.
• Other: Ошибки файловой системы: диск заполнен, запрошена запись в файловую систему только для чтения, превышена дисковая квота, слишком много открытых файлов, слишком длинное имя файла, слишком много символических ссылок в указанном пути (только в Unix-подобных системах) и т. д.

Поддержка io_uring

В Linux для выполнения системных вызовов также можно использовать io_uring. Чтобы включить io_uring, необходимо указать флаг --cfg tokio_unstable во время компиляции, включить функцию Cargo io-uring и задать параметр среды выполнения Builder::enable_io_uring.

Поддержка io_uring пока является экспериментальной, поэтому её поведение может измениться или она может быть удалена в будущих версиях.

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new().open("foo.txt").await?;
    Ok(())
}

Задаёт биты режима, с которыми будет создан новый файл.

Если новый файл создаётся в рамках вызова OpenOptions::open, указанный mode будет использован в качестве битов разрешений для нового файла. Если mode не задан, будет использоваться значение по умолчанию 0o666. Операционная система сбрасывает биты, указанные системным umask, чтобы получить итоговые разрешения.

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut options = OpenOptions::new();
    options.mode(0o644); // Give read/write for owner and read for others.
    let file = options.open("foo.txt").await?;

    Ok(())
}

Передаёт пользовательские флаги аргументу flags функции open.

Биты, определяющие режим доступа, маскируются с помощью O_ACCMODE, чтобы гарантировать, что они не будут влиять на режим доступа, заданный параметрами Rust.

Пользовательские флаги могут только устанавливать флаги, но не удалять флаги, заданные параметрами Rust. Этот параметр перезаписывает все ранее заданные пользовательские флаги.

Примеры

use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut options = OpenOptions::new();
    options.write(true);
    if cfg!(unix) {
        options.custom_flags(libc::O_NOFOLLOW);
    }
    let file = options.open("foo.txt").await?;

    Ok(())
}

Переопределяет аргумент dwDesiredAccess при вызове CreateFile указанным значением.

Это переопределит флаги read, write и append структуры OpenOptions. Этот метод предоставляет детальный контроль над разрешениями на чтение, запись и добавление данных, атрибутов (например, скрытых и системных) и расширенных атрибутов.

Примеры

use tokio::fs::OpenOptions;

// 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").await?;

Переопределяет аргумент dwShareMode при вызове CreateFile указанным значением.

По умолчанию share_mode устанавливается в FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE. Это позволяет другим процессам читать, записывать и удалять/переименовывать тот же файл, пока он открыт. Удаление любого из флагов не позволит другим процессам выполнять соответствующую операцию, пока файловый дескриптор не будет закрыт.

Примеры

use tokio::fs::OpenOptions;

// 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").await?;

Устанавливает дополнительные флаги для аргумента dwFileFlags при вызове CreateFile2 в указанное значение (или объединяет его с attributes и security_qos_flags, чтобы установить dwFlagsAndAttributes для CreateFile).

Пользовательские флаги могут только устанавливать флаги, но не удалять флаги, заданные параметрами Rust. Этот параметр перезаписывает все ранее установленные пользовательские флаги.

Примеры

use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_DELETE_ON_CLOSE;
use tokio::fs::OpenOptions;

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

Устанавливает аргумент dwFileAttributes при вызове CreateFile2 в указанное значение (или объединяет его с custom_flags и security_qos_flags, чтобы установить dwFlagsAndAttributes для CreateFile).

Если создаётся новый файл, поскольку он ещё не существует, и указаны .create(true) или .create_new(true), новому файлу назначаются атрибуты, объявленные с помощью .attributes().

Если существующий файл открывается с помощью .create(true).truncate(true), его существующие атрибуты сохраняются и объединяются с атрибутами, объявленными с помощью .attributes().

Во всех остальных случаях атрибуты игнорируются.

Примеры

use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_HIDDEN;
use tokio::fs::OpenOptions;

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

Устанавливает аргумент dwSecurityQosFlags при вызове CreateFile2 в указанное значение (или объединяет его с custom_flags и attributes, чтобы установить dwFlagsAndAttributes для CreateFile).

По умолчанию security_qos_flags не установлен. Его следует указывать при открытии именованного канала, чтобы контролировать, в какой степени серверный процесс может действовать от имени клиентского процесса (уровень олицетворения безопасности).

Если security_qos_flags не установлен, вредоносная программа может получить повышенные привилегии привилегированного процесса Rust, если тот разрешает открывать указанные пользователем пути: для этого достаточно обманом заставить его открыть именованный канал. Поэтому можно утверждать, что security_qos_flags следует также устанавливать при открытии произвольных путей. Однако в этом случае биты могут конфликтовать с другими флагами, в частности с FILE_FLAG_OPEN_NO_RECALL.

Сведения о возможных значениях см. в разделе Уровни олицетворения на сайте Центра разработки Windows. При использовании этого метода флаг SECURITY_SQOS_PRESENT устанавливается автоматически.

Примеры

use windows_sys::Win32::Storage::FileSystem::SECURITY_IDENTIFICATION;
use tokio::fs::OpenOptions;

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

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

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

Возвращает аргумент без изменений.

Вызывает U::from(self).

То есть это преобразование выполняется так, как определит реализация From<T> for U.