Net::FTP::RetrHandle(3User Contributed Perl DocumentatiNet::FTP::RetrHandle(3)NAMENet::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.
perl v5.14.2 2006-09-28 Net::FTP::RetrHandle(3)
