1NAME
2 Archive::Zip - Provide an interface to ZIP archive files.
3
4SYNOPSIS
5 # Create a Zip file
6 use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
7 my $zip = Archive::Zip->new();
8
9 # Add a directory
10 my $dir_member = $zip->addDirectory( 'dirname/' );
11
12 # Add a file from a string with compression
13 my $string_member = $zip->addString( 'This is a test', 'stringMember.txt' );
14 $string_member->desiredCompressionMethod( COMPRESSION_DEFLATED );
15
16 # Add a file from disk
17 my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
18
19 # Save the Zip file
20 unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {
21 die 'write error';
22 }
23
24 # Read a Zip file
25 my $somezip = Archive::Zip->new();
26 unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {
27 die 'read error';
28 }
29
30 # Change the compression type for a file in the Zip
31 my $member = $somezip->memberNamed( 'stringMember.txt' );
32 $member->desiredCompressionMethod( COMPRESSION_STORED );
33 unless ( $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK ) {
34 die 'write error';
35 }
36
37DESCRIPTION
38 The Archive::Zip module allows a Perl program to create, manipulate,
39 read, and write Zip archive files.
40
41 Zip archives can be created, or you can read from existing zip files.
42
43 Once created, they can be written to files, streams, or strings. Members
44 can be added, removed, extracted, replaced, rearranged, and enumerated.
45 They can also be renamed or have their dates, comments, or other
46 attributes queried or modified. Their data can be compressed or
47 uncompressed as needed.
48
49 Members can be created from members in existing Zip files, or from
50 existing directories, files, or strings.
51
52 This module uses the Compress::Raw::Zlib library to read and write the
53 compressed streams inside the files.
54
55 One can use Archive::Zip::MemberRead to read the zip file archive
56 members as if they were files.
57
58 File Naming
59 Regardless of what your local file system uses for file naming, names in
60 a Zip file are in Unix format (*forward* slashes (/) separating
61 directory names, etc.).
62
63 "Archive::Zip" tries to be consistent with file naming conventions, and
64 will translate back and forth between native and Zip file names.
65
66 However, it can't guess which format names are in. So two rules control
67 what kind of file name you must pass various routines:
68
69 Names of files are in local format.
70 "File::Spec" and "File::Basename" are used for various file
71 operations. When you're referring to a file on your system, use its
72 file naming conventions.
73
74 Names of archive members are in Unix format.
75 This applies to every method that refers to an archive member, or
76 provides a name for new archive members. The "extract()" methods
77 that can take one or two names will convert from local to zip names
78 if you call them with a single name.
79
80 Archive::Zip Object Model
81 Overview
82 Archive::Zip::Archive objects are what you ordinarily deal with. These
83 maintain the structure of a zip file, without necessarily holding data.
84 When a zip is read from a disk file, the (possibly compressed) data
85 still lives in the file, not in memory. Archive members hold information
86 about the individual members, but not (usually) the actual member data.
87 When the zip is written to a (different) file, the member data is
88 compressed or copied as needed. It is possible to make archive members
89 whose data is held in a string in memory, but this is not done when a
90 zip file is read. Directory members don't have any data.
91
92 Inheritance
93 Exporter
94 Archive::Zip Common base class, has defs.
95 Archive::Zip::Archive A Zip archive.
96 Archive::Zip::Member Abstract superclass for all members.
97 Archive::Zip::StringMember Member made from a string
98 Archive::Zip::FileMember Member made from an external file
99 Archive::Zip::ZipFileMember Member that lives in a zip file
100 Archive::Zip::NewFileMember Member whose data is in a file
101 Archive::Zip::DirectoryMember Member that is a directory
102
103EXPORTS
104 :CONSTANTS
105 Exports the following constants:
106
107 FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK GPBF_DEFLATING_COMPRESSION_MASK
108 GPBF_HAS_DATA_DESCRIPTOR_MASK COMPRESSION_STORED
109 COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK IFA_TEXT_FILE
110 IFA_BINARY_FILE COMPRESSION_LEVEL_NONE COMPRESSION_LEVEL_DEFAULT
111 COMPRESSION_LEVEL_FASTEST COMPRESSION_LEVEL_BEST_COMPRESSION
112
113 :MISC_CONSTANTS
114 Exports the following constants (only necessary for extending the
115 module):
116
117 FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS FA_MACINTOSH
118 FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
119 GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
120 GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
121 GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
122 DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
123 DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
124 COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
125 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
126 COMPRESSION_DEFLATED_ENHANCED
127 COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
128
129 :ERROR_CODES
130 Explained below. Returned from most methods.
131
132 AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
133
134ERROR CODES
135 Many of the methods in Archive::Zip return error codes. These are
136 implemented as inline subroutines, using the "use constant" pragma. They
137 can be imported into your namespace using the ":ERROR_CODES" tag:
138
139 use Archive::Zip qw( :ERROR_CODES );
140
141 ...
142
143 unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {
144 die "whoops!";
145 }
146
147 AZ_OK (0)
148 Everything is fine.
149
150 AZ_STREAM_END (1)
151 The read stream (or central directory) ended normally.
152
153 AZ_ERROR (2)
154 There was some generic kind of error.
155
156 AZ_FORMAT_ERROR (3)
157 There is a format error in a ZIP file being read.
158
159 AZ_IO_ERROR (4)
160 There was an IO error.
161
162 Compression
163 Archive::Zip allows each member of a ZIP file to be compressed (using
164 the Deflate algorithm) or uncompressed.
165
166 Other compression algorithms that some versions of ZIP have been able to
167 produce are not supported. Each member has two compression methods: the
168 one it's stored as (this is always COMPRESSION_STORED for string and
169 external file members), and the one you desire for the member in the zip
170 file.
171
172 These can be different, of course, so you can make a zip member that is
173 not compressed out of one that is, and vice versa.
174
175 You can inquire about the current compression and set the desired
176 compression method:
177
178 my $member = $zip->memberNamed( 'xyz.txt' );
179 $member->compressionMethod(); # return current compression
180
181 # set to read uncompressed
182 $member->desiredCompressionMethod( COMPRESSION_STORED );
183
184 # set to read compressed
185 $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
186
187 There are two different compression methods:
188
189 COMPRESSION_STORED
190 File is stored (no compression)
191
192 COMPRESSION_DEFLATED
193 File is Deflated
194
195 Compression Levels
196 If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can
197 choose different compression levels. This choice may affect the speed of
198 compression and decompression, as well as the size of the compressed
199 member data.
200
201 $member->desiredCompressionLevel( 9 );
202
203 The levels given can be:
204
205 0 or COMPRESSION_LEVEL_NONE
206 This is the same as saying
207
208 $member->desiredCompressionMethod( COMPRESSION_STORED );
209
210 1 .. 9
211 1 gives the best speed and worst compression, and 9 gives the best
212 compression and worst speed.
213
214 COMPRESSION_LEVEL_FASTEST
215 This is a synonym for level 1.
216
217 COMPRESSION_LEVEL_BEST_COMPRESSION
218 This is a synonym for level 9.
219
220 COMPRESSION_LEVEL_DEFAULT
221 This gives a good compromise between speed and compression, and is
222 currently equivalent to 6 (this is in the zlib code). This is the
223 level that will be used if not specified.
224
225Archive::Zip Methods
226 The Archive::Zip class (and its invisible subclass
227 Archive::Zip::Archive) implement generic zip file functionality.
228 Creating a new Archive::Zip object actually makes an
229 Archive::Zip::Archive object, but you don't have to worry about this
230 unless you're subclassing.
231
232 Constructor
233 new( [$fileName] )
234 Make a new, empty zip archive.
235
236 my $zip = Archive::Zip->new();
237
238 If an additional argument is passed, new() will call read() to read
239 the contents of an archive:
240
241 my $zip = Archive::Zip->new( 'xyz.zip' );
242
243 If a filename argument is passed and the read fails for any reason,
244 new will return undef. For this reason, it may be better to call
245 read separately.
246
247 Zip Archive Utility Methods
248 These Archive::Zip methods may be called as functions or as object
249 methods. Do not call them as class methods:
250
251 $zip = Archive::Zip->new();
252 $crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK
253 $crc = $zip->computeCRC32( 'ghijkl' ); # also OK
254 $crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK
255
256 Archive::Zip::computeCRC32( $string [, $crc] )
257 This is a utility function that uses the Compress::Raw::Zlib CRC
258 routine to compute a CRC-32. You can get the CRC of a string:
259
260 $crc = Archive::Zip::computeCRC32( $string );
261
262 Or you can compute the running CRC:
263
264 $crc = 0;
265 $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
266 $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
267
268 Archive::Zip::setChunkSize( $number )
269 Report or change chunk size used for reading and writing. This can
270 make big differences in dealing with large files. Currently, this
271 defaults to 32K. This also changes the chunk size used for
272 Compress::Raw::Zlib. You must call setChunkSize() before reading or
273 writing. This is not exportable, so you must call it like:
274
275 Archive::Zip::setChunkSize( 4096 );
276
277 or as a method on a zip (though this is a global setting). Returns
278 old chunk size.
279
280 Archive::Zip::chunkSize()
281 Returns the current chunk size:
282
283 my $chunkSize = Archive::Zip::chunkSize();
284
285 Archive::Zip::setErrorHandler( \&subroutine )
286 Change the subroutine called with error strings. This defaults to
287 \&Carp::carp, but you may want to change it to get the error
288 strings. This is not exportable, so you must call it like:
289
290 Archive::Zip::setErrorHandler( \&myErrorHandler );
291
292 If myErrorHandler is undef, resets handler to default. Returns old
293 error handler. Note that if you call Carp::carp or a similar routine
294 or if you're chaining to the default error handler from your error
295 handler, you may want to increment the number of caller levels that
296 are skipped (do not just set it to a number):
297
298 $Carp::CarpLevel++;
299
300 Archive::Zip::tempFile( [$tmpdir] )
301 Create a uniquely named temp file. It will be returned open for
302 read/write. If $tmpdir is given, it is used as the name of a
303 directory to create the file in. If not given, creates the file
304 using "File::Spec::tmpdir()". Generally, you can override this
305 choice using the
306
307 $ENV{TMPDIR}
308
309 environment variable. But see the File::Spec documentation for your
310 system. Note that on many systems, if you're running in taint mode,
311 then you must make sure that $ENV{TMPDIR} is untainted for it to be
312 used. Will *NOT* create $tmpdir if it doesn't exist (this is a
313 change from prior versions!). Returns file handle and name:
314
315 my ($fh, $name) = Archive::Zip::tempFile();
316 my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
317 my $fh = Archive::Zip::tempFile(); # if you don't need the name
318
319 Zip Archive Accessors
320 members()
321 Return a copy of the members array
322
323 my @members = $zip->members();
324
325 numberOfMembers()
326 Return the number of members I have
327
328 memberNames()
329 Return a list of the (internal) file names of the zip members
330
331 memberNamed( $string )
332 Return ref to member whose filename equals given filename or undef.
333 $string must be in Zip (Unix) filename format.
334
335 membersMatching( $regex )
336 Return array of members whose filenames match given regular
337 expression in list context. Returns number of matching members in
338 scalar context.
339
340 my @textFileMembers = $zip->membersMatching( '.*\.txt' );
341 # or
342 my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
343
344 diskNumber()
345 Return the disk that I start on. Not used for writing zips, but
346 might be interesting if you read a zip in. This should be 0, as
347 Archive::Zip does not handle multi-volume archives.
348
349 diskNumberWithStartOfCentralDirectory()
350 Return the disk number that holds the beginning of the central
351 directory. Not used for writing zips, but might be interesting if
352 you read a zip in. This should be 0, as Archive::Zip does not handle
353 multi-volume archives.
354
355 numberOfCentralDirectoriesOnThisDisk()
356 Return the number of CD structures in the zipfile last read in. Not
357 used for writing zips, but might be interesting if you read a zip
358 in.
359
360 numberOfCentralDirectories()
361 Return the number of CD structures in the zipfile last read in. Not
362 used for writing zips, but might be interesting if you read a zip
363 in.
364
365 centralDirectorySize()
366 Returns central directory size, as read from an external zip file.
367 Not used for writing zips, but might be interesting if you read a
368 zip in.
369
370 centralDirectoryOffsetWRTStartingDiskNumber()
371 Returns the offset into the zip file where the CD begins. Not used
372 for writing zips, but might be interesting if you read a zip in.
373
374 zipfileComment( [$string] )
375 Get or set the zipfile comment. Returns the old comment.
376
377 print $zip->zipfileComment();
378 $zip->zipfileComment( 'New Comment' );
379
380 eocdOffset()
381 Returns the (unexpected) number of bytes between where the EOCD was
382 found and where it expected to be. This is normally 0, but would be
383 positive if something (a virus, perhaps) had added bytes somewhere
384 before the EOCD. Not used for writing zips, but might be interesting
385 if you read a zip in. Here is an example of how you can diagnose
386 this:
387
388 my $zip = Archive::Zip->new('somefile.zip');
389 if ($zip->eocdOffset())
390 {
391 warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
392 }
393
394 The "eocdOffset()" is used to adjust the starting position of member
395 headers, if necessary.
396
397 fileName()
398 Returns the name of the file last read from. If nothing has been
399 read yet, returns an empty string; if read from a file handle,
400 returns the handle in string form.
401
402 Zip Archive Member Operations
403 Various operations on a zip file modify members. When a member is passed
404 as an argument, you can either use a reference to the member itself, or
405 the name of a member. Of course, using the name requires that names be
406 unique within a zip (this is not enforced).
407
408 removeMember( $memberOrName )
409 Remove and return the given member, or match its name and remove it.
410 Returns undef if member or name doesn't exist in this Zip. No-op if
411 member does not belong to this zip.
412
413 replaceMember( $memberOrName, $newMember )
414 Remove and return the given member, or match its name and remove it.
415 Replace with new member. Returns undef if member or name doesn't
416 exist in this Zip, or if $newMember is undefined.
417
418 It is an (undiagnosed) error to provide a $newMember that is a
419 member of the zip being modified.
420
421 my $member1 = $zip->removeMember( 'xyz' );
422 my $member2 = $zip->replaceMember( 'abc', $member1 );
423 # now, $member2 (named 'abc') is not in $zip,
424 # and $member1 (named 'xyz') is, having taken $member2's place.
425
426 extractMember( $memberOrName [, $extractedName ] )
427 Extract the given member, or match its name and extract it. Returns
428 undef if member doesn't exist in this Zip. If optional second arg is
429 given, use it as the name of the extracted member. Otherwise, the
430 internal filename of the member is used as the name of the extracted
431 file or directory. If you pass $extractedName, it should be in the
432 local file system's format. All necessary directories will be
433 created. Returns "AZ_OK" on success.
434
435 extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
436 Extract the given member, or match its name and extract it. Does not
437 use path information (extracts into the current directory). Returns
438 undef if member doesn't exist in this Zip. If optional second arg is
439 given, use it as the name of the extracted member (its paths will be
440 deleted too). Otherwise, the internal filename of the member (minus
441 paths) is used as the name of the extracted file or directory.
442 Returns "AZ_OK" on success.
443
444 addMember( $member )
445 Append a member (possibly from another zip file) to the zip file.
446 Returns the new member. Generally, you will use addFile(),
447 addDirectory(), addFileOrDirectory(), addString(), or read() to add
448 members.
449
450 # Move member named 'abc' to end of zip:
451 my $member = $zip->removeMember( 'abc' );
452 $zip->addMember( $member );
453
454 updateMember( $memberOrName, $fileName )
455 Update a single member from the file or directory named $fileName.
456 Returns the (possibly added or updated) member, if any; "undef" on
457 errors. The comparison is based on "lastModTime()" and (in the case
458 of a non-directory) the size of the file.
459
460 addFile( $fileName [, $newName ] )
461 Append a member whose data comes from an external file, returning
462 the member or undef. The member will have its file name set to the
463 name of the external file, and its desiredCompressionMethod set to
464 COMPRESSION_DEFLATED. The file attributes and last modification time
465 will be set from the file. If the name given does not represent a
466 readable plain file or symbolic link, undef will be returned.
467 $fileName must be in the format required for the local file system.
468 The optional $newName argument sets the internal file name to
469 something different than the given $fileName. $newName, if given,
470 must be in Zip name format (i.e. Unix). The text mode bit will be
471 set if the contents appears to be text (as returned by the "-T" perl
472 operator).
473
474 *NOTE* that you shouldn't (generally) use absolute path names in zip
475 member names, as this will cause problems with some zip tools as
476 well as introduce a security hole and make the zip harder to use.
477
478 addDirectory( $directoryName [, $fileName ] )
479 Append a member created from the given directory name. The directory
480 name does not have to name an existing directory. If the named
481 directory exists, the file modification time and permissions are set
482 from the existing directory, otherwise they are set to now and
483 permissive default permissions. $directoryName must be in local file
484 system format. The optional second argument sets the name of the
485 archive member (which defaults to $directoryName). If given, it must
486 be in Zip (Unix) format. Returns the new member.
487
488 addFileOrDirectory( $name [, $newName ] )
489 Append a member from the file or directory named $name. If $newName
490 is given, use it for the name of the new member. Will add or remove
491 trailing slashes from $newName as needed. $name must be in local
492 file system format. The optional second argument sets the name of
493 the archive member (which defaults to $name). If given, it must be
494 in Zip (Unix) format.
495
496 addString( $stringOrStringRef, $name )
497 Append a member created from the given string or string reference.
498 The name is given by the second argument. Returns the new member.
499 The last modification time will be set to now, and the file
500 attributes will be set to permissive defaults.
501
502 my $member = $zip->addString( 'This is a test', 'test.txt' );
503
504 contents( $memberOrMemberName [, $newContents ] )
505 Returns the uncompressed data for a particular member, or undef.
506
507 print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
508
509 Also can change the contents of a member:
510
511 $zip->contents( 'xyz.txt', 'This is the new contents' );
512
513 If called expecting an array as the return value, it will include
514 the status as the second value in the array.
515
516 ($content, $status) = $zip->contents( 'xyz.txt');
517
518 Zip Archive I/O operations
519 A Zip archive can be written to a file or file handle, or read from one.
520
521 writeToFileNamed( $fileName )
522 Write a zip archive to named file. Returns "AZ_OK" on success.
523
524 my $status = $zip->writeToFileNamed( 'xx.zip' );
525 die "error somewhere" if $status != AZ_OK;
526
527 Note that if you use the same name as an existing zip file that you
528 read in, you will clobber ZipFileMembers. So instead, write to a
529 different file name, then delete the original. If you use the
530 "overwrite()" or "overwriteAs()" methods, you can re-write the
531 original zip in this way. $fileName should be a valid file name on
532 your system.
533
534 writeToFileHandle( $fileHandle [, $seekable] )
535 Write a zip archive to a file handle. Return AZ_OK on success. The
536 optional second arg tells whether or not to try to seek backwards to
537 re-write headers. If not provided, it is set if the Perl "-f" test
538 returns true. This could fail on some operating systems, though.
539
540 my $fh = IO::File->new( 'someFile.zip', 'w' );
541 unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {
542 # error handling
543 }
544
545 If you pass a file handle that is not seekable (like if you're
546 writing to a pipe or a socket), pass a false second argument:
547
548 my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
549 $zip->writeToFileHandle( $fh, 0 ); # fh is not seekable
550
551 If this method fails during the write of a member, that member and
552 all following it will return false from "wasWritten()". See
553 writeCentralDirectory() for a way to deal with this. If you want,
554 you can write data to the file handle before passing it to
555 writeToFileHandle(); this could be used (for instance) for making
556 self-extracting archives. However, this only works reliably when
557 writing to a real file (as opposed to STDOUT or some other possible
558 non-file).
559
560 See examples/selfex.pl for how to write a self-extracting archive.
561
562 writeCentralDirectory( $fileHandle [, $offset ] )
563 Writes the central directory structure to the given file handle.
564
565 Returns AZ_OK on success. If given an $offset, will seek to that
566 point before writing. This can be used for recovery in cases where
567 writeToFileHandle or writeToFileNamed returns an IO error because of
568 running out of space on the destination file.
569
570 You can truncate the zip by seeking backwards and then writing the
571 directory:
572
573 my $fh = IO::File->new( 'someFile.zip', 'w' );
574 my $retval = $zip->writeToFileHandle( $fh );
575 if ( $retval == AZ_IO_ERROR ) {
576 my @unwritten = grep { not $_->wasWritten() } $zip->members();
577 if (@unwritten) {
578 $zip->removeMember( $member ) foreach my $member ( @unwritten );
579 $zip->writeCentralDirectory( $fh,
580 $unwritten[0]->writeLocalHeaderRelativeOffset());
581 }
582 }
583
584 overwriteAs( $newName )
585 Write the zip to the specified file, as safely as possible. This is
586 done by first writing to a temp file, then renaming the original if
587 it exists, then renaming the temp file, then deleting the renamed
588 original if it exists. Returns AZ_OK if successful.
589
590 overwrite()
591 Write back to the original zip file. See overwriteAs() above. If the
592 zip was not ever read from a file, this generates an error.
593
594 read( $fileName )
595 Read zipfile headers from a zip file, appending new members. Returns
596 "AZ_OK" or error code.
597
598 my $zipFile = Archive::Zip->new();
599 my $status = $zipFile->read( '/some/FileName.zip' );
600
601 readFromFileHandle( $fileHandle, $filename )
602 Read zipfile headers from an already-opened file handle, appending
603 new members. Does not close the file handle. Returns "AZ_OK" or
604 error code. Note that this requires a seekable file handle; reading
605 from a stream is not yet supported.
606
607 my $fh = IO::File->new( '/some/FileName.zip', 'r' );
608 my $zip1 = Archive::Zip->new();
609 my $status = $zip1->readFromFileHandle( $fh );
610 my $zip2 = Archive::Zip->new();
611 $status = $zip2->readFromFileHandle( $fh );
612
613 Zip Archive Tree operations
614 These used to be in Archive::Zip::Tree but got moved into Archive::Zip.
615 They enable operation on an entire tree of members or files. A usage
616 example:
617
618 use Archive::Zip;
619 my $zip = Archive::Zip->new();
620
621 # add all readable files and directories below . as xyz/*
622 $zip->addTree( '.', 'xyz' );
623
624 # add all readable plain files below /abc as def/*
625 $zip->addTree( '/abc', 'def', sub { -f && -r } );
626
627 # add all .c files below /tmp as stuff/*
628 $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
629
630 # add all .o files below /tmp as stuff/* if they aren't writable
631 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
632
633 # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
634 $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
635
636 # and write them into a file
637 $zip->writeToFileNamed('xxx.zip');
638
639 # now extract the same files into /tmpx
640 $zip->extractTree( 'stuff', '/tmpx' );
641
642 $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
643 $root is the root of the tree of files and directories to be added.
644 It is a valid directory name on your system. $dest is the name for
645 the root in the zip file (undef or blank means to use relative
646 pathnames). It is a valid ZIP directory name (that is, it uses
647 forward slashes (/) for separating directory components). $pred is
648 an optional subroutine reference to select files: it is passed the
649 name of the prospective file or directory using $_, and if it
650 returns true, the file or directory will be included. The default is
651 to add all readable files and directories. For instance, using
652
653 my $pred = sub { /\.txt/ };
654 $zip->addTree( '.', '', $pred );
655
656 will add all the .txt files in and below the current directory,
657 using relative names, and making the names identical in the zipfile:
658
659 original name zip member name
660 ./xyz xyz
661 ./a/ a/
662 ./a/b a/b
663
664 To translate absolute to relative pathnames, just pass them in:
665 $zip->addTree( '/c/d', 'a' );
666
667 original name zip member name
668 /c/d/xyz a/xyz
669 /c/d/a/ a/a/
670 /c/d/a/b a/a/b
671
672 Returns AZ_OK on success. Note that this will not follow symbolic
673 links to directories. Note also that this does not check for the
674 validity of filenames.
675
676 Note that you generally *don't* want to make zip archive member
677 names absolute.
678
679 $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
680 $root is the root of the tree of files and directories to be added
681 $dest is the name for the root in the zip file (undef means to use
682 relative pathnames) $pattern is a (non-anchored) regular expression
683 for filenames to match $pred is an optional subroutine reference to
684 select files: it is passed the name of the prospective file or
685 directory in $_, and if it returns true, the file or directory will
686 be included. The default is to add all readable files and
687 directories. To add all files in and below the current dirctory
688 whose names end in ".pl", and make them extract into a subdirectory
689 named "xyz", do this:
690
691 $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
692
693 To add all *writable* files in and below the dirctory named "/abc"
694 whose names end in ".pl", and make them extract into a subdirectory
695 named "xyz", do this:
696
697 $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
698
699 Returns AZ_OK on success. Note that this will not follow symbolic
700 links to directories.
701
702 $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
703 Update a zip file from a directory tree.
704
705 "updateTree()" takes the same arguments as "addTree()", but first
706 checks to see whether the file or directory already exists in the
707 zip file, and whether it has been changed.
708
709 If the fourth argument $mirror is true, then delete all my members
710 if corresponding files weren't found.
711
712 Returns an error code or AZ_OK if all is well.
713
714 $zip->extractTree()
715 $zip->extractTree( $root )
716 $zip->extractTree( $root, $dest )
717 $zip->extractTree( $root, $dest, $volume )
718 If you don't give any arguments at all, will extract all the files
719 in the zip with their original names.
720
721 If you supply one argument for $root, "extractTree" will extract all
722 the members whose names start with $root into the current directory,
723 stripping off $root first. $root is in Zip (Unix) format. For
724 instance,
725
726 $zip->extractTree( 'a' );
727
728 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
729 will extract:
730
731 a/x as ./x
732
733 a/b/c as ./b/c
734
735 If you give two arguments, "extractTree" extracts all the members
736 whose names start with $root. It will translate $root into $dest to
737 construct the destination file name. $root and $dest are in Zip
738 (Unix) format. For instance,
739
740 $zip->extractTree( 'a', 'd/e' );
741
742 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
743 will extract:
744
745 a/x to d/e/x
746
747 a/b/c to d/e/b/c and ignore ax/d/e and d/e
748
749 If you give three arguments, "extractTree" extracts all the members
750 whose names start with $root. It will translate $root into $dest to
751 construct the destination file name, and then it will convert to
752 local file system format, using $volume as the name of the
753 destination volume.
754
755 $root and $dest are in Zip (Unix) format.
756
757 $volume is in local file system format.
758
759 For instance, under Windows,
760
761 $zip->extractTree( 'a', 'd/e', 'f:' );
762
763 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
764 will extract:
765
766 a/x to f:d/e/x
767
768 a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
769
770 If you want absolute paths (the prior example used paths relative to
771 the current directory on the destination volume, you can specify
772 these in $dest:
773
774 $zip->extractTree( 'a', '/d/e', 'f:' );
775
776 when applied to a zip containing the files: a/x a/b/c ax/d/e d/e
777 will extract:
778
779 a/x to f:\d\e\x
780
781 a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
782
783 Returns an error code or AZ_OK if everything worked OK.
784
785MEMBER OPERATIONS
786 Member Class Methods
787 Several constructors allow you to construct members without adding them
788 to a zip archive. These work the same as the addFile(), addDirectory(),
789 and addString() zip instance methods described above, but they don't add
790 the new members to a zip.
791
792 Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
793 Construct a new member from the given string. Returns undef on
794 error.
795
796 my $member = Archive::Zip::Member->newFromString( 'This is a test',
797 'xyz.txt' );
798
799 newFromFile( $fileName )
800 Construct a new member from the given file. Returns undef on error.
801
802 my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
803
804 newDirectoryNamed( $directoryName [, $zipname ] )
805 Construct a new member from the given directory. $directoryName must
806 be a valid name on your file system; it doesn't have to exist.
807
808 If given, $zipname will be the name of the zip member; it must be a
809 valid Zip (Unix) name. If not given, it will be converted from
810 $directoryName.
811
812 Returns undef on error.
813
814 my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
815
816 Member Simple accessors
817 These methods get (and/or set) member attribute values.
818
819 versionMadeBy()
820 Gets the field from the member header.
821
822 fileAttributeFormat( [$format] )
823 Gets or sets the field from the member header. These are "FA_*"
824 values.
825
826 versionNeededToExtract()
827 Gets the field from the member header.
828
829 bitFlag()
830 Gets the general purpose bit field from the member header. This is
831 where the "GPBF_*" bits live.
832
833 compressionMethod()
834 Returns the member compression method. This is the method that is
835 currently being used to compress the member data. This will be
836 COMPRESSION_STORED for added string or file members, or any of the
837 "COMPRESSION_*" values for members from a zip file. However, this
838 module can only handle members whose data is in COMPRESSION_STORED
839 or COMPRESSION_DEFLATED format.
840
841 desiredCompressionMethod( [$method] )
842 Get or set the member's "desiredCompressionMethod". This is the
843 compression method that will be used when the member is written.
844 Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED or
845 COMPRESSION_STORED are valid arguments. Changing to
846 COMPRESSION_STORED will change the member desiredCompressionLevel to
847 0; changing to COMPRESSION_DEFLATED will change the member
848 desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
849
850 desiredCompressionLevel( [$method] )
851 Get or set the member's desiredCompressionLevel This is the method
852 that will be used to write. Returns prior desiredCompressionLevel.
853 Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE,
854 COMPRESSION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and
855 COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change
856 the desiredCompressionMethod to COMPRESSION_STORED. All other
857 arguments will change the desiredCompressionMethod to
858 COMPRESSION_DEFLATED.
859
860 externalFileName()
861 Return the member's external file name, if any, or undef.
862
863 fileName()
864 Get or set the member's internal filename. Returns the (possibly
865 new) filename. Names will have backslashes converted to forward
866 slashes, and will have multiple consecutive slashes converted to
867 single ones.
868
869 lastModFileDateTime()
870 Return the member's last modification date/time stamp in MS-DOS
871 format.
872
873 lastModTime()
874 Return the member's last modification date/time stamp, converted to
875 unix localtime format.
876
877 print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
878
879 setLastModFileDateTimeFromUnix()
880 Set the member's lastModFileDateTime from the given unix time.
881
882 $member->setLastModFileDateTimeFromUnix( time() );
883
884 internalFileAttributes()
885 Return the internal file attributes field from the zip header. This
886 is only set for members read from a zip file.
887
888 externalFileAttributes()
889 Return member attributes as read from the ZIP file. Note that these
890 are NOT UNIX!
891
892 unixFileAttributes( [$newAttributes] )
893 Get or set the member's file attributes using UNIX file attributes.
894 Returns old attributes.
895
896 my $oldAttribs = $member->unixFileAttributes( 0666 );
897
898 Note that the return value has more than just the file permissions,
899 so you will have to mask off the lowest bits for comparisions.
900
901 localExtraField( [$newField] )
902 Gets or sets the extra field that was read from the local header.
903 This is not set for a member from a zip file until after the member
904 has been written out. The extra field must be in the proper format.
905
906 cdExtraField( [$newField] )
907 Gets or sets the extra field that was read from the central
908 directory header. The extra field must be in the proper format.
909
910 extraFields()
911 Return both local and CD extra fields, concatenated.
912
913 fileComment( [$newComment] )
914 Get or set the member's file comment.
915
916 hasDataDescriptor()
917 Get or set the data descriptor flag. If this is set, the local
918 header will not necessarily have the correct data sizes. Instead, a
919 small structure will be stored at the end of the member data with
920 these values. This should be transparent in normal operation.
921
922 crc32()
923 Return the CRC-32 value for this member. This will not be set for
924 members that were constructed from strings or external files until
925 after the member has been written.
926
927 crc32String()
928 Return the CRC-32 value for this member as an 8 character printable
929 hex string. This will not be set for members that were constructed
930 from strings or external files until after the member has been
931 written.
932
933 compressedSize()
934 Return the compressed size for this member. This will not be set for
935 members that were constructed from strings or external files until
936 after the member has been written.
937
938 uncompressedSize()
939 Return the uncompressed size for this member.
940
941 isEncrypted()
942 Return true if this member is encrypted. The Archive::Zip module
943 does not currently create or extract encrypted members.
944
945 isTextFile( [$flag] )
946 Returns true if I am a text file. Also can set the status if given
947 an argument (then returns old state). Note that this module does not
948 currently do anything with this flag upon extraction or storage.
949 That is, bytes are stored in native format whether or not they came
950 from a text file.
951
952 isBinaryFile()
953 Returns true if I am a binary file. Also can set the status if given
954 an argument (then returns old state). Note that this module does not
955 currently do anything with this flag upon extraction or storage.
956 That is, bytes are stored in native format whether or not they came
957 from a text file.
958
959 extractToFileNamed( $fileName )
960 Extract me to a file with the given name. The file will be created
961 with default modes. Directories will be created as needed. The
962 $fileName argument should be a valid file name on your file system.
963 Returns AZ_OK on success.
964
965 isDirectory()
966 Returns true if I am a directory.
967
968 writeLocalHeaderRelativeOffset()
969 Returns the file offset in bytes the last time I was written.
970
971 wasWritten()
972 Returns true if I was successfully written. Reset at the beginning
973 of a write attempt.
974
975 Low-level member data reading
976 It is possible to use lower-level routines to access member data
977 streams, rather than the extract* methods and contents(). For instance,
978 here is how to print the uncompressed contents of a member in chunks
979 using these methods:
980
981 my ( $member, $status, $bufferRef );
982 $member = $zip->memberNamed( 'xyz.txt' );
983 $member->desiredCompressionMethod( COMPRESSION_STORED );
984 $status = $member->rewindData();
985 die "error $status" unless $status == AZ_OK;
986 while ( ! $member->readIsDone() )
987 {
988 ( $bufferRef, $status ) = $member->readChunk();
989 die "error $status"
990 if $status != AZ_OK && $status != AZ_STREAM_END;
991 # do something with $bufferRef:
992 print $$bufferRef;
993 }
994 $member->endRead();
995
996 readChunk( [$chunkSize] )
997 This reads the next chunk of given size from the member's data
998 stream and compresses or uncompresses it as necessary, returning a
999 reference to the bytes read and a status. If size argument is not
1000 given, defaults to global set by Archive::Zip::setChunkSize. Status
1001 is AZ_OK on success until the last chunk, where it returns
1002 AZ_STREAM_END. Returns "( \$bytes, $status)".
1003
1004 my ( $outRef, $status ) = $self->readChunk();
1005 print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1006
1007 rewindData()
1008 Rewind data and set up for reading data streams or writing zip
1009 files. Can take options for "inflateInit()" or "deflateInit()", but
1010 this isn't likely to be necessary. Subclass overrides should call
1011 this method. Returns "AZ_OK" on success.
1012
1013 endRead()
1014 Reset the read variables and free the inflater or deflater. Must be
1015 called to close files, etc. Returns AZ_OK on success.
1016
1017 readIsDone()
1018 Return true if the read has run out of data or errored out.
1019
1020 contents()
1021 Return the entire uncompressed member data or undef in scalar
1022 context. When called in array context, returns "( $string, $status
1023 )"; status will be AZ_OK on success:
1024
1025 my $string = $member->contents();
1026 # or
1027 my ( $string, $status ) = $member->contents();
1028 die "error $status" unless $status == AZ_OK;
1029
1030 Can also be used to set the contents of a member (this may change
1031 the class of the member):
1032
1033 $member->contents( "this is my new contents" );
1034
1035 extractToFileHandle( $fh )
1036 Extract (and uncompress, if necessary) the member's contents to the
1037 given file handle. Return AZ_OK on success.
1038
1039Archive::Zip::FileMember methods
1040 The Archive::Zip::FileMember class extends Archive::Zip::Member. It is
1041 the base class for both ZipFileMember and NewFileMember classes. This
1042 class adds an "externalFileName" and an "fh" member to keep track of the
1043 external file.
1044
1045 externalFileName()
1046 Return the member's external filename.
1047
1048 fh()
1049 Return the member's read file handle. Automatically opens file if
1050 necessary.
1051
1052Archive::Zip::ZipFileMember methods
1053 The Archive::Zip::ZipFileMember class represents members that have been
1054 read from external zip files.
1055
1056 diskNumberStart()
1057 Returns the disk number that the member's local header resides in.
1058 Should be 0.
1059
1060 localHeaderRelativeOffset()
1061 Returns the offset into the zip file where the member's local header
1062 is.
1063
1064 dataOffset()
1065 Returns the offset from the beginning of the zip file to the
1066 member's data.
1067
1068REQUIRED MODULES
1069 Archive::Zip requires several other modules:
1070
1071 Carp
1072
1073 Compress::Raw::Zlib
1074
1075 Cwd
1076
1077 File::Basename
1078
1079 File::Copy
1080
1081 File::Find
1082
1083 File::Path
1084
1085 File::Spec
1086
1087 IO::File
1088
1089 IO::Seekable
1090
1091 Time::Local
1092
1093BUGS AND CAVEATS
1094 When not to use Archive::Zip
1095 If you are just going to be extracting zips (and/or other archives) you
1096 are recommended to look at using Archive::Extract instead, as it is much
1097 easier to use and factors out archive-specific functionality.
1098
1099 Try to avoid IO::Scalar
1100 One of the most common ways to use Archive::Zip is to generate Zip files
1101 in-memory. Most people have use IO::Scalar for this purpose.
1102
1103 Unfortunately, as of 1.11 this module no longer works with IO::Scalar as
1104 it incorrectly implements seeking.
1105
1106 Anybody using IO::Scalar should consider porting to IO::String, which is
1107 smaller, lighter, and is implemented to be perfectly compatible with
1108 regular seekable filehandles.
1109
1110 Support for IO::Scalar most likely will not be restored in the future,
1111 as IO::Scalar itself cannot change the way it is implemented due to
1112 back-compatibility issues.
1113
1114TO DO
1115 * auto-choosing storing vs compression
1116
1117 * extra field hooks (see notes.txt)
1118
1119 * check for dups on addition/renaming?
1120
1121 * Text file extraction (line end translation)
1122
1123 * Reading zip files from non-seekable inputs (Perhaps by proxying
1124 through IO::String?)
1125
1126 * separate unused constants into separate module
1127
1128 * cookbook style docs
1129
1130 * Handle tainted paths correctly
1131
1132 * Work on better compatability with other IO:: modules
1133
1134SUPPORT
1135 Bugs should be reported via the CPAN bug tracker
1136
1137 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>
1138
1139 For other issues contact the maintainer
1140
1141AUTHOR
1142 Adam Kennedy <adamk@cpan.org>
1143
1144 Previously maintained by Steve Peters <steve@fisharerojo.org>.
1145
1146 File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>.
1147
1148 Originally by Ned Konz <nedkonz@cpan.org>.
1149
1150COPYRIGHT
1151 Some parts copyright 2006 - 2009 Adam Kennedy.
1152
1153 Some parts copyright 2005 Steve Peters.
1154
1155 Original work copyright 2000 - 2004 Ned Konz.
1156
1157 This program is free software; you can redistribute it and/or modify it
1158 under the same terms as Perl itself.
1159
1160SEE ALSO
1161 Look at Archive::Zip::MemberRead which is a wrapper that allows one to
1162 read Zip archive members as if they were files.
1163
1164 Compress::Raw::Zlib, Archive::Tar, Archive::Extract
1165
1166 There is a Japanese translation of this document at
1167 <http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html> that was done by
1168 DEQ <deq@oct.zaq.ne.jp> . Thanks!
1169
1170