Although Session makes it easy to do SFTP operations serially, you can also set up
multiple operations to be done in parallel, too, without needing to resort
to threading. You merely need to fire off the requests, and then run the
event loop until all of the requests
have completed:

The convention with the names of the operations is as follows: if the
method name ends with an exclamation mark, like read!, it will be synchronous (e.g., it
will block until the server responds).
Methods without an exclamation mark (e.g. read) are asynchronous, and return before
the server has responded. You will need to make sure the SSH event loop is
run in order to process these requests. (See loop.)

Public Class methods

Creates a newNet::SFTP instance atop the given Net::SSH connection. This will return immediately,
before the SFTP connection has been properly
initialized. Once the connection is ready, the given block will be called. If you want to block until the connection has been
initialized, try this:

Closes the SFTP connection, but not the SSH connection. Blocks until the session has
terminated. Once the session has terminated, further operations on this
object will result in errors. You can reopen the SFTP session via the connect method.

Attempts to establish an SFTP connection over
the SSH session given when this object was
instantiated. If the object is already open, this will simply execute the given block (if any), passing the SFTP session itself as argument. If the session is
currently being opened, this will add the given block to the list of callbacks, to be
executed when the session is fully open.

This method does not block, and will
return immediately. If you pass a block
to it, that block will be invoked when
the connection has been fully established. Thus, you can do something like
this:

sftp.connect do
puts "open!"
end

If you just want to block until the
connection is ready, see the connect!
method.

The fsetstat method is identical to the
setstat method, with the exception that
it takes a handle as the first parameter, such as would be
obtained via the open or opendir methods. (See the setstat method for full documentation.)

The fstat method is identical to the stat and lstat methods, with the exception that it
takes a handle as the first parameter, such as would be obtained
via the open or opendir methods. (See the lstat method for full documentation).

Identical to the fstat method, but
blocks until the server responds. It will raise a StatusException if the request was
unsuccessful. Otherwise, it will return the attribute object describing the
path.

Attempts to create a link, either hard
or symbolic. This operation is only available in SFTP protocol versions 6 and higher. If the symlink paramter is true, a symbolic
link will be created, otherwise a hard
link will be created. The link will be named new_link_path,
and will point to the path existing_path.

sftp.link("/path/to/symlink", "/path/to/file", true).wait

Note that link is only available for SFTP protocol 6 and higher. You can use symlink for protocols 3 and higher.

Runs the SSH event loop while the given block returns true. This lets you set up a
state machine and then "fire it off". If you do not specify a block, the event loop will run for as long as there are any
pending SFTP requests. This makes it easy to do
thing like this:

This method is identical to the stat
method, with the exception that it will not follow symbolic links (thus
allowing you to stat the link itself, rather than what it refers
to). The flags parameter is not used in SFTP protocol versions prior to 4, and will be
ignored in those versions of the protocol that do not use it. For those
that do, however, you may provide hints as to which file proprties you wish to query (e.g., if
all you want is permissions, you could pass the
Net::SFTP::Protocol::V04::Attributes::F_PERMISSIONS flag as the value for
the flags parameter).

Identical to the lstat method, but
blocks until the server responds. It will raise a StatusException if the request was
unsuccessful. Otherwise, it will return the attribute object describing the
path.

Opens a file on the remote server. The
flags parameter determines how the flag is open, and accepts the same format as
IO#open (e.g., either a string like "r" or "w", or a
combination of the IO constants). The options parameter is a hash
of attributes to be associated with the file, and varies greatly depending on the
SFTP protocol version in use, but some (like
:permissions) are always available.

Returns immediately with a Request object. If a
block is given, it will be invoked when
the server responds, with a Response object as
the only parameter. The :handle property of the response is the handle of
the opened file, and may be passed to
other methods (like close, read, write, and so forth).

Attempts to open a directory on the
remote host for reading. Once the handle is obtained, directory entries may
be retrieved using the readdir method.
The method returns immediately with a Request
object. If a block is given, it will be
invoked when the server responds.

Requests that length bytes, starting at offset bytes from
the beginning of the file, be read from the file identified by handle. (The
handle should be a value obtained via the open method.) Returns immediately with a Request object. If a block is given, it will be invoked when the
server responds.

The :data property of the response will contain the requested data,
assuming the call was successful.

Identical to read, but blocks until the
server responds. It will raise a StatusException if the request was
unsuccessful. If the end of the file was
reached, nil will be returned. Otherwise, it returns the data that
was read, as a String.

Reads a set of entries from the given directory handle (which must have
been obtained via opendir). If the
response is EOF, then there are no more entries in the directory.
Otherwise, the entries will be in the :names property of the response:

Identical to readdir, but blocks until
the server responds. It will raise a StatusException if the request was
unsuccessful. Otherwise, it will return nil if there were no more names to
read, or an array of name entries.

Queries the server for the target of the specified symbolic link. This operation is only available in
protocol versions 3 and higher. The response to this request will include a
names property, a one-element array naming the target of the symlink.

Identical to readlink, but blocks until
the server responds. It will raise a StatusException if the request was
unsuccessful. Otherwise, it will return the Name object for the path that
the symlink targets.

Tries to canonicalize the given path, turning any given path into an
absolute path. This is primarily useful for converting a path with
".." or "." segments into an identical path without
those segments. The answer will be in the response‘s :names
attribute, as a one-element array.

Attempts to remove the given file from the remote file system. Returns immediately with a Request object. If a block is given, the block will be invoked when the server
responds, and will be passed a Response object.

Renames the given file. This operation
is only available in SFTP protocol versions two
and higher. The flags parameter is ignored in versions prior to 5.
In versions 5 and higher, the flags parameter can be used to
specify how the rename should be
performed (atomically, etc.).

The following flags are defined in protocol version 5:

0x0001 - overwrite an existing file if
the new name specifies a file that already exists.

This method may be used to set file
metadata (such as permissions, or user/group information) on a remote file. The exact metadata that may be
tweaked is dependent on the SFTP protocol
version in use, but in general you may set at least the permissions, user,
and group. (See Protocol::V01::Attributes, Protocol::V04::Attributes, and Protocol::V06::Attributes for the
full lists of attributes that may be set for the different protocols.)

The attrs parameter is a hash, where the keys are symbols
identifying the attributes to set.

The method returns immediately with a Request
object. If a block is given, it will be
invoked when the server responds.

Identical to the lstat method, except
that it follows symlinks (e.g., if you give it the path to a symlink, it will stat the target of the symlink rather than the symlink itself). See the lstat method for full documentation.

Attempts to create a symlink to
path at target. This operation is only available in
protocol versions 3, 4, and 5, but the Net::SFTP
library mimics the symlink behavior in
protocol version 6 using the link
method, so it is safe to use this method in protocol version 6.

Removes a previously created byte-range lock. This operation is only
available in protocol versions 6 and higher. The offset and
length parameters must exactly match those that were given to block when the lock was acquired.

Requests that data be written to the file identified by handle,
starting at offset bytes from the start of the file. The file must have been opened for writing via
open. Returns immediately with a Request object. If a block is given, it will be invoked when the
server responds.

Identical to write, but blocks until the
server responds. It will raise a StatusException if the request was
unsuccessful, or the end of the file was
reached. Otherwise, it returns the Response
object for this request.