ext/Compress/Zlib/pod/FAQ.pod

   1
   2 =head1 NAME
   3
   4 Compress::Zlib::FAQ -- Frequently Asked Questions about Compress::Zlib
   5
   6 =head1 DESCRIPTION
   7
   8 Common questions answered.
   9
  10
  11
  12 =head2 Compatibility with Unix compress/uncompress.
  13
  14 Although C<Compress::Zlib> has a pair of functions called C<compress> and
  15 C<uncompress>, they are I<not> the same as the Unix programs of the same
  16 name. The C<Compress::Zlib> library is not compatible with Unix
  17 C<compress>.
  18
  19 If you have the C<uncompress> program available, you can use this to read
  20 compressed files
  21
  22     open F, "uncompress -c $filename |";
  23     while (<F>)
  24     {
  25         ...
  26
  27 Alternatively, if you have the C<gunzip> program available, you can use
  28 this to read compressed files
  29
  30     open F, "gunzip -c $filename |";
  31     while (<F>)
  32     {
  33         ...
  34
  35 and this to write compress files if you have the C<compress> program
  36 available
  37
  38     open F, "| compress -c $filename ";
  39     print F "data";
  40     ...
  41     close F ;
  42
  43 =head2 Accessing .tar.Z files
  44
  45 The C<Archive::Tar> module can optionally use C<Compress::Zlib> (via the
  46 C<IO::Zlib> module) to access tar files that have been compressed with
  47 C<gzip>. Unfortunately tar files compressed with the Unix C<compress>
  48 utility cannot be read by C<Compress::Zlib> and so cannot be directly
  49 accesses by C<Archive::Tar>.
  50
  51 If the C<uncompress> or C<gunzip> programs are available, you can use one
  52 of these workarounds to read C<.tar.Z> files from C<Archive::Tar>
  53
  54 Firstly with C<uncompress>
  55
  56     use strict;
  57     use warnings;
  58     use Archive::Tar;
  59
  60     open F, "uncompress -c $filename |";
  61     my $tar = Archive::Tar->new(*F);
  62     ...
  63
  64 and this with C<gunzip>
  65
  66     use strict;
  67     use warnings;
  68     use Archive::Tar;
  69
  70     open F, "gunzip -c $filename |";
  71     my $tar = Archive::Tar->new(*F);
  72     ...
  73
  74 Similarly, if the C<compress> program is available, you can use this to
  75 write a C<.tar.Z> file
  76
  77     use strict;
  78     use warnings;
  79     use Archive::Tar;
  80     use IO::File;
  81
  82     my $fh = new IO::File "| compress -c >$filename";
  83     my $tar = Archive::Tar->new();
  84     ...
  85     $tar->write($fh);
  86     $fh->close ;
  87
  88
  89 =head2 Accessing Zip Files
  90
  91
  92
  93
  94 Although it is possible (with some effort on your part) to use this
  95 module to access .zip files, there is a module on CPAN that will do all
  96 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
  97
  98     http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
  99
 100 Assuming you don't want to use this module to access zip files there
 101 are a number of undocumented features in the zlib library you need to
 102 be aware of.
 103
 104 =over 5
 105
 106 =item 1.
 107
 108 When calling B<Compress::Zlib::Inflate::new> or
 109 B<Compress::Zlib::Deflate::new> the B<WindowBits> parameter must be set to
 110 C<-MAX_WBITS>. This enables the creation of an RFC1951 compressed data
 111 stream.
 112
 113 =item 2.
 114
 115 If you are using zlib older than 1.2.0,
 116 The zlib function B<inflate>, and so the B<inflate> method supplied in
 117 this module, assume that there is at least one trailing byte after the
 118 compressed data stream. Normally this isn't a problem because both
 119 the gzip and zip file formats will guarantee that there is data directly
 120 after the compressed data stream.
 121
 122 =back
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135 =head2 Zlib Library Version Support
 136
 137 By default C<Compress::Zlib> will build with a private copy of version
 138 1.2.3 of the zlib library. (See the F<README> file for details of
 139 how to override this behaviour)
 140
 141 If you decide to use a different version of the zlib library, you need to be
 142 aware of the following issues
 143
 144 =over 5
 145
 146 =item *
 147
 148 First off, you must have zlib 1.0.5 or better.
 149
 150 =item *
 151
 152 You need to have zlib 1.2.1 or better if you want to use the C<-Merge>
 153 option with C<IO::Compress::Gzip>, C<IO::Compress::Deflate> and
 154 C<IO::Compress::RawDeflate>.
 155
 156
 157
 158 =back
 159
 160
 161
 162
 163 =head1 SEE ALSO
 164
 165 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Uncompress::AnyInflate>
 166
 167 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
 168
 169 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
 170 L<IO::Zlib|IO::Zlib>
 171
 172 For RFC 1950, 1951 and 1952 see
 173 F<http://www.faqs.org/rfcs/rfc1950.html>,
 174 F<http://www.faqs.org/rfcs/rfc1951.html> and
 175 F<http://www.faqs.org/rfcs/rfc1952.html>
 176
 177 The primary site for the gzip program is F<http://www.gzip.org>.
 178
 179 =head1 AUTHOR
 180
 181 The I<> module was written by Paul Marquess,
 182 F<pmqs@cpan.org>. The latest copy of the module can be
 183 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
 184
 185 The I<zlib> compression library was written by Jean-loup Gailly
 186 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
 187
 188 The primary site for the I<zlib> compression library is
 189 F<http://www.zlib.org>.
 190
 191 =head1 MODIFICATION HISTORY
 192
 193 See the Changes file.
 194
 195 =head1 COPYRIGHT AND LICENSE
 196
 197
 198 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
 199 This program is free software; you can redistribute it and/or
 200 modify it under the same terms as Perl itself.
 201
 202
 203
 204
 205