Gz-file Functions

This module uses the functions of zlib >= 1.0.9 (h)ttp://www.cdrom.com/pub/infozip/zlib/)) by Jean-loup Gailly and Mark Adler to transparently read and write gzip (.gz) compressed files.

Gz-file Functions

gzclose

Name

gzclose — close an open gz-file pointer

Description

int gzclose(int zp);

gzeof

gzfile

The gz-file pointed to by zp is closed. 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.

Name

gzeof — test for end-of-file on a gz-file pointer

Description

int gzeof(int zp);

Returns true if the gz-file pointer is at EOF or an error occurs; otherwise returns false. The gz-file pointer must be valid, and must point to a file successfully opened by gzopen.

Name

gzfile — read entire gz-file into an array

Description

array gzfile(string filename);

Identical to readgzfile, except that gzfile() returns the file in an array. See also readgzfile, and gzopen.

gzgetc

Name

gzgetc — get character from gz-file pointer

Description

string gzgetc(int zp);

Returns a string containing a single (uncompressed) character read from the file pointed to by zp. Returns FALSE on EOF (as does gzeof).

The gz-file pointer must be valid, and must point to a file successfully opened by gzopen. See also gzopen, and gzgets.

gzgets

Name

gzgets — get line from file pointer

Description

string gzgets(int zp, 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, and gzgetc.

gzgetss

Name

gzgetss — get line from gz-file pointer and strip HTML tags

Description

string gzgetss(int zp, int length);

Identical to gzgets, except that gzgetss attempts to strip any HTML and PHP tags from the text it reads.

gzopen

Name

gzopen — open gz-file

Description

int gzopen(string filename, string mode);

Opens a gzip (.gz) file for reading or writing. The mode parameter is as in fopen ("rb" or "wb") but 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.)

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.

If the open fails, the function returns false.

Example 1. gzopen() example

$fp = gzopen("/tmp/file.gz", "r");

gzpassthru

Name

gzpassthru — output all remaining data on a gz-file pointer

Description

int gzpassthru(int zp);

Reads to EOF on the given gz-file pointer and writes the (uncompressed) results to standard output. If an error occurs, returns false.

The file pointer must be valid, and must point to a file successfully opened by gzopen. The gz-file is closed when gzpassthru is done reading it (leaving zp useless).

gzputs

Name

gzputs — write to a gz-file pointer

Description

int gzputs(int zp, string str, int [length]); gzputs is an alias to gzwrite, and is identical in every way.

gzread

Name

gzread — Binary-safe gz-file read

Description

string gzread(int zp, int length);

gzread reads up to 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.

// 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 );

See also gzwrite, gzopen, gzgets, gzgetss, gzfile, and gzpassthru.

gzrewind

Name

gzrewind — rewind the position of a gz-file pointer

Description

int gzrewind(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.

gzseek

Name

gzseek — seek on a gz-file pointer

Description

int gzseek(int zp, int offset);

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 ).

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.

Upon success, returns 0; otherwise, returns -1. Note that seeking past EOF is not considered an error. See also gztell and gzrewind.

gztell

Name

gztell — tell gz-file pointer read/write position

Description

int gztell(int zp);

Returns the position of the file pointer referenced by zp; i.e., its offset into the file stream. 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.

readgzfile

Name

readgzfile — output a gz-file

Description

int readgzfile(string filename);

Reads a file, decompresses it and writes it to standard output.

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. See also gzpassthru, gzfile, and gzopen.

gzwrite

Name

gzwrite — Binary-safe gz-file write

Description

int gzwrite(int zp, string string, int [length]);

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.

Note that if the length argument is given, then the magic_quotes_runtime configuration option will be ignored and no slashes will be stripped from string.