3 # Copyright (c) 1995-2004 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
7 # Documentation (at end) improved 1996 by Nathan Torkington <gnat@frii.com>.
14 use vars qw(@ISA $VERSION);
22 use Fcntl qw(O_WRONLY O_RDONLY O_APPEND O_CREAT O_TRUNC);
25 @ISA = qw(Exporter Net::Cmd IO::Socket::INET);
27 # Someday I will "use constant", when I am not bothered to much about
28 # compatability with older releases of perl
30 use vars qw($TELNET_IAC $TELNET_IP $TELNET_DM);
31 ($TELNET_IAC, $TELNET_IP, $TELNET_DM) = (255, 244, 242);
36 # make a constant so code is fast'ish
37 my $is_os390 = $^O eq 'os390';
38 *trEBCDIC = sub () {$is_os390}
51 $peer = delete $arg{Host};
56 my $fire_type = undef;
58 if (exists($arg{Firewall}) || Net::Config->requires_firewall($peer)) {
59 $fire = $arg{Firewall}
61 || $NetConfig{ftp_firewall}
67 $fire_type = $arg{FirewallType}
68 || $ENV{FTP_FIREWALL_TYPE}
69 || $NetConfig{firewall_type}
74 my $ftp = $pkg->SUPER::new(
76 PeerPort => $arg{Port} || 'ftp(21)',
77 LocalAddr => $arg{'LocalAddr'},
79 Timeout => defined $arg{Timeout}
85 ${*$ftp}{'net_ftp_host'} = $host; # Remote hostname
86 ${*$ftp}{'net_ftp_type'} = 'A'; # ASCII/binary/etc mode
87 ${*$ftp}{'net_ftp_blksize'} = abs($arg{'BlockSize'} || 10240);
89 ${*$ftp}{'net_ftp_localaddr'} = $arg{'LocalAddr'};
91 ${*$ftp}{'net_ftp_firewall'} = $fire
93 ${*$ftp}{'net_ftp_firewall_type'} = $fire_type
94 if (defined $fire_type);
96 ${*$ftp}{'net_ftp_passive'} =
97 int exists $arg{Passive} ? $arg{Passive}
98 : exists $ENV{FTP_PASSIVE} ? $ENV{FTP_PASSIVE}
99 : defined $fire ? $NetConfig{ftp_ext_passive}
100 : $NetConfig{ftp_int_passive}; # Whew! :-)
102 $ftp->hash(exists $arg{Hash} ? $arg{Hash} : 0, 1024);
106 $ftp->debug(exists $arg{Debug} ? $arg{Debug} : undef);
108 unless ($ftp->response() == CMD_OK) {
118 ## User interface methods
124 ${*$me}{'net_ftp_host'};
129 my $ftp = shift; # self
133 delete ${*$ftp}{'net_ftp_hash'};
134 return [\*STDERR, 0];
136 ($h, $b) = (ref($h) ? $h : \*STDERR, $b || 1024);
137 select((select($h), $| = 1)[0]);
138 $b = 512 if $b < 512;
139 ${*$ftp}{'net_ftp_hash'} = [$h, $b];
154 sub ascii { shift->type('A', @_); }
155 sub binary { shift->type('I', @_); }
159 carp "TYPE E is unsupported, shall default to I";
160 shift->type('E', @_);
165 carp "TYPE L is unsupported, shall default to I";
166 shift->type('L', @_);
169 # Allow the user to send a command directly, BE CAREFUL !!
176 $ftp->command(uc $cmd, @_);
184 $ftp->command("SITE", @_);
193 # Server Y2K bug workaround
195 # sigh; some idiotic FTP servers use ("19%d",tm.tm_year) instead of
196 # ("%d",tm.tm_year+1900). This results in an extra digit in the
197 # string returned. To account for this we allow an optional extra
198 # digit in the year. Then if the first two digits are 19 we use the
199 # remainder, otherwise we subtract 1900 from the whole year.
202 && $ftp->message =~ /((\d\d)(\d\d\d?))(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)/
203 ? timegm($8, $7, $6, $5, $4 - 1, $2 eq '19' ? $3 : ($1 - 1900))
212 if ($ftp->supported("SIZE")) {
213 return $ftp->_SIZE($file)
214 ? ($ftp->message =~ /(\d+)\s*(bytes?\s*)?$/)[0]
217 elsif ($ftp->supported("STAT")) {
220 unless $ftp->_STAT($file) && (@msg = $ftp->message) == 3;
222 foreach $line (@msg) {
223 return (split(/\s+/, $line))[4]
224 if $line =~ /^[-rwxSsTt]{10}/;
228 my @files = $ftp->dir($file);
230 return (split(/\s+/, $1))[4]
231 if $files[0] =~ /^([-rwxSsTt]{10}.*)$/;
239 my ($ftp, $user, $pass, $acct) = @_;
240 my ($ok, $ruser, $fwtype);
242 unless (defined $user) {
245 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'});
247 ($user, $pass, $acct) = $rc->lpa()
251 $user ||= "anonymous";
254 $fwtype = ${*$ftp}{'net_ftp_firewall_type'}
255 || $NetConfig{'ftp_firewall_type'}
258 if ($fwtype && defined ${*$ftp}{'net_ftp_firewall'}) {
259 if ($fwtype == 1 || $fwtype == 7) {
260 $user .= '@' . ${*$ftp}{'net_ftp_host'};
265 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
267 my ($fwuser, $fwpass, $fwacct) = $rc ? $rc->lpa() : ();
270 $user = join('@', $user, $fwuser, ${*$ftp}{'net_ftp_host'});
271 $pass = $pass . '@' . $fwpass;
275 $user .= '@' . ${*$ftp}{'net_ftp_host'};
277 elsif ($fwtype == 6) {
278 $fwuser .= '@' . ${*$ftp}{'net_ftp_host'};
281 $ok = $ftp->_USER($fwuser);
283 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
285 $ok = $ftp->_PASS($fwpass || "");
287 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
289 $ok = $ftp->_ACCT($fwacct)
293 $ok = $ftp->command("SITE", ${*$ftp}{'net_ftp_host'})->response;
295 elsif ($fwtype == 4) {
296 $ok = $ftp->command("OPEN", ${*$ftp}{'net_ftp_host'})->response;
299 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
304 $ok = $ftp->_USER($user);
306 # Some dumb firewalls don't prefix the connection messages
307 $ok = $ftp->response()
308 if ($ok == CMD_OK && $ftp->code == 220 && $user =~ /\@/);
310 if ($ok == CMD_MORE) {
311 unless (defined $pass) {
314 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'}, $ruser);
316 ($ruser, $pass, $acct) = $rc->lpa()
319 $pass = '-anonymous@'
320 if (!defined $pass && (!defined($ruser) || $ruser =~ /^anonymous/o));
323 $ok = $ftp->_PASS($pass || "");
326 $ok = $ftp->_ACCT($acct)
327 if (defined($acct) && ($ok == CMD_MORE || $ok == CMD_OK));
329 if ($fwtype == 7 && $ok == CMD_OK && defined ${*$ftp}{'net_ftp_firewall'}) {
330 my ($f, $auth, $resp) = _auth_id($ftp);
331 $ftp->authorize($auth, $resp) if defined($resp);
339 @_ == 2 or croak 'usage: $ftp->account( ACCT )';
342 $ftp->_ACCT($acct) == CMD_OK;
347 my ($ftp, $auth, $resp) = @_;
349 unless (defined $resp) {
352 $auth ||= eval { (getpwuid($>))[0] } || $ENV{NAME};
354 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'}, $auth)
355 || Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
357 ($auth, $resp) = $rc->lpa()
360 ($ftp, $auth, $resp);
365 @_ >= 1 || @_ <= 3 or croak 'usage: $ftp->authorize( [AUTH [, RESP]])';
367 my ($ftp, $auth, $resp) = &_auth_id;
369 my $ok = $ftp->_AUTH($auth || "");
371 $ok = $ftp->_RESP($resp || "")
372 if ($ok == CMD_MORE);
379 @_ == 3 or croak 'usage: $ftp->rename(FROM, TO)';
381 my ($ftp, $from, $to) = @_;
391 my $oldval = ${*$ftp}{'net_ftp_type'};
394 unless (defined $type);
397 unless ($ftp->_TYPE($type, @_));
399 ${*$ftp}{'net_ftp_type'} = join(" ", $type, @_);
408 my $oldval = ${*$ftp}{'net_ftp_allo'};
411 unless (defined $size);
414 unless ($ftp->_ALLO($size, @_));
416 ${*$ftp}{'net_ftp_allo'} = join(" ", $size, @_);
425 send($ftp, pack("CCC", $TELNET_IAC, $TELNET_IP, $TELNET_IAC), MSG_OOB);
427 $ftp->command(pack("C", $TELNET_DM) . "ABOR");
429 ${*$ftp}{'net_ftp_dataconn'}->close()
430 if defined ${*$ftp}{'net_ftp_dataconn'};
434 $ftp->status == CMD_OK;
439 my ($ftp, $remote, $local, $where) = @_;
441 my ($loc, $len, $buf, $resp, $data);
444 my $localfd = ref($local) || ref(\$local) eq "GLOB";
446 ($local = $remote) =~ s#^.*/##
447 unless (defined $local);
449 croak("Bad remote filename '$remote'\n")
450 if $remote =~ /[\r\n]/s;
452 ${*$ftp}{'net_ftp_rest'} = $where if defined $where;
453 my $rest = ${*$ftp}{'net_ftp_rest'};
455 delete ${*$ftp}{'net_ftp_port'};
456 delete ${*$ftp}{'net_ftp_pasv'};
458 $data = $ftp->retr($remote)
467 unless (sysopen($loc, $local, O_CREAT | O_WRONLY | ($rest ? O_APPEND: O_TRUNC))) {
468 carp "Cannot open Local file $local: $!\n";
474 if ($ftp->type eq 'I' && !binmode($loc)) {
475 carp "Cannot binmode Local file $local: $!\n";
477 close($loc) unless $localfd;
482 my ($count, $hashh, $hashb, $ref) = (0);
484 ($hashh, $hashb) = @$ref
485 if ($ref = ${*$ftp}{'net_ftp_hash'});
487 my $blksize = ${*$ftp}{'net_ftp_blksize'};
488 local $\; # Just in case
491 last unless $len = $data->read($buf, $blksize);
493 if (trEBCDIC && $ftp->type ne 'I') {
494 $buf = $ftp->toebcdic($buf);
500 print $hashh "#" x (int($count / $hashb));
503 unless (print $loc $buf) {
504 carp "Cannot write to Local file $local: $!\n";
512 print $hashh "\n" if $hashh;
515 unless (close($loc)) {
516 carp "Cannot close file $local (perhaps disk space) $!\n";
521 unless ($data->close()) # implied $ftp->response
523 carp "Unable to close datastream";
532 @_ == 1 || @_ == 2 or croak 'usage: $ftp->cwd( [ DIR ] )';
534 my ($ftp, $dir) = @_;
536 $dir = "/" unless defined($dir) && $dir =~ /\S/;
545 @_ == 1 or croak 'usage: $ftp->cdup()';
551 @_ == 1 || croak 'usage: $ftp->pwd()';
558 # rmdir( $ftp, $dir, [ $recurse ] )
560 # Removes $dir on remote host via FTP.
561 # $ftp is handle for remote host
563 # If $recurse is TRUE, the directory and deleted recursively.
564 # This means all of its contents and subdirectories.
566 # Initial version contributed by Dinkum Software
569 @_ == 2 || @_ == 3 or croak('usage: $ftp->rmdir( DIR [, RECURSE ] )');
572 my ($ftp, $dir, $recurse) = @_;
576 if $ok = $ftp->_RMD($dir)
579 # Try to delete the contents
580 # Get a list of all the files in the directory
581 my @filelist = grep { !/^\.{1,2}$/ } $ftp->ls($dir);
584 unless @filelist; # failed, it is probably not a directory
586 # Go thru and delete each file or the directory
588 foreach $file (map { m,/, ? $_ : "$dir/$_" } @filelist) {
589 next # successfully deleted the file
590 if $ftp->delete($file);
592 # Failed to delete it, assume its a directory
593 # Recurse and ignore errors, the final rmdir() will
594 # fail on any errors here
596 unless $ok = $ftp->rmdir($file, 1);
599 # Directory should be empty
600 # Try to remove the directory again
601 # Pass results directly to caller
602 # If any of the prior deletes failed, this
603 # rmdir() will fail because directory is not empty
604 return $ftp->_RMD($dir);
609 @_ == 2 || croak 'usage: $ftp->restart( BYTE_OFFSET )';
611 my ($ftp, $where) = @_;
613 ${*$ftp}{'net_ftp_rest'} = $where;
620 @_ == 2 || @_ == 3 or croak 'usage: $ftp->mkdir( DIR [, RECURSE ] )';
622 my ($ftp, $dir, $recurse) = @_;
624 $ftp->_MKD($dir) || $recurse
630 my @path = split(m#(?=/+)#, $dir);
635 $path .= shift @path;
639 $path = $ftp->_extract_path($path);
642 # If the creation of the last element was not successful, see if we
643 # can cd to it, if so then return path
646 my ($status, $message) = ($ftp->status, $ftp->message);
649 if ($pwd && $ftp->cwd($dir)) {
656 $ftp->set_status($status, $message);
665 @_ == 2 || croak 'usage: $ftp->delete( FILENAME )';
671 sub put { shift->_store_cmd("stor", @_) }
672 sub put_unique { shift->_store_cmd("stou", @_) }
673 sub append { shift->_store_cmd("appe", @_) }
676 sub nlst { shift->_data_cmd("NLST", @_) }
677 sub list { shift->_data_cmd("LIST", @_) }
678 sub retr { shift->_data_cmd("RETR", @_) }
679 sub stor { shift->_data_cmd("STOR", @_) }
680 sub stou { shift->_data_cmd("STOU", @_) }
681 sub appe { shift->_data_cmd("APPE", @_) }
685 my ($ftp, $cmd, $local, $remote) = @_;
686 my ($loc, $sock, $len, $buf);
689 my $localfd = ref($local) || ref(\$local) eq "GLOB";
691 unless (defined $remote) {
692 croak 'Must specify remote filename with stream input'
695 require File::Basename;
696 $remote = File::Basename::basename($local);
698 if (defined ${*$ftp}{'net_ftp_allo'}) {
699 delete ${*$ftp}{'net_ftp_allo'};
703 # if the user hasn't already invoked the alloc method since the last
704 # _store_cmd call, figure out if the local file is a regular file(not
705 # a pipe, or device) and if so get the file size from stat, and send
706 # an ALLO command before sending the STOR, STOU, or APPE command.
707 my $size = do { local $^W; -f $local && -s _ }; # no ALLO if sending data from a pipe
708 $ftp->_ALLO($size) if $size;
710 croak("Bad remote filename '$remote'\n")
711 if $remote =~ /[\r\n]/s;
719 unless (sysopen($loc, $local, O_RDONLY)) {
720 carp "Cannot open Local file $local: $!\n";
725 if ($ftp->type eq 'I' && !binmode($loc)) {
726 carp "Cannot binmode Local file $local: $!\n";
730 delete ${*$ftp}{'net_ftp_port'};
731 delete ${*$ftp}{'net_ftp_pasv'};
733 $sock = $ftp->_data_cmd($cmd, $remote)
736 $remote = ($ftp->message =~ /FILE:\s*(.*)/)[0]
737 if 'STOU' eq uc $cmd;
739 my $blksize = ${*$ftp}{'net_ftp_blksize'};
741 my ($count, $hashh, $hashb, $ref) = (0);
743 ($hashh, $hashb) = @$ref
744 if ($ref = ${*$ftp}{'net_ftp_hash'});
747 last unless $len = read($loc, $buf = "", $blksize);
749 if (trEBCDIC && $ftp->type ne 'I') {
750 $buf = $ftp->toascii($buf);
756 print $hashh "#" x (int($count / $hashb));
761 unless (defined($wlen = $sock->write($buf, $len)) && $wlen == $len) {
765 print $hashh "\n" if $hashh;
770 print $hashh "\n" if $hashh;
778 if ('STOU' eq uc $cmd and $ftp->message =~ m/unique\s+file\s*name\s*:\s*(.*)\)|"(.*)"/) {
779 require File::Basename;
780 $remote = File::Basename::basename($+);
788 @_ == 1 || @_ == 2 or croak 'usage: $ftp->port([PORT])';
790 my ($ftp, $port) = @_;
793 delete ${*$ftp}{'net_ftp_intern_port'};
795 unless (defined $port) {
797 # create a Listen socket at same address as the command socket
799 ${*$ftp}{'net_ftp_listen'} ||= IO::Socket::INET->new(
802 Timeout => $ftp->timeout,
803 LocalAddr => $ftp->sockhost,
806 my $listen = ${*$ftp}{'net_ftp_listen'};
808 my ($myport, @myaddr) = ($listen->sockport, split(/\./, $listen->sockhost));
810 $port = join(',', @myaddr, $myport >> 8, $myport & 0xff);
812 ${*$ftp}{'net_ftp_intern_port'} = 1;
815 $ok = $ftp->_PORT($port);
817 ${*$ftp}{'net_ftp_port'} = $port;
823 sub ls { shift->_list_cmd("NLST", @_); }
824 sub dir { shift->_list_cmd("LIST", @_); }
828 @_ == 1 or croak 'usage: $ftp->pasv()';
832 delete ${*$ftp}{'net_ftp_intern_port'};
834 $ftp->_PASV && $ftp->message =~ /(\d+(,\d+)+)/
835 ? ${*$ftp}{'net_ftp_pasv'} = $1
842 ${*$ftp}{'net_ftp_unique'} || undef;
847 @_ == 2 or croak 'usage: $ftp->supported( CMD )';
850 my $hash = ${*$ftp}{'net_ftp_supported'} ||= {};
853 if exists $hash->{$cmd};
855 return $hash->{$cmd} = 0
856 unless $ftp->_HELP($cmd);
858 my $text = $ftp->message;
859 if ($text =~ /following\s+commands/i) {
861 while ($text =~ /(\*?)(\w+)(\*?)/sg) {
862 $hash->{"\U$2"} = !length("$1$3");
866 $hash->{$cmd} = $text !~ /unimplemented/i;
873 ## Deprecated methods
878 carp "Use of Net::FTP::lsl deprecated, use 'dir'"
885 carp "Use of Net::FTP::authorise deprecated, use 'authorize'"
897 my ($ftp, $path) = @_;
899 # This tries to work both with and without the quote doubling
900 # convention (RFC 959 requires it, but the first 3 servers I checked
901 # didn't implement it). It will fail on a server which uses a quote in
902 # the message which isn't a part of or surrounding the path.
904 && $ftp->message =~ /(?:^|\s)\"(.*)\"(?:$|\s)/
905 && ($path = $1) =~ s/\"\"/\"/g;
911 ## Communication methods
918 my $pkg = "Net::FTP::" . $ftp->type;
920 eval "require " . $pkg;
924 delete ${*$ftp}{'net_ftp_dataconn'};
926 if (defined ${*$ftp}{'net_ftp_pasv'}) {
927 my @port = map { 0 + $_ } split(/,/, ${*$ftp}{'net_ftp_pasv'});
930 PeerAddr => join(".", @port[0 .. 3]),
931 PeerPort => $port[4] * 256 + $port[5],
932 LocalAddr => ${*$ftp}{'net_ftp_localaddr'},
936 elsif (defined ${*$ftp}{'net_ftp_listen'}) {
937 $data = ${*$ftp}{'net_ftp_listen'}->accept($pkg);
938 close(delete ${*$ftp}{'net_ftp_listen'});
943 $data->timeout($ftp->timeout);
944 ${*$ftp}{'net_ftp_dataconn'} = $data;
945 ${*$data}{'net_ftp_cmd'} = $ftp;
946 ${*$data}{'net_ftp_blksize'} = ${*$ftp}{'net_ftp_blksize'};
957 delete ${*$ftp}{'net_ftp_port'};
958 delete ${*$ftp}{'net_ftp_pasv'};
960 my $data = $ftp->_data_cmd($cmd, @_);
963 unless (defined $data);
966 bless $data, "Net::FTP::A"; # Force ASCII mode
970 my $blksize = ${*$ftp}{'net_ftp_blksize'};
972 while ($data->read($databuf, $blksize)) {
976 my $list = [split(/\n/, $buf)];
981 for (@$list) { $_ = $ftp->toebcdic($_) }
994 my $where = delete ${*$ftp}{'net_ftp_rest'} || 0;
998 croak("Bad argument '$arg'\n")
999 if $arg =~ /[\r\n]/s;
1002 if ( ${*$ftp}{'net_ftp_passive'}
1003 && !defined ${*$ftp}{'net_ftp_pasv'}
1004 && !defined ${*$ftp}{'net_ftp_port'})
1008 $ok = defined $ftp->pasv;
1009 $ok = $ftp->_REST($where)
1013 $ftp->command($cmd, @_);
1014 $data = $ftp->_dataconn();
1015 $ok = CMD_INFO == $ftp->response();
1018 if $data && $cmd =~ /RETR|LIST|NLST/;
1028 unless (defined ${*$ftp}{'net_ftp_port'}
1029 || defined ${*$ftp}{'net_ftp_pasv'});
1031 $ok = $ftp->_REST($where)
1037 $ftp->command($cmd, @_);
1040 if (defined ${*$ftp}{'net_ftp_pasv'});
1042 $ok = CMD_INFO == $ftp->response();
1045 unless exists ${*$ftp}{'net_ftp_intern_port'};
1048 my $data = $ftp->_dataconn();
1051 if $data && $cmd =~ /RETR|LIST|NLST/;
1057 close(delete ${*$ftp}{'net_ftp_listen'});
1063 ## Over-ride methods (Net::Cmd)
1067 sub debug_text { $_[2] =~ /^(pass|resp|acct)/i ? "$1 ....\n" : $_[2]; }
1073 delete ${*$ftp}{'net_ftp_port'};
1074 $ftp->SUPER::command(@_);
1080 my $code = $ftp->SUPER::response();
1082 delete ${*$ftp}{'net_ftp_pasv'}
1083 if ($code != CMD_MORE && $code != CMD_INFO);
1089 sub parse_response {
1090 return ($1, $2 eq "-")
1091 if $_[1] =~ s/^(\d\d\d)([- ]?)//o;
1095 # Darn MS FTP server is a load of CRAP !!!!
1097 unless ${*$ftp}{'net_cmd_code'} + 0;
1099 (${*$ftp}{'net_cmd_code'}, 1);
1103 ## Allow 2 servers to talk directly
1107 sub pasv_xfer_unique {
1108 my ($sftp, $sfile, $dftp, $dfile) = @_;
1109 $sftp->pasv_xfer($sfile, $dftp, $dfile, 1);
1114 my ($sftp, $sfile, $dftp, $dfile, $unique) = @_;
1116 ($dfile = $sfile) =~ s#.*/##
1117 unless (defined $dfile);
1119 my $port = $sftp->pasv
1126 unless ($unique ? $dftp->stou($dfile) : $dftp->stor($dfile));
1128 unless ($sftp->retr($sfile) && $sftp->response == CMD_INFO) {
1129 $sftp->retr($sfile);
1135 $dftp->pasv_wait($sftp);
1140 @_ == 2 or croak 'usage: $ftp->pasv_wait(NON_PASV_FTP)';
1142 my ($ftp, $non_pasv) = @_;
1143 my ($file, $rin, $rout);
1145 vec($rin = '', fileno($ftp), 1) = 1;
1146 select($rout = $rin, undef, undef, undef);
1149 $non_pasv->response();
1152 unless $ftp->ok() && $non_pasv->ok();
1155 if $ftp->message =~ /unique file name:\s*(\S*)\s*\)/;
1158 if $non_pasv->message =~ /unique file name:\s*(\S*)\s*\)/;
1165 @_ == 2 or croak 'usage: $ftp->feature( NAME )';
1166 my ($ftp, $feat) = @_;
1168 my $feature = ${*$ftp}{net_ftp_feature} ||= do {
1178 @feat = map { /^\s+(.*\S)/ } $ftp->message
1184 return grep { /^\Q$feat\E\b/i } @$feature;
1188 sub cmd { shift->command(@_)->response() }
1190 ########################################
1196 sub _ABOR { shift->command("ABOR")->response() == CMD_OK }
1197 sub _ALLO { shift->command("ALLO", @_)->response() == CMD_OK }
1198 sub _CDUP { shift->command("CDUP")->response() == CMD_OK }
1199 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
1200 sub _PASV { shift->command("PASV")->response() == CMD_OK }
1201 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
1202 sub _DELE { shift->command("DELE", @_)->response() == CMD_OK }
1203 sub _CWD { shift->command("CWD", @_)->response() == CMD_OK }
1204 sub _PORT { shift->command("PORT", @_)->response() == CMD_OK }
1205 sub _RMD { shift->command("RMD", @_)->response() == CMD_OK }
1206 sub _MKD { shift->command("MKD", @_)->response() == CMD_OK }
1207 sub _PWD { shift->command("PWD", @_)->response() == CMD_OK }
1208 sub _TYPE { shift->command("TYPE", @_)->response() == CMD_OK }
1209 sub _RNTO { shift->command("RNTO", @_)->response() == CMD_OK }
1210 sub _RESP { shift->command("RESP", @_)->response() == CMD_OK }
1211 sub _MDTM { shift->command("MDTM", @_)->response() == CMD_OK }
1212 sub _SIZE { shift->command("SIZE", @_)->response() == CMD_OK }
1213 sub _HELP { shift->command("HELP", @_)->response() == CMD_OK }
1214 sub _STAT { shift->command("STAT", @_)->response() == CMD_OK }
1215 sub _FEAT { shift->command("FEAT", @_)->response() == CMD_OK }
1216 sub _APPE { shift->command("APPE", @_)->response() == CMD_INFO }
1217 sub _LIST { shift->command("LIST", @_)->response() == CMD_INFO }
1218 sub _NLST { shift->command("NLST", @_)->response() == CMD_INFO }
1219 sub _RETR { shift->command("RETR", @_)->response() == CMD_INFO }
1220 sub _STOR { shift->command("STOR", @_)->response() == CMD_INFO }
1221 sub _STOU { shift->command("STOU", @_)->response() == CMD_INFO }
1222 sub _RNFR { shift->command("RNFR", @_)->response() == CMD_MORE }
1223 sub _REST { shift->command("REST", @_)->response() == CMD_MORE }
1224 sub _PASS { shift->command("PASS", @_)->response() }
1225 sub _ACCT { shift->command("ACCT", @_)->response() }
1226 sub _AUTH { shift->command("AUTH", @_)->response() }
1231 my $ok = $ftp->command("USER", @_)->response();
1233 # A certain brain dead firewall :-)
1234 $ok = $ftp->command("user", @_)->response()
1235 unless $ok == CMD_MORE or $ok == CMD_OK;
1241 sub _SMNT { shift->unsupported(@_) }
1242 sub _MODE { shift->unsupported(@_) }
1243 sub _SYST { shift->unsupported(@_) }
1244 sub _STRU { shift->unsupported(@_) }
1245 sub _REIN { shift->unsupported(@_) }
1253 Net::FTP - FTP Client class
1259 $ftp = Net::FTP->new("some.host.name", Debug => 0)
1260 or die "Cannot connect to some.host.name: $@";
1262 $ftp->login("anonymous",'-anonymous@')
1263 or die "Cannot login ", $ftp->message;
1266 or die "Cannot change working directory ", $ftp->message;
1268 $ftp->get("that.file")
1269 or die "get failed ", $ftp->message;
1275 C<Net::FTP> is a class implementing a simple FTP client in Perl as
1276 described in RFC959. It provides wrappers for a subset of the RFC959
1281 FTP stands for File Transfer Protocol. It is a way of transferring
1282 files between networked machines. The protocol defines a client
1283 (whose commands are provided by this module) and a server (not
1284 implemented in this module). Communication is always initiated by the
1285 client, and the server responds with a message and a status code (and
1286 sometimes with data).
1288 The FTP protocol allows files to be sent to or fetched from the
1289 server. Each transfer involves a B<local file> (on the client) and a
1290 B<remote file> (on the server). In this module, the same file name
1291 will be used for both local and remote if only one is specified. This
1292 means that transferring remote file C</path/to/file> will try to put
1293 that file in C</path/to/file> locally, unless you specify a local file
1296 The protocol also defines several standard B<translations> which the
1297 file can undergo during transfer. These are ASCII, EBCDIC, binary,
1298 and byte. ASCII is the default type, and indicates that the sender of
1299 files will translate the ends of lines to a standard representation
1300 which the receiver will then translate back into their local
1301 representation. EBCDIC indicates the file being transferred is in
1302 EBCDIC format. Binary (also known as image) format sends the data as
1303 a contiguous bit stream. Byte format transfers the data as bytes, the
1304 values of which remain the same regardless of differences in byte size
1305 between the two machines (in theory - in practice you should only use
1306 this if you really know what you're doing).
1312 =item new ([ HOST ] [, OPTIONS ])
1314 This is the constructor for a new Net::FTP object. C<HOST> is the
1315 name of the remote host to which an FTP connection is required.
1317 C<HOST> is optional. If C<HOST> is not given then it may instead be
1318 passed as the C<Host> option described below.
1320 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
1321 Possible options are:
1323 B<Host> - FTP host to connect to. It may be a single scalar, as defined for
1324 the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
1325 an array with hosts to try in turn. The L</host> method will return the value
1326 which was used to connect to the host.
1329 B<Firewall> - The name of a machine which acts as an FTP firewall. This can be
1330 overridden by an environment variable C<FTP_FIREWALL>. If specified, and the
1331 given host cannot be directly connected to, then the
1332 connection is made to the firewall machine and the string C<@hostname> is
1333 appended to the login identifier. This kind of setup is also referred to
1336 B<FirewallType> - The type of firewall running on the machine indicated by
1337 B<Firewall>. This can be overridden by an environment variable
1338 C<FTP_FIREWALL_TYPE>. For a list of permissible types, see the description of
1339 ftp_firewall_type in L<Net::Config>.
1341 B<BlockSize> - This is the block size that Net::FTP will use when doing
1342 transfers. (defaults to 10240)
1344 B<Port> - The port number to connect to on the remote machine for the
1347 B<Timeout> - Set a timeout value (defaults to 120)
1349 B<Debug> - debug level (see the debug method in L<Net::Cmd>)
1351 B<Passive> - If set to a non-zero value then all data transfers will
1352 be done using passive mode. If set to zero then data transfers will be
1353 done using active mode. If the machine is connected to the Internet
1354 directly, both passive and active mode should work equally well.
1355 Behind most firewall and NAT configurations passive mode has a better
1356 chance of working. However, in some rare firewall configurations,
1357 active mode actually works when passive mode doesn't. Some really old
1358 FTP servers might not implement passive transfers. If not specified,
1359 then the transfer mode is set by the environment variable
1360 C<FTP_PASSIVE> or if that one is not set by the settings done by the
1361 F<libnetcfg> utility. If none of these apply then passive mode is
1364 B<Hash> - If given a reference to a file handle (e.g., C<\*STDERR>),
1365 print hash marks (#) on that filehandle every 1024 bytes. This
1366 simply invokes the C<hash()> method for you, so that hash marks
1367 are displayed for all transfers. You can, of course, call C<hash()>
1368 explicitly whenever you'd like.
1370 B<LocalAddr> - Local address to use for all socket connections, this
1371 argument will be passed to L<IO::Socket::INET>
1373 If the constructor fails undef will be returned and an error message will
1380 Unless otherwise stated all methods return either a I<true> or I<false>
1381 value, with I<true> meaning that the operation was a success. When a method
1382 states that it returns a value, failure will be returned as I<undef> or an
1387 =item login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])
1389 Log into the remote FTP server with the given login information. If
1390 no arguments are given then the C<Net::FTP> uses the C<Net::Netrc>
1391 package to lookup the login information for the connected host.
1392 If no information is found then a login of I<anonymous> is used.
1393 If no password is given and the login is I<anonymous> then I<anonymous@>
1394 will be used for password.
1396 If the connection is via a firewall then the C<authorize> method will
1397 be called with no arguments.
1399 =item authorize ( [AUTH [, RESP]])
1401 This is a protocol used by some firewall ftp proxies. It is used
1402 to authorise the user to send data out. If both arguments are not specified
1403 then C<authorize> uses C<Net::Netrc> to do a lookup.
1407 Send a SITE command to the remote server and wait for a response.
1409 Returns most significant digit of the response code.
1413 Transfer file in ASCII. CRLF translation will be done if required
1417 Transfer file in binary mode. No transformation will be done.
1419 B<Hint>: If both server and client machines use the same line ending for
1420 text files, then it will be faster to transfer all files in binary mode.
1422 =item rename ( OLDNAME, NEWNAME )
1424 Rename a file on the remote FTP server from C<OLDNAME> to C<NEWNAME>. This
1425 is done by sending the RNFR and RNTO commands.
1427 =item delete ( FILENAME )
1429 Send a request to the server to delete C<FILENAME>.
1431 =item cwd ( [ DIR ] )
1433 Attempt to change directory to the directory given in C<$dir>. If
1434 C<$dir> is C<"..">, the FTP C<CDUP> command is used to attempt to
1435 move up one directory. If no directory is given then an attempt is made
1436 to change the directory to the root directory.
1440 Change directory to the parent of the current directory.
1444 Returns the full pathname of the current directory.
1446 =item restart ( WHERE )
1448 Set the byte offset at which to begin the next data transfer. Net::FTP simply
1449 records this value and uses it when during the next data transfer. For this
1450 reason this method will not return an error, but setting it may cause
1451 a subsequent data transfer to fail.
1453 =item rmdir ( DIR [, RECURSE ])
1455 Remove the directory with the name C<DIR>. If C<RECURSE> is I<true> then
1456 C<rmdir> will attempt to delete everything inside the directory.
1458 =item mkdir ( DIR [, RECURSE ])
1460 Create a new directory with the name C<DIR>. If C<RECURSE> is I<true> then
1461 C<mkdir> will attempt to create all the directories in the given path.
1463 Returns the full pathname to the new directory.
1465 =item alloc ( SIZE [, RECORD_SIZE] )
1467 The alloc command allows you to give the ftp server a hint about the size
1468 of the file about to be transferred using the ALLO ftp command. Some storage
1469 systems use this to make intelligent decisions about how to store the file.
1470 The C<SIZE> argument represents the size of the file in bytes. The
1471 C<RECORD_SIZE> argument indicates a maximum record or page size for files
1472 sent with a record or page structure.
1474 The size of the file will be determined, and sent to the server
1475 automatically for normal files so that this method need only be called if
1476 you are transferring data from a socket, named pipe, or other stream not
1477 associated with a normal file.
1479 =item ls ( [ DIR ] )
1481 Get a directory listing of C<DIR>, or the current directory.
1483 In an array context, returns a list of lines returned from the server. In
1484 a scalar context, returns a reference to a list.
1486 =item dir ( [ DIR ] )
1488 Get a directory listing of C<DIR>, or the current directory in long format.
1490 In an array context, returns a list of lines returned from the server. In
1491 a scalar context, returns a reference to a list.
1493 =item get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )
1495 Get C<REMOTE_FILE> from the server and store locally. C<LOCAL_FILE> may be
1496 a filename or a filehandle. If not specified, the file will be stored in
1497 the current directory with the same leafname as the remote file.
1499 If C<WHERE> is given then the first C<WHERE> bytes of the file will
1500 not be transferred, and the remaining bytes will be appended to
1501 the local file if it already exists.
1503 Returns C<LOCAL_FILE>, or the generated local file name if C<LOCAL_FILE>
1504 is not given. If an error was encountered undef is returned.
1506 =item put ( LOCAL_FILE [, REMOTE_FILE ] )
1508 Put a file on the remote server. C<LOCAL_FILE> may be a name or a filehandle.
1509 If C<LOCAL_FILE> is a filehandle then C<REMOTE_FILE> must be specified. If
1510 C<REMOTE_FILE> is not specified then the file will be stored in the current
1511 directory with the same leafname as C<LOCAL_FILE>.
1513 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1516 B<NOTE>: If for some reason the transfer does not complete and an error is
1517 returned then the contents that had been transferred will not be remove
1520 =item put_unique ( LOCAL_FILE [, REMOTE_FILE ] )
1522 Same as put but uses the C<STOU> command.
1524 Returns the name of the file on the server.
1526 =item append ( LOCAL_FILE [, REMOTE_FILE ] )
1528 Same as put but appends to the file on the remote server.
1530 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1533 =item unique_name ()
1535 Returns the name of the last file stored on the server using the
1540 Returns the I<modification time> of the given file
1544 Returns the size in bytes for the given file as stored on the remote server.
1546 B<NOTE>: The size reported is the size of the stored file on the remote server.
1547 If the file is subsequently transferred from the server in ASCII mode
1548 and the remote server and local machine have different ideas about
1549 "End Of Line" then the size of file on the local machine after transfer
1552 =item supported ( CMD )
1554 Returns TRUE if the remote server supports the given command.
1556 =item hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )
1558 Called without parameters, or with the first argument false, hash marks
1559 are suppressed. If the first argument is true but not a reference to a
1560 file handle glob, then \*STDERR is used. The second argument is the number
1561 of bytes per hash mark printed, and defaults to 1024. In all cases the
1562 return value is a reference to an array of two: the filehandle glob reference
1563 and the bytes per hash mark.
1565 =item feature ( NAME )
1567 Determine if the server supports the specified feature. The return
1568 value is a list of lines the server responded with to describe the
1569 options that it supports for the given feature. If the feature is
1570 unsupported then the empty list is returned.
1572 if ($ftp->feature( 'MDTM' )) {
1576 if (grep { /\bTLS\b/ } $ftp->feature('AUTH')) {
1577 # Server supports TLS
1582 The following methods can return different results depending on
1583 how they are called. If the user explicitly calls either
1584 of the C<pasv> or C<port> methods then these methods will
1585 return a I<true> or I<false> value. If the user does not
1586 call either of these methods then the result will be a
1587 reference to a C<Net::FTP::dataconn> based object.
1591 =item nlst ( [ DIR ] )
1593 Send an C<NLST> command to the server, with an optional parameter.
1595 =item list ( [ DIR ] )
1597 Same as C<nlst> but using the C<LIST> command
1601 Begin the retrieval of a file called C<FILE> from the remote server.
1605 Tell the server that you wish to store a file. C<FILE> is the
1606 name of the new file that should be created.
1610 Same as C<stor> but using the C<STOU> command. The name of the unique
1611 file which was created on the server will be available via the C<unique_name>
1612 method after the data connection has been closed.
1616 Tell the server that we want to append some data to the end of a file
1617 called C<FILE>. If this file does not exist then create it.
1621 If for some reason you want to have complete control over the data connection,
1622 this includes generating it and calling the C<response> method when required,
1623 then the user can use these methods to do so.
1625 However calling these methods only affects the use of the methods above that
1626 can return a data connection. They have no effect on methods C<get>, C<put>,
1627 C<put_unique> and those that do not require data connections.
1631 =item port ( [ PORT ] )
1633 Send a C<PORT> command to the server. If C<PORT> is specified then it is sent
1634 to the server. If not, then a listen socket is created and the correct information
1639 Tell the server to go into passive mode. Returns the text that represents the
1640 port on which the server is listening, this text is in a suitable form to
1641 sent to another ftp server using the C<port> method.
1645 The following methods can be used to transfer files between two remote
1646 servers, providing that these two servers can connect directly to each other.
1650 =item pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1652 This method will do a file transfer between two remote ftp servers. If
1653 C<DEST_FILE> is omitted then the leaf name of C<SRC_FILE> will be used.
1655 =item pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1657 Like C<pasv_xfer> but the file is stored on the remote server using
1660 =item pasv_wait ( NON_PASV_SERVER )
1662 This method can be used to wait for a transfer to complete between a passive
1663 server and a non-passive server. The method should be called on the passive
1664 server with the C<Net::FTP> object for the non-passive server passed as an
1669 Abort the current data transfer.
1673 Send the QUIT command to the remote FTP server and close the socket connection.
1677 =head2 Methods for the adventurous
1679 C<Net::FTP> inherits from C<Net::Cmd> so methods defined in C<Net::Cmd> may
1680 be used to send commands to the remote FTP server.
1684 =item quot (CMD [,ARGS])
1686 Send a command, that Net::FTP does not directly support, to the remote
1687 server and wait for a response.
1689 Returns most significant digit of the response code.
1691 B<WARNING> This call should only be used on commands that do not require
1692 data connections. Misuse of this method can hang the connection.
1696 =head1 THE dataconn CLASS
1698 Some of the methods defined in C<Net::FTP> return an object which will
1699 be derived from this class.The dataconn class itself is derived from
1700 the C<IO::Socket::INET> class, so any normal IO operations can be performed.
1701 However the following methods are defined in the dataconn class and IO should
1702 be performed using these.
1706 =item read ( BUFFER, SIZE [, TIMEOUT ] )
1708 Read C<SIZE> bytes of data from the server and place it into C<BUFFER>, also
1709 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1710 given, the timeout value from the command connection will be used.
1712 Returns the number of bytes read before any <CRLF> translation.
1714 =item write ( BUFFER, SIZE [, TIMEOUT ] )
1716 Write C<SIZE> bytes of data from C<BUFFER> to the server, also
1717 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1718 given, the timeout value from the command connection will be used.
1720 Returns the number of bytes written before any <CRLF> translation.
1724 Returns the number of bytes read so far.
1728 Abort the current data transfer.
1732 Close the data connection and get a response from the FTP server. Returns
1733 I<true> if the connection was closed successfully and the first digit of
1734 the response from the server was a '2'.
1738 =head1 UNIMPLEMENTED
1740 The following RFC959 commands have not been implemented:
1746 Mount a different file system structure without changing login or
1747 accounting information.
1751 Ask the server for "helpful information" (that's what the RFC says) on
1752 the commands it accepts.
1756 Specifies transfer mode (stream, block or compressed) for file to be
1761 Request remote server system identification.
1765 Request remote server status.
1769 Specifies file structure for file to be transferred.
1773 Reinitialize the connection, flushing all I/O and account information.
1777 =head1 REPORTING BUGS
1779 When reporting bugs/problems please include as much information as possible.
1780 It may be difficult for me to reproduce the problem as almost every setup
1783 A small script which yields the problem will probably be of help. It would
1784 also be useful if this script was run with the extra options C<Debug => 1>
1785 passed to the constructor, and the output sent with the bug report. If you
1786 cannot include a small script then please include a Debug trace from a
1787 run of your program which does yield the problem.
1791 Graham Barr <gbarr@pobox.com>
1798 ftp(1), ftpd(8), RFC 959
1799 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html
1803 For an example of the use of Net::FTP see
1807 =item http://www.csh.rit.edu/~adam/Progs/
1809 C<autoftp> is a program that can retrieve, send, or list files via
1810 the FTP protocol in a non-interactive manner.
1816 Henry Gabryjelski <henryg@WPI.EDU> - for the suggestion of creating directories
1819 Nathan Torkington <gnat@frii.com> - for some input on the documentation.
1821 Roderick Schertler <roderick@gate.net> - for various inputs
1825 Copyright (c) 1995-2004 Graham Barr. All rights reserved.
1826 This program is free software; you can redistribute it and/or modify it
1827 under the same terms as Perl itself.