Struct File 

pub struct File { /* private fields */ }

Implementations

impl File

pub async fn into_stdio_send( self, offset: u64, ) -> Result<StdioSend, HandoffError<Self>>

Consumes this handle, converting it into a standard-output or standard-error endpoint positioned at offset.

The endpoint carries a position of its own and the cursor is kept on this side rather than in the kernel, so the position has to be stated explicitly: this handle’s own is only the right answer when the caller is the one holding it, which is not the case for anything relaying on someone else’s behalf.

The handle is consumed because two live handles onto one description would each believe a cursor the other moves. Callers that want to keep reading or writing should open the file again instead.

Errors

Returns HandoffError, which carries the handle back. Nothing has been surrendered when it does — most importantly on the busy path, where operations are still in flight against the descriptor and the caller may simply retry once they finish.

pub async fn into_stdio_recv( self, offset: u64, ) -> Result<StdioRecv, HandoffError<Self>>

Consumes this handle, converting it into a standard-input endpoint positioned at offset. See into_stdio_send.

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

Closes this handle.

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.

Trait Implementations

impl AsyncRead for File

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

Attempts to read from the AsyncRead into buf.

impl AsyncSeek for File

fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Result<()>

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

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

Waits for a seek operation to complete.

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<()>>

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

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

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

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

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

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for File

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

Formats the value using the given formatter.