diff --git a/functions/zlib.xml b/functions/zlib.xml index dd01d4f15b..db6079b273 100644 --- a/functions/zlib.xml +++ b/functions/zlib.xml @@ -1,61 +1,72 @@ - Compression functions + Zlib Compression Functions Zlib - This module uses the functions of zlib by Jean-loup Gailly and Mark Adler to + This module uses the functions of zlib by Jean-loup Gailly and Mark Adler to transparently read and write gzip (.gz) compressed files. You have to use a zlib version >= 1.0.9 with this module. - This module contains versions of most of the filesystem functions which work + This module contains versions of most of the filesystem functions which work with gzip-compressed files (and uncompressed files, too, but not with sockets). Small code example - - Opens a temporary file and writes a test string to it, then it - prints out the content of this file twice. - - + + Opens a temporary file and writes a test string to it, then it + prints out the content of this file twice. + - Small Zlib example + Small Zlib Example <?php - $filename = tempnam('/tmp', 'zlibtest').'.gz'; - print "<html>\n<head></head>\n<body>\n<pre>\n"; - $s = "Only a test, test, test, test, test, test, test, test!\n"; - // open file for writing with maximum compression - $zp = gzopen($filename, "w9"); - // write string to file - gzwrite($zp, $s); - // close file - gzclose($zp); - // open file for reading - $zp = gzopen($filename, "r"); - // read 3 char - print gzread($zp, 3); - // output until end of the file and close it. - gzpassthru($zp); - print "\n"; - // open file and print content (the 2nd time). - if (readgzfile($filename) != strlen($s)) { - echo "Error with zlib functions!"; - } - unlink($filename); - print "</pre>\n</h1></body>\n</html>\n"; -?> - - +$filename = tempnam ('/tmp', 'zlibtest').'.gz'; +print "<html>\n<head></head>\n<body>\n<pre>\n"; +$s = "Only a test, test, test, test, test, test, test, test!\n"; + +// open file for writing with maximum compression +$zp = gzopen($filename, "w9"); + +// write string to file +gzwrite($zp, $s); + +// close file +gzclose($zp); + +// open file for reading +$zp = gzopen($filename, "r"); + +// read 3 char +print gzread($zp, 3); + +// output until end of the file and close it. +gzpassthru($zp); + +print "\n"; + +// open file and print content (the 2nd time). +if (readgzfile($filename) != strlen($s)) { + echo "Error with zlib functions!"; +} +unlink($filename); +print "</pre>\n</h1></body>\n</html>\n"; + +?> + + + gzclose - close an open gz-file pointer + Close an open gz-file pointer Description @@ -66,23 +77,22 @@ - The gz-file pointed to by zp is closed. - + The gz-file pointed to by zp is closed. + - Returns true on success and false on failure. - + Returns true on success and false on failure. + The gz-file pointer must be valid, and must point to a file - successfully opened by gzopen. - + successfully opened by gzopen. + - gzeof - test for end-of-file on a gz-file pointer + Test for end-of-file on a gz-file pointer Description @@ -94,20 +104,19 @@ Returns true if the gz-file pointer is at EOF or an error occurs; - otherwise returns false. - + otherwise returns false. + The gz-file pointer must be valid, and must point to a file - successfully opened by gzopen. - + successfully opened by gzopen. + - - gzfile read entire gz-file into an - array + gzfile + Read entire gz-file into an array Description @@ -115,26 +124,31 @@ array gzfile string filename - int use_include_path + int + use_include_path + - Identical to readgzfile, except that gzfile() - returns the file in an array. - + + Identical to readgzfile, except that + gzfile returns the file in an array. + You can use the optional second parameter and set it to "1", if - you want to search for the file in the include_path, too. - - See also readgzfile, and - gzopen. + you want to search for the file in the include_path, too. + + + See also readgzfile, and + gzopen. + - gzgetc - get character from gz-file pointer + Get character from gz-file pointer Description @@ -147,23 +161,23 @@ Returns a string containing a single (uncompressed) character read from the file pointed to by zp. Returns FALSE on EOF (as - does gzeof). + does gzeof). + The gz-file pointer must be valid, and must point to a file - successfully opened by gzopen. - - See also - gzopen, and - gzgets. - + successfully opened by gzopen. + + + See also gzopen, and + gzgets. + - gzgets - get line from file pointer + Get line from file pointer Description @@ -174,29 +188,32 @@ int length - Returns a (uncompressed) string of up to length - 1 bytes read from the file pointed to by fp. Reading ends when length - 1 bytes have been read, on a newline, or on EOF (whichever comes - first). - - If an error occurs, returns false. - - The file pointer must be valid, and must point to a file - successfully opened by gzopen. - - See also gzopen, - gzgetc, and fgets. - + first). + + + If an error occurs, returns false. + + + The file pointer must be valid, and must point to a file + successfully opened by gzopen. + + + See also gzopen, + gzgetc, and fgets. + - gzgetss - get line from gz-file pointer and strip HTML tags + + Get line from gz-file pointer and strip HTML tags + Description @@ -205,34 +222,37 @@ string gzgetss int zp int length - string allowable_tags + string + allowable_tags + - Identical to gzgets, - except that gzgetss attempts to strip any HTML and PHP tags from - the text it reads. + Identical to gzgets, except that + gzgetss attempts to strip any HTML and PHP + tags from the text it reads. + You can use the optional third parameter to specify tags which should not be stripped. - - - - allowable_tags was added in PHP 3.0.13, PHP4B3. - - + + + Allowable_tags was added in PHP 3.0.13, + PHP4B3. + + + See also gzgets, - gzopen, and strip_tags. - + gzopen, and strip_tags. + - gzopen - open gz-file + Open gz-file Description @@ -241,7 +261,9 @@ int gzopen string filename string mode - int use_include_path + int + use_include_path + @@ -250,42 +272,47 @@ can also include a compression level ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman only compression as in "wb1h". (See the description of deflateInit2 in zlib.h for - more information about the strategy parameter.) - + more information about the strategy parameter.) + - Gzopen can be used to read a file which is not in gzip format; in - this case gzread will directly read from the - file without decompression. - + Gzopen can be used to read a file which is + not in gzip format; in this case gzread will + directly read from the file without decompression. + - Gzopen returns a file pointer to the file opened, after that, - everything you read from this file descriptor will be - transparently decompressed and what you write gets compressed. - + Gzopen returns a file pointer to the file + opened, after that, everything you read from this file descriptor + will be transparently decompressed and what you write gets + compressed. + - If the open fails, the function returns false. - + If the open fails, the function returns false. + You can use the optional third parameter and set it to "1", if - you want to search for the file in the include_path, too. - - - gzopen() example - -$fp = gzopen("/tmp/file.gz", "r"); - - + you want to search for the file in the include_path, too. + - See also gzclose. - + + <function>Gzopen</function> Example + +$fp = gzopen ("/tmp/file.gz", "r"); + + + + + See also gzclose. + - gzpassthru - output all remaining data on a gz-file pointer + + Output all remaining data on a gz-file pointer + Description @@ -297,27 +324,26 @@ $fp = gzopen("/tmp/file.gz", "r"); Reads to EOF on the given gz-file pointer and writes the - (uncompressed) results to standard output. - + (uncompressed) results to standard output. + - If an error occurs, returns false. - + If an error occurs, returns false. + The file pointer must be valid, and must point to a file - successfully opened by gzopen. - + successfully opened by gzopen. + The gz-file is closed when gzpassthru is - done reading it (leaving zp useless). - + done reading it (leaving zp useless). + - gzputs - write to a gz-file pointer + Write to a gz-file pointer Description @@ -326,18 +352,18 @@ $fp = gzopen("/tmp/file.gz", "r"); int gzputs int zp string str - int length + int + length + - - gzputs is an alias to - gzwrite, and is identical in every way. - + Gzputs is an alias to + gzwrite, and is identical in every way. + - gzread @@ -357,31 +383,31 @@ $fp = gzopen("/tmp/file.gz", "r"); length bytes from the gz-file pointer referenced by zp. Reading stops when length (uncompressed) bytes have been read - or EOF is reached, whichever comes first. - + or EOF is reached, whichever comes first. + - + // get contents of a gz-file into a string $filename = "/usr/local/something.txt.gz"; -$zd = gzopen( $filename, "r" ); -$contents = gzread( $zd, 10000 ); -gzclose( $zd ); +$zd = gzopen ($filename, "r"); +$contents = gzread ($zd, 10000); +gzclose ($zd); - - + + See also gzwrite, gzopen, gzgets, gzgetss, - gzfile, and gzpassthru. + gzfile, and gzpassthru. + - gzrewind - rewind the position of a gz-file pointer + Rewind the position of a gz-file pointer Description @@ -391,21 +417,28 @@ gzclose( $zd ); int zp - Sets the file position indicator for zp to the - beginning of the file stream. - If an error occurs, returns 0. - The file pointer must be valid, and must point to a file - successfully opened by gzopen. - - See also gzseek and gztell. - + + Sets the file position indicator for zp to the beginning of the + file stream. + + + If an error occurs, returns 0. + + + The file pointer must be valid, and must point to a file + successfully opened by gzopen. + + + See also gzseek and + gztell. + gzseek - seek on a gz-file pointer + Seek on a gz-file pointer Description @@ -419,30 +452,29 @@ gzclose( $zd ); Sets the file position indicator for the file referenced by zp to offset bytes into the file stream. Equivalent to calling (in C) - gzseek( zp, offset, SEEK_SET ). - + gzseek( zp, offset, SEEK_SET ). + If the file is opened for reading, this function is emulated but can be extremely slow. If the file is opened for writing, only forward seeks are supported; gzseek then compresses a sequence of - zeroes up to the new starting position. - + zeroes up to the new starting position. + Upon success, returns 0; otherwise, returns -1. Note that seeking - past EOF is not considered an error. - + past EOF is not considered an error. + See also gztell and - gzrewind. - + gzrewind. + - gztell - tell gz-file pointer read/write position + Tell gz-file pointer read/write position Description @@ -453,19 +485,21 @@ gzclose( $zd ); - Returns the position of the file pointer referenced by zp; i.e., - its offset into the file stream. - + Returns the position of the file pointer referenced by + zp; i.e., its offset into the file + stream. + - If an error occurs, returns false. - + If an error occurs, returns false. + The file pointer must be valid, and must point to a file - successfully opened by gzopen. - - See also gzopen, - gzseek and gzrewind. - + successfully opened by gzopen. + + + See also gzopen, gzseek + and gzrewind. + @@ -481,34 +515,38 @@ gzclose( $zd ); int gzwrite int zp string string - int length + int + length + - gzwrite writes the contents of + Gzwrite writes the contents of string to the gz-file stream pointed to by zp. If the length argument is given, writing will stop after length (uncompressed) bytes have been written or the end of string is reached, - whichever comes first. - + whichever comes first. + Note that if the length argument is given, - then the magic_quotes_runtime + then the magic_quotes_runtime configuration option will be ignored and no slashes will be - stripped from string. - + stripped from string. + See also gzread, gzopen, - and gzputs. + and gzputs. + readgzfile - output a gz-file + Output a gz-file Description @@ -516,39 +554,47 @@ gzclose( $zd ); int readgzfile string filename - int use_include_path + int + use_include_path + - Reads a file, decompresses it and writes it to standard - output. - + + Reads a file, decompresses it and writes it to standard + output. + - Readgzfile() can be used to read a file which is not in gzip - format; in this case readgzfile() will directly read from the - file without decompression. - - Returns the number of (uncompressed) bytes read from the - file. If an error occurs, false is returned and unless the - function was called as @readgzfile, an error message is printed. - - The file filename will be opened - from the filesystem and its contents written to standard output. - + Readgzfile can be used to read a file which + is not in gzip format; in this case + readgzfile will directly read from the file + without decompression. + + + Returns the number of (uncompressed) bytes read from the file. If + an error occurs, false is returned and unless the function was + called as @readgzfile, an error message is + printed. + + + The file filename will be opened from the + filesystem and its contents written to standard output. + You can use the optional second parameter and set it to "1", if - you want to search for the file in the include_path, too. - + you want to search for the file in the include_path, too. + See also gzpassthru, - gzfile, and gzopen. - + gzfile, and gzopen. + gzcompress - gz-compress a string + Gz-compress a string Description @@ -556,15 +602,17 @@ gzclose( $zd ); string gzcompress string data - int level + int + level + - - This function returns a gzip-compressed version of the input - data or false on errors. The optional parameter - level can be given as 0 for no compression - up to 9 for maximum compression. - + + This function returns a gzip-compressed version of the input + data or false on errors. The optional + parameter level can be given as 0 for no + compression up to 9 for maximum compression. + See also gzuncompress. @@ -574,7 +622,7 @@ gzclose( $zd ); gzuncompress - uncompress a gz-compressed string + Uncompress a gz-compressed string Description @@ -582,17 +630,19 @@ gzclose( $zd ); string gzcompress string data - int length + int + length + - This function takes data compressed by - gzcompress and returns the orignial uncompressed - data or false on error. - The function will return an error if the uncompressed data is more than 256 - times the lenght of the compressed input data or more - than the optional parameter length. - + This function takes data compressed by + gzcompress and returns the orignial + uncompressed data or false on error. The function will return an + error if the uncompressed data is more than 256 times the lenght + of the compressed input data or more than + the optional parameter length. + See also gzcompress. @@ -611,7 +661,7 @@ sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" +sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil