3 # Copyright (c) 1995-8 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);
23 # use AutoLoader qw(AUTOLOAD);
25 $VERSION = "2.65"; # $Id: //depot/libnet/Net/FTP.pm#68 $
26 @ISA = qw(Exporter Net::Cmd IO::Socket::INET);
28 # Someday I will "use constant", when I am not bothered to much about
29 # compatability with older releases of perl
31 use vars qw($TELNET_IAC $TELNET_IP $TELNET_DM);
32 ($TELNET_IAC,$TELNET_IP,$TELNET_DM) = (255,244,242);
34 # Name is too long for AutoLoad, it clashes with pasv_xfer
35 sub pasv_xfer_unique {
36 my($sftp,$sfile,$dftp,$dfile) = @_;
37 $sftp->pasv_xfer($sfile,$dftp,$dfile,1);
41 # make a constant so code is fast'ish
42 my $is_os390 = $^O eq 'os390';
43 *trEBCDIC = sub () { $is_os390 }
47 # Having problems with AutoLoader
58 my $fire_type = undef;
60 if(exists($arg{Firewall}) || Net::Config->requires_firewall($peer))
62 $fire = $arg{Firewall}
64 || $NetConfig{ftp_firewall}
71 $fire_type = $arg{FirewallType}
72 || $ENV{FTP_FIREWALL_TYPE}
77 my $ftp = $pkg->SUPER::new(PeerAddr => $peer,
78 PeerPort => $arg{Port} || 'ftp(21)',
80 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_firewall'} = $fire
91 ${*$ftp}{'net_ftp_firewall_type'} = $fire_type
92 if(defined $fire_type);
94 ${*$ftp}{'net_ftp_passive'} = int
97 : exists $ENV{FTP_PASSIVE}
100 ? $NetConfig{ftp_ext_passive}
101 : $NetConfig{ftp_int_passive}; # Whew! :-)
103 $ftp->hash(exists $arg{Hash} ? $arg{Hash} : 0, 1024);
107 $ftp->debug(exists $arg{Debug} ? $arg{Debug} : undef);
109 unless ($ftp->response() == CMD_OK)
120 ## User interface methods
124 my $ftp = shift; # self
128 delete ${*$ftp}{'net_ftp_hash'};
131 ($h,$b) = (ref($h)? $h : \*STDERR, $b || 1024);
132 select((select($h), $|=1)[0]);
133 $b = 512 if $b < 512;
134 ${*$ftp}{'net_ftp_hash'} = [$h, $b];
147 sub ascii { shift->type('A',@_); }
148 sub binary { shift->type('I',@_); }
152 carp "TYPE E is unsupported, shall default to I";
158 carp "TYPE L is unsupported, shall default to I";
162 # Allow the user to send a command directly, BE CAREFUL !!
169 $ftp->command( uc $cmd, @_);
177 $ftp->command("SITE", @_);
186 # Server Y2K bug workaround
188 # sigh; some idiotic FTP servers use ("19%d",tm.tm_year) instead of
189 # ("%d",tm.tm_year+1900). This results in an extra digit in the
190 # string returned. To account for this we allow an optional extra
191 # digit in the year. Then if the first two digits are 19 we use the
192 # remainder, otherwise we subtract 1900 from the whole year.
194 $ftp->_MDTM($file) && $ftp->message =~ /((\d\d)(\d\d\d?))(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)/
195 ? timegm($8,$7,$6,$5,$4-1,$2 eq '19' ? $3 : ($1-1900))
203 if($ftp->supported("SIZE")) {
204 return $ftp->_SIZE($file)
205 ? ($ftp->message =~ /(\d+)$/)[0]
208 elsif($ftp->supported("STAT")) {
211 unless $ftp->_STAT($file) && (@msg = $ftp->message) == 3;
213 foreach $line (@msg) {
214 return (split(/\s+/,$line))[4]
215 if $line =~ /^[-rwx]{10}/
219 my @files = $ftp->dir($file);
221 return (split(/\s+/,$1))[4]
222 if $files[0] =~ /^([-rwx]{10}.*)$/;
229 my($ftp,$user,$pass,$acct) = @_;
230 my($ok,$ruser,$fwtype);
232 unless (defined $user) {
235 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'});
237 ($user,$pass,$acct) = $rc->lpa()
241 $user ||= "anonymous";
244 $fwtype = ${*$ftp}{'net_ftp_firewall_type'}
245 || $NetConfig{'ftp_firewall_type'}
248 if ($fwtype && defined ${*$ftp}{'net_ftp_firewall'}) {
249 if ($fwtype == 1 || $fwtype == 7) {
250 $user .= '@' . ${*$ftp}{'net_ftp_host'};
255 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
257 my($fwuser,$fwpass,$fwacct) = $rc ? $rc->lpa() : ();
260 $user = join('@',$user,$fwuser,${*$ftp}{'net_ftp_host'});
261 $pass = $pass . '@' . $fwpass;
265 $user .= '@' . ${*$ftp}{'net_ftp_host'};
267 elsif ($fwtype == 6) {
268 $fwuser .= '@' . ${*$ftp}{'net_ftp_host'};
271 $ok = $ftp->_USER($fwuser);
273 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
275 $ok = $ftp->_PASS($fwpass || "");
277 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
279 $ok = $ftp->_ACCT($fwacct)
283 $ok = $ftp->command("SITE",${*$ftp}{'net_ftp_host'})->response;
285 elsif ($fwtype == 4) {
286 $ok = $ftp->command("OPEN",${*$ftp}{'net_ftp_host'})->response;
289 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
294 $ok = $ftp->_USER($user);
296 # Some dumb firewalls don't prefix the connection messages
297 $ok = $ftp->response()
298 if ($ok == CMD_OK && $ftp->code == 220 && $user =~ /\@/);
300 if ($ok == CMD_MORE) {
301 unless(defined $pass) {
304 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'}, $ruser);
306 ($ruser,$pass,$acct) = $rc->lpa()
309 $pass = '-anonymous@'
310 if (!defined $pass && (!defined($ruser) || $ruser =~ /^anonymous/o));
313 $ok = $ftp->_PASS($pass || "");
316 $ok = $ftp->_ACCT($acct)
317 if (defined($acct) && ($ok == CMD_MORE || $ok == CMD_OK));
319 if ($fwtype == 7 && $ok == CMD_OK && defined ${*$ftp}{'net_ftp_firewall'}) {
320 my($f,$auth,$resp) = _auth_id($ftp);
321 $ftp->authorize($auth,$resp) if defined($resp);
329 @_ == 2 or croak 'usage: $ftp->account( ACCT )';
332 $ftp->_ACCT($acct) == CMD_OK;
336 my($ftp,$auth,$resp) = @_;
338 unless(defined $resp)
342 $auth ||= eval { (getpwuid($>))[0] } || $ENV{NAME};
344 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'}, $auth)
345 || Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
347 ($auth,$resp) = $rc->lpa()
355 @_ >= 1 || @_ <= 3 or croak 'usage: $ftp->authorize( [AUTH [, RESP]])';
357 my($ftp,$auth,$resp) = &_auth_id;
359 my $ok = $ftp->_AUTH($auth || "");
361 $ok = $ftp->_RESP($resp || "")
362 if ($ok == CMD_MORE);
369 @_ == 3 or croak 'usage: $ftp->rename(FROM, TO)';
371 my($ftp,$from,$to) = @_;
381 my $oldval = ${*$ftp}{'net_ftp_type'};
384 unless (defined $type);
387 unless ($ftp->_TYPE($type,@_));
389 ${*$ftp}{'net_ftp_type'} = join(" ",$type,@_);
398 send($ftp,pack("CCC", $TELNET_IAC, $TELNET_IP, $TELNET_IAC),MSG_OOB);
400 $ftp->command(pack("C",$TELNET_DM) . "ABOR");
402 ${*$ftp}{'net_ftp_dataconn'}->close()
403 if defined ${*$ftp}{'net_ftp_dataconn'};
407 $ftp->status == CMD_OK;
412 my($ftp,$remote,$local,$where) = @_;
414 my($loc,$len,$buf,$resp,$data);
417 my $localfd = ref($local) || ref(\$local) eq "GLOB";
419 ($local = $remote) =~ s#^.*/##
420 unless(defined $local);
422 croak("Bad remote filename '$remote'\n")
423 if $remote =~ /[\r\n]/s;
425 ${*$ftp}{'net_ftp_rest'} = $where
428 delete ${*$ftp}{'net_ftp_port'};
429 delete ${*$ftp}{'net_ftp_pasv'};
431 $data = $ftp->retr($remote) or
442 unless(sysopen($loc, $local, O_CREAT | O_WRONLY | ($where ? O_APPEND : O_TRUNC)))
444 carp "Cannot open Local file $local: $!\n";
450 if($ftp->type eq 'I' && !binmode($loc))
452 carp "Cannot binmode Local file $local: $!\n";
454 close($loc) unless $localfd;
459 my($count,$hashh,$hashb,$ref) = (0);
461 ($hashh,$hashb) = @$ref
462 if($ref = ${*$ftp}{'net_ftp_hash'});
464 my $blksize = ${*$ftp}{'net_ftp_blksize'};
468 last unless $len = $data->read($buf,$blksize);
470 if (trEBCDIC && $ftp->type ne 'I')
472 $buf = $ftp->toebcdic($buf);
478 print $hashh "#" x (int($count / $hashb));
481 my $written = syswrite($loc,$buf,$len);
482 unless(defined($written) && $written == $len)
484 carp "Cannot write to Local file $local: $!\n";
492 print $hashh "\n" if $hashh;
498 carp "Cannot close file $local (perhaps disk space) $!\n";
503 unless ($data->close()) # implied $ftp->response
505 carp "Unable to close datastream";
514 @_ == 1 || @_ == 2 or croak 'usage: $ftp->cwd( [ DIR ] )';
518 $dir = "/" unless defined($dir) && $dir =~ /\S/;
527 @_ == 1 or croak 'usage: $ftp->cdup()';
533 @_ == 1 || croak 'usage: $ftp->pwd()';
540 # rmdir( $ftp, $dir, [ $recurse ] )
542 # Removes $dir on remote host via FTP.
543 # $ftp is handle for remote host
545 # If $recurse is TRUE, the directory and deleted recursively.
546 # This means all of its contents and subdirectories.
548 # Initial version contributed by Dinkum Software
552 @_ == 2 || @_ == 3 or croak('usage: $ftp->rmdir( DIR [, RECURSE ] )');
555 my ($ftp, $dir, $recurse) = @_ ;
559 if $ok = $ftp->_RMD( $dir ) or !$recurse;
561 # Try to delete the contents
562 # Get a list of all the files in the directory
563 my $filelist = $ftp->ls($dir);
566 unless $filelist && @$filelist; # failed, it is probably not a directory
568 # Go thru and delete each file or the directory
570 foreach $file (map { m,/, ? $_ : "$dir/$_" } @$filelist)
572 next # successfully deleted the file
573 if $ftp->delete($file);
575 # Failed to delete it, assume its a directory
576 # Recurse and ignore errors, the final rmdir() will
577 # fail on any errors here
579 unless $ok = $ftp->rmdir($file, 1) ;
582 # Directory should be empty
583 # Try to remove the directory again
584 # Pass results directly to caller
585 # If any of the prior deletes failed, this
586 # rmdir() will fail because directory is not empty
587 return $ftp->_RMD($dir) ;
592 @_ == 2 || croak 'usage: $ftp->restart( BYTE_OFFSET )';
594 my($ftp,$where) = @_;
596 ${*$ftp}{'net_ftp_rest'} = $where;
604 @_ == 2 || @_ == 3 or croak 'usage: $ftp->mkdir( DIR [, RECURSE ] )';
606 my($ftp,$dir,$recurse) = @_;
608 $ftp->_MKD($dir) || $recurse or
615 my @path = split(m#(?=/+)#, $dir);
621 $path .= shift @path;
625 $path = $ftp->_extract_path($path);
628 # If the creation of the last element was not sucessful, see if we
629 # can cd to it, if so then return path
633 my($status,$message) = ($ftp->status,$ftp->message);
636 if($pwd && $ftp->cwd($dir))
645 $ftp->set_status($status,$message);
654 @_ == 2 || croak 'usage: $ftp->delete( FILENAME )';
659 sub put { shift->_store_cmd("stor",@_) }
660 sub put_unique { shift->_store_cmd("stou",@_) }
661 sub append { shift->_store_cmd("appe",@_) }
663 sub nlst { shift->_data_cmd("NLST",@_) }
664 sub list { shift->_data_cmd("LIST",@_) }
665 sub retr { shift->_data_cmd("RETR",@_) }
666 sub stor { shift->_data_cmd("STOR",@_) }
667 sub stou { shift->_data_cmd("STOU",@_) }
668 sub appe { shift->_data_cmd("APPE",@_) }
672 my($ftp,$cmd,$local,$remote) = @_;
673 my($loc,$sock,$len,$buf);
676 my $localfd = ref($local) || ref(\$local) eq "GLOB";
678 unless(defined $remote)
680 croak 'Must specify remote filename with stream input'
683 require File::Basename;
684 $remote = File::Basename::basename($local);
687 croak("Bad remote filename '$remote'\n")
688 if $remote =~ /[\r\n]/s;
698 unless(sysopen($loc, $local, O_RDONLY))
700 carp "Cannot open Local file $local: $!\n";
705 if($ftp->type eq 'I' && !binmode($loc))
707 carp "Cannot binmode Local file $local: $!\n";
711 delete ${*$ftp}{'net_ftp_port'};
712 delete ${*$ftp}{'net_ftp_pasv'};
714 $sock = $ftp->_data_cmd($cmd, $remote) or
717 my $blksize = ${*$ftp}{'net_ftp_blksize'};
719 my($count,$hashh,$hashb,$ref) = (0);
721 ($hashh,$hashb) = @$ref
722 if($ref = ${*$ftp}{'net_ftp_hash'});
726 last unless $len = sysread($loc,$buf="",$blksize);
728 if (trEBCDIC && $ftp->type ne 'I')
730 $buf = $ftp->toascii($buf);
736 print $hashh "#" x (int($count / $hashb));
741 unless(defined($wlen = $sock->write($buf,$len)) && $wlen == $len)
746 print $hashh "\n" if $hashh;
751 print $hashh "\n" if $hashh;
759 if ('STOU' eq uc $cmd and $ftp->message =~ m/unique\s+file\s*name\s*:\s*(.*)\)|"(.*)"/)
761 require File::Basename;
762 $remote = File::Basename::basename($+)
770 @_ == 1 || @_ == 2 or croak 'usage: $ftp->port([PORT])';
775 delete ${*$ftp}{'net_ftp_intern_port'};
777 unless(defined $port)
779 # create a Listen socket at same address as the command socket
781 ${*$ftp}{'net_ftp_listen'} ||= IO::Socket::INET->new(Listen => 5,
783 Timeout => $ftp->timeout,
784 LocalAddr => $ftp->sockhost,
787 my $listen = ${*$ftp}{'net_ftp_listen'};
789 my($myport, @myaddr) = ($listen->sockport, split(/\./,$listen->sockhost));
791 $port = join(',', @myaddr, $myport >> 8, $myport & 0xff);
793 ${*$ftp}{'net_ftp_intern_port'} = 1;
796 $ok = $ftp->_PORT($port);
798 ${*$ftp}{'net_ftp_port'} = $port;
803 sub ls { shift->_list_cmd("NLST",@_); }
804 sub dir { shift->_list_cmd("LIST",@_); }
808 @_ == 1 or croak 'usage: $ftp->pasv()';
812 delete ${*$ftp}{'net_ftp_intern_port'};
814 $ftp->_PASV && $ftp->message =~ /(\d+(,\d+)+)/
815 ? ${*$ftp}{'net_ftp_pasv'} = $1
822 ${*$ftp}{'net_ftp_unique'} || undef;
826 @_ == 2 or croak 'usage: $ftp->supported( CMD )';
829 my $hash = ${*$ftp}{'net_ftp_supported'} ||= {};
832 if exists $hash->{$cmd};
834 return $hash->{$cmd} = 0
835 unless $ftp->_HELP($cmd);
837 my $text = $ftp->message;
838 if($text =~ /following\s+commands/i) {
840 while($text =~ /(\*?)(\w+)(\*?)/sg) {
841 $hash->{"\U$2"} = !length("$1$3");
845 $hash->{$cmd} = $text !~ /unimplemented/i;
852 ## Deprecated methods
857 carp "Use of Net::FTP::lsl deprecated, use 'dir'"
864 carp "Use of Net::FTP::authorise deprecated, use 'authorize'"
876 my($ftp, $path) = @_;
878 # This tries to work both with and without the quote doubling
879 # convention (RFC 959 requires it, but the first 3 servers I checked
880 # didn't implement it). It will fail on a server which uses a quote in
881 # the message which isn't a part of or surrounding the path.
883 $ftp->message =~ /(?:^|\s)\"(.*)\"(?:$|\s)/ &&
884 ($path = $1) =~ s/\"\"/\"/g;
890 ## Communication methods
897 my $pkg = "Net::FTP::" . $ftp->type;
899 eval "require " . $pkg;
903 delete ${*$ftp}{'net_ftp_dataconn'};
905 if(defined ${*$ftp}{'net_ftp_pasv'})
907 my @port = split(/,/,${*$ftp}{'net_ftp_pasv'});
909 $data = $pkg->new(PeerAddr => join(".",@port[0..3]),
910 PeerPort => $port[4] * 256 + $port[5],
914 elsif(defined ${*$ftp}{'net_ftp_listen'})
916 $data = ${*$ftp}{'net_ftp_listen'}->accept($pkg);
917 close(delete ${*$ftp}{'net_ftp_listen'});
923 $data->timeout($ftp->timeout);
924 ${*$ftp}{'net_ftp_dataconn'} = $data;
925 ${*$data}{'net_ftp_cmd'} = $ftp;
926 ${*$data}{'net_ftp_blksize'} = ${*$ftp}{'net_ftp_blksize'};
937 delete ${*$ftp}{'net_ftp_port'};
938 delete ${*$ftp}{'net_ftp_pasv'};
940 my $data = $ftp->_data_cmd($cmd,@_);
943 unless(defined $data);
946 bless $data, "Net::FTP::A"; # Force ASCII mode
950 my $blksize = ${*$ftp}{'net_ftp_blksize'};
952 while($data->read($databuf,$blksize)) {
956 my $list = [ split(/\n/,$buf) ];
962 for (@$list) { $_ = $ftp->toebcdic($_) }
974 my $where = delete ${*$ftp}{'net_ftp_rest'} || 0;
978 croak("Bad argument '$arg'\n")
979 if $arg =~ /[\r\n]/s;
982 if(${*$ftp}{'net_ftp_passive'} &&
983 !defined ${*$ftp}{'net_ftp_pasv'} &&
984 !defined ${*$ftp}{'net_ftp_port'})
988 $ok = defined $ftp->pasv;
989 $ok = $ftp->_REST($where)
994 $ftp->command($cmd,@_);
995 $data = $ftp->_dataconn();
996 $ok = CMD_INFO == $ftp->response();
1000 if $data && $cmd =~ /RETR|LIST|NLST/;
1010 unless (defined ${*$ftp}{'net_ftp_port'} ||
1011 defined ${*$ftp}{'net_ftp_pasv'});
1013 $ok = $ftp->_REST($where)
1019 $ftp->command($cmd,@_);
1022 if(defined ${*$ftp}{'net_ftp_pasv'});
1024 $ok = CMD_INFO == $ftp->response();
1027 unless exists ${*$ftp}{'net_ftp_intern_port'};
1030 my $data = $ftp->_dataconn();
1033 if $data && $cmd =~ /RETR|LIST|NLST/;
1039 close(delete ${*$ftp}{'net_ftp_listen'});
1045 ## Over-ride methods (Net::Cmd)
1048 sub debug_text { $_[2] =~ /^(pass|resp|acct)/i ? "$1 ....\n" : $_[2]; }
1054 delete ${*$ftp}{'net_ftp_port'};
1055 $ftp->SUPER::command(@_);
1061 my $code = $ftp->SUPER::response();
1063 delete ${*$ftp}{'net_ftp_pasv'}
1064 if ($code != CMD_MORE && $code != CMD_INFO);
1071 return ($1, $2 eq "-")
1072 if $_[1] =~ s/^(\d\d\d)(.?)//o;
1076 # Darn MS FTP server is a load of CRAP !!!!
1078 unless ${*$ftp}{'net_cmd_code'} + 0;
1080 (${*$ftp}{'net_cmd_code'},1);
1084 ## Allow 2 servers to talk directly
1088 my($sftp,$sfile,$dftp,$dfile,$unique) = @_;
1090 ($dfile = $sfile) =~ s#.*/##
1091 unless(defined $dfile);
1093 my $port = $sftp->pasv or
1096 $dftp->port($port) or
1100 unless($unique ? $dftp->stou($dfile) : $dftp->stor($dfile));
1102 unless($sftp->retr($sfile) && $sftp->response == CMD_INFO) {
1103 $sftp->retr($sfile);
1109 $dftp->pasv_wait($sftp);
1114 @_ == 2 or croak 'usage: $ftp->pasv_wait(NON_PASV_FTP)';
1116 my($ftp, $non_pasv) = @_;
1117 my($file,$rin,$rout);
1119 vec($rin='',fileno($ftp),1) = 1;
1120 select($rout=$rin, undef, undef, undef);
1123 $non_pasv->response();
1126 unless $ftp->ok() && $non_pasv->ok();
1129 if $ftp->message =~ /unique file name:\s*(\S*)\s*\)/;
1132 if $non_pasv->message =~ /unique file name:\s*(\S*)\s*\)/;
1137 sub cmd { shift->command(@_)->response() }
1139 ########################################
1144 sub _ABOR { shift->command("ABOR")->response() == CMD_OK }
1145 sub _CDUP { shift->command("CDUP")->response() == CMD_OK }
1146 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
1147 sub _PASV { shift->command("PASV")->response() == CMD_OK }
1148 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
1149 sub _DELE { shift->command("DELE",@_)->response() == CMD_OK }
1150 sub _CWD { shift->command("CWD", @_)->response() == CMD_OK }
1151 sub _PORT { shift->command("PORT",@_)->response() == CMD_OK }
1152 sub _RMD { shift->command("RMD", @_)->response() == CMD_OK }
1153 sub _MKD { shift->command("MKD", @_)->response() == CMD_OK }
1154 sub _PWD { shift->command("PWD", @_)->response() == CMD_OK }
1155 sub _TYPE { shift->command("TYPE",@_)->response() == CMD_OK }
1156 sub _RNTO { shift->command("RNTO",@_)->response() == CMD_OK }
1157 sub _RESP { shift->command("RESP",@_)->response() == CMD_OK }
1158 sub _MDTM { shift->command("MDTM",@_)->response() == CMD_OK }
1159 sub _SIZE { shift->command("SIZE",@_)->response() == CMD_OK }
1160 sub _HELP { shift->command("HELP",@_)->response() == CMD_OK }
1161 sub _STAT { shift->command("STAT",@_)->response() == CMD_OK }
1162 sub _APPE { shift->command("APPE",@_)->response() == CMD_INFO }
1163 sub _LIST { shift->command("LIST",@_)->response() == CMD_INFO }
1164 sub _NLST { shift->command("NLST",@_)->response() == CMD_INFO }
1165 sub _RETR { shift->command("RETR",@_)->response() == CMD_INFO }
1166 sub _STOR { shift->command("STOR",@_)->response() == CMD_INFO }
1167 sub _STOU { shift->command("STOU",@_)->response() == CMD_INFO }
1168 sub _RNFR { shift->command("RNFR",@_)->response() == CMD_MORE }
1169 sub _REST { shift->command("REST",@_)->response() == CMD_MORE }
1170 sub _USER { shift->command("user",@_)->response() } # A certain brain dead firewall :-)
1171 sub _PASS { shift->command("PASS",@_)->response() }
1172 sub _ACCT { shift->command("ACCT",@_)->response() }
1173 sub _AUTH { shift->command("AUTH",@_)->response() }
1175 sub _ALLO { shift->unsupported(@_) }
1176 sub _SMNT { shift->unsupported(@_) }
1177 sub _MODE { shift->unsupported(@_) }
1178 sub _SYST { shift->unsupported(@_) }
1179 sub _STRU { shift->unsupported(@_) }
1180 sub _REIN { shift->unsupported(@_) }
1188 Net::FTP - FTP Client class
1194 $ftp = Net::FTP->new("some.host.name", Debug => 0);
1195 $ftp->login("anonymous",'-anonymous@');
1197 $ftp->get("that.file");
1202 C<Net::FTP> is a class implementing a simple FTP client in Perl as
1203 described in RFC959. It provides wrappers for a subset of the RFC959
1208 FTP stands for File Transfer Protocol. It is a way of transferring
1209 files between networked machines. The protocol defines a client
1210 (whose commands are provided by this module) and a server (not
1211 implemented in this module). Communication is always initiated by the
1212 client, and the server responds with a message and a status code (and
1213 sometimes with data).
1215 The FTP protocol allows files to be sent to or fetched from the
1216 server. Each transfer involves a B<local file> (on the client) and a
1217 B<remote file> (on the server). In this module, the same file name
1218 will be used for both local and remote if only one is specified. This
1219 means that transferring remote file C</path/to/file> will try to put
1220 that file in C</path/to/file> locally, unless you specify a local file
1223 The protocol also defines several standard B<translations> which the
1224 file can undergo during transfer. These are ASCII, EBCDIC, binary,
1225 and byte. ASCII is the default type, and indicates that the sender of
1226 files will translate the ends of lines to a standard representation
1227 which the receiver will then translate back into their local
1228 representation. EBCDIC indicates the file being transferred is in
1229 EBCDIC format. Binary (also known as image) format sends the data as
1230 a contiguous bit stream. Byte format transfers the data as bytes, the
1231 values of which remain the same regardless of differences in byte size
1232 between the two machines (in theory - in practice you should only use
1233 this if you really know what you're doing).
1239 =item new (HOST [,OPTIONS])
1241 This is the constructor for a new Net::FTP object. C<HOST> is the
1242 name of the remote host to which an FTP connection is required.
1244 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
1245 Possible options are:
1247 B<Firewall> - The name of a machine which acts as an FTP firewall. This can be
1248 overridden by an environment variable C<FTP_FIREWALL>. If specified, and the
1249 given host cannot be directly connected to, then the
1250 connection is made to the firewall machine and the string C<@hostname> is
1251 appended to the login identifier. This kind of setup is also refered to
1254 B<FirewallType> - The type of firewall running on the machine indicated by
1255 B<Firewall>. This can be overridden by an environment variable
1256 C<FTP_FIREWALL_TYPE>. For a list of permissible types, see the description of
1257 ftp_firewall_type in L<Net::Config>.
1259 B<BlockSize> - This is the block size that Net::FTP will use when doing
1260 transfers. (defaults to 10240)
1262 B<Port> - The port number to connect to on the remote machine for the
1265 B<Timeout> - Set a timeout value (defaults to 120)
1267 B<Debug> - debug level (see the debug method in L<Net::Cmd>)
1269 B<Passive> - If set to a non-zero value then all data transfers will be done
1270 using passive mode. This is not usually required except for some I<dumb>
1271 servers, and some firewall configurations. This can also be set by the
1272 environment variable C<FTP_PASSIVE>.
1274 B<Hash> - If given a reference to a file handle (e.g., C<\*STDERR>),
1275 print hash marks (#) on that filehandle every 1024 bytes. This
1276 simply invokes the C<hash()> method for you, so that hash marks
1277 are displayed for all transfers. You can, of course, call C<hash()>
1278 explicitly whenever you'd like.
1280 If the constructor fails undef will be returned and an error message will
1287 Unless otherwise stated all methods return either a I<true> or I<false>
1288 value, with I<true> meaning that the operation was a success. When a method
1289 states that it returns a value, failure will be returned as I<undef> or an
1294 =item login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])
1296 Log into the remote FTP server with the given login information. If
1297 no arguments are given then the C<Net::FTP> uses the C<Net::Netrc>
1298 package to lookup the login information for the connected host.
1299 If no information is found then a login of I<anonymous> is used.
1300 If no password is given and the login is I<anonymous> then I<anonymous@>
1301 will be used for password.
1303 If the connection is via a firewall then the C<authorize> method will
1304 be called with no arguments.
1306 =item authorize ( [AUTH [, RESP]])
1308 This is a protocol used by some firewall ftp proxies. It is used
1309 to authorise the user to send data out. If both arguments are not specified
1310 then C<authorize> uses C<Net::Netrc> to do a lookup.
1314 Send a SITE command to the remote server and wait for a response.
1316 Returns most significant digit of the response code.
1318 =item type (TYPE [, ARGS])
1320 This method will send the TYPE command to the remote FTP server
1321 to change the type of data transfer. The return value is the previous
1324 =item ascii ([ARGS]) binary([ARGS]) ebcdic([ARGS]) byte([ARGS])
1326 Synonyms for C<type> with the first arguments set correctly
1328 B<NOTE> ebcdic and byte are not fully supported.
1330 =item rename ( OLDNAME, NEWNAME )
1332 Rename a file on the remote FTP server from C<OLDNAME> to C<NEWNAME>. This
1333 is done by sending the RNFR and RNTO commands.
1335 =item delete ( FILENAME )
1337 Send a request to the server to delete C<FILENAME>.
1339 =item cwd ( [ DIR ] )
1341 Attempt to change directory to the directory given in C<$dir>. If
1342 C<$dir> is C<"..">, the FTP C<CDUP> command is used to attempt to
1343 move up one directory. If no directory is given then an attempt is made
1344 to change the directory to the root directory.
1348 Change directory to the parent of the current directory.
1352 Returns the full pathname of the current directory.
1354 =item restart ( WHERE )
1356 Set the byte offset at which to begin the next data transfer. Net::FTP simply
1357 records this value and uses it when during the next data transfer. For this
1358 reason this method will not return an error, but setting it may cause
1359 a subsequent data transfer to fail.
1363 Remove the directory with the name C<DIR>.
1365 =item mkdir ( DIR [, RECURSE ])
1367 Create a new directory with the name C<DIR>. If C<RECURSE> is I<true> then
1368 C<mkdir> will attempt to create all the directories in the given path.
1370 Returns the full pathname to the new directory.
1372 =item ls ( [ DIR ] )
1374 Get a directory listing of C<DIR>, or the current directory.
1376 In an array context, returns a list of lines returned from the server. In
1377 a scalar context, returns a reference to a list.
1379 =item dir ( [ DIR ] )
1381 Get a directory listing of C<DIR>, or the current directory in long format.
1383 In an array context, returns a list of lines returned from the server. In
1384 a scalar context, returns a reference to a list.
1386 =item get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )
1388 Get C<REMOTE_FILE> from the server and store locally. C<LOCAL_FILE> may be
1389 a filename or a filehandle. If not specified, the file will be stored in
1390 the current directory with the same leafname as the remote file.
1392 If C<WHERE> is given then the first C<WHERE> bytes of the file will
1393 not be transfered, and the remaining bytes will be appended to
1394 the local file if it already exists.
1396 Returns C<LOCAL_FILE>, or the generated local file name if C<LOCAL_FILE>
1397 is not given. If an error was encountered undef is returned.
1399 =item put ( LOCAL_FILE [, REMOTE_FILE ] )
1401 Put a file on the remote server. C<LOCAL_FILE> may be a name or a filehandle.
1402 If C<LOCAL_FILE> is a filehandle then C<REMOTE_FILE> must be specified. If
1403 C<REMOTE_FILE> is not specified then the file will be stored in the current
1404 directory with the same leafname as C<LOCAL_FILE>.
1406 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1409 B<NOTE>: If for some reason the transfer does not complete and an error is
1410 returned then the contents that had been transfered will not be remove
1413 =item put_unique ( LOCAL_FILE [, REMOTE_FILE ] )
1415 Same as put but uses the C<STOU> command.
1417 Returns the name of the file on the server.
1419 =item append ( LOCAL_FILE [, REMOTE_FILE ] )
1421 Same as put but appends to the file on the remote server.
1423 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1426 =item unique_name ()
1428 Returns the name of the last file stored on the server using the
1433 Returns the I<modification time> of the given file
1437 Returns the size in bytes for the given file as stored on the remote server.
1439 B<NOTE>: The size reported is the size of the stored file on the remote server.
1440 If the file is subsequently transfered from the server in ASCII mode
1441 and the remote server and local machine have different ideas about
1442 "End Of Line" then the size of file on the local machine after transfer
1445 =item supported ( CMD )
1447 Returns TRUE if the remote server supports the given command.
1449 =item hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )
1451 Called without parameters, or with the first argument false, hash marks
1452 are suppressed. If the first argument is true but not a reference to a
1453 file handle glob, then \*STDERR is used. The second argument is the number
1454 of bytes per hash mark printed, and defaults to 1024. In all cases the
1455 return value is a reference to an array of two: the filehandle glob reference
1456 and the bytes per hash mark.
1460 The following methods can return different results depending on
1461 how they are called. If the user explicitly calls either
1462 of the C<pasv> or C<port> methods then these methods will
1463 return a I<true> or I<false> value. If the user does not
1464 call either of these methods then the result will be a
1465 reference to a C<Net::FTP::dataconn> based object.
1469 =item nlst ( [ DIR ] )
1471 Send an C<NLST> command to the server, with an optional parameter.
1473 =item list ( [ DIR ] )
1475 Same as C<nlst> but using the C<LIST> command
1479 Begin the retrieval of a file called C<FILE> from the remote server.
1483 Tell the server that you wish to store a file. C<FILE> is the
1484 name of the new file that should be created.
1488 Same as C<stor> but using the C<STOU> command. The name of the unique
1489 file which was created on the server will be available via the C<unique_name>
1490 method after the data connection has been closed.
1494 Tell the server that we want to append some data to the end of a file
1495 called C<FILE>. If this file does not exist then create it.
1499 If for some reason you want to have complete control over the data connection,
1500 this includes generating it and calling the C<response> method when required,
1501 then the user can use these methods to do so.
1503 However calling these methods only affects the use of the methods above that
1504 can return a data connection. They have no effect on methods C<get>, C<put>,
1505 C<put_unique> and those that do not require data connections.
1509 =item port ( [ PORT ] )
1511 Send a C<PORT> command to the server. If C<PORT> is specified then it is sent
1512 to the server. If not, then a listen socket is created and the correct information
1517 Tell the server to go into passive mode. Returns the text that represents the
1518 port on which the server is listening, this text is in a suitable form to
1519 sent to another ftp server using the C<port> method.
1523 The following methods can be used to transfer files between two remote
1524 servers, providing that these two servers can connect directly to each other.
1528 =item pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1530 This method will do a file transfer between two remote ftp servers. If
1531 C<DEST_FILE> is omitted then the leaf name of C<SRC_FILE> will be used.
1533 =item pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1535 Like C<pasv_xfer> but the file is stored on the remote server using
1538 =item pasv_wait ( NON_PASV_SERVER )
1540 This method can be used to wait for a transfer to complete between a passive
1541 server and a non-passive server. The method should be called on the passive
1542 server with the C<Net::FTP> object for the non-passive server passed as an
1547 Abort the current data transfer.
1551 Send the QUIT command to the remote FTP server and close the socket connection.
1555 =head2 Methods for the adventurous
1557 C<Net::FTP> inherits from C<Net::Cmd> so methods defined in C<Net::Cmd> may
1558 be used to send commands to the remote FTP server.
1562 =item quot (CMD [,ARGS])
1564 Send a command, that Net::FTP does not directly support, to the remote
1565 server and wait for a response.
1567 Returns most significant digit of the response code.
1569 B<WARNING> This call should only be used on commands that do not require
1570 data connections. Misuse of this method can hang the connection.
1574 =head1 THE dataconn CLASS
1576 Some of the methods defined in C<Net::FTP> return an object which will
1577 be derived from this class.The dataconn class itself is derived from
1578 the C<IO::Socket::INET> class, so any normal IO operations can be performed.
1579 However the following methods are defined in the dataconn class and IO should
1580 be performed using these.
1584 =item read ( BUFFER, SIZE [, TIMEOUT ] )
1586 Read C<SIZE> bytes of data from the server and place it into C<BUFFER>, also
1587 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1588 given, the timeout value from the command connection will be used.
1590 Returns the number of bytes read before any <CRLF> translation.
1592 =item write ( BUFFER, SIZE [, TIMEOUT ] )
1594 Write C<SIZE> bytes of data from C<BUFFER> to the server, also
1595 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1596 given, the timeout value from the command connection will be used.
1598 Returns the number of bytes written before any <CRLF> translation.
1602 Returns the number of bytes read so far.
1606 Abort the current data transfer.
1610 Close the data connection and get a response from the FTP server. Returns
1611 I<true> if the connection was closed successfully and the first digit of
1612 the response from the server was a '2'.
1616 =head1 UNIMPLEMENTED
1618 The following RFC959 commands have not been implemented:
1624 Allocates storage for the file to be transferred.
1628 Mount a different file system structure without changing login or
1629 accounting information.
1633 Ask the server for "helpful information" (that's what the RFC says) on
1634 the commands it accepts.
1638 Specifies transfer mode (stream, block or compressed) for file to be
1643 Request remote server system identification.
1647 Request remote server status.
1651 Specifies file structure for file to be transferred.
1655 Reinitialize the connection, flushing all I/O and account information.
1659 =head1 REPORTING BUGS
1661 When reporting bugs/problems please include as much information as possible.
1662 It may be difficult for me to reproduce the problem as almost every setup
1665 A small script which yields the problem will probably be of help. It would
1666 also be useful if this script was run with the extra options C<Debug => 1>
1667 passed to the constructor, and the output sent with the bug report. If you
1668 cannot include a small script then please include a Debug trace from a
1669 run of your program which does yield the problem.
1673 Graham Barr <gbarr@pobox.com>
1680 ftp(1), ftpd(8), RFC 959
1681 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html
1685 For an example of the use of Net::FTP see
1689 =item http://www.csh.rit.edu/~adam/Progs/autoftp-2.0.tar.gz
1691 C<autoftp> is a program that can retrieve, send, or list files via
1692 the FTP protocol in a non-interactive manner.
1698 Henry Gabryjelski <henryg@WPI.EDU> - for the suggestion of creating directories
1701 Nathan Torkington <gnat@frii.com> - for some input on the documentation.
1703 Roderick Schertler <roderick@gate.net> - for various inputs
1707 Copyright (c) 1995-1998 Graham Barr. All rights reserved.
1708 This program is free software; you can redistribute it and/or modify it
1709 under the same terms as Perl itself.
1713 I<$Id: //depot/libnet/Net/FTP.pm#68 $>