Table of Contents

Class SftpClient

Namespace
SshSharp.Sftp
Assembly
SshSharp.dll

An SFTP session (version 3, as OpenSSH's sftp-server and internal-sftp speak it) over an SshClient: files, directories, links and attributes, file streams, and pipelined uploads and downloads. Open one with OpenSftpAsync(SshClient, CancellationToken); several can share a connection, and one may be used by several callers at once.

public sealed class SftpClient : IAsyncDisposable
Inheritance
SftpClient
Implements
Inherited Members

Remarks

Remote paths are passed to the server as they are: relative ones are relative to the login directory, and / is the separator, whatever this machine uses.

Properties

Extensions

The protocol extensions the server announced, with their versions, for example posix-rename@openssh.com = 1.

Limits

The server's limits (limits@openssh.com), or the defaults every server accepts when it announces none.

ProtocolVersion

The protocol version the server speaks (3 for OpenSSH).

Methods

CopyFileAsync(string, string, bool, CancellationToken)

Copies sourcePath to destinationPath on the server (copy-data): the data never travels through this machine. The destination is created, or with overwrite replaced.

CreateDirectoryAsync(string, UnixFileMode?, CancellationToken)

Creates a directory, with permissions if given (the server's umask applies).

CreateHardLinkAsync(string, string, CancellationToken)

Creates the hard link linkPath to the file existingPath (hardlink@openssh.com).

CreateSymbolicLinkAsync(string, string, CancellationToken)

Creates the symbolic link linkPath pointing to targetPath (stored as given).

DeleteDirectoryAsync(string, CancellationToken)

Deletes an empty directory.

DeleteFileAsync(string, CancellationToken)

Deletes a file (or a symbolic link, not its target).

DisposeAsync()

Ends the SFTP session (the SSH connection stays up). Requests still waiting fail.

DownloadAsync(string, Stream, SftpTransferOptions?, CancellationToken)

Downloads remotePath into destination, with several reads in flight (the window, by default 64 reads of up to MaxReadLength), which is what makes SFTP fast on links with latency.

DownloadDirectoryAsync(string, string, SftpTransferOptions?, CancellationToken)

Downloads the directory remoteDirectory and everything under it into localDirectory (created if needed), file by file with DownloadFileAsync(string, string, SftpTransferOptions?, CancellationToken) and the same options. Symbolic links and special files are skipped, so a link cannot lead the download outside the tree.

DownloadFileAsync(string, string, SftpTransferOptions?, CancellationToken)

Downloads remotePath to the local file localPath. With Overwrite off, an existing local file is an error; with Preserve, the local file gets the remote one's modification and access times, and its permissions where this system has Unix modes. A failed download leaves no partial file behind.

ExistsAsync(string, CancellationToken)

Whether path exists (following symbolic links: a dangling link does not).

ExpandPathAsync(string, CancellationToken)

path with a leading ~ or ~user expanded and made canonical, as sftp does for cd ~/dir (expand-path@openssh.com, OpenSSH 8.7+). Without the extension, ~ and ~/... start at GetHomeDirectoryAsync(CancellationToken), and a path without a tilde resolves as GetFullPathAsync(string, CancellationToken) does.

GetAttributesAsync(string, bool, CancellationToken)

The attributes of path; of the link itself when followSymbolicLinks is false.

GetFileSystemInfoAsync(string, CancellationToken)

The size and free space of the file system that holds path, as df shows them (statvfs@openssh.com).

GetFullPathAsync(string, CancellationToken)

The canonical absolute form of path (. is the login directory), as the server resolves it.

GetHomeDirectoryAsync(CancellationToken)

The login directory: the server's home-directory extension when it has one, otherwise what . resolves to. In an OpenSSH ChrootDirectory session the extension answers the passwd home, outside the chroot; relative paths resolve from GetFullPathAsync(string, CancellationToken) of ..

GetOwnerNamesAsync(IEnumerable<uint>, IEnumerable<uint>, CancellationToken)

The names of user and group ids, as ls -l shows them (users-groups-by-id@openssh.com, OpenSSH 9.1+).

ListDirectoryAsync(string, CancellationToken)

Lists a directory, without . and ... Entries arrive in batches as the server sends them; names that cannot be file names in one directory (empty, or with a /) are left out.

OpenAsync(string, FileMode, FileAccess, CancellationToken)

Opens a remote file as a seekable Stream (asynchronous reads and writes only). mode works as for FileStream: Create creates or truncates, CreateNew fails if the file exists, Append starts at the end. Disposing the stream closes the remote file.

OpenReadAsync(string, CancellationToken)

Opens a remote file for reading, as OpenAsync(string, FileMode, FileAccess, CancellationToken) with Open and Read.

OpenWriteAsync(string, CancellationToken)

Creates or truncates a remote file for writing, as OpenAsync(string, FileMode, FileAccess, CancellationToken) with Create.

ReadSymbolicLinkAsync(string, CancellationToken)

The target of the symbolic link path, as stored in the link.

RenameAsync(string, string, bool, CancellationToken)

Renames or moves oldPath to newPath. Plain SFTP refuses when newPath exists; with overwrite it is replaced atomically, which needs the server's posix-rename@openssh.com.

SetAttributesAsync(string, SftpFileAttributes, bool, CancellationToken)

Changes the attributes that are set in attributes; of a symbolic link itself when followSymbolicLinks is false (lsetstat@openssh.com, OpenSSH 8.0+: owner, permissions and times; a server may refuse a size).

SetAttributesAsync(string, SftpFileAttributes, CancellationToken)

Changes the attributes that are set in attributes (size, owner, permissions, times).

UploadAsync(Stream, string, SftpTransferOptions?, CancellationToken)

Uploads source (read to its end) to remotePath, with several writes in flight. The remote file is created or, with Overwrite, truncated.

UploadDirectoryAsync(string, string, SftpTransferOptions?, CancellationToken)

Uploads the local directory localDirectory and everything under it to remoteDirectory (created if needed), file by file with UploadFileAsync(string, string, SftpTransferOptions?, CancellationToken) and the same options. Symbolic links, junctions and other reparse points are skipped, and so are special files on Unix (FIFOs, sockets, devices).

UploadFileAsync(string, string, SftpTransferOptions?, CancellationToken)

Uploads the local file localPath to remotePath. With Preserve, the remote file gets the local one's modification and access times, and its permissions where this system has Unix modes.

Edit this page