Using the Net::FTP module is a three-part process:
to a server, identify and
files. All interaction with the FTP server happens through method calls on a Net::FTP object. If an error occurs, methods return
in scalar context or an empty list in list context.
The connection is established with the
constructor. If an error occurs,
is set to an error message and
. The first argument is the hostname of the FTP server and is optionally followed by named options:
$ftp = Net::FTP->new("ftp.host.com",
Timeout => 30,
Debug => 1)
or die "Can't connect: $@\n";
option gives the number of seconds all operations wait before giving up.
sets the debugging level (non-zero sends copies of all commands to STDERR).
takes a string as an argument, specifying the machine acting as an FTP proxy.
lets you specify an alternate port number (the default is 21, the standard port for FTP). Finally, if the
option is set to true, all transfers are done passively (some firewalls and proxies require this). The
options override the environment variables
Having connected, the next step is to authenticate. Normally, you'll want to call
with up to three arguments: username, password, and account.
or die "Couldn't authenticate.\n";
or die "Still couldn't authenticate.\n";
or die "Couldn't authenticate, even with explicit username
$ftp->login($username, $password, $account)
or die "No dice. It hates me.\n";
If you call
with no arguments, Net::FTP uses the Net::Netrc module to find settings for the host you've connected to. If none are found there, anonymous login is attempted (username
). If no password is given and the username
is used, the user's mail address is supplied as the password. The optional account argument is not used on most systems. If the authentication fails,
Once authenticated, the usual FTP commands are available as methods called on your Net::FTP object. The
methods fetch and send files. To send a file, use:
or die "Can't send $localfile: $!\n";
If you omit the second argument, the remote file will have the same name as the local file. You can also send from a filehandle (in which case the remote filename must be given as the second argument):
or die "Can't send from STDIN: $!\n";
If the transfer is interrupted, the remote file is not automatically deleted. The
method returns the remote filename if it succeeded, or
if an error occurred.
To fetch a file, use the
method, which returns the local filename, or
if there was an error:
or die "Can't fetch $remotefile : $!\n";
You can also
into a filehandle, in which case the filehandle is returned (or
if there was an error):
or die "Can't fetch $remotefile: $!\n";
an optional third argument, an offset into the remote file, to begin the transfer at that offset. Received bytes are appended to the local file.
method changes the file translation mode. Pass it a string (
) and it will return the previous translation mode. The
with the appropriate string. If an error occurs (the FTP server does not do EBCDIC, for example),
and its helper methods return
to set and fetch the current remote directory. They both return true if successful, false otherwise. If you
method is called to change the directory to the parent of the current directory. Call
without an argument to change to the root directory.
print "I'm in the directory ", $ftp->pwd(), "\n";
make and delete directories on the remote machine. You have the built-in
functions to make and delete directories on the local machine. To create all directories up to the given directory, pass a true second argument to
. For instance, if you want to make
or die "Can't create /pub/gnat/perl recursively: $!\n";
succeeds, the full path to the newly created directory is returned. If it fails,
methods get a list of files in a remote directory. Traditionally,
gives you a more verbose listing than
, but neither has a standard format. Most Unix FTP servers return the output of
respectively, but you can't guarantee that behavior from every FTP server. These methods, in list context, return the list of lines returned by the server. In scalar context, they return a reference to an array.
@lines = $ftp->ls("/pub/gnat/perl")
or die "Can't get a list of files in /pub/gnat/perl: $!";
$ref_to_lines = $ftp->dir("/pub/perl/CPAN/src/latest.tar.gz")
or die "Can't check status of latest.tar.gz: $!\n";
When you're done and want to close up gracefully, use the
$ftp->quit() or warn "Couldn't quit. Oh well.\n";
Other methods rename, change ownership and permissions of remote files, check the size of the remote file, and so on. Read the Net::FTP documentation for details.
If you want to mirror files between machines, use the excellent
program written in Perl by Lee McLoughlin. Look for it on the Web at