Struct File

pub struct File { /* private fields */ }

A reference to the remote file.

Cloning File instance would return a new one that shares the same underlying file handle as the existing File instance, while reads, writes and seeks can be performed independently.

If you want a file that implements tokio::io::AsyncRead and tokio::io::AsyncWrite, checkout TokioCompatFile.

Implementations

impl File

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

Close the File, send the close request if this is the last reference.

Cancel Safety

This function is cancel safe.

pub async fn set_metadata(&mut self, metadata: MetaData) -> Result<(), Error>

Change the metadata of a file or a directory.

Cancel Safety

This function is cancel safe.

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

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.

Cancel Safety

This function is cancel safe.

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

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.

Precondition

Require extension fsync

You can check it with Sftp::support_fsync.

Cancel Safety

This function is cancel safe.

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

Changes the permissions on the underlying file.

Cancel Safety

This function is cancel safe.

pub async fn metadata(&mut self) -> Result<MetaData, Error>

Queries metadata about the underlying file.

pub async fn read( &mut self, n: u32, buffer: BytesMut, ) -> Result<Option<BytesMut>, Error>

• n - number of bytes to read in

If the File has reached EOF or n == 0, then None is returned.

NOTE that the returned buffer might be smaller than n.

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

Write data into the file.

NOTE that this API might only write part of the buf.

pub async fn write_vectorized( &mut self, bufs: &[IoSlice<'_>], ) -> Result<usize, Error>

Write from multiple buffer at once.

NOTE that this API might only write part of the buf.

pub async fn write_zero_copy( &mut self, bytes_slice: &[Bytes], ) -> Result<usize, Error>

Zero copy write.

NOTE that this API might only write part of the buf.

pub async fn read_all( &mut self, n: usize, buffer: BytesMut, ) -> Result<BytesMut, Error>

• n - number of bytes to read in.

If n == 0 or EOF is reached, then buffer is returned unchanged.

Cancel Safety

This function is cancel safe.

pub async fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Write entire buf.

Cancel Safety

This function is cancel safe.

pub async fn write_all_vectorized( &mut self, bufs: &mut [IoSlice<'_>], ) -> Result<(), Error>

Write entire buf.

Cancel Safety

This function is cancel safe.

pub async fn write_all_zero_copy( &mut self, bufs: &mut [Bytes], ) -> Result<(), Error>

Write entire buf.

Cancel Safety

This function is cancel safe.

pub fn offset(&self) -> u64

Return the offset of the file.

pub async fn copy_to( &mut self, dst: &mut Self, n: NonZeroU64, ) -> Result<(), Error>

Copy n bytes of data from self to dst.

The server MUST copy the data exactly as if the data is copied using a series of read and write.

There are no protocol restictions on this operation; however, the server MUST ensure that the user does not exceed quota, etc. The server is, as always, free to complete this operation out of order if it is too large to complete immediately, or to refuse a request that is too large.

After a successful function call, the offset of self and dst are increased by n.

Precondition

Requires extension copy-data. For openssh-portable, this is available from V_9_0_P1.

You can check it with Sftp::support_copy.

If the extension is not supported by the server, this function would fail with Error::UnsupportedExtension.

pub async fn copy_all_to(&mut self, dst: &mut Self) -> Result<(), Error>

Copy data from self to dst until EOF is encountered.

The server MUST copy the data exactly as if the data is copied using a series of read and write.

There are no protocol restictions on this operation; however, the server MUST ensure that the user does not exceed quota, etc. The server is, as always, free to complete this operation out of order if it is too large to complete immediately, or to refuse a request that is too large.

After a successful function call, the offset of self and dst are unchanged.

Precondition

Requires extension copy-data. For openssh-portable, this is available from V_9_0_P1.

You can check it with Sftp::support_copy.

If the extension is not supported by the server, this function would fail with Error::UnsupportedExtension.

pub fn as_mut_file(&mut self) -> &mut File

No-op to be compatible with TokioCompatFile::as_mut_file

Trait Implementations

impl AsyncSeek for File

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

start_seek only adjust local offset since sftp protocol does not provides a seek function.

Instead, offset is provided when sending read/write requests, thus errors are reported at read/write.

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

This function is a no-op, it simply return the offset.

impl Clone for File

fn clone(&self) -> Self

Returns a copy 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 TokioCompatFile

fn from(inner: File) -> Self

Converts to this type from the input type.

impl From<TokioCompatFile> for File

fn from(file: TokioCompatFile) -> Self

Converts to this type from the input type.