home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _fe4bf6fb8dc90e0c646cddcc376e3d8e < prev    next >
Text File  |  2000-03-23  |  29KB  |  693 lines

  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Compress::Zlib - Interface to zlib compression library</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Compress::Zlib - Interface to zlib compression library</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#deflate">DEFLATE</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#($d, $status) = deflateinit( [opt] )"><STRONG>($d, $status) = deflateInit( [OPT] )</STRONG></A></LI>
  29.         <LI><A HREF="#($out, $status) = $d>deflate($buffer)"><STRONG>($out, $status) = $d->deflate($buffer)</STRONG></A></LI>
  30.         <LI><A HREF="#($out, $status) = $d>flush()"><STRONG>($out, $status) = $d->flush()</STRONG></A></LI>
  31.         <LI><A HREF="#$d>dict_adler()"><STRONG>$d->dict_adler()</STRONG></A></LI>
  32.         <LI><A HREF="#example">Example</A></LI>
  33.     </UL>
  34.  
  35.     <LI><A HREF="#inflate">INFLATE</A></LI>
  36.     <UL>
  37.  
  38.         <LI><A HREF="#($i, $status) = inflateinit()"><STRONG>($i, $status) = inflateInit()</STRONG></A></LI>
  39.         <LI><A HREF="#($out, $status) = $i>inflate($buffer)"><STRONG>($out, $status) = $i->inflate($buffer)</STRONG></A></LI>
  40.         <LI><A HREF="#$i>dict_adler()"><STRONG>$i->dict_adler()</STRONG></A></LI>
  41.         <LI><A HREF="#example">Example</A></LI>
  42.     </UL>
  43.  
  44.     <LI><A HREF="#compress/uncompress">COMPRESS/UNCOMPRESS</A></LI>
  45.     <LI><A HREF="#gzip interface">GZIP INTERFACE</A></LI>
  46.     <UL>
  47.  
  48.         <LI><A HREF="#examples">Examples</A></LI>
  49.         <LI><A HREF="#compress::zlib::memgzip">Compress::Zlib::memGzip</A></LI>
  50.     </UL>
  51.  
  52.     <LI><A HREF="#checksum functions">CHECKSUM FUNCTIONS</A></LI>
  53.     <LI><A HREF="#constants">CONSTANTS</A></LI>
  54.     <LI><A HREF="#author">AUTHOR</A></LI>
  55.     <LI><A HREF="#modification history">MODIFICATION HISTORY</A></LI>
  56.     <UL>
  57.  
  58.         <LI><A HREF="#0.1 2nd october 1995.">0.1 2nd October 1995.</A></LI>
  59.         <LI><A HREF="#0.2 5th october 1995.">0.2 5th October 1995.</A></LI>
  60.         <LI><A HREF="#0.3 12th october 1995.">0.3 12th October 1995.</A></LI>
  61.         <LI><A HREF="#0.4 25th june 1996.">0.4 25th June 1996.</A></LI>
  62.         <LI><A HREF="#0.50 19th feb 1997">0.50 19th Feb 1997</A></LI>
  63.         <LI><A HREF="#1.00 14 nov 1997">1.00 14 Nov 1997</A></LI>
  64.         <LI><A HREF="#1.01 23 nov 1997">1.01 23 Nov 1997</A></LI>
  65.         <LI><A HREF="#1.02 10 jan 1998">1.02 10 Jan 1998</A></LI>
  66.         <LI><A HREF="#1.03 17 mar 1999">1.03 17 Mar 1999</A></LI>
  67.     </UL>
  68.  
  69. </UL>
  70. <!-- INDEX END -->
  71.  
  72. <HR>
  73. <P>
  74. <HR>
  75. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  76. <UL>
  77. <LI>Linux</LI>
  78. <LI>Solaris</LI>
  79. <LI>Windows</LI>
  80. </UL>
  81. <HR>
  82. <H1><A NAME="name">NAME</A></H1>
  83. <P>Compress::Zlib - Interface to zlib compression library</P>
  84. <P>
  85. <HR>
  86. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  87. <PRE>
  88.     use Compress::Zlib ;</PRE>
  89. <PRE>
  90.     ($d, $status) = deflateInit( [OPT] ) ;
  91.     ($out, $status) = $d->deflate($buffer) ;
  92.     ($out, $status) = $d->flush() ;
  93.     $d->dict_adler() ;</PRE>
  94. <PRE>
  95.     ($i, $status) = inflateInit( [OPT] ) ;
  96.     ($out, $status) = $i->inflate($buffer) ;
  97.     $i->dict_adler() ;</PRE>
  98. <PRE>
  99.     $dest = compress($source) ;
  100.     $dest = uncompress($source) ;</PRE>
  101. <PRE>
  102.     $gz = gzopen($filename or filehandle, $mode) ;
  103.     $bytesread = $gz->gzread($buffer [,$size]) ;
  104.     $bytesread = $gz->gzreadline($line) ;
  105.     $byteswritten = $gz->gzwrite($buffer) ;
  106.     $status = $gz->gzflush($flush) ;
  107.     $status = $gz->gzclose() ;
  108.     $errstring = $gz->gzerror() ; 
  109.     $gzerrno</PRE>
  110. <PRE>
  111.     $dest = Compress::Zlib::memGzip($buffer) ;</PRE>
  112. <PRE>
  113.     $crc = adler32($buffer [,$crc]) ;
  114.     $crc = crc32($buffer [,$crc]) ;</PRE>
  115. <PRE>
  116.     ZLIB_VERSION</PRE>
  117. <P>
  118. <HR>
  119. <H1><A NAME="description">DESCRIPTION</A></H1>
  120. <P>The <EM>Compress::Zlib</EM> module provides a Perl interface to the <EM>zlib</EM>
  121. compression library (see <A HREF="#authors">AUTHORS</A> for details about where to get
  122. <EM>zlib</EM>). Most of the functionality provided by <EM>zlib</EM> is available
  123. in <EM>Compress::Zlib</EM>.</P>
  124. <P>The module can be split into two general areas of functionality, namely
  125. in-memory compression/decompression and read/write access to <EM>gzip</EM>
  126. files. Each of these areas will be discussed separately below.</P>
  127. <P>
  128. <HR>
  129. <H1><A NAME="deflate">DEFLATE</A></H1>
  130. <P>The interface <EM>Compress::Zlib</EM> provides to the in-memory <EM>deflate</EM>
  131. (and <EM>inflate</EM>) functions has been modified to fit into a Perl model.</P>
  132. <P>The main difference is that for both inflation and deflation, the Perl
  133. interface will <EM>always</EM> consume the complete input buffer before
  134. returning. Also the output buffer returned will be automatically grown
  135. to fit the amount of output available.</P>
  136. <P>Here is a definition of the interface available:</P>
  137. <P>
  138. <H2><A NAME="($d, $status) = deflateinit( [opt] )"><STRONG>($d, $status) = deflateInit( [OPT] )</STRONG></A></H2>
  139. <P>Initialises a deflation stream.</P>
  140. <P>It combines the features of the <EM>zlib</EM> functions <STRONG>deflateInit</STRONG>,
  141. <STRONG>deflateInit2</STRONG> and <STRONG>deflateSetDictionary</STRONG>.</P>
  142. <P>If successful, it will return the initialised deflation stream, <STRONG>$d</STRONG>
  143. and <STRONG>$status</STRONG> of <CODE>Z_OK</CODE> in a list context. In scalar context it
  144. returns the deflation stream, <STRONG>$d</STRONG>, only.</P>
  145. <P>If not successful, the returned deflation stream (<STRONG>$d</STRONG>) will be
  146. <EM>undef</EM> and <STRONG>$status</STRONG> will hold the exact <EM>zlib</EM> error code.</P>
  147. <P>The function optionally takes a number of named options specified as
  148. <CODE>-Name=>value</CODE> pairs. This allows individual options to be
  149. tailored without having to specify them all in the parameter list.</P>
  150. <P>For backward compatability, it is also possible to pass the parameters
  151. as a reference to a hash containing the name=>value pairs.</P>
  152. <P>The function takes one optional parameter, a reference to a hash.  The
  153. contents of the hash allow the deflation interface to be tailored.</P>
  154. <P>Here is a list of the valid options:</P>
  155. <DL>
  156. <DT><STRONG><A NAME="item_%2DLevel"><STRONG>-Level</STRONG></A></STRONG><BR>
  157. <DD>
  158. Defines the compression level. Valid values are 1 through 9,
  159. <CODE>Z_BEST_SPEED</CODE>, <CODE>Z_BEST_COMPRESSION</CODE>, and <CODE>Z_DEFAULT_COMPRESSION</CODE>.
  160. <P>The default is <CODE>-Level =>Z_DEFAULT_COMPRESSION</CODE>.</P>
  161. <P></P>
  162. <DT><STRONG><A NAME="item_%2DMethod"><STRONG>-Method</STRONG></A></STRONG><BR>
  163. <DD>
  164. Defines the compression method. The only valid value at present (and
  165. the default) is <CODE>-Method =>Z_DEFLATED</CODE>.
  166. <P></P>
  167. <DT><STRONG><A NAME="item_%2DWindowBits"><STRONG>-WindowBits</STRONG></A></STRONG><BR>
  168. <DD>
  169. For a definition of the meaning and valid values for <STRONG>WindowBits</STRONG>
  170. refer to the <EM>zlib</EM> documentation for <EM>deflateInit2</EM>.
  171. <P>Defaults to <CODE>-WindowBits =>MAX_WBITS</CODE>.</P>
  172. <P></P>
  173. <DT><STRONG><A NAME="item_%2DMemLevel"><STRONG>-MemLevel</STRONG></A></STRONG><BR>
  174. <DD>
  175. For a definition of the meaning and valid values for <STRONG>MemLevel</STRONG>
  176. refer to the <EM>zlib</EM> documentation for <EM>deflateInit2</EM>.
  177. <P>Defaults to <CODE>-MemLevel =>MAX_MEM_LEVEL</CODE>.</P>
  178. <P></P>
  179. <DT><STRONG><A NAME="item_%2DStrategy"><STRONG>-Strategy</STRONG></A></STRONG><BR>
  180. <DD>
  181. Defines the strategy used to tune the compression. The valid values are
  182. <CODE>Z_DEFAULT_STRATEGY</CODE>, <CODE>Z_FILTERED</CODE> and <CODE>Z_HUFFMAN_ONLY</CODE>.
  183. <P>The default is <CODE>-Strategy =>Z_DEFAULT_STRATEGY</CODE>.</P>
  184. <P></P>
  185. <DT><STRONG><A NAME="item_%2DDictionary"><STRONG>-Dictionary</STRONG></A></STRONG><BR>
  186. <DD>
  187. When a dictionary is specified <EM>Compress::Zlib</EM> will automatically
  188. call <STRONG>deflateSetDictionary</STRONG> directly after calling <STRONG>deflateInit</STRONG>. The
  189. Adler32 value for the dictionary can be obtained by calling tht method 
  190. <CODE>$d-</CODE>dict_adler()>.
  191. <P>The default is no dictionary.</P>
  192. <P></P>
  193. <DT><STRONG><A NAME="item_%2DBufsize"><STRONG>-Bufsize</STRONG></A></STRONG><BR>
  194. <DD>
  195. Sets the initial size for the deflation buffer. If the buffer has to be
  196. reallocated to increase the size, it will grow in increments of
  197. <STRONG>Bufsize</STRONG>.
  198. <P>The default is 4096.</P>
  199. <P></P></DL>
  200. <P>Here is an example of using the <STRONG>deflateInit</STRONG> optional parameter list
  201. to override the default buffer size and compression level. All other
  202. options will take their default values.</P>
  203. <PRE>
  204.     deflateInit( -Bufsize => 300, 
  205.                  -Level => Z_BEST_SPEED  ) ;</PRE>
  206. <P>
  207. <H2><A NAME="($out, $status) = $d>deflate($buffer)"><STRONG>($out, $status) = $d->deflate($buffer)</STRONG></A></H2>
  208. <P>Deflates the contents of <STRONG>$buffer</STRONG>. The buffer can either be a scalar
  209. or a scalar reference.  When finished, <STRONG>$buffer</STRONG> will be
  210. completely processed (assuming there were no errors). If the deflation
  211. was successful it returns the deflated output, <STRONG>$out</STRONG>, and a status
  212. value, <STRONG>$status</STRONG>, of <CODE>Z_OK</CODE>.</P>
  213. <P>On error, <STRONG>$out</STRONG> will be <EM>undef</EM> and <STRONG>$status</STRONG> will contain the
  214. <EM>zlib</EM> error code.</P>
  215. <P>In a scalar context <STRONG>deflate</STRONG> will return <STRONG>$out</STRONG> only.</P>
  216. <P>As with the <EM>deflate</EM> function in <EM>zlib</EM>, it is not necessarily the
  217. case that any output will be produced by this method. So don't rely on
  218. the fact that <STRONG>$out</STRONG> is empty for an error test.</P>
  219. <P>
  220. <H2><A NAME="($out, $status) = $d>flush()"><STRONG>($out, $status) = $d->flush()</STRONG></A></H2>
  221. <P>Finishes the deflation. Any pending output will be returned via <STRONG>$out</STRONG>.
  222. <STRONG>$status</STRONG> will have a value <CODE>Z_OK</CODE> if successful.</P>
  223. <P>In a scalar context <STRONG>flush</STRONG> will return <STRONG>$out</STRONG> only.</P>
  224. <P>Note that flushing can degrade the compression ratio, so it should only
  225. be used to terminate a decompression.</P>
  226. <P>
  227. <H2><A NAME="$d>dict_adler()"><STRONG>$d->dict_adler()</STRONG></A></H2>
  228. <P>Returns the adler32 value for the dictionary.</P>
  229. <P>
  230. <H2><A NAME="example">Example</A></H2>
  231. <P>Here is a trivial example of using <STRONG>deflate</STRONG>. It simply reads standard
  232. input, deflates it and writes it to standard output.</P>
  233. <PRE>
  234.     use Compress::Zlib ;</PRE>
  235. <PRE>
  236.     binmode STDIN;
  237.     binmode STDOUT;</PRE>
  238. <PRE>
  239.     $x = deflateInit()
  240.        or die "Cannot create a deflation stream\n" ;</PRE>
  241. <PRE>
  242.     while (<>)
  243.     {
  244.         ($output, $status) = $x->deflate($_) ;
  245. </PRE>
  246. <PRE>
  247.  
  248.         $status == Z_OK
  249.             or die "deflation failed\n" ;</PRE>
  250. <PRE>
  251.         print $output ;
  252.     }</PRE>
  253. <PRE>
  254.     ($output, $status) = $x->flush() ;</PRE>
  255. <PRE>
  256.     $status == Z_OK
  257.         or die "deflation failed\n" ;</PRE>
  258. <PRE>
  259.     print $output ;</PRE>
  260. <P>
  261. <HR>
  262. <H1><A NAME="inflate">INFLATE</A></H1>
  263. <P>Here is a definition of the interface:</P>
  264. <P>
  265. <H2><A NAME="($i, $status) = inflateinit()"><STRONG>($i, $status) = inflateInit()</STRONG></A></H2>
  266. <P>Initialises an inflation stream.</P>
  267. <P>In a list context it returns the inflation stream, <STRONG>$i</STRONG>, and the
  268. <EM>zlib</EM> status code (<STRONG>$status</STRONG>). In a scalar context it returns the
  269. inflation stream only.</P>
  270. <P>If successful, <STRONG>$i</STRONG> will hold the inflation stream and <STRONG>$status</STRONG> will
  271. be <CODE>Z_OK</CODE>.</P>
  272. <P>If not successful, <STRONG>$i</STRONG> will be <EM>undef</EM> and <STRONG>$status</STRONG> will hold the
  273. <EM>zlib</EM> error code.</P>
  274. <P>The function optionally takes a number of named options specified as
  275. <CODE>-Name=>value</CODE> pairs. This allows individual options to be
  276. tailored without having to specify them all in the parameter list.
  277. </P>
  278. <PRE>
  279.  
  280. For backward compatability, it is also possible to pass the parameters
  281. as a reference to a hash containing the name=>value pairs.</PRE>
  282. <PRE>
  283.  
  284. The function takes one optional parameter, a reference to a hash.  The
  285. contents of the hash allow the deflation interface to be tailored.</PRE>
  286. <PRE>
  287.  
  288. Here is a list of the valid options:</PRE>
  289. <DL>
  290. <DT><STRONG><STRONG>-WindowBits</STRONG></STRONG><BR>
  291. <DD>
  292. For a definition of the meaning and valid values for <STRONG>WindowBits</STRONG>
  293. refer to the <EM>zlib</EM> documentation for <EM>inflateInit2</EM>.
  294. <P>Defaults to <CODE>-WindowBits =>MAX_WBITS</CODE>.</P>
  295. <P></P>
  296. <DT><STRONG><STRONG>-Bufsize</STRONG></STRONG><BR>
  297. <DD>
  298. Sets the initial size for the inflation buffer. If the buffer has to be
  299. reallocated to increase the size, it will grow in increments of
  300. <STRONG>Bufsize</STRONG>.
  301. <P>Default is 4096.</P>
  302. <P></P>
  303. <DT><STRONG><STRONG>-Dictionary</STRONG></STRONG><BR>
  304. <DD>
  305. The default is no dictionary.
  306. <P></P></DL>
  307. <P>Here is an example of using the <STRONG>inflateInit</STRONG> optional parameter to
  308. override the default buffer size.</P>
  309. <PRE>
  310.     inflateInit( -Bufsize => 300 ) ;</PRE>
  311. <P>
  312. <H2><A NAME="($out, $status) = $i>inflate($buffer)"><STRONG>($out, $status) = $i->inflate($buffer)</STRONG></A></H2>
  313. <P>Inflates the complete contents of <STRONG>$buffer</STRONG>. The buffer can either be
  314. a scalar or a scalar reference.</P>
  315. <P>Returns <CODE>Z_OK</CODE> if successful and <CODE>Z_STREAM_END</CODE> if the end of the
  316. compressed data has been reached.</P>
  317. <P>The <CODE>$buffer</CODE> parameter is modified by <CODE>inflate</CODE>. On completion it
  318. will contain what remains of the input buffer after inflation. This
  319. means that <CODE>$buffer</CODE> will be an empty string when the return status is
  320. <CODE>Z_OK</CODE>. When the return status is <CODE>Z_STREAM_END</CODE> the <CODE>$buffer</CODE>
  321. parameter will contains what (if anything) was stored in the input
  322. buffer after the deflated data stream.</P>
  323. <P>This feature is needed when processing a file format that encapsulates
  324. a  deflated data stream (e.g. gzip, zip).</P>
  325. <P>
  326. <H2><A NAME="$i>dict_adler()"><STRONG>$i->dict_adler()</STRONG></A></H2>
  327. <P>
  328. <H2><A NAME="example">Example</A></H2>
  329. <P>Here is an example of using <STRONG>inflate</STRONG>.</P>
  330. <PRE>
  331.     use Compress::Zlib ;</PRE>
  332. <PRE>
  333.     $x = inflateInit()
  334.        or die "Cannot create a inflation stream\n" ;</PRE>
  335. <PRE>
  336.     $input = '' ;
  337.     binmode STDIN;
  338.     binmode STDOUT;</PRE>
  339. <PRE>
  340.     while (read(STDIN, $input, 4096))
  341.     {
  342.         ($output, $status) = $x->inflate(\$input) ;</PRE>
  343. <PRE>
  344.         print $output 
  345.             if $status == Z_OK or $status == Z_STREAM_END ;</PRE>
  346. <PRE>
  347.         last if $status != Z_OK ;
  348.     }</PRE>
  349. <PRE>
  350.     die "inflation failed\n"
  351.         unless $status == Z_STREAM_END ;</PRE>
  352. <P>
  353. <HR>
  354. <H1><A NAME="compress/uncompress">COMPRESS/UNCOMPRESS</A></H1>
  355. <P>Two high-level functions are provided by <EM>zlib</EM> to perform in-memory
  356. compression. They are <STRONG>compress</STRONG> and <STRONG>uncompress</STRONG>. Two Perl subs are
  357. provided which provide similar functionality.</P>
  358. <DL>
  359. <DT><STRONG><A NAME="item_compress"><STRONG>$dest = compress($source) ;</STRONG></A></STRONG><BR>
  360. <DD>
  361. Compresses <STRONG>$source</STRONG>. If successful it returns the
  362. compressed data. Otherwise it returns <EM>undef</EM>.
  363. <P>The source buffer can either be a scalar or a scalar reference.</P>
  364. <P></P>
  365. <DT><STRONG><A NAME="item_uncompress"><STRONG>$dest = uncompress($source) ;</STRONG></A></STRONG><BR>
  366. <DD>
  367. Uncompresses <STRONG>$source</STRONG>. If successful it returns the uncompressed
  368. data. Otherwise it returns <EM>undef</EM>.
  369. <P>The source buffer can either be a scalar or a scalar reference.</P>
  370. <P></P></DL>
  371. <P>
  372. <HR>
  373. <H1><A NAME="gzip interface">GZIP INTERFACE</A></H1>
  374. <P>A number of functions are supplied in <EM>zlib</EM> for reading and writing
  375. <EM>gzip</EM> files. This module provides an interface to most of them. In
  376. general the interface provided by this module operates identically to
  377. the functions provided by <EM>zlib</EM>. Any differences are explained
  378. below.</P>
  379. <DL>
  380. <DT><STRONG><A NAME="item_gzopen"><STRONG>$gz = gzopen(filename or filehandle, mode)</STRONG></A></STRONG><BR>
  381. <DD>
  382. This function operates identically to the <EM>zlib</EM> equivalent except
  383. that it returns an object which is used to access the other <EM>gzip</EM>
  384. methods.
  385. <P>As with the <EM>zlib</EM> equivalent, the <STRONG>mode</STRONG> parameter is used to
  386. specify both whether the file is opened for reading or writing and to
  387. optionally specify a a compression level. Refer to the <EM>zlib</EM>
  388. documentation for the exact format of the <STRONG>mode</STRONG> parameter.</P>
  389. <P>If a reference to an open filehandle is passed in place of the
  390. filename, gzdopen will be called behind the scenes. The third example
  391. at the end of this section, <EM>gzstream</EM>, uses this feature.</P>
  392. <P></P>
  393. <DT><STRONG><A NAME="item_gzread"><STRONG>$bytesread = $gz->gzread($buffer [, $size]) ;</STRONG></A></STRONG><BR>
  394. <DD>
  395. Reads <STRONG>$size</STRONG> bytes from the compressed file into <STRONG>$buffer</STRONG>. If
  396. <STRONG>$size</STRONG> is not specified, it will default to 4096. If the scalar
  397. <STRONG>$buffer</STRONG> is not large enough, it will be extended automatically.
  398. <P>Returns the number of bytes actually read. On EOF it returns 0 and in
  399. the case of an error, -1.</P>
  400. <P></P>
  401. <DT><STRONG><A NAME="item_gzreadline"><STRONG>$bytesread = $gz->gzreadline($line) ;</STRONG></A></STRONG><BR>
  402. <DD>
  403. Reads the next line from the compressed file into <STRONG>$line</STRONG>.
  404. <P>Returns the number of bytes actually read. On EOF it returns 0 and in
  405. the case of an error, -1.</P>
  406. <P>It is legal to intermix calls to <STRONG>gzread</STRONG> and <STRONG>gzreadline</STRONG>.</P>
  407. <P>At this time <STRONG>gzreadline</STRONG> ignores the variable <CODE>$/</CODE>
  408. (<CODE>$INPUT_RECORD_SEPARATOR</CODE> or <CODE>$RS</CODE> when <CODE>English</CODE> is in use). The
  409. end of a line is denoted by the C character <CODE>'\n'</CODE>.</P>
  410. <P></P>
  411. <DT><STRONG><A NAME="item_gzwrite"><STRONG>$byteswritten = $gz->gzwrite($buffer) ;</STRONG></A></STRONG><BR>
  412. <DD>
  413. Writes the contents of <STRONG>$buffer</STRONG> to the compressed file. Returns the
  414. number of bytes actually written, or 0 on error.
  415. <P></P>
  416. <DT><STRONG><A NAME="item_gzflush"><STRONG>$status = $gz->gzflush($flush) ;</STRONG></A></STRONG><BR>
  417. <DD>
  418. Flushes all pending output into the compressed file.
  419. Works identically to the <EM>zlib</EM> function it interfaces to. Note that
  420. the use of <STRONG>gzflush</STRONG> can degrade compression.
  421. <P>Refer to the <EM>zlib</EM> documentation for the valid values of <STRONG>$flush</STRONG>.</P>
  422. <P></P>
  423. <DT><STRONG><A NAME="item_gzclose"><STRONG>$gz->gzclose</STRONG></A></STRONG><BR>
  424. <DD>
  425. Closes the compressed file. Any pending data is flushed to the file
  426. before it is closed.
  427. <P></P>
  428. <DT><STRONG><A NAME="item_gzerror"><STRONG>$gz->gzerror</STRONG></A></STRONG><BR>
  429. <DD>
  430. Returns the <EM>zlib</EM> error message or number for the last operation
  431. associated with <STRONG>$gz</STRONG>. The return value will be the <EM>zlib</EM> error
  432. number when used in a numeric context and the <EM>zlib</EM> error message
  433. when used in a string context. The <EM>zlib</EM> error number constants,
  434. shown below, are available for use.
  435. <PRE>
  436.     Z_OK
  437.     Z_STREAM_END
  438.     Z_ERRNO
  439.     Z_STREAM_ERROR
  440.     Z_DATA_ERROR
  441.     Z_MEM_ERROR
  442.     Z_BUF_ERROR</PRE>
  443. <P></P>
  444. <DT><STRONG><A NAME="item_%24gzerrno"><STRONG>$gzerrno</STRONG></A></STRONG><BR>
  445. <DD>
  446. The <STRONG>$gzerrno</STRONG> scalar holds the error code associated with the most
  447. recent <EM>gzip</EM> routine. Note that unlike <STRONG>gzerror()</STRONG>, the error is
  448. <EM>not</EM> associated with a particular file.
  449. <P>As with <STRONG>gzerror()</STRONG> it returns an error number in numeric context and
  450. an error message in string context. Unlike <STRONG>gzerror()</STRONG> though, the
  451. error message will correspond to the <EM>zlib</EM> message when the error is
  452. associated with <EM>zlib</EM> itself, or the UNIX error message when it is
  453. not (i.e. <EM>zlib</EM> returned <CODE>Z_ERRORNO</CODE>).</P>
  454. <P>As there is an overlap between the error numbers used by <EM>zlib</EM> and
  455. UNIX, <STRONG>$gzerrno</STRONG> should only be used to check for the presence of
  456. <EM>an</EM> error in numeric context. Use <STRONG>gzerror()</STRONG> to check for specific
  457. <EM>zlib</EM> errors. The <EM>gzcat</EM> example below shows how the variable can
  458. be used safely.</P>
  459. <P></P></DL>
  460. <P>
  461. <H2><A NAME="examples">Examples</A></H2>
  462. <P>Here is an example script which uses the interface. It implements a
  463. <EM>gzcat</EM> function.</P>
  464. <PRE>
  465.     use Compress::Zlib ;</PRE>
  466. <PRE>
  467.     die "Usage: gzcat file...\n"
  468.         unless @ARGV ;</PRE>
  469. <PRE>
  470.     foreach $file (@ARGV) {
  471.         $gz = gzopen($file, "rb") 
  472.             or die "Cannot open $file: $gzerrno\n" ;</PRE>
  473. <PRE>
  474.         print $buffer 
  475.             while $gz->gzread($buffer) > 0 ;
  476.         die "Error reading from $file: $gzerrno\n" 
  477.             if $gzerrno != Z_STREAM_END ;
  478. </PRE>
  479. <PRE>
  480.  
  481.         $gz->gzclose() ;
  482.     }</PRE>
  483. <P>Below is a script which makes use of <STRONG>gzreadline</STRONG>. It implements a
  484. very simple <EM>grep</EM> like script.</P>
  485. <PRE>
  486.     use Compress::Zlib ;</PRE>
  487. <PRE>
  488.     die "Usage: gzgrep pattern file...\n"
  489.         unless @ARGV >= 2;</PRE>
  490. <PRE>
  491.     $pattern = shift ;</PRE>
  492. <PRE>
  493.     foreach $file (@ARGV) {
  494.         $gz = gzopen($file, "rb") 
  495.              or die "Cannot open $file: $gzerrno\n" ;
  496. </PRE>
  497. <PRE>
  498.  
  499.         while ($gz->gzreadline($_) > 0) {
  500.             print if /$pattern/ ;
  501.         }</PRE>
  502. <PRE>
  503.  
  504.         die "Error reading from $file: $gzerrno\n" 
  505.             if $gzerrno != Z_STREAM_END ;</PRE>
  506. <PRE>
  507.  
  508.         $gz->gzclose() ;
  509.     }</PRE>
  510. <P>This script, <EM>gzstream</EM>, does the opposite of the <EM>gzcat</EM> script
  511. above. It reads from standard input and writes a gzip file to standard
  512. output.</P>
  513. <PRE>
  514.     use Compress::Zlib ;</PRE>
  515. <PRE>
  516.     binmode STDOUT; # gzopen only sets it on the fd</PRE>
  517. <PRE>
  518.     my $gz = gzopen(\*STDOUT, "wb")
  519.           or die "Cannot open stdout: $gzerrno\n" ;</PRE>
  520. <PRE>
  521.     while (<>) {
  522.         $gz->gzwrite($_) 
  523.             or die "error writing: $gzerrno\n" ;
  524.     }</PRE>
  525. <PRE>
  526.     $gz->gzclose ;</PRE>
  527. <P>
  528. <H2><A NAME="compress::zlib::memgzip">Compress::Zlib::memGzip</A></H2>
  529. <P>This function is used to create an in-memory gzip file. 
  530. It creates a minimal gzip header.</P>
  531. <PRE>
  532.     $dest = Compress::Zlib::memGzip($buffer) ;</PRE>
  533. <P>If successful, it returns the in-memory gzip file, otherwise it returns
  534. undef.</P>
  535. <P>The buffer parameter can either be a scalar or a scalar reference.</P>
  536. <P>
  537. <HR>
  538. <H1><A NAME="checksum functions">CHECKSUM FUNCTIONS</A></H1>
  539. <P>Two functions are provided by <EM>zlib</EM> to calculate a checksum. For the
  540. Perl interface, the order of the two parameters in both functions has
  541. been reversed. This allows both running checksums and one off
  542. calculations to be done.</P>
  543. <PRE>
  544.     $crc = adler32($buffer [,$crc]) ;
  545.     $crc = crc32($buffer [,$crc]) ;</PRE>
  546. <P>The buffer parameters can either be a scalar or a scalar reference.</P>
  547. <P>If the $crc parameters is <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A>, the crc value will be reset.</P>
  548. <P>
  549. <HR>
  550. <H1><A NAME="constants">CONSTANTS</A></H1>
  551. <P>All the <EM>zlib</EM> constants are automatically imported when you make use
  552. of <EM>Compress::Zlib</EM>.</P>
  553. <P>
  554. <HR>
  555. <H1><A NAME="author">AUTHOR</A></H1>
  556. <P>The <EM>Compress::Zlib</EM> module was written by Paul Marquess,
  557. <EM><A HREF="mailto:Paul.Marquess@btinternet.com">Paul.Marquess@btinternet.com</A></EM>. The latest copy of the module can be
  558. found on CPAN in <EM>modules/by-module/Compress/Compress-Zlib-x.x.tar.gz</EM>.</P>
  559. <P>The <EM>zlib</EM> compression library was written by Jean-loup Gailly
  560. <EM><A HREF="mailto:gzip@prep.ai.mit.edu">gzip@prep.ai.mit.edu</A></EM> and Mark Adler <EM><A HREF="mailto:madler@alumni.caltech.edu">madler@alumni.caltech.edu</A></EM>.
  561. It is available at <EM><A HREF="ftp://ftp.uu.net/pub/archiving/zip/zlib*">ftp://ftp.uu.net/pub/archiving/zip/zlib*</A></EM> and
  562. <EM><A HREF="ftp://swrinde.nde.swri.edu/pub/png/src/zlib*">ftp://swrinde.nde.swri.edu/pub/png/src/zlib*</A></EM>. Alternatively check
  563. out the zlib home page at <EM><A HREF="http://quest.jpl.nasa.gov/zlib/">http://quest.jpl.nasa.gov/zlib/</A></EM>.</P>
  564. <P>Questions about <EM>zlib</EM> itself should be sent to
  565. <EM><A HREF="mailto:zlib@quest.jpl.nasa.gov">zlib@quest.jpl.nasa.gov</A></EM> or, if this fails, to the addresses given
  566. for the authors above.</P>
  567. <P>
  568. <HR>
  569. <H1><A NAME="modification history">MODIFICATION HISTORY</A></H1>
  570. <P>
  571. <H2><A NAME="0.1 2nd october 1995.">0.1 2nd October 1995.</A></H2>
  572. <P>First public release of <EM>Compress::Zlib</EM>.</P>
  573. <P>
  574. <H2><A NAME="0.2 5th october 1995.">0.2 5th October 1995.</A></H2>
  575. <P>Fixed a minor allocation problem in Zlib.xs</P>
  576. <P>
  577. <H2><A NAME="0.3 12th october 1995.">0.3 12th October 1995.</A></H2>
  578. <P>Added prototype specification.</P>
  579. <P>
  580. <H2><A NAME="0.4 25th june 1996.">0.4 25th June 1996.</A></H2>
  581. <OL>
  582. <LI>
  583. Documentation update.
  584. <P></P>
  585. <LI>
  586. Upgraded to support zlib 1.0.2
  587. <P></P>
  588. <LI>
  589. Added dictionary interface.
  590. <P></P>
  591. <LI>
  592. Fixed bug in gzreadline - previously it would keep returning the same
  593. buffer. This bug was reported by Helmut Jarausch
  594. <P></P>
  595. <LI>
  596. Removed dependancy to zutil.h and so dropped support for 
  597.  
  598. <PRE>
  599.  
  600.     DEF_MEM_LEVEL (use MAX_MEM_LEVEL instead)
  601.     DEF_WBITS     (use MAX_WBITS instead)</PRE>
  602. <P></P></OL>
  603. <P>
  604. <H2><A NAME="0.50 19th feb 1997">0.50 19th Feb 1997</A></H2>
  605. <OL>
  606. <LI>
  607. Confirmed that no changes were necessary for zlib 1.0.3 or 1.0.4.
  608. <P></P>
  609. <LI>
  610. The optional parameters for deflateInit and inflateInit can now be
  611. specified as an associative array in addition to a reference to an
  612. associative array. They can also accept the -Name syntax.
  613. <P></P>
  614. <LI>
  615. gzopen can now optionally take a reference to an open filehandle in
  616. place of a filename. In this case it will call gzdopen.
  617. <P></P>
  618. <LI>
  619. Added gzstream example script.
  620. <P></P></OL>
  621. <P>
  622. <H2><A NAME="1.00 14 nov 1997">1.00 14 Nov 1997</A></H2>
  623. <OL>
  624. <LI>
  625. The following functions can now take a scalar reference in place of a
  626. scalar for their buffer parameters:
  627. <PRE>
  628.     compress
  629.     uncompress
  630.     deflate
  631.     inflate
  632.     crc32
  633.     adler32</PRE>
  634. <P>This should mean applications that make use of the module don't have to
  635. copy large buffers around.</P>
  636. <P></P>
  637. <LI>
  638. Normally the inflate method consumes <EM>all</EM> of the input buffer before
  639. returning. The exception to this is when inflate detects the end of the
  640. stream (Z_STREAM_END). In this case the input buffer need not be
  641. completely consumed. To allow processing of file formats that embed a
  642. deflation stream (e.g. zip, gzip), the inflate method now sets the
  643. buffer parameter to be what remains after inflation.
  644. <P>When the return status is Z_STREAM_END, it will be what remains of the
  645. buffer (if any) after deflation. When the status is Z_OK it will be an
  646. empty string.</P>
  647. <P>This change means that the buffer parameter must be a lvalue.</P>
  648. <P></P>
  649. <LI>
  650. Fixed crc32 and adler32. They were both very broken.
  651. <P></P>
  652. <LI><STRONG><A NAME="item_%2C">,</A></STRONG><BR>
  653.  
  654. Added the Compress::Zlib::memGzip function.
  655. <P></P></OL>
  656. <P>
  657. <H2><A NAME="1.01 23 nov 1997">1.01 23 Nov 1997</A></H2>
  658. <OL>
  659. <LI>
  660. A number of fixes to the test suite and the example scripts to allow
  661. them to work under win32. All courtesy of Gurusamy Sarathy.
  662. <P></P></OL>
  663. <P>
  664. <H2><A NAME="1.02 10 jan 1998">1.02 10 Jan 1998</A></H2>
  665. <OL>
  666. <LI>
  667. The return codes for gzread, gzreadline and gzwrite were documented
  668. incorrectly as returning a status code.
  669. <P></P>
  670. <LI>
  671. The test harness was missing a ``gzclose''. This caused problem showed up
  672. on an amiga. Thanks to Erik van Roode for reporting this one.
  673. <P></P>
  674. <LI>
  675. Patched zlib.t for OS/2. Thanks to Ilya Zakharevich for the patch.
  676. <P></P></OL>
  677. <P>
  678. <H2><A NAME="1.03 17 mar 1999">1.03 17 Mar 1999</A></H2>
  679. <OL>
  680. <LI>
  681. Updated to use the new PL_ symbols. 
  682. Means the module can be built with Perl 5.005_5*
  683. <P></P></OL>
  684. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  685. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  686. <STRONG><P CLASS=block> Compress::Zlib - Interface to zlib compression library</P></STRONG>
  687. </TD></TR>
  688. </TABLE>
  689.  
  690. </BODY>
  691.  
  692. </HTML>
  693.