Net::FTP::RetrHandle(3pm)

1Net::FTP::RetrHandle(3)User Contributed Perl DocumentatioNnet::FTP::RetrHandle(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

15       Support for skipping the beginning of the file is implemented with the
16       FTP "REST" command, which starts a retrieval at any point in the file.
17       Support for skipping the end of the file is implemented with the FTP
18       "ABOR" command, which stops the transfer.  With these two commands and
19       some careful tracking of the current file position, we're able to
20       reliably emulate a "seek/read" pair, and get only the parts of the file
21       that are actually read.
22
23       This was originally designed for use with Archive::Zip; it's reliable
24       enough that the table of contents and individual files can be extracted
25       from a remote ZIP archive without downloading the whole thing.  See
26       EXAMPLES below.
27
28       An interface compatible with IO::Handle is provided, along with a
29       "tie"-based interface.
30
31       Remember that an FTP server can only do one thing at a time, so make
32       sure to "close" your connection before asking the FTP server to do
33       nything else.
34

CONSTRUCTOR

36   new ( $ftp, $filename, options... )
37       Creates a new IO::Handle-compatible object to fetch all or parts of
38       $filename using the FTP connection $ftp.
39
40       Available options:
41
42       MaxSkipSize => $size
43           If we need to move forward in a file or close the connection,
44           sometimes it's faster to just read the bytes we don't need than to
45           abort the connection and restart. This setting tells how many
46           unnecessary bytes we're willing to read rather than abort.  An
47           appropriate setting depends on the speed of transferring files and
48           the speed of reconnecting to the server.
49
50       BlockSize => $size
51           When doing buffered reads, how many bytes to read at once.  The
52           default is the same as the default for Net::FTP, so it's generally
53           best to leave it alone.
54
55       AlreadyBinary => $bool
56           If set to a true value, we assume the server is already in binary
57           mode, and don't try to set it.
58

METHODS

60       Most of the methods implemented behave exactly like those from
61       IO::Handle.
62
63       These methods are implemented: "binmode", "clearerr", "close", "eof",
64       "error", "getc", "getline", "getlines", "getpos", "read", "seek",
65       "setpos", "sysseek", "tell", "ungetc", "opened".
66

TIED INTERFACE

68       Instead of a IO::Handle-compatible interface, you can use a "tie"-based
69       interface to use the standard Perl I/O operators.  You can use it like
70       this:
71
72         use Net::FTP::RetrHandle;
73         # Create FTP object in $ftp
74         # Store filename in $filename
75         tie *FH, 'Net::FTP::RetrHandle', $ftp, $filename
76           or die "Error in tie!\n";
77

EXAMPLE

79       Here's an example of listing a Zip file without downloading the whole
80       thing:
81
82           #!/usr/bin/perl
83
84           use warnings;
85           use strict;
86
87           use Net::FTP;
88           use Net::FTP::AutoReconnect;
89           use Net::FTP::RetrHandle;
90           use Archive::Zip;
91
92           my $ftp = Net::FTP::AutoReconnect->new("ftp.info-zip.com", Debug => $ENV{DEBUG})
93               or die "connect error\n";
94           $ftp->login('anonymous','example@example.com')
95               or die "login error\n";
96           $ftp->cwd('/pub/infozip/UNIX/LINUX')
97               or die "cwd error\n";
98           my $fh = Net::FTP::RetrHandle->new($ftp,'unz551x-glibc.zip')
99               or die "Couldn't get handle to remote file\n";
100           my $zip = Archive::Zip->new($fh)
101               or die "Couldn't create Zip object\n";
102           foreach my $fn ($zip->memberNames())
103           {
104             print "unz551-glibc.zip: $fn\n";
105           }
106

AUTHOR

108       Scott Gifford <sgifford@suspectclass.com>
109

BUGS

111       The distinction between tied filehandles and "IO::Handle"-compatible
112       filehandles should be blurrier.  It seems like other file handle
113       objects you can freely mix method calls and traditional Perl
114       operations, but I can't figure out how to do it.
115
116       Many FTP servers don't like frequent connection aborts.  If that's the
117       case, try Net::FTP::AutoReconnect, which will hide much of that from
118       you.
119
120       If the filehandle is tied and created with "gensym", "readline" doesn't
121       work with older versions of Perl.  No idea why.
122

COPYRIGHT

127       Copyright (c) 2006 Scott Gifford. All rights reserved.  This program is
128       free software; you can redistribute it and/or modify it under the same
129       terms as Perl itself.
130
131
132
133perl v5.36.0                      2023-01-20           Net::FTP::RetrHandle(3)