« back to all changes in this revision
Viewing changes to lib/Archive/Zip.pod
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Matthias Klose
- Date: 2004-10-30 22:19:15 UTC
- mfrom: (1.2.1 upstream) (2.1.1 warty)
- Revision ID: james.westby@ubuntu.com-20041030221915-gtxn2xoojblyekyh
Tags: 1.14-1
* New upstream version.
- Fixes: Archive::Zip is fooled by manipulated ZIP directory
Closes: #277773.
- Fixes: Archive::Zip is fooled by manipulated ZIP directory
Closes: #277773.
added
removed
lib/Archive/Zip.pod
1
2
=head1 NAME
3
4
5
Archive::Zip - Provide an interface to ZIP archive files.
6
7
=head1 SYNOPSIS
8
9
10
use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
11
my $zip = Archive::Zip->new();
12
my $member = $zip->addDirectory( 'dirname/' );
13
$member = $zip->addString( 'This is a test', 'stringMember.txt' );
14
$member->desiredCompressionMethod( COMPRESSION_DEFLATED );
15
$member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
16
die 'write error' unless $zip->writeToFileNamed( 'someZip.zip' ) == AZ_OK;
17
$zip = Archive::Zip->new();
18
die 'read error' unless $zip->read( 'someZip.zip' ) == AZ_OK;
19
$member = $zip->memberNamed( 'stringMember.txt' );
20
$member->desiredCompressionMethod( COMPRESSION_STORED );
21
die 'write error' unless $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK;
22
23
=head1 DESCRIPTION
24
25
26
The Archive::Zip module allows a Perl program to create, manipulate, read,
27
and write Zip archive files. Zip archives can be created, or you can read
28
from existing zip files. Once created, they can be written to files, streams,
29
or strings. Members can be added, removed, extracted, replaced, rearranged,
30
and enumerated. They can also be renamed or have their dates, comments, or
31
other attributes queried or modified. Their data can be compressed or
32
uncompressed as needed. Members can be created from members in existing Zip
33
files, or from existing directories, files, or strings. This module uses the
34
L<Compress::Zlib|Compress::Zlib> library to read and write the compressed
35
streams inside the files.
36
37
=head1 FILE NAMING
38
39
40
Regardless of what your local file system uses for file naming, names in a
41
Zip file are in Unix format (I<forward> slashes (/) separating directory
42
names, etc.).
43
C<Archive::Zip> tries to be consistent with file naming
44
conventions, and will
45
translate back and forth between native and Zip file names.
46
However, it can't guess which format names are in. So two rules control what
47
kind of file name you must pass various routines:
48
49
=over 4
50
51
=item Names of files are in local format.
52
53
54
55
C<File::Spec> and C<File::Basename> are used for various file
56
operations. When you're referring to a file on your system, use its
57
file naming conventions.
58
59
=item Names of archive members are in Unix format.
60
61
62
63
This applies to every method that refers to an archive member, or
64
provides a name for new archive members. The C<extract()> methods
65
that can take one or two names will convert from local to zip names
66
if you call them with a single name.
67
68
=back
69
70
=head1 OBJECT MODEL
71
72
73
=head2 Overview
74
75
76
Archive::Zip::Archive objects are what you ordinarily deal with.
77
These maintain the structure of a zip file, without necessarily
78
holding data. When a zip is read from a disk file, the (possibly
79
compressed) data still lives in the file, not in memory. Archive
80
members hold information about the individual members, but not
81
(usually) the actual member data. When the zip is written to a
82
(different) file, the member data is compressed or copied as needed.
83
It is possible to make archive members whose data is held in a string
84
in memory, but this is not done when a zip file is read. Directory
85
members don't have any data.
86
87
=head2 Inheritance
88
89
90
Exporter
91
Archive::Zip Common base class, has defs.
92
Archive::Zip::Archive A Zip archive.
93
Archive::Zip::Member Abstract superclass for all members.
94
Archive::Zip::StringMember Member made from a string
95
Archive::Zip::FileMember Member made from an external file
96
Archive::Zip::ZipFileMember Member that lives in a zip file
97
Archive::Zip::NewFileMember Member whose data is in a file
98
Archive::Zip::DirectoryMember Member that is a directory
99
100
=head1 EXPORTS
101
102
103
=over 4
104
105
=item :CONSTANTS
106
107
108
109
Exports the following constants: FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK
110
GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK
111
COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK
112
IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE
113
COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST
114
COMPRESSION_LEVEL_BEST_COMPRESSION
115
116
=item :MISC_CONSTANTS
117
118
119
120
Exports the following constants (only necessary for extending the
121
module): FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS
122
FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
123
GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
124
GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
125
GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
126
DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
127
DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
128
COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
129
COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
130
COMPRESSION_DEFLATED_ENHANCED
131
COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
132
133
=item :ERROR_CODES
134
135
136
137
Explained below. Returned from most methods. AZ_OK AZ_STREAM_END
138
AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
139
140
=back
141
142
=head1 ERROR CODES
143
144
145
Many of the methods in Archive::Zip return error codes. These are implemented
146
as inline subroutines, using the C<use constant> pragma. They can be imported
147
into your namespace using the C<:ERROR_CODES> tag:
148
149
use Archive::Zip qw( :ERROR_CODES );
150
...
151
die "whoops!" unless $zip->read( 'myfile.zip' ) == AZ_OK;
152
153
=over 4
154
155
=item AZ_OK (0)
156
157
158
159
Everything is fine.
160
161
=item AZ_STREAM_END (1)
162
163
164
165
The read stream (or central directory) ended normally.
166
167
=item AZ_ERROR (2)
168
169
170
171
There was some generic kind of error.
172
173
=item AZ_FORMAT_ERROR (3)
174
175
176
177
There is a format error in a ZIP file being read.
178
179
=item AZ_IO_ERROR (4)
180
181
182
183
There was an IO error.
184
185
=back
186
187
=head1 COMPRESSION
188
189
190
Archive::Zip allows each member of a ZIP file to be compressed (using the
191
Deflate algorithm) or uncompressed. Other compression algorithms that some
192
versions of ZIP have been able to produce are not supported. Each member has
193
two compression methods: the one it's stored as (this is always
194
COMPRESSION_STORED for string and external file members), and the one you
195
desire for the member in the zip file. These can be different, of course, so
196
you can make a zip member that is not compressed out of one that is, and vice
197
versa. You can inquire about the current compression and set the desired
198
compression method:
199
200
my $member = $zip->memberNamed( 'xyz.txt' );
201
$member->compressionMethod(); # return current compression
202
# set to read uncompressed
203
$member->desiredCompressionMethod( COMPRESSION_STORED );
204
# set to read compressed
205
$member->desiredCompressionMethod( COMPRESSION_DEFLATED );
206
207
There are two different compression methods:
208
209
=over 4
210
211
=item COMPRESSION_STORED
212
213
214
215
file is stored (no compression)
216
217
=item COMPRESSION_DEFLATED
218
219
220
221
file is Deflated
222
223
=back
224
225
=head2 Compression Levels
226
227
228
If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you
229
can choose different compression levels. This choice may affect the
230
speed of compression and decompression, as well as the size of the
231
compressed member data.
232
233
$member->desiredCompressionLevel( 9 );
234
235
The levels given can be:
236
237
=over 4
238
239
=item 0 or COMPRESSION_LEVEL_NONE
240
241
242
243
This is the same as saying
244
245
$member->desiredCompressionMethod( COMPRESSION_STORED );
246
247
=item 1 .. 9
248
249
250
251
1 gives the best speed and worst compression, and 9 gives the
252
best compression and worst speed.
253
254
=item COMPRESSION_LEVEL_FASTEST
255
256
257
258
This is a synonym for level 1.
259
260
=item COMPRESSION_LEVEL_BEST_COMPRESSION
261
262
263
264
This is a synonym for level 9.
265
266
=item COMPRESSION_LEVEL_DEFAULT
267
268
269
270
This gives a good compromise between speed and compression,
271
and is currently equivalent to 6 (this is in the zlib code).
272
This is the level that will be used if not specified.
273
274
=back
275
276
=head1 Archive::Zip methods
277
278
279
The Archive::Zip class (and its invisible subclass Archive::Zip::Archive)
280
implement generic zip file functionality. Creating a new Archive::Zip object
281
actually makes an Archive::Zip::Archive object, but you don't have to worry
282
about this unless you're subclassing.
283
284
=head2 Constructor
285
286
287
=over 4
288
289
=item new( [$fileName] )
290
291
292
293
Make a new, empty zip archive.
294
295
my $zip = Archive::Zip->new();
296
297
If an additional argument is passed, new() will call read()
298
to read the contents of an archive:
299
300
my $zip = Archive::Zip->new( 'xyz.zip' );
301
302
If a filename argument is passed and the read fails for any
303
reason, new will return undef. For this reason, it may be
304
better to call read separately.
305
306
=back
307
308
=head2 Zip Archive Utility Methods
309
310
311
These Archive::Zip methods may be called as functions or as object
312
methods. Do not call them as class methods:
313
314
$zip = Archive::Zip->new();
315
$crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK
316
$crc = $zip->computeCRC32( 'ghijkl' ); # also OK
317
$crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK
318
319
=over 4
320
321
=item Archive::Zip::computeCRC32( $string [, $crc] )
322
323
324
325
This is a utility function that uses the Compress::Zlib CRC
326
routine to compute a CRC-32. You can get the CRC of a string:
327
328
$crc = Archive::Zip::computeCRC32( $string );
329
330
Or you can compute the running CRC:
331
332
$crc = 0;
333
$crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
334
$crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
335
336
=item Archive::Zip::setChunkSize( $number )
337
338
339
340
Report or change chunk size used for reading and writing.
341
This can make big differences in dealing with large files.
342
Currently, this defaults to 32K. This also changes the chunk
343
size used for Compress::Zlib. You must call setChunkSize()
344
before reading or writing. This is not exportable, so you
345
must call it like:
346
347
Archive::Zip::setChunkSize( 4096 );
348
349
or as a method on a zip (though this is a global setting).
350
Returns old chunk size.
351
352
=item Archive::Zip::chunkSize()
353
354
355
356
Returns the current chunk size:
357
358
my $chunkSize = Archive::Zip::chunkSize();
359
360
=item Archive::Zip::setErrorHandler( \&subroutine )
361
362
363
364
Change the subroutine called with error strings. This
365
defaults to \&Carp::carp, but you may want to change it to
366
get the error strings. This is not exportable, so you must
367
call it like:
368
369
Archive::Zip::setErrorHandler( \&myErrorHandler );
370
371
If myErrorHandler is undef, resets handler to default.
372
Returns old error handler. Note that if you call Carp::carp
373
or a similar routine or if you're chaining to the default
374
error handler from your error handler, you may want to
375
increment the number of caller levels that are skipped (do
376
not just set it to a number):
377
378
$Carp::CarpLevel++;
379
380
=item Archive::Zip::tempFile( [$tmpdir] )
381
382
383
384
Create a uniquely named temp file. It will be returned open
385
for read/write. If C<$tmpdir> is given, it is used as the
386
name of a directory to create the file in. If not given,
387
creates the file using C<File::Spec::tmpdir()>. Generally, you can
388
override this choice using the
389
390
$ENV{TMPDIR}
391
392
environment variable. But see the L<File::Spec|File::Spec>
393
documentation for your system. Note that on many systems, if you're
394
running in taint mode, then you must make sure that C<$ENV{TMPDIR}> is
395
untainted for it to be used.
396
Will I<NOT> create C<$tmpdir> if it doesn't exist (this is a change
397
from prior versions!). Returns file handle and name:
398
399
my ($fh, $name) = Archive::Zip::tempFile();
400
my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
401
my $fh = Archive::Zip::tempFile(); # if you don't need the name
402
403
=back
404
405
=head2 Zip Archive Accessors
406
407
408
=over 4
409
410
=item members()
411
412
413
414
Return a copy of the members array
415
416
my @members = $zip->members();
417
418
=item numberOfMembers()
419
420
421
422
Return the number of members I have
423
424
=item memberNames()
425
426
427
428
Return a list of the (internal) file names of the zip members
429
430
=item memberNamed( $string )
431
432
433
434
Return ref to member whose filename equals given filename or
435
undef. C<$string> must be in Zip (Unix) filename format.
436
437
=item membersMatching( $regex )
438
439
440
441
Return array of members whose filenames match given regular
442
expression in list context. Returns number of matching
443
members in scalar context.
444
445
my @textFileMembers = $zip->membersMatching( '.*\.txt' );
446
# or
447
my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
448
449
=item diskNumber()
450
451
452
453
Return the disk that I start on. Not used for writing zips,
454
but might be interesting if you read a zip in. This should be
455
0, as Archive::Zip does not handle multi-volume archives.
456
457
=item diskNumberWithStartOfCentralDirectory()
458
459
460
461
Return the disk number that holds the beginning of the
462
central directory. Not used for writing zips, but might be
463
interesting if you read a zip in. This should be 0, as
464
Archive::Zip does not handle multi-volume archives.
465
466
=item numberOfCentralDirectoriesOnThisDisk()
467
468
469
470
Return the number of CD structures in the zipfile last read in.
471
Not used for writing zips, but might be interesting if you read a zip
472
in.
473
474
=item numberOfCentralDirectories()
475
476
477
478
Return the number of CD structures in the zipfile last read in.
479
Not used for writing zips, but might be interesting if you read a zip
480
in.
481
482
=item centralDirectorySize()
483
484
485
486
Returns central directory size, as read from an external zip
487
file. Not used for writing zips, but might be interesting if
488
you read a zip in.
489
490
=item centralDirectoryOffsetWRTStartingDiskNumber()
491
492
493
494
Returns the offset into the zip file where the CD begins. Not
495
used for writing zips, but might be interesting if you read a
496
zip in.
497
498
=item zipfileComment( [$string] )
499
500
501
502
Get or set the zipfile comment. Returns the old comment.
503
504
print $zip->zipfileComment();
505
$zip->zipfileComment( 'New Comment' );
506
507
=item eocdOffset()
508
509
510
511
Returns the (unexpected) number of bytes between where the
512
EOCD was found and where it expected to be. This is normally
513
0, but would be positive if something (a virus, perhaps) had
514
added bytes somewhere before the EOCD. Not used for writing
515
zips, but might be interesting if you read a zip in. Here is
516
an example of how you can diagnose this:
517
518
my $zip = Archive::Zip->new('somefile.zip');
519
if ($zip->eocdOffset())
520
{
521
warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
522
}
523
524
The C<eocdOffset()> is used to adjust the starting position of member
525
headers, if necessary.
526
527
=item fileName()
528
529
530
531
Returns the name of the file last read from. If nothing has
532
been read yet, returns an empty string; if read from a file
533
handle, returns the handle in string form.
534
535
=back
536
537
=head2 Zip Archive Member Operations
538
539
540
Various operations on a zip file modify members. When a member is
541
passed as an argument, you can either use a reference to the member
542
itself, or the name of a member. Of course, using the name requires
543
that names be unique within a zip (this is not enforced).
544
545
=over 4
546
547
=item removeMember( $memberOrName )
548
549
550
551
Remove and return the given member, or match its name and
552
remove it. Returns undef if member or name doesn't exist in this
553
Zip. No-op if member does not belong to this zip.
554
555
=item replaceMember( $memberOrName, $newMember )
556
557
558
559
Remove and return the given member, or match its name and
560
remove it. Replace with new member. Returns undef if member or
561
name doesn't exist in this Zip, or if C<$newMember> is undefined.
562
563
564
It is an (undiagnosed) error to provide a C<$newMember> that is a
565
member of the zip being modified.
566
567
my $member1 = $zip->removeMember( 'xyz' );
568
my $member2 = $zip->replaceMember( 'abc', $member1 );
569
# now, $member2 (named 'abc') is not in $zip,
570
# and $member1 (named 'xyz') is, having taken $member2's place.
571
572
=item extractMember( $memberOrName [, $extractedName ] )
573
574
575
576
Extract the given member, or match its name and extract it.
577
Returns undef if member doesn't exist in this Zip. If
578
optional second arg is given, use it as the name of the
579
extracted member. Otherwise, the internal filename of the
580
member is used as the name of the extracted file or
581
directory.
582
If you pass C<$extractedName>, it should be in the local file
583
system's format.
584
All necessary directories will be created. Returns C<AZ_OK>
585
on success.
586
587
=item extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
588
589
590
591
Extract the given member, or match its name and extract it.
592
Does not use path information (extracts into the current
593
directory). Returns undef if member doesn't exist in this
594
Zip.
595
If optional second arg is given, use it as the name of the
596
extracted member (its paths will be deleted too). Otherwise,
597
the internal filename of the member (minus paths) is used as
598
the name of the extracted file or directory. Returns C<AZ_OK>
599
on success.
600
601
=item addMember( $member )
602
603
604
605
Append a member (possibly from another zip file) to the zip
606
file. Returns the new member. Generally, you will use
607
addFile(), addDirectory(), addFileOrDirectory(), addString(),
608
or read() to add members.
609
610
# Move member named 'abc' to end of zip:
611
my $member = $zip->removeMember( 'abc' );
612
$zip->addMember( $member );
613
614
=item updateMember( $memberOrName, $fileName )
615
616
617
618
Update a single member from the file or directory named C<$fileName>.
619
Returns the (possibly added or updated) member, if any; C<undef> on
620
errors.
621
The comparison is based on C<lastModTime()> and (in the case of a
622
non-directory) the size of the file.
623
624
=item addFile( $fileName [, $newName ] )
625
626
627
628
Append a member whose data comes from an external file,
629
returning the member or undef. The member will have its file
630
name set to the name of the external file, and its
631
desiredCompressionMethod set to COMPRESSION_DEFLATED. The
632
file attributes and last modification time will be set from
633
the file.
634
If the name given does not represent a readable plain file or
635
symbolic link, undef will be returned. C<$fileName> must be
636
in the format required for the local file system.
637
The optional C<$newName> argument sets the internal file name
638
to something different than the given $fileName. C<$newName>,
639
if given, must be in Zip name format (i.e. Unix).
640
The text mode bit will be set if the contents appears to be
641
text (as returned by the C<-T> perl operator).
642
643
644
I<NOTE> that you shouldn't (generally) use absolute path names
645
in zip member names, as this will cause problems with some zip
646
tools as well as introduce a security hole and make the zip
647
harder to use.
648
649
=item addDirectory( $directoryName [, $fileName ] )
650
651
652
653
Append a member created from the given directory name. The
654
directory name does not have to name an existing directory.
655
If the named directory exists, the file modification time and
656
permissions are set from the existing directory, otherwise
657
they are set to now and permissive default permissions.
658
C<$directoryName> must be in local file system format.
659
The optional second argument sets the name of the archive
660
member (which defaults to C<$directoryName>). If given, it
661
must be in Zip (Unix) format.
662
Returns the new member.
663
664
=item addFileOrDirectory( $name [, $newName ] )
665
666
667
668
Append a member from the file or directory named $name. If
669
$newName is given, use it for the name of the new member.
670
Will add or remove trailing slashes from $newName as needed.
671
C<$name> must be in local file system format.
672
The optional second argument sets the name of the archive
673
member (which defaults to C<$name>). If given, it must be in
674
Zip (Unix) format.
675
676
=item addString( $stringOrStringRef, $name )
677
678
679
680
Append a member created from the given string or string
681
reference. The name is given by the second argument.
682
Returns the new member. The last modification time will be
683
set to now, and the file attributes will be set to permissive
684
defaults.
685
686
my $member = $zip->addString( 'This is a test', 'test.txt' );
687
688
=item contents( $memberOrMemberName [, $newContents ] )
689
690
691
692
Returns the uncompressed data for a particular member, or
693
undef.
694
695
print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
696
697
Also can change the contents of a member:
698
699
$zip->contents( 'xyz.txt', 'This is the new contents' );
700
701
=back
702
703
=head2 Zip Archive I/O operations
704
705
706
A Zip archive can be written to a file or file handle, or read from
707
one.
708
709
=over 4
710
711
=item writeToFileNamed( $fileName )
712
713
714
715
Write a zip archive to named file. Returns C<AZ_OK> on
716
success.
717
718
my $status = $zip->writeToFileNamed( 'xx.zip' );
719
die "error somewhere" if $status != AZ_OK;
720
721
Note that if you use the same name as an existing zip file
722
that you read in, you will clobber ZipFileMembers. So
723
instead, write to a different file name, then delete the
724
original.
725
If you use the C<overwrite()> or C<overwriteAs()> methods, you can
726
re-write the original zip in this way.
727
C<$fileName> should be a valid file name on your system.
728
729
=item writeToFileHandle( $fileHandle [, $seekable] )
730
731
732
733
Write a zip archive to a file handle. Return AZ_OK on
734
success. The optional second arg tells whether or not to try
735
to seek backwards to re-write headers. If not provided, it is
736
set if the Perl C<-f> test returns true. This could fail on
737
some operating systems, though.
738
739
my $fh = IO::File->new( 'someFile.zip', 'w' );
740
if ( $zip->writeToFileHandle( $fh ) != AZ_OK)
741
{
742
# error handling
743
}
744
745
If you pass a file handle that is not seekable (like if
746
you're writing to a pipe or a socket), pass a false second
747
argument:
748
749
my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
750
$zip->writeToFileHandle( $fh, 0 ); # fh is not seekable
751
752
If this method fails during the write of a member, that
753
member and all following it will return false from
754
C<wasWritten()>. See writeCentralDirectory() for a way to
755
deal with this.
756
If you want, you can write data to the file handle before
757
passing it to writeToFileHandle(); this could be used (for
758
instance) for making self-extracting archives. However, this
759
only works reliably when writing to a real file (as opposed
760
to STDOUT or some other possible non-file).
761
See examples/selfex.pl for how to write a self-extracting
762
archive.
763
764
=item writeCentralDirectory( $fileHandle [, $offset ] )
765
766
767
768
Writes the central directory structure to the given file
769
handle. Returns AZ_OK on success. If given an $offset, will
770
seek to that point before writing. This can be used for
771
recovery in cases where writeToFileHandle or writeToFileNamed
772
returns an IO error because of running out of space on the
773
destination file. You can truncate the zip by seeking
774
backwards and then writing the directory:
775
776
my $fh = IO::File->new( 'someFile.zip', 'w' );
777
my $retval = $zip->writeToFileHandle( $fh );
778
if ( $retval == AZ_IO_ERROR )
779
{
780
my @unwritten = grep { not $_->wasWritten() } $zip->members();
781
if (@unwritten)
782
{
783
$zip->removeMember( $member ) foreach my $member ( @unwritten );
784
$zip->writeCentralDirectory( $fh,
785
$unwritten[0]->writeLocalHeaderRelativeOffset());
786
}
787
}
788
789
=item overwriteAs( $newName )
790
791
792
793
Write the zip to the specified file, as safely as possible.
794
This is done by first writing to a temp file, then renaming
795
the original if it exists, then renaming the temp file, then
796
deleting the renamed original if it exists. Returns AZ_OK if
797
successful.
798
799
=item overwrite()
800
801
802
803
Write back to the original zip file. See overwriteAs() above.
804
If the zip was not ever read from a file, this generates an
805
error.
806
807
=item read( $fileName )
808
809
810
811
Read zipfile headers from a zip file, appending new members.
812
Returns C<AZ_OK> or error code.
813
814
my $zipFile = Archive::Zip->new();
815
my $status = $zipFile->read( '/some/FileName.zip' );
816
817
=item readFromFileHandle( $fileHandle, $filename )
818
819
820
821
Read zipfile headers from an already-opened file handle,
822
appending new members. Does not close the file handle.
823
Returns C<AZ_OK> or error code. Note that this requires a
824
seekable file handle; reading from a stream is not yet
825
supported.
826
827
my $fh = IO::File->new( '/some/FileName.zip', 'r' );
828
my $zip1 = Archive::Zip->new();
829
my $status = $zip1->readFromFileHandle( $fh );
830
my $zip2 = Archive::Zip->new();
831
$status = $zip2->readFromFileHandle( $fh );
832
833
=back
834
835
=head2 Zip Archive Tree operations
836
837
838
These used to be in Archive::Zip::Tree but got moved into
839
Archive::Zip. They enable operation on an entire tree of members or
840
files.
841
A usage example:
842
843
use Archive::Zip;
844
my $zip = Archive::Zip->new();
845
# add all readable files and directories below . as xyz/*
846
$zip->addTree( '.', 'xyz' );
847
# add all readable plain files below /abc as def/*
848
$zip->addTree( '/abc', 'def', sub { -f && -r } );
849
# add all .c files below /tmp as stuff/*
850
$zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
851
# add all .o files below /tmp as stuff/* if they aren't writable
852
$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
853
# add all .so files below /tmp that are smaller than 200 bytes as stuff/*
854
$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
855
# and write them into a file
856
$zip->writeToFileNamed('xxx.zip');
857
# now extract the same files into /tmpx
858
$zip->extractTree( 'stuff', '/tmpx' );
859
860
=over 4
861
862
=item $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
863
864
865
866
C<$root> is the root of the tree of files and directories to be
867
added. It is a valid directory name on your system. C<$dest> is
868
the name for the root in the zip file (undef or blank means
869
to use relative pathnames). It is a valid ZIP directory name
870
(that is, it uses forward slashes (/) for separating
871
directory components). C<$pred> is an optional subroutine
872
reference to select files: it is passed the name of the
873
prospective file or directory using C<$_>, and if it returns
874
true, the file or directory will be included. The default is
875
to add all readable files and directories. For instance,
876
using
877
878
my $pred = sub { /\.txt/ };
879
$zip->addTree( '.', '', $pred );
880
881
will add all the .txt files in and below the current
882
directory, using relative names, and making the names
883
identical in the zipfile:
884
885
original name zip member name
886
./xyz xyz
887
./a/ a/
888
./a/b a/b
889
890
To translate absolute to relative pathnames, just pass them
891
in: $zip->addTree( '/c/d', 'a' );
892
893
original name zip member name
894
/c/d/xyz a/xyz
895
/c/d/a/ a/a/
896
/c/d/a/b a/a/b
897
898
Returns AZ_OK on success. Note that this will not follow
899
symbolic links to directories. Note also that this does not
900
check for the validity of filenames.
901
902
903
Note that you generally I<don't> want to make zip archive member names
904
absolute.
905
906
=item $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
907
908
909
910
$root is the root of the tree of files and directories to be
911
added $dest is the name for the root in the zip file (undef
912
means to use relative pathnames) $pattern is a (non-anchored)
913
regular expression for filenames to match $pred is an
914
optional subroutine reference to select files: it is passed
915
the name of the prospective file or directory in C<$_>, and
916
if it returns true, the file or directory will be included.
917
The default is to add all readable files and directories. To
918
add all files in and below the current dirctory whose names
919
end in C<.pl>, and make them extract into a subdirectory
920
named C<xyz>, do this:
921
922
$zip->addTreeMatching( '.', 'xyz', '\.pl$' )
923
924
To add all I<writable> files in and below the dirctory named
925
C</abc> whose names end in C<.pl>, and make them extract into
926
a subdirectory named C<xyz>, do this:
927
928
$zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
929
930
Returns AZ_OK on success. Note that this will not follow
931
symbolic links to directories.
932
933
=item $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
934
935
936
937
Update a zip file from a directory tree.
938
939
C<updateTree()> takes the same arguments as C<addTree()>, but first
940
checks to see whether the file or directory already exists in the zip
941
file, and whether it has been changed.
942
943
If the fourth argument C<$mirror> is true, then delete all my members
944
if corresponding files weren't found.
945
946
947
Returns an error code or AZ_OK of all is well.
948
949
=item $zip->extractTree()
950
951
952
953
=item $zip->extractTree( $root )
954
955
956
957
=item $zip->extractTree( $root, $dest )
958
959
960
961
=item $zip->extractTree( $root, $dest, $volume )
962
963
964
965
If you don't give any arguments at all, will extract all the
966
files in the zip with their original names.
967
968
969
If you supply one argument for C<$root>, C<extractTree> will extract
970
all the members whose names start with C<$root> into the current
971
directory, stripping off C<$root> first.
972
C<$root> is in Zip (Unix) format.
973
For instance,
974
975
$zip->extractTree( 'a' );
976
977
when applied to a zip containing the files:
978
a/x a/b/c ax/d/e d/e will extract:
979
980
981
a/x as ./x
982
983
984
a/b/c as ./b/c
985
986
987
If you give two arguments, C<extractTree> extracts all the members
988
whose names start with C<$root>. It will translate C<$root> into
989
C<$dest> to construct the destination file name.
990
C<$root> and C<$dest> are in Zip (Unix) format.
991
For instance,
992
993
$zip->extractTree( 'a', 'd/e' );
994
995
when applied to a zip containing the files:
996
a/x a/b/c ax/d/e d/e will extract:
997
998
999
a/x to d/e/x
1000
1001
1002
a/b/c to d/e/b/c and ignore ax/d/e and d/e
1003
1004
1005
If you give three arguments, C<extractTree> extracts all the members
1006
whose names start with C<$root>. It will translate C<$root> into
1007
C<$dest> to construct the destination file name, and then it will
1008
convert to local file system format, using C<$volume> as the name of
1009
the destination volume.
1010
1011
1012
C<$root> and C<$dest> are in Zip (Unix) format.
1013
1014
1015
C<$volume> is in local file system format.
1016
1017
1018
For instance, under Windows,
1019
1020
$zip->extractTree( 'a', 'd/e', 'f:' );
1021
1022
when applied to a zip containing the files:
1023
a/x a/b/c ax/d/e d/e will extract:
1024
1025
1026
a/x to f:d/e/x
1027
1028
1029
a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
1030
1031
1032
If you want absolute paths (the prior example used paths relative to
1033
the current directory on the destination volume, you can specify these
1034
in C<$dest>:
1035
1036
$zip->extractTree( 'a', '/d/e', 'f:' );
1037
1038
when applied to a zip containing the files:
1039
a/x a/b/c ax/d/e d/e will extract:
1040
1041
1042
a/x to f:\d\e\x
1043
1044
1045
a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
1046
1047
1048
=back
1049
1050
=head1 MEMBER OPERATIONS
1051
1052
1053
=head2 Member Class Methods
1054
1055
1056
Several constructors allow you to construct members without adding
1057
them to a zip archive. These work the same as the addFile(),
1058
addDirectory(), and addString() zip instance methods described above,
1059
but they don't add the new members to a zip.
1060
1061
=over 4
1062
1063
=item Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
1064
1065
1066
1067
Construct a new member from the given string. Returns undef
1068
on error.
1069
1070
my $member = Archive::Zip::Member->newFromString( 'This is a test',
1071
'xyz.txt' );
1072
1073
=item newFromFile( $fileName )
1074
1075
1076
1077
Construct a new member from the given file. Returns undef on
1078
error.
1079
1080
my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
1081
1082
=item newDirectoryNamed( $directoryName [, $zipname ] )
1083
1084
1085
1086
Construct a new member from the given directory.
1087
C<$directoryName> must be a valid name on your file system; it doesn't
1088
have to exist.
1089
1090
1091
If given, C<$zipname> will be the name of the zip member; it must be a
1092
valid Zip (Unix) name. If not given, it will be converted from
1093
C<$directoryName>.
1094
1095
1096
Returns undef on error.
1097
1098
my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
1099
1100
=back
1101
1102
=head2 Member Simple accessors
1103
1104
1105
These methods get (and/or set) member attribute values.
1106
1107
=over 4
1108
1109
=item versionMadeBy()
1110
1111
1112
1113
Gets the field from the member header.
1114
1115
=item fileAttributeFormat( [$format] )
1116
1117
1118
1119
Gets or sets the field from the member header. These are
1120
C<FA_*> values.
1121
1122
=item versionNeededToExtract()
1123
1124
1125
1126
Gets the field from the member header.
1127
1128
=item bitFlag()
1129
1130
1131
1132
Gets the general purpose bit field from the member header.
1133
This is where the C<GPBF_*> bits live.
1134
1135
=item compressionMethod()
1136
1137
1138
1139
Returns the member compression method. This is the method
1140
that is currently being used to compress the member data.
1141
This will be COMPRESSION_STORED for added string or file
1142
members, or any of the C<COMPRESSION_*> values for members
1143
from a zip file. However, this module can only handle members
1144
whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
1145
format.
1146
1147
=item desiredCompressionMethod( [$method] )
1148
1149
1150
1151
Get or set the member's C<desiredCompressionMethod>. This is
1152
the compression method that will be used when the member is
1153
written. Returns prior desiredCompressionMethod. Only
1154
COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
1155
arguments. Changing to COMPRESSION_STORED will change the
1156
member desiredCompressionLevel to 0; changing to
1157
COMPRESSION_DEFLATED will change the member
1158
desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
1159
1160
=item desiredCompressionLevel( [$method] )
1161
1162
1163
1164
Get or set the member's desiredCompressionLevel This is the
1165
method that will be used to write. Returns prior
1166
desiredCompressionLevel. Valid arguments are 0 through 9,
1167
COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
1168
COMPRESSION_LEVEL_BEST_COMPRESSION, and
1169
COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
1170
change the desiredCompressionMethod to COMPRESSION_STORED.
1171
All other arguments will change the desiredCompressionMethod
1172
to COMPRESSION_DEFLATED.
1173
1174
=item externalFileName()
1175
1176
1177
1178
Return the member's external file name, if any, or undef.
1179
1180
=item fileName()
1181
1182
1183
1184
Get or set the member's internal filename. Returns the
1185
(possibly new) filename. Names will have backslashes
1186
converted to forward slashes, and will have multiple
1187
consecutive slashes converted to single ones.
1188
1189
=item lastModFileDateTime()
1190
1191
1192
1193
Return the member's last modification date/time stamp in
1194
MS-DOS format.
1195
1196
=item lastModTime()
1197
1198
1199
1200
Return the member's last modification date/time stamp,
1201
converted to unix localtime format.
1202
1203
print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
1204
1205
=item setLastModFileDateTimeFromUnix()
1206
1207
1208
1209
Set the member's lastModFileDateTime from the given unix
1210
time.
1211
1212
$member->setLastModFileDateTimeFromUnix( time() );
1213
1214
=item internalFileAttributes()
1215
1216
1217
1218
Return the internal file attributes field from the zip
1219
header. This is only set for members read from a zip file.
1220
1221
=item externalFileAttributes()
1222
1223
1224
1225
Return member attributes as read from the ZIP file. Note that
1226
these are NOT UNIX!
1227
1228
=item unixFileAttributes( [$newAttributes] )
1229
1230
1231
1232
Get or set the member's file attributes using UNIX file
1233
attributes. Returns old attributes.
1234
1235
my $oldAttribs = $member->unixFileAttributes( 0666 );
1236
1237
Note that the return value has more than just the file
1238
permissions, so you will have to mask off the lowest bits for
1239
comparisions.
1240
1241
=item localExtraField( [$newField] )
1242
1243
1244
1245
Gets or sets the extra field that was read from the local
1246
header. This is not set for a member from a zip file until
1247
after the member has been written out. The extra field must
1248
be in the proper format.
1249
1250
=item cdExtraField( [$newField] )
1251
1252
1253
1254
Gets or sets the extra field that was read from the central
1255
directory header. The extra field must be in the proper
1256
format.
1257
1258
=item extraFields()
1259
1260
1261
1262
Return both local and CD extra fields, concatenated.
1263
1264
=item fileComment( [$newComment] )
1265
1266
1267
1268
Get or set the member's file comment.
1269
1270
=item hasDataDescriptor()
1271
1272
1273
1274
Get or set the data descriptor flag. If this is set, the
1275
local header will not necessarily have the correct data
1276
sizes. Instead, a small structure will be stored at the end
1277
of the member data with these values. This should be
1278
transparent in normal operation.
1279
1280
=item crc32()
1281
1282
1283
1284
Return the CRC-32 value for this member. This will not be set
1285
for members that were constructed from strings or external
1286
files until after the member has been written.
1287
1288
=item crc32String()
1289
1290
1291
1292
Return the CRC-32 value for this member as an 8 character
1293
printable hex string. This will not be set for members that
1294
were constructed from strings or external files until after
1295
the member has been written.
1296
1297
=item compressedSize()
1298
1299
1300
1301
Return the compressed size for this member. This will not be
1302
set for members that were constructed from strings or
1303
external files until after the member has been written.
1304
1305
=item uncompressedSize()
1306
1307
1308
1309
Return the uncompressed size for this member.
1310
1311
=item isEncrypted()
1312
1313
1314
1315
Return true if this member is encrypted. The Archive::Zip
1316
module does not currently create or extract encrypted
1317
members.
1318
1319
=item isTextFile( [$flag] )
1320
1321
1322
1323
Returns true if I am a text file. Also can set the status if
1324
given an argument (then returns old state). Note that this
1325
module does not currently do anything with this flag upon
1326
extraction or storage. That is, bytes are stored in native
1327
format whether or not they came from a text file.
1328
1329
=item isBinaryFile()
1330
1331
1332
1333
Returns true if I am a binary file. Also can set the status
1334
if given an argument (then returns old state). Note that this
1335
module does not currently do anything with this flag upon
1336
extraction or storage. That is, bytes are stored in native
1337
format whether or not they came from a text file.
1338
1339
=item extractToFileNamed( $fileName )
1340
1341
1342
1343
Extract me to a file with the given name. The file will be
1344
created with default modes. Directories will be created as
1345
needed.
1346
The C<$fileName> argument should be a valid file name on your
1347
file system.
1348
Returns AZ_OK on success.
1349
1350
=item isDirectory()
1351
1352
1353
1354
Returns true if I am a directory.
1355
1356
=item writeLocalHeaderRelativeOffset()
1357
1358
1359
1360
Returns the file offset in bytes the last time I was written.
1361
1362
=item wasWritten()
1363
1364
1365
1366
Returns true if I was successfully written. Reset at the
1367
beginning of a write attempt.
1368
1369
=back
1370
1371
=head2 Low-level member data reading
1372
1373
1374
It is possible to use lower-level routines to access member data
1375
streams, rather than the extract* methods and contents(). For
1376
instance, here is how to print the uncompressed contents of a member
1377
in chunks using these methods:
1378
1379
my ( $member, $status, $bufferRef );
1380
$member = $zip->memberNamed( 'xyz.txt' );
1381
$member->desiredCompressionMethod( COMPRESSION_STORED );
1382
$status = $member->rewindData();
1383
die "error $status" unless $status == AZ_OK;
1384
while ( ! $member->readIsDone() )
1385
{
1386
( $bufferRef, $status ) = $member->readChunk();
1387
die "error $status"
1388
if $status != AZ_OK && $status != AZ_STREAM_END;
1389
# do something with $bufferRef:
1390
print $$bufferRef;
1391
}
1392
$member->endRead();
1393
1394
=over 4
1395
1396
=item readChunk( [$chunkSize] )
1397
1398
1399
1400
This reads the next chunk of given size from the member's
1401
data stream and compresses or uncompresses it as necessary,
1402
returning a reference to the bytes read and a status. If size
1403
argument is not given, defaults to global set by
1404
Archive::Zip::setChunkSize. Status is AZ_OK on success until
1405
the last chunk, where it returns AZ_STREAM_END. Returns C<(
1406
\$bytes, $status)>.
1407
1408
my ( $outRef, $status ) = $self->readChunk();
1409
print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1410
1411
=item rewindData()
1412
1413
1414
1415
Rewind data and set up for reading data streams or writing
1416
zip files. Can take options for C<inflateInit()> or
1417
C<deflateInit()>, but this isn't likely to be necessary.
1418
Subclass overrides should call this method. Returns C<AZ_OK>
1419
on success.
1420
1421
=item endRead()
1422
1423
1424
1425
Reset the read variables and free the inflater or deflater.
1426
Must be called to close files, etc. Returns AZ_OK on success.
1427
1428
=item readIsDone()
1429
1430
1431
1432
Return true if the read has run out of data or errored out.
1433
1434
=item contents()
1435
1436
1437
1438
Return the entire uncompressed member data or undef in scalar
1439
context. When called in array context, returns C<( $string,
1440
$status )>; status will be AZ_OK on success:
1441
1442
my $string = $member->contents();
1443
# or
1444
my ( $string, $status ) = $member->contents();
1445
die "error $status" unless $status == AZ_OK;
1446
1447
Can also be used to set the contents of a member (this may
1448
change the class of the member):
1449
1450
$member->contents( "this is my new contents" );
1451
1452
=item extractToFileHandle( $fh )
1453
1454
1455
1456
Extract (and uncompress, if necessary) the member's contents
1457
to the given file handle. Return AZ_OK on success.
1458
1459
=back
1460
1461
=head1 Archive::Zip::FileMember methods
1462
1463
1464
The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
1465
base class for both ZipFileMember and NewFileMember classes. This class adds
1466
an C<externalFileName> and an C<fh> member to keep track of the external
1467
file.
1468
1469
=over 4
1470
1471
=item externalFileName()
1472
1473
1474
1475
Return the member's external filename.
1476
1477
=item fh()
1478
1479
1480
1481
Return the member's read file handle. Automatically opens file if
1482
necessary.
1483
1484
=back
1485
1486
=head1 Archive::Zip::ZipFileMember methods
1487
1488
1489
The Archive::Zip::ZipFileMember class represents members that have been read
1490
from external zip files.
1491
1492
=over 4
1493
1494
=item diskNumberStart()
1495
1496
1497
1498
Returns the disk number that the member's local header resides in.
1499
Should be 0.
1500
1501
=item localHeaderRelativeOffset()
1502
1503
1504
1505
Returns the offset into the zip file where the member's local header
1506
is.
1507
1508
=item dataOffset()
1509
1510
1511
1512
Returns the offset from the beginning of the zip file to the member's
1513
data.
1514
1515
=back
1516
1517
=head1 REQUIRED MODULES
1518
1519
1520
L<Archive::Zip|Archive::Zip> requires several other modules:
1521
1522
1523
L<Carp|Carp>
1524
1525
1526
L<Compress::Zlib|Compress::Zlib>
1527
1528
1529
L<Cwd|Cwd>
1530
1531
1532
L<File::Basename|File::Basename>
1533
1534
1535
L<File::Copy|File::Copy>
1536
1537
1538
L<File::Find|File::Find>
1539
1540
1541
L<File::Path|File::Path>
1542
1543
1544
L<File::Spec|File::Spec>
1545
1546
1547
L<File::Spec|File::Spec>
1548
1549
1550
L<IO::File|IO::File>
1551
1552
1553
L<IO::Seekable|IO::Seekable>
1554
1555
1556
L<Time::Local|Time::Local>
1557
1558
1559
=head1 AUTHOR
1560
1561
1562
Ned Konz, <nedkonz@cpan.org>
1563
1564
1565
File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>
1566
1567
=head1 COPYRIGHT
1568
1569
1570
Copyright (c) 2000-2003 Ned Konz. All rights reserved. This program is free
1571
software; you can redistribute it and/or modify it under the same terms as
1572
Perl itself.
1573
1574
=head1 SEE ALSO
1575
1576
1577
L<Compress::Zlib>
1578
1579
1580
L<Archive::Tar>
1581
1582
1583
There is a Japanese translation of this
1584
document at L<http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html> that
1585
was done by DEQ <deq@oct.zaq.ne.jp> . Thanks!
1586
Loggerhead is a web-based interface for Breezy
Version: 2.0.1