module Net

Public Instance Methods

block(handle, offset, length, mask) → request click to toggle source
block(handle, offset, length, mask) { |response| ... } → request

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.

# File lib/net/sftp/session.rb, line 693
def block(handle, offset, length, mask, &callback)
  request :block, handle, offset, length, mask, &callback
end
block!(handle, offset, length, mask, &callback) click to toggle source

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.

# File lib/net/sftp/session.rb, line 700
def block!(handle, offset, length, mask, &callback)
  wait_for(block(handle, offset, length, mask, &callback))
end
close(handle) → request click to toggle source
close(handle) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 209
def close(handle, &callback)
  request :close, handle, &callback
end
close!(handle, &callback) click to toggle source

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)
# File lib/net/sftp/session.rb, line 218
def close!(handle, &callback)
  wait_for(close(handle, &callback))
end
fsetstat(handle, attrs, &callback) click to toggle source

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

# File lib/net/sftp/session.rb, line 380
def fsetstat(handle, attrs, &callback)
  request :fsetstat, handle, attrs, &callback
end
fsetstat!(handle, attrs, &callback) click to toggle source

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)
# File lib/net/sftp/session.rb, line 389
def fsetstat!(handle, attrs, &callback)
  wait_for(fsetstat(handle, attrs, &callback))
end
fstat(handle, flags=nil, &callback) click to toggle source

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

# File lib/net/sftp/session.rb, line 329
def fstat(handle, flags=nil, &callback)
  request :fstat, handle, flags, &callback
end
fstat!(handle, flags=nil, &callback) click to toggle source

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
# File lib/net/sftp/session.rb, line 338
def fstat!(handle, flags=nil, &callback)
  wait_for(fstat(handle, flags, &callback), :attrs)
end
lstat(path, flags=nil) → request click to toggle source
lstat(path, flags=nil) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 312
def lstat(path, flags=nil, &callback)
  request :lstat, path, flags, &callback
end
lstat!(path, flags=nil, &callback) click to toggle source

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
# File lib/net/sftp/session.rb, line 321
def lstat!(path, flags=nil, &callback)
  wait_for(lstat(path, flags, &callback), :attrs)
end
mkdir(path, attrs={}) → request click to toggle source
mkdir(path, attrs={}) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 490
def mkdir(path, attrs={}, &callback)
  request :mkdir, path, attrs, &callback
end
mkdir!(path, attrs={}, &callback) click to toggle source

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)
# File lib/net/sftp/session.rb, line 499
def mkdir!(path, attrs={}, &callback)
  wait_for(mkdir(path, attrs, &callback))
end
open!(path, flags="r", options={}, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 192
def open!(path, flags="r", options={}, &callback)
  wait_for(open(path, flags, options, &callback), :handle)
end
opendir(path) → request click to toggle source
opendir(path) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 407
def opendir(path, &callback)
  request :opendir, path, &callback
end
opendir!(path, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 416
def opendir!(path, &callback)
  wait_for(opendir(path, &callback), :handle)
end
read(handle, offset, length) → request click to toggle source
read(handle, offset, length) { |response| ... } → request

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.

# File lib/net/sftp/session.rb, line 248
def read(handle, offset, length, &callback)
  request :read, handle, offset, length, &callback
end
read!(handle, offset, length, &callback) click to toggle source

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)
# File lib/net/sftp/session.rb, line 258
def read!(handle, offset, length, &callback)
  wait_for(read(handle, offset, length, &callback), :data)
end
readdir(handle) → request click to toggle source
readdir(handle) { |response| ... } → request

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

# File lib/net/sftp/session.rb, line 441
def readdir(handle, &callback)
  request :readdir, handle, &callback
end
readdir!(handle, &callback) click to toggle source

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
# File lib/net/sftp/session.rb, line 453
def readdir!(handle, &callback)
  wait_for(readdir(handle, &callback), :names)
end
realpath(path) → request click to toggle source
realpath(path) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 536
def realpath(path, &callback)
  request :realpath, path, &callback
end
realpath!(path, &callback) click to toggle source

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"))
# File lib/net/sftp/session.rb, line 545
def realpath!(path, &callback)
  wait_for(realpath(path, &callback), :names).first
end
remove(filename) → request click to toggle source
remove(filename) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 467
def remove(filename, &callback)
  request :remove, filename, &callback
end
remove!(filename, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 476
def remove!(filename, &callback)
  wait_for(remove(filename, &callback))
end
rename(name, new_name, flags=nil) → request click to toggle source
rename(name, new_name, flags=nil) { |response| ... } → request

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.

# File lib/net/sftp/session.rb, line 582
def rename(name, new_name, flags=nil, &callback)
  request :rename, name, new_name, flags, &callback
end
rename!(name, new_name, flags=nil, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 591
def rename!(name, new_name, flags=nil, &callback)
  wait_for(rename(name, new_name, flags, &callback))
end
rmdir(path) → request click to toggle source
rmdir(path) { |response| ... } → request

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

sftp.rmdir("/path/to/directory").wait
# File lib/net/sftp/session.rb, line 511
def rmdir(path, &callback)
  request :rmdir, path, &callback
end
rmdir!(path, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 520
def rmdir!(path, &callback)
  wait_for(rmdir(path, &callback))
end
setstat(path, attrs) → request click to toggle source
setstat(path, attrs) { |response| ... } → request

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?}"
# File lib/net/sftp/session.rb, line 363
def setstat(path, attrs, &callback)
  request :setstat, path, attrs, &callback
end
setstat!(path, attrs, &callback) click to toggle source

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)
# File lib/net/sftp/session.rb, line 372
def setstat!(path, attrs, &callback)
  wait_for(setstat(path, attrs, &callback))
end
stat(path, flags=nil, &callback) click to toggle source

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.

# File lib/net/sftp/session.rb, line 553
def stat(path, flags=nil, &callback)
  request :stat, path, flags, &callback
end
stat!(path, flags=nil, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 562
def stat!(path, flags=nil, &callback)
  wait_for(stat(path, flags, &callback), :attrs)
end
unblock(handle, offset, length) → request click to toggle source
unblock(handle, offset, length) { |response| ... } → request

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.

# File lib/net/sftp/session.rb, line 712
def unblock(handle, offset, length, &callback)
  request :unblock, handle, offset, length, &callback
end
unblock!(handle, offset, length, &callback) click to toggle source

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.

# File lib/net/sftp/session.rb, line 719
def unblock!(handle, offset, length, &callback)
  wait_for(unblock(handle, offset, length, &callback))
end
write(handle, offset, data) → request click to toggle source
write(handle, offset, data) { |response| ... } → request

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
# File lib/net/sftp/session.rb, line 274
def write(handle, offset, data, &callback)
  request :write, handle, offset, data, &callback
end
write!(handle, offset, data, &callback) click to toggle source

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")
# File lib/net/sftp/session.rb, line 283
def write!(handle, offset, data, &callback)
  wait_for(write(handle, offset, data, &callback))
end