1Archive::Zip(3)       User Contributed Perl Documentation      Archive::Zip(3)
2
3
4

NAME

6       Archive::Zip - Provide an interface to ZIP archive files.
7

SYNOPSIS

9          # Create a Zip file
10          use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
11          my $zip = Archive::Zip->new();
12
13          # Add a directory
14          my $dir_member = $zip->addDirectory( 'dirname/' );
15
16          # Add a file from a string with compression
17          my $string_member = $zip->addString( 'This is a test', 'stringMember.txt' );
18          $string_member->desiredCompressionMethod( COMPRESSION_DEFLATED );
19
20          # Add a file from disk
21          my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
22
23          # Save the Zip file
24          unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {
25              die 'write error';
26          }
27
28          # Read a Zip file
29          my $somezip = Archive::Zip->new();
30          unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {
31              die 'read error';
32          }
33
34          # Change the compression type for a file in the Zip
35          my $member = $somezip->memberNamed( 'stringMember.txt' );
36          $member->desiredCompressionMethod( COMPRESSION_STORED );
37          unless ( $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK ) {
38              die 'write error';
39          }
40

DESCRIPTION

42       The Archive::Zip module allows a Perl program to create, manipulate,
43       read, and write Zip archive files.
44
45       Zip archives can be created, or you can read from existing zip files.
46
47       Once created, they can be written to files, streams, or strings.
48       Members can be added, removed, extracted, replaced, rearranged, and
49       enumerated.  They can also be renamed or have their dates, comments, or
50       other attributes queried or modified. Their data can be compressed or
51       uncompressed as needed.
52
53       Members can be created from members in existing Zip files, or from
54       existing directories, files, or strings.
55
56       This module uses the Compress::Raw::Zlib library to read and write the
57       compressed streams inside the files.
58
59       One can use Archive::Zip::MemberRead to read the zip file archive
60       members as if they were files.
61
62   File Naming
63       Regardless of what your local file system uses for file naming, names
64       in a Zip file are in Unix format (forward slashes (/) separating
65       directory names, etc.).
66
67       "Archive::Zip" tries to be consistent with file naming conventions, and
68       will translate back and forth between native and Zip file names.
69
70       However, it can't guess which format names are in. So two rules control
71       what kind of file name you must pass various routines:
72
73       Names of files are in local format.
74           "File::Spec" and "File::Basename" are used for various file
75           operations. When you're referring to a file on your system, use its
76           file naming conventions.
77
78       Names of archive members are in Unix format.
79           This applies to every method that refers to an archive member, or
80           provides a name for new archive members. The extract() methods that
81           can take one or two names will convert from local to zip names if
82           you call them with a single name.
83
84   Archive::Zip Object Model
85       Overview
86
87       Archive::Zip::Archive objects are what you ordinarily deal with.  These
88       maintain the structure of a zip file, without necessarily holding data.
89       When a zip is read from a disk file, the (possibly compressed) data
90       still lives in the file, not in memory. Archive members hold
91       information about the individual members, but not (usually) the actual
92       member data. When the zip is written to a (different) file, the member
93       data is compressed or copied as needed.  It is possible to make archive
94       members whose data is held in a string in memory, but this is not done
95       when a zip file is read. Directory members don't have any data.
96
97   Inheritance
98         Exporter
99          Archive::Zip                            Common base class, has defs.
100              Archive::Zip::Archive               A Zip archive.
101              Archive::Zip::Member                Abstract superclass for all members.
102                  Archive::Zip::StringMember      Member made from a string
103                  Archive::Zip::FileMember        Member made from an external file
104                      Archive::Zip::ZipFileMember Member that lives in a zip file
105                      Archive::Zip::NewFileMember Member whose data is in a file
106                  Archive::Zip::DirectoryMember   Member that is a directory
107

EXPORTS

109       :CONSTANTS
110           Exports the following constants:
111
112           FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK
113           GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK
114           COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK
115           IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE
116           COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST
117           COMPRESSION_LEVEL_BEST_COMPRESSION ZIP64_SUPPORTED ZIP64_AS_NEEDED
118           ZIP64_EOCD ZIP64_HEADERS
119
120       :MISC_CONSTANTS
121           Exports the following constants (only necessary for extending the
122           module):
123
124           FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS FA_MACINTOSH
125           FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
126           GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
127           GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
128           GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
129           DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
130           DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
131           COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
132           COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
133           COMPRESSION_DEFLATED_ENHANCED
134           COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
135
136       :ERROR_CODES
137           Explained below. Returned from most methods.
138
139           AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
140

ERROR CODES

142       Many of the methods in Archive::Zip return error codes. These are
143       implemented as inline subroutines, using the "use constant" pragma.
144       They can be imported into your namespace using the ":ERROR_CODES" tag:
145
146         use Archive::Zip qw( :ERROR_CODES );
147
148         ...
149
150         unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {
151             die "whoops!";
152         }
153
154       AZ_OK (0)
155           Everything is fine.
156
157       AZ_STREAM_END (1)
158           The read stream (or central directory) ended normally.
159
160       AZ_ERROR (2)
161           There was some generic kind of error.
162
163       AZ_FORMAT_ERROR (3)
164           There is a format error in a ZIP file being read.
165
166       AZ_IO_ERROR (4)
167           There was an IO error.
168
169   Compression
170       Archive::Zip allows each member of a ZIP file to be compressed (using
171       the Deflate algorithm) or uncompressed.
172
173       Other compression algorithms that some versions of ZIP have been able
174       to produce are not supported. Each member has two compression methods:
175       the one it's stored as (this is always COMPRESSION_STORED for string
176       and external file members), and the one you desire for the member in
177       the zip file.
178
179       These can be different, of course, so you can make a zip member that is
180       not compressed out of one that is, and vice versa.
181
182       You can inquire about the current compression and set the desired
183       compression method:
184
185         my $member = $zip->memberNamed( 'xyz.txt' );
186         $member->compressionMethod();    # return current compression
187
188         # set to read uncompressed
189         $member->desiredCompressionMethod( COMPRESSION_STORED );
190
191         # set to read compressed
192         $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
193
194       There are two different compression methods:
195
196       COMPRESSION_STORED
197           File is stored (no compression)
198
199       COMPRESSION_DEFLATED
200           File is Deflated
201
202   Compression Levels
203       If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can
204       choose different compression levels. This choice may affect the speed
205       of compression and decompression, as well as the size of the compressed
206       member data.
207
208         $member->desiredCompressionLevel( 9 );
209
210       The levels given can be:
211
212       •   0 or COMPRESSION_LEVEL_NONE
213
214           This is the same as saying
215
216             $member->desiredCompressionMethod( COMPRESSION_STORED );
217
218       •   1 .. 9
219
220           1 gives the best speed and worst compression, and 9 gives the best
221           compression and worst speed.
222
223       •   COMPRESSION_LEVEL_FASTEST
224
225           This is a synonym for level 1.
226
227       •   COMPRESSION_LEVEL_BEST_COMPRESSION
228
229           This is a synonym for level 9.
230
231       •   COMPRESSION_LEVEL_DEFAULT
232
233           This gives a good compromise between speed and compression, and is
234           currently equivalent to 6 (this is in the zlib code).  This is the
235           level that will be used if not specified.
236

Archive::Zip Methods

238       The Archive::Zip class (and its invisible subclass
239       Archive::Zip::Archive) implement generic zip file functionality.
240       Creating a new Archive::Zip object actually makes an
241       Archive::Zip::Archive object, but you don't have to worry about this
242       unless you're subclassing.
243
244   Constructor
245       new( [$fileName] )
246       new( { filename => $fileName } )
247           Make a new, empty zip archive.
248
249               my $zip = Archive::Zip->new();
250
251           If an additional argument is passed, new() will call read() to read
252           the contents of an archive:
253
254               my $zip = Archive::Zip->new( 'xyz.zip' );
255
256           If a filename argument is passed and the read fails for any reason,
257           new will return undef. For this reason, it may be better to call
258           read separately.
259
260   Zip Archive Utility Methods
261       These Archive::Zip methods may be called as functions or as object
262       methods. Do not call them as class methods:
263
264           $zip = Archive::Zip->new();
265           $crc = Archive::Zip::computeCRC32( 'ghijkl' );    # OK
266           $crc = $zip->computeCRC32( 'ghijkl' );            # also OK
267           $crc = Archive::Zip->computeCRC32( 'ghijkl' );    # NOT OK
268
269       Archive::Zip::computeCRC32( $string [, $crc] )
270       Archive::Zip::computeCRC32( { string => $string [, checksum => $crc ] }
271       )
272           This is a utility function that uses the Compress::Raw::Zlib CRC
273           routine to compute a CRC-32. You can get the CRC of a string:
274
275               $crc = Archive::Zip::computeCRC32( $string );
276
277           Or you can compute the running CRC:
278
279               $crc = 0;
280               $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
281               $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
282
283       Archive::Zip::setChunkSize( $number )
284       Archive::Zip::setChunkSize( { chunkSize => $number } )
285           Report or change chunk size used for reading and writing.  This can
286           make big differences in dealing with large files.  Currently, this
287           defaults to 32K. This also changes the chunk size used for
288           Compress::Raw::Zlib. You must call setChunkSize() before reading or
289           writing. This is not exportable, so you must call it like:
290
291               Archive::Zip::setChunkSize( 4096 );
292
293           or as a method on a zip (though this is a global setting).  Returns
294           old chunk size.
295
296       Archive::Zip::chunkSize()
297           Returns the current chunk size:
298
299               my $chunkSize = Archive::Zip::chunkSize();
300
301       Archive::Zip::setErrorHandler( \&subroutine )
302       Archive::Zip::setErrorHandler( { subroutine => \&subroutine } )
303           Change the subroutine called with error strings. This defaults to
304           \&Carp::carp, but you may want to change it to get the error
305           strings. This is not exportable, so you must call it like:
306
307               Archive::Zip::setErrorHandler( \&myErrorHandler );
308
309           If myErrorHandler is undef, resets handler to default.  Returns old
310           error handler. Note that if you call Carp::carp or a similar
311           routine or if you're chaining to the default error handler from
312           your error handler, you may want to increment the number of caller
313           levels that are skipped (do not just set it to a number):
314
315               $Carp::CarpLevel++;
316
317       Archive::Zip::tempFile( [ $tmpdir ] )
318       Archive::Zip::tempFile( { tempDir => $tmpdir } )
319           Create a uniquely named temp file. It will be returned open for
320           read/write. If $tmpdir is given, it is used as the name of a
321           directory to create the file in. If not given, creates the file
322           using File::Spec::tmpdir(). Generally, you can override this choice
323           using the
324
325               $ENV{TMPDIR}
326
327           environment variable. But see the File::Spec documentation for your
328           system. Note that on many systems, if you're running in taint mode,
329           then you must make sure that $ENV{TMPDIR} is untainted for it to be
330           used.  Will NOT create $tmpdir if it does not exist (this is a
331           change from prior versions!). Returns file handle and name:
332
333               my ($fh, $name) = Archive::Zip::tempFile();
334               my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
335               my $fh = Archive::Zip::tempFile();  # if you don't need the name
336
337   Zip Archive Accessors
338       members()
339           Return a copy of the members array
340
341               my @members = $zip->members();
342
343       numberOfMembers()
344           Return the number of members I have
345
346       memberNames()
347           Return a list of the (internal) file names of the zip members
348
349       memberNamed( $string )
350       memberNamed( { zipName => $string } )
351           Return ref to member whose filename equals given filename or undef.
352           $string must be in Zip (Unix) filename format.
353
354       membersMatching( $regex )
355       membersMatching( { regex => $regex } )
356           Return array of members whose filenames match given regular
357           expression in list context. Returns number of matching members in
358           scalar context.
359
360               my @textFileMembers = $zip->membersMatching( '.*\.txt' );
361               # or
362               my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
363
364       zip64()
365           Returns whether the previous read or write of the archive has been
366           done in zip64 format.
367
368       desiredZip64Mode()
369           Gets or sets which parts of the archive should be written in zip64
370           format: All parts as needed (ZIP64_AS_NEEDED), the default, force
371           writing the zip64 end of central directory record (ZIP64_EOCD),
372           force writing the zip64 EOCD record and all headers in zip64 format
373           (ZIP64_HEADERS).
374
375       versionMadeBy()
376       versionNeededToExtract()
377           Gets the fields from the zip64 end of central directory record.
378           These are always 0 if the archive is not in zip64 format.
379
380       diskNumber()
381           Return the disk that I start on. Not used for writing zips, but
382           might be interesting if you read a zip in. This should be 0, as
383           Archive::Zip does not handle multi-volume archives.
384
385       diskNumberWithStartOfCentralDirectory()
386           Return the disk number that holds the beginning of the central
387           directory. Not used for writing zips, but might be interesting if
388           you read a zip in. This should be 0, as Archive::Zip does not
389           handle multi-volume archives.
390
391       numberOfCentralDirectoriesOnThisDisk()
392           Return the number of CD structures in the zipfile last read in.
393           Not used for writing zips, but might be interesting if you read a
394           zip in.
395
396       numberOfCentralDirectories()
397           Return the number of CD structures in the zipfile last read in.
398           Not used for writing zips, but might be interesting if you read a
399           zip in.
400
401       centralDirectorySize()
402           Returns central directory size, as read from an external zip file.
403           Not used for writing zips, but might be interesting if you read a
404           zip in.
405
406       centralDirectoryOffsetWRTStartingDiskNumber()
407           Returns the offset into the zip file where the CD begins. Not used
408           for writing zips, but might be interesting if you read a zip in.
409
410       zipfileComment( [ $string ] )
411       zipfileComment( [ { comment => $string } ] )
412           Get or set the zipfile comment. Returns the old comment.
413
414               print $zip->zipfileComment();
415               $zip->zipfileComment( 'New Comment' );
416
417       eocdOffset()
418           Returns the (unexpected) number of bytes between where the EOCD was
419           found and where it expected to be. This is normally 0, but would be
420           positive if something (a virus, perhaps) had added bytes somewhere
421           before the EOCD. Not used for writing zips, but might be
422           interesting if you read a zip in. Here is an example of how you can
423           diagnose this:
424
425             my $zip = Archive::Zip->new('somefile.zip');
426             if ($zip->eocdOffset())
427             {
428               warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
429             }
430
431           The eocdOffset() is used to adjust the starting position of member
432           headers, if necessary.
433
434       fileName()
435           Returns the name of the file last read from. If nothing has been
436           read yet, returns an empty string; if read from a file handle,
437           returns the handle in string form.
438
439   Zip Archive Member Operations
440       Various operations on a zip file modify members. When a member is
441       passed as an argument, you can either use a reference to the member
442       itself, or the name of a member. Of course, using the name requires
443       that names be unique within a zip (this is not enforced).
444
445       removeMember( $memberOrName )
446       removeMember( { memberOrZipName => $memberOrName } )
447           Remove and return the given member, or match its name and remove
448           it. Returns undef if member or name does not exist in this Zip. No-
449           op if member does not belong to this zip.
450
451       replaceMember( $memberOrName, $newMember )
452       replaceMember( { memberOrZipName => $memberOrName, newMember =>
453       $newMember } )
454           Remove and return the given member, or match its name and remove
455           it. Replace with new member. Returns undef if member or name does
456           not exist in this Zip, or if $newMember is undefined.
457
458           It is an (undiagnosed) error to provide a $newMember that is a
459           member of the zip being modified.
460
461               my $member1 = $zip->removeMember( 'xyz' );
462               my $member2 = $zip->replaceMember( 'abc', $member1 );
463               # now, $member2 (named 'abc') is not in $zip,
464               # and $member1 (named 'xyz') is, having taken $member2's place.
465
466       extractMember( $memberOrName [, $extractedName ] )
467       extractMember( { memberOrZipName => $memberOrName [, name =>
468       $extractedName ] } )
469           Extract the given member, or match its name and extract it.
470           Returns undef if member does not exist in this Zip. If optional
471           second arg is given, use it as the name of the extracted member.
472           Otherwise, the internal filename of the member is used as the name
473           of the extracted file or directory.  If you pass $extractedName, it
474           should be in the local file system's format.  If you do not pass
475           $extractedName and the internal filename traverses a parent
476           directory or a symbolic link, the extraction will be aborted with
477           "AC_ERROR" for security reason.  All necessary directories will be
478           created. Returns "AZ_OK" on success.
479
480       extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
481       extractMemberWithoutPaths( { memberOrZipName => $memberOrName [, name
482       => $extractedName ] } )
483           Extract the given member, or match its name and extract it.  Does
484           not use path information (extracts into the current directory).
485           Returns undef if member does not exist in this Zip.  If optional
486           second arg is given, use it as the name of the extracted member
487           (its paths will be deleted too). Otherwise, the internal filename
488           of the member (minus paths) is used as the name of the extracted
489           file or directory. Returns "AZ_OK" on success.  If you do not pass
490           $extractedName and the internal filename is equalled to a local
491           symbolic link, the extraction will be aborted with "AC_ERROR" for
492           security reason.
493
494       addMember( $member )
495       addMember( { member => $member } )
496           Append a member (possibly from another zip file) to the zip file.
497           Returns the new member. Generally, you will use addFile(),
498           addDirectory(), addFileOrDirectory(), addString(), or read() to add
499           members.
500
501               # Move member named 'abc' to end of zip:
502               my $member = $zip->removeMember( 'abc' );
503               $zip->addMember( $member );
504
505       updateMember( $memberOrName, $fileName )
506       updateMember( { memberOrZipName => $memberOrName, name => $fileName } )
507           Update a single member from the file or directory named $fileName.
508           Returns the (possibly added or updated) member, if any; "undef" on
509           errors.  The comparison is based on lastModTime() and (in the case
510           of a non-directory) the size of the file.
511
512       addFile( $fileName [, $newName, $compressionLevel ] )
513       addFile( { filename => $fileName [, zipName => $newName,
514       compressionLevel => $compressionLevel } ] )
515           Append a member whose data comes from an external file, returning
516           the member or undef. The member will have its file name set to the
517           name of the external file, and its desiredCompressionMethod set to
518           COMPRESSION_DEFLATED. The file attributes and last modification
519           time will be set from the file.  If the name given does not
520           represent a readable plain file or symbolic link, undef will be
521           returned. $fileName must be in the format required for the local
522           file system.  The optional $newName argument sets the internal file
523           name to something different than the given $fileName. $newName, if
524           given, must be in Zip name format (i.e. Unix).  The text mode bit
525           will be set if the contents appears to be text (as returned by the
526           "-T" perl operator).
527
528           NOTE that you should not (generally) use absolute path names in zip
529           member names, as this will cause problems with some zip tools as
530           well as introduce a security hole and make the zip harder to use.
531
532       addDirectory( $directoryName [, $fileName ] )
533       addDirectory( { directoryName => $directoryName [, zipName => $fileName
534       ] } )
535           Append a member created from the given directory name. The
536           directory name does not have to name an existing directory.  If the
537           named directory exists, the file modification time and permissions
538           are set from the existing directory, otherwise they are set to now
539           and permissive default permissions.  $directoryName must be in
540           local file system format.  The optional second argument sets the
541           name of the archive member (which defaults to $directoryName). If
542           given, it must be in Zip (Unix) format.  Returns the new member.
543
544       addFileOrDirectory( $name [, $newName, $compressionLevel ] )
545       addFileOrDirectory( { name => $name [, zipName => $newName,
546       compressionLevel => $compressionLevel ] } )
547           Append a member from the file or directory named $name. If $newName
548           is given, use it for the name of the new member.  Will add or
549           remove trailing slashes from $newName as needed.  $name must be in
550           local file system format.  The optional second argument sets the
551           name of the archive member (which defaults to $name). If given, it
552           must be in Zip (Unix) format.
553
554       addString( $stringOrStringRef, $name, [$compressionLevel] )
555       addString( { string => $stringOrStringRef [, zipName => $name,
556       compressionLevel => $compressionLevel ] } )
557           Append a member created from the given string or string reference.
558           The name is given by the second argument.  Returns the new member.
559           The last modification time will be set to now, and the file
560           attributes will be set to permissive defaults.
561
562               my $member = $zip->addString( 'This is a test', 'test.txt' );
563
564       contents( $memberOrMemberName [, $newContents ] )
565       contents( { memberOrZipName => $memberOrMemberName [, contents =>
566       $newContents ] } )
567           Returns the uncompressed data for a particular member, or undef.
568
569               print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
570
571           Also can change the contents of a member:
572
573               $zip->contents( 'xyz.txt', 'This is the new contents' );
574
575           If called expecting an array as the return value, it will include
576           the status as the second value in the array.
577
578               ($content, $status) = $zip->contents( 'xyz.txt');
579
580   Zip Archive I/O operations
581       A Zip archive can be written to a file or file handle, or read from
582       one.
583
584       writeToFileNamed( $fileName )
585       writeToFileNamed( { fileName => $fileName } )
586           Write a zip archive to named file. Returns "AZ_OK" on success.
587
588               my $status = $zip->writeToFileNamed( 'xx.zip' );
589               die "error somewhere" if $status != AZ_OK;
590
591           Note that if you use the same name as an existing zip file that you
592           read in, you will clobber ZipFileMembers. So instead, write to a
593           different file name, then delete the original.  If you use the
594           overwrite() or overwriteAs() methods, you can re-write the original
595           zip in this way.  $fileName should be a valid file name on your
596           system.
597
598       writeToFileHandle( $fileHandle [, $seekable] )
599           Write a zip archive to a file handle. Return AZ_OK on success. The
600           optional second arg tells whether or not to try to seek backwards
601           to re-write headers. If not provided, it is set if the Perl "-f"
602           test returns true. This could fail on some operating systems,
603           though.
604
605               my $fh = IO::File->new( 'someFile.zip', 'w' );
606               unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {
607                   # error handling
608               }
609
610           If you pass a file handle that is not seekable (like if you're
611           writing to a pipe or a socket), pass a false second argument:
612
613               my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
614               $zip->writeToFileHandle( $fh, 0 );   # fh is not seekable
615
616           If this method fails during the write of a member, that member and
617           all following it will return false from wasWritten(). See
618           writeCentralDirectory() for a way to deal with this.  If you want,
619           you can write data to the file handle before passing it to
620           writeToFileHandle(); this could be used (for instance) for making
621           self-extracting archives. However, this only works reliably when
622           writing to a real file (as opposed to STDOUT or some other possible
623           non-file).
624
625           See examples/selfex.pl for how to write a self-extracting archive.
626
627       writeCentralDirectory( $fileHandle [, $offset ] )
628       writeCentralDirectory( { fileHandle => $fileHandle [, offset => $offset
629       ] } )
630           Writes the central directory structure to the given file handle.
631
632           Returns AZ_OK on success. If given an $offset, will seek to that
633           point before writing. This can be used for recovery in cases where
634           writeToFileHandle or writeToFileNamed returns an IO error because
635           of running out of space on the destination file.
636
637           You can truncate the zip by seeking backwards and then writing the
638           directory:
639
640               my $fh = IO::File->new( 'someFile.zip', 'w' );
641                   my $retval = $zip->writeToFileHandle( $fh );
642               if ( $retval == AZ_IO_ERROR ) {
643                   my @unwritten = grep { not $_->wasWritten() } $zip->members();
644                   if (@unwritten) {
645                       $zip->removeMember( $member ) foreach my $member ( @unwritten );
646                       $zip->writeCentralDirectory( $fh,
647                       $unwritten[0]->writeLocalHeaderRelativeOffset());
648                   }
649               }
650
651       overwriteAs( $newName )
652       overwriteAs( { filename => $newName } )
653           Write the zip to the specified file, as safely as possible.  This
654           is done by first writing to a temp file, then renaming the original
655           if it exists, then renaming the temp file, then deleting the
656           renamed original if it exists. Returns AZ_OK if successful.
657
658       overwrite()
659           Write back to the original zip file. See overwriteAs() above.  If
660           the zip was not ever read from a file, this generates an error.
661
662       read( $fileName )
663       read( { filename => $fileName } )
664           Read zipfile headers from a zip file, appending new members.
665           Returns "AZ_OK" or error code.
666
667               my $zipFile = Archive::Zip->new();
668               my $status = $zipFile->read( '/some/FileName.zip' );
669
670       readFromFileHandle( $fileHandle, $filename )
671       readFromFileHandle( { fileHandle => $fileHandle, filename => $filename
672       } )
673           Read zipfile headers from an already-opened file handle, appending
674           new members. Does not close the file handle.  Returns "AZ_OK" or
675           error code. Note that this requires a seekable file handle; reading
676           from a stream is not yet supported, but using in-memory data is.
677
678               my $fh = IO::File->new( '/some/FileName.zip', 'r' );
679               my $zip1 = Archive::Zip->new();
680               my $status = $zip1->readFromFileHandle( $fh );
681               my $zip2 = Archive::Zip->new();
682               $status = $zip2->readFromFileHandle( $fh );
683
684           Read zip using in-memory data (recursable):
685
686               open my $fh, "<", "archive.zip" or die $!;
687               my $zip_data = do { local $.; <$fh> };
688               my $zip = Archive::Zip->new;
689               open my $dh, "+<", \$zip_data;
690               $zip->readFromFileHandle ($dh);
691
692   Zip Archive Tree operations
693       These used to be in Archive::Zip::Tree but got moved into Archive::Zip.
694       They enable operation on an entire tree of members or files.  A usage
695       example:
696
697         use Archive::Zip;
698         my $zip = Archive::Zip->new();
699
700         # add all readable files and directories below . as xyz/*
701         $zip->addTree( '.', 'xyz' );
702
703         # add all readable plain files below /abc as def/*
704         $zip->addTree( '/abc', 'def', sub { -f && -r } );
705
706         # add all .c files below /tmp as stuff/*
707         $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
708
709         # add all .o files below /tmp as stuff/* if they aren't writable
710         $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
711
712         # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
713         $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
714
715         # and write them into a file
716         $zip->writeToFileNamed('xxx.zip');
717
718         # now extract the same files into /tmpx
719         $zip->extractTree( 'stuff', '/tmpx' );
720
721       $zip->addTree( $root, $dest [, $pred, $compressionLevel ] ) -- Add tree
722       of files to a zip
723       $zip->addTree( { root => $root, zipName => $dest [, select => $pred,
724       compressionLevel => $compressionLevel ] )
725           $root is the root of the tree of files and directories to be added.
726           It is a valid directory name on your system. $dest is the name for
727           the root in the zip file (undef or blank means to use relative
728           pathnames). It is a valid ZIP directory name (that is, it uses
729           forward slashes (/) for separating directory components). $pred is
730           an optional subroutine reference to select files: it is passed the
731           name of the prospective file or directory using $_, and if it
732           returns true, the file or directory will be included. The default
733           is to add all readable files and directories. For instance, using
734
735             my $pred = sub { /\.txt/ };
736             $zip->addTree( '.', '', $pred );
737
738           will add all the .txt files in and below the current directory,
739           using relative names, and making the names identical in the
740           zipfile:
741
742             original name           zip member name
743             ./xyz                   xyz
744             ./a/                    a/
745             ./a/b                   a/b
746
747           To translate absolute to relative pathnames, just pass them in:
748           $zip->addTree( '/c/d', 'a' );
749
750             original name           zip member name
751             /c/d/xyz                a/xyz
752             /c/d/a/                 a/a/
753             /c/d/a/b                a/a/b
754
755           Returns AZ_OK on success. Note that this will not follow symbolic
756           links to directories. Note also that this does not check for the
757           validity of filenames.
758
759           Note that you generally don't want to make zip archive member names
760           absolute.
761
762       $zip->addTreeMatching( $root, $dest, $pattern [, $pred,
763       $compressionLevel ] )
764       $zip->addTreeMatching( { root => $root, zipName => $dest, pattern =>
765       $pattern [, select => $pred, compressionLevel => $compressionLevel ] }
766       )
767           $root is the root of the tree of files and directories to be added
768           $dest is the name for the root in the zip file (undef means to use
769           relative pathnames) $pattern is a (non-anchored) regular expression
770           for filenames to match $pred is an optional subroutine reference to
771           select files: it is passed the name of the prospective file or
772           directory in $_, and if it returns true, the file or directory will
773           be included.  The default is to add all readable files and
774           directories. To add all files in and below the current directory
775           whose names end in ".pl", and make them extract into a subdirectory
776           named "xyz", do this:
777
778             $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
779
780           To add all writable files in and below the directory named "/abc"
781           whose names end in ".pl", and make them extract into a subdirectory
782           named "xyz", do this:
783
784             $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
785
786           Returns AZ_OK on success. Note that this will not follow symbolic
787           links to directories.
788
789       $zip->updateTree( $root [, $dest , $pred , $mirror, $compressionLevel ]
790       );
791       $zip->updateTree( { root => $root [, zipName => $dest, select => $pred,
792       mirror => $mirror, compressionLevel => $compressionLevel ] } );
793           Update a zip file from a directory tree.
794
795           updateTree() takes the same arguments as addTree(), but first
796           checks to see whether the file or directory already exists in the
797           zip file, and whether it has been changed.
798
799           If the fourth argument $mirror is true, then delete all my members
800           if corresponding files were not found.
801
802           Returns an error code or AZ_OK if all is well.
803
804       $zip->extractTree( [ $root, $dest, $volume } ] )
805       $zip->extractTree( [ { root => $root, zipName => $dest, volume =>
806       $volume } ] )
807           If you don't give any arguments at all, will extract all the files
808           in the zip with their original names.
809
810           If you supply one argument for $root, "extractTree" will extract
811           all the members whose names start with $root into the current
812           directory, stripping off $root first.  $root is in Zip (Unix)
813           format.  For instance,
814
815             $zip->extractTree( 'a' );
816
817           when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
818           will extract:
819
820           a/x as ./x
821
822           a/b/c as ./b/c
823
824           If you give two arguments, "extractTree" extracts all the members
825           whose names start with $root. It will translate $root into $dest to
826           construct the destination file name.  $root and $dest are in Zip
827           (Unix) format.  For instance,
828
829              $zip->extractTree( 'a', 'd/e' );
830
831           when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
832           will extract:
833
834           a/x to d/e/x
835
836           a/b/c to d/e/b/c and ignore ax/d/e and d/e
837
838           If you give three arguments, "extractTree" extracts all the members
839           whose names start with $root. It will translate $root into $dest to
840           construct the destination file name, and then it will convert to
841           local file system format, using $volume as the name of the
842           destination volume.
843
844           $root and $dest are in Zip (Unix) format.
845
846           $volume is in local file system format.
847
848           For instance, under Windows,
849
850              $zip->extractTree( 'a', 'd/e', 'f:' );
851
852           when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
853           will extract:
854
855           a/x to f:d/e/x
856
857           a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
858
859           If you want absolute paths (the prior example used paths relative
860           to the current directory on the destination volume, you can specify
861           these in $dest:
862
863              $zip->extractTree( 'a', '/d/e', 'f:' );
864
865           when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
866           will extract:
867
868           a/x to f:\d\e\x
869
870           a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
871
872           If the path to the extracted file traverses a parent directory or a
873           symbolic link, the extraction will be aborted with "AC_ERROR" for
874           security reason.  Returns an error code or AZ_OK if everything
875           worked OK.
876

Archive::Zip Global Variables

878       $Archive::Zip::UNICODE
879           This variable governs how Unicode file and directory names are
880           added to or extracted from an archive. If set, file and directory
881           names are considered to be UTF-8 encoded. This is EXPERIMENTAL AND
882           BUGGY (there are some edge cases on Win32). Please report problems.
883
884               {
885                   local $Archive::Zip::UNICODE = 1;
886                   $zip->addFile('Déjà vu.txt');
887               }
888

MEMBER OPERATIONS

890   Member Class Methods
891       Several constructors allow you to construct members without adding them
892       to a zip archive. These work the same as the addFile(), addDirectory(),
893       and addString() zip instance methods described above, but they don't
894       add the new members to a zip.
895
896       Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName ]
897       )
898       Archive::Zip::Member->newFromString( { string => $stringOrStringRef [,
899       zipName => $fileName ] )
900           Construct a new member from the given string. Returns undef on
901           error.
902
903               my $member = Archive::Zip::Member->newFromString( 'This is a test' );
904               my $member = Archive::Zip::Member->newFromString( 'This is a test', 'test.txt' );
905               my $member = Archive::Zip::Member->newFromString( { string => 'This is a test', zipName => 'test.txt' } );
906
907       newFromFile( $fileName [, $zipName ] )
908       newFromFile( { filename => $fileName [, zipName => $zipName ] } )
909           Construct a new member from the given file. Returns undef on error.
910
911               my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
912
913       newDirectoryNamed( $directoryName [, $zipname ] )
914       newDirectoryNamed( { directoryName => $directoryName [, zipName =>
915       $zipname ] } )
916           Construct a new member from the given directory.  $directoryName
917           must be a valid name on your file system; it does not have to
918           exist.
919
920           If given, $zipname will be the name of the zip member; it must be a
921           valid Zip (Unix) name. If not given, it will be converted from
922           $directoryName.
923
924           Returns undef on error.
925
926               my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
927
928   Member Simple Accessors
929       These methods get (and/or set) member attribute values.
930
931       The zip64 format requires parts of the member data to be stored in the
932       so-called extra fields.  You cannot get nor set this zip64 data through
933       the extra field accessors described in this section.  In fact, the low-
934       level member methods ensure that the zip64 data in the extra fields is
935       handled completely transparently and invisibly to the user when members
936       are read or written.
937
938       zip64()
939           Returns whether the previous read or write of the member has been
940           done in zip64 format.
941
942       desiredZip64Mode()
943           Gets or sets whether the member's headers should be written in
944           zip64 format: As needed (ZIP64_AS_NEEDED), the default, or always
945           (ZIP64_HEADERS).
946
947       versionMadeBy()
948           Gets the field from the member header.
949
950       fileAttributeFormat( [ $format ] )
951       fileAttributeFormat( [ { format => $format ] } )
952           Gets or sets the field from the member header. These are "FA_*"
953           values.
954
955       versionNeededToExtract()
956           Gets the field from the member header.
957
958       bitFlag()
959           Gets the general purpose bit field from the member header.  This is
960           where the "GPBF_*" bits live.
961
962       compressionMethod()
963           Returns the member compression method. This is the method that is
964           currently being used to compress the member data.  This will be
965           COMPRESSION_STORED for added string or file members, or any of the
966           "COMPRESSION_*" values for members from a zip file. However, this
967           module can only handle members whose data is in COMPRESSION_STORED
968           or COMPRESSION_DEFLATED format.
969
970       desiredCompressionMethod( [ $method ] )
971       desiredCompressionMethod( [ { compressionMethod => $method } ] )
972           Get or set the member's "desiredCompressionMethod". This is the
973           compression method that will be used when the member is written.
974           Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED
975           or COMPRESSION_STORED are valid arguments. Changing to
976           COMPRESSION_STORED will change the member desiredCompressionLevel
977           to 0; changing to COMPRESSION_DEFLATED will change the member
978           desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
979
980       desiredCompressionLevel( [ $level ] )
981       desiredCompressionLevel( [ { compressionLevel => $level } ] )
982           Get or set the member's desiredCompressionLevel This is the method
983           that will be used to write. Returns prior desiredCompressionLevel.
984           Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE,
985           COMPRESSION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and
986           COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change
987           the desiredCompressionMethod to COMPRESSION_STORED.  All other
988           arguments will change the desiredCompressionMethod to
989           COMPRESSION_DEFLATED.
990
991       externalFileName()
992           Return the member's external file name, if any, or undef.
993
994       fileName()
995           Get or set the member's internal filename. Returns the (possibly
996           new) filename. Names will have backslashes converted to forward
997           slashes, and will have multiple consecutive slashes converted to
998           single ones.
999
1000       lastModFileDateTime()
1001           Return the member's last modification date/time stamp in MS-DOS
1002           format.
1003
1004       lastModTime()
1005           Return the member's last modification date/time stamp, converted to
1006           unix localtime format.
1007
1008               print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
1009
1010       setLastModFileDateTimeFromUnix()
1011           Set the member's lastModFileDateTime from the given unix time.
1012
1013               $member->setLastModFileDateTimeFromUnix( time() );
1014
1015       internalFileAttributes()
1016           Return the internal file attributes field from the zip header. This
1017           is only set for members read from a zip file.
1018
1019       externalFileAttributes()
1020           Return member attributes as read from the ZIP file. Note that these
1021           are NOT UNIX!
1022
1023       unixFileAttributes( [ $newAttributes ] )
1024       unixFileAttributes( [ { attributes => $newAttributes } ] )
1025           Get or set the member's file attributes using UNIX file attributes.
1026           Returns old attributes.
1027
1028               my $oldAttribs = $member->unixFileAttributes( 0666 );
1029
1030           Note that the return value has more than just the file permissions,
1031           so you will have to mask off the lowest bits for comparisons.
1032
1033       localExtraField( [ $newField ] )
1034       localExtraField( [ { field => $newField } ] )
1035           Gets or sets the extra field that was read from the local header.
1036           The extra field must be in the proper format.  If it is not or if
1037           the new field contains data related to the zip64 format, this
1038           method does not modify the extra field and returns AZ_FORMAT_ERROR,
1039           otherwise it returns AZ_OK.
1040
1041       cdExtraField( [ $newField ] )
1042       cdExtraField( [ { field => $newField } ] )
1043           Gets or sets the extra field that was read from the central
1044           directory header. The extra field must be in the proper format.  If
1045           it is not or if the new field contains data related to the zip64
1046           format, this method does not modify the extra field and returns
1047           AZ_FORMAT_ERROR, otherwise it returns AZ_OK.
1048
1049       extraFields()
1050           Return both local and CD extra fields, concatenated.
1051
1052       fileComment( [ $newComment ] )
1053       fileComment( [ { comment => $newComment } ] )
1054           Get or set the member's file comment.
1055
1056       hasDataDescriptor()
1057           Get or set the data descriptor flag. If this is set, the local
1058           header will not necessarily have the correct data sizes. Instead, a
1059           small structure will be stored at the end of the member data with
1060           these values. This should be transparent in normal operation.
1061
1062       crc32()
1063           Return the CRC-32 value for this member. This will not be set for
1064           members that were constructed from strings or external files until
1065           after the member has been written.
1066
1067       crc32String()
1068           Return the CRC-32 value for this member as an 8 character printable
1069           hex string. This will not be set for members that were constructed
1070           from strings or external files until after the member has been
1071           written.
1072
1073       compressedSize()
1074           Return the compressed size for this member. This will not be set
1075           for members that were constructed from strings or external files
1076           until after the member has been written.
1077
1078       uncompressedSize()
1079           Return the uncompressed size for this member.
1080
1081       password( [ $password ] )
1082           Returns the password for this member to be used on decryption.  If
1083           $password is given, it will set the password for the decryption.
1084
1085       isEncrypted()
1086           Return true if this member is encrypted. The Archive::Zip module
1087           does not currently support creation of encrypted members.
1088           Decryption works more or less like this:
1089
1090             my $zip = Archive::Zip->new;
1091             $zip->read ("encrypted.zip");
1092             for my $m (map { $zip->memberNamed ($_) } $zip->memberNames) {
1093                 $m->password ("secret");
1094                 $m->contents;  # is "" when password was wrong
1095
1096           That shows that the password has to be set per member, and not per
1097           archive. This might change in the future.
1098
1099       isTextFile( [ $flag ] )
1100       isTextFile( [ { flag => $flag } ] )
1101           Returns true if I am a text file. Also can set the status if given
1102           an argument (then returns old state). Note that this module does
1103           not currently do anything with this flag upon extraction or
1104           storage. That is, bytes are stored in native format whether or not
1105           they came from a text file.
1106
1107       isBinaryFile()
1108           Returns true if I am a binary file. Also can set the status if
1109           given an argument (then returns old state). Note that this module
1110           does not currently do anything with this flag upon extraction or
1111           storage. That is, bytes are stored in native format whether or not
1112           they came from a text file.
1113
1114       extractToFileNamed( $fileName )
1115       extractToFileNamed( { name => $fileName } )
1116           Extract me to a file with the given name. The file will be created
1117           with default modes. Directories will be created as needed.  The
1118           $fileName argument should be a valid file name on your file system.
1119           Returns AZ_OK on success.
1120
1121       isDirectory()
1122           Returns true if I am a directory.
1123
1124       isSymbolicLink()
1125           Returns true if I am a symbolic link.
1126
1127       writeLocalHeaderRelativeOffset()
1128           Returns the file offset in bytes the last time I was written.
1129
1130       wasWritten()
1131           Returns true if I was successfully written. Reset at the beginning
1132           of a write attempt.
1133
1134   Low-level member data reading
1135       It is possible to use lower-level routines to access member data
1136       streams, rather than the extract* methods and contents(). For instance,
1137       here is how to print the uncompressed contents of a member in chunks
1138       using these methods:
1139
1140           my ( $member, $status, $bufferRef );
1141           $member = $zip->memberNamed( 'xyz.txt' );
1142           $member->desiredCompressionMethod( COMPRESSION_STORED );
1143           $status = $member->rewindData();
1144           die "error $status" unless $status == AZ_OK;
1145           while ( ! $member->readIsDone() )
1146           {
1147           ( $bufferRef, $status ) = $member->readChunk();
1148           die "error $status"
1149                       if $status != AZ_OK && $status != AZ_STREAM_END;
1150           # do something with $bufferRef:
1151           print $$bufferRef;
1152           }
1153           $member->endRead();
1154
1155       readChunk( [ $chunkSize ] )
1156       readChunk( [ { chunkSize => $chunkSize } ] )
1157           This reads the next chunk of given size from the member's data
1158           stream and compresses or uncompresses it as necessary, returning a
1159           reference to the bytes read and a status. If size argument is not
1160           given, defaults to global set by Archive::Zip::setChunkSize. Status
1161           is AZ_OK on success until the last chunk, where it returns
1162           AZ_STREAM_END. Returns "( \$bytes, $status)".
1163
1164               my ( $outRef, $status ) = $self->readChunk();
1165               print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1166
1167       rewindData()
1168           Rewind data and set up for reading data streams or writing zip
1169           files. Can take options for inflateInit() or deflateInit(), but
1170           this is not likely to be necessary.  Subclass overrides should call
1171           this method. Returns "AZ_OK" on success.
1172
1173       endRead()
1174           Reset the read variables and free the inflater or deflater.  Must
1175           be called to close files, etc. Returns AZ_OK on success.
1176
1177       readIsDone()
1178           Return true if the read has run out of data or encountered an
1179           error.
1180
1181       contents()
1182           Return the entire uncompressed member data or undef in scalar
1183           context. When called in array context, returns "( $string, $status
1184           )"; status will be AZ_OK on success:
1185
1186               my $string = $member->contents();
1187               # or
1188               my ( $string, $status ) = $member->contents();
1189               die "error $status" unless $status == AZ_OK;
1190
1191           Can also be used to set the contents of a member (this may change
1192           the class of the member):
1193
1194               $member->contents( "this is my new contents" );
1195
1196       extractToFileHandle( $fh )
1197       extractToFileHandle( { fileHandle => $fh } )
1198           Extract (and uncompress, if necessary) the member's contents to the
1199           given file handle. Return AZ_OK on success.
1200
1201           For members representing symbolic links, pass the name of the
1202           symbolic link as file handle. Ensure that all directories in the
1203           path to the symbolic link already exist.
1204

Archive::Zip::FileMember methods

1206       The Archive::Zip::FileMember class extends Archive::Zip::Member. It is
1207       the base class for both ZipFileMember and NewFileMember classes. This
1208       class adds an "externalFileName" and an "fh" member to keep track of
1209       the external file.
1210
1211       externalFileName()
1212           Return the member's external filename.
1213
1214       fh()
1215           Return the member's read file handle. Automatically opens file if
1216           necessary.
1217

Archive::Zip::ZipFileMember methods

1219       The Archive::Zip::ZipFileMember class represents members that have been
1220       read from external zip files.
1221
1222       diskNumberStart()
1223           Returns the disk number that the member's local header resides in.
1224           Should be 0.
1225
1226       localHeaderRelativeOffset()
1227           Returns the offset into the zip file where the member's local
1228           header is.
1229
1230       dataOffset()
1231           Returns the offset from the beginning of the zip file to the
1232           member's data.
1233

REQUIRED MODULES

1235       Archive::Zip requires several other modules:
1236
1237       Carp
1238
1239       Compress::Raw::Zlib
1240
1241       Cwd
1242
1243       File::Basename
1244
1245       File::Copy
1246
1247       File::Find
1248
1249       File::Path
1250
1251       File::Spec
1252
1253       IO::File
1254
1255       IO::Seekable
1256
1257       Time::Local
1258

BUGS AND CAVEATS

1260   When not to use Archive::Zip
1261       If you are just going to be extracting zips (and/or other archives) you
1262       are recommended to look at using Archive::Extract instead, as it is
1263       much easier to use and factors out archive-specific functionality.
1264
1265   Zip64 Format Support
1266       Since version 1.66 Archive::Zip supports the so-called zip64 format,
1267       which overcomes various limitations in the original zip file format.
1268       On some Perl interpreters, however, even version 1.66 and newer of
1269       Archive::Zip cannot support the zip64 format.  Among these are all Perl
1270       interpreters that lack 64-bit support and those older than version
1271       5.10.0.
1272
1273       Constant "ZIP64_SUPPORTED", exported with tag :CONSTANTS, equals true
1274       if Archive::Zip on the current Perl interpreter supports the zip64
1275       format.  If it does not and you try to read or write an archive in
1276       zip64 format, anyway, Archive::Zip returns an error "AZ_ERROR" and
1277       reports an error message along the lines of "zip64 format not supported
1278       on this Perl interpreter".
1279
1280   "versionMadeBy" and "versionNeededToExtract"
1281       The zip64 format and the zip file format in general specify what values
1282       to use for the "versionMadeBy" and "versionNeededToExtract" fields in
1283       the local file header, central directory file header, and zip64 EOCD
1284       record.  In practice however, these fields seem to be more or less
1285       randomly used by various archiver implementations.
1286
1287       To achieve a compromise between backward compatibility and (whatever)
1288       standard compliance, Archive::Zip handles them as follows:
1289
1290       •   For field "versionMadeBy", Archive::Zip uses default value 20 (45
1291           for the zip64 EOCD record) or any previously read value. It never
1292           changes that value when writing a header, even if it is written in
1293           zip64 format, or when writing the zip64 EOCD record.
1294
1295       •   Likewise for field "versionNeededToExtract", but here Archive::Zip
1296           forces a minimum value of 45 when writing a header in zip64 format
1297           or the zip64 EOCD record.
1298
1299       •   Finally, Archive::Zip never depends on the values of these fields
1300           in any way when reading an archive from a file or file handle.
1301
1302   Try to avoid IO::Scalar
1303       One of the most common ways to use Archive::Zip is to generate Zip
1304       files in-memory. Most people use IO::Scalar for this purpose.
1305
1306       Unfortunately, as of 1.11 this module no longer works with IO::Scalar
1307       as it incorrectly implements seeking.
1308
1309       Anybody using IO::Scalar should consider porting to IO::String, which
1310       is smaller, lighter, and is implemented to be perfectly compatible with
1311       regular seekable filehandles.
1312
1313       Support for IO::Scalar most likely will not be restored in the future,
1314       as IO::Scalar itself cannot change the way it is implemented due to
1315       back-compatibility issues.
1316
1317   Wrong password for encrypted members
1318       When an encrypted member is read using the wrong password, you
1319       currently have to re-read the entire archive to try again with the
1320       correct password.
1321

TO DO

1323       * auto-choosing storing vs compression
1324
1325       * extra field hooks (see notes.txt)
1326
1327       * check for duplicates on addition/renaming?
1328
1329       * Text file extraction (line end translation)
1330
1331       * Reading zip files from non-seekable inputs
1332         (Perhaps by proxying through IO::String?)
1333
1334       * separate unused constants into separate module
1335
1336       * cookbook style docs
1337
1338       * Handle tainted paths correctly
1339
1340       * Work on better compatibility with other IO:: modules
1341
1342       * Support encryption
1343
1344       * More user-friendly decryption
1345

SUPPORT

1347       Bugs should be reported on GitHub
1348
1349       <https://github.com/redhotpenguin/perl-Archive-Zip/issues>
1350
1351       For other issues contact the maintainer.
1352

AUTHOR

1354       Currently maintained by Fred Moyer <fred@redhotpenguin.com>
1355
1356       Previously maintained by Adam Kennedy <adamk@cpan.org>
1357
1358       Previously maintained by Steve Peters <steve@fisharerojo.org>.
1359
1360       File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>.
1361
1362       Originally by Ned Konz <nedkonz@cpan.org>.
1363
1365       Some parts copyright 2006 - 2012 Adam Kennedy.
1366
1367       Some parts copyright 2005 Steve Peters.
1368
1369       Original work copyright 2000 - 2004 Ned Konz.
1370
1371       This program is free software; you can redistribute it and/or modify it
1372       under the same terms as Perl itself.
1373

SEE ALSO

1375       Look at Archive::Zip::MemberRead which is a wrapper that allows one to
1376       read Zip archive members as if they were files.
1377
1378       Compress::Raw::Zlib, Archive::Tar, Archive::Extract
1379
1380
1381
1382perl v5.38.0                      2023-07-20                   Archive::Zip(3)
Impressum