Class Net::SFTP::Session
In: lib/net/sftp/session.rb
lib/net/sftp/session.rb
Parent: Object

The Session class encapsulates a single SFTP channel on a Net::SSH connection. Instances of this class are what most applications will interact with most, as it provides access to both low-level (mkdir, rename, remove, symlink, etc.) and high-level (upload, download, etc.) SFTP operations.

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:

  handle1 = sftp.open!("/path/to/file1")
  handle2 = sftp.open!("/path/to/file2")

  r1 = sftp.read(handle1, 0, 1024)
  r2 = sftp.read(handle2, 0, 1024)
  sftp.loop { [r1, r2].any? { |r| r.pending? } }

  puts "chunk #1: #{r1.response[:data]}"
  puts "chunk #2: #{r2.response[:data]}"

By passing blocks to the operations, you can set up powerful state machines, to fire off subsequent operations. In fact, the Net::SFTP::Operations::Upload and Net::SFTP::Operations::Download classes set up such state machines, so that multiple uploads and/or downloads can be running simultaneously.

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

Methods

block   block   block!   block!   close   close   close!   close!   close_channel   close_channel   closed?   closed?   connect   connect   connect!   connect!   dir   dir   download   download   download!   download!   file   file   fsetstat   fsetstat   fsetstat!   fsetstat!   fstat   fstat   fstat!   fstat!   link   link   link!   link!   loop   loop   loop_forever   lstat   lstat   lstat!   lstat!   mkdir   mkdir   mkdir!   mkdir!   new   new   open   open   open!   open!   open?   open?   opendir   opendir   opendir!   opendir!   opening?   opening?   read   read   read!   read!   readdir   readdir   readdir!   readdir!   readlink   readlink   readlink!   readlink!   realpath   realpath   realpath!   realpath!   remove   remove   remove!   remove!   rename   rename   rename!   rename!   rmdir   rmdir   rmdir!   rmdir!   send_packet   send_packet   setstat   setstat   setstat!   setstat!   stat   stat   stat!   stat!   symlink   symlink   symlink!   symlink!   unblock   unblock   unblock!   unblock!   upload   upload   upload!   upload!   write   write   write!   write!  

Included Modules

Net::SSH::Loggable Net::SFTP::Constants::PacketTypes Net::SSH::Loggable Net::SFTP::Constants::PacketTypes

Constants

HIGHEST_PROTOCOL_VERSION_SUPPORTED = 6   The highest protocol version supported by the Net::SFTP library.
HIGHEST_PROTOCOL_VERSION_SUPPORTED = 6   The highest protocol version supported by the Net::SFTP library.

External Aliases

loop -> loop_forever

Attributes

channel  [R]  The Net::SSH::Connection::Channel object that the SFTP session is being processed by.
channel  [R]  The Net::SSH::Connection::Channel object that the SFTP session is being processed by.
pending_requests  [R]  The hash of pending requests. Any requests that have been sent and which the server has not yet responded to will be represented here.
pending_requests  [R]  The hash of pending requests. Any requests that have been sent and which the server has not yet responded to will be represented here.
protocol  [R]  The protocol instance being used by this SFTP session. Useful for querying the protocol version in effect.
protocol  [R]  The protocol instance being used by this SFTP session. Useful for querying the protocol version in effect.
session  [R]  A reference to the Net::SSH session object that powers this SFTP session.
session  [R]  A reference to the Net::SSH session object that powers this SFTP session.
state  [R]  The state of the SFTP connection. It will be :opening, :subsystem, :init, :open, or :closed.
state  [R]  The state of the SFTP connection. It will be :opening, :subsystem, :init, :open, or :closed.

Public Class methods

Creates a new Net::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:

  sftp = Net::SFTP::Session.new(ssh)
  sftp.loop { sftp.opening? }

[Source]

    # File lib/net/sftp/session.rb, line 78
78:     def initialize(session, &block)
79:       @session    = session
80:       @input      = Net::SSH::Buffer.new
81:       self.logger = session.logger
82:       @state      = :closed
83: 
84:       connect(&block)
85:     end

Creates a new Net::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:

  sftp = Net::SFTP::Session.new(ssh)
  sftp.loop { sftp.opening? }

[Source]

    # File lib/net/sftp/session.rb, line 78
78:     def initialize(session, &block)
79:       @session    = session
80:       @input      = Net::SSH::Buffer.new
81:       self.logger = session.logger
82:       @state      = :closed
83: 
84:       connect(&block)
85:     end

Public Instance methods

Creates a byte-range lock on the file specified by the given handle. This operation is only available in SFTP protocol versions 6 and higher. The lock may be either mandatory or advisory.

The handle parameter is a file handle, as obtained by the open method.

The offset and length parameters describe the location and size of the byte range.

The mask describes how the lock should be defined, and consists of some combination of the following bit masks:

  • 0x0040 - Read lock. The byte range may not be accessed for reading by via any other handle, though it may be written to.
  • 0x0080 - Write lock. The byte range may not be written to via any other handle, though it may be read from.
  • 0x0100 - Delete lock. No other handle may delete this file.
  • 0x0200 - Advisory lock. The server need not honor the lock instruction.

Once created, the lock may be removed via the unblock method.

[Source]

     # File lib/net/sftp/session.rb, line 691
691:       def block(handle, offset, length, mask, &callback)
692:         request :block, handle, offset, length, mask, &callback
693:       end

Creates a byte-range lock on the file specified by the given handle. This operation is only available in SFTP protocol versions 6 and higher. The lock may be either mandatory or advisory.

The handle parameter is a file handle, as obtained by the open method.

The offset and length parameters describe the location and size of the byte range.

The mask describes how the lock should be defined, and consists of some combination of the following bit masks:

  • 0x0040 - Read lock. The byte range may not be accessed for reading by via any other handle, though it may be written to.
  • 0x0080 - Write lock. The byte range may not be written to via any other handle, though it may be read from.
  • 0x0100 - Delete lock. No other handle may delete this file.
  • 0x0200 - Advisory lock. The server need not honor the lock instruction.

Once created, the lock may be removed via the unblock method.

[Source]

     # File lib/net/sftp/session.rb, line 691
691:       def block(handle, offset, length, mask, &callback)
692:         request :block, handle, offset, length, mask, &callback
693:       end

Identical to block, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

[Source]

     # File lib/net/sftp/session.rb, line 698
698:       def block!(handle, offset, length, mask, &callback)
699:         wait_for(block(handle, offset, length, mask, &callback))
700:       end

Identical to block, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

[Source]

     # File lib/net/sftp/session.rb, line 698
698:       def block!(handle, offset, length, mask, &callback)
699:         wait_for(block(handle, offset, length, mask, &callback))
700:       end

Closes an open handle, whether obtained via open, or opendir. Returns immediately with a Request object. If a block is given, it will be invoked when the server responds.

  sftp.open("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 207
207:       def close(handle, &callback)
208:         request :close, handle, &callback
209:       end

Closes an open handle, whether obtained via open, or opendir. Returns immediately with a Request object. If a block is given, it will be invoked when the server responds.

  sftp.open("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 207
207:       def close(handle, &callback)
208:         request :close, handle, &callback
209:       end

Identical to close, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it returns the Response object for this request.

  sftp.close!(handle)

[Source]

     # File lib/net/sftp/session.rb, line 216
216:       def close!(handle, &callback)
217:         wait_for(close(handle, &callback))
218:       end

Identical to close, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it returns the Response object for this request.

  sftp.close!(handle)

[Source]

     # File lib/net/sftp/session.rb, line 216
216:       def close!(handle, &callback)
217:         wait_for(close(handle, &callback))
218:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 727
727:       def close_channel
728:         return unless open?
729:         channel.close
730:         loop { !closed? }
731:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 727
727:       def close_channel
728:         return unless open?
729:         channel.close
730:         loop { !closed? }
731:       end

Returns true if the connection has been closed.

[Source]

     # File lib/net/sftp/session.rb, line 739
739:       def closed?
740:         state == :closed
741:       end

Returns true if the connection has been closed.

[Source]

     # File lib/net/sftp/session.rb, line 739
739:       def closed?
740:         state == :closed
741:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 766
766:       def connect(&block)
767:         case state
768:         when :open
769:           block.call(self) if block
770:         when :closed
771:           @state = :opening
772:           @channel = session.open_channel(&method(:when_channel_confirmed))
773:           @packet_length = nil
774:           @protocol = nil
775:           @on_ready = Array(block)
776:         else # opening
777:           @on_ready << block if block
778:         end
779: 
780:         self
781:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 766
766:       def connect(&block)
767:         case state
768:         when :open
769:           block.call(self) if block
770:         when :closed
771:           @state = :opening
772:           @channel = session.open_channel(&method(:when_channel_confirmed))
773:           @packet_length = nil
774:           @protocol = nil
775:           @on_ready = Array(block)
776:         else # opening
777:           @on_ready << block if block
778:         end
779: 
780:         self
781:       end

Same as the connect method, but blocks until the SFTP connection has been fully initialized.

[Source]

     # File lib/net/sftp/session.rb, line 785
785:       def connect!(&block)
786:         connect(&block)
787:         loop { opening? }
788:         self
789:       end

Same as the connect method, but blocks until the SFTP connection has been fully initialized.

[Source]

     # File lib/net/sftp/session.rb, line 785
785:       def connect!(&block)
786:         connect(&block)
787:         loop { opening? }
788:         self
789:       end

Returns a Net::SFTP::Operations::Dir instance, which can be used to conveniently iterate over and search directories on the remote server.

 sftp.dir.glob("/base/path", "*/**/*.rb") do |entry|
   p entry.name
 end

See Net::SFTP::Operations::Dir for a more detailed discussion of how to use this.

[Source]

     # File lib/net/sftp/session.rb, line 153
153:       def dir
154:         @dir ||= Operations::Dir.new(self)
155:       end

Returns a Net::SFTP::Operations::Dir instance, which can be used to conveniently iterate over and search directories on the remote server.

 sftp.dir.glob("/base/path", "*/**/*.rb") do |entry|
   p entry.name
 end

See Net::SFTP::Operations::Dir for a more detailed discussion of how to use this.

[Source]

     # File lib/net/sftp/session.rb, line 153
153:       def dir
154:         @dir ||= Operations::Dir.new(self)
155:       end

Initiates a download from remote to local, asynchronously. This method will return a new Net::SFTP::Operations::Download instance, and requires that the event loop be run in order for the download to progress. See Net::SFTP::Operations::Download for a full discussion of hos this method can be used.

  download = sftp.download("/remote/path", "/local/path")
  download.wait

[Source]

     # File lib/net/sftp/session.rb, line 114
114:       def download(remote, local, options={}, &block)
115:         Operations::Download.new(self, local, remote, options, &block)
116:       end

Initiates a download from remote to local, asynchronously. This method will return a new Net::SFTP::Operations::Download instance, and requires that the event loop be run in order for the download to progress. See Net::SFTP::Operations::Download for a full discussion of hos this method can be used.

  download = sftp.download("/remote/path", "/local/path")
  download.wait

[Source]

     # File lib/net/sftp/session.rb, line 114
114:       def download(remote, local, options={}, &block)
115:         Operations::Download.new(self, local, remote, options, &block)
116:       end

Identical to download, but blocks until the download is complete. If local is omitted, downloads the file to an in-memory buffer and returns the result as a string; otherwise, returns the Net::SFTP::Operations::Download instance.

[Source]

     # File lib/net/sftp/session.rb, line 122
122:       def download!(remote, local=nil, options={}, &block)
123:         require 'stringio' unless defined?(StringIO)
124:         destination = local || StringIO.new
125:         result = download(remote, destination, options, &block).wait
126:         local ? result : destination.string
127:       end

Identical to download, but blocks until the download is complete. If local is omitted, downloads the file to an in-memory buffer and returns the result as a string; otherwise, returns the Net::SFTP::Operations::Download instance.

[Source]

     # File lib/net/sftp/session.rb, line 122
122:       def download!(remote, local=nil, options={}, &block)
123:         require 'stringio' unless defined?(StringIO)
124:         destination = local || StringIO.new
125:         result = download(remote, destination, options, &block).wait
126:         local ? result : destination.string
127:       end

Returns an Net::SFTP::Operations::FileFactory instance, which can be used to mimic synchronous, IO-like file operations on a remote file via SFTP.

  sftp.file.open("/path/to/file") do |file|
    while line = file.gets
      puts line
    end
  end

See Net::SFTP::Operations::FileFactory and Net::SFTP::Operations::File for more details.

[Source]

     # File lib/net/sftp/session.rb, line 140
140:       def file
141:         @file ||= Operations::FileFactory.new(self)
142:       end

Returns an Net::SFTP::Operations::FileFactory instance, which can be used to mimic synchronous, IO-like file operations on a remote file via SFTP.

  sftp.file.open("/path/to/file") do |file|
    while line = file.gets
      puts line
    end
  end

See Net::SFTP::Operations::FileFactory and Net::SFTP::Operations::File for more details.

[Source]

     # File lib/net/sftp/session.rb, line 140
140:       def file
141:         @file ||= Operations::FileFactory.new(self)
142:       end

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

[Source]

     # File lib/net/sftp/session.rb, line 378
378:       def fsetstat(handle, attrs, &callback)
379:         request :fsetstat, handle, attrs, &callback
380:       end

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

[Source]

     # File lib/net/sftp/session.rb, line 378
378:       def fsetstat(handle, attrs, &callback)
379:         request :fsetstat, handle, attrs, &callback
380:       end

Identical to the fsetstat method, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.fsetstat!(handle, :permissions => 0644)

[Source]

     # File lib/net/sftp/session.rb, line 387
387:       def fsetstat!(handle, attrs, &callback)
388:         wait_for(fsetstat(handle, attrs, &callback))
389:       end

Identical to the fsetstat method, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.fsetstat!(handle, :permissions => 0644)

[Source]

     # File lib/net/sftp/session.rb, line 387
387:       def fsetstat!(handle, attrs, &callback)
388:         wait_for(fsetstat(handle, attrs, &callback))
389:       end

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

[Source]

     # File lib/net/sftp/session.rb, line 327
327:       def fstat(handle, flags=nil, &callback)
328:         request :fstat, handle, flags, &callback
329:       end

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

[Source]

     # File lib/net/sftp/session.rb, line 327
327:       def fstat(handle, flags=nil, &callback)
328:         request :fstat, handle, flags, &callback
329:       end

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.

  puts sftp.fstat!(handle).permissions

[Source]

     # File lib/net/sftp/session.rb, line 336
336:       def fstat!(handle, flags=nil, &callback)
337:         wait_for(fstat(handle, flags, &callback), :attrs)
338:       end

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.

  puts sftp.fstat!(handle).permissions

[Source]

     # File lib/net/sftp/session.rb, line 336
336:       def fstat!(handle, flags=nil, &callback)
337:         wait_for(fstat(handle, flags, &callback), :attrs)
338:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 654
654:       def link(new_link_path, existing_path, symlink=true, &callback)
655:         request :link, new_link_path, existing_path, symlink, &callback
656:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 654
654:       def link(new_link_path, existing_path, symlink=true, &callback)
655:         request :link, new_link_path, existing_path, symlink, &callback
656:       end

Identical to link, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

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

[Source]

     # File lib/net/sftp/session.rb, line 663
663:       def link!(new_link_path, existing_path, symlink=true, &callback)
664:         wait_for(link(new_link_path, existing_path, symlink, &callback))
665:       end

Identical to link, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

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

[Source]

     # File lib/net/sftp/session.rb, line 663
663:       def link!(new_link_path, existing_path, symlink=true, &callback)
664:         wait_for(link(new_link_path, existing_path, symlink, &callback))
665:       end

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:

  sftp.remove("/path/to/file")
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 800
800:       def loop(&block)
801:         block ||= Proc.new { pending_requests.any? }
802:         session.loop(&block)
803:       end

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:

  sftp.remove("/path/to/file")
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 800
800:       def loop(&block)
801:         block ||= Proc.new { pending_requests.any? }
802:         session.loop(&block)
803:       end
loop_forever(&block)

Alias for loop

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

The method returns immediately with a Request object. If a block is given, it will be invoked when the server responds. The :attrs property of the response will contain an Attributes instance appropriate for the the protocol version (see Protocol::V01::Attributes, Protocol::V04::Attributes, and Protocol::V06::Attributes).

  request = sftp.lstat("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    puts "permissions: %04o" % response[:attrs].permissions
  end
  request.wait

[Source]

     # File lib/net/sftp/session.rb, line 310
310:       def lstat(path, flags=nil, &callback)
311:         request :lstat, path, flags, &callback
312:       end

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

The method returns immediately with a Request object. If a block is given, it will be invoked when the server responds. The :attrs property of the response will contain an Attributes instance appropriate for the the protocol version (see Protocol::V01::Attributes, Protocol::V04::Attributes, and Protocol::V06::Attributes).

  request = sftp.lstat("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    puts "permissions: %04o" % response[:attrs].permissions
  end
  request.wait

[Source]

     # File lib/net/sftp/session.rb, line 310
310:       def lstat(path, flags=nil, &callback)
311:         request :lstat, path, flags, &callback
312:       end

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.

  puts sftp.lstat!("/path/to/file").permissions

[Source]

     # File lib/net/sftp/session.rb, line 319
319:       def lstat!(path, flags=nil, &callback)
320:         wait_for(lstat(path, flags, &callback), :attrs)
321:       end

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.

  puts sftp.lstat!("/path/to/file").permissions

[Source]

     # File lib/net/sftp/session.rb, line 319
319:       def lstat!(path, flags=nil, &callback)
320:         wait_for(lstat(path, flags, &callback), :attrs)
321:       end

Creates the named directory on the remote server. If an attribute hash is given, it must map to the set of attributes supported by the version of the SFTP protocol in use. (See Protocol::V01::Attributes, Protocol::V04::Attributes, and Protocol::V06::Attributes.)

  sftp.mkdir("/path/to/directory", :permissions => 0550).wait

[Source]

     # File lib/net/sftp/session.rb, line 488
488:       def mkdir(path, attrs={}, &callback)
489:         request :mkdir, path, attrs, &callback
490:       end

Creates the named directory on the remote server. If an attribute hash is given, it must map to the set of attributes supported by the version of the SFTP protocol in use. (See Protocol::V01::Attributes, Protocol::V04::Attributes, and Protocol::V06::Attributes.)

  sftp.mkdir("/path/to/directory", :permissions => 0550).wait

[Source]

     # File lib/net/sftp/session.rb, line 488
488:       def mkdir(path, attrs={}, &callback)
489:         request :mkdir, path, attrs, &callback
490:       end

Identical to mkdir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.mkdir!("/path/to/directory", :permissions => 0550)

[Source]

     # File lib/net/sftp/session.rb, line 497
497:       def mkdir!(path, attrs={}, &callback)
498:         wait_for(mkdir(path, attrs, &callback))
499:       end

Identical to mkdir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.mkdir!("/path/to/directory", :permissions => 0550)

[Source]

     # File lib/net/sftp/session.rb, line 497
497:       def mkdir!(path, attrs={}, &callback)
498:         wait_for(mkdir(path, attrs, &callback))
499:       end

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

  sftp.open("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 181
181:       def open(path, flags="r", options={}, &callback)
182:         request :open, path, flags, options, &callback
183:       end

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

  sftp.open("/path/to/file") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 181
181:       def open(path, flags="r", options={}, &callback)
182:         request :open, path, flags, options, &callback
183:       end

Identical to open, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the handle of the newly opened file.

  handle = sftp.open!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 190
190:       def open!(path, flags="r", options={}, &callback)
191:         wait_for(open(path, flags, options, &callback), :handle)
192:       end

Identical to open, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the handle of the newly opened file.

  handle = sftp.open!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 190
190:       def open!(path, flags="r", options={}, &callback)
191:         wait_for(open(path, flags, options, &callback), :handle)
192:       end

Returns true if the connection has been initialized.

[Source]

     # File lib/net/sftp/session.rb, line 734
734:       def open?
735:         state == :open
736:       end

Returns true if the connection has been initialized.

[Source]

     # File lib/net/sftp/session.rb, line 734
734:       def open?
735:         state == :open
736:       end

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.

  sftp.opendir("/path/to/directory") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 405
405:       def opendir(path, &callback)
406:         request :opendir, path, &callback
407:       end

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.

  sftp.opendir("/path/to/directory") do |response|
    raise "fail!" unless response.ok?
    sftp.close(response[:handle])
  end
  sftp.loop

[Source]

     # File lib/net/sftp/session.rb, line 405
405:       def opendir(path, &callback)
406:         request :opendir, path, &callback
407:       end

Identical to opendir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return a handle to the given path.

  handle = sftp.opendir!("/path/to/directory")

[Source]

     # File lib/net/sftp/session.rb, line 414
414:       def opendir!(path, &callback)
415:         wait_for(opendir(path, &callback), :handle)
416:       end

Identical to opendir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return a handle to the given path.

  handle = sftp.opendir!("/path/to/directory")

[Source]

     # File lib/net/sftp/session.rb, line 414
414:       def opendir!(path, &callback)
415:         wait_for(opendir(path, &callback), :handle)
416:       end

Returns true if the connection is in the process of being initialized (e.g., it is not closed, but is not yet fully open).

[Source]

     # File lib/net/sftp/session.rb, line 745
745:       def opening?
746:         !(open? || closed?)
747:       end

Returns true if the connection is in the process of being initialized (e.g., it is not closed, but is not yet fully open).

[Source]

     # File lib/net/sftp/session.rb, line 745
745:       def opening?
746:         !(open? || closed?)
747:       end

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.

  request = sftp.read(handle, 0, 1024) do |response|
    if response.eof?
      puts "end of file reached before reading any data"
    elsif !response.ok?
      puts "error (#{response})"
    else
      print(response[:data])
    end
  end
  request.wait

To read an entire file will usually require multiple calls to read, unless you know in advance how large the file is.

[Source]

     # File lib/net/sftp/session.rb, line 246
246:       def read(handle, offset, length, &callback)
247:         request :read, handle, offset, length, &callback
248:       end

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.

  request = sftp.read(handle, 0, 1024) do |response|
    if response.eof?
      puts "end of file reached before reading any data"
    elsif !response.ok?
      puts "error (#{response})"
    else
      print(response[:data])
    end
  end
  request.wait

To read an entire file will usually require multiple calls to read, unless you know in advance how large the file is.

[Source]

     # File lib/net/sftp/session.rb, line 246
246:       def read(handle, offset, length, &callback)
247:         request :read, handle, offset, length, &callback
248:       end

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.

  data = sftp.read!(handle, 0, 1024)

[Source]

     # File lib/net/sftp/session.rb, line 256
256:       def read!(handle, offset, length, &callback)
257:         wait_for(read(handle, offset, length, &callback), :data)
258:       end

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.

  data = sftp.read!(handle, 0, 1024)

[Source]

     # File lib/net/sftp/session.rb, line 256
256:       def read!(handle, offset, length, &callback)
257:         wait_for(read(handle, offset, length, &callback), :data)
258:       end

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:

  loop do
    request = sftp.readdir(handle).wait
    break if request.response.eof?
    raise "fail!" unless request.response.ok?
    request.response[:names].each do |entry|
       puts entry.name
    end
  end

See also Protocol::V01::Name and Protocol::V04::Name for the specific properties of each individual entry (which vary based on the SFTP protocol version in use).

[Source]

     # File lib/net/sftp/session.rb, line 439
439:       def readdir(handle, &callback)
440:         request :readdir, handle, &callback
441:       end

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:

  loop do
    request = sftp.readdir(handle).wait
    break if request.response.eof?
    raise "fail!" unless request.response.ok?
    request.response[:names].each do |entry|
       puts entry.name
    end
  end

See also Protocol::V01::Name and Protocol::V04::Name for the specific properties of each individual entry (which vary based on the SFTP protocol version in use).

[Source]

     # File lib/net/sftp/session.rb, line 439
439:       def readdir(handle, &callback)
440:         request :readdir, handle, &callback
441:       end

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.

  while (entries = sftp.readdir!(handle)) do
    entries.each { |entry| puts(entry.name) }
  end

[Source]

     # File lib/net/sftp/session.rb, line 451
451:       def readdir!(handle, &callback)
452:         wait_for(readdir(handle, &callback), :names)
453:       end

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.

  while (entries = sftp.readdir!(handle)) do
    entries.each { |entry| puts(entry.name) }
  end

[Source]

     # File lib/net/sftp/session.rb, line 451
451:       def readdir!(handle, &callback)
452:         wait_for(readdir(handle, &callback), :names)
453:       end

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.

  request = sftp.readlink("/path/to/symlink").wait
  puts request.response[:names].first.name

[Source]

     # File lib/net/sftp/session.rb, line 604
604:       def readlink(path, &callback)
605:         request :readlink, path, &callback
606:       end

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.

  request = sftp.readlink("/path/to/symlink").wait
  puts request.response[:names].first.name

[Source]

     # File lib/net/sftp/session.rb, line 604
604:       def readlink(path, &callback)
605:         request :readlink, path, &callback
606:       end

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.

  item = sftp.readlink!("/path/to/symlink")

[Source]

     # File lib/net/sftp/session.rb, line 613
613:       def readlink!(path, &callback)
614:         wait_for(readlink(path, &callback), :names).first
615:       end

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.

  item = sftp.readlink!("/path/to/symlink")

[Source]

     # File lib/net/sftp/session.rb, line 613
613:       def readlink!(path, &callback)
614:         wait_for(readlink(path, &callback), :names).first
615:       end

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.

  request = sftp.realpath("/path/../to/../directory").wait
  puts request[:names].first.name

[Source]

     # File lib/net/sftp/session.rb, line 534
534:       def realpath(path, &callback)
535:         request :realpath, path, &callback
536:       end

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.

  request = sftp.realpath("/path/../to/../directory").wait
  puts request[:names].first.name

[Source]

     # File lib/net/sftp/session.rb, line 534
534:       def realpath(path, &callback)
535:         request :realpath, path, &callback
536:       end

Identical to realpath, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return a name object identifying the path.

  puts(sftp.realpath!("/path/../to/../directory"))

[Source]

     # File lib/net/sftp/session.rb, line 543
543:       def realpath!(path, &callback)
544:         wait_for(realpath(path, &callback), :names).first
545:       end

Identical to realpath, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return a name object identifying the path.

  puts(sftp.realpath!("/path/../to/../directory"))

[Source]

     # File lib/net/sftp/session.rb, line 543
543:       def realpath!(path, &callback)
544:         wait_for(realpath(path, &callback), :names).first
545:       end

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.

  sftp.remove("/path/to/file").wait

[Source]

     # File lib/net/sftp/session.rb, line 465
465:       def remove(filename, &callback)
466:         request :remove, filename, &callback
467:       end

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.

  sftp.remove("/path/to/file").wait

[Source]

     # File lib/net/sftp/session.rb, line 465
465:       def remove(filename, &callback)
466:         request :remove, filename, &callback
467:       end

Identical to remove, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.remove!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 474
474:       def remove!(filename, &callback)
475:         wait_for(remove(filename, &callback))
476:       end

Identical to remove, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.remove!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 474
474:       def remove!(filename, &callback)
475:         wait_for(remove(filename, &callback))
476:       end

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.
  • 0x0002 - perform the rewrite atomically.
  • 0x0004 - allow the server to perform the rename as it prefers.

[Source]

     # File lib/net/sftp/session.rb, line 580
580:       def rename(name, new_name, flags=nil, &callback)
581:         request :rename, name, new_name, flags, &callback
582:       end

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.
  • 0x0002 - perform the rewrite atomically.
  • 0x0004 - allow the server to perform the rename as it prefers.

[Source]

     # File lib/net/sftp/session.rb, line 580
580:       def rename(name, new_name, flags=nil, &callback)
581:         request :rename, name, new_name, flags, &callback
582:       end

Identical to rename, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.rename!("/path/to/old", "/path/to/new")

[Source]

     # File lib/net/sftp/session.rb, line 589
589:       def rename!(name, new_name, flags=nil, &callback)
590:         wait_for(rename(name, new_name, flags, &callback))
591:       end

Identical to rename, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.rename!("/path/to/old", "/path/to/new")

[Source]

     # File lib/net/sftp/session.rb, line 589
589:       def rename!(name, new_name, flags=nil, &callback)
590:         wait_for(rename(name, new_name, flags, &callback))
591:       end

Removes the named directory on the remote server. The directory must be empty before it can be removed.

  sftp.rmdir("/path/to/directory").wait

[Source]

     # File lib/net/sftp/session.rb, line 509
509:       def rmdir(path, &callback)
510:         request :rmdir, path, &callback
511:       end

Removes the named directory on the remote server. The directory must be empty before it can be removed.

  sftp.rmdir("/path/to/directory").wait

[Source]

     # File lib/net/sftp/session.rb, line 509
509:       def rmdir(path, &callback)
510:         request :rmdir, path, &callback
511:       end

Identical to rmdir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.rmdir!("/path/to/directory")

[Source]

     # File lib/net/sftp/session.rb, line 518
518:       def rmdir!(path, &callback)
519:         wait_for(rmdir(path, &callback))
520:       end

Identical to rmdir, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.rmdir!("/path/to/directory")

[Source]

     # File lib/net/sftp/session.rb, line 518
518:       def rmdir!(path, &callback)
519:         wait_for(rmdir(path, &callback))
520:       end

Formats, constructs, and sends an SFTP packet of the given type and with the given data. This does not block, but merely enqueues the packet for sending and returns.

You should probably use the operation methods, rather than building and sending the packet directly. (See open, close, etc.)

[Source]

     # File lib/net/sftp/session.rb, line 811
811:       def send_packet(type, *args)
812:         data = Net::SSH::Buffer.from(*args)
813:         msg = Net::SSH::Buffer.from(:long, data.length+1, :byte, type, :raw, data)
814:         channel.send_data(msg.to_s)
815:       end

Formats, constructs, and sends an SFTP packet of the given type and with the given data. This does not block, but merely enqueues the packet for sending and returns.

You should probably use the operation methods, rather than building and sending the packet directly. (See open, close, etc.)

[Source]

     # File lib/net/sftp/session.rb, line 811
811:       def send_packet(type, *args)
812:         data = Net::SSH::Buffer.from(*args)
813:         msg = Net::SSH::Buffer.from(:long, data.length+1, :byte, type, :raw, data)
814:         channel.send_data(msg.to_s)
815:       end

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.

  request = sftp.setstat("/path/to/file", :permissions => 0644)
  request.wait
  puts "success: #{request.response.ok?}"

[Source]

     # File lib/net/sftp/session.rb, line 361
361:       def setstat(path, attrs, &callback)
362:         request :setstat, path, attrs, &callback
363:       end

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.

  request = sftp.setstat("/path/to/file", :permissions => 0644)
  request.wait
  puts "success: #{request.response.ok?}"

[Source]

     # File lib/net/sftp/session.rb, line 361
361:       def setstat(path, attrs, &callback)
362:         request :setstat, path, attrs, &callback
363:       end

Identical to the setstat method, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.setstat!("/path/to/file", :permissions => 0644)

[Source]

     # File lib/net/sftp/session.rb, line 370
370:       def setstat!(path, attrs, &callback)
371:         wait_for(setstat(path, attrs, &callback))
372:       end

Identical to the setstat method, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

  sftp.setstat!("/path/to/file", :permissions => 0644)

[Source]

     # File lib/net/sftp/session.rb, line 370
370:       def setstat!(path, attrs, &callback)
371:         wait_for(setstat(path, attrs, &callback))
372:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 551
551:       def stat(path, flags=nil, &callback)
552:         request :stat, path, flags, &callback
553:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 551
551:       def stat(path, flags=nil, &callback)
552:         request :stat, path, flags, &callback
553:       end

Identical to stat, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return an attribute object for the named path.

  attrs = sftp.stat!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 560
560:       def stat!(path, flags=nil, &callback)
561:         wait_for(stat(path, flags, &callback), :attrs)
562:       end

Identical to stat, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return an attribute object for the named path.

  attrs = sftp.stat!("/path/to/file")

[Source]

     # File lib/net/sftp/session.rb, line 560
560:       def stat!(path, flags=nil, &callback)
561:         wait_for(stat(path, flags, &callback), :attrs)
562:       end

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.

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

[Source]

     # File lib/net/sftp/session.rb, line 627
627:       def symlink(path, target, &callback)
628:         request :symlink, path, target, &callback
629:       end

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.

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

[Source]

     # File lib/net/sftp/session.rb, line 627
627:       def symlink(path, target, &callback)
628:         request :symlink, path, target, &callback
629:       end

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

  sftp.symlink!("/path/to/file", "/path/to/symlink")

[Source]

     # File lib/net/sftp/session.rb, line 636
636:       def symlink!(path, target, &callback)
637:         wait_for(symlink(path, target, &callback))
638:       end

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

  sftp.symlink!("/path/to/file", "/path/to/symlink")

[Source]

     # File lib/net/sftp/session.rb, line 636
636:       def symlink!(path, target, &callback)
637:         wait_for(symlink(path, target, &callback))
638:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 710
710:       def unblock(handle, offset, length, &callback)
711:         request :unblock, handle, offset, length, &callback
712:       end

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.

[Source]

     # File lib/net/sftp/session.rb, line 710
710:       def unblock(handle, offset, length, &callback)
711:         request :unblock, handle, offset, length, &callback
712:       end

Identical to unblock, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

[Source]

     # File lib/net/sftp/session.rb, line 717
717:       def unblock!(handle, offset, length, &callback)
718:         wait_for(unblock(handle, offset, length, &callback))
719:       end

Identical to unblock, but blocks until the server responds. It will raise a StatusException if the request was unsuccessful. Otherwise, it will return the Response object for the request.

[Source]

     # File lib/net/sftp/session.rb, line 717
717:       def unblock!(handle, offset, length, &callback)
718:         wait_for(unblock(handle, offset, length, &callback))
719:       end

Initiates an upload from local to remote, asynchronously. This method will return a new Net::SFTP::Operations::Upload instance, and requires the event loop to be run in order for the upload to progress. See Net::SFTP::Operations::Upload for a full discussion of how this method can be used.

  uploader = sftp.upload("/local/path", "/remote/path")
  uploader.wait

[Source]

    # File lib/net/sftp/session.rb, line 97
97:       def upload(local, remote, options={}, &block)
98:         Operations::Upload.new(self, local, remote, options, &block)
99:       end

Initiates an upload from local to remote, asynchronously. This method will return a new Net::SFTP::Operations::Upload instance, and requires the event loop to be run in order for the upload to progress. See Net::SFTP::Operations::Upload for a full discussion of how this method can be used.

  uploader = sftp.upload("/local/path", "/remote/path")
  uploader.wait

[Source]

    # File lib/net/sftp/session.rb, line 97
97:       def upload(local, remote, options={}, &block)
98:         Operations::Upload.new(self, local, remote, options, &block)
99:       end

Identical to upload, but blocks until the upload is complete.

[Source]

     # File lib/net/sftp/session.rb, line 102
102:       def upload!(local, remote, options={}, &block)
103:         upload(local, remote, options, &block).wait
104:       end

Identical to upload, but blocks until the upload is complete.

[Source]

     # File lib/net/sftp/session.rb, line 102
102:       def upload!(local, remote, options={}, &block)
103:         upload(local, remote, options, &block).wait
104:       end

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.

  request = sftp.write(handle, 0, "hello, world!\n")
  request.wait

[Source]

     # File lib/net/sftp/session.rb, line 272
272:       def write(handle, offset, data, &callback)
273:         request :write, handle, offset, data, &callback
274:       end

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.

  request = sftp.write(handle, 0, "hello, world!\n")
  request.wait

[Source]

     # File lib/net/sftp/session.rb, line 272
272:       def write(handle, offset, data, &callback)
273:         request :write, handle, offset, data, &callback
274:       end

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.

  sftp.write!(handle, 0, "hello, world!\n")

[Source]

     # File lib/net/sftp/session.rb, line 281
281:       def write!(handle, offset, data, &callback)
282:         wait_for(write(handle, offset, data, &callback))
283:       end

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.

  sftp.write!(handle, 0, "hello, world!\n")

[Source]

     # File lib/net/sftp/session.rb, line 281
281:       def write!(handle, offset, data, &callback)
282:         wait_for(write(handle, offset, data, &callback))
283:       end

[Validate]