NAME

Net::FTP::RetrHandle - Tied or IO::Handle-compatible interface to a file retrieved by FTP

SYNOPSIS

Provides a file reading interface for reading all or parts of files located on a remote FTP server, including emulation of seek and support for downloading only the parts of the file requested.

DESCRIPTION

Support for skipping the beginning of the file is implemented with the FTP REST command, which starts a retrieval at any point in the file. Support for skipping the end of the file is implemented with the FTP ABOR command, which stops the transfer. With these two commands and some careful tracking of the current file position, we're able to reliably emulate a seek/read pair, and get only the parts of the file that are actually read.

This was originally designed for use with Archive::Zip; it's reliable enough that the table of contents and individual files can be extracted from a remote ZIP archive without downloading the whole thing. See EXAMPLES below.

An interface compatible with IO::Handle is provided, along with a tie-based interface.

Remember that an FTP server can only do one thing at a time, so make sure to close your connection before asking the FTP server to do nything else.

CONSTRUCTOR

new ( $ftp, $filename, options... )

Creates a new IO::Handle-compatible object to fetch all or parts of $filename using the FTP connection $ftp.

Available options:

MaxSkipSize => $size

If we need to move forward in a file or close the connection, sometimes it's faster to just read the bytes we don't need than to abort the connection and restart. This setting tells how many unnecessary bytes we're willing to read rather than abort. An appropriate setting depends on the speed of transferring files and the speed of reconnecting to the server.

BlockSize => $size

When doing buffered reads, how many bytes to read at once. The default is the same as the default for Net::FTP, so it's generally best to leave it alone.

AlreadyBinary => $bool

If set to a true value, we assume the server is already in binary mode, and don't try to set it.

METHODS

Most of the methods implemented behave exactly like those from IO::Handle.

These methods are implemented: binmode, clearerr, close, eof, error, getc, getline, getlines, getpos, read, seek, setpos, sysseek, tell, ungetc, opened.

TIED INTERFACE

Instead of a IO::Handle-compatible interface, you can use a tie-based interface to use the standard Perl I/O operators. You can use it like this:

  use Net::FTP::RetrHandle;
  # Create FTP object in $ftp
  # Store filename in $filename
  tie *FH, 'Net::FTP::RetrHandle', $ftp, $filename
    or die "Error in tie!\n";

EXAMPLE

Here's an example of listing a Zip file without downloading the whole thing:

    #!/usr/bin/perl
    
    use warnings;
    use strict;
    
    use Net::FTP;
    use Net::FTP::AutoReconnect;
    use Net::FTP::RetrHandle;
    use Archive::Zip;
    
    my $ftp = Net::FTP::AutoReconnect->new("ftp.info-zip.com", Debug => $ENV{DEBUG}) 
        or die "connect error\n";
    $ftp->login('anonymous','example@example.com')
        or die "login error\n";
    $ftp->cwd('/pub/infozip/UNIX/LINUX')
        or die "cwd error\n";
    my $fh = Net::FTP::RetrHandle->new($ftp,'unz551x-glibc.zip')
        or die "Couldn't get handle to remote file\n";
    my $zip = Archive::Zip->new($fh)
        or die "Couldn't create Zip object\n";
    foreach my $fn ($zip->memberNames())
    {
      print "unz551-glibc.zip: $fn\n";
    }

AUTHOR

Scott Gifford <sgifford@suspectclass.com>

BUGS

The distinction between tied filehandles and IO::Handle-compatible filehandles should be blurrier. It seems like other file handle objects you can freely mix method calls and traditional Perl operations, but I can't figure out how to do it.

Many FTP servers don't like frequent connection aborts. If that's the case, try Net::FTP::AutoReconnect, which will hide much of that from you.

If the filehandle is tied and created with gensym, readline doesn't work with older versions of Perl. No idea why.

SEE ALSO

Net::FTP, Net::FTP::AutoReconnect, IO::Handle.

COPYRIGHT

Copyright (c) 2006 Scott Gifford. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Net::FTP::RetrHandle

perl -MCPAN -e shell
install Net::FTP::RetrHandle