lib/Archive/Zip.pm

   1 package Archive::Zip;
   2
   3 use strict;
   4 BEGIN {
   5         require 5.003_96;
   6 }
   7 use UNIVERSAL           ();
   8 use Carp                ();
   9 use IO::File            ();
  10 use IO::Seekable        ();
  11 use Compress::Raw::Zlib ();
  12 use File::Spec          ();
  13 use File::Temp          ();
  14 use FileHandle          ();
  15
  16 use vars qw( $VERSION @ISA );
  17 BEGIN {
  18         $VERSION = '1.28';
  19
  20         require Exporter;
  21         @ISA = qw( Exporter );
  22 }
  23
  24 use vars qw( $ChunkSize $ErrorHandler );
  25 BEGIN {
  26         # This is the size we'll try to read, write, and (de)compress.
  27         # You could set it to something different if you had lots of memory
  28         # and needed more speed.
  29         $ChunkSize ||= 32768;
  30
  31         $ErrorHandler = \&Carp::carp;
  32 }
  33
  34 # BEGIN block is necessary here so that other modules can use the constants.
  35 use vars qw( @EXPORT_OK %EXPORT_TAGS );
  36 BEGIN {
  37         @EXPORT_OK   = ('computeCRC32');
  38         %EXPORT_TAGS = (
  39                 CONSTANTS => [ qw(
  40                         FA_MSDOS
  41                         FA_UNIX
  42                         GPBF_ENCRYPTED_MASK
  43                         GPBF_DEFLATING_COMPRESSION_MASK
  44                         GPBF_HAS_DATA_DESCRIPTOR_MASK
  45                         COMPRESSION_STORED
  46                         COMPRESSION_DEFLATED
  47                         COMPRESSION_LEVEL_NONE
  48                         COMPRESSION_LEVEL_DEFAULT
  49                         COMPRESSION_LEVEL_FASTEST
  50                         COMPRESSION_LEVEL_BEST_COMPRESSION
  51                         IFA_TEXT_FILE_MASK
  52                         IFA_TEXT_FILE
  53                         IFA_BINARY_FILE
  54                         ) ],
  55
  56                 MISC_CONSTANTS => [ qw(
  57                         FA_AMIGA
  58                         FA_VAX_VMS
  59                         FA_VM_CMS
  60                         FA_ATARI_ST
  61                         FA_OS2_HPFS
  62                         FA_MACINTOSH
  63                         FA_Z_SYSTEM
  64                         FA_CPM
  65                         FA_TOPS20
  66                         FA_WINDOWS_NTFS
  67                         FA_QDOS
  68                         FA_ACORN
  69                         FA_VFAT
  70                         FA_MVS
  71                         FA_BEOS
  72                         FA_TANDEM
  73                         FA_THEOS
  74                         GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
  75                         GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
  76                         GPBF_IS_COMPRESSED_PATCHED_DATA_MASK
  77                         COMPRESSION_SHRUNK
  78                         DEFLATING_COMPRESSION_NORMAL
  79                         DEFLATING_COMPRESSION_MAXIMUM
  80                         DEFLATING_COMPRESSION_FAST
  81                         DEFLATING_COMPRESSION_SUPER_FAST
  82                         COMPRESSION_REDUCED_1
  83                         COMPRESSION_REDUCED_2
  84                         COMPRESSION_REDUCED_3
  85                         COMPRESSION_REDUCED_4
  86                         COMPRESSION_IMPLODED
  87                         COMPRESSION_TOKENIZED
  88                         COMPRESSION_DEFLATED_ENHANCED
  89                         COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
  90                         ) ],
  91
  92                 ERROR_CODES => [ qw(
  93                         AZ_OK
  94                         AZ_STREAM_END
  95                         AZ_ERROR
  96                         AZ_FORMAT_ERROR
  97                         AZ_IO_ERROR
  98                         ) ],
  99
 100                 # For Internal Use Only
 101                 PKZIP_CONSTANTS => [ qw(
 102                         SIGNATURE_FORMAT
 103                         SIGNATURE_LENGTH
 104                         LOCAL_FILE_HEADER_SIGNATURE
 105                         LOCAL_FILE_HEADER_FORMAT
 106                         LOCAL_FILE_HEADER_LENGTH
 107                         CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE
 108                         DATA_DESCRIPTOR_FORMAT
 109                         DATA_DESCRIPTOR_LENGTH
 110                         DATA_DESCRIPTOR_SIGNATURE
 111                         DATA_DESCRIPTOR_FORMAT_NO_SIG
 112                         DATA_DESCRIPTOR_LENGTH_NO_SIG
 113                         CENTRAL_DIRECTORY_FILE_HEADER_FORMAT
 114                         CENTRAL_DIRECTORY_FILE_HEADER_LENGTH
 115                         END_OF_CENTRAL_DIRECTORY_SIGNATURE
 116                         END_OF_CENTRAL_DIRECTORY_SIGNATURE_STRING
 117                         END_OF_CENTRAL_DIRECTORY_FORMAT
 118                         END_OF_CENTRAL_DIRECTORY_LENGTH
 119                         ) ],
 120
 121                 # For Internal Use Only
 122                 UTILITY_METHODS => [ qw(
 123                         _error
 124                         _printError
 125                         _ioError
 126                         _formatError
 127                         _subclassResponsibility
 128                         _binmode
 129                         _isSeekable
 130                         _newFileHandle
 131                         _readSignature
 132                         _asZipDirName
 133                         ) ],
 134         );
 135
 136         # Add all the constant names and error code names to @EXPORT_OK
 137         Exporter::export_ok_tags( qw(
 138                 CONSTANTS
 139                 ERROR_CODES
 140                 PKZIP_CONSTANTS
 141                 UTILITY_METHODS
 142                 MISC_CONSTANTS
 143                 ) );
 144
 145 }
 146
 147 # Error codes
 148 use constant AZ_OK           => 0;
 149 use constant AZ_STREAM_END   => 1;
 150 use constant AZ_ERROR        => 2;
 151 use constant AZ_FORMAT_ERROR => 3;
 152 use constant AZ_IO_ERROR     => 4;
 153
 154 # File types
 155 # Values of Archive::Zip::Member->fileAttributeFormat()
 156
 157 use constant FA_MSDOS        => 0;
 158 use constant FA_AMIGA        => 1;
 159 use constant FA_VAX_VMS      => 2;
 160 use constant FA_UNIX         => 3;
 161 use constant FA_VM_CMS       => 4;
 162 use constant FA_ATARI_ST     => 5;
 163 use constant FA_OS2_HPFS     => 6;
 164 use constant FA_MACINTOSH    => 7;
 165 use constant FA_Z_SYSTEM     => 8;
 166 use constant FA_CPM          => 9;
 167 use constant FA_TOPS20       => 10;
 168 use constant FA_WINDOWS_NTFS => 11;
 169 use constant FA_QDOS         => 12;
 170 use constant FA_ACORN        => 13;
 171 use constant FA_VFAT         => 14;
 172 use constant FA_MVS          => 15;
 173 use constant FA_BEOS         => 16;
 174 use constant FA_TANDEM       => 17;
 175 use constant FA_THEOS        => 18;
 176
 177 # general-purpose bit flag masks
 178 # Found in Archive::Zip::Member->bitFlag()
 179
 180 use constant GPBF_ENCRYPTED_MASK             => 1 << 0;
 181 use constant GPBF_DEFLATING_COMPRESSION_MASK => 3 << 1;
 182 use constant GPBF_HAS_DATA_DESCRIPTOR_MASK   => 1 << 3;
 183
 184 # deflating compression types, if compressionMethod == COMPRESSION_DEFLATED
 185 # ( Archive::Zip::Member->bitFlag() & GPBF_DEFLATING_COMPRESSION_MASK )
 186
 187 use constant DEFLATING_COMPRESSION_NORMAL     => 0 << 1;
 188 use constant DEFLATING_COMPRESSION_MAXIMUM    => 1 << 1;
 189 use constant DEFLATING_COMPRESSION_FAST       => 2 << 1;
 190 use constant DEFLATING_COMPRESSION_SUPER_FAST => 3 << 1;
 191
 192 # compression method
 193
 194 # these two are the only ones supported in this module
 195 use constant COMPRESSION_STORED                 => 0; # file is stored (no compression)
 196 use constant COMPRESSION_DEFLATED               => 8; # file is Deflated
 197 use constant COMPRESSION_LEVEL_NONE             => 0;
 198 use constant COMPRESSION_LEVEL_DEFAULT          => -1;
 199 use constant COMPRESSION_LEVEL_FASTEST          => 1;
 200 use constant COMPRESSION_LEVEL_BEST_COMPRESSION => 9;
 201
 202 # internal file attribute bits
 203 # Found in Archive::Zip::Member::internalFileAttributes()
 204
 205 use constant IFA_TEXT_FILE_MASK => 1;
 206 use constant IFA_TEXT_FILE      => 1;
 207 use constant IFA_BINARY_FILE    => 0;
 208
 209 # PKZIP file format miscellaneous constants (for internal use only)
 210 use constant SIGNATURE_FORMAT   => "V";
 211 use constant SIGNATURE_LENGTH   => 4;
 212
 213 # these lengths are without the signature.
 214 use constant LOCAL_FILE_HEADER_SIGNATURE   => 0x04034b50;
 215 use constant LOCAL_FILE_HEADER_FORMAT      => "v3 V4 v2";
 216 use constant LOCAL_FILE_HEADER_LENGTH      => 26;
 217
 218 # PKZIP docs don't mention the signature, but Info-Zip writes it.
 219 use constant DATA_DESCRIPTOR_SIGNATURE     => 0x08074b50;
 220 use constant DATA_DESCRIPTOR_FORMAT        => "V3";
 221 use constant DATA_DESCRIPTOR_LENGTH        => 12;
 222
 223 # but the signature is apparently optional.
 224 use constant DATA_DESCRIPTOR_FORMAT_NO_SIG => "V2";
 225 use constant DATA_DESCRIPTOR_LENGTH_NO_SIG => 8;
 226
 227 use constant CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE  => 0x02014b50;
 228 use constant CENTRAL_DIRECTORY_FILE_HEADER_FORMAT     => "C2 v3 V4 v5 V2";
 229 use constant CENTRAL_DIRECTORY_FILE_HEADER_LENGTH     => 42;
 230
 231 use constant END_OF_CENTRAL_DIRECTORY_SIGNATURE        => 0x06054b50;
 232 use constant END_OF_CENTRAL_DIRECTORY_SIGNATURE_STRING =>
 233         pack( "V", END_OF_CENTRAL_DIRECTORY_SIGNATURE );
 234 use constant END_OF_CENTRAL_DIRECTORY_FORMAT           => "v4 V2 v";
 235 use constant END_OF_CENTRAL_DIRECTORY_LENGTH           => 18;
 236
 237 use constant GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK => 1 << 1;
 238 use constant GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK  => 1 << 2;
 239 use constant GPBF_IS_COMPRESSED_PATCHED_DATA_MASK      => 1 << 5;
 240
 241 # the rest of these are not supported in this module
 242 use constant COMPRESSION_SHRUNK    => 1;    # file is Shrunk
 243 use constant COMPRESSION_REDUCED_1 => 2;    # file is Reduced CF=1
 244 use constant COMPRESSION_REDUCED_2 => 3;    # file is Reduced CF=2
 245 use constant COMPRESSION_REDUCED_3 => 4;    # file is Reduced CF=3
 246 use constant COMPRESSION_REDUCED_4 => 5;    # file is Reduced CF=4
 247 use constant COMPRESSION_IMPLODED  => 6;    # file is Imploded
 248 use constant COMPRESSION_TOKENIZED => 7;    # reserved for Tokenizing compr.
 249 use constant COMPRESSION_DEFLATED_ENHANCED => 9;   # reserved for enh. Deflating
 250 use constant COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED => 10;
 251
 252 # Load the various required classes
 253 require Archive::Zip::Archive;
 254 require Archive::Zip::Member;
 255 require Archive::Zip::FileMember;
 256 require Archive::Zip::DirectoryMember;
 257 require Archive::Zip::ZipFileMember;
 258 require Archive::Zip::NewFileMember;
 259 require Archive::Zip::StringMember;
 260
 261 use constant ZIPARCHIVECLASS => 'Archive::Zip::Archive';
 262 use constant ZIPMEMBERCLASS  => 'Archive::Zip::Member';
 263
 264 # Convenience functions
 265
 266 sub _ISA ($$) {
 267         # Can't rely on Scalar::Util, so use the next best way
 268         local $@;
 269         !! eval { ref $_[0] and $_[0]->isa($_[1]) };
 270 }
 271
 272 sub _CAN ($$) {
 273         local $@;
 274         !! eval { ref $_[0] and $_[0]->can($_[1]) };
 275 }
 276
 277
 278
 279
 280
 281 #####################################################################
 282 # Methods
 283
 284 sub new {
 285         my $class = shift;
 286         return $class->ZIPARCHIVECLASS->new(@_);
 287 }
 288
 289 sub computeCRC32 {
 290         my $data = shift;
 291         $data = shift if ref($data);    # allow calling as an obj method
 292         my $crc = shift;
 293         return Compress::Raw::Zlib::crc32( $data, $crc );
 294 }
 295
 296 # Report or change chunk size used for reading and writing.
 297 # Also sets Zlib's default buffer size (eventually).
 298 sub setChunkSize {
 299         my $chunkSize = shift;
 300         $chunkSize = shift if ref($chunkSize);    # object method on zip?
 301         my $oldChunkSize = $Archive::Zip::ChunkSize;
 302         $Archive::Zip::ChunkSize = $chunkSize if ($chunkSize);
 303         return $oldChunkSize;
 304 }
 305
 306 sub chunkSize {
 307         return $Archive::Zip::ChunkSize;
 308 }
 309
 310 sub setErrorHandler (&) {
 311         my $errorHandler = shift;
 312         $errorHandler = \&Carp::carp unless defined($errorHandler);
 313         my $oldErrorHandler = $Archive::Zip::ErrorHandler;
 314         $Archive::Zip::ErrorHandler = $errorHandler;
 315         return $oldErrorHandler;
 316 }
 317
 318
 319
 320
 321
 322 ######################################################################
 323 # Private utility functions (not methods).
 324
 325 sub _printError {
 326         my $string = join ( ' ', @_, "\n" );
 327         my $oldCarpLevel = $Carp::CarpLevel;
 328         $Carp::CarpLevel += 2;
 329         &{$ErrorHandler} ($string);
 330         $Carp::CarpLevel = $oldCarpLevel;
 331 }
 332
 333 # This is called on format errors.
 334 sub _formatError {
 335         shift if ref( $_[0] );
 336         _printError( 'format error:', @_ );
 337         return AZ_FORMAT_ERROR;
 338 }
 339
 340 # This is called on IO errors.
 341 sub _ioError {
 342         shift if ref( $_[0] );
 343         _printError( 'IO error:', @_, ':', $! );
 344         return AZ_IO_ERROR;
 345 }
 346
 347 # This is called on generic errors.
 348 sub _error {
 349         shift if ref( $_[0] );
 350         _printError( 'error:', @_ );
 351         return AZ_ERROR;
 352 }
 353
 354 # Called when a subclass should have implemented
 355 # something but didn't
 356 sub _subclassResponsibility {
 357         Carp::croak("subclass Responsibility\n");
 358 }
 359
 360 # Try to set the given file handle or object into binary mode.
 361 sub _binmode {
 362         my $fh = shift;
 363         return _CAN( $fh, 'binmode' ) ? $fh->binmode() : binmode($fh);
 364 }
 365
 366 # Attempt to guess whether file handle is seekable.
 367 # Because of problems with Windows, this only returns true when
 368 # the file handle is a real file.
 369 sub _isSeekable {
 370         my $fh = shift;
 371         return 0 unless ref $fh;
 372         if ( _ISA($fh, 'IO::Scalar') ) {
 373                 # IO::Scalar objects are brokenly-seekable
 374                 return 0;
 375         }
 376         if ( _ISA($fh, 'IO::String') ) {
 377                 return 1;
 378         }
 379         if ( _ISA($fh, 'IO::Seekable') ) {
 380                 # Unfortunately, some things like FileHandle objects
 381                 # return true for Seekable, but AREN'T!!!!!
 382                 if ( _ISA($fh, 'FileHandle') ) {
 383                         return 0;
 384                 } else {
 385                         return 1;
 386                 }
 387         }
 388         if ( _CAN($fh, 'stat') ) {
 389                 return -f $fh;
 390         }
 391         return (
 392                 _CAN($fh, 'seek') and _CAN($fh, 'tell')
 393                 ) ? 1 : 0;
 394 }
 395
 396 # Print to the filehandle, while making sure the pesky Perl special global
 397 # variables don't interfere.
 398 sub _print
 399 {
 400     my ($self, $fh, @data) = @_;
 401
 402     local $\;
 403
 404     return $fh->print(@data);
 405 }
 406
 407 # Return an opened IO::Handle
 408 # my ( $status, fh ) = _newFileHandle( 'fileName', 'w' );
 409 # Can take a filename, file handle, or ref to GLOB
 410 # Or, if given something that is a ref but not an IO::Handle,
 411 # passes back the same thing.
 412 sub _newFileHandle {
 413         my $fd     = shift;
 414         my $status = 1;
 415         my $handle;
 416
 417         if ( ref($fd) ) {
 418                 if ( _ISA($fd, 'IO::Scalar') or _ISA($fd, 'IO::String') ) {
 419                         $handle = $fd;
 420                 } elsif ( _ISA($fd, 'IO::Handle') or ref($fd) eq 'GLOB' ) {
 421                         $handle = IO::File->new;
 422                         $status = $handle->fdopen( $fd, @_ );
 423                 } else {
 424                         $handle = $fd;
 425                 }
 426         } else {
 427                 $handle = IO::File->new;
 428                 $status = $handle->open( $fd, @_ );
 429         }
 430
 431         return ( $status, $handle );
 432 }
 433
 434 # Returns next signature from given file handle, leaves
 435 # file handle positioned afterwards.
 436 # In list context, returns ($status, $signature)
 437 # ( $status, $signature) = _readSignature( $fh, $fileName );
 438
 439 sub _readSignature {
 440         my $fh                = shift;
 441         my $fileName          = shift;
 442         my $expectedSignature = shift;    # optional
 443
 444         my $signatureData;
 445         my $bytesRead = $fh->read( $signatureData, SIGNATURE_LENGTH );
 446         if ( $bytesRead != SIGNATURE_LENGTH ) {
 447                 return _ioError("reading header signature");
 448         }
 449         my $signature = unpack( SIGNATURE_FORMAT, $signatureData );
 450         my $status    = AZ_OK;
 451
 452         # compare with expected signature, if any, or any known signature.
 453         if ( ( defined($expectedSignature) && $signature != $expectedSignature )
 454                 || ( !defined($expectedSignature)
 455                         && $signature != CENTRAL_DIRECTORY_FILE_HEADER_SIGNATURE
 456                         && $signature != LOCAL_FILE_HEADER_SIGNATURE
 457                         && $signature != END_OF_CENTRAL_DIRECTORY_SIGNATURE
 458                         && $signature != DATA_DESCRIPTOR_SIGNATURE ) )
 459         {
 460                 my $errmsg = sprintf( "bad signature: 0x%08x", $signature );
 461                 if ( _isSeekable($fh) )
 462                 {
 463                         $errmsg .=
 464                           sprintf( " at offset %d", $fh->tell() - SIGNATURE_LENGTH );
 465                 }
 466
 467                 $status = _formatError("$errmsg in file $fileName");
 468         }
 469
 470         return ( $status, $signature );
 471 }
 472
 473 # Utility method to make and open a temp file.
 474 # Will create $temp_dir if it doesn't exist.
 475 # Returns file handle and name:
 476 #
 477 # my ($fh, $name) = Archive::Zip::tempFile();
 478 # my ($fh, $name) = Archive::Zip::tempFile('mytempdir');
 479 #
 480
 481 sub tempFile {
 482         my $dir = shift;
 483         my ( $fh, $filename ) = File::Temp::tempfile(
 484                 SUFFIX => '.zip',
 485                 UNLINK => 0,        # we will delete it!
 486                 $dir ? ( DIR => $dir ) : ()
 487         );
 488         return ( undef, undef ) unless $fh;
 489         my ( $status, $newfh ) = _newFileHandle( $fh, 'w+' );
 490         return ( $newfh, $filename );
 491 }
 492
 493 # Return the normalized directory name as used in a zip file (path
 494 # separators become slashes, etc.).
 495 # Will translate internal slashes in path components (i.e. on Macs) to
 496 # underscores.  Discards volume names.
 497 # When $forceDir is set, returns paths with trailing slashes (or arrays
 498 # with trailing blank members).
 499 #
 500 # If third argument is a reference, returns volume information there.
 501 #
 502 # input         output
 503 # .                             ('.')   '.'
 504 # ./a                   ('a')   a
 505 # ./a/b                 ('a','b')       a/b
 506 # ./a/b/                ('a','b')       a/b
 507 # a/b/                  ('a','b')       a/b
 508 # /a/b/                 ('','a','b')    /a/b
 509 # c:\a\b\c.doc  ('','a','b','c.doc')    /a/b/c.doc              # on Windoze
 510 # "i/o maps:whatever"   ('i_o maps', 'whatever')  "i_o maps/whatever"   # on Macs
 511 sub _asZipDirName
 512 {
 513         my $name      = shift;
 514         my $forceDir  = shift;
 515         my $volReturn = shift;
 516         my ( $volume, $directories, $file ) =
 517           File::Spec->splitpath( File::Spec->canonpath($name), $forceDir );
 518         $$volReturn = $volume if ( ref($volReturn) );
 519         my @dirs = map { $_ =~ s{/}{_}g; $_ } File::Spec->splitdir($directories);
 520     if ( @dirs > 0 ) { pop (@dirs) unless $dirs[-1] }   # remove empty component
 521     push ( @dirs, defined($file) ? $file : '' );
 522         #return wantarray ? @dirs : join ( '/', @dirs );
 523     return join ( '/', @dirs );
 524 }
 525
 526 # Return an absolute local name for a zip name.
 527 # Assume a directory if zip name has trailing slash.
 528 # Takes an optional volume name in FS format (like 'a:').
 529 #
 530 sub _asLocalName
 531 {
 532         my $name   = shift;    # zip format
 533         my $volume = shift;
 534         $volume = '' unless defined($volume);    # local FS format
 535
 536         my @paths = split ( /\//, $name );
 537         my $filename = pop (@paths);
 538         $filename = '' unless defined($filename);
 539         my $localDirs = @paths?File::Spec->catdir(@paths):'';
 540         my $localName = File::Spec->catpath( $volume, $localDirs, $filename );
 541     use Cwd;
 542     $localName = File::Spec->catfile(getcwd, $localName) unless $volume;
 543         return $localName;
 544 }
 545
 546 1;
 547
 548 __END__
 549
 550 =pod
 551
 552 =head1 NAME
 553
 554 Archive::Zip - Provide an interface to ZIP archive files.
 555
 556 =head1 SYNOPSIS
 557
 558    # Create a Zip file
 559    use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
 560    my $zip = Archive::Zip->new();
 561
 562    # Add a directory
 563    my $dir_member = $zip->addDirectory( 'dirname/' );
 564
 565    # Add a file from a string with compression
 566    my $string_member = $zip->addString( 'This is a test', 'stringMember.txt' );
 567    $string_member->desiredCompressionMethod( COMPRESSION_DEFLATED );
 568
 569    # Add a file from disk
 570    my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );
 571
 572    # Save the Zip file
 573    unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {
 574        die 'write error';
 575    }
 576
 577    # Read a Zip file
 578    my $somezip = Archive::Zip->new();
 579    unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {
 580        die 'read error';
 581    }
 582
 583    # Change the compression type for a file in the Zip
 584    my $member = $somezip->memberNamed( 'stringMember.txt' );
 585    $member->desiredCompressionMethod( COMPRESSION_STORED );
 586    unless ( $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK ) {
 587        die 'write error';
 588    }
 589
 590 =head1 DESCRIPTION
 591
 592 The Archive::Zip module allows a Perl program to create, manipulate, read,
 593 and write Zip archive files.
 594
 595 Zip archives can be created, or you can read from existing zip files.
 596
 597 Once created, they can be written to files, streams, or strings. Members
 598 can be added, removed, extracted, replaced, rearranged, and enumerated.
 599 They can also be renamed or have their dates, comments, or other attributes
 600 queried or modified. Their data can be compressed or uncompressed as needed.
 601
 602 Members can be created from members in existing Zip files, or from existing
 603 directories, files, or strings.
 604
 605 This module uses the L<Compress::Raw::Zlib> library to read and write the
 606 compressed streams inside the files.
 607
 608 One can use L<Archive::Zip::MemberRead> to read the zip file archive members
 609 as if they were files.
 610
 611 =head2 File Naming
 612
 613 Regardless of what your local file system uses for file naming, names in a
 614 Zip file are in Unix format (I<forward> slashes (/) separating directory
 615 names, etc.).
 616
 617 C<Archive::Zip> tries to be consistent with file naming conventions, and will
 618 translate back and forth between native and Zip file names.
 619
 620 However, it can't guess which format names are in. So two rules control what
 621 kind of file name you must pass various routines:
 622
 623 =over 4
 624
 625 =item Names of files are in local format.
 626
 627 C<File::Spec> and C<File::Basename> are used for various file
 628 operations. When you're referring to a file on your system, use its
 629 file naming conventions.
 630
 631 =item Names of archive members are in Unix format.
 632
 633 This applies to every method that refers to an archive member, or
 634 provides a name for new archive members. The C<extract()> methods
 635 that can take one or two names will convert from local to zip names
 636 if you call them with a single name.
 637
 638 =back
 639
 640 =head2 Archive::Zip Object Model
 641
 642 =head2 Overview
 643
 644 Archive::Zip::Archive objects are what you ordinarily deal with.
 645 These maintain the structure of a zip file, without necessarily
 646 holding data. When a zip is read from a disk file, the (possibly
 647 compressed) data still lives in the file, not in memory. Archive
 648 members hold information about the individual members, but not
 649 (usually) the actual member data. When the zip is written to a
 650 (different) file, the member data is compressed or copied as needed.
 651 It is possible to make archive members whose data is held in a string
 652 in memory, but this is not done when a zip file is read. Directory
 653 members don't have any data.
 654
 655 =head2 Inheritance
 656
 657   Exporter
 658    Archive::Zip                            Common base class, has defs.
 659        Archive::Zip::Archive               A Zip archive.
 660        Archive::Zip::Member                Abstract superclass for all members.
 661            Archive::Zip::StringMember      Member made from a string
 662            Archive::Zip::FileMember        Member made from an external file
 663                Archive::Zip::ZipFileMember Member that lives in a zip file
 664                Archive::Zip::NewFileMember Member whose data is in a file
 665            Archive::Zip::DirectoryMember   Member that is a directory
 666
 667 =head1 EXPORTS
 668
 669 =over 4
 670
 671 =item :CONSTANTS
 672
 673 Exports the following constants:
 674
 675 FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK
 676 GPBF_DEFLATING_COMPRESSION_MASK GPBF_HAS_DATA_DESCRIPTOR_MASK
 677 COMPRESSION_STORED COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK
 678 IFA_TEXT_FILE IFA_BINARY_FILE COMPRESSION_LEVEL_NONE
 679 COMPRESSION_LEVEL_DEFAULT COMPRESSION_LEVEL_FASTEST
 680 COMPRESSION_LEVEL_BEST_COMPRESSION
 681
 682 =item :MISC_CONSTANTS
 683
 684 Exports the following constants (only necessary for extending the
 685 module):
 686
 687 FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS
 688 FA_MACINTOSH FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS
 689 GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK
 690 GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK
 691 GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK
 692 DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM
 693 DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST
 694 COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3
 695 COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED
 696 COMPRESSION_DEFLATED_ENHANCED
 697 COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED
 698
 699 =item :ERROR_CODES
 700
 701 Explained below. Returned from most methods.
 702
 703 AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR
 704
 705 =back
 706
 707 =head1 ERROR CODES
 708
 709 Many of the methods in Archive::Zip return error codes. These are implemented
 710 as inline subroutines, using the C<use constant> pragma. They can be imported
 711 into your namespace using the C<:ERROR_CODES> tag:
 712
 713   use Archive::Zip qw( :ERROR_CODES );
 714
 715   ...
 716
 717   unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {
 718       die "whoops!";
 719   }
 720
 721 =over 4
 722
 723 =item AZ_OK (0)
 724
 725 Everything is fine.
 726
 727 =item AZ_STREAM_END (1)
 728
 729 The read stream (or central directory) ended normally.
 730
 731 =item AZ_ERROR (2)
 732
 733 There was some generic kind of error.
 734
 735 =item AZ_FORMAT_ERROR (3)
 736
 737 There is a format error in a ZIP file being read.
 738
 739 =item AZ_IO_ERROR (4)
 740
 741 There was an IO error.
 742
 743 =back
 744
 745 =head2 Compression
 746
 747 Archive::Zip allows each member of a ZIP file to be compressed (using the
 748 Deflate algorithm) or uncompressed.
 749
 750 Other compression algorithms that some versions of ZIP have been able to
 751 produce are not supported. Each member has two compression methods: the
 752 one it's stored as (this is always COMPRESSION_STORED for string and external
 753 file members), and the one you desire for the member in the zip file.
 754
 755 These can be different, of course, so you can make a zip member that is not
 756 compressed out of one that is, and vice versa.
 757
 758 You can inquire about the current compression and set the desired
 759 compression method:
 760
 761   my $member = $zip->memberNamed( 'xyz.txt' );
 762   $member->compressionMethod();    # return current compression
 763
 764   # set to read uncompressed
 765   $member->desiredCompressionMethod( COMPRESSION_STORED );
 766
 767   # set to read compressed
 768   $member->desiredCompressionMethod( COMPRESSION_DEFLATED );
 769
 770 There are two different compression methods:
 771
 772 =over 4
 773
 774 =item COMPRESSION_STORED
 775
 776 File is stored (no compression)
 777
 778 =item COMPRESSION_DEFLATED
 779
 780 File is Deflated
 781
 782 =back
 783
 784 =head2 Compression Levels
 785
 786 If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you
 787 can choose different compression levels. This choice may affect the
 788 speed of compression and decompression, as well as the size of the
 789 compressed member data.
 790
 791   $member->desiredCompressionLevel( 9 );
 792
 793 The levels given can be:
 794
 795 =over 4
 796
 797 =item 0 or COMPRESSION_LEVEL_NONE
 798
 799 This is the same as saying
 800
 801   $member->desiredCompressionMethod( COMPRESSION_STORED );
 802
 803 =item 1 .. 9
 804
 805 1 gives the best speed and worst compression, and 9 gives the
 806 best compression and worst speed.
 807
 808 =item COMPRESSION_LEVEL_FASTEST
 809
 810 This is a synonym for level 1.
 811
 812 =item COMPRESSION_LEVEL_BEST_COMPRESSION
 813
 814 This is a synonym for level 9.
 815
 816 =item COMPRESSION_LEVEL_DEFAULT
 817
 818 This gives a good compromise between speed and compression,
 819 and is currently equivalent to 6 (this is in the zlib code).
 820 This is the level that will be used if not specified.
 821
 822 =back
 823
 824 =head1 Archive::Zip Methods
 825
 826 The Archive::Zip class (and its invisible subclass Archive::Zip::Archive)
 827 implement generic zip file functionality. Creating a new Archive::Zip object
 828 actually makes an Archive::Zip::Archive object, but you don't have to worry
 829 about this unless you're subclassing.
 830
 831 =head2 Constructor
 832
 833 =over 4
 834
 835 =item new( [$fileName] )
 836
 837 Make a new, empty zip archive.
 838
 839     my $zip = Archive::Zip->new();
 840
 841 If an additional argument is passed, new() will call read()
 842 to read the contents of an archive:
 843
 844     my $zip = Archive::Zip->new( 'xyz.zip' );
 845
 846 If a filename argument is passed and the read fails for any
 847 reason, new will return undef. For this reason, it may be
 848 better to call read separately.
 849
 850 =back
 851
 852 =head2 Zip Archive Utility Methods
 853
 854 These Archive::Zip methods may be called as functions or as object
 855 methods. Do not call them as class methods:
 856
 857     $zip = Archive::Zip->new();
 858     $crc = Archive::Zip::computeCRC32( 'ghijkl' );    # OK
 859     $crc = $zip->computeCRC32( 'ghijkl' );            # also OK
 860     $crc = Archive::Zip->computeCRC32( 'ghijkl' );    # NOT OK
 861
 862 =over 4
 863
 864 =item Archive::Zip::computeCRC32( $string [, $crc] )
 865
 866 This is a utility function that uses the Compress::Raw::Zlib CRC
 867 routine to compute a CRC-32. You can get the CRC of a string:
 868
 869     $crc = Archive::Zip::computeCRC32( $string );
 870
 871 Or you can compute the running CRC:
 872
 873     $crc = 0;
 874     $crc = Archive::Zip::computeCRC32( 'abcdef', $crc );
 875     $crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );
 876
 877 =item Archive::Zip::setChunkSize( $number )
 878
 879 Report or change chunk size used for reading and writing.
 880 This can make big differences in dealing with large files.
 881 Currently, this defaults to 32K. This also changes the chunk
 882 size used for Compress::Raw::Zlib. You must call setChunkSize()
 883 before reading or writing. This is not exportable, so you
 884 must call it like:
 885
 886     Archive::Zip::setChunkSize( 4096 );
 887
 888 or as a method on a zip (though this is a global setting).
 889 Returns old chunk size.
 890
 891 =item Archive::Zip::chunkSize()
 892
 893 Returns the current chunk size:
 894
 895     my $chunkSize = Archive::Zip::chunkSize();
 896
 897 =item Archive::Zip::setErrorHandler( \&subroutine )
 898
 899 Change the subroutine called with error strings. This
 900 defaults to \&Carp::carp, but you may want to change it to
 901 get the error strings. This is not exportable, so you must
 902 call it like:
 903
 904     Archive::Zip::setErrorHandler( \&myErrorHandler );
 905
 906 If myErrorHandler is undef, resets handler to default.
 907 Returns old error handler. Note that if you call Carp::carp
 908 or a similar routine or if you're chaining to the default
 909 error handler from your error handler, you may want to
 910 increment the number of caller levels that are skipped (do
 911 not just set it to a number):
 912
 913     $Carp::CarpLevel++;
 914
 915 =item Archive::Zip::tempFile( [$tmpdir] )
 916
 917 Create a uniquely named temp file. It will be returned open
 918 for read/write. If C<$tmpdir> is given, it is used as the
 919 name of a directory to create the file in. If not given,
 920 creates the file using C<File::Spec::tmpdir()>. Generally, you can
 921 override this choice using the
 922
 923     $ENV{TMPDIR}
 924
 925 environment variable. But see the L<File::Spec|File::Spec>
 926 documentation for your system. Note that on many systems, if you're
 927 running in taint mode, then you must make sure that C<$ENV{TMPDIR}> is
 928 untainted for it to be used.
 929 Will I<NOT> create C<$tmpdir> if it doesn't exist (this is a change
 930 from prior versions!). Returns file handle and name:
 931
 932     my ($fh, $name) = Archive::Zip::tempFile();
 933     my ($fh, $name) = Archive::Zip::tempFile('myTempDir');
 934     my $fh = Archive::Zip::tempFile();  # if you don't need the name
 935
 936 =back
 937
 938 =head2 Zip Archive Accessors
 939
 940 =over 4
 941
 942 =item members()
 943
 944 Return a copy of the members array
 945
 946     my @members = $zip->members();
 947
 948 =item numberOfMembers()
 949
 950 Return the number of members I have
 951
 952 =item memberNames()
 953
 954 Return a list of the (internal) file names of the zip members
 955
 956 =item memberNamed( $string )
 957
 958 Return ref to member whose filename equals given filename or
 959 undef. C<$string> must be in Zip (Unix) filename format.
 960
 961 =item membersMatching( $regex )
 962
 963 Return array of members whose filenames match given regular
 964 expression in list context. Returns number of matching
 965 members in scalar context.
 966
 967     my @textFileMembers = $zip->membersMatching( '.*\.txt' );
 968     # or
 969     my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );
 970
 971 =item diskNumber()
 972
 973 Return the disk that I start on. Not used for writing zips,
 974 but might be interesting if you read a zip in. This should be
 975 0, as Archive::Zip does not handle multi-volume archives.
 976
 977 =item diskNumberWithStartOfCentralDirectory()
 978
 979 Return the disk number that holds the beginning of the
 980 central directory. Not used for writing zips, but might be
 981 interesting if you read a zip in. This should be 0, as
 982 Archive::Zip does not handle multi-volume archives.
 983
 984 =item numberOfCentralDirectoriesOnThisDisk()
 985
 986 Return the number of CD structures in the zipfile last read in.
 987 Not used for writing zips, but might be interesting if you read a zip
 988 in.
 989
 990 =item numberOfCentralDirectories()
 991
 992 Return the number of CD structures in the zipfile last read in.
 993 Not used for writing zips, but might be interesting if you read a zip
 994 in.
 995
 996 =item centralDirectorySize()
 997
 998 Returns central directory size, as read from an external zip
 999 file. Not used for writing zips, but might be interesting if
1000 you read a zip in.
1001
1002 =item centralDirectoryOffsetWRTStartingDiskNumber()
1003
1004 Returns the offset into the zip file where the CD begins. Not
1005 used for writing zips, but might be interesting if you read a
1006 zip in.
1007
1008 =item zipfileComment( [$string] )
1009
1010 Get or set the zipfile comment. Returns the old comment.
1011
1012     print $zip->zipfileComment();
1013     $zip->zipfileComment( 'New Comment' );
1014
1015 =item eocdOffset()
1016
1017 Returns the (unexpected) number of bytes between where the
1018 EOCD was found and where it expected to be. This is normally
1019 0, but would be positive if something (a virus, perhaps) had
1020 added bytes somewhere before the EOCD. Not used for writing
1021 zips, but might be interesting if you read a zip in. Here is
1022 an example of how you can diagnose this:
1023
1024   my $zip = Archive::Zip->new('somefile.zip');
1025   if ($zip->eocdOffset())
1026   {
1027     warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";
1028   }
1029
1030 The C<eocdOffset()> is used to adjust the starting position of member
1031 headers, if necessary.
1032
1033 =item fileName()
1034
1035 Returns the name of the file last read from. If nothing has
1036 been read yet, returns an empty string; if read from a file
1037 handle, returns the handle in string form.
1038
1039 =back
1040
1041 =head2 Zip Archive Member Operations
1042
1043 Various operations on a zip file modify members. When a member is
1044 passed as an argument, you can either use a reference to the member
1045 itself, or the name of a member. Of course, using the name requires
1046 that names be unique within a zip (this is not enforced).
1047
1048 =over 4
1049
1050 =item removeMember( $memberOrName )
1051
1052 Remove and return the given member, or match its name and
1053 remove it. Returns undef if member or name doesn't exist in this
1054 Zip. No-op if member does not belong to this zip.
1055
1056 =item replaceMember( $memberOrName, $newMember )
1057
1058 Remove and return the given member, or match its name and
1059 remove it. Replace with new member. Returns undef if member or
1060 name doesn't exist in this Zip, or if C<$newMember> is undefined.
1061
1062 It is an (undiagnosed) error to provide a C<$newMember> that is a
1063 member of the zip being modified.
1064
1065     my $member1 = $zip->removeMember( 'xyz' );
1066     my $member2 = $zip->replaceMember( 'abc', $member1 );
1067     # now, $member2 (named 'abc') is not in $zip,
1068     # and $member1 (named 'xyz') is, having taken $member2's place.
1069
1070 =item extractMember( $memberOrName [, $extractedName ] )
1071
1072 Extract the given member, or match its name and extract it.
1073 Returns undef if member doesn't exist in this Zip. If
1074 optional second arg is given, use it as the name of the
1075 extracted member. Otherwise, the internal filename of the
1076 member is used as the name of the extracted file or
1077 directory.
1078 If you pass C<$extractedName>, it should be in the local file
1079 system's format.
1080 All necessary directories will be created. Returns C<AZ_OK>
1081 on success.
1082
1083 =item extractMemberWithoutPaths( $memberOrName [, $extractedName ] )
1084
1085 Extract the given member, or match its name and extract it.
1086 Does not use path information (extracts into the current
1087 directory). Returns undef if member doesn't exist in this
1088 Zip.
1089 If optional second arg is given, use it as the name of the
1090 extracted member (its paths will be deleted too). Otherwise,
1091 the internal filename of the member (minus paths) is used as
1092 the name of the extracted file or directory. Returns C<AZ_OK>
1093 on success.
1094
1095 =item addMember( $member )
1096
1097 Append a member (possibly from another zip file) to the zip
1098 file. Returns the new member. Generally, you will use
1099 addFile(), addDirectory(), addFileOrDirectory(), addString(),
1100 or read() to add members.
1101
1102     # Move member named 'abc' to end of zip:
1103     my $member = $zip->removeMember( 'abc' );
1104     $zip->addMember( $member );
1105
1106 =item updateMember( $memberOrName, $fileName )
1107
1108 Update a single member from the file or directory named C<$fileName>.
1109 Returns the (possibly added or updated) member, if any; C<undef> on
1110 errors.
1111 The comparison is based on C<lastModTime()> and (in the case of a
1112 non-directory) the size of the file.
1113
1114 =item addFile( $fileName [, $newName ] )
1115
1116 Append a member whose data comes from an external file,
1117 returning the member or undef. The member will have its file
1118 name set to the name of the external file, and its
1119 desiredCompressionMethod set to COMPRESSION_DEFLATED. The
1120 file attributes and last modification time will be set from
1121 the file.
1122 If the name given does not represent a readable plain file or
1123 symbolic link, undef will be returned. C<$fileName> must be
1124 in the format required for the local file system.
1125 The optional C<$newName> argument sets the internal file name
1126 to something different than the given $fileName. C<$newName>,
1127 if given, must be in Zip name format (i.e. Unix).
1128 The text mode bit will be set if the contents appears to be
1129 text (as returned by the C<-T> perl operator).
1130
1131
1132 I<NOTE> that you shouldn't (generally) use absolute path names
1133 in zip member names, as this will cause problems with some zip
1134 tools as well as introduce a security hole and make the zip
1135 harder to use.
1136
1137 =item addDirectory( $directoryName [, $fileName ] )
1138
1139
1140
1141 Append a member created from the given directory name. The
1142 directory name does not have to name an existing directory.
1143 If the named directory exists, the file modification time and
1144 permissions are set from the existing directory, otherwise
1145 they are set to now and permissive default permissions.
1146 C<$directoryName> must be in local file system format.
1147 The optional second argument sets the name of the archive
1148 member (which defaults to C<$directoryName>). If given, it
1149 must be in Zip (Unix) format.
1150 Returns the new member.
1151
1152 =item addFileOrDirectory( $name [, $newName ] )
1153
1154
1155
1156 Append a member from the file or directory named $name. If
1157 $newName is given, use it for the name of the new member.
1158 Will add or remove trailing slashes from $newName as needed.
1159 C<$name> must be in local file system format.
1160 The optional second argument sets the name of the archive
1161 member (which defaults to C<$name>). If given, it must be in
1162 Zip (Unix) format.
1163
1164 =item addString( $stringOrStringRef, $name )
1165
1166
1167
1168 Append a member created from the given string or string
1169 reference. The name is given by the second argument.
1170 Returns the new member. The last modification time will be
1171 set to now, and the file attributes will be set to permissive
1172 defaults.
1173
1174     my $member = $zip->addString( 'This is a test', 'test.txt' );
1175
1176 =item contents( $memberOrMemberName [, $newContents ] )
1177
1178
1179
1180 Returns the uncompressed data for a particular member, or
1181 undef.
1182
1183     print "xyz.txt contains " . $zip->contents( 'xyz.txt' );
1184
1185 Also can change the contents of a member:
1186
1187     $zip->contents( 'xyz.txt', 'This is the new contents' );
1188
1189 If called expecting an array as the return value, it will include
1190 the status as the second value in the array.
1191
1192     ($content, $status) = $zip->contents( 'xyz.txt');
1193
1194 =back
1195
1196 =head2 Zip Archive I/O operations
1197
1198
1199 A Zip archive can be written to a file or file handle, or read from
1200 one.
1201
1202 =over 4
1203
1204 =item writeToFileNamed( $fileName )
1205
1206
1207
1208 Write a zip archive to named file. Returns C<AZ_OK> on
1209 success.
1210
1211     my $status = $zip->writeToFileNamed( 'xx.zip' );
1212     die "error somewhere" if $status != AZ_OK;
1213
1214 Note that if you use the same name as an existing zip file
1215 that you read in, you will clobber ZipFileMembers. So
1216 instead, write to a different file name, then delete the
1217 original.
1218 If you use the C<overwrite()> or C<overwriteAs()> methods, you can
1219 re-write the original zip in this way.
1220 C<$fileName> should be a valid file name on your system.
1221
1222 =item writeToFileHandle( $fileHandle [, $seekable] )
1223
1224 Write a zip archive to a file handle. Return AZ_OK on
1225 success. The optional second arg tells whether or not to try
1226 to seek backwards to re-write headers. If not provided, it is
1227 set if the Perl C<-f> test returns true. This could fail on
1228 some operating systems, though.
1229
1230     my $fh = IO::File->new( 'someFile.zip', 'w' );
1231     unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {
1232         # error handling
1233     }
1234
1235 If you pass a file handle that is not seekable (like if
1236 you're writing to a pipe or a socket), pass a false second
1237 argument:
1238
1239     my $fh = IO::File->new( '| cat > somefile.zip', 'w' );
1240     $zip->writeToFileHandle( $fh, 0 );   # fh is not seekable
1241
1242 If this method fails during the write of a member, that
1243 member and all following it will return false from
1244 C<wasWritten()>. See writeCentralDirectory() for a way to
1245 deal with this.
1246 If you want, you can write data to the file handle before
1247 passing it to writeToFileHandle(); this could be used (for
1248 instance) for making self-extracting archives. However, this
1249 only works reliably when writing to a real file (as opposed
1250 to STDOUT or some other possible non-file).
1251
1252 See examples/selfex.pl for how to write a self-extracting
1253 archive.
1254
1255 =item writeCentralDirectory( $fileHandle [, $offset ] )
1256
1257 Writes the central directory structure to the given file
1258 handle.
1259
1260 Returns AZ_OK on success. If given an $offset, will
1261 seek to that point before writing. This can be used for
1262 recovery in cases where writeToFileHandle or writeToFileNamed
1263 returns an IO error because of running out of space on the
1264 destination file.
1265
1266 You can truncate the zip by seeking backwards and then writing the
1267 directory:
1268
1269     my $fh = IO::File->new( 'someFile.zip', 'w' );
1270         my $retval = $zip->writeToFileHandle( $fh );
1271     if ( $retval == AZ_IO_ERROR ) {
1272         my @unwritten = grep { not $_->wasWritten() } $zip->members();
1273         if (@unwritten) {
1274             $zip->removeMember( $member ) foreach my $member ( @unwritten );
1275             $zip->writeCentralDirectory( $fh,
1276             $unwritten[0]->writeLocalHeaderRelativeOffset());
1277         }
1278     }
1279
1280 =item overwriteAs( $newName )
1281
1282 Write the zip to the specified file, as safely as possible.
1283 This is done by first writing to a temp file, then renaming
1284 the original if it exists, then renaming the temp file, then
1285 deleting the renamed original if it exists. Returns AZ_OK if
1286 successful.
1287
1288 =item overwrite()
1289
1290 Write back to the original zip file. See overwriteAs() above.
1291 If the zip was not ever read from a file, this generates an
1292 error.
1293
1294 =item read( $fileName )
1295
1296 Read zipfile headers from a zip file, appending new members.
1297 Returns C<AZ_OK> or error code.
1298
1299     my $zipFile = Archive::Zip->new();
1300     my $status = $zipFile->read( '/some/FileName.zip' );
1301
1302 =item readFromFileHandle( $fileHandle, $filename )
1303
1304 Read zipfile headers from an already-opened file handle,
1305 appending new members. Does not close the file handle.
1306 Returns C<AZ_OK> or error code. Note that this requires a
1307 seekable file handle; reading from a stream is not yet
1308 supported.
1309
1310     my $fh = IO::File->new( '/some/FileName.zip', 'r' );
1311     my $zip1 = Archive::Zip->new();
1312     my $status = $zip1->readFromFileHandle( $fh );
1313     my $zip2 = Archive::Zip->new();
1314     $status = $zip2->readFromFileHandle( $fh );
1315
1316 =back
1317
1318 =head2 Zip Archive Tree operations
1319
1320 These used to be in Archive::Zip::Tree but got moved into
1321 Archive::Zip. They enable operation on an entire tree of members or
1322 files.
1323 A usage example:
1324
1325   use Archive::Zip;
1326   my $zip = Archive::Zip->new();
1327
1328   # add all readable files and directories below . as xyz/*
1329   $zip->addTree( '.', 'xyz' );
1330
1331   # add all readable plain files below /abc as def/*
1332   $zip->addTree( '/abc', 'def', sub { -f && -r } );
1333
1334   # add all .c files below /tmp as stuff/*
1335   $zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );
1336
1337   # add all .o files below /tmp as stuff/* if they aren't writable
1338   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );
1339
1340   # add all .so files below /tmp that are smaller than 200 bytes as stuff/*
1341   $zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );
1342
1343   # and write them into a file
1344   $zip->writeToFileNamed('xxx.zip');
1345
1346   # now extract the same files into /tmpx
1347   $zip->extractTree( 'stuff', '/tmpx' );
1348
1349 =over 4
1350
1351 =item $zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip
1352
1353 C<$root> is the root of the tree of files and directories to be
1354 added. It is a valid directory name on your system. C<$dest> is
1355 the name for the root in the zip file (undef or blank means
1356 to use relative pathnames). It is a valid ZIP directory name
1357 (that is, it uses forward slashes (/) for separating
1358 directory components). C<$pred> is an optional subroutine
1359 reference to select files: it is passed the name of the
1360 prospective file or directory using C<$_>, and if it returns
1361 true, the file or directory will be included. The default is
1362 to add all readable files and directories. For instance,
1363 using
1364
1365   my $pred = sub { /\.txt/ };
1366   $zip->addTree( '.', '', $pred );
1367
1368 will add all the .txt files in and below the current
1369 directory, using relative names, and making the names
1370 identical in the zipfile:
1371
1372   original name           zip member name
1373   ./xyz                   xyz
1374   ./a/                    a/
1375   ./a/b                   a/b
1376
1377 To translate absolute to relative pathnames, just pass them
1378 in: $zip->addTree( '/c/d', 'a' );
1379
1380   original name           zip member name
1381   /c/d/xyz                a/xyz
1382   /c/d/a/                 a/a/
1383   /c/d/a/b                a/a/b
1384
1385 Returns AZ_OK on success. Note that this will not follow
1386 symbolic links to directories. Note also that this does not
1387 check for the validity of filenames.
1388
1389 Note that you generally I<don't> want to make zip archive member names
1390 absolute.
1391
1392 =item $zip->addTreeMatching( $root, $dest, $pattern [,$pred] )
1393
1394 $root is the root of the tree of files and directories to be
1395 added $dest is the name for the root in the zip file (undef
1396 means to use relative pathnames) $pattern is a (non-anchored)
1397 regular expression for filenames to match $pred is an
1398 optional subroutine reference to select files: it is passed
1399 the name of the prospective file or directory in C<$_>, and
1400 if it returns true, the file or directory will be included.
1401 The default is to add all readable files and directories. To
1402 add all files in and below the current dirctory whose names
1403 end in C<.pl>, and make them extract into a subdirectory
1404 named C<xyz>, do this:
1405
1406   $zip->addTreeMatching( '.', 'xyz', '\.pl$' )
1407
1408 To add all I<writable> files in and below the dirctory named
1409 C</abc> whose names end in C<.pl>, and make them extract into
1410 a subdirectory named C<xyz>, do this:
1411
1412   $zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )
1413
1414 Returns AZ_OK on success. Note that this will not follow
1415 symbolic links to directories.
1416
1417 =item $zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );
1418
1419
1420
1421 Update a zip file from a directory tree.
1422
1423 C<updateTree()> takes the same arguments as C<addTree()>, but first
1424 checks to see whether the file or directory already exists in the zip
1425 file, and whether it has been changed.
1426
1427 If the fourth argument C<$mirror> is true, then delete all my members
1428 if corresponding files weren't found.
1429
1430
1431 Returns an error code or AZ_OK if all is well.
1432
1433 =item $zip->extractTree()
1434
1435
1436
1437 =item $zip->extractTree( $root )
1438
1439
1440
1441 =item $zip->extractTree( $root, $dest )
1442
1443
1444
1445 =item $zip->extractTree( $root, $dest, $volume )
1446
1447
1448
1449 If you don't give any arguments at all, will extract all the
1450 files in the zip with their original names.
1451
1452
1453 If you supply one argument for C<$root>, C<extractTree> will extract
1454 all the members whose names start with C<$root> into the current
1455 directory, stripping off C<$root> first.
1456 C<$root> is in Zip (Unix) format.
1457 For instance,
1458
1459   $zip->extractTree( 'a' );
1460
1461 when applied to a zip containing the files:
1462 a/x a/b/c ax/d/e d/e will extract:
1463
1464
1465 a/x as ./x
1466
1467
1468 a/b/c as ./b/c
1469
1470
1471 If you give two arguments, C<extractTree> extracts all the members
1472 whose names start with C<$root>. It will translate C<$root> into
1473 C<$dest> to construct the destination file name.
1474 C<$root> and C<$dest> are in Zip (Unix) format.
1475 For instance,
1476
1477    $zip->extractTree( 'a', 'd/e' );
1478
1479 when applied to a zip containing the files:
1480 a/x a/b/c ax/d/e d/e will extract:
1481
1482
1483 a/x to d/e/x
1484
1485
1486 a/b/c to d/e/b/c and ignore ax/d/e and d/e
1487
1488
1489 If you give three arguments, C<extractTree> extracts all the members
1490 whose names start with C<$root>. It will translate C<$root> into
1491 C<$dest> to construct the destination file name, and then it will
1492 convert to local file system format, using C<$volume> as the name of
1493 the destination volume.
1494
1495
1496 C<$root> and C<$dest> are in Zip (Unix) format.
1497
1498
1499 C<$volume> is in local file system format.
1500
1501
1502 For instance, under Windows,
1503
1504    $zip->extractTree( 'a', 'd/e', 'f:' );
1505
1506 when applied to a zip containing the files:
1507 a/x a/b/c ax/d/e d/e will extract:
1508
1509
1510 a/x to f:d/e/x
1511
1512
1513 a/b/c to f:d/e/b/c and ignore ax/d/e and d/e
1514
1515
1516 If you want absolute paths (the prior example used paths relative to
1517 the current directory on the destination volume, you can specify these
1518 in C<$dest>:
1519
1520    $zip->extractTree( 'a', '/d/e', 'f:' );
1521
1522 when applied to a zip containing the files:
1523 a/x a/b/c ax/d/e d/e will extract:
1524
1525
1526 a/x to f:\d\e\x
1527
1528
1529 a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e
1530
1531 Returns an error code or AZ_OK if everything worked OK.
1532
1533 =back
1534
1535 =head1 MEMBER OPERATIONS
1536
1537
1538 =head2 Member Class Methods
1539
1540
1541 Several constructors allow you to construct members without adding
1542 them to a zip archive. These work the same as the addFile(),
1543 addDirectory(), and addString() zip instance methods described above,
1544 but they don't add the new members to a zip.
1545
1546 =over 4
1547
1548 =item Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )
1549
1550
1551
1552 Construct a new member from the given string. Returns undef
1553 on error.
1554
1555     my $member = Archive::Zip::Member->newFromString( 'This is a test',
1556                                                  'xyz.txt' );
1557
1558 =item newFromFile( $fileName )
1559
1560
1561
1562 Construct a new member from the given file. Returns undef on
1563 error.
1564
1565     my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );
1566
1567 =item newDirectoryNamed( $directoryName [, $zipname ] )
1568
1569
1570
1571 Construct a new member from the given directory.
1572 C<$directoryName> must be a valid name on your file system; it doesn't
1573 have to exist.
1574
1575
1576 If given, C<$zipname> will be the name of the zip member; it must be a
1577 valid Zip (Unix) name. If not given, it will be converted from
1578 C<$directoryName>.
1579
1580
1581 Returns undef on error.
1582
1583     my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );
1584
1585 =back
1586
1587 =head2 Member Simple accessors
1588
1589
1590 These methods get (and/or set) member attribute values.
1591
1592 =over 4
1593
1594 =item versionMadeBy()
1595
1596
1597
1598 Gets the field from the member header.
1599
1600 =item fileAttributeFormat( [$format] )
1601
1602
1603
1604 Gets or sets the field from the member header. These are
1605 C<FA_*> values.
1606
1607 =item versionNeededToExtract()
1608
1609
1610
1611 Gets the field from the member header.
1612
1613 =item bitFlag()
1614
1615
1616
1617 Gets the general purpose bit field from the member header.
1618 This is where the C<GPBF_*> bits live.
1619
1620 =item compressionMethod()
1621
1622
1623
1624 Returns the member compression method. This is the method
1625 that is currently being used to compress the member data.
1626 This will be COMPRESSION_STORED for added string or file
1627 members, or any of the C<COMPRESSION_*> values for members
1628 from a zip file. However, this module can only handle members
1629 whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
1630 format.
1631
1632 =item desiredCompressionMethod( [$method] )
1633
1634
1635
1636 Get or set the member's C<desiredCompressionMethod>. This is
1637 the compression method that will be used when the member is
1638 written. Returns prior desiredCompressionMethod. Only
1639 COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
1640 arguments. Changing to COMPRESSION_STORED will change the
1641 member desiredCompressionLevel to 0; changing to
1642 COMPRESSION_DEFLATED will change the member
1643 desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.
1644
1645 =item desiredCompressionLevel( [$method] )
1646
1647
1648
1649 Get or set the member's desiredCompressionLevel This is the
1650 method that will be used to write. Returns prior
1651 desiredCompressionLevel. Valid arguments are 0 through 9,
1652 COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
1653 COMPRESSION_LEVEL_BEST_COMPRESSION, and
1654 COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
1655 change the desiredCompressionMethod to COMPRESSION_STORED.
1656 All other arguments will change the desiredCompressionMethod
1657 to COMPRESSION_DEFLATED.
1658
1659 =item externalFileName()
1660
1661
1662
1663 Return the member's external file name, if any, or undef.
1664
1665 =item fileName()
1666
1667
1668
1669 Get or set the member's internal filename. Returns the
1670 (possibly new) filename. Names will have backslashes
1671 converted to forward slashes, and will have multiple
1672 consecutive slashes converted to single ones.
1673
1674 =item lastModFileDateTime()
1675
1676
1677
1678 Return the member's last modification date/time stamp in
1679 MS-DOS format.
1680
1681 =item lastModTime()
1682
1683
1684
1685 Return the member's last modification date/time stamp,
1686 converted to unix localtime format.
1687
1688     print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );
1689
1690 =item setLastModFileDateTimeFromUnix()
1691
1692 Set the member's lastModFileDateTime from the given unix
1693 time.
1694
1695     $member->setLastModFileDateTimeFromUnix( time() );
1696
1697 =item internalFileAttributes()
1698
1699 Return the internal file attributes field from the zip
1700 header. This is only set for members read from a zip file.
1701
1702 =item externalFileAttributes()
1703
1704 Return member attributes as read from the ZIP file. Note that
1705 these are NOT UNIX!
1706
1707 =item unixFileAttributes( [$newAttributes] )
1708
1709 Get or set the member's file attributes using UNIX file
1710 attributes. Returns old attributes.
1711
1712     my $oldAttribs = $member->unixFileAttributes( 0666 );
1713
1714 Note that the return value has more than just the file
1715 permissions, so you will have to mask off the lowest bits for
1716 comparisions.
1717
1718 =item localExtraField( [$newField] )
1719
1720 Gets or sets the extra field that was read from the local
1721 header. This is not set for a member from a zip file until
1722 after the member has been written out. The extra field must
1723 be in the proper format.
1724
1725 =item cdExtraField( [$newField] )
1726
1727 Gets or sets the extra field that was read from the central
1728 directory header. The extra field must be in the proper
1729 format.
1730
1731 =item extraFields()
1732
1733 Return both local and CD extra fields, concatenated.
1734
1735 =item fileComment( [$newComment] )
1736
1737 Get or set the member's file comment.
1738
1739 =item hasDataDescriptor()
1740
1741 Get or set the data descriptor flag. If this is set, the
1742 local header will not necessarily have the correct data
1743 sizes. Instead, a small structure will be stored at the end
1744 of the member data with these values. This should be
1745 transparent in normal operation.
1746
1747 =item crc32()
1748
1749 Return the CRC-32 value for this member. This will not be set
1750 for members that were constructed from strings or external
1751 files until after the member has been written.
1752
1753 =item crc32String()
1754
1755 Return the CRC-32 value for this member as an 8 character
1756 printable hex string. This will not be set for members that
1757 were constructed from strings or external files until after
1758 the member has been written.
1759
1760 =item compressedSize()
1761
1762 Return the compressed size for this member. This will not be
1763 set for members that were constructed from strings or
1764 external files until after the member has been written.
1765
1766 =item uncompressedSize()
1767
1768 Return the uncompressed size for this member.
1769
1770 =item isEncrypted()
1771
1772 Return true if this member is encrypted. The Archive::Zip
1773 module does not currently create or extract encrypted
1774 members.
1775
1776 =item isTextFile( [$flag] )
1777
1778 Returns true if I am a text file. Also can set the status if
1779 given an argument (then returns old state). Note that this
1780 module does not currently do anything with this flag upon
1781 extraction or storage. That is, bytes are stored in native
1782 format whether or not they came from a text file.
1783
1784 =item isBinaryFile()
1785
1786 Returns true if I am a binary file. Also can set the status
1787 if given an argument (then returns old state). Note that this
1788 module does not currently do anything with this flag upon
1789 extraction or storage. That is, bytes are stored in native
1790 format whether or not they came from a text file.
1791
1792 =item extractToFileNamed( $fileName )
1793
1794 Extract me to a file with the given name. The file will be
1795 created with default modes. Directories will be created as
1796 needed.
1797 The C<$fileName> argument should be a valid file name on your
1798 file system.
1799 Returns AZ_OK on success.
1800
1801 =item isDirectory()
1802
1803 Returns true if I am a directory.
1804
1805 =item writeLocalHeaderRelativeOffset()
1806
1807 Returns the file offset in bytes the last time I was written.
1808
1809 =item wasWritten()
1810
1811 Returns true if I was successfully written. Reset at the
1812 beginning of a write attempt.
1813
1814 =back
1815
1816 =head2 Low-level member data reading
1817
1818 It is possible to use lower-level routines to access member data
1819 streams, rather than the extract* methods and contents(). For
1820 instance, here is how to print the uncompressed contents of a member
1821 in chunks using these methods:
1822
1823     my ( $member, $status, $bufferRef );
1824     $member = $zip->memberNamed( 'xyz.txt' );
1825     $member->desiredCompressionMethod( COMPRESSION_STORED );
1826     $status = $member->rewindData();
1827     die "error $status" unless $status == AZ_OK;
1828     while ( ! $member->readIsDone() )
1829     {
1830     ( $bufferRef, $status ) = $member->readChunk();
1831     die "error $status"
1832                         if $status != AZ_OK && $status != AZ_STREAM_END;
1833     # do something with $bufferRef:
1834     print $$bufferRef;
1835     }
1836     $member->endRead();
1837
1838 =over 4
1839
1840 =item readChunk( [$chunkSize] )
1841
1842 This reads the next chunk of given size from the member's
1843 data stream and compresses or uncompresses it as necessary,
1844 returning a reference to the bytes read and a status. If size
1845 argument is not given, defaults to global set by
1846 Archive::Zip::setChunkSize. Status is AZ_OK on success until
1847 the last chunk, where it returns AZ_STREAM_END. Returns C<(
1848 \$bytes, $status)>.
1849
1850     my ( $outRef, $status ) = $self->readChunk();
1851     print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;
1852
1853 =item rewindData()
1854
1855 Rewind data and set up for reading data streams or writing
1856 zip files. Can take options for C<inflateInit()> or
1857 C<deflateInit()>, but this isn't likely to be necessary.
1858 Subclass overrides should call this method. Returns C<AZ_OK>
1859 on success.
1860
1861 =item endRead()
1862
1863 Reset the read variables and free the inflater or deflater.
1864 Must be called to close files, etc. Returns AZ_OK on success.
1865
1866 =item readIsDone()
1867
1868 Return true if the read has run out of data or errored out.
1869
1870 =item contents()
1871
1872 Return the entire uncompressed member data or undef in scalar
1873 context. When called in array context, returns C<( $string,
1874 $status )>; status will be AZ_OK on success:
1875
1876     my $string = $member->contents();
1877     # or
1878     my ( $string, $status ) = $member->contents();
1879     die "error $status" unless $status == AZ_OK;
1880
1881 Can also be used to set the contents of a member (this may
1882 change the class of the member):
1883
1884     $member->contents( "this is my new contents" );
1885
1886 =item extractToFileHandle( $fh )
1887
1888 Extract (and uncompress, if necessary) the member's contents
1889 to the given file handle. Return AZ_OK on success.
1890
1891 =back
1892
1893 =head1 Archive::Zip::FileMember methods
1894
1895 The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
1896 base class for both ZipFileMember and NewFileMember classes. This class adds
1897 an C<externalFileName> and an C<fh> member to keep track of the external
1898 file.
1899
1900 =over 4
1901
1902 =item externalFileName()
1903
1904 Return the member's external filename.
1905
1906 =item fh()
1907
1908 Return the member's read file handle. Automatically opens file if
1909 necessary.
1910
1911 =back
1912
1913 =head1 Archive::Zip::ZipFileMember methods
1914
1915 The Archive::Zip::ZipFileMember class represents members that have been read
1916 from external zip files.
1917
1918 =over 4
1919
1920 =item diskNumberStart()
1921
1922 Returns the disk number that the member's local header resides in.
1923 Should be 0.
1924
1925 =item localHeaderRelativeOffset()
1926
1927 Returns the offset into the zip file where the member's local header
1928 is.
1929
1930 =item dataOffset()
1931
1932 Returns the offset from the beginning of the zip file to the member's
1933 data.
1934
1935 =back
1936
1937 =head1 REQUIRED MODULES
1938
1939 L<Archive::Zip> requires several other modules:
1940
1941 L<Carp>
1942
1943 L<Compress::Raw::Zlib>
1944
1945 L<Cwd>
1946
1947 L<File::Basename>
1948
1949 L<File::Copy>
1950
1951 L<File::Find>
1952
1953 L<File::Path>
1954
1955 L<File::Spec>
1956
1957 L<IO::File>
1958
1959 L<IO::Seekable>
1960
1961 L<Time::Local>
1962
1963 =head1 BUGS AND CAVEATS
1964
1965 =head2 When not to use Archive::Zip
1966
1967 If you are just going to be extracting zips (and/or other archives) you
1968 are recommended to look at using L<Archive::Extract> instead, as it is much
1969 easier to use and factors out archive-specific functionality.
1970
1971 =head2 Try to avoid IO::Scalar
1972
1973 One of the most common ways to use Archive::Zip is to generate Zip files
1974 in-memory. Most people have use L<IO::Scalar> for this purpose.
1975
1976 Unfortunately, as of 1.11 this module no longer works with L<IO::Scalar>
1977 as it incorrectly implements seeking.
1978
1979 Anybody using L<IO::Scalar> should consider porting to L<IO::String>,
1980 which is smaller, lighter, and is implemented to be perfectly compatible
1981 with regular seekable filehandles.
1982
1983 Support for L<IO::Scalar> most likely will B<not> be restored in the
1984 future, as L<IO::Scalar> itself cannot change the way it is implemented
1985 due to back-compatibility issues.
1986
1987 =head1 TO DO
1988
1989 * auto-choosing storing vs compression
1990
1991 * extra field hooks (see notes.txt)
1992
1993 * check for dups on addition/renaming?
1994
1995 * Text file extraction (line end translation)
1996
1997 * Reading zip files from non-seekable inputs
1998   (Perhaps by proxying through IO::String?)
1999
2000 * separate unused constants into separate module
2001
2002 * cookbook style docs
2003
2004 * Handle tainted paths correctly
2005
2006 * Work on better compatability with other IO:: modules
2007
2008 =head1 SUPPORT
2009
2010 Bugs should be reported via the CPAN bug tracker
2011
2012 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>
2013
2014 For other issues contact the maintainer
2015
2016 =head1 AUTHOR
2017
2018 Adam Kennedy E<lt>adamk@cpan.orgE<gt>
2019
2020 Previously maintained by Steve Peters E<lt>steve@fisharerojo.orgE<gt>.
2021
2022 File attributes code by Maurice Aubrey E<lt>maurice@lovelyfilth.comE<gt>.
2023
2024 Originally by Ned Konz E<lt>nedkonz@cpan.orgE<gt>.
2025
2026 =head1 COPYRIGHT
2027
2028 Some parts copyright 2006 - 2008 Adam Kennedy.
2029
2030 Some parts copyright 2005 Steve Peters.
2031
2032 Original work copyright 2000 - 2004 Ned Konz.
2033
2034 This program is free software; you can redistribute it and/or modify
2035 it under the same terms as Perl itself.
2036
2037 =head1 SEE ALSO
2038
2039 Look at L<Archive::Zip::MemberRead> which is a wrapper that allows one to
2040 read Zip archive members as if they were files.
2041
2042 L<Compress::Raw::Zlib>, L<Archive::Tar>, L<Archive::Extract>
2043
2044 There is a Japanese translation of this
2045 document at L<http://www.memb.jp/~deq/perl/doc-ja/Archive-Zip.html>
2046 that was done by DEQ E<lt>deq@oct.zaq.ne.jpE<gt> . Thanks!
2047
2048 =cut