Net::FTP (Perl in a Nutshell, 2nd Edition)

18.2. Net::FTP

Net::FTP is used to transfer files from remote hosts. With Net::FTP, you can write simple FTP clients that transfer files from remote servers based on information passed on the command line or from hardcoded variables. Here is an example of a client that connects to a remote FTP server and gets a file from the server:

#!/usr/local/bin/perl -w

use Net::FTP;

$hostname = 'remotehost.com';
$username = 'anonymous';
$password = 'myname@mydomain.com';

# Hardcode the directory and filename to get
$home = '/pub';
$filename = 'TESTFILE';

# Open the connection to the host
$ftp = Net::FTP->new($hostname);        # Construct object
$ftp->login($username, $password);      # Log in

$ftp->cwd($home),"\n";                  # Change directory
print $ftp->ls($home),"\n";        

# Now get the file and leave
$ftp->get($filename); 
$ftp->quit;

FTP clients have also been integrated with most World Wide Web browsers, using ftp:// in place of http://. When the URL points to a directory, the browser displays a listing of the directory, in which each filename is a link to that file. When the URL points directly to a file, the remote file is downloaded.

Here's an example that uses Net::FTP to list files from a remote FTP server on a web page, with a link from each file to the URL of the file on the remote site:

#!/usr/local/bin/perl -w

use Net::FTP;

$hostname = 'remotehost.com';        # FTP host
$username = 'anonymous';             # Username
$password = 'myname@mydomain.com';   # Password
$home = '/pub';

$ftp = Net::FTP->new($hostname);     # Net::FTP constructor
$ftp->login($username, $password);  # Log in w/username and password

$pwd = $ftp->pwd;                   # Get current directory

print <<HTML;                       # Output HTML page
Content-type: text/html
<HTML>
  
  <HEAD>
    <TITLE>Download Files</TITLE>
  </HEAD>
  <BODY>
      
      <B>Current working directory:</B> $pwd<BR>
      Files to download: <P>
HTML
  
    @entries = $ftp->ls($home);     # Slurp all entries into an array
    foreach (@entries) { # Output links for all files in the ftp area
                         # as links
        print "<INPUT TYPE=hidden NAME=\"files\" VALUE=\"$_\">\n";
        print "<A HREF=\"ftp://$hostname$_\">",
        "<IMG SRC=\"http://www/icons/f.gif\" border=0>\n";
        print " $_</A><BR>\n";
    }
    print <<HTML;
  </BODY>
</HTML>
HTML
$ftp->quit;             # end FTP session

The Net::FTP module implements a subset (as shown earlier in this chapter) of the FTP protocol as defined in RFC 959. In addition to providing the methods shown below, the module inherits from Net::Cmd. Some of the Net::FTP methods return an object derived from the dataconn class (which is in turn derived from the IO::Socket::INET class), as noted in the entries for those methods.

The following methods are defined by Net::FTP.

new

$ftp = Net::FTP->new(host[, options])

Constructs a new Net::FTP object. Arguments are:

host: The name of the remote host
options: A hash specifying any of the following information:

Firewall

Name of an FTP firewall.

Port

Port number to use for the FTP connection. Defaults to 21.

Timeout

Timeout value. Defaults to 120 seconds.

Debug

Debug level.

Passive

True or false, specifying whether to perform transfers in passive mode.

abort

$ftp->abort(  )

Aborts the current transaction.

appe

$ftp->appe(file)

Appends data to the end of the remote file file, which is created if it doesn't exist. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object.

append

$ftp->append(local[, remote])

Appends the contents of a local file to an existing file on the remote system. Arguments are:

local: Either the name of the file on the local system to transfer or a filehandle.
remote: The name of the file on the remote system. If local is a filehandle, remote must be specified.

ascii

$ftp->ascii([args])

Changes the type of data transfer to ascii. Like type, without the need to specify the first argument.

authorize

$ftp->authorize([auth[, resp]])

Authorizes the user to send data outside the firewall, for use with FTP proxies. If authorization auth and response resp are not specified, authorize uses Net::Netrc to do a lookup.

Called with no arguments by login if the connection is through a firewall.

binary

$ftp->binary([args])

Changes the type of data transfer to binary. Like type, without the need to specify the first argument.

byte

$ftp->byte([args])

Changes the data transfer type to byte. Not supported. If specified, defaults to binary. Like type, without the need to specify the first argument.

cdup

$ftp->cdup(  )

Goes up one level in the directory hierarchy.

cwd

$ftp->cwd([dir])

Changes the working directory to dir. With no argument, changes the directory to root.

delete

$ftp->delete([filename])

Deletes the specified file from the server.

dir

$ftp->dir([dir])

Lists the specified server directory in long format. Returns a reference to the list. dir defaults to the current working directory.

ebcdic

$ftp->ebcdic([args])

Changes the data transfer type to ebcdic. Not supported. If specified, defaults to binary. Like type, without the need to specify the first argument.

get

$ftp->get(remote[, local])

Retrieves a file from the server. If specified, local is the name to give the file on the local system; otherwise, the name stays the same. Arguments are:

remote: Name of the file to retrieve from the remote system.
local: Either the new filename on the local system or a filehandle. If omitted, the same filename is used.

list

$ftp->list([dir])

Lists a directory, dir, for display. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object. If directory is omitted, defaults to the current directory.

login

$ftp->([login[, passwd[, account]]])

Logs user into an FTP server. Arguments are:

login: Login name. If not specified, defaults to anonymous or to the value in $HOME/.netrc.
passwd: Password. If not specified, defaults to the user's email address or to the value in $HOME/.netrc.
account: Additional account information for files on the FTP server that have special access restrictions.

$ftp->ls([dir])

Lists directory, dir, returning a reference to the list. Defaults to the current working directory.

mdtm

$ftp->mdtm(file)

Returns the modification time of remote file file.

mkdir

$ftp->mkdir(dir[, recursive])

Makes a new directory. Arguments are:

dir: The new directory name
recursive: If true, creates all directories in the path as needed

nlst

$ftp->nlst([dir])

Lists a directory, dir, for further processing. With no argument, defaults to the current directory. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object.

pasv

$ftp->pasv(  )

Puts server in passive mode.

pasv_wait

$ftp->pasv_wait(server)

Waits for a transfer to complete between a passive and a nonpassive server, in which server is the Net::FTP object for the nonpassive server.

pasv_xfer

$ftp->pasv_xfer(file1, server, [file2])

Transfers a file between two remote servers. Arguments are:

file1: The file to transfer from the server represented by the Net::FTP object.
server: Destination server.
file2: New name of the file on the destination server. If omitted, the original name is used.

pasv_xfer_unique

$ftp->pasv_xfer_unique(file1, server[, file2])

Like pasv_xfer, but stores the file on the remote server with a new (unique) name.

port

$ftp->port([port])

Sends a PORT command telling the server to use port port. With no argument, a socket is created, and its information is sent.

put

$ftp->put(local[, remote])

Puts a file onto the server. Arguments are:

local: The name of the file to transfer from the local system, or a filehandle.
remote: The new filename on the remote system. If omitted, the same filename is used. If local is a filehandle, the remote filename must be specified.

put_unique

$ftp->put_unique(local[, remote])

Puts a file with a unique name onto the server. Arguments are:

local: The name of the file to transfer from the local system, or a filehandle.
remote: The new filename on the remote system. If a file exists by that name, a new unique filename is created.

pwd

$ftp->pwd(  )

Returns the current directory path.

quit

$ftp->quit(  )

Closes the connection.

quot

$ftp->quot(cmd[, args])

Sends a literal FTP protocol command to the server and waits for a response. Returns the most significant digit of the response code.

rename

$ftp->rename(file1, file2)

Renames a file on the server. Arguments are:

file1: The old name of the file
file2: The new name of the file

retr

$ftp->retr(file)

Retrieves file file from the remote server. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object.

rmdir

$ftp->rmdir(dir)

Removes directory dir.

size

$ftp->size(file)

Returns the size of file file in bytes.

stor

$ftp->stor(file)

Tells the server to store a new file under the name file. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object.

stou

$ftp->stou(file)

Like stor, but stores file on the remote server with a unique name, file. If the user calls either pasv or port, returns true or false. Otherwise, returns a reference to a Net::FTP::dataconn object.

supported

$ftp->supported(cmd)

Returns true if the server supports the command cmd.

type

$ftp->type(type[, args])

Changes the type of data transfer. Possible types are ascii, ebcdic, byte, and binary. The value of args depends on the type.

unique_name

$ftp->unique_name(  )

Returns the name of the last file stored with a unique name.