view release on metacpan or  search on metacpan

lib/Net/FTP.pm  view on Meta::CPAN

# Net::FTP.pm
#
# Copyright (C) 1995-2004 Graham Barr.  All rights reserved.
# Copyright (C) 2013-2017, 2020, 2022 Steve Hay.  All rights reserved.
# This module is free software; you can redistribute it and/or modify it under
# the same terms as Perl itself, i.e. under the terms of either the GNU General
# Public License or the Artistic License, as specified in the F<LICENCE> file.
#
# Documentation (at end) improved 1996 by Nathan Torkington <gnat@frii.com>.

package Net::FTP;

use 5.008001;

use strict;
use warnings;

use Carp;
use Fcntl qw(O_WRONLY O_RDONLY O_APPEND O_CREAT O_TRUNC);
use IO::Socket;
use Net::Cmd;
use Net::Config;
use Socket;
use Time::Local;

our $VERSION = '3.15';

our $IOCLASS;
my $family_key;
BEGIN {
  # Code for detecting if we can use SSL
  my $ssl_class = eval {
    require IO::Socket::SSL;
    # first version with default CA on most platforms
    no warnings 'numeric';
    IO::Socket::SSL->VERSION(2.007);
  } && 'IO::Socket::SSL';

  my $nossl_warn = !$ssl_class &&
    'To use SSL please install IO::Socket::SSL with version>=2.007';

  # Code for detecting if we can use IPv6
  my $inet6_class = eval {
    require IO::Socket::IP;
    no warnings 'numeric';
    IO::Socket::IP->VERSION(0.25);
  } && 'IO::Socket::IP' || eval {
    require IO::Socket::INET6;
    no warnings 'numeric';
    IO::Socket::INET6->VERSION(2.62);
  } && 'IO::Socket::INET6';

  sub can_ssl   { $ssl_class };
  sub can_inet6 { $inet6_class };

  $IOCLASS = $ssl_class || $inet6_class || 'IO::Socket::INET';
  $family_key =
    ( $ssl_class ? $ssl_class->can_ipv6 : $inet6_class || '' )
      eq 'IO::Socket::IP'
      ? 'Family' : 'Domain';
}

our @ISA = ('Exporter','Net::Cmd',$IOCLASS);

use constant TELNET_IAC => 255;
use constant TELNET_IP  => 244;
use constant TELNET_DM  => 242;

use constant EBCDIC => ord 'A' == 193;

sub new {
  my $pkg = shift;
  my ($peer, %arg);
  if (@_ % 2) {
    $peer = shift;
    %arg  = @_;
  }
  else {
    %arg  = @_;
    $peer = delete $arg{Host};
  }

  my $host      = $peer;
  my $fire      = undef;
  my $fire_type = undef;

  if (exists($arg{Firewall}) || Net::Config->requires_firewall($peer)) {
         $fire = $arg{Firewall}
      || $ENV{FTP_FIREWALL}
      || $NetConfig{ftp_firewall}
      || undef;

    if (defined $fire) {
      $peer = $fire;
      delete $arg{Port};
           $fire_type = $arg{FirewallType}
        || $ENV{FTP_FIREWALL_TYPE}
        || $NetConfig{firewall_type}
        || undef;
    }
  }

  my %tlsargs;
  if (can_ssl()) {
    # for name verification strip port from domain:port, ipv4:port, [ipv6]:port
    (my $hostname = $host) =~s{(?<!:):\d+$}{};
    %tlsargs = (
      SSL_verifycn_scheme => 'ftp',
      SSL_verifycn_name => $hostname,
      # use SNI if supported by IO::Socket::SSL
      $pkg->can_client_sni ? (SSL_hostname => $hostname):(),
      # reuse SSL session of control connection in data connections
      SSL_session_cache_size => 10,
      SSL_session_key => $hostname,
    );
    # user defined SSL arg
    $tlsargs{$_} = $arg{$_} for(grep { m{^SSL_} } keys %arg);
    $tlsargs{SSL_reuse_ctx} = IO::Socket::SSL::SSL_Context->new(%tlsargs)

lib/Net/FTP.pm  view on Meta::CPAN

specified then it is sent to the server. If not, then a listen socket is created
and the correct information sent to the server.

=item C<pasv()>

=item C<epsv()>

Tell the server to go into passive mode (C<pasv> for IPv4, C<epsv> for IPv6).
Returns the text that represents the port on which the server is listening, this
text is in a suitable form to send to another ftp server using the C<port> or
C<eprt> method.

=back

The following methods can be used to transfer files between two remote
servers, providing that these two servers can connect directly to each other.

=over 4

=item C<pasv_xfer($src_file, $dest_server[, $dest_file ])>

This method will do a file transfer between two remote ftp servers. If
C<$dest_file> is omitted then the leaf name of C<$src_file> will be used.

=item C<pasv_xfer_unique($src_file, $dest_server[, $dest_file ])>

Like C<pasv_xfer> but the file is stored on the remote server using
the STOU command.

=item C<pasv_wait($non_pasv_server)>

This method can be used to wait for a transfer to complete between a passive
server and a non-passive server. The method should be called on the passive
server with the C<Net::FTP> object for the non-passive server passed as an
argument.

=item C<abort()>

Abort the current data transfer.

=item C<quit()>

Send the QUIT command to the remote FTP server and close the socket connection.

=back

=head2 Methods for the Adventurous

=over 4

=item C<quot($cmd[, $args])>

Send a command, that Net::FTP does not directly support, to the remote
server and wait for a response.

Returns most significant digit of the response code.

B<WARNING> This call should only be used on commands that do not require
data connections. Misuse of this method can hang the connection.

=item C<can_inet6()>

Returns whether we can use IPv6.

=item C<can_ssl()>

Returns whether we can use SSL.

=back

=head2 The dataconn Class

Some of the methods defined in C<Net::FTP> return an object which will
be derived from the C<Net::FTP::dataconn> class. See L<Net::FTP::dataconn> for
more details.

=head2 Unimplemented

The following RFC959 commands have not been implemented:

=over 4

=item C<SMNT>

Mount a different file system structure without changing login or
accounting information.

=item C<HELP>

Ask the server for "helpful information" (that's what the RFC says) on
the commands it accepts.

=item C<MODE>

Specifies transfer mode (stream, block or compressed) for file to be
transferred.

=item C<SYST>

Request remote server system identification.

=item C<STAT>

Request remote server status.

=item C<STRU>

Specifies file structure for file to be transferred.

=item C<REIN>

Reinitialize the connection, flushing all I/O and account information.

=back

=head1 EXPORTS

I<None>.

=head1 KNOWN BUGS