Reuse, not rework
Home

License Awareness



Highly Reusable Software

By activity
Professions, Sciences, Humanities, Business, ...

User Interface
Text-based, GUI, Audio, Video, Keyboards, Mouse, Images,...

Text Strings
Conversions, tests, processing, manipulation,...

Math
Integer, Floating point, Matrix, Statistics, Boolean, ...

Processing
Algorithms, Memory, Process control, Debugging, ...

Stored Data
Data storage, Integrity, Encryption, Compression, ...

Communications
Networks, protocols, Interprocess, Remote, Client Server, ...

Hard World
Timing, Calendar and Clock, Audio, Video, Printer, Controls...

File System
Management, Filtering, File & Directory access, Viewers, ...


NAME

librock_zlib_gzio - transparent gzip file reading and writing
librock_z_gzopen - Open a .gz file for reading or writing.
librock_z_gzdopen - associates a file descriptor.
librock_z_gzparams - dynamically update compression parameters.
librock_z_gzread - uncompress bytes from the file.
librock_z_gzwrite - compress bytes into the file.
librock_z_gzprintf - as with fprintf, but write compressed.
librock_z_gzputs - compress a string up to a NUL into the file.
librock_z_gzgets - uncompress a string from file.
librock_z_gzputc - write a character to compressed file.
librock_z_gzgets - uncompress a character from file.
librock_z_gzflush - flush all pending output to the compressed file.
librock_z_gzseek - set position for next read or write of compressed file.
librock_z_gzrewind - rewind a compressed file.
librock_z_gztell - report position for next read or write.
librock_z_gzeof - report EOF previously detected.
librock_z_gzclose - flush output, deallocate internal state, close file.
librock_z_gzerror - return most recent error message during operation on compressed file.

#License - #Source code - #Example Use -

SYNOPSIS

#include <librock/target/types.c>
#include <librock/zlibh.h>

librock_z_gzFile
librock_z_gzopen  (const char *path,
                  const char *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 librock_z_deflateInit2 for more information about the strategy parameter.)

librock_z_gzopen can be used to read a file which is not in gzip format; in this case librock_z_gzread will directly read from the file without decompression.

librock_z_gzopen returns NULL if the file could not be opened or if there was insufficient memory to allocate the (de)compression state; errno can be checked to distinguish the two cases (if errno is zero, the librock_zlib error is librock_Z_MEM_ERROR).


librock_z_gzFile
librock_z_gzdopen  (int fd,
                    const char *mode);
librock_z_gzdopen() associates a librock_z_gzFile with the file descriptor fd. File descriptors are obtained from calls like open, dup, creat, pipe or fileno (in the file has been previously opened with fopen ).

The mode parameter is as in librock_z_gzopen().

The next call of librock_z_gzclose on the returned librock_z_gzFile will also close the file descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor fd. If you want to keep fd open, use librock_z_gzdopen(dup(fd), mode) . librock_z_gzdopen returns NULL if there was insufficient memory to allocate the (de)compression state.


int
librock_z_gzsetparams (librock_z_gzFile file,
    int level,
    int strategy);
Dynamically update the compression level or strategy. See the description of librock_z_deflateInit2 for the meaning of these parameters. librock_z_gzsetparams returns librock_Z_OK if success, or librock_Z_STREAM_ERROR if the file was not opened for writing.

int
librock_z_gzread  (librock_z_gzFile file,
                          librock_z_voidp buf,
                          unsigned len);
Reads the given number of uncompressed bytes from the compressed file. If the input file was not in gzip format, librock_z_gzread copies the given number of bytes into the buffer. librock_z_gzread returns the number of uncompressed bytes actually read (0 for end of file, -1 for error).

int
librock_z_gzwrite (librock_z_gzFile file,
                           const librock_z_voidp buf,
                           unsigned len);
Writes the given number of uncompressed bytes into the compressed file. librock_z_gzwrite returns the number of uncompressed bytes actually written (0 in case of error).
int
librock_z_gzprintf (librock_z_gzFile file,
                           const char *format,
                           ...);
Converts, formats, and writes the args to the compressed file under control of the format string, as in fprintf. librock_z_gzprintf returns the number of uncompressed bytes actually written (0 in case of error).

The default compile-time macro librock_Z_PRINTF_BUFSIZE is 4096, which is the largest string which can be written without truncation. NOTE: A #define in librock/zconf.h librock forces zlib to compile with a call to vsnprintf() (instead of vsprintf(), or other overrun unsafe calls.)


int  librock_z_gzputs (librock_z_gzFile file,
                        const char *s);
Writes the given NUL-terminated string to the compressed file, excluding the terminating NUL character. librock_z_gzputs returns the number of characters written, or -1 in case of error.

char *  librock_z_gzgets (librock_z_gzFile file,
                         char *buf,
                         int len);
Reads bytes from the compressed file until len-1 characters are read, or a newline character is read and transferred to buf, or an end-of-file condition is encountered. The string is then terminated with a NUL character. librock_z_gzgets returns buf, or librock_Z_NULL in case of error.

int
librock_z_gzputc (librock_z_gzFile file,
                        int c);
Writes c, converted to an unsigned char, into the compressed file. librock_z_gzputc returns the value that was written, or -1 in case of error.
int
librock_z_gzgetc (librock_z_gzFile file);
Reads one byte from the compressed file. librock_z_gzgetc returns this byte or -1 in case of end of file or error.
int
librock_z_gzflush (librock_z_gzFile file,
                        int flush);
Flushes all pending output into the compressed file. The parameter flush is as in the librock_z_deflate() function. The return value is the librock_zlib error number (see function librock_z_gzerror below). librock_z_gzflush returns librock_Z_OK if the flush parameter is librock_Z_FINISH and all output could be flushed. librock_z_gzflush() should be called only when strictly necessary because it can degrade compression.

librock_z_off_t
librock_z_gzseek (librock_z_gzFile file,
                        librock_z_off_t offset,
                        int whence);
Sets the starting position for the next librock_z_gzread or librock_z_gzwrite on the given compressed file. The offset represents a number of bytes in the uncompressed data stream. The whence parameter is defined as in lseek(2) ; the value SEEK_END is not supported.

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; librock_z_gzseek then compresses a sequence of zeroes up to the new starting position.

librock_z_gzseek returns the resulting offset location as measured in bytes from the beginning of the uncompressed stream, or -1 in case of error, in particular if the file is opened for writing and the new starting position would be before the current position.

int
librock_z_gzrewind (librock_z_gzFile file);
Rewinds the given file. This function is supported only for reading.

librock_z_gzrewind(file) is equivalent to (int)librock_z_gzseek(file, 0L, SEEK_SET)


librock_z_off_t
librock_z_gztell (librock_z_gzFile file);
Returns the starting position for the next librock_z_gzread or librock_z_gzwrite on the given compressed file. This position represents a number of bytes in the uncompressed data stream.

librock_z_gztell(file) is equivalent to librock_z_gzseek(file, 0L, SEEK_CUR)


int
librock_z_gzeof (librock_z_gzFile file);
Returns 1 when EOF has previously been detected reading the given input stream, otherwise zero.

int
librock_z_gzclose (librock_z_gzFile file);
Flushes all pending output if necessary, closes the compressed file and deallocates all the (de)compression state. The return value is the librock_zlib error number (see function librock_z_gzerror() below).

const char *
librock_z_gzerror (librock_z_gzFile file,
                int *errnum);
Returns the error message for the last error which occurred on the given compressed file. errnum is set to librock_zlib error number. If an error occurred in the file system and not in the compression library, errnum is set to librock_Z_ERRNO and the application may consult errno to get the exact error code.

Typical use is
void test_gzio(out, in, uncompr, uncomprLen)
    const char *out; /* compressed output file */
    const char *in;  /* compressed input file */
    librock_z_Byte *uncompr;
    int  uncomprLen;
{
    int err;
    int len = strlen(hello)+1;
    librock_z_gzFile file;
    librock_z_off_t pos;

    file = librock_z_gzopen(out, "wb");
    if (file == NULL) {
        fprintf(stderr, "gzopen error\n");
        exit(1);
    }
    librock_z_gzputc(file, 'h');
    if (librock_z_gzputs(file, "ello") != 4) {
        fprintf(stderr, "gzputs err: %s\n", librock_z_gzerror(file, &err));
        exit(1);
    }
    if (librock_z_gzprintf(file, ", %s!", "hello") != 8) {
        fprintf(stderr, "gzprintf err: %s\n", librock_z_gzerror(file, &err));
        exit(1);
    }
    librock_z_gzseek(file, 1L, SEEK_CUR); /* add one zero librock_z_Byte */
    librock_z_gzclose(file);

    file = librock_z_gzopen(in, "rb");
    if (file == NULL) {
        fprintf(stderr, "gzopen error\n");
    }

    uncomprLen = librock_z_gzread(file, uncompr, (unsigned)uncomprLen);
    if (uncomprLen != len) {
        fprintf(stderr, "gzread err: %s\n", librock_z_gzerror(file, &err));
        exit(1);
    }
    /* Work with uncompr here */
    printf("gzread(): %s\n", (char *)uncompr);

    pos = librock_z_gzseek(file, -8L, SEEK_CUR);
    if (pos != 6 || librock_z_gztell(file) != pos) {
        fprintf(stderr, "gzseek error, pos=%ld, librock_z_gztell=%ld\n",
                (long)pos, (long)librock_z_gztell(file));
        exit(1);
    }

    if (librock_z_gzgetc(file) != ' ') {
        fprintf(stderr, "gzgetc error\n");
        exit(1);
    }

    librock_z_gzgets(file, (char*)uncompr, uncomprLen);
    uncomprLen = strlen((char*)uncompr);

    printf("gzgets() after gzseek: %s\n", (char *)uncompr);

    librock_z_gzclose(file);
}

USES

    librock_z_crc32
    librock_z_deflate
    librock_z_deflateEnd
    librock_z_deflateInit2_
    librock_z_deflateParams
    librock_z_errmsg
    librock_z_inflate
    librock_z_inflateEnd
    librock_z_inflateInit2_
    librock_z_inflateReset
    fdopen
    errno
    fclose
    fflush
    fopen
    fprintf
    fputc
    fread
    free
    fseek
    ftell
    fwrite
    malloc
    memcpy
    memset
    rewind
    sprintf     // During gz_fdopen for debugging.  buffer-overrun safe if sizeof(int) <= 4
    strcat
    strcpy
    strlen
    vsnprintf   // called by librock_z_gzprintf only


MT Behavior

These functions are well-behaved in multi-threaded environments. The zlib functions do not install any signal handler, and return error codes instead of exiting or throwing exceptions. The decoder checks the consistency of the compressed data, so the library should never crash even in case of corrupted input.

LICENSE

    Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler
  Licensed under BSD-ish license, NO WARRANTY. Copies must retain this block.
  License text in <librock/license/zlib.txt> librock_LIDESC_HC=d49ece91d0f3402f1ca405bc4ae7b2a989a56ab2

************************************************************

Source Code

./acquired/zlib/adler32.c
./acquired/zlib/zcrc32.c
./acquired/zlib/compress.c
./acquired/zlib/deflate.c
./acquired/zlib/deflate.h
./acquired/zlib/gzio.c
./acquired/zlib/infblock.c
./acquired/zlib/infblock.h
./acquired/zlib/infcodes.c
./acquired/zlib/infcodes.h
./acquired/zlib/inffast.c
./acquired/zlib/inffast.h
./acquired/zlib/inffixed.h
./acquired/zlib/inflate.c
./acquired/zlib/inftrees.c
./acquired/zlib/inftrees.h
./acquired/zlib/infutil.c
./acquired/zlib/infutil.h
./acquired/zlib/trees.h
./acquired/zlib/uncompr.c
./acquired/zlib/zconf.h
./acquired/zlib/zlib.h
./acquired/zlib/ztrees.c
./acquired/zlib/zutil.c
./acquired/zlib/zutil.h
./librock/zlibh.h
./librock/zlibh.h (source of this manual page)

Tests and Supported Platform Types

This is a representative sample. Librock code is highly portable. For a particular platform not reported here, request paid support

librock_z_gzclose passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzclose passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzgets passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzgets passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzopen passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzopen passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzprintf passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzprintf passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzputc passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzputc passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzputs passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzputs passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzread passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzread passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gzseek passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gzseek passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)
librock_z_gztell passed tests in tzlib (Unix/Linux/BSD: 2002/08/08 sys=FreeBSD using gcc)
librock_z_gztell passed tests in tzlib_main (WIN32: 2002/08/08 sys=NT 4.0 using MSVC)


This software is part of Librock

Rapid reuse, without rework. Details
This page copyright (C) 2002-2003 Forrest J. Cavalier III, d-b-a Mib Software, Saylorsburg PA 18353, USA

Verbatim copying and distribution of this generated page is permitted in any medium provided that no changes are made.
(The source of this manual page may be covered by a more permissive license which allows modifications.)

Want to help? We welcome comments, patches. -- Need help? Request paid support.