1Archive::Zip(3) User Contributed Perl Documentation Archive::Zip(3)
2
6 Archive::Zip - Provide an interface to ZIP archive files.
7
9 # Create a Zip file
10 use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
11 my $zip = Archive::Zip->new();
12 # Add a directory
14 my $dir_member = $zip->addDirectory( 'dirname/' );
15 # 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 # Add a file from disk
21 my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
22 # Save the Zip file
24 unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {
25 die 'write error';
26 }
27 # Read a Zip file
29 my $somezip = Archive::Zip->new();
30 unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {
31 die 'read error';
32 }
33 # 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
42 The Archive::Zip module allows a Perl program to create, manipulate,
43 read, and write Zip archive files.
44 Zip archives can be created, or you can read from existing zip files.
46 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 Members can be created from members in existing Zip files, or from
54 existing directories, files, or strings.
55 This module uses the Compress::Raw::Zlib library to read and write the
57 compressed streams inside the files.
58 One can use Archive::Zip::MemberRead to read the zip file archive
60 members as if they were files.
61 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 "Archive::Zip" tries to be consistent with file naming conventions, and
68 will translate back and forth between native and Zip file names.
69 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 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 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
81 that can take one or two names will convert from local to zip names
82 if you call them with a single name.
83 Archive::Zip Object Model
85 Overview
86 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 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
109 :CONSTANTS
110 Exports the following constants:
111 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
118 :MISC_CONSTANTS
120 Exports the following constants (only necessary for extending the
121 module):
122 FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS FA_MACINTOSH
124 FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
125 GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
126 GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
127 GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
128 DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
129 DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
130 COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
131 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
132 COMPRESSION_DEFLATED_ENHANCED
133 COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
134 :ERROR_CODES
136 Explained below. Returned from most methods.
137 AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
139
141 Many of the methods in Archive::Zip return error codes. These are
142 implemented as inline subroutines, using the "use constant" pragma.
143 They can be imported into your namespace using the ":ERROR_CODES" tag:
144 use Archive::Zip qw( :ERROR_CODES );
146 ...
148 unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {
150 die "whoops!";
151 }
152 AZ_OK (0)
154 Everything is fine.
155 AZ_STREAM_END (1)
157 The read stream (or central directory) ended normally.
158 AZ_ERROR (2)
160 There was some generic kind of error.
161 AZ_FORMAT_ERROR (3)
163 There is a format error in a ZIP file being read.
164 AZ_IO_ERROR (4)
166 There was an IO error.
167 Compression
169 Archive::Zip allows each member of a ZIP file to be compressed (using
170 the Deflate algorithm) or uncompressed.
171 Other compression algorithms that some versions of ZIP have been able
173 to produce are not supported. Each member has two compression methods:
174 the one it's stored as (this is always COMPRESSION_STORED for string
175 and external file members), and the one you desire for the member in
176 the zip file.
177 These can be different, of course, so you can make a zip member that is
179 not compressed out of one that is, and vice versa.
180 You can inquire about the current compression and set the desired
182 compression method:
183 my $member = $zip->memberNamed( 'xyz.txt' );
185 $member->compressionMethod(); # return current compression
186 # set to read uncompressed
188 $member->desiredCompressionMethod( COMPRESSION_STORED );
189 # set to read compressed
191 $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
192 There are two different compression methods:
194 COMPRESSION_STORED
196 File is stored (no compression)
197 COMPRESSION_DEFLATED
199 File is Deflated
200 Compression Levels
202 If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can
203 choose different compression levels. This choice may affect the speed
204 of compression and decompression, as well as the size of the compressed
205 member data.
206 $member->desiredCompressionLevel( 9 );
208 The levels given can be:
210 · 0 or COMPRESSION_LEVEL_NONE
212 This is the same as saying
214 $member->desiredCompressionMethod( COMPRESSION_STORED );
216 · 1 .. 9
218 1 gives the best speed and worst compression, and 9 gives the best
220 compression and worst speed.
221 · COMPRESSION_LEVEL_FASTEST
223 This is a synonym for level 1.
225 · COMPRESSION_LEVEL_BEST_COMPRESSION
227 This is a synonym for level 9.
229 · COMPRESSION_LEVEL_DEFAULT
231 This gives a good compromise between speed and compression, and is
233 currently equivalent to 6 (this is in the zlib code). This is the
234 level that will be used if not specified.
235
237 The Archive::Zip class (and its invisible subclass
238 Archive::Zip::Archive) implement generic zip file functionality.
239 Creating a new Archive::Zip object actually makes an
240 Archive::Zip::Archive object, but you don't have to worry about this
241 unless you're subclassing.
242 Constructor
244 new( [$fileName] )
245 new( { filename => $fileName } )
246 Make a new, empty zip archive.
247 my $zip = Archive::Zip->new();
249 If an additional argument is passed, new() will call read() to read
251 the contents of an archive:
252 my $zip = Archive::Zip->new( 'xyz.zip' );
254 If a filename argument is passed and the read fails for any reason,
256 new will return undef. For this reason, it may be better to call
257 read separately.
258 Zip Archive Utility Methods
260 These Archive::Zip methods may be called as functions or as object
261 methods. Do not call them as class methods:
262 $zip = Archive::Zip->new();
264 $crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK
265 $crc = $zip->computeCRC32( 'ghijkl' ); # also OK
266 $crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK
267 Archive::Zip::computeCRC32( $string [, $crc] )
269 Archive::Zip::computeCRC32( { string => $string [, checksum => $crc ] }
270 )
271 This is a utility function that uses the Compress::Raw::Zlib CRC
272 routine to compute a CRC-32. You can get the CRC of a string:
273 $crc = Archive::Zip::computeCRC32( $string );
275 Or you can compute the running CRC:
277 $crc = 0;
279 $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
280 $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
281 Archive::Zip::setChunkSize( $number )
283 Archive::Zip::setChunkSize( { chunkSize => $number } )
284 Report or change chunk size used for reading and writing. This can
285 make big differences in dealing with large files. Currently, this
286 defaults to 32K. This also changes the chunk size used for
287 Compress::Raw::Zlib. You must call setChunkSize() before reading or
288 writing. This is not exportable, so you must call it like:
289 Archive::Zip::setChunkSize( 4096 );
291 or as a method on a zip (though this is a global setting). Returns
293 old chunk size.
294 Archive::Zip::chunkSize()
296 Returns the current chunk size:
297 my $chunkSize = Archive::Zip::chunkSize();
299 Archive::Zip::setErrorHandler( \&subroutine )
301 Archive::Zip::setErrorHandler( { subroutine => \&subroutine } )
302 Change the subroutine called with error strings. This defaults to
303 \&Carp::carp, but you may want to change it to get the error
304 strings. This is not exportable, so you must call it like:
305 Archive::Zip::setErrorHandler( \&myErrorHandler );
307 If myErrorHandler is undef, resets handler to default. Returns old
309 error handler. Note that if you call Carp::carp or a similar
310 routine or if you're chaining to the default error handler from
311 your error handler, you may want to increment the number of caller
312 levels that are skipped (do not just set it to a number):
313 $Carp::CarpLevel++;
315 Archive::Zip::tempFile( [ $tmpdir ] )
317 Archive::Zip::tempFile( { tempDir => $tmpdir } )
318 Create a uniquely named temp file. It will be returned open for
319 read/write. If $tmpdir is given, it is used as the name of a
320 directory to create the file in. If not given, creates the file
321 using "File::Spec::tmpdir()". Generally, you can override this
322 choice using the
323 $ENV{TMPDIR}
325 environment variable. But see the File::Spec documentation for your
327 system. Note that on many systems, if you're running in taint mode,
328 then you must make sure that $ENV{TMPDIR} is untainted for it to be
329 used. Will NOT create $tmpdir if it does not exist (this is a
330 change from prior versions!). Returns file handle and name:
331 my ($fh, $name) = Archive::Zip::tempFile();
333 my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
334 my $fh = Archive::Zip::tempFile(); # if you don't need the name
335 Zip Archive Accessors
337 members()
338 Return a copy of the members array
339 my @members = $zip->members();
341 numberOfMembers()
343 Return the number of members I have
344 memberNames()
346 Return a list of the (internal) file names of the zip members
347 memberNamed( $string )
349 memberNamed( { zipName => $string } )
350 Return ref to member whose filename equals given filename or undef.
351 $string must be in Zip (Unix) filename format.
352 membersMatching( $regex )
354 membersMatching( { regex => $regex } )
355 Return array of members whose filenames match given regular
356 expression in list context. Returns number of matching members in
357 scalar context.
358 my @textFileMembers = $zip->membersMatching( '.*\.txt' );
360 # or
361 my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
362 diskNumber()
364 Return the disk that I start on. Not used for writing zips, but
365 might be interesting if you read a zip in. This should be 0, as
366 Archive::Zip does not handle multi-volume archives.
367 diskNumberWithStartOfCentralDirectory()
369 Return the disk number that holds the beginning of the central
370 directory. Not used for writing zips, but might be interesting if
371 you read a zip in. This should be 0, as Archive::Zip does not
372 handle multi-volume archives.
373 numberOfCentralDirectoriesOnThisDisk()
375 Return the number of CD structures in the zipfile last read in.
376 Not used for writing zips, but might be interesting if you read a
377 zip in.
378 numberOfCentralDirectories()
380 Return the number of CD structures in the zipfile last read in.
381 Not used for writing zips, but might be interesting if you read a
382 zip in.
383 centralDirectorySize()
385 Returns central directory size, as read from an external zip file.
386 Not used for writing zips, but might be interesting if you read a
387 zip in.
388 centralDirectoryOffsetWRTStartingDiskNumber()
390 Returns the offset into the zip file where the CD begins. Not used
391 for writing zips, but might be interesting if you read a zip in.
392 zipfileComment( [ $string ] )
394 zipfileComment( [ { comment => $string } ] )
395 Get or set the zipfile comment. Returns the old comment.
396 print $zip->zipfileComment();
398 $zip->zipfileComment( 'New Comment' );
399 eocdOffset()
401 Returns the (unexpected) number of bytes between where the EOCD was
402 found and where it expected to be. This is normally 0, but would be
403 positive if something (a virus, perhaps) had added bytes somewhere
404 before the EOCD. Not used for writing zips, but might be
405 interesting if you read a zip in. Here is an example of how you can
406 diagnose this:
407 my $zip = Archive::Zip->new('somefile.zip');
409 if ($zip->eocdOffset())
410 {
411 warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
412 }
413 The "eocdOffset()" is used to adjust the starting position of
415 member headers, if necessary.
416 fileName()
418 Returns the name of the file last read from. If nothing has been
419 read yet, returns an empty string; if read from a file handle,
420 returns the handle in string form.
421 Zip Archive Member Operations
423 Various operations on a zip file modify members. When a member is
424 passed as an argument, you can either use a reference to the member
425 itself, or the name of a member. Of course, using the name requires
426 that names be unique within a zip (this is not enforced).
427 removeMember( $memberOrName )
429 removeMember( { memberOrZipName => $memberOrName } )
430 Remove and return the given member, or match its name and remove
431 it. Returns undef if member or name does not exist in this Zip. No-
432 op if member does not belong to this zip.
433 replaceMember( $memberOrName, $newMember )
435 replaceMember( { memberOrZipName => $memberOrName, newMember =>
436 $newMember } )
437 Remove and return the given member, or match its name and remove
438 it. Replace with new member. Returns undef if member or name does
439 not exist in this Zip, or if $newMember is undefined.
440 It is an (undiagnosed) error to provide a $newMember that is a
442 member of the zip being modified.
443 my $member1 = $zip->removeMember( 'xyz' );
445 my $member2 = $zip->replaceMember( 'abc', $member1 );
446 # now, $member2 (named 'abc') is not in $zip,
447 # and $member1 (named 'xyz') is, having taken $member2's place.
448 extractMember( $memberOrName [, $extractedName ] )
450 extractMember( { memberOrZipName => $memberOrName [, name =>
451 $extractedName ] } )
452 Extract the given member, or match its name and extract it.
453 Returns undef if member does not exist in this Zip. If optional
454 second arg is given, use it as the name of the extracted member.
455 Otherwise, the internal filename of the member is used as the name
456 of the extracted file or directory. If you pass $extractedName, it
457 should be in the local file system's format. If you do not pass
458 $extractedName and the internal filename traverses a parent
459 directory or a symbolic link, the extraction will be aborted with
460 "AC_ERROR" for security reason. All necessary directories will be
461 created. Returns "AZ_OK" on success.
462 extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
464 extractMemberWithoutPaths( { memberOrZipName => $memberOrName [, name
465 => $extractedName ] } )
466 Extract the given member, or match its name and extract it. Does
467 not use path information (extracts into the current directory).
468 Returns undef if member does not exist in this Zip. If optional
469 second arg is given, use it as the name of the extracted member
470 (its paths will be deleted too). Otherwise, the internal filename
471 of the member (minus paths) is used as the name of the extracted
472 file or directory. Returns "AZ_OK" on success. If you do not pass
473 $extractedName and the internal filename is equalled to a local
474 symbolic link, the extraction will be aborted with "AC_ERROR" for
475 security reason.
476 addMember( $member )
478 addMember( { member => $member } )
479 Append a member (possibly from another zip file) to the zip file.
480 Returns the new member. Generally, you will use addFile(),
481 addDirectory(), addFileOrDirectory(), addString(), or read() to add
482 members.
483 # Move member named 'abc' to end of zip:
485 my $member = $zip->removeMember( 'abc' );
486 $zip->addMember( $member );
487 updateMember( $memberOrName, $fileName )
489 updateMember( { memberOrZipName => $memberOrName, name => $fileName } )
490 Update a single member from the file or directory named $fileName.
491 Returns the (possibly added or updated) member, if any; "undef" on
492 errors. The comparison is based on "lastModTime()" and (in the
493 case of a non-directory) the size of the file.
494 addFile( $fileName [, $newName, $compressionLevel ] )
496 addFile( { filename => $fileName [, zipName => $newName,
497 compressionLevel => $compressionLevel } ] )
498 Append a member whose data comes from an external file, returning
499 the member or undef. The member will have its file name set to the
500 name of the external file, and its desiredCompressionMethod set to
501 COMPRESSION_DEFLATED. The file attributes and last modification
502 time will be set from the file. If the name given does not
503 represent a readable plain file or symbolic link, undef will be
504 returned. $fileName must be in the format required for the local
505 file system. The optional $newName argument sets the internal file
506 name to something different than the given $fileName. $newName, if
507 given, must be in Zip name format (i.e. Unix). The text mode bit
508 will be set if the contents appears to be text (as returned by the
509 "-T" perl operator).
510 NOTE that you should not (generally) use absolute path names in zip
512 member names, as this will cause problems with some zip tools as
513 well as introduce a security hole and make the zip harder to use.
514 addDirectory( $directoryName [, $fileName ] )
516 addDirectory( { directoryName => $directoryName [, zipName => $fileName
517 ] } )
518 Append a member created from the given directory name. The
519 directory name does not have to name an existing directory. If the
520 named directory exists, the file modification time and permissions
521 are set from the existing directory, otherwise they are set to now
522 and permissive default permissions. $directoryName must be in
523 local file system format. The optional second argument sets the
524 name of the archive member (which defaults to $directoryName). If
525 given, it must be in Zip (Unix) format. Returns the new member.
526 addFileOrDirectory( $name [, $newName, $compressionLevel ] )
528 addFileOrDirectory( { name => $name [, zipName => $newName,
529 compressionLevel => $compressionLevel ] } )
530 Append a member from the file or directory named $name. If $newName
531 is given, use it for the name of the new member. Will add or
532 remove trailing slashes from $newName as needed. $name must be in
533 local file system format. The optional second argument sets the
534 name of the archive member (which defaults to $name). If given, it
535 must be in Zip (Unix) format.
536 addString( $stringOrStringRef, $name, [$compressionLevel] )
538 addString( { string => $stringOrStringRef [, zipName => $name,
539 compressionLevel => $compressionLevel ] } )
540 Append a member created from the given string or string reference.
541 The name is given by the second argument. Returns the new member.
542 The last modification time will be set to now, and the file
543 attributes will be set to permissive defaults.
544 my $member = $zip->addString( 'This is a test', 'test.txt' );
546 contents( $memberOrMemberName [, $newContents ] )
548 contents( { memberOrZipName => $memberOrMemberName [, contents =>
549 $newContents ] } )
550 Returns the uncompressed data for a particular member, or undef.
551 print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
553 Also can change the contents of a member:
555 $zip->contents( 'xyz.txt', 'This is the new contents' );
557 If called expecting an array as the return value, it will include
559 the status as the second value in the array.
560 ($content, $status) = $zip->contents( 'xyz.txt');
562 Zip Archive I/O operations
564 A Zip archive can be written to a file or file handle, or read from
565 one.
566 writeToFileNamed( $fileName )
568 writeToFileNamed( { fileName => $fileName } )
569 Write a zip archive to named file. Returns "AZ_OK" on success.
570 my $status = $zip->writeToFileNamed( 'xx.zip' );
572 die "error somewhere" if $status != AZ_OK;
573 Note that if you use the same name as an existing zip file that you
575 read in, you will clobber ZipFileMembers. So instead, write to a
576 different file name, then delete the original. If you use the
577 "overwrite()" or "overwriteAs()" methods, you can re-write the
578 original zip in this way. $fileName should be a valid file name on
579 your system.
580 writeToFileHandle( $fileHandle [, $seekable] )
582 Write a zip archive to a file handle. Return AZ_OK on success. The
583 optional second arg tells whether or not to try to seek backwards
584 to re-write headers. If not provided, it is set if the Perl "-f"
585 test returns true. This could fail on some operating systems,
586 though.
587 my $fh = IO::File->new( 'someFile.zip', 'w' );
589 unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {
590 # error handling
591 }
592 If you pass a file handle that is not seekable (like if you're
594 writing to a pipe or a socket), pass a false second argument:
595 my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
597 $zip->writeToFileHandle( $fh, 0 ); # fh is not seekable
598 If this method fails during the write of a member, that member and
600 all following it will return false from "wasWritten()". See
601 writeCentralDirectory() for a way to deal with this. If you want,
602 you can write data to the file handle before passing it to
603 writeToFileHandle(); this could be used (for instance) for making
604 self-extracting archives. However, this only works reliably when
605 writing to a real file (as opposed to STDOUT or some other possible
606 non-file).
607 See examples/selfex.pl for how to write a self-extracting archive.
609 writeCentralDirectory( $fileHandle [, $offset ] )
611 writeCentralDirectory( { fileHandle => $fileHandle [, offset => $offset
612 ] } )
613 Writes the central directory structure to the given file handle.
614 Returns AZ_OK on success. If given an $offset, will seek to that
616 point before writing. This can be used for recovery in cases where
617 writeToFileHandle or writeToFileNamed returns an IO error because
618 of running out of space on the destination file.
619 You can truncate the zip by seeking backwards and then writing the
621 directory:
622 my $fh = IO::File->new( 'someFile.zip', 'w' );
624 my $retval = $zip->writeToFileHandle( $fh );
625 if ( $retval == AZ_IO_ERROR ) {
626 my @unwritten = grep { not $_->wasWritten() } $zip->members();
627 if (@unwritten) {
628 $zip->removeMember( $member ) foreach my $member ( @unwritten );
629 $zip->writeCentralDirectory( $fh,
630 $unwritten[0]->writeLocalHeaderRelativeOffset());
631 }
632 }
633 overwriteAs( $newName )
635 overwriteAs( { filename => $newName } )
636 Write the zip to the specified file, as safely as possible. This
637 is done by first writing to a temp file, then renaming the original
638 if it exists, then renaming the temp file, then deleting the
639 renamed original if it exists. Returns AZ_OK if successful.
640 overwrite()
642 Write back to the original zip file. See overwriteAs() above. If
643 the zip was not ever read from a file, this generates an error.
644 read( $fileName )
646 read( { filename => $fileName } )
647 Read zipfile headers from a zip file, appending new members.
648 Returns "AZ_OK" or error code.
649 my $zipFile = Archive::Zip->new();
651 my $status = $zipFile->read( '/some/FileName.zip' );
652 readFromFileHandle( $fileHandle, $filename )
654 readFromFileHandle( { fileHandle => $fileHandle, filename => $filename
655 } )
656 Read zipfile headers from an already-opened file handle, appending
657 new members. Does not close the file handle. Returns "AZ_OK" or
658 error code. Note that this requires a seekable file handle; reading
659 from a stream is not yet supported, but using in-memory data is.
660 my $fh = IO::File->new( '/some/FileName.zip', 'r' );
662 my $zip1 = Archive::Zip->new();
663 my $status = $zip1->readFromFileHandle( $fh );
664 my $zip2 = Archive::Zip->new();
665 $status = $zip2->readFromFileHandle( $fh );
666 Read zip using in-memory data (recursable):
668 open my $fh, "<", "archive.zip" or die $!;
670 my $zip_data = do { local $.; <$fh> };
671 my $zip = Archive::Zip->new;
672 open my $dh, "+<", \$zip_data;
673 $zip->readFromFileHandle ($dh);
674 Zip Archive Tree operations
676 These used to be in Archive::Zip::Tree but got moved into Archive::Zip.
677 They enable operation on an entire tree of members or files. A usage
678 example:
679 use Archive::Zip;
681 my $zip = Archive::Zip->new();
682 # add all readable files and directories below . as xyz/*
684 $zip->addTree( '.', 'xyz' );
685 # add all readable plain files below /abc as def/*
687 $zip->addTree( '/abc', 'def', sub { -f && -r } );
688 # add all .c files below /tmp as stuff/*
690 $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
691 # add all .o files below /tmp as stuff/* if they aren't writable
693 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
694 # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
696 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
697 # and write them into a file
699 $zip->writeToFileNamed('xxx.zip');
700 # now extract the same files into /tmpx
702 $zip->extractTree( 'stuff', '/tmpx' );
703 $zip->addTree( $root, $dest [, $pred, $compressionLevel ] ) -- Add tree
705 of files to a zip
706 $zip->addTree( { root => $root, zipName => $dest [, select => $pred,
707 compressionLevel => $compressionLevel ] )
708 $root is the root of the tree of files and directories to be added.
709 It is a valid directory name on your system. $dest is the name for
710 the root in the zip file (undef or blank means to use relative
711 pathnames). It is a valid ZIP directory name (that is, it uses
712 forward slashes (/) for separating directory components). $pred is
713 an optional subroutine reference to select files: it is passed the
714 name of the prospective file or directory using $_, and if it
715 returns true, the file or directory will be included. The default
716 is to add all readable files and directories. For instance, using
717 my $pred = sub { /\.txt/ };
719 $zip->addTree( '.', '', $pred );
720 will add all the .txt files in and below the current directory,
722 using relative names, and making the names identical in the
723 zipfile:
724 original name zip member name
726 ./xyz xyz
727 ./a/ a/
728 ./a/b a/b
729 To translate absolute to relative pathnames, just pass them in:
731 $zip->addTree( '/c/d', 'a' );
732 original name zip member name
734 /c/d/xyz a/xyz
735 /c/d/a/ a/a/
736 /c/d/a/b a/a/b
737 Returns AZ_OK on success. Note that this will not follow symbolic
739 links to directories. Note also that this does not check for the
740 validity of filenames.
741 Note that you generally don't want to make zip archive member names
743 absolute.
744 $zip->addTreeMatching( $root, $dest, $pattern [, $pred,
746 $compressionLevel ] )
747 $zip->addTreeMatching( { root => $root, zipName => $dest, pattern =>
748 $pattern [, select => $pred, compressionLevel => $compressionLevel ] }
749 )
750 $root is the root of the tree of files and directories to be added
751 $dest is the name for the root in the zip file (undef means to use
752 relative pathnames) $pattern is a (non-anchored) regular expression
753 for filenames to match $pred is an optional subroutine reference to
754 select files: it is passed the name of the prospective file or
755 directory in $_, and if it returns true, the file or directory will
756 be included. The default is to add all readable files and
757 directories. To add all files in and below the current directory
758 whose names end in ".pl", and make them extract into a subdirectory
759 named "xyz", do this:
760 $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
762 To add all writable files in and below the directory named "/abc"
764 whose names end in ".pl", and make them extract into a subdirectory
765 named "xyz", do this:
766 $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
768 Returns AZ_OK on success. Note that this will not follow symbolic
770 links to directories.
771 $zip->updateTree( $root [, $dest , $pred , $mirror, $compressionLevel ]
773 );
774 $zip->updateTree( { root => $root [, zipName => $dest, select => $pred,
775 mirror => $mirror, compressionLevel => $compressionLevel ] } );
776 Update a zip file from a directory tree.
777 "updateTree()" takes the same arguments as "addTree()", but first
779 checks to see whether the file or directory already exists in the
780 zip file, and whether it has been changed.
781 If the fourth argument $mirror is true, then delete all my members
783 if corresponding files were not found.
784 Returns an error code or AZ_OK if all is well.
786 $zip->extractTree( [ $root, $dest, $volume } ] )
788 $zip->extractTree( [ { root => $root, zipName => $dest, volume =>
789 $volume } ] )
790 If you don't give any arguments at all, will extract all the files
791 in the zip with their original names.
792 If you supply one argument for $root, "extractTree" will extract
794 all the members whose names start with $root into the current
795 directory, stripping off $root first. $root is in Zip (Unix)
796 format. For instance,
797 $zip->extractTree( 'a' );
799 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
801 will extract:
802 a/x as ./x
804 a/b/c as ./b/c
806 If you give two arguments, "extractTree" extracts all the members
808 whose names start with $root. It will translate $root into $dest to
809 construct the destination file name. $root and $dest are in Zip
810 (Unix) format. For instance,
811 $zip->extractTree( 'a', 'd/e' );
813 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
815 will extract:
816 a/x to d/e/x
818 a/b/c to d/e/b/c and ignore ax/d/e and d/e
820 If you give three arguments, "extractTree" extracts all the members
822 whose names start with $root. It will translate $root into $dest to
823 construct the destination file name, and then it will convert to
824 local file system format, using $volume as the name of the
825 destination volume.
826 $root and $dest are in Zip (Unix) format.
828 $volume is in local file system format.
830 For instance, under Windows,
832 $zip->extractTree( 'a', 'd/e', 'f:' );
834 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
836 will extract:
837 a/x to f:d/e/x
839 a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
841 If you want absolute paths (the prior example used paths relative
843 to the current directory on the destination volume, you can specify
844 these in $dest:
845 $zip->extractTree( 'a', '/d/e', 'f:' );
847 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
849 will extract:
850 a/x to f:\d\e\x
852 a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
854 If the path to the extracted file traverses a parent directory or a
856 symbolic link, the extraction will be aborted with "AC_ERROR" for
857 security reason. Returns an error code or AZ_OK if everything
858 worked OK.
859
861 $Archive::Zip::UNICODE
862 This variable governs how Unicode file and directory names are
863 added to or extracted from an archive. If set, file and directory
864 names are considered to be UTF-8 encoded. This is EXPERIMENTAL AND
865 BUGGY (there are some edge cases on Win32). Please report problems.
866 {
868 local $Archive::Zip::UNICODE = 1;
869 $zip->addFile('Déjà vu.txt');
870 }
871
873 Member Class Methods
874 Several constructors allow you to construct members without adding them
875 to a zip archive. These work the same as the addFile(), addDirectory(),
876 and addString() zip instance methods described above, but they don't
877 add the new members to a zip.
878 Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName ]
880 )
881 Archive::Zip::Member->newFromString( { string => $stringOrStringRef [,
882 zipName => $fileName ] )
883 Construct a new member from the given string. Returns undef on
884 error.
885 my $member = Archive::Zip::Member->newFromString( 'This is a test',
887 newFromFile( $fileName [, $zipName ] )
889 newFromFile( { filename => $fileName [, zipName => $zipName ] } )
890 Construct a new member from the given file. Returns undef on error.
891 my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
893 newDirectoryNamed( $directoryName [, $zipname ] )
895 newDirectoryNamed( { directoryName => $directoryName [, zipName =>
896 $zipname ] } )
897 Construct a new member from the given directory. $directoryName
898 must be a valid name on your file system; it does not have to
899 exist.
900 If given, $zipname will be the name of the zip member; it must be a
902 valid Zip (Unix) name. If not given, it will be converted from
903 $directoryName.
904 Returns undef on error.
906 my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
908 Member Simple accessors
910 These methods get (and/or set) member attribute values.
911 versionMadeBy()
913 Gets the field from the member header.
914 fileAttributeFormat( [ $format ] )
916 fileAttributeFormat( [ { format => $format ] } )
917 Gets or sets the field from the member header. These are "FA_*"
918 values.
919 versionNeededToExtract()
921 Gets the field from the member header.
922 bitFlag()
924 Gets the general purpose bit field from the member header. This is
925 where the "GPBF_*" bits live.
926 compressionMethod()
928 Returns the member compression method. This is the method that is
929 currently being used to compress the member data. This will be
930 COMPRESSION_STORED for added string or file members, or any of the
931 "COMPRESSION_*" values for members from a zip file. However, this
932 module can only handle members whose data is in COMPRESSION_STORED
933 or COMPRESSION_DEFLATED format.
934 desiredCompressionMethod( [ $method ] )
936 desiredCompressionMethod( [ { compressionMethod => $method } ] )
937 Get or set the member's "desiredCompressionMethod". This is the
938 compression method that will be used when the member is written.
939 Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED
940 or COMPRESSION_STORED are valid arguments. Changing to
941 COMPRESSION_STORED will change the member desiredCompressionLevel
942 to 0; changing to COMPRESSION_DEFLATED will change the member
943 desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
944 desiredCompressionLevel( [ $level ] )
946 desiredCompressionLevel( [ { compressionLevel => $level } ] )
947 Get or set the member's desiredCompressionLevel This is the method
948 that will be used to write. Returns prior desiredCompressionLevel.
949 Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE,
950 COMPRESSION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and
951 COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change
952 the desiredCompressionMethod to COMPRESSION_STORED. All other
953 arguments will change the desiredCompressionMethod to
954 COMPRESSION_DEFLATED.
955 externalFileName()
957 Return the member's external file name, if any, or undef.
958 fileName()
960 Get or set the member's internal filename. Returns the (possibly
961 new) filename. Names will have backslashes converted to forward
962 slashes, and will have multiple consecutive slashes converted to
963 single ones.
964 lastModFileDateTime()
966 Return the member's last modification date/time stamp in MS-DOS
967 format.
968 lastModTime()
970 Return the member's last modification date/time stamp, converted to
971 unix localtime format.
972 print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
974 setLastModFileDateTimeFromUnix()
976 Set the member's lastModFileDateTime from the given unix time.
977 $member->setLastModFileDateTimeFromUnix( time() );
979 internalFileAttributes()
981 Return the internal file attributes field from the zip header. This
982 is only set for members read from a zip file.
983 externalFileAttributes()
985 Return member attributes as read from the ZIP file. Note that these
986 are NOT UNIX!
987 unixFileAttributes( [ $newAttributes ] )
989 unixFileAttributes( [ { attributes => $newAttributes } ] )
990 Get or set the member's file attributes using UNIX file attributes.
991 Returns old attributes.
992 my $oldAttribs = $member->unixFileAttributes( 0666 );
994 Note that the return value has more than just the file permissions,
996 so you will have to mask off the lowest bits for comparisons.
997 localExtraField( [ $newField ] )
999 localExtraField( [ { field => $newField } ] )
1000 Gets or sets the extra field that was read from the local header.
1001 This is not set for a member from a zip file until after the member
1002 has been written out. The extra field must be in the proper format.
1003 cdExtraField( [ $newField ] )
1005 cdExtraField( [ { field => $newField } ] )
1006 Gets or sets the extra field that was read from the central
1007 directory header. The extra field must be in the proper format.
1008 extraFields()
1010 Return both local and CD extra fields, concatenated.
1011 fileComment( [ $newComment ] )
1013 fileComment( [ { comment => $newComment } ] )
1014 Get or set the member's file comment.
1015 hasDataDescriptor()
1017 Get or set the data descriptor flag. If this is set, the local
1018 header will not necessarily have the correct data sizes. Instead, a
1019 small structure will be stored at the end of the member data with
1020 these values. This should be transparent in normal operation.
1021 crc32()
1023 Return the CRC-32 value for this member. This will not be set for
1024 members that were constructed from strings or external files until
1025 after the member has been written.
1026 crc32String()
1028 Return the CRC-32 value for this member as an 8 character printable
1029 hex string. This will not be set for members that were constructed
1030 from strings or external files until after the member has been
1031 written.
1032 compressedSize()
1034 Return the compressed size for this member. This will not be set
1035 for members that were constructed from strings or external files
1036 until after the member has been written.
1037 uncompressedSize()
1039 Return the uncompressed size for this member.
1040 password( [ $password ] )
1042 Returns the password for this member to be used on decryption. If
1043 $password is given, it will set the password for the decryption.
1044 isEncrypted()
1046 Return true if this member is encrypted. The Archive::Zip module
1047 does not currently support creation of encrypted members.
1048 Decryption works more or less like this:
1049 my $zip = Archive::Zip->new;
1051 $zip->read ("encrypted.zip");
1052 for my $m (map { $zip->memberNamed ($_) } $zip->memberNames) {
1053 $m->password ("secret");
1054 $m->contents; # is "" when password was wrong
1055 That shows that the password has to be set per member, and not per
1057 archive. This might change in the future.
1058 isTextFile( [ $flag ] )
1060 isTextFile( [ { flag => $flag } ] )
1061 Returns true if I am a text file. Also can set the status if given
1062 an argument (then returns old state). Note that this module does
1063 not currently do anything with this flag upon extraction or
1064 storage. That is, bytes are stored in native format whether or not
1065 they came from a text file.
1066 isBinaryFile()
1068 Returns true if I am a binary file. Also can set the status if
1069 given an argument (then returns old state). Note that this module
1070 does not currently do anything with this flag upon extraction or
1071 storage. That is, bytes are stored in native format whether or not
1072 they came from a text file.
1073 extractToFileNamed( $fileName )
1075 extractToFileNamed( { name => $fileName } )
1076 Extract me to a file with the given name. The file will be created
1077 with default modes. Directories will be created as needed. The
1078 $fileName argument should be a valid file name on your file system.
1079 Returns AZ_OK on success.
1080 isDirectory()
1082 Returns true if I am a directory.
1083 writeLocalHeaderRelativeOffset()
1085 Returns the file offset in bytes the last time I was written.
1086 wasWritten()
1088 Returns true if I was successfully written. Reset at the beginning
1089 of a write attempt.
1090 Low-level member data reading
1092 It is possible to use lower-level routines to access member data
1093 streams, rather than the extract* methods and contents(). For instance,
1094 here is how to print the uncompressed contents of a member in chunks
1095 using these methods:
1096 my ( $member, $status, $bufferRef );
1098 $member = $zip->memberNamed( 'xyz.txt' );
1099 $member->desiredCompressionMethod( COMPRESSION_STORED );
1100 $status = $member->rewindData();
1101 die "error $status" unless $status == AZ_OK;
1102 while ( ! $member->readIsDone() )
1103 {
1104 ( $bufferRef, $status ) = $member->readChunk();
1105 die "error $status"
1106 if $status != AZ_OK && $status != AZ_STREAM_END;
1107 # do something with $bufferRef:
1108 print $$bufferRef;
1109 }
1110 $member->endRead();
1111 readChunk( [ $chunkSize ] )
1113 readChunk( [ { chunkSize => $chunkSize } ] )
1114 This reads the next chunk of given size from the member's data
1115 stream and compresses or uncompresses it as necessary, returning a
1116 reference to the bytes read and a status. If size argument is not
1117 given, defaults to global set by Archive::Zip::setChunkSize. Status
1118 is AZ_OK on success until the last chunk, where it returns
1119 AZ_STREAM_END. Returns "( \$bytes, $status)".
1120 my ( $outRef, $status ) = $self->readChunk();
1122 print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1123 rewindData()
1125 Rewind data and set up for reading data streams or writing zip
1126 files. Can take options for "inflateInit()" or "deflateInit()", but
1127 this is not likely to be necessary. Subclass overrides should call
1128 this method. Returns "AZ_OK" on success.
1129 endRead()
1131 Reset the read variables and free the inflater or deflater. Must
1132 be called to close files, etc. Returns AZ_OK on success.
1133 readIsDone()
1135 Return true if the read has run out of data or encountered an
1136 error.
1137 contents()
1139 Return the entire uncompressed member data or undef in scalar
1140 context. When called in array context, returns "( $string, $status
1141 )"; status will be AZ_OK on success:
1142 my $string = $member->contents();
1144 # or
1145 my ( $string, $status ) = $member->contents();
1146 die "error $status" unless $status == AZ_OK;
1147 Can also be used to set the contents of a member (this may change
1149 the class of the member):
1150 $member->contents( "this is my new contents" );
1152 extractToFileHandle( $fh )
1154 extractToFileHandle( { fileHandle => $fh } )
1155 Extract (and uncompress, if necessary) the member's contents to the
1156 given file handle. Return AZ_OK on success.
1157
1159 The Archive::Zip::FileMember class extends Archive::Zip::Member. It is
1160 the base class for both ZipFileMember and NewFileMember classes. This
1161 class adds an "externalFileName" and an "fh" member to keep track of
1162 the external file.
1163 externalFileName()
1165 Return the member's external filename.
1166 fh()
1168 Return the member's read file handle. Automatically opens file if
1169 necessary.
1170
1172 The Archive::Zip::ZipFileMember class represents members that have been
1173 read from external zip files.
1174 diskNumberStart()
1176 Returns the disk number that the member's local header resides in.
1177 Should be 0.
1178 localHeaderRelativeOffset()
1180 Returns the offset into the zip file where the member's local
1181 header is.
1182 dataOffset()
1184 Returns the offset from the beginning of the zip file to the
1185 member's data.
1186
1188 Archive::Zip requires several other modules:
1189 Carp
1191 Compress::Raw::Zlib
1193 Cwd
1195 File::Basename
1197 File::Copy
1199 File::Find
1201 File::Path
1203 File::Spec
1205 IO::File
1207 IO::Seekable
1209 Time::Local
1211
1213 When not to use Archive::Zip
1214 If you are just going to be extracting zips (and/or other archives) you
1215 are recommended to look at using Archive::Extract instead, as it is
1216 much easier to use and factors out archive-specific functionality.
1217 Try to avoid IO::Scalar
1219 One of the most common ways to use Archive::Zip is to generate Zip
1220 files in-memory. Most people use IO::Scalar for this purpose.
1221 Unfortunately, as of 1.11 this module no longer works with IO::Scalar
1223 as it incorrectly implements seeking.
1224 Anybody using IO::Scalar should consider porting to IO::String, which
1226 is smaller, lighter, and is implemented to be perfectly compatible with
1227 regular seekable filehandles.
1228 Support for IO::Scalar most likely will not be restored in the future,
1230 as IO::Scalar itself cannot change the way it is implemented due to
1231 back-compatibility issues.
1232 Wrong password for encrypted members
1234 When an encrypted member is read using the wrong password, you
1235 currently have to re-read the entire archive to try again with the
1236 correct password.
1237
1239 * auto-choosing storing vs compression
1240 * extra field hooks (see notes.txt)
1242 * check for duplicates on addition/renaming?
1244 * Text file extraction (line end translation)
1246 * Reading zip files from non-seekable inputs
1248 (Perhaps by proxying through IO::String?)
1249 * separate unused constants into separate module
1251 * cookbook style docs
1253 * Handle tainted paths correctly
1255 * Work on better compatibility with other IO:: modules
1257 * Support encryption
1259 * More user-friendly decryption
1261
1263 Bugs should be reported via the CPAN bug tracker
1264 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>
1266 For other issues contact the maintainer
1268
1270 Currently maintained by Fred Moyer <fred@redhotpenguin.com>
1271 Previously maintained by Adam Kennedy <adamk@cpan.org>
1273 Previously maintained by Steve Peters <steve@fisharerojo.org>.
1275 File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>.
1277 Originally by Ned Konz <nedkonz@cpan.org>.
1279
1281 Some parts copyright 2006 - 2012 Adam Kennedy.
1282 Some parts copyright 2005 Steve Peters.
1284 Original work copyright 2000 - 2004 Ned Konz.
1286 This program is free software; you can redistribute it and/or modify it
1288 under the same terms as Perl itself.
1289
1291 Look at Archive::Zip::MemberRead which is a wrapper that allows one to
1292 read Zip archive members as if they were files.
1293 Compress::Raw::Zlib, Archive::Tar, Archive::Extract
1295perl v5.28.1 2018-09-12 Archive::Zip(3)