module Net
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.
# File lib/net/sftp/session.rb, line 693 def block(handle, offset, length, mask, &callback) request :block, handle, offset, length, mask, &callback 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.
# File lib/net/sftp/session.rb, line 700 def block!(handle, offset, length, mask, &callback) wait_for(block(handle, offset, length, mask, &callback)) 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
# File lib/net/sftp/session.rb, line 209 def close(handle, &callback) request :close, handle, &callback 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)
# File lib/net/sftp/session.rb, line 218 def close!(handle, &callback) wait_for(close(handle, &callback)) 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.)
# File lib/net/sftp/session.rb, line 380 def fsetstat(handle, attrs, &callback) request :fsetstat, handle, attrs, &callback 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)
# File lib/net/sftp/session.rb, line 389 def fsetstat!(handle, attrs, &callback) wait_for(fsetstat(handle, attrs, &callback)) 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).
# File lib/net/sftp/session.rb, line 329 def fstat(handle, flags=nil, &callback) request :fstat, handle, flags, &callback 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
# File lib/net/sftp/session.rb, line 338 def fstat!(handle, flags=nil, &callback) wait_for(fstat(handle, flags, &callback), :attrs) 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.
# File lib/net/sftp/session.rb, line 656 def link(new_link_path, existing_path, symlink=true, &callback) request :link, new_link_path, existing_path, symlink, &callback 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)
# File lib/net/sftp/session.rb, line 665 def link!(new_link_path, existing_path, symlink=true, &callback) wait_for(link(new_link_path, existing_path, symlink, &callback)) 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
# File lib/net/sftp/session.rb, line 312 def lstat(path, flags=nil, &callback) request :lstat, path, flags, &callback 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
# File lib/net/sftp/session.rb, line 321 def lstat!(path, flags=nil, &callback) wait_for(lstat(path, flags, &callback), :attrs) 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
# File lib/net/sftp/session.rb, line 490 def mkdir(path, attrs={}, &callback) request :mkdir, path, attrs, &callback 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)
# File lib/net/sftp/session.rb, line 499 def mkdir!(path, attrs={}, &callback) wait_for(mkdir(path, attrs, &callback)) 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")
# File lib/net/sftp/session.rb, line 192 def open!(path, flags="r", options={}, &callback) wait_for(open(path, flags, options, &callback), :handle) 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
# File lib/net/sftp/session.rb, line 407 def opendir(path, &callback) request :opendir, path, &callback 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")
# File lib/net/sftp/session.rb, line 416 def opendir!(path, &callback) wait_for(opendir(path, &callback), :handle) 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.
# File lib/net/sftp/session.rb, line 248 def read(handle, offset, length, &callback) request :read, handle, offset, length, &callback 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)
# File lib/net/sftp/session.rb, line 258 def read!(handle, offset, length, &callback) wait_for(read(handle, offset, length, &callback), :data) 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).
# File lib/net/sftp/session.rb, line 441 def readdir(handle, &callback) request :readdir, handle, &callback 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
# File lib/net/sftp/session.rb, line 453 def readdir!(handle, &callback) wait_for(readdir(handle, &callback), :names) 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
# File lib/net/sftp/session.rb, line 606 def readlink(path, &callback) request :readlink, path, &callback 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")
# File lib/net/sftp/session.rb, line 615 def readlink!(path, &callback) wait_for(readlink(path, &callback), :names).first 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
# File lib/net/sftp/session.rb, line 536 def realpath(path, &callback) request :realpath, path, &callback 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"))
# File lib/net/sftp/session.rb, line 545 def realpath!(path, &callback) wait_for(realpath(path, &callback), :names).first 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
# File lib/net/sftp/session.rb, line 467 def remove(filename, &callback) request :remove, filename, &callback 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")
# File lib/net/sftp/session.rb, line 476 def remove!(filename, &callback) wait_for(remove(filename, &callback)) 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.
# File lib/net/sftp/session.rb, line 582 def rename(name, new_name, flags=nil, &callback) request :rename, name, new_name, flags, &callback 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")
# 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
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
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
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
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
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
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
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
# File lib/net/sftp/session.rb, line 629 def symlink(path, target, &callback) request :symlink, path, target, &callback 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")
# File lib/net/sftp/session.rb, line 638 def symlink!(path, target, &callback) wait_for(symlink(path, target, &callback)) 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.
# File lib/net/sftp/session.rb, line 712 def unblock(handle, offset, length, &callback) request :unblock, handle, offset, length, &callback 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.
# File lib/net/sftp/session.rb, line 719 def unblock!(handle, offset, length, &callback) wait_for(unblock(handle, offset, length, &callback)) 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
# File lib/net/sftp/session.rb, line 274 def write(handle, offset, data, &callback) request :write, handle, offset, data, &callback 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")
# File lib/net/sftp/session.rb, line 283 def write!(handle, offset, data, &callback) wait_for(write(handle, offset, data, &callback)) end