~ubuntu-branches/ubuntu/vivid/libarchive-zip-perl/vivid-proposed : revision 6

1

The Archive::Zip module allows a Perl program to create, manipulate,

2

read, and write Zip archive files.

3

4

Zip archives can be created, or you can read from existing zip files.

5

Once created, they can be written to files, streams, or strings.

6

7

Members can be added, removed, extracted, replaced, rearranged, and

8

enumerated. They can also be renamed or have their dates, comments, or

9

other attributes queried or modified. Their data can be compressed or

10

uncompressed as needed. Members can be created from members in existing

11

Zip files, or from existing directories, files, or strings.

12

13

This module uses the Compress::Zlib library to read and write the

14

compressed streams inside the files.

15

16

Examples and helper libraries are given to show how:

17

* zip files can be written to strings

18

* zip files can be written in chunks to arbitrary functions

19

20

Documentation will be installed as man pages for:

21

Archive::Zip

22

Archive::Zip::FAQ

23

Archive::Zip::Tree

24

Archive::Zip::MemberRead

25

26

27

software; you can redistribute it and/or modify it under the same terms

28

as Perl itself.

1

NAME

2

Archive::Zip - Provide an interface to ZIP archive files.

3

4

SYNOPSIS

5

# Create a Zip file

6

use Archive::Zip qw( :ERROR_CODES :CONSTANTS );

7

my $zip = Archive::Zip->new();

8

9

# Add a directory

10

my $dir_member = $zip->addDirectory( 'dirname/' );

11

12

# Add a file from a string with compression

13

my $string_member = $zip->addString( 'This is a test', 'stringMember.txt' );

14

$string_member->desiredCompressionMethod( COMPRESSION_DEFLATED );

15

16

# Add a file from disk

17

my $file_member = $zip->addFile( 'xyz.pl', 'AnotherName.pl' );

18

19

# Save the Zip file

20

unless ( $zip->writeToFileNamed('someZip.zip') == AZ_OK ) {

21

die 'write error';

22

}

23

24

# Read a Zip file

25

my $somezip = Archive::Zip->new();

26

unless ( $somezip->read( 'someZip.zip' ) == AZ_OK ) {

27

die 'read error';

28

}

29

30

# Change the compression type for a file in the Zip

31

my $member = $somezip->memberNamed( 'stringMember.txt' );

32

$member->desiredCompressionMethod( COMPRESSION_STORED );

33

unless ( $zip->writeToFileNamed( 'someOtherZip.zip' ) == AZ_OK ) {

34

die 'write error';

35

}

36

37

DESCRIPTION

38

The Archive::Zip module allows a Perl program to create, manipulate,

39

read, and write Zip archive files.

40

41

Zip archives can be created, or you can read from existing zip files.

42

43

Once created, they can be written to files, streams, or strings. Members

44

can be added, removed, extracted, replaced, rearranged, and enumerated.

45

They can also be renamed or have their dates, comments, or other

46

attributes queried or modified. Their data can be compressed or

47

uncompressed as needed.

48

49

Members can be created from members in existing Zip files, or from

50

existing directories, files, or strings.

51

52

This module uses the Compress::Raw::Zlib library to read and write the

53

compressed streams inside the files.

54

55

One can use Archive::Zip::MemberRead to read the zip file archive

56

members as if they were files.

57

58

File Naming

59

Regardless of what your local file system uses for file naming, names in

60

a Zip file are in Unix format (*forward* slashes (/) separating

61

directory names, etc.).

62

63

"Archive::Zip" tries to be consistent with file naming conventions, and

64

will translate back and forth between native and Zip file names.

65

66

However, it can't guess which format names are in. So two rules control

67

what kind of file name you must pass various routines:

68

69

Names of files are in local format.

70

"File::Spec" and "File::Basename" are used for various file

71

operations. When you're referring to a file on your system, use its

72

file naming conventions.

73

74

Names of archive members are in Unix format.

75

This applies to every method that refers to an archive member, or

76

provides a name for new archive members. The "extract()" methods

77

that can take one or two names will convert from local to zip names

78

if you call them with a single name.

79

80

Archive::Zip Object Model

81

Overview

82

Archive::Zip::Archive objects are what you ordinarily deal with. These

83

maintain the structure of a zip file, without necessarily holding data.

84

When a zip is read from a disk file, the (possibly compressed) data

85

still lives in the file, not in memory. Archive members hold information

86

about the individual members, but not (usually) the actual member data.

87

When the zip is written to a (different) file, the member data is

88

compressed or copied as needed. It is possible to make archive members

89

whose data is held in a string in memory, but this is not done when a

90

zip file is read. Directory members don't have any data.

91

92

Inheritance

93

Exporter

94

Archive::Zip Common base class, has defs.

95

Archive::Zip::Archive A Zip archive.

96

Archive::Zip::Member Abstract superclass for all members.

97

Archive::Zip::StringMember Member made from a string

98

Archive::Zip::FileMember Member made from an external file

99

Archive::Zip::ZipFileMember Member that lives in a zip file

100

Archive::Zip::NewFileMember Member whose data is in a file

101

Archive::Zip::DirectoryMember Member that is a directory

102

103

EXPORTS

104

:CONSTANTS

105

Exports the following constants:

106

107

FA_MSDOS FA_UNIX GPBF_ENCRYPTED_MASK GPBF_DEFLATING_COMPRESSION_MASK

108

GPBF_HAS_DATA_DESCRIPTOR_MASK COMPRESSION_STORED

109

COMPRESSION_DEFLATED IFA_TEXT_FILE_MASK IFA_TEXT_FILE

110

IFA_BINARY_FILE COMPRESSION_LEVEL_NONE COMPRESSION_LEVEL_DEFAULT

111

COMPRESSION_LEVEL_FASTEST COMPRESSION_LEVEL_BEST_COMPRESSION

112

113

:MISC_CONSTANTS

114

Exports the following constants (only necessary for extending the

115

module):

116

117

FA_AMIGA FA_VAX_VMS FA_VM_CMS FA_ATARI_ST FA_OS2_HPFS FA_MACINTOSH

118

FA_Z_SYSTEM FA_CPM FA_WINDOWS_NTFS

119

GPBF_IMPLODING_8K_SLIDING_DICTIONARY_MASK

120

GPBF_IMPLODING_3_SHANNON_FANO_TREES_MASK

121

GPBF_IS_COMPRESSED_PATCHED_DATA_MASK COMPRESSION_SHRUNK

122

DEFLATING_COMPRESSION_NORMAL DEFLATING_COMPRESSION_MAXIMUM

123

DEFLATING_COMPRESSION_FAST DEFLATING_COMPRESSION_SUPER_FAST

124

COMPRESSION_REDUCED_1 COMPRESSION_REDUCED_2 COMPRESSION_REDUCED_3

125

COMPRESSION_REDUCED_4 COMPRESSION_IMPLODED COMPRESSION_TOKENIZED

126

COMPRESSION_DEFLATED_ENHANCED

127

COMPRESSION_PKWARE_DATA_COMPRESSION_LIBRARY_IMPLODED

128

129

:ERROR_CODES

130

Explained below. Returned from most methods.

131

132

AZ_OK AZ_STREAM_END AZ_ERROR AZ_FORMAT_ERROR AZ_IO_ERROR

133

134

ERROR CODES

135

Many of the methods in Archive::Zip return error codes. These are

136

implemented as inline subroutines, using the "use constant" pragma. They

137

can be imported into your namespace using the ":ERROR_CODES" tag:

138

139

use Archive::Zip qw( :ERROR_CODES );

140

141

...

142

143

unless ( $zip->read( 'myfile.zip' ) == AZ_OK ) {

144

die "whoops!";

145

}

146

147

AZ_OK (0)

148

Everything is fine.

149

150

AZ_STREAM_END (1)

151

The read stream (or central directory) ended normally.

152

153

AZ_ERROR (2)

154

There was some generic kind of error.

155

156

AZ_FORMAT_ERROR (3)

157

There is a format error in a ZIP file being read.

158

159

AZ_IO_ERROR (4)

160

There was an IO error.

161

162

Compression

163

Archive::Zip allows each member of a ZIP file to be compressed (using

164

the Deflate algorithm) or uncompressed.

165

166

Other compression algorithms that some versions of ZIP have been able to

167

produce are not supported. Each member has two compression methods: the

168

one it's stored as (this is always COMPRESSION_STORED for string and

169

external file members), and the one you desire for the member in the zip

170

file.

171

172

These can be different, of course, so you can make a zip member that is

173

not compressed out of one that is, and vice versa.

174

175

You can inquire about the current compression and set the desired

176

compression method:

177

178

my $member = $zip->memberNamed( 'xyz.txt' );

179

$member->compressionMethod(); # return current compression

180

181

# set to read uncompressed

182

$member->desiredCompressionMethod( COMPRESSION_STORED );

183

184

# set to read compressed

185

$member->desiredCompressionMethod( COMPRESSION_DEFLATED );

186

187

There are two different compression methods:

188

189

COMPRESSION_STORED

190

File is stored (no compression)

191

192

COMPRESSION_DEFLATED

193

File is Deflated

194

195

Compression Levels

196

If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you can

197

choose different compression levels. This choice may affect the speed of

198

compression and decompression, as well as the size of the compressed

199

member data.

200

201

$member->desiredCompressionLevel( 9 );

202

203

The levels given can be:

204

205

0 or COMPRESSION_LEVEL_NONE

206

This is the same as saying

207

208

$member->desiredCompressionMethod( COMPRESSION_STORED );

209

210

1 .. 9

211

1 gives the best speed and worst compression, and 9 gives the best

212

compression and worst speed.

213

214

COMPRESSION_LEVEL_FASTEST

215

This is a synonym for level 1.

216

217

COMPRESSION_LEVEL_BEST_COMPRESSION

218

This is a synonym for level 9.

219

220

COMPRESSION_LEVEL_DEFAULT

221

This gives a good compromise between speed and compression, and is

222

currently equivalent to 6 (this is in the zlib code). This is the

223

level that will be used if not specified.

224

225

Archive::Zip Methods

226

The Archive::Zip class (and its invisible subclass

227

Archive::Zip::Archive) implement generic zip file functionality.

228

Creating a new Archive::Zip object actually makes an

229

Archive::Zip::Archive object, but you don't have to worry about this

230

unless you're subclassing.

231

232

Constructor

233

new( [$fileName] )

234

Make a new, empty zip archive.

235

236

my $zip = Archive::Zip->new();

237

238

If an additional argument is passed, new() will call read() to read

239

the contents of an archive:

240

241

my $zip = Archive::Zip->new( 'xyz.zip' );

242

243

If a filename argument is passed and the read fails for any reason,

244

new will return undef. For this reason, it may be better to call

245

read separately.

246

247

Zip Archive Utility Methods

248

These Archive::Zip methods may be called as functions or as object

249

methods. Do not call them as class methods:

250

251

$zip = Archive::Zip->new();

252

$crc = Archive::Zip::computeCRC32( 'ghijkl' ); # OK

253

$crc = $zip->computeCRC32( 'ghijkl' ); # also OK

254

$crc = Archive::Zip->computeCRC32( 'ghijkl' ); # NOT OK

255

256

Archive::Zip::computeCRC32( $string [, $crc] )

257

This is a utility function that uses the Compress::Raw::Zlib CRC

258

routine to compute a CRC-32. You can get the CRC of a string:

259

260

$crc = Archive::Zip::computeCRC32( $string );

261

262

Or you can compute the running CRC:

263

264

$crc = 0;

265

$crc = Archive::Zip::computeCRC32( 'abcdef', $crc );

266

$crc = Archive::Zip::computeCRC32( 'ghijkl', $crc );

267

268

Archive::Zip::setChunkSize( $number )

269

Report or change chunk size used for reading and writing. This can

270

make big differences in dealing with large files. Currently, this

271

defaults to 32K. This also changes the chunk size used for

272

Compress::Raw::Zlib. You must call setChunkSize() before reading or

273

writing. This is not exportable, so you must call it like:

274

275

Archive::Zip::setChunkSize( 4096 );

276

277

or as a method on a zip (though this is a global setting). Returns

278

old chunk size.

279

280

Archive::Zip::chunkSize()

281

Returns the current chunk size:

282

283

my $chunkSize = Archive::Zip::chunkSize();

284

285

Archive::Zip::setErrorHandler( \&subroutine )

286

Change the subroutine called with error strings. This defaults to

287

\&Carp::carp, but you may want to change it to get the error

288

strings. This is not exportable, so you must call it like:

289

290

Archive::Zip::setErrorHandler( \&myErrorHandler );

291

292

If myErrorHandler is undef, resets handler to default. Returns old

293

error handler. Note that if you call Carp::carp or a similar routine

294

or if you're chaining to the default error handler from your error

295

handler, you may want to increment the number of caller levels that

296

are skipped (do not just set it to a number):

297

298

$Carp::CarpLevel++;

299

300

Archive::Zip::tempFile( [$tmpdir] )

301

Create a uniquely named temp file. It will be returned open for

302

read/write. If $tmpdir is given, it is used as the name of a

303

directory to create the file in. If not given, creates the file

304

using "File::Spec::tmpdir()". Generally, you can override this

305

choice using the

306

307

$ENV{TMPDIR}

308

309

environment variable. But see the File::Spec documentation for your

310

system. Note that on many systems, if you're running in taint mode,

311

then you must make sure that $ENV{TMPDIR} is untainted for it to be

312

used. Will *NOT* create $tmpdir if it doesn't exist (this is a

313

change from prior versions!). Returns file handle and name:

314

315

my ($fh, $name) = Archive::Zip::tempFile();

316

my ($fh, $name) = Archive::Zip::tempFile('myTempDir');

317

my $fh = Archive::Zip::tempFile(); # if you don't need the name

318

319

Zip Archive Accessors

320

members()

321

Return a copy of the members array

322

323

my @members = $zip->members();

324

325

numberOfMembers()

326

Return the number of members I have

327

328

memberNames()

329

Return a list of the (internal) file names of the zip members

330

331

memberNamed( $string )

332

Return ref to member whose filename equals given filename or undef.

333

$string must be in Zip (Unix) filename format.

334

335

membersMatching( $regex )

336

Return array of members whose filenames match given regular

337

expression in list context. Returns number of matching members in

338

scalar context.

339

340

my @textFileMembers = $zip->membersMatching( '.*\.txt' );

341

# or

342

my $numberOfTextFiles = $zip->membersMatching( '.*\.txt' );

343

344

diskNumber()

345

Return the disk that I start on. Not used for writing zips, but

346

might be interesting if you read a zip in. This should be 0, as

347

Archive::Zip does not handle multi-volume archives.

348

349

diskNumberWithStartOfCentralDirectory()

350

Return the disk number that holds the beginning of the central

351

directory. Not used for writing zips, but might be interesting if

352

you read a zip in. This should be 0, as Archive::Zip does not handle

353

multi-volume archives.

354

355

numberOfCentralDirectoriesOnThisDisk()

356

Return the number of CD structures in the zipfile last read in. Not

357

used for writing zips, but might be interesting if you read a zip

358

in.

359

360

numberOfCentralDirectories()

361

Return the number of CD structures in the zipfile last read in. Not

362

used for writing zips, but might be interesting if you read a zip

363

in.

364

365

centralDirectorySize()

366

Returns central directory size, as read from an external zip file.

367

Not used for writing zips, but might be interesting if you read a

368

zip in.

369

370

centralDirectoryOffsetWRTStartingDiskNumber()

371

Returns the offset into the zip file where the CD begins. Not used

372

for writing zips, but might be interesting if you read a zip in.

373

374

zipfileComment( [$string] )

375

Get or set the zipfile comment. Returns the old comment.

376

377

print $zip->zipfileComment();

378

$zip->zipfileComment( 'New Comment' );

379

380

eocdOffset()

381

Returns the (unexpected) number of bytes between where the EOCD was

382

found and where it expected to be. This is normally 0, but would be

383

positive if something (a virus, perhaps) had added bytes somewhere

384

before the EOCD. Not used for writing zips, but might be interesting

385

if you read a zip in. Here is an example of how you can diagnose

386

this:

387

388

my $zip = Archive::Zip->new('somefile.zip');

389

if ($zip->eocdOffset())

390

{

391

warn "A virus has added ", $zip->eocdOffset, " bytes of garbage\n";

392

}

393

394

The "eocdOffset()" is used to adjust the starting position of member

395

headers, if necessary.

396

397

fileName()

398

Returns the name of the file last read from. If nothing has been

399

read yet, returns an empty string; if read from a file handle,

400

returns the handle in string form.

401

402

Zip Archive Member Operations

403

Various operations on a zip file modify members. When a member is passed

404

as an argument, you can either use a reference to the member itself, or

405

the name of a member. Of course, using the name requires that names be

406

unique within a zip (this is not enforced).

407

408

removeMember( $memberOrName )

409

Remove and return the given member, or match its name and remove it.

410

Returns undef if member or name doesn't exist in this Zip. No-op if

411

member does not belong to this zip.

412

413

replaceMember( $memberOrName, $newMember )

414

Remove and return the given member, or match its name and remove it.

415

Replace with new member. Returns undef if member or name doesn't

416

exist in this Zip, or if $newMember is undefined.

417

418

It is an (undiagnosed) error to provide a $newMember that is a

419

member of the zip being modified.

420

421

my $member1 = $zip->removeMember( 'xyz' );

422

my $member2 = $zip->replaceMember( 'abc', $member1 );

423

# now, $member2 (named 'abc') is not in $zip,

424

# and $member1 (named 'xyz') is, having taken $member2's place.

425

426

extractMember( $memberOrName [, $extractedName ] )

427

Extract the given member, or match its name and extract it. Returns

428

undef if member doesn't exist in this Zip. If optional second arg is

429

given, use it as the name of the extracted member. Otherwise, the

430

internal filename of the member is used as the name of the extracted

431

file or directory. If you pass $extractedName, it should be in the

432

local file system's format. All necessary directories will be

433

created. Returns "AZ_OK" on success.

434

435

extractMemberWithoutPaths( $memberOrName [, $extractedName ] )

436

Extract the given member, or match its name and extract it. Does not

437

use path information (extracts into the current directory). Returns

438

undef if member doesn't exist in this Zip. If optional second arg is

439

given, use it as the name of the extracted member (its paths will be

440

deleted too). Otherwise, the internal filename of the member (minus

441

paths) is used as the name of the extracted file or directory.

442

Returns "AZ_OK" on success.

443

444

addMember( $member )

445

Append a member (possibly from another zip file) to the zip file.

446

Returns the new member. Generally, you will use addFile(),

447

addDirectory(), addFileOrDirectory(), addString(), or read() to add

448

members.

449

450

# Move member named 'abc' to end of zip:

451

my $member = $zip->removeMember( 'abc' );

452

$zip->addMember( $member );

453

454

updateMember( $memberOrName, $fileName )

455

Update a single member from the file or directory named $fileName.

456

Returns the (possibly added or updated) member, if any; "undef" on

457

errors. The comparison is based on "lastModTime()" and (in the case

458

of a non-directory) the size of the file.

459

460

addFile( $fileName [, $newName ] )

461

Append a member whose data comes from an external file, returning

462

the member or undef. The member will have its file name set to the

463

name of the external file, and its desiredCompressionMethod set to

464

COMPRESSION_DEFLATED. The file attributes and last modification time

465

will be set from the file. If the name given does not represent a

466

readable plain file or symbolic link, undef will be returned.

467

$fileName must be in the format required for the local file system.

468

The optional $newName argument sets the internal file name to

469

something different than the given $fileName. $newName, if given,

470

must be in Zip name format (i.e. Unix). The text mode bit will be

471

set if the contents appears to be text (as returned by the "-T" perl

472

operator).

473

474

*NOTE* that you shouldn't (generally) use absolute path names in zip

475

member names, as this will cause problems with some zip tools as

476

well as introduce a security hole and make the zip harder to use.

477

478

addDirectory( $directoryName [, $fileName ] )

479

Append a member created from the given directory name. The directory

480

name does not have to name an existing directory. If the named

481

directory exists, the file modification time and permissions are set

482

from the existing directory, otherwise they are set to now and

483

permissive default permissions. $directoryName must be in local file

484

system format. The optional second argument sets the name of the

485

archive member (which defaults to $directoryName). If given, it must

486

be in Zip (Unix) format. Returns the new member.

487

488

addFileOrDirectory( $name [, $newName ] )

489

Append a member from the file or directory named $name. If $newName

490

is given, use it for the name of the new member. Will add or remove

491

trailing slashes from $newName as needed. $name must be in local

492

file system format. The optional second argument sets the name of

493

the archive member (which defaults to $name). If given, it must be

494

in Zip (Unix) format.

495

496

addString( $stringOrStringRef, $name )

497

Append a member created from the given string or string reference.

498

The name is given by the second argument. Returns the new member.

499

The last modification time will be set to now, and the file

500

attributes will be set to permissive defaults.

501

502

my $member = $zip->addString( 'This is a test', 'test.txt' );

503

504

contents( $memberOrMemberName [, $newContents ] )

505

Returns the uncompressed data for a particular member, or undef.

506

507

print "xyz.txt contains " . $zip->contents( 'xyz.txt' );

508

509

Also can change the contents of a member:

510

511

$zip->contents( 'xyz.txt', 'This is the new contents' );

512

513

If called expecting an array as the return value, it will include

514

the status as the second value in the array.

515

516

($content, $status) = $zip->contents( 'xyz.txt');

517

518

Zip Archive I/O operations

519

A Zip archive can be written to a file or file handle, or read from one.

520

521

writeToFileNamed( $fileName )

522

Write a zip archive to named file. Returns "AZ_OK" on success.

523

524

my $status = $zip->writeToFileNamed( 'xx.zip' );

525

die "error somewhere" if $status != AZ_OK;

526

527

Note that if you use the same name as an existing zip file that you

528

read in, you will clobber ZipFileMembers. So instead, write to a

529

different file name, then delete the original. If you use the

530

"overwrite()" or "overwriteAs()" methods, you can re-write the

531

original zip in this way. $fileName should be a valid file name on

532

your system.

533

534

writeToFileHandle( $fileHandle [, $seekable] )

535

Write a zip archive to a file handle. Return AZ_OK on success. The

536

optional second arg tells whether or not to try to seek backwards to

537

re-write headers. If not provided, it is set if the Perl "-f" test

538

returns true. This could fail on some operating systems, though.

539

540

my $fh = IO::File->new( 'someFile.zip', 'w' );

541

unless ( $zip->writeToFileHandle( $fh ) == AZ_OK ) {

542

# error handling

543

}

544

545

If you pass a file handle that is not seekable (like if you're

546

writing to a pipe or a socket), pass a false second argument:

547

548

my $fh = IO::File->new( '| cat > somefile.zip', 'w' );

549

$zip->writeToFileHandle( $fh, 0 ); # fh is not seekable

550

551

If this method fails during the write of a member, that member and

552

all following it will return false from "wasWritten()". See

553

writeCentralDirectory() for a way to deal with this. If you want,

554

you can write data to the file handle before passing it to

555

writeToFileHandle(); this could be used (for instance) for making

556

self-extracting archives. However, this only works reliably when

557

writing to a real file (as opposed to STDOUT or some other possible

558

non-file).

559

560

See examples/selfex.pl for how to write a self-extracting archive.

561

562

writeCentralDirectory( $fileHandle [, $offset ] )

563

Writes the central directory structure to the given file handle.

564

565

Returns AZ_OK on success. If given an $offset, will seek to that

566

point before writing. This can be used for recovery in cases where

567

writeToFileHandle or writeToFileNamed returns an IO error because of

568

running out of space on the destination file.

569

570

You can truncate the zip by seeking backwards and then writing the

571

directory:

572

573

my $fh = IO::File->new( 'someFile.zip', 'w' );

574

my $retval = $zip->writeToFileHandle( $fh );

575

if ( $retval == AZ_IO_ERROR ) {

576

my @unwritten = grep { not $_->wasWritten() } $zip->members();

577

if (@unwritten) {

578

$zip->removeMember( $member ) foreach my $member ( @unwritten );

579

$zip->writeCentralDirectory( $fh,

580

$unwritten[0]->writeLocalHeaderRelativeOffset());

581

}

582

}

583

584

overwriteAs( $newName )

585

Write the zip to the specified file, as safely as possible. This is

586

done by first writing to a temp file, then renaming the original if

587

it exists, then renaming the temp file, then deleting the renamed

588

original if it exists. Returns AZ_OK if successful.

589

590

overwrite()

591

Write back to the original zip file. See overwriteAs() above. If the

592

zip was not ever read from a file, this generates an error.

593

594

read( $fileName )

595

Read zipfile headers from a zip file, appending new members. Returns

596

"AZ_OK" or error code.

597

598

my $zipFile = Archive::Zip->new();

599

my $status = $zipFile->read( '/some/FileName.zip' );

600

601

readFromFileHandle( $fileHandle, $filename )

602

Read zipfile headers from an already-opened file handle, appending

603

new members. Does not close the file handle. Returns "AZ_OK" or

604

error code. Note that this requires a seekable file handle; reading

605

from a stream is not yet supported.

606

607

my $fh = IO::File->new( '/some/FileName.zip', 'r' );

608

my $zip1 = Archive::Zip->new();

609

my $status = $zip1->readFromFileHandle( $fh );

610

my $zip2 = Archive::Zip->new();

611

$status = $zip2->readFromFileHandle( $fh );

612

613

Zip Archive Tree operations

614

These used to be in Archive::Zip::Tree but got moved into Archive::Zip.

615

They enable operation on an entire tree of members or files. A usage

616

example:

617

618

use Archive::Zip;

619

my $zip = Archive::Zip->new();

620

621

# add all readable files and directories below . as xyz/*

622

$zip->addTree( '.', 'xyz' );

623

624

# add all readable plain files below /abc as def/*

625

$zip->addTree( '/abc', 'def', sub { -f && -r } );

626

627

# add all .c files below /tmp as stuff/*

628

$zip->addTreeMatching( '/tmp', 'stuff', '\.c$' );

629

630

# add all .o files below /tmp as stuff/* if they aren't writable

631

$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { ! -w } );

632

633

# add all .so files below /tmp that are smaller than 200 bytes as stuff/*

634

$zip->addTreeMatching( '/tmp', 'stuff', '\.o$', sub { -s < 200 } );

635

636

# and write them into a file

637

$zip->writeToFileNamed('xxx.zip');

638

639

# now extract the same files into /tmpx

640

$zip->extractTree( 'stuff', '/tmpx' );

641

642

$zip->addTree( $root, $dest [,$pred] ) -- Add tree of files to a zip

643

$root is the root of the tree of files and directories to be added.

644

It is a valid directory name on your system. $dest is the name for

645

the root in the zip file (undef or blank means to use relative

646

pathnames). It is a valid ZIP directory name (that is, it uses

647

forward slashes (/) for separating directory components). $pred is

648

an optional subroutine reference to select files: it is passed the

649

name of the prospective file or directory using $_, and if it

650

returns true, the file or directory will be included. The default is

651

to add all readable files and directories. For instance, using

652

653

my $pred = sub { /\.txt/ };

654

$zip->addTree( '.', '', $pred );

655

656

will add all the .txt files in and below the current directory,

657

using relative names, and making the names identical in the zipfile:

658

659

original name zip member name

660

./xyz xyz

661

./a/ a/

662

./a/b a/b

663

664

To translate absolute to relative pathnames, just pass them in:

665

$zip->addTree( '/c/d', 'a' );

666

667

original name zip member name

668

/c/d/xyz a/xyz

669

/c/d/a/ a/a/

670

/c/d/a/b a/a/b

671

672

Returns AZ_OK on success. Note that this will not follow symbolic

673

links to directories. Note also that this does not check for the

674

validity of filenames.

675

676

Note that you generally *don't* want to make zip archive member

677

names absolute.

678

679

$zip->addTreeMatching( $root, $dest, $pattern [,$pred] )

680

$root is the root of the tree of files and directories to be added

681

$dest is the name for the root in the zip file (undef means to use

682

relative pathnames) $pattern is a (non-anchored) regular expression

683

for filenames to match $pred is an optional subroutine reference to

684

select files: it is passed the name of the prospective file or

685

directory in $_, and if it returns true, the file or directory will

686

be included. The default is to add all readable files and

687

directories. To add all files in and below the current dirctory

688

whose names end in ".pl", and make them extract into a subdirectory

689

named "xyz", do this:

690

691

$zip->addTreeMatching( '.', 'xyz', '\.pl$' )

692

693

To add all *writable* files in and below the dirctory named "/abc"

694

whose names end in ".pl", and make them extract into a subdirectory

695

named "xyz", do this:

696

697

$zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )

698

699

Returns AZ_OK on success. Note that this will not follow symbolic

700

links to directories.

701

702

$zip->updateTree( $root, [ $dest, [ $pred [, $mirror]]] );

703

Update a zip file from a directory tree.

704

705

"updateTree()" takes the same arguments as "addTree()", but first

706

checks to see whether the file or directory already exists in the

707

zip file, and whether it has been changed.

708

709

If the fourth argument $mirror is true, then delete all my members

710

if corresponding files weren't found.

711

712

Returns an error code or AZ_OK if all is well.

713

714

$zip->extractTree()

715

$zip->extractTree( $root )

716

$zip->extractTree( $root, $dest )

717

$zip->extractTree( $root, $dest, $volume )

718

If you don't give any arguments at all, will extract all the files

719

in the zip with their original names.

720

721

If you supply one argument for $root, "extractTree" will extract all

722

the members whose names start with $root into the current directory,

723

stripping off $root first. $root is in Zip (Unix) format. For

724

instance,

725

726

$zip->extractTree( 'a' );

727

728

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e

729

will extract:

730

731

a/x as ./x

732

733

a/b/c as ./b/c

734

735

If you give two arguments, "extractTree" extracts all the members

736

whose names start with $root. It will translate $root into $dest to

737

construct the destination file name. $root and $dest are in Zip

738

(Unix) format. For instance,

739

740

$zip->extractTree( 'a', 'd/e' );

741

742

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e

743

will extract:

744

745

a/x to d/e/x

746

747

a/b/c to d/e/b/c and ignore ax/d/e and d/e

748

749

If you give three arguments, "extractTree" extracts all the members

750

whose names start with $root. It will translate $root into $dest to

751

construct the destination file name, and then it will convert to

752

local file system format, using $volume as the name of the

753

destination volume.

754

755

$root and $dest are in Zip (Unix) format.

756

757

$volume is in local file system format.

758

759

For instance, under Windows,

760

761

$zip->extractTree( 'a', 'd/e', 'f:' );

762

763

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e

764

will extract:

765

766

a/x to f:d/e/x

767

768

a/b/c to f:d/e/b/c and ignore ax/d/e and d/e

769

770

If you want absolute paths (the prior example used paths relative to

771

the current directory on the destination volume, you can specify

772

these in $dest:

773

774

$zip->extractTree( 'a', '/d/e', 'f:' );

775

776

when applied to a zip containing the files: a/x a/b/c ax/d/e d/e

777

will extract:

778

779

a/x to f:\d\e\x

780

781

a/b/c to f:\d\e\b\c and ignore ax/d/e and d/e

782

783

Returns an error code or AZ_OK if everything worked OK.

784

785

MEMBER OPERATIONS

786

Member Class Methods

787

Several constructors allow you to construct members without adding them

788

to a zip archive. These work the same as the addFile(), addDirectory(),

789

and addString() zip instance methods described above, but they don't add

790

the new members to a zip.

791

792

Archive::Zip::Member->newFromString( $stringOrStringRef [, $fileName] )

793

Construct a new member from the given string. Returns undef on

794

error.

795

796

my $member = Archive::Zip::Member->newFromString( 'This is a test',

797

'xyz.txt' );

798

799

newFromFile( $fileName )

800

Construct a new member from the given file. Returns undef on error.

801

802

my $member = Archive::Zip::Member->newFromFile( 'xyz.txt' );

803

804

newDirectoryNamed( $directoryName [, $zipname ] )

805

Construct a new member from the given directory. $directoryName must

806

be a valid name on your file system; it doesn't have to exist.

807

808

If given, $zipname will be the name of the zip member; it must be a

809

valid Zip (Unix) name. If not given, it will be converted from

810

$directoryName.

811

812

Returns undef on error.

813

814

my $member = Archive::Zip::Member->newDirectoryNamed( 'CVS/' );

815

816

Member Simple accessors

817

These methods get (and/or set) member attribute values.

818

819

versionMadeBy()

820

Gets the field from the member header.

821

822

fileAttributeFormat( [$format] )

823

Gets or sets the field from the member header. These are "FA_*"

824

values.

825

826

versionNeededToExtract()

827

Gets the field from the member header.

828

829

bitFlag()

830

Gets the general purpose bit field from the member header. This is

831

where the "GPBF_*" bits live.

832

833

compressionMethod()

834

Returns the member compression method. This is the method that is

835

currently being used to compress the member data. This will be

836

COMPRESSION_STORED for added string or file members, or any of the

837

"COMPRESSION_*" values for members from a zip file. However, this

838

module can only handle members whose data is in COMPRESSION_STORED

839

or COMPRESSION_DEFLATED format.

840

841

desiredCompressionMethod( [$method] )

842

Get or set the member's "desiredCompressionMethod". This is the

843

compression method that will be used when the member is written.

844

Returns prior desiredCompressionMethod. Only COMPRESSION_DEFLATED or

845

COMPRESSION_STORED are valid arguments. Changing to

846

COMPRESSION_STORED will change the member desiredCompressionLevel to

847

0; changing to COMPRESSION_DEFLATED will change the member

848

desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.

849

850

desiredCompressionLevel( [$method] )

851

Get or set the member's desiredCompressionLevel This is the method

852

that will be used to write. Returns prior desiredCompressionLevel.

853

Valid arguments are 0 through 9, COMPRESSION_LEVEL_NONE,

854

COMPRESSION_LEVEL_DEFAULT, COMPRESSION_LEVEL_BEST_COMPRESSION, and

855

COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will change

856

the desiredCompressionMethod to COMPRESSION_STORED. All other

857

arguments will change the desiredCompressionMethod to

858

COMPRESSION_DEFLATED.

859

860

externalFileName()

861

Return the member's external file name, if any, or undef.

862

863

fileName()

864

Get or set the member's internal filename. Returns the (possibly

865

new) filename. Names will have backslashes converted to forward

866

slashes, and will have multiple consecutive slashes converted to

867

single ones.

868

869

lastModFileDateTime()

870

Return the member's last modification date/time stamp in MS-DOS

871

format.

872

873

lastModTime()

874

Return the member's last modification date/time stamp, converted to

875

unix localtime format.

876

877

print "Mod Time: " . scalar( localtime( $member->lastModTime() ) );

878

879

setLastModFileDateTimeFromUnix()

880

Set the member's lastModFileDateTime from the given unix time.

881

882

$member->setLastModFileDateTimeFromUnix( time() );

883

884

internalFileAttributes()

885

Return the internal file attributes field from the zip header. This

886

is only set for members read from a zip file.

887

888

externalFileAttributes()

889

Return member attributes as read from the ZIP file. Note that these

890

are NOT UNIX!

891

892

unixFileAttributes( [$newAttributes] )

893

Get or set the member's file attributes using UNIX file attributes.

894

Returns old attributes.

895

896

my $oldAttribs = $member->unixFileAttributes( 0666 );

897

898

Note that the return value has more than just the file permissions,

899

so you will have to mask off the lowest bits for comparisions.

900

901

localExtraField( [$newField] )

902

Gets or sets the extra field that was read from the local header.

903

This is not set for a member from a zip file until after the member

904

has been written out. The extra field must be in the proper format.

905

906

cdExtraField( [$newField] )

907

Gets or sets the extra field that was read from the central

908

directory header. The extra field must be in the proper format.

909

910

extraFields()

911

Return both local and CD extra fields, concatenated.

912

913

fileComment( [$newComment] )

914

Get or set the member's file comment.

915

916

hasDataDescriptor()

917

Get or set the data descriptor flag. If this is set, the local

918

header will not necessarily have the correct data sizes. Instead, a

919

small structure will be stored at the end of the member data with

920

these values. This should be transparent in normal operation.

921

922

crc32()

923

Return the CRC-32 value for this member. This will not be set for

924

members that were constructed from strings or external files until

925

after the member has been written.

926

927

crc32String()

928

Return the CRC-32 value for this member as an 8 character printable

929

hex string. This will not be set for members that were constructed

930

from strings or external files until after the member has been

931

written.

932

933

compressedSize()

934

Return the compressed size for this member. This will not be set for

935

members that were constructed from strings or external files until

936

after the member has been written.

937

938

uncompressedSize()

939

Return the uncompressed size for this member.

940

941

isEncrypted()

942

Return true if this member is encrypted. The Archive::Zip module

943

does not currently create or extract encrypted members.

944

945

isTextFile( [$flag] )

946

Returns true if I am a text file. Also can set the status if given

947

an argument (then returns old state). Note that this module does not

948

currently do anything with this flag upon extraction or storage.

949

That is, bytes are stored in native format whether or not they came

950

from a text file.

951

952

isBinaryFile()

953

Returns true if I am a binary file. Also can set the status if given

954

an argument (then returns old state). Note that this module does not

955

currently do anything with this flag upon extraction or storage.

956

That is, bytes are stored in native format whether or not they came

957

from a text file.

958

959

extractToFileNamed( $fileName )

960

Extract me to a file with the given name. The file will be created

961

with default modes. Directories will be created as needed. The

962

$fileName argument should be a valid file name on your file system.

963

Returns AZ_OK on success.

964

965

isDirectory()

966

Returns true if I am a directory.

967

968

writeLocalHeaderRelativeOffset()

969

Returns the file offset in bytes the last time I was written.

970

971

wasWritten()

972

Returns true if I was successfully written. Reset at the beginning

973

of a write attempt.

974

975

Low-level member data reading

976

It is possible to use lower-level routines to access member data

977

streams, rather than the extract* methods and contents(). For instance,

978

here is how to print the uncompressed contents of a member in chunks

979

using these methods:

980

981

my ( $member, $status, $bufferRef );

982

$member = $zip->memberNamed( 'xyz.txt' );

983

$member->desiredCompressionMethod( COMPRESSION_STORED );

984

$status = $member->rewindData();

985

die "error $status" unless $status == AZ_OK;

986

while ( ! $member->readIsDone() )

987

{

988

( $bufferRef, $status ) = $member->readChunk();

989

die "error $status"

990

if $status != AZ_OK && $status != AZ_STREAM_END;

991

# do something with $bufferRef:

992

print $$bufferRef;

993

}

994

$member->endRead();

995

996

readChunk( [$chunkSize] )

997

This reads the next chunk of given size from the member's data

998

stream and compresses or uncompresses it as necessary, returning a

999

reference to the bytes read and a status. If size argument is not

1000

given, defaults to global set by Archive::Zip::setChunkSize. Status

1001

is AZ_OK on success until the last chunk, where it returns

1002

AZ_STREAM_END. Returns "( \$bytes, $status)".

1003

1004

my ( $outRef, $status ) = $self->readChunk();

1005

print $$outRef if $status != AZ_OK && $status != AZ_STREAM_END;

1006

1007

rewindData()

1008

Rewind data and set up for reading data streams or writing zip

1009

files. Can take options for "inflateInit()" or "deflateInit()", but

1010

this isn't likely to be necessary. Subclass overrides should call

1011

this method. Returns "AZ_OK" on success.

1012

1013

endRead()

1014

Reset the read variables and free the inflater or deflater. Must be

1015

called to close files, etc. Returns AZ_OK on success.

1016

1017

readIsDone()

1018

Return true if the read has run out of data or errored out.

1019

1020

contents()

1021

Return the entire uncompressed member data or undef in scalar

1022

context. When called in array context, returns "( $string, $status

1023

)"; status will be AZ_OK on success:

1024

1025

my $string = $member->contents();

1026

# or

1027

my ( $string, $status ) = $member->contents();

1028

die "error $status" unless $status == AZ_OK;

1029

1030

Can also be used to set the contents of a member (this may change

1031

the class of the member):

1032

1033

$member->contents( "this is my new contents" );

1034

1035

extractToFileHandle( $fh )

1036

Extract (and uncompress, if necessary) the member's contents to the

1037

given file handle. Return AZ_OK on success.

1038

1039

Archive::Zip::FileMember methods

1040

The Archive::Zip::FileMember class extends Archive::Zip::Member. It is

1041

the base class for both ZipFileMember and NewFileMember classes. This

1042

class adds an "externalFileName" and an "fh" member to keep track of the

1043

external file.

1044

1045

externalFileName()

1046

Return the member's external filename.

1047

1048

fh()

1049

Return the member's read file handle. Automatically opens file if

1050

necessary.

1051

1052

Archive::Zip::ZipFileMember methods

1053

The Archive::Zip::ZipFileMember class represents members that have been

1054

read from external zip files.

1055

1056

diskNumberStart()

1057

Returns the disk number that the member's local header resides in.

1058

Should be 0.

1059

1060

localHeaderRelativeOffset()

1061

Returns the offset into the zip file where the member's local header

1062

is.

1063

1064

dataOffset()

1065

Returns the offset from the beginning of the zip file to the

1066

member's data.

1067

1068

REQUIRED MODULES

1069

Archive::Zip requires several other modules:

1070

1071

Carp

1072

1073

Compress::Raw::Zlib

1074

1075

Cwd

1076

1077

File::Basename

1078

1079

File::Copy

1080

1081

File::Find

1082

1083

File::Path

1084

1085

File::Spec

1086

1087

IO::File

1088

1089

IO::Seekable

1090

1091

Time::Local

1092

1093

BUGS AND CAVEATS

1094

When not to use Archive::Zip

1095

If you are just going to be extracting zips (and/or other archives) you

1096

are recommended to look at using Archive::Extract instead, as it is much

1097

easier to use and factors out archive-specific functionality.

1098

1099

Try to avoid IO::Scalar

1100

One of the most common ways to use Archive::Zip is to generate Zip files

1101

in-memory. Most people have use IO::Scalar for this purpose.

1102

1103

Unfortunately, as of 1.11 this module no longer works with IO::Scalar as

1104

it incorrectly implements seeking.

1105

1106

Anybody using IO::Scalar should consider porting to IO::String, which is

1107

smaller, lighter, and is implemented to be perfectly compatible with

1108

regular seekable filehandles.

1109

1110

Support for IO::Scalar most likely will not be restored in the future,

1111

as IO::Scalar itself cannot change the way it is implemented due to

1112

back-compatibility issues.

1113

1114

TO DO

1115

* auto-choosing storing vs compression

1116

1117

* extra field hooks (see notes.txt)

1118

1119

* check for dups on addition/renaming?

1120

1121

* Text file extraction (line end translation)

1122

1123

* Reading zip files from non-seekable inputs (Perhaps by proxying

1124

through IO::String?)

1125

1126

* separate unused constants into separate module

1127

1128

* cookbook style docs

1129

1130

* Handle tainted paths correctly

1131

1132

* Work on better compatability with other IO:: modules

1133

1134

SUPPORT

1135

Bugs should be reported via the CPAN bug tracker

1136

1137

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Archive-Zip>

1138

1139

For other issues contact the maintainer

1140

1141

AUTHOR

1142

Adam Kennedy <adamk@cpan.org>

1143

1144

Previously maintained by Steve Peters <steve@fisharerojo.org>.

1145

1146

File attributes code by Maurice Aubrey <maurice@lovelyfilth.com>.

1147

1148

Originally by Ned Konz <nedkonz@cpan.org>.

1149

1150

COPYRIGHT

1151

1152

1153

1154

1155

1156

1157

This program is free software; you can redistribute it and/or modify it

1158

under the same terms as Perl itself.

1159

1160