Class: Net::FTP (Ruby 2.2.2)
Description: Class : Net::FTP - Ruby 2.2.2

- Home
- Core 2.2.2
- Std-lib 2.2.2
- Downloads

Support for the Ruby 2.2 series has ended. See here for reference.

### Home Classes Methods

### In Files

- net/ftp.rb

### Parent

Object

### Namespace

- CLASS Net::FTP::BufferedSocket
- CLASS Net::FTP::NullSocket

### Methods

- ::new
- ::open
- #abort
- #acct
- #binary=
- #chdir
- #close
- #closed?
- #connect
- #delete
- #dir
- #get
- #getbinaryfile
- #getdir
- #gettextfile
- #help
- #list
- #login
- #ls
- #mdtm
- #mkdir
- #mtime
- #nlst
- #noop
- #put
- #putbinaryfile
- #puttextfile
- #pwd
- #quit
- #read_timeout=
- #rename
- #retrbinary
- #retrlines
- #rmdir
- #sendcmd
- #set_socket
- #site
- #size
- #status
- #storbinary
- #storlines
- #system
- #voidcmd

### Included Modules

- MonitorMixin

### Class/Module Index

Quicksearch

- Net
- Net::FTP

No matching classes.

# Net::FTP

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:

- ::open

- getbinaryfile

- gettextfile

- putbinaryfile

- puttextfile

- chdir

- nlst

- size

- rename

- delete

### Attributes

binary[R]

When `true`, transfers are performed in binary mode. Default: `true`.

debug_mode[RW]

When `true`, all traffic to and from the server is written to +$stdout+. Default: `false`.

last_response[R]

The server's last response.

last_response_code[R]

The server's last response code.

lastresp[R]

The server's 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`.

passive[RW]

When `true`, the connection is in passive mode. Default: `false`.

read_timeout[R]

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.

resume[RW]

Sets or retrieves the `resume` status, which decides whether incomplete transfers are resumed or restarted. Default: `false`.

welcome[R]

The server's welcome message.

### Public Class Methods

new(host = nil, user = nil, passwd = nil, acct = nil) click to toggle source

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

open(host, user = nil, passwd = nil, acct = nil) click to toggle source

A synonym for `FTP.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.

                   # File net/ftp.rb, line 131
    def FTP.open(host, user = nil, passwd = nil, acct = nil)
      if block_given?
        ftp = new(host, user, passwd, acct)
        begin
          yield ftp
        ensure
          ftp.close
        end
      else
        new(host, user, passwd, acct)
      end
    end

### Public Instance Methods

abort() click to toggle source

Aborts the previous command (ABOR command).

                   # File net/ftp.rb, line 882
    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) click to toggle source

Sends the ACCT command.

This is a less common FTP command, to send account information if the destination host requires it.

                   # File net/ftp.rb, line 734
    def acct(account)
      cmd = "ACCT " + account
      voidcmd(cmd)
    end

binary=(newmode) click to toggle source

A setter to toggle transfers in binary mode. `newmode` is either `true` or `false`

                   # File net/ftp.rb, line 169
    def binary=(newmode)
      if newmode != @binary
        @binary = newmode
        send_type_command if @logged_in
      end
    end

chdir(dirname) click to toggle source

Changes the (remote) directory.

                   # File net/ftp.rb, line 804
    def chdir(dirname)
      if dirname == ".."
        begin
          voidcmd("CDUP")
          return
        rescue FTPPermError => e
          if e.message[0, 3] != "500"
            raise e
          end
        end
      end
      cmd = "CWD " + dirname
      voidcmd(cmd)
    end

close() click to toggle source

Closes the connection. Further operations are impossible until you open a new connection with connect.

                   # File net/ftp.rb, line 955
    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

closed?() click to toggle source

Returns `true` iff the connection is closed.

                   # File net/ftp.rb, line 971
    def closed?
      @sock == nil or @sock.closed?
    end

connect(host, port = FTP_PORT) click to toggle source

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 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) click to toggle source

Deletes a file on the server.

                   # File net/ftp.rb, line 790
    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) click to toggle source
Alias for: list
get(remotefile, localfile = File.basename(remotefile), blocksize = DEFAULT_BLOCKSIZE) click to toggle source

Retrieves `remotefile` in whatever mode the session is set (text or binary). See gettextfile and getbinaryfile.

                   # File net/ftp.rb, line 663
    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) click to toggle source

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 net/ftp.rb, line 605
    def getbinaryfile(remotefile, localfile = File.basename(remotefile),
                      blocksize = DEFAULT_BLOCKSIZE) # :yield: data
      result = nil
      if localfile
        if @resume
          rest_offset = File.size?(localfile)
          f = open(localfile, "a")
        else
          rest_offset = nil
          f = 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() click to toggle source
Alias for: pwd
gettextfile(remotefile, localfile = File.basename(remotefile)) click to toggle source

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 net/ftp.rb, line 639
    def gettextfile(remotefile, localfile = File.basename(remotefile)) # :yield: line
      result = nil
      if localfile
        f = 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) click to toggle source

Issues the HELP command.

                   # File net/ftp.rb, line 919
    def help(arg = nil)
      cmd = "HELP"
      if arg
        cmd = cmd + " " + arg
      end
      sendcmd(cmd)
    end

list(*args) click to toggle source

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.

                   # File net/ftp.rb, line 758
    def list(*args, &block) # :yield: line
      cmd = "LIST"
      args.each do |arg|
        cmd = cmd + " " + arg.to_s
      end
      if block
        retrlines(cmd, &block)
      else
        lines = []
        retrlines(cmd) do |line|
          lines << line
        end
        return lines
      end
    end

Also aliased as: ls, dir
login(user = "anonymous", passwd = nil, acct = nil) click to toggle source

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 `Net::FTPPermError`).

                   # File net/ftp.rb, line 456
    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) click to toggle source
Alias for: list
mdtm(filename) click to toggle source

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 net/ftp.rb, line 909
    def mdtm(filename)
      resp = sendcmd("MDTM " + filename)
      if resp[0, 3] == "213"
        return resp[3 .. -1].strip
      end
    end

mkdir(dirname) click to toggle source

Creates a remote directory.

                   # File net/ftp.rb, line 847
    def mkdir(dirname)
      resp = sendcmd("MKD " + dirname)
      return parse257(resp)
    end

mtime(filename, local = false) click to toggle source

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 net/ftp.rb, line 838
    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) click to toggle source

Returns an array of filenames in the remote directory.

                   # File net/ftp.rb, line 742
    def nlst(dir = nil)
      cmd = "NLST"
      if dir
        cmd = cmd + " " + dir
      end
      files = []
      retrlines(cmd) do |line|
        files.push(line)
      end
      return files
    end

noop() click to toggle source

Issues a NOOP command.

Does nothing except return a response.

                   # File net/ftp.rb, line 939
    def noop
      voidcmd("NOOP")
    end

put(localfile, remotefile = File.basename(localfile), blocksize = DEFAULT_BLOCKSIZE, &block) click to toggle source

Transfers `localfile` to the server in whatever mode the session is set (text or binary). See puttextfile and putbinaryfile.

                   # File net/ftp.rb, line 719
    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) click to toggle source

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 net/ftp.rb, line 677
    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 = 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)) click to toggle source

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.

                   # File net/ftp.rb, line 706
    def puttextfile(localfile, remotefile = File.basename(localfile), &block) # :yield: line
      f = open(localfile)
      begin
        storlines("STOR " + remotefile, f, &block)
      ensure
        f.close
      end
    end

pwd() click to toggle source

Returns the current remote directory.

                   # File net/ftp.rb, line 862
    def pwd
      resp = sendcmd("PWD")
      return parse257(resp)
    end

Also aliased as: getdir
quit() click to toggle source

Exits the FTP session.

                   # File net/ftp.rb, line 930
    def quit
      voidcmd("QUIT")
    end

read_timeout=(sec) click to toggle source

Setter for the #read_timeout attribute.

                   # File net/ftp.rb, line 110
    def read_timeout=(sec)
      @sock.read_timeout = sec
      @read_timeout = sec
    end

rename(fromname, toname) click to toggle source

Renames a file on the server.

                   # File net/ftp.rb, line 779
    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) click to toggle source

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 net/ftp.rb, line 487
    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) click to toggle source

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 net/ftp.rb, line 514
    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) click to toggle source

Removes a remote directory.

                   # File net/ftp.rb, line 855
    def rmdir(dirname)
      voidcmd("RMD " + dirname)
    end

sendcmd(cmd) click to toggle source

Sends a command and returns the response.

                   # File net/ftp.rb, line 349
    def sendcmd(cmd)
      synchronize do
        putline(cmd)
        return getresp
      end
    end

set_socket(sock, get_greeting = true) click to toggle source

Set the socket used to connect to the FTP server.

May raise FTPReplyError if `get_greeting` is false.

                   # File 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) click to toggle source

Issues a SITE command.

                   # File net/ftp.rb, line 946
    def site(arg)
      cmd = "SITE " + arg
      voidcmd(cmd)
    end

size(filename) click to toggle source

Returns the size of the given (remote) filename.

                   # File net/ftp.rb, line 822
    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() click to toggle source

Returns the status (STAT command).

                   # File net/ftp.rb, line 896
    def status
      line = "STAT" + CRLF
      print "put: STAT\n" if @debug_mode
      @sock.send(line, Socket::MSG_OOB)
      return getresp
    end

storbinary(cmd, file, blocksize, rest_offset = nil) click to toggle source

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 net/ftp.rb, line 541
    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) click to toggle source

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 net/ftp.rb, line 573
    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() click to toggle source

Returns system information.

                   # File net/ftp.rb, line 871
    def system
      resp = sendcmd("SYST")
      if resp[0, 3] != "215"
        raise FTPReplyError, resp
      end
      return resp[4 .. -1]
    end

voidcmd(cmd) click to toggle source

Sends a command and expect a response beginning with '2'.

                   # File net/ftp.rb, line 359
    def voidcmd(cmd)
      synchronize do
        putline(cmd)
        voidresp
      end
    end