Struct File 

pub struct File { /* private fields */ }

An asynchronous file handle backed by either a remote VFS client or the local process.

File handles implement Tokio’s asynchronous read, write, and seek traits.

Clones share one open file, as duplicated descriptors do: one cursor position, one set of locks, and one closed state. Closing or handing off the file through any clone closes it for all of them, and their later operations fail with ErrorKind::Closed. Operations in flight are not shared: a clone starts with none, and its reads and writes do not wait for another clone’s.

Implementations

impl File

pub fn poll_read_uninit( &mut self, cx: &mut Context<'_>, buf: &mut [MaybeUninit<u8>], ) -> Poll<Result<usize>>

Reads at the cursor into uninitialized storage, returning how many bytes at its front were filled. Zero means end of file, unless buf is empty.

This is [AsyncRead::poll_read] without the requirement that buf be initialized, so a caller reading into fresh memory need not zero it first. The remote backend writes the reply straight into buf.

impl File

pub async fn close(self) -> Result<()>

Closes the file, for every clone. Closing a closed file does nothing.

pub fn read_at<'b>( &self, buf: &'b mut BytesMut, offset: u64, ) -> impl Future<Output = Result<usize>> + Send + use<'b>

Reads into buf’s spare capacity starting at offset, returning the transfer count.

Cancelling the read may leave buf empty.

Fewer bytes than the spare capacity available may be read. 0 indicates either end-of-file or that buf had no spare capacity.

pub fn write_at( &self, data: Bytes, offset: u64, ) -> impl Future<Output = Result<usize>> + Send + use<>

Writes data at offset, returning the byte count.

May write less than all of data on success, but at least 1 byte unless data is empty. Use on an append-mode handle is an error; use append there.

pub fn append( &self, data: Bytes, ) -> impl Future<Output = Result<(usize, u64)>> + Send + use<>

Appends data, returning the byte count and the position just past what was written. Less data may be written than requested on success, but at least 1 byte will be written unless data was empty.

pub fn read_at_into<'b>( &self, buf: &'b mut [MaybeUninit<u8>], offset: u64, ) -> impl Future<Output = Result<usize>> + Send + use<'b>

Reads into the possibly uninitialized `buf``, returning how many bytes at its front were filled.

pub fn write_at_from<'b>( &self, data: &'b [u8], offset: u64, ) -> impl Future<Output = Result<usize>> + Send + use<'b>

Writes data at offset from borrowed storage, returning the byte count.

Less data may be written than requested on success, but always at least 1 byte unless data is empty.

pub async fn copy_data( &self, dst: &File, src_offset: u64, target: CopyDest, len: Option<u64>, mode: CopyMode, ) -> Result<CopyDataResult>

Copies at most 2 MiB from this file into dst.

len of None copies toward end of source. A positive result may be short for any reason; callers that want a complete operation must loop. Zero indicates end of source (or an empty request).

Nothing is promised about physical allocation: an accelerated route may preserve holes, and the fallback does not.

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

Changes the file length to size bytes.

pub async fn sync(&self, data: bool) -> Result<()>

Flushes the file’s written data to durable storage, returning once the device reports it committed.

data selects a data-only flush (fdatasync), which may skip metadata the caller does not need — notably the modification time — and so can avoid a second write to the inode. Size changes are still flushed, since a reader could not find the data without them.

This durably places the contents. It says nothing about the directory entry naming the file, which is a separate inode and needs its own flush to survive a crash.

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

Returns metadata for the open file.

pub async fn fs_metadata(&self) -> Result<FsMetadata>

Returns metadata for the filesystem containing the open file.

pub async fn acl(&self, kind: AclKind, default: bool) -> Result<Option<Acl>>

Returns the ACL of the requested kind. For a POSIX ACL, default selects the directory’s default ACL rather than its access ACL; it must be false for AclKind::Nfs4.

pub async fn set_acl( &self, kind: AclKind, acl: Option<&Acl>, default: bool, ) -> Result<()>

Sets or removes the ACL of kind. acl, if present, must match kind. default selects the POSIX default ACL, as in acl; it must be false for AclKind::Nfs4.

pub async fn sec_desc(&self, mask: SecInfo) -> Result<SecDesc>

Returns the Windows security descriptor selected by mask.

pub async fn update_sec_desc(&self, sec_desc: &SecDesc) -> Result<()>

Replaces the Windows security descriptor.

pub async fn xattrs( &self, namespace: XattrNamespace<'_>, ) -> Result<Vec<XattrEntry>>

Lists extended attributes in namespace.

pub async fn xattr( &self, name: &str, namespace: Option<&str>, ) -> Result<Vec<u8>>

Reads one extended attribute.

pub async fn streams(&self) -> Result<Vec<StreamEntry>>

Lists alternate data streams.

pub async fn set_xattr( &self, name: &str, namespace: Option<&str>, value: &[u8], ) -> Result<()>

Creates or replaces an extended attribute.

pub async fn remove_xattr( &self, name: &str, namespace: Option<&str>, ) -> Result<()>

Removes an extended attribute.

pub async fn lock( &self, range: FileLockRange, mode: FileLockMode, behavior: FileLockBehavior, ) -> Result<Option<FileLock>>

Acquires a byte-range lock with the requested mode and behavior.

pub async fn try_into_std(self) -> Result<File, Self>

Converts this handle into a local standard-library file when possible, taking it from every clone.

Surrendering the descriptor means surrendering the cursor with it, so the file comes back positioned where this handle is.

Trait Implementations

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.

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 AsyncSeek for File

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

An end-relative seek has to ask for the file’s length, so it may be pending; polling again with the same position drives that query.

impl AsyncWrite for File

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

Each write reaches the file when it completes, so there is nothing buffered to push; flushing only has to settle work in flight.

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

Only flushes: the file is closed by File::close, or when dropped.

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_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 Clone for File

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for File

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

Formats the value using the given formatter.

impl From<File> for ChildIn

fn from(file: File) -> Self

Converts to this type from the input type.

impl From<File> for ChildOut

fn from(file: File) -> Self

Converts to this type from the input type.