Struct File 

pub struct File(/* private fields */);

A reference to an open file on the filesystem.

Implementations

impl File

pub async fn open(path: impl AsRef<Path>) -> Result<Self>

Attempts to open a file in read-only mode. See std::fs::OpenOptions for more details.

Errors

This function will return an error if called from outside of the Tokio runtime (if async) or if path does not already exist. Other errors may also be returned according to OpenOptions::open.

See https://docs.rs/rustc-std-workspace-std/latest/std/fs/struct.File.html#method.open

pub async fn create(path: impl AsRef<Path>) -> Result<Self>

Attempts to open a file in read-only mode with buffering.

Errors

This function will return an error if path does not already exist, or if memory allocation fails for the new buffer. Other errors may also be returned according to std::fs::OpenOptions::open.

See https://docs.rs/rustc-std-workspace-std/latest/std/fs/struct.File.html#method.create

pub async fn create_new(path: impl AsRef<Path>) -> Result<Self>

Opens a file in read-write mode.

This function will create a file if it does not exist, or return an error if it does. This way, if the call succeeds, the file returned is guaranteed to be new.

This option is useful because it is atomic. Otherwise between checking whether a file exists and creating a new one, the file may have been created by another process (a TOCTOU race condition / attack).

This can also be written using File::options().read(true).write(true).create_new(true).open(...).

See std::fs::OpenOptions for more details. See https://docs.rs/rustc-std-workspace-std/latest/std/fs/struct.File.html#method.create_new

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

Queries metadata about the underlying file.

pub fn open_options() -> OpenOptions

Returns a new OpenOptions object.

This function returns a new OpenOptions object that you can use to open or create a file with specific options if open() or create() are not appropriate.

It is equivalent to OpenOptions::new, but allows you to write more readable code. Instead of OpenOptions::new().append(true).open("example.log"), you can write File::options().append(true).open("example.log").await. This also avoids the need to import OpenOptions.

See the OpenOptions::new function for more details.

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

Truncates or extends the underlying file, updating the size of this file to become size.

If the size is less than the current file’s size, then the file will be shrunk. 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 0s.

Errors

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

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

Changes the permissions on the underlying file.

Platform-specific behavior This function currently corresponds to the fchmod function on Unix and the SetFileInformationByHandle function on Windows. Note that, this may change in the future.

Errors

This function will return an error if the user lacks permission change attributes on the underlying file. It may also return an error in other os-specific unspecified cases.

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

Attempts to sync all OS-internal metadata to disk.

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

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

This function is similar to Self::sync_all, except that it may not synchronize file metadata to the filesystem.

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.

pub async fn try_clone(&self) -> Result<Self>

Creates a new File instance that shares the same underlying file handle as the existing File instance. Reads, writes, and seeks will affect both File instances simultaneously.

pub async fn to_std(self) -> File

Converts the File inner instance to a std::fs::File instance if it is currently a tokio::fs::File.

This can be useful when you need for instance to pass an impl std::io::Write to a function.

Trait Implementations

impl AsFd for File

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for File

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for File

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

Formats the value using the given formatter.

impl From<File> for File

fn from(file: File) -> Self

Converts to this type from the input type.

impl FromRawFd for File

unsafe fn from_raw_fd(fd: RawFd) -> Self

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

impl Read for File

async fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Reads data from the stream into the provided buffer.

fn read_vectored( &mut self, bufs: &mut [IoSliceMut<'_>], ) -> impl Future<Output = Result<usize>>

fn is_read_vectored(&self) -> bool

fn read_to_end( &mut self, buf: &mut Vec<u8>, ) -> impl Future<Output = Result<usize>>

fn read_to_string(&mut self) -> impl Future<Output = Result<String>>

fn read_exact(&mut self, buf: &mut [u8]) -> impl Future<Output = Result<()>>

impl Seek for File

async fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Moves the cursor to a new position within the stream.

fn rewind(&mut self) -> impl Future<Output = Result<u64>>

Rewind to the beginning of a stream.

fn stream_position(&mut self) -> impl Future<Output = Result<u64>>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> impl Future<Output = Result<u64>>

Seeks relative to the current position.

impl Unwrap for File

type StdImpl = File

type TokioImpl = File

fn unwrap_std(self) -> Self::StdImpl

Unwraps the std underlying implementation of the MaybeFut type.

fn unwrap_tokio(self) -> Self::TokioImpl

Unwraps the tokio underlying implementation of the MaybeFut type.

fn unwrap_std_ref(&self) -> &Self::StdImpl

Unwraps the std underlying implementation of the MaybeFut type as a reference.

fn unwrap_tokio_ref(&self) -> &Self::TokioImpl

Unwraps the tokio underlying implementation of the MaybeFut type as a reference.

fn unwrap_std_mut(&mut self) -> &mut Self::StdImpl

Unwraps the std underlying implementation of the MaybeFut type as a mutable reference.

fn unwrap_tokio_mut(&mut self) -> &mut Self::TokioImpl

Unwraps the tokio underlying implementation of the MaybeFut type as a mutable reference.

fn get_std(self) -> Option<Self::StdImpl>

Safely unwraps the std underlying implementation of the MaybeFut type.

fn get_tokio(self) -> Option<Self::TokioImpl>

Safely unwraps the tokio underlying implementation of the MaybeFut type.

fn get_std_ref(&self) -> Option<&Self::StdImpl>

Safely unwraps the std underlying implementation of the MaybeFut type as a reference.

fn get_tokio_ref(&self) -> Option<&Self::TokioImpl>

Safely unwraps the tokio underlying implementation of the MaybeFut type as a reference.

fn get_std_mut(&mut self) -> Option<&mut Self::StdImpl>

Safely unwraps the std underlying implementation of the MaybeFut type as a mutable reference.

fn get_tokio_mut(&mut self) -> Option<&mut Self::TokioImpl>

Safely unwraps the tokio underlying implementation of the MaybeFut type as a mutable reference.

impl Write for File

async fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were successfully written.

async fn flush(&mut self) -> Result<()>

Flushes the output streamer, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored( &mut self, bufs: &[IoSlice<'_>], ) -> impl Future<Output = Result<usize>>

Like write, except that it writes from a slice of buffers.

fn write_all(&mut self, buf: &[u8]) -> impl Future<Output = Result<()>>

Attempts to write an entire buffer into this writer.