pub struct File { /* private fields */ }Expand description
A reference to an open file on the filesystem.
An instance of a File can be read and/or written depending on what options
it was opened with. The File type provides positional read and write
operations. The file does not maintain an internal cursor. The caller is
required to specify an offset when issuing an operation.
Implementations§
source§impl File
impl File
sourcepub fn open(path: impl AsRef<Path>) -> Result<Self>
pub fn open(path: impl AsRef<Path>) -> Result<Self>
Attempts to open a file in read-only mode.
See the OpenOptions::open method for more details.
sourcepub fn create(path: impl AsRef<Path>) -> Result<Self>
pub fn create(path: impl AsRef<Path>) -> Result<Self>
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.
sourcepub fn try_clone(&self) -> Result<Self>
pub fn try_clone(&self) -> Result<Self>
Creates a new File instance that shares the same underlying file
handle as the existing File instance.
It does not clear the attach state.
sourcepub async fn read_at<T: IoBufMut>(
&self,
buffer: T,
pos: usize
) -> BufResult<usize, T>
pub async fn read_at<T: IoBufMut>( &self, buffer: T, pos: usize ) -> BufResult<usize, T>
Read some bytes at the specified offset from the file into the specified buffer, returning how many bytes were read.
Return
The method returns the operation result and the same buffer value passed as an argument.
If the method returns [Ok(n)], then the read was successful. A nonzero
n value indicates that the buffer has been filled with n bytes of
data from the file. If n is 0, then one of the following happened:
- The specified offset is the end of the file.
- The buffer specified was 0 bytes in capacity.
It is not an error if the returned value n is smaller than the buffer
size, even when the file contains enough data to fill the buffer.
Errors
If this function encounters any form of I/O or other error, an error variant will be returned. The buffer is returned on error.
sourcepub async fn read_exact_at<T: IoBufMut>(
&self,
buffer: T,
pos: usize
) -> BufResult<usize, T>
pub async fn read_exact_at<T: IoBufMut>( &self, buffer: T, pos: usize ) -> BufResult<usize, T>
Read the exact number of bytes required to fill buffer.
This function reads as many bytes as necessary to completely fill the
uninitialized space of specified buffer.
Errors
If this function encounters an “end of file” before completely filling
the buffer, it returns an error of the kind
ErrorKind::UnexpectedEof. The contents of buffer are unspecified
in this case.
If any other read error is encountered then this function immediately
returns. The contents of buffer are unspecified in this case.
If this function returns an error, it is unspecified how many bytes it has read, but it will never read more than would be necessary to completely fill the buffer.
sourcepub async fn read_to_end_at<A: Allocator + Unpin + 'static>(
&self,
buffer: Vec<u8, A>,
pos: usize
) -> BufResult<usize, Vec<u8, A>>
pub async fn read_to_end_at<A: Allocator + Unpin + 'static>( &self, buffer: Vec<u8, A>, pos: usize ) -> BufResult<usize, Vec<u8, A>>
Read all bytes until EOF in this source, placing them into buffer.
All bytes read from this source will be appended to the specified buffer
buffer. This function will continuously call read_at() to append
more data to buffer until read_at() returns [Ok(0)].
If successful, this function will return the total number of bytes read.
sourcepub async fn write_at<T: IoBuf>(
&self,
buffer: T,
pos: usize
) -> BufResult<usize, T>
pub async fn write_at<T: IoBuf>( &self, buffer: T, pos: usize ) -> BufResult<usize, T>
Write a buffer into this file at the specified offset, returning how many bytes were written.
This function will attempt to write the entire contents of buf, but
the entire write may not succeed, or the write may also generate an
error. The bytes will be written starting at the specified offset.
Return
The method returns the operation result and the same buffer value passed
in as an argument. A return value of 0 typically means that the
underlying file is no longer able to accept bytes and will likely not be
able to in the future as well, or that the buffer provided is empty.
Errors
Each call to write_at may generate an I/O error indicating that the
operation could not be completed. If an error is returned then no bytes
in the buffer were written to this writer.
It is not considered an error if the entire buffer could not be written to this writer.
sourcepub async fn write_all_at<T: IoBuf>(
&self,
buffer: T,
pos: usize
) -> BufResult<usize, T>
pub async fn write_all_at<T: IoBuf>( &self, buffer: T, pos: usize ) -> BufResult<usize, T>
Attempts to write an entire buffer into this writer.
This method will continuously call write_at until there is no more
data to be written. This method will not return until the entire
buffer has been successfully written or such an error occurs.
If the buffer contains no data, this will never call write_at.
sourcepub async fn sync_all(&self) -> Result<()>
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-memory data reaches the filesystem before returning.
sourcepub async fn sync_data(&self) -> Result<()>
pub async fn sync_data(&self) -> Result<()>
This function is similar to sync_all, except that it might 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.