Struct async_std::fs::File

pub struct File { /* fields omitted */ }

A reference to a file on the filesystem.

An instance of a File can be read and/or written depending on what options it was opened with.

Files are automatically closed when they go out of scope. Errors detected on closing are ignored by the implementation of Drop. Use the method sync_all if these errors must be manually handled.

This type is an async version of std::fs::File.

Examples

Create a new file and write some bytes to it:

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::create("a.txt").await?;
file.write_all(b"Hello, world!").await?;

Read the contents of a file into a Vec<u8>:

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::open("a.txt").await?;
let mut contents = Vec::new();
file.read_to_end(&mut contents).await?;

Methods

impl File

pub async fn open<P: AsRef<Path>>(path: P) -> Result<File>

Opens a file in read-only mode.

See the OpenOptions::open method for more details.

Errors

This function will return an error if path does not already exist. Other errors may also be returned according to OpenOptions::open.

Examples

use async_std::fs::File;

let file = File::open("a.txt").await?;

pub async fn create<P: AsRef<Path>>(path: P) -> Result<File>

Opens a file in write-only mode.

This function will create a file if it does not exist, and will truncate it if it does.

See the OpenOptions::open function for more details.

Examples

use async_std::fs::File;

let file = File::create("a.txt").await?;

pub async fn sync_all<'_>(&'_ self) -> Result<()>

Attempts to synchronize all OS-internal metadata to disk.

This function will attempt to ensure that all in-memory data reaches the filesystem before returning.

This can be used to handle errors that would otherwise only be caught when the File is closed. Dropping a file will ignore errors in synchronizing this in-memory data.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::create("a.txt").await?;
file.write_all(b"Hello, world!").await?;
file.sync_all().await?;

pub async fn sync_data<'_>(&'_ self) -> Result<()>

Similar to sync_all, except that it may not synchronize file metadata.

This is intended for use cases that must synchronize content, but don't need the metadata on disk. The goal of this method is to reduce disk operations.

Note that some platforms may simply implement this in terms of sync_all.

Examples

use async_std::fs::File;
use async_std::prelude::*;

let mut file = File::create("a.txt").await?;
file.write_all(b"Hello, world!").await?;
file.sync_data().await?;

pub async fn set_len<'_>(&'_ self, size: u64) -> Result<()>

Truncates or extends the underlying file.

If the size is less than the current file's size, then the file will be truncated. If it is greater than the current file's size, then the file will be extended to size and have all of the intermediate data filled in with zeros.

The file's cursor isn't changed. In particular, if the cursor was at the end and the file is truncated using this operation, the cursor will now be past the end.

Errors

This function will return an error if the file is not opened for writing.

Examples

use async_std::fs::File;

let file = File::create("a.txt").await?;
file.set_len(10).await?;

pub async fn metadata<'_>(&'_ self) -> Result<Metadata>

Queries metadata about the file.

Examples

use async_std::fs::File;

let file = File::open("a.txt").await?;
let metadata = file.metadata().await?;

pub async fn set_permissions<'_>(&'_ self, perm: Permissions) -> Result<()>

Changes the permissions on the underlying file.

Errors

This function will return an error if the user lacks permission to change attributes on the underlying file, but may also return an error in other OS-specific cases.

Examples

use async_std::fs::File;

let file = File::create("a.txt").await?;

let mut perms = file.metadata().await?.permissions();
perms.set_readonly(true);
file.set_permissions(perms).await?;

Trait Implementations

impl AsRawFd for File

fn as_raw_fd(&self) -> RawFd

This is supported on Unix only.

Extracts the raw file descriptor.

impl FromRawFd for File

unsafe fn from_raw_fd(fd: RawFd) -> File

This is supported on Unix only.

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for File

fn into_raw_fd(self) -> RawFd

This is supported on Unix only.

Consumes this object, returning the raw underlying file descriptor.

impl AsRawHandle for File

fn as_raw_handle(&self) -> RawHandle

This is supported on Windows only.

Extracts the raw handle, without taking any ownership.

impl FromRawHandle for File

unsafe fn from_raw_handle(handle: RawHandle) -> File

This is supported on Windows only.

Constructs a new I/O object from the specified raw handle.

impl IntoRawHandle for File

fn into_raw_handle(self) -> RawHandle

This is supported on Windows only.

Consumes this object, returning the raw underlying handle.

impl Drop for File

fn drop(&mut self)

Executes the destructor for this type.

impl From<File> for File

fn from(file: File) -> File

Converts a std::fs::File into its asynchronous equivalent.

impl Debug for File

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

Formats the value using the given formatter.

impl AsyncRead for File

fn poll_read(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &mut [u8]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

unsafe fn initializer(&self) -> Initializer

Determines if this AsyncReader can work with buffers of uninitialized memory.

fn poll_read_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &mut [IoSliceMut]
) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<'_> AsyncRead for &'_ File

fn poll_read(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &mut [u8]
) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

unsafe fn initializer(&self) -> Initializer

Determines if this AsyncReader can work with buffers of uninitialized memory.

fn poll_read_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &mut [IoSliceMut]
) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncWrite for File

fn poll_write(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &[IoSlice]
) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl<'_> AsyncWrite for &'_ File

fn poll_write(
    self: Pin<&mut Self>,
    cx: &mut Context,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context,
    bufs: &[IoSlice]
) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl AsyncSeek for File

fn poll_seek(
    self: Pin<&mut Self>,
    cx: &mut Context,
    pos: SeekFrom
) -> Poll<Result<u64>>

Attempt to seek to an offset, in bytes, in a stream.

impl<'_> AsyncSeek for &'_ File

fn poll_seek(
    self: Pin<&mut Self>,
    cx: &mut Context,
    pos: SeekFrom
) -> Poll<Result<u64>>

Attempt to seek to an offset, in bytes, in a stream.