home *** CD-ROM | disk | FTP | other *** search
-
- =head1 NAME
-
-
- Archive::Zip FAQ - Answers to a few frequently asked questions about
- Archive::Zip
-
- =head1 DESCRIPTION
-
-
- It seems that I keep answering the same questions over and over again. I
- assume that this is because my documentation is deficient, rather than that
- people don't read the documentation.
-
-
- So this FAQ is an attempt to cut down on the number of personal answers I have
- to give. At least I can now say "You I<did> read the FAQ, right?".
-
-
- The questions are not in any particular order. The answers assume the current
- version of Archive::Zip; some of the answers depend on newly added/fixed
- functionality.
-
- =head1 Sample code?
-
-
- B<Q:> Can you send me code to do (whatever)?
-
-
- B<A:> Have you looked in the C<examples/> directory yet? It contains:
-
- =over 4
-
- =item examples/calcSizes.pl -- How to find out how big a Zip file will be before writing it
-
-
-
- =item examples/copy.pl -- Copies one Zip file to another
-
-
-
- =item examples/extract.pl -- extract file(s) from a Zip
-
-
-
- =item examples/mfh.pl -- demo for use of MockFileHandle
-
-
-
- =item examples/readScalar.pl -- shows how to use IO::Scalar as the source of a Zip read
-
-
-
- =item examples/selfex.pl -- a brief example of a self-extracting Zip
-
-
-
- =item examples/unzipAll.pl -- uses tree operations to unzip an entire Zip
-
-
-
- =item examples/updateZip.pl -- shows how to read/modify/write a Zip
-
-
-
- =item examples/writeScalar.pl -- shows how to use IO::Scalar as the destination of a Zip write
-
-
-
- =item examples/zip.pl -- Constructs a Zip file
-
-
-
- =item examples/zipcheck.pl -- One way to check a Zip file for validity
-
-
-
- =item examples/zipinfo.pl -- Prints out information about a Zip archive file
-
-
-
- =item examples/zipGrep.pl -- Searches for text in Zip files
-
-
-
- =item examples/ziptest.pl -- Lists a Zip file and checks member CRCs
-
-
-
- =item examples/ziprecent.pl -- Puts recent files into a zipfile
-
-
-
- =item examples/ziptest.pl -- Another way to check a Zip file for validity
-
-
-
- =back
-
- =head1 Can't Read/modify/write same Zip file
-
-
- B<Q:> Why can't I open a Zip file, add a member, and write it back? I get an
- error message when I try.
-
-
- B<A:> Because Archive::Zip doesn't (and can't, generally) read file contents into memory,
- the original Zip file is required to stay around until the writing of the new
- file is completed.
-
-
- The best way to do this is to write the Zip to a temporary file and then
- rename the temporary file to have the old name (possibly after deleting the
- old one).
-
-
- Archive::Zip v1.02 added the archive methods overwrite() and overwriteAs() to
- do this simply and carefully.
-
-
- See C<examples/updateZip.pl> for an example of this technique.
-
- =head1 File creation time not set
-
-
- B<Q:> Upon extracting files, I see that their modification (and access) times are
- set to the time in the Zip archive. However, their creation time is not set to
- the same time. Why?
-
-
- B<A:> Mostly because Perl doesn't give cross-platform access to I<creation time>.
- Indeed, many systems don't support such a concept.
- However, if yours does, you can easily set it. Get the modification time from
- the member using C<lastModTime()>.
-
- =head1 Can't use Archive::Zip on gzip files
-
-
- B<Q:> Can I use Archive::Zip to extract Unix gzip files?
-
-
- B<A:> No.
-
-
- There is a distinction between Unix gzip files, and Zip archives that
- also can use the gzip compression.
-
-
- Depending on the format of the gzip file, you can use Compress::Zlib, or
- Archive::Tar to decompress it (and de-archive it in the case of Tar files).
-
-
- You can unzip PKZIP/WinZip/etc/ archives using Archive::Zip (that's what
- it's for) as long as any compressed members are compressed using
- Deflate compression.
-
- =head1 Add a directory/tree to a Zip
-
-
- B<Q:> How can I add a directory (or tree) full of files to a Zip?
-
-
- B<A:> You can use the Archive::Zip::addTree*() methods:
-
- use Archive::Zip;
- my $zip = Archive::Zip->new();
- # add all readable files and directories below . as xyz/*
- $zip->addTree( '.', 'xyz' );
- # add all readable plain files below /abc as def/*
- $zip->addTree( '/abc', 'def', sub { -f && -r } );
- # add all .c files below /tmp as stuff/*
- $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
- # add all .o files below /tmp as stuff/* if they aren't writable
- $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
- # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
- $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
- # and write them into a file
- $zip->writeToFileNamed('xxx.zip');
-
- =head1 Extract a directory/tree
-
-
- B<Q:> How can I extract some (or all) files from a Zip into a different
- directory?
-
-
- B<A:> You can use the Archive::Zip::extractTree() method:
- ??? ||
-
-
- # now extract the same files into /tmpx
- $zip->extractTree( 'stuff', '/tmpx' );
-
- =head1 Zip times might be off by 1 second
-
-
- B<Q:> It bothers me greatly that my file times are wrong by one second about half
- the time. Why don't you do something about it?
-
-
- B<A:> Get over it. This is a result of the Zip format storing times in DOS
- format, which has a resolution of only two seconds.
-
- =head1 Zip times don't include time zone information
-
-
- B<Q:> My file times don't respect time zones. What gives?
-
-
- B<A:> If this is important to you, please submit patches to read the various
- Extra Fields that encode times with time zones. I'm just using the DOS
- Date/Time, which doesn't have a time zone.
-
- =head1 How do I make a self-extracting Zip
-
-
- B<Q:> I want to make a self-extracting Zip file. Can I do this?
-
-
- B<A:> Yes. You can write a self-extracting archive stub (that is, a version of
- unzip) to the output filehandle that you pass to writeToFileHandle(). See
- examples/selfex.pl for how to write a self-extracting archive.
-
-
- However, you should understand that this will only work on one kind of
- platform (the one for which the stub was compiled).
-
- =head1 How can I deal with Zips with prepended garbage (i.e. from Sircam)
-
-
- B<Q:> How can I tell if a Zip has been damaged by adding garbage to the
- beginning?
-
-
- B<A:> I added code for this for the Amavis virus scanner. You can query archives
- for their 'eocdOffset' property, which should be 0:
-
-
- if ($zip->eocdOffset > 0)
- { warn($zip->eocdOffset . " bytes of garbage at beginning of Zip") }
-
- =head1 Can't extract Shrunk files
-
-
- B<Q:> I'm trying to extract a file out of a Zip produced by PKZIP, and keep
- getting this error message:
-
-
- error: Unsupported compression combination: read 6, write 0
-
-
- B<A:> You can't uncompress this archive member. Archive::Zip only supports uncompressed
- members, and compressed members that are compressed using the compression
- supported by Compress::Zlib. That means only Deflated and Stored members.
-
-
- Your file is compressed using the Shrink format, which isn't supported by
- Compress::Zlib.
-
-
- You could, perhaps, use a command-line UnZip program (like the Info-Zip
- one) to extract this.
-
- =head1 Can't do decryption
-
-
- B<Q:> How do I decrypt encrypted Zip members?
-
-
- B<A:> With some other program or library. Archive::Zip doesn't support decryption,
- and probably never will (unless I<you> write it).
-
- =head1 How to test file integrity?
-
-
- B<Q:> How can Archive::Zip can test the validity of a Zip file?
-
-
- B<A:> If you try to decompress the file, the gzip streams will report errors
- if you have garbage. Most of the time.
-
- If you try to open the file and a central directory structure can't be
- found, an error will be reported.
-
- When a file is being read, if we can't find a proper PK.. signature in
- the right places we report a format error.
-
- If there is added garbage at the beginning of a Zip file (as inserted
- by some viruses), you can find out about it, but Archive::Zip will ignore it,
- and you can still use the archive. When it gets written back out the
- added stuff will be gone.
-
-
- There are two ready-to-use utilities in the examples directory that can
- be used to test file integrity, or that you can use as examples
- for your own code:
-
- =over 4
-
- =item examples/zipcheck.pl shows how to use an attempted extraction to test a file.
-
-
-
- =item examples/ziptest.pl shows how to test CRCs in a file.
-
-
-
- =back
-
- =head1 Duplicate files in Zip?
-
-
- B<Q:> Archive::Zip let me put the same file in my Zip twice! Why don't you prevent this?
-
-
- B<A:> As far as I can tell, this is not disallowed by the Zip spec. If you
- think it's a bad idea, check for it yourself:
-
-
- $zip->addFile($someFile, $someName) unless $zip->memberNamed($someName);
-
-
- I can even imagine cases where this might be useful (for instance, multiple
- versions of files).
-
- =head1 File ownership/permissions/ACLS/etc
-
-
- B<Q:> Why doesn't Archive::Zip deal with file ownership, ACLs, etc.?
-
-
- B<A:> There is no standard way to represent these in the Zip file format. If
- you want to send me code to properly handle the various extra fields that
- have been used to represent these through the years, I'll look at it.
-
- =head1 I can't compile but AS only has an old version of Archive::Zip
-
-
- B<Q:> I've only installed modules using ActiveState's PPM program and
- repository. But they have a much older version of Archive::Zip than is in CPAN. Will
- you send me a newer PPM?
-
-
- B<A:> Probably not, unless I get lots of extra time. But there's no reason you
- can't install the version from CPAN. Archive::Zip is pure Perl, so all you need is
- NMAKE, which you can get for free from Microsoft (see the FAQ in the
- ActiveState documentation for details on how to install CPAN modules).
-
- =head1 My JPEGs (or MP3's) don't compress when I put them into Zips!
-
-
- B<Q:> How come my JPEGs and MP3's don't compress much when I put them into Zips?
-
-
- B<A:> Because they're already compressed.
-
- =head1 Under Windows, things lock up/get damaged
-
-
- B<Q:> I'm using Windows. When I try to use Archive::Zip, my machine locks up/makes
- funny sounds/displays a BSOD/corrupts data. How can I fix this?
-
-
- B<A:> First, try the newest version of Compress::Zlib. I know of
- Windows-related problems prior to v1.14 of that library.
-
-
- If that doesn't get rid of the problem, fix your computer or get rid of
- Windows.
-
- =head1 Zip contents in a scalar
-
-
- B<Q:> I want to read a Zip file from (or write one to) a scalar variable instead
- of a file. How can I do this?
-
-
- B<A:> Use C<IO::Scalar> and the C<readFromFileHandle()> and
- C<writeToFileHandle()> methods.
- See C<examples/readScalar.pl> and C<examples/writeScalar.pl>.
-
- =head1 Reading from streams
-
-
- B<Q:> How do I read from a stream (like for the Info-Zip C<funzip> program)?
-
-
- B<A:> This isn't currently supported, though writing to a stream is.
-