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 AutoLoader qw(AUTOLOAD);
24 $VERSION = "2.56"; # $Id:$
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);
33 # Name is too long for AutoLoad, it clashes with pasv_xfer
34 sub pasv_xfer_unique {
35 my($sftp,$sfile,$dftp,$dfile) = @_;
36 $sftp->pasv_xfer($sfile,$dftp,$dfile,1);
40 # Having problems with AutoLoader
52 if(exists($arg{Firewall}) || Net::Config->requires_firewall($peer))
54 $fire = $arg{Firewall}
56 || $NetConfig{ftp_firewall}
66 my $ftp = $pkg->SUPER::new(PeerAddr => $peer,
67 PeerPort => $arg{Port} || 'ftp(21)',
69 Timeout => defined $arg{Timeout}
74 ${*$ftp}{'net_ftp_host'} = $host; # Remote hostname
75 ${*$ftp}{'net_ftp_type'} = 'A'; # ASCII/binary/etc mode
76 ${*$ftp}{'net_ftp_blksize'} = abs($arg{'BlockSize'} || 10240);
78 ${*$ftp}{'net_ftp_firewall'} = $fire
81 ${*$ftp}{'net_ftp_passive'} = int
84 : exists $ENV{FTP_PASSIVE}
87 ? $NetConfig{ftp_ext_passive}
88 : $NetConfig{ftp_int_passive}; # Whew! :-)
90 $ftp->hash(exists $arg{Hash} ? $arg{Hash} : 0, 1024);
94 $ftp->debug(exists $arg{Debug} ? $arg{Debug} : undef);
96 unless ($ftp->response() == CMD_OK)
107 ## User interface methods
111 my $ftp = shift; # self
112 my $prev = ${*$ftp}{'net_ftp_hash'} || [\*STDERR, 0];
120 delete ${*$ftp}{'net_ftp_hash'};
127 ($h,$b) = (\*STDERR,$h);
130 select((select($h), $|=1)[0]);
131 $b = 512 if $b < 512;
132 ${*$ftp}{'net_ftp_hash'} = [$h, $b];
147 defined(fileno($ftp)) && $ftp->quit
150 sub ascii { shift->type('A',@_); }
151 sub binary { shift->type('I',@_); }
155 carp "TYPE E is unsupported, shall default to I";
161 carp "TYPE L is unsupported, shall default to I";
165 # Allow the user to send a command directly, BE CAREFUL !!
172 $ftp->command( uc $cmd, @_);
180 $ftp->command("SITE", @_);
189 # Server Y2K bug workaround
191 # sigh; some idiotic FTP servers use ("19%d",tm.tm_year) instead of
192 # ("%d",tm.tm_year+1900). This results in an extra digit in the
193 # string returned. To account for this we allow an optional extra
194 # digit in the year. Then if the first two digits are 19 we use the
195 # remainder, otherwise we subtract 1900 from the whole year.
197 $ftp->_MDTM($file) && $ftp->message =~ /((\d\d)(\d\d\d?))(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)/
198 ? timegm($8,$7,$6,$5,$4-1,$2 eq '19' ? $3 : ($1-1900))
206 if($ftp->supported("SIZE")) {
207 return $ftp->_SIZE($file)
208 ? ($ftp->message =~ /(\d+)/)[0]
211 elsif($ftp->supported("STAT")) {
214 unless $ftp->_STAT($file) && (@msg = $ftp->message) == 3;
216 foreach $line (@msg) {
217 return (split(/\s+/,$line))[4]
218 if $line =~ /^[-rw]{10}/
222 my @files = $ftp->dir($file);
224 return (split(/\s+/,$1))[4]
225 if $files[0] =~ /^([-rw]{10}.*)$/;
232 my($ftp,$user,$pass,$acct) = @_;
233 my($ok,$ruser,$fwtype);
235 unless (defined $user) {
238 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'});
240 ($user,$pass,$acct) = $rc->lpa()
244 $user ||= "anonymous";
247 $fwtype = $NetConfig{'ftp_firewall_type'} || 0;
249 if ($fwtype && defined ${*$ftp}{'net_ftp_firewall'}) {
250 if ($fwtype == 1 || $fwtype == 7) {
251 $user .= '@' . ${*$ftp}{'net_ftp_host'};
256 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
258 my($fwuser,$fwpass,$fwacct) = $rc ? $rc->lpa() : ();
261 $user = join('@',$user,$fwuser,${*$ftp}{'net_ftp_host'});
262 $pass = $pass . '@' . $fwpass;
266 $user .= '@' . ${*$ftp}{'net_ftp_host'};
268 elsif ($fwtype == 6) {
269 $fwuser .= '@' . ${*$ftp}{'net_ftp_host'};
272 $ok = $ftp->_USER($fwuser);
274 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
276 $ok = $ftp->_PASS($fwpass || "");
278 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
280 $ok = $ftp->_ACCT($fwacct)
284 $ok = $ftp->command("SITE",${*$ftp}{'net_ftp_host'})->response;
286 elsif ($fwtype == 4) {
287 $ok = $ftp->command("OPEN",${*$ftp}{'net_ftp_host'})->response;
290 return 0 unless $ok == CMD_OK || $ok == CMD_MORE;
295 $ok = $ftp->_USER($user);
297 # Some dumb firewalls don't prefix the connection messages
298 $ok = $ftp->response()
299 if ($ok == CMD_OK && $ftp->code == 220 && $user =~ /\@/);
301 if ($ok == CMD_MORE) {
302 unless(defined $pass) {
305 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_host'}, $ruser);
307 ($ruser,$pass,$acct) = $rc->lpa()
310 $pass = "-" . (eval { (getpwuid($>))[0] } || $ENV{NAME} ) . '@'
311 if (!defined $pass && (!defined($ruser) || $ruser =~ /^anonymous/o));
314 $ok = $ftp->_PASS($pass || "");
317 $ok = $ftp->_ACCT($acct)
318 if (defined($acct) && ($ok == CMD_MORE || $ok == CMD_OK));
320 if ($fwtype == 7 && $ok == CMD_OK && defined ${*$ftp}{'net_ftp_firewall'}) {
321 my($f,$auth,$resp) = _auth_id($ftp);
322 $ftp->authorize($auth,$resp) if defined($resp);
330 @_ == 2 or croak 'usage: $ftp->account( ACCT )';
333 $ftp->_ACCT($acct) == CMD_OK;
337 my($ftp,$auth,$resp) = @_;
339 unless(defined $resp)
343 $auth ||= eval { (getpwuid($>))[0] } || $ENV{NAME};
345 my $rc = Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'}, $auth)
346 || Net::Netrc->lookup(${*$ftp}{'net_ftp_firewall'});
348 ($auth,$resp) = $rc->lpa()
356 @_ >= 1 || @_ <= 3 or croak 'usage: $ftp->authorize( [AUTH [, RESP]])';
358 my($ftp,$auth,$resp) = &_auth_id;
360 my $ok = $ftp->_AUTH($auth || "");
362 $ok = $ftp->_RESP($resp || "")
363 if ($ok == CMD_MORE);
370 @_ == 3 or croak 'usage: $ftp->rename(FROM, TO)';
372 my($ftp,$from,$to) = @_;
382 my $oldval = ${*$ftp}{'net_ftp_type'};
385 unless (defined $type);
388 unless ($ftp->_TYPE($type,@_));
390 ${*$ftp}{'net_ftp_type'} = join(" ",$type,@_);
399 send($ftp,pack("CCC", $TELNET_IAC, $TELNET_IP, $TELNET_IAC),MSG_OOB);
401 $ftp->command(pack("C",$TELNET_DM) . "ABOR");
403 ${*$ftp}{'net_ftp_dataconn'}->close()
404 if defined ${*$ftp}{'net_ftp_dataconn'};
408 $ftp->status == CMD_OK;
413 my($ftp,$remote,$local,$where) = @_;
415 my($loc,$len,$buf,$resp,$localfd,$data);
418 $localfd = ref($local) || ref(\$local) eq "GLOB"
422 ($local = $remote) =~ s#^.*/##
423 unless(defined $local);
425 croak("Bad remote filename '$remote'\n")
426 if $remote =~ /[\r\n]/s;
428 ${*$ftp}{'net_ftp_rest'} = $where
431 delete ${*$ftp}{'net_ftp_port'};
432 delete ${*$ftp}{'net_ftp_pasv'};
434 $data = $ftp->retr($remote) or
445 unless(($where) ? open($loc,">>$local") : open($loc,">$local"))
447 carp "Cannot open Local file $local: $!\n";
453 if($ftp->type eq 'I' && !binmode($loc))
455 carp "Cannot binmode Local file $local: $!\n";
457 close($loc) unless $localfd;
462 my($count,$hashh,$hashb,$ref) = (0);
464 ($hashh,$hashb) = @$ref
465 if($ref = ${*$ftp}{'net_ftp_hash'});
467 my $blksize = ${*$ftp}{'net_ftp_blksize'};
471 last unless $len = $data->read($buf,$blksize);
474 print $hashh "#" x (int($count / $hashb));
477 my $written = syswrite($loc,$buf,$len);
478 unless(defined($written) && $written == $len)
480 carp "Cannot write to Local file $local: $!\n";
483 unless defined $localfd;
488 print $hashh "\n" if $hashh;
491 unless defined $localfd;
493 $data->close(); # implied $ftp->response
500 @_ == 1 || @_ == 2 or croak 'usage: $ftp->cwd( [ DIR ] )';
504 $dir = "/" unless defined($dir) && $dir =~ /\S/;
513 @_ == 1 or croak 'usage: $ftp->cdup()';
519 @_ == 1 || croak 'usage: $ftp->pwd()';
526 # rmdir( $ftp, $dir, [ $recurse ] )
528 # Removes $dir on remote host via FTP.
529 # $ftp is handle for remote host
531 # If $recurse is TRUE, the directory and deleted recursively.
532 # This means all of its contents and subdirectories.
534 # Initial version contributed by Dinkum Software
538 @_ == 2 || @_ == 3 or croak('usage: $ftp->rmdir( DIR [, RECURSE ] )');
541 my ($ftp, $dir, $recurse) = @_ ;
545 if $ftp->_RMD( $dir ) || !$recurse;
547 # Try to delete the contents
548 # Get a list of all the files in the directory
549 my $filelist = $ftp->ls($dir);
552 unless $filelist && @$filelist; # failed, it is probably not a directory
554 # Go thru and delete each file or the directory
556 foreach $file (map { m,/, ? $_ : "$dir/$_" } @$filelist)
558 next # successfully deleted the file
559 if $ftp->delete($file);
561 # Failed to delete it, assume its a directory
562 # Recurse and ignore errors, the final rmdir() will
563 # fail on any errors here
565 unless $ok = $ftp->rmdir($file, 1) ;
568 # Directory should be empty
569 # Try to remove the directory again
570 # Pass results directly to caller
571 # If any of the prior deletes failed, this
572 # rmdir() will fail because directory is not empty
573 return $ftp->_RMD($dir) ;
578 @_ == 2 || @_ == 3 or croak 'usage: $ftp->mkdir( DIR [, RECURSE ] )';
580 my($ftp,$dir,$recurse) = @_;
582 $ftp->_MKD($dir) || $recurse or
589 my @path = split(m#(?=/+)#, $dir);
595 $path .= shift @path;
599 $path = $ftp->_extract_path($path);
602 # If the creation of the last element was not sucessful, see if we
603 # can cd to it, if so then return path
607 my($status,$message) = ($ftp->status,$ftp->message);
610 if($pwd && $ftp->cwd($dir))
619 $ftp->set_status($status,$message);
628 @_ == 2 || croak 'usage: $ftp->delete( FILENAME )';
633 sub put { shift->_store_cmd("stor",@_) }
634 sub put_unique { shift->_store_cmd("stou",@_) }
635 sub append { shift->_store_cmd("appe",@_) }
637 sub nlst { shift->_data_cmd("NLST",@_) }
638 sub list { shift->_data_cmd("LIST",@_) }
639 sub retr { shift->_data_cmd("RETR",@_) }
640 sub stor { shift->_data_cmd("STOR",@_) }
641 sub stou { shift->_data_cmd("STOU",@_) }
642 sub appe { shift->_data_cmd("APPE",@_) }
646 my($ftp,$cmd,$local,$remote) = @_;
647 my($loc,$sock,$len,$buf,$localfd);
650 $localfd = ref($local) || ref(\$local) eq "GLOB"
654 unless(defined $remote)
656 croak 'Must specify remote filename with stream input'
659 require File::Basename;
660 $remote = File::Basename::basename($local);
663 croak("Bad remote filename '$remote'\n")
664 if $remote =~ /[\r\n]/s;
674 unless(open($loc,"<$local"))
676 carp "Cannot open Local file $local: $!\n";
681 if($ftp->type eq 'I' && !binmode($loc))
683 carp "Cannot binmode Local file $local: $!\n";
687 delete ${*$ftp}{'net_ftp_port'};
688 delete ${*$ftp}{'net_ftp_pasv'};
690 $sock = $ftp->_data_cmd($cmd, $remote) or
693 my $blksize = ${*$ftp}{'net_ftp_blksize'};
695 my($count,$hashh,$hashb,$ref) = (0);
697 ($hashh,$hashb) = @$ref
698 if($ref = ${*$ftp}{'net_ftp_hash'});
702 last unless $len = sysread($loc,$buf="",$blksize);
706 print $hashh "#" x (int($count / $hashb));
711 unless(defined($wlen = $sock->write($buf,$len)) && $wlen == $len)
715 unless defined $localfd;
716 print $hashh "\n" if $hashh;
721 print $hashh "\n" if $hashh;
724 unless defined $localfd;
729 ($remote) = $ftp->message =~ /unique file name:\s*(\S*)\s*\)/
730 if ('STOU' eq uc $cmd);
737 @_ == 1 || @_ == 2 or croak 'usage: $ftp->port([PORT])';
742 delete ${*$ftp}{'net_ftp_intern_port'};
744 unless(defined $port)
746 # create a Listen socket at same address as the command socket
748 ${*$ftp}{'net_ftp_listen'} ||= IO::Socket::INET->new(Listen => 5,
752 my $listen = ${*$ftp}{'net_ftp_listen'};
754 my($myport, @myaddr) = ($listen->sockport, split(/\./,$ftp->sockhost));
756 $port = join(',', @myaddr, $myport >> 8, $myport & 0xff);
758 ${*$ftp}{'net_ftp_intern_port'} = 1;
761 $ok = $ftp->_PORT($port);
763 ${*$ftp}{'net_ftp_port'} = $port;
768 sub ls { shift->_list_cmd("NLST",@_); }
769 sub dir { shift->_list_cmd("LIST",@_); }
773 @_ == 1 or croak 'usage: $ftp->pasv()';
777 delete ${*$ftp}{'net_ftp_intern_port'};
779 $ftp->_PASV && $ftp->message =~ /(\d+(,\d+)+)/
780 ? ${*$ftp}{'net_ftp_pasv'} = $1
787 ${*$ftp}{'net_ftp_unique'} || undef;
791 @_ == 2 or croak 'usage: $ftp->supported( CMD )';
794 my $hash = ${*$ftp}{'net_ftp_supported'} ||= {};
797 if exists $hash->{$cmd};
799 return $hash->{$cmd} = 0
800 unless $ftp->_HELP($cmd);
802 my $text = $ftp->message;
803 if($text =~ /following\s+commands/i) {
806 while($text =~ /(\w+)([* ])/g) {
807 $hash->{"\U$1"} = $2 eq " " ? 1 : 0;
811 $hash->{$cmd} = $text !~ /unimplemented/i;
818 ## Deprecated methods
823 carp "Use of Net::FTP::lsl deprecated, use 'dir'"
830 carp "Use of Net::FTP::authorise deprecated, use 'authorize'"
842 my($ftp, $path) = @_;
844 # This tries to work both with and without the quote doubling
845 # convention (RFC 959 requires it, but the first 3 servers I checked
846 # didn't implement it). It will fail on a server which uses a quote in
847 # the message which isn't a part of or surrounding the path.
849 $ftp->message =~ /(?:^|\s)\"(.*)\"(?:$|\s)/ &&
850 ($path = $1) =~ s/\"\"/\"/g;
856 ## Communication methods
863 my $pkg = "Net::FTP::" . $ftp->type;
865 eval "require " . $pkg;
869 delete ${*$ftp}{'net_ftp_dataconn'};
871 if(defined ${*$ftp}{'net_ftp_pasv'})
873 my @port = split(/,/,${*$ftp}{'net_ftp_pasv'});
875 $data = $pkg->new(PeerAddr => join(".",@port[0..3]),
876 PeerPort => $port[4] * 256 + $port[5],
880 elsif(defined ${*$ftp}{'net_ftp_listen'})
882 $data = ${*$ftp}{'net_ftp_listen'}->accept($pkg);
883 close(delete ${*$ftp}{'net_ftp_listen'});
889 $data->timeout($ftp->timeout);
890 ${*$ftp}{'net_ftp_dataconn'} = $data;
891 ${*$data}{'net_ftp_cmd'} = $ftp;
892 ${*$data}{'net_ftp_blksize'} = ${*$ftp}{'net_ftp_blksize'};
903 delete ${*$ftp}{'net_ftp_port'};
904 delete ${*$ftp}{'net_ftp_pasv'};
906 my $data = $ftp->_data_cmd($cmd,@_);
909 unless(defined $data);
912 bless $data, "Net::FTP::A"; # Force ASCII mode
916 my $blksize = ${*$ftp}{'net_ftp_blksize'};
918 while($data->read($databuf,$blksize)) {
922 my $list = [ split(/\n/,$buf) ];
935 my $where = delete ${*$ftp}{'net_ftp_rest'} || 0;
939 croak("Bad argument '$arg'\n")
940 if $arg =~ /[\r\n]/s;
943 if(${*$ftp}{'net_ftp_passive'} &&
944 !defined ${*$ftp}{'net_ftp_pasv'} &&
945 !defined ${*$ftp}{'net_ftp_port'})
949 $ok = defined $ftp->pasv;
950 $ok = $ftp->_REST($where)
955 $ftp->command($cmd,@_);
956 $data = $ftp->_dataconn();
957 $ok = CMD_INFO == $ftp->response();
961 if $data && $cmd =~ /RETR|LIST|NLST/;
971 unless (defined ${*$ftp}{'net_ftp_port'} ||
972 defined ${*$ftp}{'net_ftp_pasv'});
974 $ok = $ftp->_REST($where)
980 $ftp->command($cmd,@_);
983 if(defined ${*$ftp}{'net_ftp_pasv'});
985 $ok = CMD_INFO == $ftp->response();
988 unless exists ${*$ftp}{'net_ftp_intern_port'};
991 my $data = $ftp->_dataconn();
994 if $data && $cmd =~ /RETR|LIST|NLST/;
1000 close(delete ${*$ftp}{'net_ftp_listen'});
1006 ## Over-ride methods (Net::Cmd)
1009 sub debug_text { $_[2] =~ /^(pass|resp|acct)/i ? "$1 ....\n" : $_[2]; }
1015 delete ${*$ftp}{'net_ftp_port'};
1016 $ftp->SUPER::command(@_);
1022 my $code = $ftp->SUPER::response();
1024 delete ${*$ftp}{'net_ftp_pasv'}
1025 if ($code != CMD_MORE && $code != CMD_INFO);
1032 return ($1, $2 eq "-")
1033 if $_[1] =~ s/^(\d\d\d)(.?)//o;
1037 # Darn MS FTP server is a load of CRAP !!!!
1039 unless ${*$ftp}{'net_cmd_code'} + 0;
1041 (${*$ftp}{'net_cmd_code'},1);
1045 ## Allow 2 servers to talk directly
1049 my($sftp,$sfile,$dftp,$dfile,$unique) = @_;
1051 ($dfile = $sfile) =~ s#.*/##
1052 unless(defined $dfile);
1054 my $port = $sftp->pasv or
1057 $dftp->port($port) or
1061 unless($unique ? $dftp->stou($dfile) : $dftp->stor($dfile));
1063 unless($sftp->retr($sfile) && $sftp->response == CMD_INFO) {
1064 $sftp->retr($sfile);
1070 $dftp->pasv_wait($sftp);
1075 @_ == 2 or croak 'usage: $ftp->pasv_wait(NON_PASV_FTP)';
1077 my($ftp, $non_pasv) = @_;
1078 my($file,$rin,$rout);
1080 vec($rin='',fileno($ftp),1) = 1;
1081 select($rout=$rin, undef, undef, undef);
1084 $non_pasv->response();
1087 unless $ftp->ok() && $non_pasv->ok();
1090 if $ftp->message =~ /unique file name:\s*(\S*)\s*\)/;
1093 if $non_pasv->message =~ /unique file name:\s*(\S*)\s*\)/;
1098 sub cmd { shift->command(@_)->response() }
1100 ########################################
1105 sub _ABOR { shift->command("ABOR")->response() == CMD_OK }
1106 sub _CDUP { shift->command("CDUP")->response() == CMD_OK }
1107 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
1108 sub _PASV { shift->command("PASV")->response() == CMD_OK }
1109 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
1110 sub _DELE { shift->command("DELE",@_)->response() == CMD_OK }
1111 sub _CWD { shift->command("CWD", @_)->response() == CMD_OK }
1112 sub _PORT { shift->command("PORT",@_)->response() == CMD_OK }
1113 sub _RMD { shift->command("RMD", @_)->response() == CMD_OK }
1114 sub _MKD { shift->command("MKD", @_)->response() == CMD_OK }
1115 sub _PWD { shift->command("PWD", @_)->response() == CMD_OK }
1116 sub _TYPE { shift->command("TYPE",@_)->response() == CMD_OK }
1117 sub _RNTO { shift->command("RNTO",@_)->response() == CMD_OK }
1118 sub _RESP { shift->command("RESP",@_)->response() == CMD_OK }
1119 sub _MDTM { shift->command("MDTM",@_)->response() == CMD_OK }
1120 sub _SIZE { shift->command("SIZE",@_)->response() == CMD_OK }
1121 sub _HELP { shift->command("HELP",@_)->response() == CMD_OK }
1122 sub _STAT { shift->command("STAT",@_)->response() == CMD_OK }
1123 sub _APPE { shift->command("APPE",@_)->response() == CMD_INFO }
1124 sub _LIST { shift->command("LIST",@_)->response() == CMD_INFO }
1125 sub _NLST { shift->command("NLST",@_)->response() == CMD_INFO }
1126 sub _RETR { shift->command("RETR",@_)->response() == CMD_INFO }
1127 sub _STOR { shift->command("STOR",@_)->response() == CMD_INFO }
1128 sub _STOU { shift->command("STOU",@_)->response() == CMD_INFO }
1129 sub _RNFR { shift->command("RNFR",@_)->response() == CMD_MORE }
1130 sub _REST { shift->command("REST",@_)->response() == CMD_MORE }
1131 sub _USER { shift->command("user",@_)->response() } # A certain brain dead firewall :-)
1132 sub _PASS { shift->command("PASS",@_)->response() }
1133 sub _ACCT { shift->command("ACCT",@_)->response() }
1134 sub _AUTH { shift->command("AUTH",@_)->response() }
1136 sub _ALLO { shift->unsupported(@_) }
1137 sub _SMNT { shift->unsupported(@_) }
1138 sub _MODE { shift->unsupported(@_) }
1139 sub _SYST { shift->unsupported(@_) }
1140 sub _STRU { shift->unsupported(@_) }
1141 sub _REIN { shift->unsupported(@_) }
1149 Net::FTP - FTP Client class
1155 $ftp = Net::FTP->new("some.host.name", Debug => 0);
1156 $ftp->login("anonymous",'me@here.there');
1158 $ftp->get("that.file");
1163 C<Net::FTP> is a class implementing a simple FTP client in Perl as
1164 described in RFC959. It provides wrappers for a subset of the RFC959
1169 FTP stands for File Transfer Protocol. It is a way of transferring
1170 files between networked machines. The protocol defines a client
1171 (whose commands are provided by this module) and a server (not
1172 implemented in this module). Communication is always initiated by the
1173 client, and the server responds with a message and a status code (and
1174 sometimes with data).
1176 The FTP protocol allows files to be sent to or fetched from the
1177 server. Each transfer involves a B<local file> (on the client) and a
1178 B<remote file> (on the server). In this module, the same file name
1179 will be used for both local and remote if only one is specified. This
1180 means that transferring remote file C</path/to/file> will try to put
1181 that file in C</path/to/file> locally, unless you specify a local file
1184 The protocol also defines several standard B<translations> which the
1185 file can undergo during transfer. These are ASCII, EBCDIC, binary,
1186 and byte. ASCII is the default type, and indicates that the sender of
1187 files will translate the ends of lines to a standard representation
1188 which the receiver will then translate back into their local
1189 representation. EBCDIC indicates the file being transferred is in
1190 EBCDIC format. Binary (also known as image) format sends the data as
1191 a contiguous bit stream. Byte format transfers the data as bytes, the
1192 values of which remain the same regardless of differences in byte size
1193 between the two machines (in theory - in practice you should only use
1194 this if you really know what you're doing).
1200 =item new (HOST [,OPTIONS])
1202 This is the constructor for a new Net::FTP object. C<HOST> is the
1203 name of the remote host to which a FTP connection is required.
1205 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
1206 Possible options are:
1208 B<Firewall> - The name of a machine which acts as a FTP firewall. This can be
1209 overridden by an environment variable C<FTP_FIREWALL>. If specified, and the
1210 given host cannot be directly connected to, then the
1211 connection is made to the firewall machine and the string C<@hostname> is
1212 appended to the login identifier. This kind of setup is also refered to
1215 B<BlockSize> - This is the block size that Net::FTP will use when doing
1216 transfers. (defaults to 10240)
1218 B<Port> - The port number to connect to on the remote machine for the
1221 B<Timeout> - Set a timeout value (defaults to 120)
1223 B<Debug> - debug level (see the debug method in L<Net::Cmd>)
1225 B<Passive> - If set to a non-zero value then all data transfers will be done
1226 using passive mode. This is not usually required except for some I<dumb>
1227 servers, and some firewall configurations. This can also be set by the
1228 environment variable C<FTP_PASSIVE>.
1230 B<Hash> - If given a reference to a file handle (e.g., C<\*STDERR>),
1231 print hash marks (#) on that filehandle every 1024 bytes. This
1232 simply invokes the C<hash()> method for you, so that hash marks
1233 are displayed for all transfers. You can, of course, call C<hash()>
1234 explicitly whenever you'd like.
1236 If the constructor fails undef will be returned and an error message will
1243 Unless otherwise stated all methods return either a I<true> or I<false>
1244 value, with I<true> meaning that the operation was a success. When a method
1245 states that it returns a value, failure will be returned as I<undef> or an
1250 =item login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])
1252 Log into the remote FTP server with the given login information. If
1253 no arguments are given then the C<Net::FTP> uses the C<Net::Netrc>
1254 package to lookup the login information for the connected host.
1255 If no information is found then a login of I<anonymous> is used.
1256 If no password is given and the login is I<anonymous> then the users
1257 Email address will be used for a password.
1259 If the connection is via a firewall then the C<authorize> method will
1260 be called with no arguments.
1262 =item authorize ( [AUTH [, RESP]])
1264 This is a protocol used by some firewall ftp proxies. It is used
1265 to authorise the user to send data out. If both arguments are not specified
1266 then C<authorize> uses C<Net::Netrc> to do a lookup.
1270 Send a SITE command to the remote server and wait for a response.
1272 Returns most significant digit of the response code.
1274 =item type (TYPE [, ARGS])
1276 This method will send the TYPE command to the remote FTP server
1277 to change the type of data transfer. The return value is the previous
1280 =item ascii ([ARGS]) binary([ARGS]) ebcdic([ARGS]) byte([ARGS])
1282 Synonyms for C<type> with the first arguments set correctly
1284 B<NOTE> ebcdic and byte are not fully supported.
1286 =item rename ( OLDNAME, NEWNAME )
1288 Rename a file on the remote FTP server from C<OLDNAME> to C<NEWNAME>. This
1289 is done by sending the RNFR and RNTO commands.
1291 =item delete ( FILENAME )
1293 Send a request to the server to delete C<FILENAME>.
1295 =item cwd ( [ DIR ] )
1297 Attempt to change directory to the directory given in C<$dir>. If
1298 C<$dir> is C<"..">, the FTP C<CDUP> command is used to attempt to
1299 move up one directory. If no directory is given then an attempt is made
1300 to change the directory to the root directory.
1304 Change directory to the parent of the current directory.
1308 Returns the full pathname of the current directory.
1312 Remove the directory with the name C<DIR>.
1314 =item mkdir ( DIR [, RECURSE ])
1316 Create a new directory with the name C<DIR>. If C<RECURSE> is I<true> then
1317 C<mkdir> will attempt to create all the directories in the given path.
1319 Returns the full pathname to the new directory.
1321 =item ls ( [ DIR ] )
1323 Get a directory listing of C<DIR>, or the current directory.
1325 In an array context, returns a list of lines returned from the server. In
1326 a scalar context, returns a reference to a list.
1328 =item dir ( [ DIR ] )
1330 Get a directory listing of C<DIR>, or the current directory in long format.
1332 In an array context, returns a list of lines returned from the server. In
1333 a scalar context, returns a reference to a list.
1335 =item get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )
1337 Get C<REMOTE_FILE> from the server and store locally. C<LOCAL_FILE> may be
1338 a filename or a filehandle. If not specified the the file will be stored in
1339 the current directory with the same leafname as the remote file.
1341 If C<WHERE> is given then the first C<WHERE> bytes of the file will
1342 not be transfered, and the remaining bytes will be appended to
1343 the local file if it already exists.
1345 Returns C<LOCAL_FILE>, or the generated local file name if C<LOCAL_FILE>
1348 =item put ( LOCAL_FILE [, REMOTE_FILE ] )
1350 Put a file on the remote server. C<LOCAL_FILE> may be a name or a filehandle.
1351 If C<LOCAL_FILE> is a filehandle then C<REMOTE_FILE> must be specified. If
1352 C<REMOTE_FILE> is not specified then the file will be stored in the current
1353 directory with the same leafname as C<LOCAL_FILE>.
1355 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1358 B<NOTE>: If for some reason the transfer does not complete and an error is
1359 returned then the contents that had been transfered will not be remove
1362 =item put_unique ( LOCAL_FILE [, REMOTE_FILE ] )
1364 Same as put but uses the C<STOU> command.
1366 Returns the name of the file on the server.
1368 =item append ( LOCAL_FILE [, REMOTE_FILE ] )
1370 Same as put but appends to the file on the remote server.
1372 Returns C<REMOTE_FILE>, or the generated remote filename if C<REMOTE_FILE>
1375 =item unique_name ()
1377 Returns the name of the last file stored on the server using the
1382 Returns the I<modification time> of the given file
1386 Returns the size in bytes for the given file as stored on the remote server.
1388 B<NOTE>: The size reported is the size of the stored file on the remote server.
1389 If the file is subsequently transfered from the server in ASCII mode
1390 and the remote server and local machine have different ideas about
1391 "End Of Line" then the size of file on the local machine after transfer
1394 =item supported ( CMD )
1396 Returns TRUE if the remote server supports the given command.
1398 =item hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )
1400 Called without parameters, or with the first argument false, hash marks
1401 are suppressed. If the first argument is true but not a reference to a
1402 file handle glob, then \*STDERR is used. The second argument is the number
1403 of bytes per hash mark printed, and defaults to 1024. In all cases the
1404 return value is a reference to an array of two: the filehandle glob reference
1405 and the bytes per hash mark.
1409 The following methods can return different results depending on
1410 how they are called. If the user explicitly calls either
1411 of the C<pasv> or C<port> methods then these methods will
1412 return a I<true> or I<false> value. If the user does not
1413 call either of these methods then the result will be a
1414 reference to a C<Net::FTP::dataconn> based object.
1418 =item nlst ( [ DIR ] )
1420 Send a C<NLST> command to the server, with an optional parameter.
1422 =item list ( [ DIR ] )
1424 Same as C<nlst> but using the C<LIST> command
1428 Begin the retrieval of a file called C<FILE> from the remote server.
1432 Tell the server that you wish to store a file. C<FILE> is the
1433 name of the new file that should be created.
1437 Same as C<stor> but using the C<STOU> command. The name of the unique
1438 file which was created on the server will be available via the C<unique_name>
1439 method after the data connection has been closed.
1443 Tell the server that we want to append some data to the end of a file
1444 called C<FILE>. If this file does not exist then create it.
1448 If for some reason you want to have complete control over the data connection,
1449 this includes generating it and calling the C<response> method when required,
1450 then the user can use these methods to do so.
1452 However calling these methods only affects the use of the methods above that
1453 can return a data connection. They have no effect on methods C<get>, C<put>,
1454 C<put_unique> and those that do not require data connections.
1458 =item port ( [ PORT ] )
1460 Send a C<PORT> command to the server. If C<PORT> is specified then it is sent
1461 to the server. If not the a listen socket is created and the correct information
1466 Tell the server to go into passive mode. Returns the text that represents the
1467 port on which the server is listening, this text is in a suitable form to
1468 sent to another ftp server using the C<port> method.
1472 The following methods can be used to transfer files between two remote
1473 servers, providing that these two servers can connect directly to each other.
1477 =item pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1479 This method will do a file transfer between two remote ftp servers. If
1480 C<DEST_FILE> is omitted then the leaf name of C<SRC_FILE> will be used.
1482 =item pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] )
1484 Like C<pasv_xfer> but the file is stored on the remote server using
1487 =item pasv_wait ( NON_PASV_SERVER )
1489 This method can be used to wait for a transfer to complete between a passive
1490 server and a non-passive server. The method should be called on the passive
1491 server with the C<Net::FTP> object for the non-passive server passed as an
1496 Abort the current data transfer.
1500 Send the QUIT command to the remote FTP server and close the socket connection.
1504 =head2 Methods for the adventurous
1506 C<Net::FTP> inherits from C<Net::Cmd> so methods defined in C<Net::Cmd> may
1507 be used to send commands to the remote FTP server.
1511 =item quot (CMD [,ARGS])
1513 Send a command, that Net::FTP does not directly support, to the remote
1514 server and wait for a response.
1516 Returns most significant digit of the response code.
1518 B<WARNING> This call should only be used on commands that do not require
1519 data connections. Misuse of this method can hang the connection.
1523 =head1 THE dataconn CLASS
1525 Some of the methods defined in C<Net::FTP> return an object which will
1526 be derived from this class.The dataconn class itself is derived from
1527 the C<IO::Socket::INET> class, so any normal IO operations can be performed.
1528 However the following methods are defined in the dataconn class and IO should
1529 be performed using these.
1533 =item read ( BUFFER, SIZE [, TIMEOUT ] )
1535 Read C<SIZE> bytes of data from the server and place it into C<BUFFER>, also
1536 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1537 given the the timeout value from the command connection will be used.
1539 Returns the number of bytes read before any <CRLF> translation.
1541 =item write ( BUFFER, SIZE [, TIMEOUT ] )
1543 Write C<SIZE> bytes of data from C<BUFFER> to the server, also
1544 performing any <CRLF> translation necessary. C<TIMEOUT> is optional, if not
1545 given the the timeout value from the command connection will be used.
1547 Returns the number of bytes written before any <CRLF> translation.
1551 Abort the current data transfer.
1555 Close the data connection and get a response from the FTP server. Returns
1556 I<true> if the connection was closed successfully and the first digit of
1557 the response from the server was a '2'.
1561 =head1 UNIMPLEMENTED
1563 The following RFC959 commands have not been implemented:
1569 Allocates storage for the file to be transferred.
1573 Mount a different file system structure without changing login or
1574 accounting information.
1578 Ask the server for "helpful information" (that's what the RFC says) on
1579 the commands it accepts.
1583 Specifies transfer mode (stream, block or compressed) for file to be
1588 Request remote server system identification.
1592 Request remote server status.
1596 Specifies file structure for file to be transferred.
1600 Reinitialize the connection, flushing all I/O and account information.
1604 =head1 REPORTING BUGS
1606 When reporting bugs/problems please include as much information as possible.
1607 It may be difficult for me to reproduce the problem as almost every setup
1610 A small script which yields the problem will probably be of help. It would
1611 also be useful if this script was run with the extra options C<Debug => 1>
1612 passed to the constructor, and the output sent with the bug report. If you
1613 cannot include a small script then please include a Debug trace from a
1614 run of your program which does yield the problem.
1618 Graham Barr <gbarr@pobox.com>
1625 ftp(1), ftpd(8), RFC 959
1626 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html
1630 Henry Gabryjelski <henryg@WPI.EDU> - for the suggestion of creating directories
1633 Nathan Torkington <gnat@frii.com> - for some input on the documentation.
1635 Roderick Schertler <roderick@gate.net> - for various inputs
1639 Copyright (c) 1995-1998 Graham Barr. All rights reserved.
1640 This program is free software; you can redistribute it and/or modify it
1641 under the same terms as Perl itself.