1Archive::Zip(3) User Contributed Perl Documentation Archive::Zip(3)
2
6 Archive::Zip - Provide an interface to ZIP archive files.
7
9 use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
10 my $zip = Archive::Zip->new();
11 my $member = $zip->addDirectory( 'dirname/' );
12 $member = $zip->addString( 'This is a test', 'stringMember.txt' );
13 $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
14 $member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
15 die 'write error' unless $zip->writeToFileNamed( 'someZip.zip' ) == AZ_OK;
16 $zip = Archive::Zip->new();
17 die 'read error' unless $zip->read( 'someZip.zip' ) == AZ_OK;
18 $member = $zip->memberNamed( 'stringMember.txt' );
19 $member->desiredCompressionMethod( COMPRESSION_STORED );
20 die 'write error' unless $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK;
21
23 The Archive::Zip module allows a Perl program to create, manipulate,
24 read, and write Zip archive files. Zip archives can be created, or you
25 can read from existing zip files. Once created, they can be written to
26 files, streams, or strings. Members can be added, removed, extracted,
27 replaced, rearranged, and enumerated. They can also be renamed or have
28 their dates, comments, or other attributes queried or modified. Their
29 data can be compressed or uncompressed as needed. Members can be cre‐
30 ated from members in existing Zip files, or from existing directories,
31 files, or strings. This module uses the Compress::Zlib library to read
32 and write the compressed streams inside the files.
33
35 Regardless of what your local file system uses for file naming, names
36 in a Zip file are in Unix format (forward slashes (/) separating direc‐
37 tory names, etc.). "Archive::Zip" tries to be consistent with file
38 naming conventions, and will translate back and forth between native
39 and Zip file names. However, it can't guess which format names are in.
40 So two rules control what kind of file name you must pass various rou‐
41 tines:
42 Names of files are in local format.
44 "File::Spec" and "File::Basename" are used for various file opera‐
45 tions. When you're referring to a file on your system, use its file
46 naming conventions.
47 Names of archive members are in Unix format.
49 This applies to every method that refers to an archive member, or
50 provides a name for new archive members. The "extract()" methods
51 that can take one or two names will convert from local to zip names
52 if you call them with a single name.
53
55 Overview
56 Archive::Zip::Archive objects are what you ordinarily deal with. These
58 maintain the structure of a zip file, without necessarily holding data.
59 When a zip is read from a disk file, the (possibly compressed) data
60 still lives in the file, not in memory. Archive members hold informa‐
61 tion about the individual members, but not (usually) the actual member
62 data. When the zip is written to a (different) file, the member data is
63 compressed or copied as needed. It is possible to make archive members
64 whose data is held in a string in memory, but this is not done when a
65 zip file is read. Directory members don't have any data.
66 Inheritance
68 Exporter
70 Archive::Zip Common base class, has defs.
71 Archive::Zip::Archive A Zip archive.
72 Archive::Zip::Member Abstract superclass for all members.
73 Archive::Zip::StringMember Member made from a string
74 Archive::Zip::FileMember Member made from an external file
75 Archive::Zip::ZipFileMember Member that lives in a zip file
76 Archive::Zip::NewFileMember Member whose data is in a file
77 Archive::Zip::DirectoryMember Member that is a directory
78
80 :CONSTANTS
81 Exports the following constants: FA_MSDOS FA_UNIX
82 GPBF_ENCRYPTED_MASK GPBF_DEFLATING_COMPRESSION_MASK
83 GPBF_HAS_DATA_DESCRIPTOR_MASK COMPRESSION_STORED COMPRES‐
84 SION_DEFLATED IFA_TEXT_FILE_MASK IFA_TEXT_FILE IFA_BINARY_FILE COM‐
85 PRESSION_LEVEL_NONE COMPRESSION_LEVEL_DEFAULT COMPRES‐
86 SION_LEVEL_FASTEST COMPRESSION_LEVEL_BEST_COMPRESSION
87 :MISC_CONSTANTS
89 Exports the following constants (only necessary for extending the
90 module): FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS
91 FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS GPBF_IMPLOD‐
92 ING_8K_SLIDING_DICTIONARY_MASK GPBF_IMPLODING_3_SHAN‐
93 NON_FANO_TREES_MASK GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRES‐
94 SION_SHRUNK DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAX‐
95 IMUM DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
96 COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
97 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
98 COMPRESSION_DEFLATED_ENHANCED COMPRESSION_PKWARE_DATA_COMPRES‐
99 SION_LIBRARY_IMPLODED
100 :ERROR_CODES
102 Explained below. Returned from most methods. AZ_OK AZ_STREAM_END
103 AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
104
106 Many of the methods in Archive::Zip return error codes. These are
107 implemented as inline subroutines, using the "use constant" pragma.
108 They can be imported into your namespace using the ":ERROR_CODES" tag:
109 use Archive::Zip qw( :ERROR_CODES );
111 ...
112 die "whoops!" unless $zip->read( 'myfile.zip' ) == AZ_OK;
113 AZ_OK (0)
115 Everything is fine.
116 AZ_STREAM_END (1)
118 The read stream (or central directory) ended normally.
119 AZ_ERROR (2)
121 There was some generic kind of error.
122 AZ_FORMAT_ERROR (3)
124 There is a format error in a ZIP file being read.
125 AZ_IO_ERROR (4)
127 There was an IO error.
128
130 Archive::Zip allows each member of a ZIP file to be compressed (using
131 the Deflate algorithm) or uncompressed. Other compression algorithms
132 that some versions of ZIP have been able to produce are not supported.
133 Each member has two compression methods: the one it's stored as (this
134 is always COMPRESSION_STORED for string and external file members), and
135 the one you desire for the member in the zip file. These can be differ‐
136 ent, of course, so you can make a zip member that is not compressed out
137 of one that is, and vice versa. You can inquire about the current com‐
138 pression and set the desired compression method:
139 my $member = $zip->memberNamed( 'xyz.txt' );
141 $member->compressionMethod(); # return current compression
142 # set to read uncompressed
143 $member->desiredCompressionMethod( COMPRESSION_STORED );
144 # set to read compressed
145 $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
146 There are two different compression methods:
148 COMPRESSION_STORED
150 file is stored (no compression)
151 COMPRESSION_DEFLATED
153 file is Deflated
154 Compression Levels
156 If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can
158 choose different compression levels. This choice may affect the speed
159 of compression and decompression, as well as the size of the compressed
160 member data.
161 $member->desiredCompressionLevel( 9 );
163 The levels given can be:
165 0 or COMPRESSION_LEVEL_NONE
167 This is the same as saying
168 $member->desiredCompressionMethod( COMPRESSION_STORED );
170 1 .. 9
172 1 gives the best speed and worst compression, and 9 gives the best
173 compression and worst speed.
174 COMPRESSION_LEVEL_FASTEST
176 This is a synonym for level 1.
177 COMPRESSION_LEVEL_BEST_COMPRESSION
179 This is a synonym for level 9.
180 COMPRESSION_LEVEL_DEFAULT
182 This gives a good compromise between speed and compression, and is
183 currently equivalent to 6 (this is in the zlib code). This is the
184 level that will be used if not specified.
185
187 The Archive::Zip class (and its invisible subclass Archive::Zip::Ar‐
188 chive) implement generic zip file functionality. Creating a new Ar‐
189 chive::Zip object actually makes an Archive::Zip::Archive object, but
190 you don't have to worry about this unless you're subclassing.
191 Constructor
193 new( [$fileName] )
195 Make a new, empty zip archive.
196 my $zip = Archive::Zip->new();
198 If an additional argument is passed, new() will call read() to read
200 the contents of an archive:
201 my $zip = Archive::Zip->new( 'xyz.zip' );
203 If a filename argument is passed and the read fails for any reason,
205 new will return undef. For this reason, it may be better to call
206 read separately.
207 Zip Archive Utility Methods
209 These Archive::Zip methods may be called as functions or as object
211 methods. Do not call them as class methods:
212 $zip = Archive::Zip->new();
214 $crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK
215 $crc = $zip->computeCRC32( 'ghijkl' ); # also OK
216 $crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK
217 Archive::Zip::computeCRC32( $string [, $crc] )
219 This is a utility function that uses the Compress::Zlib CRC routine
220 to compute a CRC-32. You can get the CRC of a string:
221 $crc = Archive::Zip::computeCRC32( $string );
223 Or you can compute the running CRC:
225 $crc = 0;
227 $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
228 $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
229 Archive::Zip::setChunkSize( $number )
231 Report or change chunk size used for reading and writing. This can
232 make big differences in dealing with large files. Currently, this
233 defaults to 32K. This also changes the chunk size used for Com‐
234 press::Zlib. You must call setChunkSize() before reading or writ‐
235 ing. This is not exportable, so you must call it like:
236 Archive::Zip::setChunkSize( 4096 );
238 or as a method on a zip (though this is a global setting). Returns
240 old chunk size.
241 Archive::Zip::chunkSize()
243 Returns the current chunk size:
244 my $chunkSize = Archive::Zip::chunkSize();
246 Archive::Zip::setErrorHandler( \&subroutine )
248 Change the subroutine called with error strings. This defaults to
249 \&Carp::carp, but you may want to change it to get the error
250 strings. This is not exportable, so you must call it like:
251 Archive::Zip::setErrorHandler( \&myErrorHandler );
253 If myErrorHandler is undef, resets handler to default. Returns old
255 error handler. Note that if you call Carp::carp or a similar rou‐
256 tine or if you're chaining to the default error handler from your
257 error handler, you may want to increment the number of caller lev‐
258 els that are skipped (do not just set it to a number):
259 $Carp::CarpLevel++;
261 Archive::Zip::tempFile( [$tmpdir] )
263 Create a uniquely named temp file. It will be returned open for
264 read/write. If $tmpdir is given, it is used as the name of a direc‐
265 tory to create the file in. If not given, creates the file using
266 "File::Spec::tmpdir()". Generally, you can override this choice
267 using the
268 $ENV{TMPDIR}
270 environment variable. But see the File::Spec documentation for your
272 system. Note that on many systems, if you're running in taint mode,
273 then you must make sure that $ENV{TMPDIR} is untainted for it to be
274 used. Will NOT create $tmpdir if it doesn't exist (this is a
275 change from prior versions!). Returns file handle and name:
276 my ($fh, $name) = Archive::Zip::tempFile();
278 my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
279 my $fh = Archive::Zip::tempFile(); # if you don't need the name
280 Zip Archive Accessors
282 members()
284 Return a copy of the members array
285 my @members = $zip->members();
287 numberOfMembers()
289 Return the number of members I have
290 memberNames()
292 Return a list of the (internal) file names of the zip members
293 memberNamed( $string )
295 Return ref to member whose filename equals given filename or undef.
296 $string must be in Zip (Unix) filename format.
297 membersMatching( $regex )
299 Return array of members whose filenames match given regular expres‐
300 sion in list context. Returns number of matching members in scalar
301 context.
302 my @textFileMembers = $zip->membersMatching( '.*\.txt' );
304 # or
305 my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
306 diskNumber()
308 Return the disk that I start on. Not used for writing zips, but
309 might be interesting if you read a zip in. This should be 0, as Ar‐
310 chive::Zip does not handle multi-volume archives.
311 diskNumberWithStartOfCentralDirectory()
313 Return the disk number that holds the beginning of the central
314 directory. Not used for writing zips, but might be interesting if
315 you read a zip in. This should be 0, as Archive::Zip does not han‐
316 dle multi-volume archives.
317 numberOfCentralDirectoriesOnThisDisk()
319 Return the number of CD structures in the zipfile last read in.
320 Not used for writing zips, but might be interesting if you read a
321 zip in.
322 numberOfCentralDirectories()
324 Return the number of CD structures in the zipfile last read in.
325 Not used for writing zips, but might be interesting if you read a
326 zip in.
327 centralDirectorySize()
329 Returns central directory size, as read from an external zip file.
330 Not used for writing zips, but might be interesting if you read a
331 zip in.
332 centralDirectoryOffsetWRTStartingDiskNumber()
334 Returns the offset into the zip file where the CD begins. Not used
335 for writing zips, but might be interesting if you read a zip in.
336 zipfileComment( [$string] )
338 Get or set the zipfile comment. Returns the old comment.
339 print $zip->zipfileComment();
341 $zip->zipfileComment( 'New Comment' );
342 eocdOffset()
344 Returns the (unexpected) number of bytes between where the EOCD was
345 found and where it expected to be. This is normally 0, but would be
346 positive if something (a virus, perhaps) had added bytes somewhere
347 before the EOCD. Not used for writing zips, but might be interest‐
348 ing if you read a zip in. Here is an example of how you can diag‐
349 nose this:
350 my $zip = Archive::Zip->new('somefile.zip');
352 if ($zip->eocdOffset())
353 {
354 warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
355 }
356 The "eocdOffset()" is used to adjust the starting position of mem‐
358 ber headers, if necessary.
359 fileName()
361 Returns the name of the file last read from. If nothing has been
362 read yet, returns an empty string; if read from a file handle,
363 returns the handle in string form.
364 Zip Archive Member Operations
366 Various operations on a zip file modify members. When a member is
368 passed as an argument, you can either use a reference to the member
369 itself, or the name of a member. Of course, using the name requires
370 that names be unique within a zip (this is not enforced).
371 removeMember( $memberOrName )
373 Remove and return the given member, or match its name and remove
374 it. Returns undef if member or name doesn't exist in this Zip. No-
375 op if member does not belong to this zip.
376 replaceMember( $memberOrName, $newMember )
378 Remove and return the given member, or match its name and remove
379 it. Replace with new member. Returns undef if member or name
380 doesn't exist in this Zip, or if $newMember is undefined.
381 It is an (undiagnosed) error to provide a $newMember that is a mem‐
383 ber of the zip being modified.
384 my $member1 = $zip->removeMember( 'xyz' );
386 my $member2 = $zip->replaceMember( 'abc', $member1 );
387 # now, $member2 (named 'abc') is not in $zip,
388 # and $member1 (named 'xyz') is, having taken $member2's place.
389 extractMember( $memberOrName [, $extractedName ] )
391 Extract the given member, or match its name and extract it.
392 Returns undef if member doesn't exist in this Zip. If optional sec‐
393 ond arg is given, use it as the name of the extracted member. Oth‐
394 erwise, the internal filename of the member is used as the name of
395 the extracted file or directory. If you pass $extractedName, it
396 should be in the local file system's format. All necessary direc‐
397 tories will be created. Returns "AZ_OK" on success.
398 extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
400 Extract the given member, or match its name and extract it. Does
401 not use path information (extracts into the current directory).
402 Returns undef if member doesn't exist in this Zip. If optional
403 second arg is given, use it as the name of the extracted member
404 (its paths will be deleted too). Otherwise, the internal filename
405 of the member (minus paths) is used as the name of the extracted
406 file or directory. Returns "AZ_OK" on success.
407 addMember( $member )
409 Append a member (possibly from another zip file) to the zip file.
410 Returns the new member. Generally, you will use addFile(), addDi‐
411 rectory(), addFileOrDirectory(), addString(), or read() to add mem‐
412 bers.
413 # Move member named 'abc' to end of zip:
415 my $member = $zip->removeMember( 'abc' );
416 $zip->addMember( $member );
417 updateMember( $memberOrName, $fileName )
419 Update a single member from the file or directory named $fileName.
420 Returns the (possibly added or updated) member, if any; "undef" on
421 errors. The comparison is based on "lastModTime()" and (in the
422 case of a non-directory) the size of the file.
423 addFile( $fileName [, $newName ] )
425 Append a member whose data comes from an external file, returning
426 the member or undef. The member will have its file name set to the
427 name of the external file, and its desiredCompressionMethod set to
428 COMPRESSION_DEFLATED. The file attributes and last modification
429 time will be set from the file. If the name given does not repre‐
430 sent a readable plain file or symbolic link, undef will be
431 returned. $fileName must be in the format required for the local
432 file system. The optional $newName argument sets the internal file
433 name to something different than the given $fileName. $newName, if
434 given, must be in Zip name format (i.e. Unix). The text mode bit
435 will be set if the contents appears to be text (as returned by the
436 "-T" perl operator).
437 NOTE that you shouldn't (generally) use absolute path names in zip
439 member names, as this will cause problems with some zip tools as
440 well as introduce a security hole and make the zip harder to use.
441 addDirectory( $directoryName [, $fileName ] )
443 Append a member created from the given directory name. The direc‐
444 tory name does not have to name an existing directory. If the
445 named directory exists, the file modification time and permissions
446 are set from the existing directory, otherwise they are set to now
447 and permissive default permissions. $directoryName must be in
448 local file system format. The optional second argument sets the
449 name of the archive member (which defaults to $directoryName). If
450 given, it must be in Zip (Unix) format. Returns the new member.
451 addFileOrDirectory( $name [, $newName ] )
453 Append a member from the file or directory named $name. If $newName
454 is given, use it for the name of the new member. Will add or
455 remove trailing slashes from $newName as needed. $name must be in
456 local file system format. The optional second argument sets the
457 name of the archive member (which defaults to $name). If given, it
458 must be in Zip (Unix) format.
459 addString( $stringOrStringRef, $name )
461 Append a member created from the given string or string reference.
462 The name is given by the second argument. Returns the new member.
463 The last modification time will be set to now, and the file
464 attributes will be set to permissive defaults.
465 my $member = $zip->addString( 'This is a test', 'test.txt' );
467 contents( $memberOrMemberName [, $newContents ] )
469 Returns the uncompressed data for a particular member, or undef.
470 print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
472 Also can change the contents of a member:
474 $zip->contents( 'xyz.txt', 'This is the new contents' );
476 If called expecting an array as the return value, it will include
478 the status as the second value in the array.
479 ($content, $status) = $zip->contents( 'xyz.txt');
481 Zip Archive I/O operations
483 A Zip archive can be written to a file or file handle, or read from
485 one.
486 writeToFileNamed( $fileName )
488 Write a zip archive to named file. Returns "AZ_OK" on success.
489 my $status = $zip->writeToFileNamed( 'xx.zip' );
491 die "error somewhere" if $status != AZ_OK;
492 Note that if you use the same name as an existing zip file that you
494 read in, you will clobber ZipFileMembers. So instead, write to a
495 different file name, then delete the original. If you use the
496 "overwrite()" or "overwriteAs()" methods, you can re-write the
497 original zip in this way. $fileName should be a valid file name on
498 your system.
499 writeToFileHandle( $fileHandle [, $seekable] )
501 Write a zip archive to a file handle. Return AZ_OK on success. The
502 optional second arg tells whether or not to try to seek backwards
503 to re-write headers. If not provided, it is set if the Perl "-f"
504 test returns true. This could fail on some operating systems,
505 though.
506 my $fh = IO::File->new( 'someFile.zip', 'w' );
508 if ( $zip->writeToFileHandle( $fh ) != AZ_OK)
509 {
510 # error handling
511 }
512 If you pass a file handle that is not seekable (like if you're
514 writing to a pipe or a socket), pass a false second argument:
515 my $fh = IO::File->new( '⎪ cat > somefile.zip', 'w' );
517 $zip->writeToFileHandle( $fh, 0 ); # fh is not seekable
518 If this method fails during the write of a member, that member and
520 all following it will return false from "wasWritten()". See write‐
521 CentralDirectory() for a way to deal with this. If you want, you
522 can write data to the file handle before passing it to writeToFile‐
523 Handle(); this could be used (for instance) for making self-
524 extracting archives. However, this only works reliably when writing
525 to a real file (as opposed to STDOUT or some other possible
526 non-file). See examples/selfex.pl for how to write a self-extract‐
527 ing archive.
528 writeCentralDirectory( $fileHandle [, $offset ] )
530 Writes the central directory structure to the given file handle.
531 Returns AZ_OK on success. If given an $offset, will seek to that
532 point before writing. This can be used for recovery in cases where
533 writeToFileHandle or writeToFileNamed returns an IO error because
534 of running out of space on the destination file. You can truncate
535 the zip by seeking backwards and then writing the directory:
536 my $fh = IO::File->new( 'someFile.zip', 'w' );
538 my $retval = $zip->writeToFileHandle( $fh );
539 if ( $retval == AZ_IO_ERROR )
540 {
541 my @unwritten = grep { not $_->wasWritten() } $zip->members();
542 if (@unwritten)
543 {
544 $zip->removeMember( $member ) foreach my $member ( @unwritten );
545 $zip->writeCentralDirectory( $fh,
546 $unwritten[0]->writeLocalHeaderRelativeOffset());
547 }
548 }
549 overwriteAs( $newName )
551 Write the zip to the specified file, as safely as possible. This
552 is done by first writing to a temp file, then renaming the original
553 if it exists, then renaming the temp file, then deleting the
554 renamed original if it exists. Returns AZ_OK if successful.
555 overwrite()
557 Write back to the original zip file. See overwriteAs() above. If
558 the zip was not ever read from a file, this generates an error.
559 read( $fileName )
561 Read zipfile headers from a zip file, appending new members.
562 Returns "AZ_OK" or error code.
563 my $zipFile = Archive::Zip->new();
565 my $status = $zipFile->read( '/some/FileName.zip' );
566 readFromFileHandle( $fileHandle, $filename )
568 Read zipfile headers from an already-opened file handle, appending
569 new members. Does not close the file handle. Returns "AZ_OK" or
570 error code. Note that this requires a seekable file handle; reading
571 from a stream is not yet supported.
572 my $fh = IO::File->new( '/some/FileName.zip', 'r' );
574 my $zip1 = Archive::Zip->new();
575 my $status = $zip1->readFromFileHandle( $fh );
576 my $zip2 = Archive::Zip->new();
577 $status = $zip2->readFromFileHandle( $fh );
578 Zip Archive Tree operations
580 These used to be in Archive::Zip::Tree but got moved into Archive::Zip.
582 They enable operation on an entire tree of members or files. A usage
583 example:
584 use Archive::Zip;
586 my $zip = Archive::Zip->new();
587 # add all readable files and directories below . as xyz/*
588 $zip->addTree( '.', 'xyz' );
589 # add all readable plain files below /abc as def/*
590 $zip->addTree( '/abc', 'def', sub { -f && -r } );
591 # add all .c files below /tmp as stuff/*
592 $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
593 # add all .o files below /tmp as stuff/* if they aren't writable
594 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
595 # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
596 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
597 # and write them into a file
598 $zip->writeToFileNamed('xxx.zip');
599 # now extract the same files into /tmpx
600 $zip->extractTree( 'stuff', '/tmpx' );
601 $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
603 $root is the root of the tree of files and directories to be added.
604 It is a valid directory name on your system. $dest is the name for
605 the root in the zip file (undef or blank means to use relative
606 pathnames). It is a valid ZIP directory name (that is, it uses for‐
607 ward slashes (/) for separating directory components). $pred is an
608 optional subroutine reference to select files: it is passed the
609 name of the prospective file or directory using $_, and if it
610 returns true, the file or directory will be included. The default
611 is to add all readable files and directories. For instance, using
612 my $pred = sub { /\.txt/ };
614 $zip->addTree( '.', '', $pred );
615 will add all the .txt files in and below the current directory,
617 using relative names, and making the names identical in the zip‐
618 file:
619 original name zip member name
621 ./xyz xyz
622 ./a/ a/
623 ./a/b a/b
624 To translate absolute to relative pathnames, just pass them in:
626 $zip->addTree( '/c/d', 'a' );
627 original name zip member name
629 /c/d/xyz a/xyz
630 /c/d/a/ a/a/
631 /c/d/a/b a/a/b
632 Returns AZ_OK on success. Note that this will not follow symbolic
634 links to directories. Note also that this does not check for the
635 validity of filenames.
636 Note that you generally don't want to make zip archive member names
638 absolute.
639 $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
641 $root is the root of the tree of files and directories to be added
642 $dest is the name for the root in the zip file (undef means to use
643 relative pathnames) $pattern is a (non-anchored) regular expression
644 for filenames to match $pred is an optional subroutine reference to
645 select files: it is passed the name of the prospective file or
646 directory in $_, and if it returns true, the file or directory will
647 be included. The default is to add all readable files and directo‐
648 ries. To add all files in and below the current dirctory whose
649 names end in ".pl", and make them extract into a subdirectory named
650 "xyz", do this:
651 $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
653 To add all writable files in and below the dirctory named "/abc"
655 whose names end in ".pl", and make them extract into a subdirectory
656 named "xyz", do this:
657 $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
659 Returns AZ_OK on success. Note that this will not follow symbolic
661 links to directories.
662 $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
664 Update a zip file from a directory tree.
665 "updateTree()" takes the same arguments as "addTree()", but first
667 checks to see whether the file or directory already exists in the
668 zip file, and whether it has been changed.
669 If the fourth argument $mirror is true, then delete all my members
671 if corresponding files weren't found.
672 Returns an error code or AZ_OK if all is well.
674 $zip->extractTree()
676 $zip->extractTree( $root )
677 $zip->extractTree( $root, $dest )
678 $zip->extractTree( $root, $dest, $volume )
679 If you don't give any arguments at all, will extract all the files
680 in the zip with their original names.
681 If you supply one argument for $root, "extractTree" will extract
683 all the members whose names start with $root into the current
684 directory, stripping off $root first. $root is in Zip (Unix) for‐
685 mat. For instance,
686 $zip->extractTree( 'a' );
688 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
690 will extract:
691 a/x as ./x
693 a/b/c as ./b/c
695 If you give two arguments, "extractTree" extracts all the members
697 whose names start with $root. It will translate $root into $dest to
698 construct the destination file name. $root and $dest are in Zip
699 (Unix) format. For instance,
700 $zip->extractTree( 'a', 'd/e' );
702 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
704 will extract:
705 a/x to d/e/x
707 a/b/c to d/e/b/c and ignore ax/d/e and d/e
709 If you give three arguments, "extractTree" extracts all the members
711 whose names start with $root. It will translate $root into $dest to
712 construct the destination file name, and then it will convert to
713 local file system format, using $volume as the name of the destina‐
714 tion volume.
715 $root and $dest are in Zip (Unix) format.
717 $volume is in local file system format.
719 For instance, under Windows,
721 $zip->extractTree( 'a', 'd/e', 'f:' );
723 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
725 will extract:
726 a/x to f:d/e/x
728 a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
730 If you want absolute paths (the prior example used paths relative
732 to the current directory on the destination volume, you can specify
733 these in $dest:
734 $zip->extractTree( 'a', '/d/e', 'f:' );
736 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
738 will extract:
739 a/x to f:\d\e\x
741 a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
743 Returns an error code or AZ_OK if everything worked OK.
745
747 Member Class Methods
748 Several constructors allow you to construct members without adding them
750 to a zip archive. These work the same as the addFile(), addDirectory(),
751 and addString() zip instance methods described above, but they don't
752 add the new members to a zip.
753 Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
755 Construct a new member from the given string. Returns undef on
756 error.
757 my $member = Archive::Zip::Member->newFromString( 'This is a test',
759 'xyz.txt' );
760 newFromFile( $fileName )
762 Construct a new member from the given file. Returns undef on error.
763 my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
765 newDirectoryNamed( $directoryName [, $zipname ] )
767 Construct a new member from the given directory. $directoryName
768 must be a valid name on your file system; it doesn't have to exist.
769 If given, $zipname will be the name of the zip member; it must be a
771 valid Zip (Unix) name. If not given, it will be converted from
772 $directoryName.
773 Returns undef on error.
775 my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
777 Member Simple accessors
779 These methods get (and/or set) member attribute values.
781 versionMadeBy()
783 Gets the field from the member header.
784 fileAttributeFormat( [$format] )
786 Gets or sets the field from the member header. These are "FA_*"
787 values.
788 versionNeededToExtract()
790 Gets the field from the member header.
791 bitFlag()
793 Gets the general purpose bit field from the member header. This is
794 where the "GPBF_*" bits live.
795 compressionMethod()
797 Returns the member compression method. This is the method that is
798 currently being used to compress the member data. This will be
799 COMPRESSION_STORED for added string or file members, or any of the
800 "COMPRESSION_*" values for members from a zip file. However, this
801 module can only handle members whose data is in COMPRESSION_STORED
802 or COMPRESSION_DEFLATED format.
803 desiredCompressionMethod( [$method] )
805 Get or set the member's "desiredCompressionMethod". This is the
806 compression method that will be used when the member is written.
807 Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED
808 or COMPRESSION_STORED are valid arguments. Changing to COMPRES‐
809 SION_STORED will change the member desiredCompressionLevel to 0;
810 changing to COMPRESSION_DEFLATED will change the member desiredCom‐
811 pressionLevel to COMPRESSION_LEVEL_DEFAULT.
812 desiredCompressionLevel( [$method] )
814 Get or set the member's desiredCompressionLevel This is the method
815 that will be used to write. Returns prior desiredCompressionLevel.
816 Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE, COMPRES‐
817 SION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and COM‐
818 PRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change the
819 desiredCompressionMethod to COMPRESSION_STORED. All other argu‐
820 ments will change the desiredCompressionMethod to COMPRES‐
821 SION_DEFLATED.
822 externalFileName()
824 Return the member's external file name, if any, or undef.
825 fileName()
827 Get or set the member's internal filename. Returns the (possibly
828 new) filename. Names will have backslashes converted to forward
829 slashes, and will have multiple consecutive slashes converted to
830 single ones.
831 lastModFileDateTime()
833 Return the member's last modification date/time stamp in MS-DOS
834 format.
835 lastModTime()
837 Return the member's last modification date/time stamp, converted to
838 unix localtime format.
839 print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
841 setLastModFileDateTimeFromUnix()
843 Set the member's lastModFileDateTime from the given unix time.
844 $member->setLastModFileDateTimeFromUnix( time() );
846 internalFileAttributes()
848 Return the internal file attributes field from the zip header. This
849 is only set for members read from a zip file.
850 externalFileAttributes()
852 Return member attributes as read from the ZIP file. Note that these
853 are NOT UNIX!
854 unixFileAttributes( [$newAttributes] )
856 Get or set the member's file attributes using UNIX file attributes.
857 Returns old attributes.
858 my $oldAttribs = $member->unixFileAttributes( 0666 );
860 Note that the return value has more than just the file permissions,
862 so you will have to mask off the lowest bits for comparisions.
863 localExtraField( [$newField] )
865 Gets or sets the extra field that was read from the local header.
866 This is not set for a member from a zip file until after the member
867 has been written out. The extra field must be in the proper format.
868 cdExtraField( [$newField] )
870 Gets or sets the extra field that was read from the central direc‐
871 tory header. The extra field must be in the proper format.
872 extraFields()
874 Return both local and CD extra fields, concatenated.
875 fileComment( [$newComment] )
877 Get or set the member's file comment.
878 hasDataDescriptor()
880 Get or set the data descriptor flag. If this is set, the local
881 header will not necessarily have the correct data sizes. Instead, a
882 small structure will be stored at the end of the member data with
883 these values. This should be transparent in normal operation.
884 crc32()
886 Return the CRC-32 value for this member. This will not be set for
887 members that were constructed from strings or external files until
888 after the member has been written.
889 crc32String()
891 Return the CRC-32 value for this member as an 8 character printable
892 hex string. This will not be set for members that were constructed
893 from strings or external files until after the member has been
894 written.
895 compressedSize()
897 Return the compressed size for this member. This will not be set
898 for members that were constructed from strings or external files
899 until after the member has been written.
900 uncompressedSize()
902 Return the uncompressed size for this member.
903 isEncrypted()
905 Return true if this member is encrypted. The Archive::Zip module
906 does not currently create or extract encrypted members.
907 isTextFile( [$flag] )
909 Returns true if I am a text file. Also can set the status if given
910 an argument (then returns old state). Note that this module does
911 not currently do anything with this flag upon extraction or stor‐
912 age. That is, bytes are stored in native format whether or not they
913 came from a text file.
914 isBinaryFile()
916 Returns true if I am a binary file. Also can set the status if
917 given an argument (then returns old state). Note that this module
918 does not currently do anything with this flag upon extraction or
919 storage. That is, bytes are stored in native format whether or not
920 they came from a text file.
921 extractToFileNamed( $fileName )
923 Extract me to a file with the given name. The file will be created
924 with default modes. Directories will be created as needed. The
925 $fileName argument should be a valid file name on your file system.
926 Returns AZ_OK on success.
927 isDirectory()
929 Returns true if I am a directory.
930 writeLocalHeaderRelativeOffset()
932 Returns the file offset in bytes the last time I was written.
933 wasWritten()
935 Returns true if I was successfully written. Reset at the beginning
936 of a write attempt.
937 Low-level member data reading
939 It is possible to use lower-level routines to access member data
941 streams, rather than the extract* methods and contents(). For instance,
942 here is how to print the uncompressed contents of a member in chunks
943 using these methods:
944 my ( $member, $status, $bufferRef );
946 $member = $zip->memberNamed( 'xyz.txt' );
947 $member->desiredCompressionMethod( COMPRESSION_STORED );
948 $status = $member->rewindData();
949 die "error $status" unless $status == AZ_OK;
950 while ( ! $member->readIsDone() )
951 {
952 ( $bufferRef, $status ) = $member->readChunk();
953 die "error $status"
954 if $status != AZ_OK && $status != AZ_STREAM_END;
955 # do something with $bufferRef:
956 print $$bufferRef;
957 }
958 $member->endRead();
959 readChunk( [$chunkSize] )
961 This reads the next chunk of given size from the member's data
962 stream and compresses or uncompresses it as necessary, returning a
963 reference to the bytes read and a status. If size argument is not
964 given, defaults to global set by Archive::Zip::setChunkSize. Status
965 is AZ_OK on success until the last chunk, where it returns
966 AZ_STREAM_END. Returns "( \$bytes, $status)".
967 my ( $outRef, $status ) = $self->readChunk();
969 print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
970 rewindData()
972 Rewind data and set up for reading data streams or writing zip
973 files. Can take options for "inflateInit()" or "deflateInit()", but
974 this isn't likely to be necessary. Subclass overrides should call
975 this method. Returns "AZ_OK" on success.
976 endRead()
978 Reset the read variables and free the inflater or deflater. Must
979 be called to close files, etc. Returns AZ_OK on success.
980 readIsDone()
982 Return true if the read has run out of data or errored out.
983 contents()
985 Return the entire uncompressed member data or undef in scalar con‐
986 text. When called in array context, returns "( $string, $status )";
987 status will be AZ_OK on success:
988 my $string = $member->contents();
990 # or
991 my ( $string, $status ) = $member->contents();
992 die "error $status" unless $status == AZ_OK;
993 Can also be used to set the contents of a member (this may change
995 the class of the member):
996 $member->contents( "this is my new contents" );
998 extractToFileHandle( $fh )
1000 Extract (and uncompress, if necessary) the member's contents to the
1001 given file handle. Return AZ_OK on success.
1002
1004 The Archive::Zip::FileMember class extends Archive::Zip::Member. It is
1005 the base class for both ZipFileMember and NewFileMember classes. This
1006 class adds an "externalFileName" and an "fh" member to keep track of
1007 the external file.
1008 externalFileName()
1010 Return the member's external filename.
1011 fh()
1013 Return the member's read file handle. Automatically opens file if
1014 necessary.
1015
1017 The Archive::Zip::ZipFileMember class represents members that have been
1018 read from external zip files.
1019 diskNumberStart()
1021 Returns the disk number that the member's local header resides in.
1022 Should be 0.
1023 localHeaderRelativeOffset()
1025 Returns the offset into the zip file where the member's local
1026 header is.
1027 dataOffset()
1029 Returns the offset from the beginning of the zip file to the mem‐
1030 ber's data.
1031
1033 Archive::Zip requires several other modules:
1034 Carp
1036 Compress::Zlib
1038 Cwd
1040 File::Basename
1042 File::Copy
1044 File::Find
1046 File::Path
1048 File::Spec
1050 File::Spec
1052 IO::File
1054 IO::Seekable
1056 Time::Local
1058
1060 Ned Konz, <nedkonz@cpan.org>
1061
1063 Steve Peters, <steve@fisharerojo.org>
1064 File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>
1066
1068 Copyright (c) 2000-2004 Ned Konz, 2005 Steve Peters. All rights
1069 reserved. This program is free software; you can redistribute it
1070 and/or modify it under the same terms as Perl itself.
1071
1073 Compress::Zlib
1074 Archive::Tar
1076 There is a Japanese translation of this document at
1078 <http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html> that was done by
1079 DEQ <deq@oct.zaq.ne.jp> . Thanks!
1080perl v5.8.8 2005-06-20 Archive::Zip(3)