Class: Net::FTP
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
MonitorMixin
|
|
Inherits: | Object |
Defined in: | lib/net/ftp.rb |
Overview
This class implements the File Transfer Protocol. If you have used a command-line FTP
program, and are familiar with the commands, you will be able to use this class easily. Some extra features are included to take advantage of Ruby's style and strengths.
Example
require 'net/ftp'
Example 1
ftp = Net::FTP.new('example.com')
ftp.login
files = ftp.chdir('pub/lang/ruby/contrib')
files = ftp.list('n*')
ftp.getbinaryfile('nif.rb-0.91.gz', 'nif.gz', 1024)
ftp.close
Example 2
Net::FTP.open('example.com') do |ftp|
ftp.login
files = ftp.chdir('pub/lang/ruby/contrib')
files = ftp.list('n*')
ftp.getbinaryfile('nif.rb-0.91.gz', 'nif.gz', 1024)
end
Major Methods
The following are the methods most likely to be useful to users:
Class Method Summary
-
.new(host = nil, user = nil, passwd = nil, acct = nil) ⇒ FTP
constructor
Creates and returns a new
FTP
object. -
.open(host, user = nil, passwd = nil, acct = nil)
A synonym for .new, but with a mandatory host parameter.
Instance Attribute Summary
-
#binary
rw
When
true
, transfers are performed in binary mode. -
#binary=(newmode)
rw
A setter to toggle transfers in binary mode.
-
#debug_mode
rw
When
true
, all traffic to and from the server is written to $stdout. -
#open_timeout
rw
Number of seconds to wait for the connection to open.
-
#passive
rw
When
true
, the connection is in passive mode. -
#read_timeout
rw
Number of seconds to wait for one block to be read (via one read(2) call).
-
#read_timeout=(sec)
rw
Setter for the read_timeout attribute.
-
#resume
rw
Sets or retrieves the
resume
status, which decides whether incomplete transfers are resumed or restarted. -
#closed? ⇒ Boolean
readonly
Returns
true
iff the connection is closed. -
#last_response
readonly
The server's last response.
-
#last_response_code
(also: #lastresp)
readonly
The server's last response code.
-
#lastresp
readonly
Alias for #last_response_code.
-
#welcome
readonly
The server's welcome message.
Instance Method Summary
-
#abort
Aborts the previous command (ABOR command).
-
#acct(account)
Sends the ACCT command.
-
#chdir(dirname)
Changes the (remote) directory.
-
#close
Closes the connection.
-
#connect(host, port = FTP_PORT)
Establishes an
FTP
connection to host, optionally overriding the default port. -
#delete(filename)
Deletes a file on the server.
-
#dir(*args, &block)
Alias for #list.
-
#get(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE, &block)
Retrieves
remotefile
in whatever mode the session is set (text or binary). -
#getbinaryfile(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE)
Retrieves
remotefile
in binary mode, storing the result inlocalfile
. -
#getdir
Alias for #pwd.
-
#gettextfile(remotefile, localfile = File.basename(remotefile))
Retrieves
remotefile
in ASCII (text) mode, storing the result inlocalfile
. -
#help(arg = nil)
Issues the HELP command.
-
#list(*args, &block)
(also: #ls, #dir)
Returns an array of file information in the directory (the output is like `ls -l`).
-
#login(user = "anonymous", passwd = nil, acct = nil)
Logs in to the remote host.
-
#ls(*args, &block)
Alias for #list.
-
#mdtm(filename)
Returns the raw last modification time of the (remote) file in the format “YYYYMMDDhhmmss” (MDTM command).
-
#mkdir(dirname)
Creates a remote directory.
-
#mtime(filename, local = false)
Returns the last modification time of the (remote) file.
-
#nlst(dir = nil)
Returns an array of filenames in the remote directory.
-
#noop
Issues a NOOP command.
-
#put(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block)
Transfers
localfile
to the server in whatever mode the session is set (text or binary). -
#putbinaryfile(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block)
Transfers
localfile
to the server in binary mode, storing the result inremotefile
. -
#puttextfile(localfile, remotefile = File.basename(localfile), &block)
Transfers
localfile
to the server in ASCII (text) mode, storing the result inremotefile
. -
#pwd
(also: #getdir)
Returns the current remote directory.
-
#quit
Exits the
FTP
session. -
#rename(fromname, toname)
Renames a file on the server.
-
#retrbinary(cmd, blocksize, rest_offset = nil)
Puts the connection into binary (image) mode, issues the given command, and fetches the data returned, passing it to the associated block in chunks of
blocksize
characters. -
#retrlines(cmd)
Puts the connection into ASCII (text) mode, issues the given command, and passes the resulting data, one line at a time, to the associated block.
-
#rmdir(dirname)
Removes a remote directory.
-
#sendcmd(cmd)
Sends a command and returns the response.
-
#set_socket(sock, get_greeting = true)
Set the socket used to connect to the
FTP
server. -
#site(arg)
Issues a SITE command.
-
#size(filename)
Returns the size of the given (remote) filename.
-
#status
Returns the status (STAT command).
-
#storbinary(cmd, file, blocksize, rest_offset = nil)
Puts the connection into binary (image) mode, issues the given server-side command (such as “STOR myfile”), and sends the contents of the file named
file
to the server. -
#storlines(cmd, file)
Puts the connection into ASCII (text) mode, issues the given server-side command (such as “STOR myfile”), and sends the contents of the file named
file
to the server, one line at a time. -
#system
Returns system information.
-
#voidcmd(cmd)
Sends a command and expect a response beginning with '2'.
- #parse_pasv_ipv4_host(s) private
- #parse_pasv_ipv6_host(s) private
- #parse_pasv_port(s) private
Constructor Details
.new(host = nil, user = nil, passwd = nil, acct = nil) ⇒ FTP
Creates and returns a new FTP
object. If a host
is given, a connection is made. Additionally, if the user
is given, the given user name, password, and (optionally) account are used to log in. See #login.
# File 'lib/net/ftp.rb', line 149
def initialize(host = nil, user = nil, passwd = nil, acct = nil) super() @binary = true @passive = false @debug_mode = false @resume = false @sock = NullSocket.new @logged_in = false @open_timeout = nil @read_timeout = 60 if host connect(host) if user login(user, passwd, acct) end end end
Class Method Details
.open(host, user = nil, passwd = nil, acct = nil)
A synonym for .new, but with a mandatory host parameter.
If a block is given, it is passed the FTP
object, which will be closed when the block finishes, or when an exception is raised.
Instance Attribute Details
#binary (rw)
When true
, transfers are performed in binary mode. Default: true
.
# File 'lib/net/ftp.rb', line 84
attr_reader :binary
#binary=(newmode) (rw)
A setter to toggle transfers in binary mode. newmode
is either true
or false
# File 'lib/net/ftp.rb', line 169
def binary=(newmode) if newmode != @binary @binary = newmode send_type_command if @logged_in end end
#closed? ⇒ Boolean
(readonly)
Returns true
iff the connection is closed.
# File 'lib/net/ftp.rb', line 969
def closed? @sock == nil or @sock.closed? end
#debug_mode (rw)
When true
, all traffic to and from the server is written to $stdout. Default: false
.
# File 'lib/net/ftp.rb', line 91
attr_accessor :debug_mode
#last_response (readonly)
The server's last response.
# File 'lib/net/ftp.rb', line 123
attr_reader :last_response
#last_response_code (readonly) Also known as: #lastresp
The server's last response code.
# File 'lib/net/ftp.rb', line 119
attr_reader :last_response_code
#lastresp (readonly)
Alias for #last_response_code.
# File 'lib/net/ftp.rb', line 120
alias lastresp last_response_code
#open_timeout (rw)
Number of seconds to wait for the connection to open. Any number may be used, including Floats for fractional seconds. If the FTP
object cannot open a connection in this many seconds, it raises a Net::OpenTimeout
exception. The default value is nil
.
# File 'lib/net/ftp.rb', line 101
attr_accessor :open_timeout
#passive (rw)
When true
, the connection is in passive mode. Default: false
.
# File 'lib/net/ftp.rb', line 87
attr_accessor :passive
#read_timeout (rw)
Number of seconds to wait for one block to be read (via one read(2) call). Any number may be used, including Floats for fractional seconds. If the FTP
object cannot read data in this many seconds, it raises a Timeout::Error
exception. The default value is 60 seconds.
# File 'lib/net/ftp.rb', line 107
attr_reader :read_timeout
#read_timeout=(sec) (rw)
Setter for the read_timeout attribute.
# File 'lib/net/ftp.rb', line 110
def read_timeout=(sec) @sock.read_timeout = sec @read_timeout = sec end
#resume (rw)
Sets or retrieves the resume
status, which decides whether incomplete transfers are resumed or restarted. Default: false
.
# File 'lib/net/ftp.rb', line 95
attr_accessor :resume
#welcome (readonly)
The server's welcome message.
# File 'lib/net/ftp.rb', line 116
attr_reader :welcome
Instance Method Details
#abort
Aborts the previous command (ABOR command).
# File 'lib/net/ftp.rb', line 880
def abort line = "ABOR" + CRLF print "put: ABOR\n" if @debug_mode @sock.send(line, Socket::MSG_OOB) resp = getmultiline unless ["426", "226", "225"].include?(resp[0, 3]) raise FTPProtoError, resp end return resp end
#acct(account)
Sends the ACCT command.
This is a less common FTP
command, to send account information if the destination host requires it.
# File 'lib/net/ftp.rb', line 732
def acct(account) cmd = "ACCT " + account voidcmd(cmd) end
#chdir(dirname)
Changes the (remote) directory.
# File 'lib/net/ftp.rb', line 802
def chdir(dirname) if dirname == ".." begin voidcmd("CDUP") return rescue FTPPermError => e if e. [0, 3] != "500" raise e end end end cmd = "CWD " + dirname voidcmd(cmd) end
#close
Closes the connection. Further operations are impossible until you open a new connection with #connect.
# File 'lib/net/ftp.rb', line 953
def close if @sock and not @sock.closed? begin @sock.shutdown(Socket::SHUT_WR) rescue nil orig, self.read_timeout = self.read_timeout, 3 @sock.read rescue nil ensure @sock.close self.read_timeout = orig end end end
#connect(host, port = FTP_PORT)
Establishes an FTP
connection to host, optionally overriding the default port. If the environment variable SOCKS_SERVER
is set, sets up the connection through a SOCKS proxy. Raises an exception (typically Errno::ECONNREFUSED
) if the connection cannot be established.
# File 'lib/net/ftp.rb', line 243
def connect(host, port = FTP_PORT) if @debug_mode print "connect: ", host, ", ", port, "\n" end synchronize do @sock = open_socket(host, port) voidresp end end
#delete(filename)
Deletes a file on the server.
# File 'lib/net/ftp.rb', line 788
def delete(filename) resp = sendcmd("DELE " + filename) if resp[0, 3] == "250" return elsif resp[0] == ?5 raise FTPPermError, resp else raise FTPReplyError, resp end end
#dir(*args, &block)
Alias for #list.
# File 'lib/net/ftp.rb', line 772
alias dir list
#get(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE, &block)
Retrieves remotefile
in whatever mode the session is set (text or binary). See #gettextfile and #getbinaryfile.
# File 'lib/net/ftp.rb', line 661
def get(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE, &block) # :yield: data if @binary getbinaryfile(remotefile, localfile, blocksize, &block) else gettextfile(remotefile, localfile, &block) end end
#getbinaryfile(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE)
Retrieves remotefile
in binary mode, storing the result in localfile
. If localfile
is nil, returns retrieved data. If a block is supplied, it is passed the retrieved data in blocksize
chunks.
# File 'lib/net/ftp.rb', line 603
def getbinaryfile(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE) # :yield: data result = nil if localfile if @resume rest_offset = File.size?(localfile) f = File.open(localfile, "a") else rest_offset = nil f = File.open(localfile, "w") end elsif !block_given? result = "" end begin f.binmode if localfile retrbinary("RETR " + remotefile.to_s, blocksize, rest_offset) do |data| f.write(data) if localfile yield(data) if block_given? result.concat(data) if result end return result ensure f.close if localfile end end
#getdir
Alias for #pwd.
# File 'lib/net/ftp.rb', line 864
alias getdir pwd
#gettextfile(remotefile, localfile = File.basename(remotefile))
Retrieves remotefile
in ASCII (text) mode, storing the result in localfile
. If localfile
is nil, returns retrieved data. If a block is supplied, it is passed the retrieved data one line at a time.
# File 'lib/net/ftp.rb', line 637
def gettextfile(remotefile, localfile = File.basename(remotefile)) # :yield: line result = nil if localfile f = File.open(localfile, "w") elsif !block_given? result = "" end begin retrlines("RETR " + remotefile) do |line, newline| l = newline ? line + "\n" : line f.print(l) if localfile yield(line, newline) if block_given? result.concat(l) if result end return result ensure f.close if localfile end end
#help(arg = nil)
Issues the HELP command.
# File 'lib/net/ftp.rb', line 917
def help(arg = nil) cmd = "HELP" if arg cmd = cmd + " " + arg end sendcmd(cmd) end
#list(*args, &block) Also known as: #ls, #dir
Returns an array of file information in the directory (the output is like `ls -l`). If a block is given, it iterates through the listing.
#login(user = "anonymous", passwd = nil, acct = nil)
Logs in to the remote host. The session must have been previously connected. If user
is the string “anonymous” and the password
is nil
, “anonymous@” is used as a password. If the #acct parameter is not nil
, an FTP
ACCT command is sent following the successful login. Raises an exception on error (typically FTPPermError).
# File 'lib/net/ftp.rb', line 454
def login(user = "anonymous", passwd = nil, acct = nil) if user == "anonymous" and passwd == nil passwd = "anonymous@" end resp = "" synchronize do resp = sendcmd('USER ' + user) if resp[0] == ?3 raise FTPReplyError, resp if passwd.nil? resp = sendcmd('PASS ' + passwd) end if resp[0] == ?3 raise FTPReplyError, resp if acct.nil? resp = sendcmd('ACCT ' + acct) end end if resp[0] != ?2 raise FTPReplyError, resp end @welcome = resp send_type_command @logged_in = true end
#ls(*args, &block)
Alias for #list.
# File 'lib/net/ftp.rb', line 771
alias ls list
#mdtm(filename)
Returns the raw last modification time of the (remote) file in the format “YYYYMMDDhhmmss” (MDTM command).
Use #mtime if you want a parsed Time instance.
# File 'lib/net/ftp.rb', line 907
def mdtm(filename) resp = sendcmd("MDTM " + filename) if resp[0, 3] == "213" return resp[3 .. -1].strip end end
#mkdir(dirname)
Creates a remote directory.
#mtime(filename, local = false)
Returns the last modification time of the (remote) file. If local
is true
, it is returned as a local time, otherwise it's a UTC time.
# File 'lib/net/ftp.rb', line 836
def mtime(filename, local = false) str = mdtm(filename) ary = str.scan(MDTM_REGEXP)[0].collect {|i| i.to_i} return local ? Time.local(*ary) : Time.gm(*ary) end
#nlst(dir = nil)
Returns an array of filenames in the remote directory.
#noop
Issues a NOOP command.
Does nothing except return a response.
# File 'lib/net/ftp.rb', line 937
def noop voidcmd("NOOP") end
#parse_pasv_ipv4_host(s) (private)
[ GitHub ]# File 'lib/net/ftp.rb', line 1007
def parse_pasv_ipv4_host(s) return s.tr(",", ".") end
#parse_pasv_ipv6_host(s) (private)
[ GitHub ]# File 'lib/net/ftp.rb', line 1012
def parse_pasv_ipv6_host(s) return s.split(/,/).map { |i| "%02x" % i.to_i }.each_slice(2).map(&:join).join(":") end
#parse_pasv_port(s) (private)
[ GitHub ]# File 'lib/net/ftp.rb', line 1019
def parse_pasv_port(s) return s.split(/,/).map(&:to_i).inject { |x, y| (x << 8) + y } end
#put(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block)
Transfers localfile
to the server in whatever mode the session is set (text or binary). See #puttextfile and #putbinaryfile.
# File 'lib/net/ftp.rb', line 717
def put(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block) if @binary putbinaryfile(localfile, remotefile, blocksize, &block) else puttextfile(localfile, remotefile, &block) end end
#putbinaryfile(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block)
Transfers localfile
to the server in binary mode, storing the result in remotefile
. If a block is supplied, calls it, passing in the transmitted data in blocksize
chunks.
# File 'lib/net/ftp.rb', line 675
def putbinaryfile(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block) # :yield: data if @resume begin rest_offset = size(remotefile) rescue Net::FTPPermError rest_offset = nil end else rest_offset = nil end f = File.open(localfile) begin f.binmode if rest_offset storbinary("APPE " + remotefile, f, blocksize, rest_offset, &block) else storbinary("STOR " + remotefile, f, blocksize, rest_offset, &block) end ensure f.close end end
#puttextfile(localfile, remotefile = File.basename(localfile), &block)
Transfers localfile
to the server in ASCII (text) mode, storing the result in remotefile
. If callback or an associated block is supplied, calls it, passing in the transmitted data one line at a time.
#pwd Also known as: #getdir
Returns the current remote directory.
#quit
Exits the FTP
session.
# File 'lib/net/ftp.rb', line 928
def quit voidcmd("QUIT") end
#rename(fromname, toname)
Renames a file on the server.
# File 'lib/net/ftp.rb', line 777
def rename(fromname, toname) resp = sendcmd("RNFR " + fromname) if resp[0] != ?3 raise FTPReplyError, resp end voidcmd("RNTO " + toname) end
#retrbinary(cmd, blocksize, rest_offset = nil)
Puts the connection into binary (image) mode, issues the given command, and fetches the data returned, passing it to the associated block in chunks of blocksize
characters. Note that cmd
is a server command (such as “RETR myfile”).
# File 'lib/net/ftp.rb', line 485
def retrbinary(cmd, blocksize, rest_offset = nil) # :yield: data synchronize do with_binary(true) do begin conn = transfercmd(cmd, rest_offset) loop do data = conn.read(blocksize) break if data == nil yield(data) end conn.shutdown(Socket::SHUT_WR) conn.read_timeout = 1 conn.read ensure conn.close if conn end voidresp end end end
#retrlines(cmd)
Puts the connection into ASCII (text) mode, issues the given command, and passes the resulting data, one line at a time, to the associated block. If no block is given, prints the lines. Note that cmd
is a server command (such as “RETR myfile”).
# File 'lib/net/ftp.rb', line 512
def retrlines(cmd) # :yield: line synchronize do with_binary(false) do begin conn = transfercmd(cmd) loop do line = conn.gets break if line == nil yield(line.sub(/\r?\n\z/, ""), !line.match(/\n\z/).nil?) end conn.shutdown(Socket::SHUT_WR) conn.read_timeout = 1 conn.read ensure conn.close if conn end voidresp end end end
#rmdir(dirname)
Removes a remote directory.
# File 'lib/net/ftp.rb', line 853
def rmdir(dirname) voidcmd("RMD " + dirname) end
#sendcmd(cmd)
Sends a command and returns the response.
#set_socket(sock, get_greeting = true)
Set the socket used to connect to the FTP
server.
May raise FTPReplyError if get_greeting
is false.
# File 'lib/net/ftp.rb', line 257
def set_socket(sock, get_greeting = true) synchronize do @sock = sock if get_greeting voidresp end end end
#site(arg)
Issues a SITE command.
# File 'lib/net/ftp.rb', line 944
def site(arg) cmd = "SITE " + arg voidcmd(cmd) end
#size(filename)
Returns the size of the given (remote) filename.
# File 'lib/net/ftp.rb', line 820
def size(filename) with_binary(true) do resp = sendcmd("SIZE " + filename) if resp[0, 3] != "213" raise FTPReplyError, resp end return resp[3..-1].strip.to_i end end
#status
Returns the status (STAT command).
#storbinary(cmd, file, blocksize, rest_offset = nil)
Puts the connection into binary (image) mode, issues the given server-side command (such as “STOR myfile”), and sends the contents of the file named file
to the server. If the optional block is given, it also passes it the data, in chunks of blocksize
characters.
# File 'lib/net/ftp.rb', line 539
def storbinary(cmd, file, blocksize, rest_offset = nil) # :yield: data if rest_offset file.seek(rest_offset, IO::SEEK_SET) end synchronize do with_binary(true) do conn = transfercmd(cmd) loop do buf = file.read(blocksize) break if buf == nil conn.write(buf) yield(buf) if block_given? end conn.close voidresp end end rescue Errno::EPIPE # EPIPE, in this case, means that the data connection was unexpectedly # terminated. Rather than just raising EPIPE to the caller, check the # response on the control connection. If getresp doesn't raise a more # appropriate exception, re-raise the original exception. getresp raise end
#storlines(cmd, file)
Puts the connection into ASCII (text) mode, issues the given server-side command (such as “STOR myfile”), and sends the contents of the file named file
to the server, one line at a time. If the optional block is given, it also passes it the lines.
# File 'lib/net/ftp.rb', line 571
def storlines(cmd, file) # :yield: line synchronize do with_binary(false) do conn = transfercmd(cmd) loop do buf = file.gets break if buf == nil if buf[-2, 2] != CRLF buf = buf.chomp + CRLF end conn.write(buf) yield(buf) if block_given? end conn.close voidresp end end rescue Errno::EPIPE # EPIPE, in this case, means that the data connection was unexpectedly # terminated. Rather than just raising EPIPE to the caller, check the # response on the control connection. If getresp doesn't raise a more # appropriate exception, re-raise the original exception. getresp raise end
#system
Returns system information.
# File 'lib/net/ftp.rb', line 869
def system resp = sendcmd("SYST") if resp[0, 3] != "215" raise FTPReplyError, resp end return resp[4 .. -1] end
#voidcmd(cmd)
Sends a command and expect a response beginning with '2'.