zlib это библиотека сжатия данных общего назначения, авторы Jean-loup Gailly и Mark Adler. Это программное обеспечение предоставляется "как есть", без какой-либо фактической или подразумеваемой гарантии. Ни при каких условиях авторы не будут считаться ответственными ни за какие убытки, являющиеся результатом использования этого программного обеспечения (перевод документации [1]).

Всем без исключения дается разрешение на использование этого ПО для любых целей, включая коммерческие приложения. Дается разрешение на изменение этого ПО и свободное его распространение при условии соблюдения следующих ограничений:

1. Оригинальный вариант этого ПО не должен быть представлен в ложном свете; Вы не должны предъявлять права на то, что написали это оригинальное ПО. Если используете это ПО в своем продукте, то подтверждение оригинального авторства исходного кода было бы желательно, но это необязательное условие.
2. Измененные версии исходного кода должны быть ясно помечены соответствующей информацией, и не должны быть ложно представлены как будто это оригинальное ПО.
3. Эти замечания не должны быть удалены или изменены в любом дистрибутиве исходного кода.

Формат данных, используемый библиотекой zlib, описан в документах RFC 1950..1952, в файлах rfc1950 (zlib format), rfc1951 (deflate format) и rfc1952 (gzip format).

Версии zlib обозначаются в исходном коде константами:

#define ZLIB_VERSION "1.2.11"

#define ZLIB_VERNUM 0x12b0

[Введение]

Библиотека компрессии zlib предоставляет функции компрессии и декомпрессии памяти данных, включая проверку целостности распакованных данных. Эта версия библиотеки поддерживает только один метод компрессии (deflation), однако другие алгоритмы будут добавлены позже, и будут иметь такой же потоковый интерфейс.

Сжатие может быть выполнено за один шаг, если буферы для этого достаточно велики (например, если входной файл отображен на память процессора), или же сжатие может быть осуществлено повторяющимися вызовами функции компрессии. В последнем случае приложение должно предоставить большее количество входных данных или потребить большее количество выходных перед каждым вызовом.

Используемый функциями формат сжатия данных по умолчанию zlib, этот стандарт и обертка для него документированы в RFC 1950, RFC 1951.

Библиотека также поддерживает чтение и запись файлов в формате gzip (.gz) с интерфейсом, подобным stdio, при этом используются имена функций с префиксом "gz". Формат gzip отличается от формата zlib. Формат gzip и его обертка документированы в RFC 1952.

Также, как и для формата zlib, эта библиотека может опционально читать и записывать формат gzip и обрабатывать сырые deflate-потоки в памяти ("сырые", raw означает, что это только полезные сжатые данные, без информационного заголовка и проверочного хвоста с контрольной суммой).

Формат zlib был разработан с учетом компактности и скорости работы, с областью применения сжатия данных в памяти и каналах обмена данными. Формат gzip был разработан для сжатия одного файла в контексте файловых систем, и у него заголовок большего размера, чем заголовок zlib - чтобы содержать информацию о директории, и gzip использует другой, более медленный метод проверки, чем у zlib.

Библиотека не устанавливает никакой сигнальный заголовок. Декодер проверяет целостность сжатых данных, так что библиотека никогда не должна потерпеть катастрофический отказ в случае поврежденных данных на входе декодера.

[Структуры данных]

typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size));

typedef void   (*free_func)  OF((voidpf opaque, voidpf address));

struct internal_state;

typedef struct z_stream_s {
   z_const Bytef *next_in;     /* следующий входной байт */
   uInt     avail_in;  /* количество байт, доступных по адресу next_in */
   uLong    total_in;  /* общее количество прочитанных входных байт */
   Bytef    *next_out; /* здесь находится следующий выходной байт */
   uInt     avail_out; /* оставшееся свободное пространство по адресу next_out */
   uLong    total_out; /* общее количество выведенных байт */
   z_const char *msg;  /* последнее сообщение об ошибке, NULL если ошибки не было */
   struct internal_state FAR *state; /* это невидимо приложениям */
   alloc_func zalloc;  /* используется для выделения внутреннего состояния */
   free_func  zfree;   /* используется для освобождения внутреннего состояния */
   voidpf     opaque;  /* приватный объект данных, передаваемый в zalloc и zfree */
   int     data_type;  /* лучшее предположение о типе данных: bin или text

                          для deflate, или же состояние декодирования для inflate */
   uLong   adler;      /* значение Adler-32 или CRC-32 для распакованных данных */
   uLong   reserved;   /* зарезервировано для будущего использования */
} z_stream;

typedef z_stream FAR *z_streamp;

Информация заголовка gzip передается в подпрограммы zlib и из подпрограмм zlib. Подробное описание полей заголовка gzip см. в RFC 1952.

typedef struct gz_header_s {
    int     text;       /* true, если сжимаемые данные считаются текстом */
    uLong   time;       /* время модификации */
    int     xflags;     /* дополнительные флаги (не используются, когда записывается файл gzip) */
    int     os;         /* операционная система */
    Bytef   *extra;     /* указатель на дополнительное поле, или здесь Z_NULL, если этого поля нет */
    uInt    extra_len;  /* длина дополнительного поля (допустимо, если extra != Z_NULL) */
    uInt    extra_max;  /* размер памяти для extra (только когда считывается заголовок) */
    Bytef   *name;      /* указатель на ASCIIZ имя файла, или здесь Z_NULL */
    uInt    name_max;   /* размер памяти для имени файла (только когда считывается заголовок) */
    Bytef   *comment;   /* указатель на ASCIIZ-комментарий, или здесь Z_NULL */
    uInt    comm_max;   /* размер памяти для comment (только когда считывается заголовок) */
    int     hcrc;       /* true, если была или будет контрольная сумма заголовка */
    int     done;       /* true, когда считывается заголовок gzip (не используется при записи

                           файла gzip) */
} gz_header;

typedef gz_header FAR *gz_headerp;

[Использование структур]

Приложение должно обновлять next_in и avail_in, когда значение avail_in падает до 0. Также оно должно обновлять next_out и avail_out, когда avail_out падает до 0. Приложение должно инициализировать zalloc, zfree и opaque перед вызовом функции инициализации. Все другие поля устанавливаются библиотекой компрессии, и не должны обновляться приложением.

Значение opaque, предоставленное приложением, будет передано как первый параметр для вызовов zalloc и zfree. Это может быть полезно для пользовательского обслуживания памяти (например во встраиваемых приложениях, где может быть несколько куч памяти). Сама библиотека компрессии не придает никакого значения переменной opaque.

Функция zalloc должна вернуть Z_NULL, если не хватает памяти для объекта. Если zlib используется в многопоточном приложении, то  zalloc и zfree должны быть потокобезопасными (thread safe). Тогда и сама библиотека zlib будет потокобезопасной. Когда zalloc и zfree равны Z_NULL (не инициализированы) в момент запуска функции инициализации, то они будут установлены внутренними функциями на использование стандартных подпрограмм управления динамической памятью, т. е. на стандартные библиотечные функции malloc() и free().

На 16-битных системах функции zalloc и zfree должны быть способны выделить точно 65536 байт, но не требуется выделение большего количества, если определен символ MAXSEG_64K (см. zconf.h). ПРЕДУПРЕЖДЕНИЕ: в MSDOS указатели, которые возвращают zalloc для объектов размером точно 65536 байт, должны иметь свое смещение, нормализованное к 0. Функция по умолчанию для выделения памяти, предоставленная библиотекой zlib, гарантирует выполнение этого условия (см. zutil.c). Чтобы уменьшить требования памяти и избежать любых выделений объектов размером 64K, ценой ухудшения сжатия, компилируйте библиотеку с опцией -DMAX_WBITS=14 (см. zconf.h).

Примечание: опытным путем было установлено, что если делать распаковку (inflate) за 1 шаг, то требования к свободной памяти в куче для распаковки снижаются. Таким образом, при распаковке за 1 шаг zalloc должна быть способна выделить 8192 байта, и этого оказывается достаточно.

Поля total_in и total_out могут использоваться для информационной статистики и генерации сообщений о прогрессе операции компрессии/декомпрессии. После компрессии поле total_in содержит общий размер входных (не сжатых) данных, и это значение может быть сохранено для использования декомпрессором (в частности, если декомпрессор пожелает выполнить распаковку за 1 шаг).

[Константы]

Разрешенные значения для параметра flush (см. далее описание функций deflate() и inflate()).

#define Z_NO_FLUSH      0

#define Z_PARTIAL_FLUSH 1

#define Z_SYNC_FLUSH    2

#define Z_FULL_FLUSH    3

#define Z_FINISH        4

#define Z_BLOCK         5

#define Z_TREES         6

Коды возврата для функций компрессии/декомпрессии. Отрицательные значения обозначают ошибки, положительные используются для специальных, однако нормальных событий.

#define Z_OK              0

#define Z_STREAM_END      1

#define Z_NEED_DICT       2

#define Z_ERRNO         (-1)

#define Z_STREAM_ERROR  (-2)

#define Z_DATA_ERROR    (-3)

#define Z_MEM_ERROR     (-4)

#define Z_BUF_ERROR     (-5)

#define Z_VERSION_ERROR (-6)

Уровни компрессии:

#define Z_NO_COMPRESSION         0

#define Z_BEST_SPEED             1

#define Z_BEST_COMPRESSION       9

#define Z_DEFAULT_COMPRESSION  (-1)

Стратегия компрессии - для получения подробностей см. описание deflateInit2().

#define Z_FILTERED            1

#define Z_HUFFMAN_ONLY        2

#define Z_RLE                 3

#define Z_FIXED               4

#define Z_DEFAULT_STRATEGY    0

Возможные значения поля data_type для deflate().

#define Z_BINARY   0

#define Z_TEXT     1

#define Z_ASCII    Z_TEXT   /* для совместимости с 1.2.2

                                и более старыми версиями */

#define Z_UNKNOWN  2

Метод компрессии deflate (поддерживается только в этой версии 1.2.11).

#define Z_DEFLATED   8

Для инициализации zalloc, zfree, opaque.

#define Z_NULL  0

Для совместимости с версиями < 1.0.2.

#define zlib_version zlibVersion()

[Базовые функции]

ZEXTERN const char * ZEXPORT zlibVersion OF((void));

Приложение может сравнить zlibVersion и ZLIB_VERSION с целью проверки соответствия. Если первый символ отличается, то используемый код библиотеки не совместим с заголовочным файлом zlib.h, используемым приложением. Эта проверка автоматически делается функциями deflateInit и inflateInit.

ZEXTERN int ZEXPORT deflateInit OF((z_streamp strm, int level));

Инициализирует внутреннее состояние потока для компрессии. Перед вызовом deflateInit должны быть инициализированы поля zalloc, zfree и opaque структуры strm. Если zalloc и zfree установлены в Z_NULL, то deflateInit обновляет их для использования функций выделения памяти по умолчанию.

Уровень компрессии level должен быть Z_DEFAULT_COMPRESSION, или должен быть значением между 0 и 9: 1 дает самую лучшую скорость, 9 дает самую лучшую компрессию, 0 не предоставляет компрессию как таковую (входные данные просто копируются блоками на выход). Z_DEFAULT_COMPRESSION запрашивает использование компромисса по умолчанию между скоростью и сжатием (сейчас это соответствует уровню 6).

Функция deflateInit вернет Z_OK при успешном завершении, Z_MEM_ERROR если не хватает памяти, Z_STREAM_ERROR если level не соответствует допустимому уровню компрессии, Z_VERSION_ERROR если версия библиотеки zlib (zlib_version) несовместима с версией, которую подразумевает вызывающий код (ZLIB_VERSION). Поле msg устанавливается в null, если нет сообщения об ошибке. Функция deflateInit не выполняет никакое сжатие данных, это будут делать последующие вызовы deflate().

ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush));

Функция deflate сожмет столько данных, сколько возможно, и остановится, когда входной буфер опустошится, или когда заполнится выходной буфер. Она может вводить некоторую задержку на выходе (между чтением входных данных и генерацией выходных), за исключением случая, когда передача данных между входом и выходом принудительно определена значением flush.

Функция выполняет одно или оба из следующих действий:

• Сжимает еще одну порцию входных данных, начиная с next_in, и соответственно обновляет next_in и avail_in. Если обработаны не все входные данные (когда для этого недостаточно места в выходном буфере), то next_in и avail_in обновляются, и обработка возобновится с этого места при следующем вызове deflate().
• Генерирует еще одну порцию выходных данных, начиная с next_out, и соответственно обновляет next_out и avail_out. Это действие принудительно задает параметр flush, если он не равен 0. Слишком частое принуждение сброса выходных данных (когда flush != 0) снижает степень сжатия данных, поэтом этот параметр должен устанавливаться в ненулевое значение только когда это действительно необходимо (это может быть необходимо в специальных приложениях, например для сжатия потока данных на канале связи). Даже если flush установлен в 0, могут быть сгенерированы некоторые выходные данные.

Перед вызовом deflate(), приложение должно гарантировать, что можно выполнить одно из этих действий, путем предоставления дополнительных данных на входе и/или предоставления дополнительного места для выходных данных, обновляя для этого значения полей avail_in или avail_out соответственно. Поле avail_out никогда не должно быть равно 0 перед вызовом deflate(). Приложение может потребить сжатые выходные данные, когда захочет, например когда выходной буфер заполнится (avail_out == 0), либо после каждого вызова deflate(). Если функция deflate() вернет Z_OK и 0 в avail_out, то она должна быть вызвана снова после того, как будет предоставлено дополнительное пространство в буфере, потому что могут ожидать вывода дополнительные выходные данные. См. описание функции deflatePending(), которую можно использовать, если это необходимо, чтобы определить, нужно или нет в таком случае предоставлять больше места под выходные данные.

Обычно параметр flush устанавливается в значение Z_NO_FLUSH, которое позволяет самой функции deflate() решать, сколько данных накапливать перед тем, как передавать их на выход, чтобы максимально повысить сжатие данных.

Если параметр flush установлен в значение  Z_SYNC_FLUSH, то все ожидающие выходные данные будут сброшены в выходной буфер с выравниванием по границе байта, чтобы декомпрессор мог получить все данные, доступные до сих пор (в частности, avail_in равно 0 после вызова, если перед вызовом в выходном буфере предоставлено достаточно места). Принудительный сброс данных в выходной буфер может снизить качество сжатия данных для некоторых алгоритмов компрессии, поэтому принудительный сброс следует использовать только когда это действительно необходимо. Это закончит текущий сжатый блок, и за ним идет пустой сохраненный блок с тремя битами плюс биты заполнения в следующем байте, за которым идут 4 байта (00 00 ff ff).

Если параметр flush установлен в Z_PARTIAL_FLUSH, то все ожидающие вывод выходные данные сбрасываются в выходной буфер, но выходные данные не выравниваются по границе байта. Все входные данные до настоящего момента будут доступны декомпрессора, как и для применения Z_SYNC_FLUSH. Это закончит текущий сжатый блок, и за ним будут идти пустой фиксированный блок кодов длиной 10 бит. Это гарантирует, что для декомпрессора произведено достаточное количество байт, чтобы закончить блок перед поступлением пустого блока с фиксированными кодами.

Если параметр flush установлен в Z_BLOCK, блок сжатия завершается и выдается наружу, как и для Z_SYNC_FLUSH, но выходные данные не выравниваются по границе байта, и до 7 бит текущего блока удерживаются для записи в качестве следующего байта после завершения следующего сжатого блока. В этом случае для декомпрессора в этот момент может быть не предоставлено достаточно бит, чтобы завершить декомпрессию данных, предоставленных в настоящий момент компрессором. Может понадобиться ожидание поступления следующего блока сжатых данных. Этот вариант может понадобиться для продвинутых приложений, которым нужно управление эмиссией сжатых блоков.

Если параметр flush установлен в Z_FULL_FLUSH, то на выход будут сброшены все данные, как и с Z_SYNC_FLUSH, и состояние алгоритма сжатия сбрасывается, так что декомпрессия может перезапуститься с этой точки, если предыдущие сжатые данные были повреждены, или если нужен произвольный доступ к данным. Слишком частое использование Z_FULL_FLUSH может сильно ухудшить качество сжатия данных.

Если deflate() возвратится с avail_out == 0, то эта функция должна быть вызвана снова с тем же самым значением параметра flush и дополнительным предоставленным пространством для выходных данных (с обновленным значением), пока сброс выходных данных не будет завершен (пока deflate не возвратится с не нулевым значением avail_out). В случае использования Z_FULL_FLUSH или Z_SYNC_FLUSH гарантируйте, что avail_out больше 6, чтобы избежать повторения маркеров flush из-за того, что при возврате было avail_out == 0.

Если параметр flush установлен в Z_FINISH, то ожидающие обработки входные данные обрабатываются, ожидающие вывода выходные данные сбрасываются в выходной буфер, и deflate() возвратит Z_STREAM_END, если было достаточно места для выходные данные. Если deflate() возвратила Z_OK или Z_BUF_ERROR, то эта функция должна быть вызвана еще раз с параметром Z_FINISH, и предоставить больше пространства для выходных данных (вызов с обновленным avail_out), но без дополнительных входных данных, пока функция deflate() не возвратится со значением Z_STREAM_END или с ошибкой. После того, как deflate() возвратит Z_STREAM_END, возможными операциями на потоке будут только deflateReset или deflateEnd.

Z_FINISH может использоваться в первом вызове deflate() после deflateInit(), если вся компрессия может быть выполнена за один шаг. Чтобы завершить компрессию за один шаг, в поле avail_out должно быть значение не меньше значения, которое возвратила функция deflateBound() (см. её описание далее). Тогда deflate() гарантированно возвратит Z_STREAM_END. Если было недостаточно предоставлено места под выходные данные, то deflate() не возвратит Z_STREAM_END, и должна быть вызвана снова так, как это было описано ранее.

Функция deflate() установит поле strm->adler в контрольную сумму Adler-32 от всех входных данных, которые были упакованы до текущего момента (т. е. контрольная сумма подсчитывается от total_in байт). Если генерируется поток gzip, то strm->adler вернет контрольную сумму CRC-32 по прочитанным входным данным (см. описание deflateInit() далее).

Функция deflate() может обновить strm->data_type, если она может сделать надежное предположение по поводу типа входных данных (Z_BINARY или Z_TEXT). Если есть сомнения, то данные считаются двоичными. Это поле предназначено только для информационных целей, и никак не влияет на работу алгоритма сжатия.

Функция deflate() вернет Z_OK, если был сделан некий прогресс (обработано больше входных данных или сгенерировано больше выходных данных), Z_STREAM_END если все входные данные были обработан, и все выходные данные были сгенерированы (только для случая, когда flush установлен в Z_FINISH), Z_STREAM_ERROR если состояние потока стало недопустимым (например, если next_in или next_out было равно Z_NULL, или состояние потока было неожиданно перезаписано приложением), или Z_BUF_ERROR если дальнейшая обработка невозможна (например, если avail_in или avail_out были равны 0). Обратите внимание, что код возврата Z_BUF_ERROR не фатальный, и deflate() может быть вызвана снова с предоставлением дополнительного количества входных данных или места под выходные данные, чтобы компрессия продолжилась.

ZEXTERN int ZEXPORT deflateEnd OF((z_streamp strm));

После вызова этой функции вся память динамически выделенная под структуры данных, будет освобождена. Эта функция отбрасывает все не обработанные входные данные и не делает сброс в выходной буфер никаких ожидающих вывода данных.

Функция deflateEnd() вернет Z_OK в случае успеха, Z_STREAM_ERROR если состояние потока было недостоверным, Z_DATA_ERROR если поток был освобожден преждевременно (некоторые входные или выходные данные были отброшены). В любом случае ошибки msg может быть установлен, но указывая тогда на статическую строку (которая не должна быть освобождена из памяти).

ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm));

Инициализирует внутреннее состояние потока для декомпрессии. Поля next_in, avail_in, zalloc, zfree и opaque должны быть предварительно инициализированы вызывающим кодом. В текущей версии inflate, предоставленные входные данные при вызове inflateInit() не читаются (не обрабатываются). Выделение скользящего окна будет отложено до первого вызова inflate (если декомпрессия не завершена на первом вызове). Если zalloc и zfree установлены в Z_NULL, то inflateInit обновит их на использование функций выделения памяти по умолчанию.

Функция inflateInit вернет Z_OK в случае успеха, Z_MEM_ERROR если недостаточно памяти, Z_VERSION_ERROR если версия библиотеки zlib несовместима с версией, подразумеваемой вызывающим кодом, или Z_STREAM_ERROR если параметры в недопустимом значении, как например если используется нулевой указатель на структуру. Поле msg устанавливается в null, если нет сообщения об ошибке. Функция inflateInit() не выполняет никакой декомпрессии. Реальная декомпрессия будет осуществлена вызовами inflate(). Поэтому next_in, avail_in, next_out и avail_out не используются и останутся не измененными. Текущая реализация inflateInit() не обрабатывает какую-либо информацию из заголовка, это откладывается до первого вызова inflate().

ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush));

Функция inflate() распаковывает столько данных, сколько возможно, и останавливается, когда либо опустошается входной буфер, или становится заполненным выходной буфер. Это может ввести некоторую задержку в появлении выходных данных (чтение входных данных без генерации выходных) кроме ситуации, когда принудительно задана операция сброса данных (flush).

Функция inflate() выполняет одно или оба следующих действия:

• Распаковывает больше данных со входа, начиная с позиции next_in, соответственно обновляя next_in и avail_in. Если не все входные данные обработаны (из-за того, что недостаточно места в выходном буфере), то next_in и avail_in будут соответственно обновлены, и обработка возобновиться с этого места при следующем вызове inflate().
• Генерирует больше выходных данных, начиная с позиции next_out, соответственно обновляя next_out и avail_out. Функция inflate() предоставляет столько выходных данных, сколько возможно, пока не закончатся данные во входном буфере, или пока не закончится место в выходном буфере (см. ниже описание параметра flush).

Перед вызовом inflate() приложение должно гарантировать, что можно произвести как минимум одно из этих действий путем предоставления большего количества данных на входе и/или большего места под данные на выходе, с соответствующем обновлением значением next_* и avail_*. Если код, который вызвал inflate(), не предоставил больше входных данных или больше места под выходные данные, то процесс декомпрессии не будет продолжен. Приложение может потребить распакованные выходные данные в любой момент, например когда выходной буфер станет заполненным (avail_out == 0), или после каждого вызова inflate(). Если inflate() возвратит Z_OK с нулем в avail_out, то она должна быть вызвана снова после предоставления большего количества места под данные в выходном буфере, потому что может быть большее количество данных, ожидающее своего вывода.

Параметр flush функции inflate() может принимать значения Z_NO_FLUSH, Z_SYNC_FLUSH, Z_FINISH, Z_BLOCK или Z_TREES. Z_SYNC_FLUSH запрашивает, чтобы inflate() сбрасывала в выходной буфер столько данных, сколько это возможно. Z_BLOCK запрашивает, чтобы inflate() остановилась, если она встретилась со следующей границей блока deflate. Когда декодируется формат zlib или gzip, это приведет к немедленному выходу из inflate() после заголовка и перед первым блоком. Когда осуществляется сырая декомпрессия (raw inflate), то функция inflate() будет переходить вперед и обрабатывать первый блок, и вернется, когда дойдет до конца этого блока, или когда закончатся данные.

Опция Z_BLOCK помогает в добавлении или в комбинировании потоков deflate. Чтобы помочь в этом, на выходе inflate() всегда установит strm->data_type в количество не используемых бит в последнем байте, полученном из strm->next_in, плюс 64, если inflate() в настоящий момент декодирует последний блок (end-of-block) в потоке deflate, плюс 128 если inflate() возвратилась немедленно после декодирования кода конца блока или декодирования полного заголовка, сразу перед первым байтом потока deflate. End-of-block не будет показан, пока все распакованные данные из этого блока не будут записаны в strm->next_out. Количество не использованных бит может быть обычно больше семи, кроме ситуации, когда установлен бит 7 поля data_type, в таком случае количество не использованных бит будет меньше восьми. Поле data_type устанавливается, как указано здесь, всякий раз, когда inflate() возвратится для всех опций flush, и это может использоваться для определения количества потребленных в настоящее время данных со входа, в битах.

Опция Z_TREES ведет себя так же, как и Z_BLOCK, но она также делает возврат, когда достигнут конец каждого заголовка блока deflate, перед тем, как будут декодированы реальные данные из этого блока. Это позволяет вызывающему коду определить длину заголовка блока для последующего использования при произвольном доступе внутри блока deflate. К значению strm->data_type добавляется 256, когда inflate() возвратится немедленно после достижения конца заголовка блока deflate.

Функция inflate() должна нормально вызываться до тех пор, пока она не возвратит Z_STREAM_END или ошибку. Однако если декомпрессия выполняется за один шаг (один вызов inflate), то параметр flush должен быть установлен в Z_FINISH. В этом случае все ожидающие обработки входные данные будут декодированы, и все ожидающие вывода данные будут сброшены в выходной буфер; значение avail_out должно быть достаточно большим, чтобы сохранить все распакованные данные, чтобы эта операция могла завершиться (для этой цели размер распакованных данных может быть сохранен компрессором). Использование Z_FINISH не требуется для выполнения декомпрессии за 1 шаг. Однако это может использоваться для информирования алгоритма декомпрессии, что может использоваться более быстрый способ для одиночного вызова inflate(). Z_FINISH также информирует алгоритм распаковки не поддерживать скользящее окно, если поток завершается, что уменьшает потребляемую память. Если поток не завершается либо из-за того, не все данные потока были предоставлены, либо предоставлено недостаточно места под выходные данные, то будет выделена память под скользящее окно, и inflate() может быть вызвана снова, чтобы продолжить работу, как если бы использовалась опция Z_NO_FLUSH.

В этой реализации функция inflate() всегда сбрасывает в выходной буфер столько данных, сколько возможно, и всегда использует самый быстрой способ обработки при первом вызове. Поэтому эффекты от параметра flush в этой реализации проявляются при возврате значения из inflate(), как показано ниже, когда inflate() сделает ранний возврат при использовании Z_BLOCK или Z_TREES, и когда inflate() избегает выделать память для скользящего окна при использовании Z_FINISH.

Если после этого вызова нужен словарь предварительной установки (см. ниже описание inflateSetDictionary), то алгоритм распаковки установит strm->adler в контрольную сумму Adler-32 словаря, выбранного компрессором, и возвратит Z_NEED_DICT; иначе алгоритм установит strm->adler в контрольную сумму Adler-32 всех выходных данных, сгенерированных до сих пор (т. е. от total_out байт), и вернет Z_OK, Z_STREAM_END или код ошибки, как это описано ниже. В конце потока inflate() проверяет вычисленную контрольную сумму Adler-32 на равенство контрольной сумме, которая была сохранена компрессором, и вернет Z_STREAM_END только если контрольная сумма была корректна.

Функция inflate() будет распаковывать и проверять сжатые данные либо на обертку zlib, либо на обертку gzip. Тип заголовка детектируется автоматически, если это запрашивается при инициализации через вызов inflateInit2(). Любая информация, содержащаяся в заголовке gzip, не сохраняется, если не используется inflateGetHeader(). Когда обрабатываются сжатые данные с оберткой gzip, strm->adler32 устанавливается в CRC-32 выходных данных, сгенерированных до настоящего момента. CRC-32 проверяется на соответствие с хвостом gzip, как несжатая длина, по модулю 2^32.

Функция inflate() вернет Z_OK, если был сделан некоторый прогресс (было обработана еще порция входных данных и/или была выведена еще порция выходных), Z_STREAM_END если сжатые данные закончились и были сгенерированы выходные данные, Z_NEED_DICT если в этом месте нужен словарь предустановки, Z_DATA_ERROR если входные данные были повреждены (входной поток не удовлетворяет формату zlib или некорректное проверочное значение, в этом случае strm->msg указывает на строку с более точным указанием на ошибку), Z_STREAM_ERROR если структура потока была некорректна (например next_in или next_out были Z_NULL, или состояние потока было неожиданно перезаписано приложением), Z_MEM_ERROR если недостаточно памяти, Z_BUF_ERROR если невозможен дальнейший прогресс или если недостаточно места в выходном буфере, когда использовался Z_FINISH. Имейте в виду, что сообщение Z_BUF_ERROR не фатально, и inflate() может быть вызвана еще раз с дополнительно предоставленными входными данными и/или большим количеством пространства под выходные данные, чтобы процесс декомпрессии продолжился. Если было возвращено значение Z_DATA_ERROR, приложение может тогда вызвать inflateSync(), чтобы увидеть хороший блок сжатых данных, если сделана попытка частичного восстановления данных.

ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm));

Функция освободит всю динамически выделенную память под структуры данных этого потока. Функция отбросит любые необработанные входные данные, и не сбросит в выходной буфер любые ожидающие вывода выходные данные. Функция inflateEnd вернет Z_OK в случае успеха или Z_STREAM_ERROR если состояние потока было неправильным.

[Продвинутые функции]

Следующие функции нужны только для специальных приложений.

ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm,
                                     int  level,
                                     int  method,
                                     int  windowBits,
                                     int  memLevel,
                                     int  strategy));

Это другая версия deflateInit с дополнительными опциями компрессии. Поля next_in, zalloc, zfree и opaque должны быть предварительно инициализированы вызывающим кодом.

Параметр method задает метод компрессии. В этой версии библиотеки он должен быть Z_DEFLATED.

Параметр windowBits это логарифм по основанию 2 для размера окна (размер буфера истории). Для этой версии библиотеки значение этого параметра должно быть в диапазоне 8..15. Чем больше значение этого параметра, тем лучше компрессия ценой повышения использования памяти. Значение по умолчанию равно 15, если используется функция deflateInit() вместо deflateInit2().

Для текущей реализации deflate() значение windowBits 8 (размер окна 256 байт) не поддерживается. В результате запрос со значением 8 будет вместо этого использовать 9 (512-байтное окно). В этом случае предоставление 8 для inflateInit2() приведет к ошибке, когда заголовок zlib с 9 проверяется инициализацией inflate(). Для исправления ситуации не используйте 8 с deflateInit2() в этой инициализации, или как минимум используйте 9 с inflateInit2().

Параметр windowBits может также быть –8 .. –15 для сырой компрессии (raw deflate). В этом случае размер окна определит значение -windowBits. Функция deflate() тогда будет генерировать сырые сжатые данные без заголовка или хвоста zlib, и не будет вычислять проверочное значение.

Параметр windowBits может быть также больше 15 для опционального кодирования gzip. Добавьте 16 к windowBits для написания простого заголовка и хвоста gzip вокруг сжатых данных вместо обертки zlib. Заголовок gzip не будет иметь имя файла, дополнительных данных, комментария, не будет времени модификации (оно установится в 0), не будет CRC заголовка, и операционная система установит подходящее значение, если операционная система была определена в момент компиляции. Если записывается поток gzip, то в strm->adler записывается CRC-32 вместо Adler-32.

Для сырой компрессии или кодирования gzip запрос на 256-байтное окно отклоняется как недопустимое, поскольку только заголовок zlib предоставляет способ передать размер окна декомпрессору.

Параметр memLevel задает, сколько памяти должно быть выделено для внутреннего состояния компрессии. Значение memLevel=1 использует минимальное количество, но работает медленно, и снижает степень сжатия; memLevel=9 использует память по максимуму для оптимальной скорости. Значение по умолчанию 8. См. zconf.h для общего использования памяти как функции от windowBits и memLevel.

Параметр strategy используется для настройки алгоритма компрессии. Используйте значение Z_DEFAULT_STRATEGY для обычных данных, Z_FILTERED для данных, представленных фильтром (или предсказателем), Z_HUFFMAN_ONLY для принудительного использования только кодирования Хаффмана (не соответствует строкам) или Z_RLE для ограничения до 1 дистанции совпадения (кодирование run-length, RLE; подробнее см. в Википедии "Кодирование длин серий"). Фильтрованные данные состоят обычно из малых значений с неким случайным распределением. В этом случае алгоритм сжатия подстраивается, чтобы сжатие было эффективнее. Эффект Z_FILTERED состоит в принудительном кодировании Хаффмана с меньшим совпадением со строками; эффект промежуточный между Z_DEFAULT_STRATEGY и Z_HUFFMAN_ONLY. Z_RLE разработан, чтобы он работал почти также быстр, как Z_HUFFMAN_ONLY, но давал лучшее сжатие для растровых данных картинок PNG. Параметр strategy влияет только на степень компрессии, но не на правильность выходных сжатых данных, даже если это не установлено соответственно. Z_FIXED предотвращает использование динамических кодов Хаффмана, позволяя применять упрощенный декодер для специальных приложений.

Функция deflateInit2() вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватает памяти, Z_STREAM_ERROR если указан неправильный параметр (как например недопустимый method), или Z_VERSION_ERROR если версия библиотеки zlib (zlib_version) несовместима с версией, которую подразумевает вызывающий код (ZLIB_VERSION). Указатель на строку msg устанавливается в null, если нет сообщения об ошибке. Функция deflateInit2() не выполняет никакую компрессию: это делает функция deflate().

ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm,
                                             const Bytef *dictionary,
                                             uInt  dictLength));

Инициализирует словарь сжатия из заданной последовательности байт без генерации каких-либо выходных сжатых данных. Эта функция должна быть вызвана сразу после deflateInit, deflateInit2 или deflateReset, перед любым вызовом deflate. Компрессор и декомпрессор должны использовать абсолютно одинаковый словарь (см. inflateSetDictionary). Когда используется формат zlib, эта функция должна быть вызвана сразу после deflateInit, deflateInit2 или deflateReset, и перед любым вызовом deflate. Когда выполняется сырое сжатие (raw deflate), эта функция должна быть вызвана либо перед любым вызовом deflate, либо сразу после завершения блока deflate, например после того, как все входные данные были обработаны, и все выходные данные были переданы в выходной буфера с помощью flush-опцийi Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH или Z_FULL_FLUSH. Компрессор и декомпрессор должны использовать абсолютно одинаковый словарь (см. inflateSetDictionary).

Словарь должен состоять из строк (последовательностей байт), которые скорее всего встретятся позже в сжимаемых данных. Использование словаря особенно полезно, когда данные для сжатия короткие, и могут быть предсказаны с хорошей точностью; данные могут быть лучше сжаты, чем с пустым словарем по умолчанию.

В зависимости от размера структур сжатия данных, выбранных функциями deflateInit или deflateInit2, часть словаря может быть отброшена, например если словарь больше, чем используемое окно в deflate или deflate2. Таким образом строки, более полезные для использования, должны быть помещены в конец словаря, а не в его начало. Кроме того, текущая реализация deflate будет использовать самое большее размер окна минус 262 байта предоставленного словаря.

При возврате из этой функции strm->adler устанавливается в значение Adler-32 словаря; декомпрессор может позже использовать это значение, чтобы определить, какой словарь был использован компрессором (значение Adler-32 относится ко всему словарю, даже если компрессором в действительности было использована только его часть). Если запрошено сырое сжатие (raw deflate), то значение Adler-32 не вычисляется, и strm->adler не устанавливается.

Функция deflateSetDictionary вернет Z_OK в случае успеха или Z_STREAM_ERROR если параметр недопустимый (такой как например NULL в параметре dictionary), или если состояние потока некорректное (например если deflate уже была вызвана для этого потока, или если вызов произошел не на границе блока для raw deflate). Функция deflateSetDictionary не выполняет никакое сжатие: это делается функцией deflate().

ZEXTERN int ZEXPORT deflateGetDictionary OF((z_streamp strm,
                                             Bytef *dictionary,
                                             uInt  *dictLength));

Вернет скользящий словарь, который поддерживает deflate. Параметр dictLength устанавливается на количество байт в словаре, и сколько байт копируется в словарь dictionary. По указателю должно быть достаточно места, 32768 байт всегда хватит. Если deflateGetDictionary() вызывается с dictionary, равным Z_NULL, то будет возвращена только длина словаря, и никакие данные словаря копироваться не будут. Подобным образом, если dictLength равен Z_NULL, то длина словаря установлена не будет.

Функция deflateGetDictionary() может вернуть длину меньше размера окна, даже когда на входе был обеспечен буфер больше размера окна. В этом случае может быть возвращено меньше 258 байт, потому что реализация функции deflate библиотеки zlib управляет скользящим окном и предвидением для соответствий, где длина соответствия может быть до 258 байт. Если для приложения нужны последние байты размера окна, то они должны быть сохранены приложением вне библиотеки zlib.

Функция deflateGetDictionary вернет Z_OK в случае успеха или Z_STREAM_ERROR, если состояние потока было противоречивым.

ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest,
                                    z_streamp source));

Устанавливает поток назначения как полную копию потока источника.

Эта функция полезна, когда делаются попытки использовать несколько стратегий компрессии, например когда есть несколько способов предварительной обработки входных данные с помощью фильтра. Тогда потоки, которые отбрасываются, должны быть освобождены вызовом deflateEnd. Обратите внимание, что deflateCopy делает дубликат внутреннего состояния компрессии, которое может быть довольно большим, так что эта стратегия медленная, и может потребить большой объем памяти.

Функция deflateCopy вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватает памяти, Z_STREAM_ERROR если состояние исходного потока было противоречивым (например, если zalloc равен NULL). Сообщение msg останется не измененным в обоих потоках, dest и source.

ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm));

Эта функция эквивалентна deflateEnd, за которой следует deflateInit, но она не освобождает и не выделяет заново память для внутреннего состояния компрессии. У потока останется не измененным уровень компрессии и другие установленные атрибуты.

Функция deflateReset вернет Z_OK в случае успеха или Z_STREAM_ERROR, если исходное состояние потока было противоречивым (например, если zalloc или state были равны NULL).

ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm,
                                      int level,
                                      int strategy));

Динамически обновляет уровень сжатия и стратегию компрессии. Интерпретация параметров level и strategy такое же, как и у deflateInit2(). Это может использоваться для переключения между компрессией и прямым копированием входных данных, или для переключения к обработке другого типа входных данных, требующих другой стратегии сжатия. Если поменялся метод компрессии (который является функцией от level) или поменялась стратегия, и если любые входные данные были потреблены предыдущим вызовом deflate(), то входные данные, которые были доступны до сих пор, сжимаются со старым уровнем и стратегией (применяются старые значения level и strategy) с использованием deflate(strm, Z_BLOCK). Есть 3 подхода к уровням компрессии, 0, 1..3 и 4..9 соответственно. Новые level и strategy вступят в силу при следующем вызове deflate().

Если deflate(strm, Z_BLOCK) выполняется функцией deflateParams(), и не хватит места под выходные данные для завершения, то изменение параметров не вступят в силу. В этом случае может быть снова сделана попытка вызова deflateParams() с теми же параметрами и большим предоставленным пространством для выходных данных.

Чтобы гарантировать изменение параметров на первой попытке, перед вызовом deflateParams() выходные данные потока сжатия должны быть сброшены в выходной буфер использованием deflate() с параметром Z_BLOCK или другим запросом сброса, пока strm.avail_out не равен 0. Тогда не должно быть предоставлено большее количество входных данных перед вызовом deflateParams(). Если это сделано, то старые level и strategy будут применены к сжатым данных перед вызовом deflateParams(), и новые level и strategy будут применены к данным, сжатым перед deflateParams().

Функция deflateParams вернет Z_OK в случае успеха, Z_STREAM_ERROR если состояние исходного потока было противоречивым, или если параметр был недопустимым, или Z_BUF_ERROR если было недостаточно места под выходные данные для завершения сжатия доступных входных данных перед изменением в стратегии или методе сжатия. Обратите внимание, что в случае Z_BUF_ERROR текущие параметры уровня сжатия и стратегии не изменяются. Возвращенное значение Z_BUF_ERROR не фатально, в этом случае deflateParams() может быть вызвана снова с дополнительно предоставленным местом под выходные данные.

ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm,
                                    int good_length,
                                    int max_lazy,
                                    int nice_length,
                                    int max_chain));

Тонкая настройка внутренних параметров компрессии. Это должно использоваться только теми специалистами, кто понимает алгоритм, используемый для сжатия библиотекой zlib при поиске лучшей совпадающей строки, и только когда самый фанатичный оптимизатор пытается выжать последние биты из каких-то определенных входных данных. Изучите исходный код deflate.c, чтобы разобраться со значением параметров max_lazy, good_length, nice_length и max_chain.

Функция deflateTune() может быть вызвана после deflateInit() или deflateInit2(), и вернет Z_OK в случае успеха, или Z_STREAM_ERROR на неправильном потоке сжатия.

ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm,
                                       uLong sourceLen));

Функция deflateBound() вернет предельное количество байт на выходе после сжатия sourceLen байт. Она должна быть вызвана после deflateInit() или deflateInit2(). Это может использоваться для выделения буфера под выходные данные, чтобы можно было выполнить компрессию за один шаг, и вызов deflateBound() должен быть сделан перед deflate(). Если первый вызов deflate() был сделан для предоставленных sourceLen входных байт, выделенный выходной буфер выбран размером, который возвратила deflateBound(), и значение параметра flush было выбрано Z_FINISH, то deflate() гарантированно вернет Z_STREAM_END. Обратите внимание, что размер сжатых данных может быть больше, чем возвращенное значение deflateBound(), если используемая опция flush отличается от Z_FINISH или Z_NO_FLUSH.

ZEXTERN int ZEXPORT deflatePending OF((z_streamp strm,
                                       unsigned *pending,
                                       int *bits));

Функция deflatePending() вернет количество байт и бит выходных данных, которые были сгенерированы, по пока еще не предоставлены в выходном буфере. Это могло произойти из-за того, что было предоставлено недостаточно места в выходном буфере. Количество бит не предоставленных выходных данных находится в диапазоне от 0 до 7, где они будут ожидать большего количества бит для заполнения, чтобы получился полный байт. Если указатели pending или bits равны Z_NULL, то соответствующие величины не будут установлены.

Функция deflatePending вернет Z_OK в случае успеха, или Z_STREAM_ERROR если исходный поток был противоречивым.

ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm,
                                     int bits,
                                     int value));

Функция deflatePrime() вставляет биты в выходной поток сжатых данных. Назначение этой функции - выкачать оставшиеся выходные биты от предыдущего потока сжатия при добавлении к нему данных. Таким образом, эту функцию можно использовать только для сырого сжатия (raw deflate), и она должна использоваться перед первым вызовом deflate() после deflateInit2() или deflateReset(). Значение bits должно быть меньше или равно 16, и младшие значащие биты value будут вставлены в выходные данные.

Функция deflatePrime вернет Z_OK в случае успеха, Z_BUF_ERROR если было недостаточно места во внутреннем буфере для вставки бит, или Z_STREAM_ERROR если исходный поток был противоречивым.

ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm,
                                         gz_headerp head));

Функция deflateSetHeader() предоставляет информацию заголовка gzip для потока gzip, когда он запрашивается функцией deflateInit2(). Функция deflateSetHeader() может быть вызвана после deflateInit2() или deflateReset(), и перед первым вызовом deflate(). Поля text, time, os, extra, и информация комментария comment в предоставленной структуре gz_header записываются в заголовок gzip (xflag игнорируется - дополнительные флаги устанавливаются в соответствии с уровнем сжатия). Вызывающий код должен гарантировать, что строки name и comment (если они не равны Z_NULL) должны завершаться нулевым байтом, и если extra не равен Z_NULL, то там будет доступно extra_len байт. Если hcrc равно true, то включена контрольная сумма заголовка gzip. Обратите внимание, что текущие версии утилит командной строки gzip (до версии 1.3.x) не поддерживают контрольную сумму заголовка, сообщат о недопустимом файле с несколькими частями ("multi-part gzip file") и завершат работу.

Если deflateSetHeader не используется, то заголовок gzip по умолчанию имеет text в значении false, time установленное в 0, и os установленный в 255, без полей extra, name или comment. Заголовок gzip возвращается в состояние по умолчанию вызовом deflateReset().

Функция deflateSetHeader вернет Z_OK в случае успеха, или Z_STREAM_ERROR если исходный поток был противоречивым.

ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm,
                                     int  windowBits));

Это другая версия inflateInit с дополнительным параметром. Поля next_in, avail_in, zalloc, zfree и opaque предварительно должны быть инициализированы вызывающим кодом.

Параметр windowBits это показатель степени числа 2 (логарифм по основанию 2) для максимального размера окна (размер буфера истории). Для этой версии библиотеки он должен быть в диапазоне 8..15. Значение по умолчанию 15, если вместо inflateInit2 использовалась inflateInit. Параметр windowBits должен быть больше или равен значению windowBits, предоставленному для deflateInit2() при компрессии, или он должен быть равен 15, если deflateInit2() не использовалась. Если на входе поток компрессии поток сжатых данных с размером окна больше, то inflate() завершит работу с кодом ошибки Z_DATA_ERROR, вместо того, чтобы попытаться выделить окно большего размера.

Параметр windowBits также может быть нулем для запроса, чтобы inflate использовала размер окна из заголовка zlib потока сжатых данных.

Параметр windowBits также может быть в диапазоне –8..–15 для сырой распаковки (raw inflate). В этом случае размер окна будет определять значение -windowBits. Функция inflate() тогда будет обрабатывать сырые сжатые данные, не ожидая на входе заголовка zlib или gzip, не генерируя проверочное значение, и не ожидая любые проверочные значения в конце потока для проверки на целостность данных. Это применяется для использования с другими форматами, которые используют формат сжатых данных, как например zip. Эти форматы предоставляют свои собственные проверочные значения. Если пользовательский формат разработан с использованием формата сырых сжатых данных (raw deflate), то рекомендуется использовать проверочное значение Adler-32 или CRC-32, добавленное к распакованным данным, как это сделано в форматах zlib, gzip и zip. Для большинства приложений формат zlib должен использоваться как есть. Обратите внимание, что предыдущие замечания по использованию в deflateInit2() применимы к величине windowBits.

Параметр windowBits также может быть больше 15 для опционального декодирования gzip. Добавьте 32 к windowBits, чтобы разрешить декодирование zlib и gzip с автоматическим детектированием заголовка, или добавьте 16, чтобы декодировать только формат gzip (попытка декодирования формата zlib вернет Z_DATA_ERROR). Если декодируется поток gzip, то в strm->adler применяется CRC-32 вместо Adler-32. В отличие от утилиты gunzip и gzread() (см. далее), функция inflate() не будет автоматически декодировать склеенные потоки gzip. Функция inflate() вернет Z_STREAM_END в конце потока gzip. Для продолжения декодирования следующего потока gzip требуется сброс состояния.

Функция inflateInit2 вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватает памяти, Z_VERSION_ERROR если версия библиотеки zlib не совместима с версией, которую подразумевает вызывающий код, Z_STREAM_ERROR если указаны неправильные параметры, такие как нулевой указатель на структуру. Поле msg устанавливается в null, если нет сообщения об ошибке. Функция inflateInit2 не выполняет никакую декомпрессию кроме чтения заголовка zlib, если он присутствует: реальную декомпрессию делает функция inflate() (так что next_in и avail_in могут быть модифицированы, но next_out и avail_out останутся не измененными). Текущая реализация inflateInit2() не обрабатывает какую-либо информацию заголовка information, это откладывается до первого вызова inflate().

ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm,
                                             const Bytef *dictionary,
                                             uInt  dictLength));

Инициирует словарь декомпрессии из указанной последовательности несжатых байт. Эта функция должна быть вызвана немедленно после вызова inflate, если вызов вернул Z_NEED_DICT. Словарь, выбранный компрессором, может быть определен по значению Adler-32, возвращенному этим вызовом inflate. Компрессор и декомпрессор должны использовать абсолютно одинаковый словарь (см. описание функции deflateSetDictionary). Для сырой распаковки (raw inflate) эта функция может быть вызвана в любое время с целью установки словаря. Если предоставленный словарь меньше, чем окно, и в окне уже имеются данные, то предоставленный словарь исправит данные, находящиеся там. Приложение должно гарантировать, что предоставленный словарь именно тот, что использовался для сжатия.

Функция inflateSetDictionary вернет Z_OK в случае успеха, Z_STREAM_ERROR если параметр неправильный (например, если dictionary равен NULL) или состояние потока было противоречивым, Z_DATA_ERROR если предоставленный словарь не соответствует ожидаемому (некорректное значение Adler-32). Функция inflateSetDictionary не выполняет никакую декомпрессию: это будет выполнено последующими вызовами inflate().

ZEXTERN int ZEXPORT inflateGetDictionary OF((z_streamp strm,
                                             Bytef *dictionary,
                                             uInt  *dictLength));

Вернет скользящий словарь, поддерживаемый функцией распаковки inflate. Параметр dictLength устанавливается в количество байт в словаре, байты словаря будут скопированы по указателю dictionary. В буфере, на который указывает dictionary, должно быть достаточно места, 32768 байт всегда будет достаточно. Если inflateGetDictionary() будет вызвана с указателем dictionary, равным Z_NULL, то будет возвращена только длина словаря, и сам словарь копироваться не будет. Подобным образом, если dictLength равен Z_NULL, то длина словаря возвращена не будет.

Функция inflateGetDictionary вернет Z_OK в случае успеха, или Z_STREAM_ERROR если состояние потока противоречиво.

ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm));

Пропускает неправильные сжатые данные, пока не будет найдена точка полной выгрузки (см. выше описание функции deflate с параметром Z_FULL_FLUSH), или пока не будет пропущен все доступные входные данные. Никакие выходные данные сгенерированы не будут.

Функция inflateSync ищет последовательность 00 00 FF FF в сжатых данных. Все точки полной выгрузки (full flush point) имеют этот маркер, но не все встретившиеся такие маркеры относятся к точкам полной выгрузки.

Функция inflateSync вернет Z_OK, если была найдена возможная точка полной выгрузки, Z_BUF_ERROR если больше не было предоставлено входных данных, Z_DATA_ERROR если не найдена точка flush point, или Z_STREAM_ERROR если структура потока была противоречивой. В случае успеха приложение может сохранить текущее значение в total_in, которое покажет, где можно найти допустимые сжатые данные. В случае ошибки приложение может несколько раз вызвать inflateSync, каждый раз предоставляя дополнительные входные данные, пока не добьется успеха или не дойдет до конца входных данных.

ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest,
                                    z_streamp source));

Устанавливает поток назначения dest как копию исходного потока source.

Эта функция может быть полезна, когда осуществляется произвольный доступ по большому потоку. Первый проход по потоку может периодически записывать состояние inflate, что позволяет перезапускать распаковку в записанных точках при произвольном доступе к данным потока.

Функция inflateCopy вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватает памяти, Z_STREAM_ERROR если состояние потока source было противоречивым (например, если zalloc было равно NULL). Поле msg остается не измененным как в исходном потоке, так и в потоке назначения.

ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm));

Эта функция эквивалентна вызову inflateEnd, за которым идет вызов inflateInit, отличие только в том, что не освобождается и не выделяется повторно память под внутреннее состояние процесса декомпрессии. В потоке будут сохранены атрибуты, которые могли быть установлены вызовом inflateInit2.

Функция inflateReset вернет Z_OK в случае успеха или Z_STREAM_ERROR, если состояние исходного потока source было противоречивым (как например если zalloc или state были равны NULL).

ZEXTERN int ZEXPORT inflateReset2 OF((z_streamp strm,
                                      int windowBits));

Эта функция делает то же самое, что и inflateReset, но также позволяет делать запросы на изменение размера окна и обертки. Параметр windowBits интерпретируется так же, как и у inflateInit2. Если размер окна меняется, то память, выделенная для окна, освобождается, и окно выделяется заново функцией inflate(), если это необходимо.

Функция inflateReset2 вернет Z_OK в случае успеха или Z_STREAM_ERROR, если состояние исходного потока было противоречивым (как например если zalloc или state были равны Z_NULL), или если был указан недопустимый параметр windowBits.

ZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm,
                                     int bits,
                                     int value));

Эта функция вставляет биты во входной поток inflate. Назначение этой функции - начать распаковку в позиции бита, находящейся посередине байта. Используется предоставленный параметр bits перед любыми байтами из next_in. Эта функция должна использоваться только для сырой распаковки (raw inflate), и должна использоваться перед первым вызовом inflate() после вызова inflateInit2() или inflateReset(). Параметр bits должен быть меньше или равен 16, и некоторое количество младших бит value будет вставлено во входные данные.

Если значение bits отрицательное, то буфер бит входного потока опустошается. Тогда inflatePrime() может быть вызвана снова для размещения бит в буфер. Это используется для очистки остатка бит после обработки входных данных функцией inflate при пропуске описания блока перед тем, как передать коды в функцию inflate.

Функция inflatePrime вернет Z_OK в случае успеха, или Z_STREAM_ERROR если исходный поток был противоречивым.

ZEXTERN long ZEXPORT inflateMark OF((z_streamp strm));

Эта функция вернет 2 значения, одно в младших 16 битах возвращаемого значения, и второе в оставшихся старших битах, полученных путем сдвига вправо на 16 позиций возвращенного значения. Если старшее значение –1 и младшее 0, то inflate() в настоящий момент декодирует информацию вне блока. Если старшее значение –1 и младшее не равно 0, то inflate находится в середине сохранного блока, с младшим значением, равным количеству байт со входа, оставшихся для копирования. Если старшее значение не –1, то это количество бит обратно от текущей обрабатываемой позиции бит входного кода (литерал или пара длина/расстояние). В этом случае младшее значение это количество байт, уже сгенерированное для этого кода.

Код находится в обработке, если inflate ждет поступления большего количества данных для завершения декодирования кода, или если было завершено декодирование, но требуется дополнительное пространство для записи в выходной буфер литерала или соответствующих данных.

Функция inflateMark() используется для пометки мест во входных данных при произвольном доступе, которые могут находится в позициях бита, и помечать те случаи, когда выходной код может относится к границам блоков произвольного доступа. Текущая позиция во входном потоке может быть определена из avail_in и data_type, как это было отмечено в описании значения Z_BLOCK параметра flush для функции inflate.

Функция inflateMark вернет упомянутое выше значение или –65536, если предоставленный входной поток был противоречивым.

ZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm,
                                         gz_headerp head));

Функция inflateGetHeader() запрашивает информацию заголовка gzip, сохраненную в предоставленной структуре gz_header. Функция inflateGetHeader() может быть вызвана после inflateInit2() или inflateReset(), и перед первым вызовом inflate(). Когда inflate() обрабатывает поток gzip, head->done равен 0, пока не будет обработан заголовок, и 1, когда заголовок обработан. Если декодируется поток zlib, то head->done устанавливается в –1, чтобы показать, что здесь нет информации заголовка gzip. Обратите внимание, что может использоваться Z_BLOCK, чтобы заставить inflate() сделать немедленный возврат после завершения обработки заголовка и перед реальной декомпрессией данных.

Поля text, time, xflags и os заполняются содержимым из заголовка gzip. Поле hcrc устанавливается в true, если в заголовке есть CRC (CRC заголовка допустима, если это поле установлено в 1). Если extra не равно Z_NULL, то extra_max содержит максимальное количество байт для записи в extra. Когда поле done стало true, extra_len содержит реальную длину буфера, указанного полем extra, и extra содержит дополнительное поле, или это поле обрезается, если extra_max меньше, чем extra_len. Если name не равно Z_NULL, то туда записано до name_max символов строки, завершающейся нулем, кроме ситуации, когда длина строки больше name_max. Если comment не равен Z_NULL, то туда записано до comm_max символов строки комментария, завершающейся нулем, кроме ситуации, когда длина строки больше comm_max. Когда любое из полей extra, name или comment не равно Z_NULL, и соответствующее поле не присутствует в заголовке, то это поле устанавливается в Z_NULL, чтобы сигнализировать об его отсутствии. Это позволяет использовать deflateSetHeader() с возвращенной структурой для создания дубликата заголовка. Однако если эти поля установлены на выделенную память, то приложение должно сохранить эти указатели где-нибудь, чтобы они могли быть когда-то освобождены.

Если inflateGetHeader на используется, то информация заголовка просто отбрасывается. Заголовок всегда проверяется на правильность, включая CRC, если она есть. Функция inflateReset() сбросит обработку, чтобы отбросить информацию заголовка. Приложению может понадобиться повторный вызов inflateGetHeader(), чтобы запросить информацию из следующего потока gzip.

Функция inflateGetHeader вернет Z_OK в случае успеха, или Z_STREAM_ERROR если исходный поток был противоречивым.

ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits,
                                        unsigned char FAR *window));

Инициализирует внутреннее состояние потока для декомпрессии с использованием вызова inflateBack(). Поля zalloc, zfree и opaque в strm должны быть инициализированы перед этим вызовом. Если zalloc и zfree равны Z_NULL, то для работы с кучей будет использоваться библиотека по умолчанию. Параметр windowBits равен логарифму по основанию 2 от размера окна, в диапазоне 8..15. Окно представляется вызывающим кодом в буфере window соответствующего размера. Исключая специальные приложения, где гарантируется, что deflate использовалась меньшими размерами окна, значение windowBits должно быть равно 15, и размер окна должен быть 32 килобайта, чтобы можно было выполнить декомпрессию основных потоков deflate.

Для использования этих функций см. описание inflateBack().

Функция inflateBackInit вернет Z_OK в случае успеха, Z_STREAM_ERROR если любой из параметров неправильный, Z_MEM_ERROR если внутреннее состояние не может быть выделено, или Z_VERSION_ERROR если версия библиотеки не соответствует версии заголовочного файла zlib.

typedef unsigned (*in_func) OF((void FAR *,
                                z_const unsigned char FAR * FAR *));

typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned));

ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm,
                                    in_func in, void FAR *in_desc,
                                    out_func out, void FAR *out_desc));

Функция inflateBack() делает сырую распаковку за один вызов с использованием callback-интерфейса для ввода и вывода. Это потенциально более эффективно, чем применение inflate() для приложений с файловым вводом/выводом, потому что это позволяет избежать копирования между выходом и скользящим окном, так как само окно становится выходным буфером. Функция inflate() может работать быстрее на современных CPU, когда используются большие буферы. Функция inflateBack() доверяет приложению, что оно не поменяет выходной буфер, переданный функцией вывода, как минимум до тех пор, пока inflateBack() не возвратит управление.

Предварительно должна быть вызвана inflateBackInit(), чтобы выделить память под внутреннее состояние и инициализировать состояние с предоставленным пользователем буфером окна. Тогда inflateBack() может использоваться несколько раз для завершения декомпрессии, обрабатывая сырой поток сжатых данных на каждом вызове. После этого вызывается функция inflateBackEnd(), чтобы освободить память, выделенную под состояние.

Сырой поток сжатых данных может быть либо потоком zlib, либо потоком gzip, у которых отсутствуют заголовок и хвост. Это подпрограмма должна обычно использоваться в утилитах, которые читают файлы zip или gzip, и записывают распакованные файлы. Утилита должна декодировать заголовок и обрабатывать хвост сама, так что эта функция ожидает на входе только сырой поток сжатых данных, который нужно распаковать. Это отличается от поведения по умолчанию для inflate(), которая ожидает на входе заголовка zlib, и по окончанию потока сжатых данных ожидает хвост с контрольным значением.

Функция inflateBack() использует 2 подпрограммы, предоставленные вызывающим кодом, который вызовет inflateBack() для входа и выхода. Функция inflateBack() вызовет эти подпрограммы в процессе чтения полного потока deflate и записи всех распакованных данных, пока все не будет выполнено или пока не произойдет ошибка. Параметры функции и возвращаемые типы определены выше в операторах typedef для in_func и out_func. Функция inflateBack() будет вызывать in(in_desc, &buf), которая должна вернуть количество байт, предоставленных на входе, и указатель на входные данные в buf. Если в этот момент больше нет входных данных, in() должна вернуть 0 - buf в этом случае игнорируется - и inflateBack() вернет ошибку буфера. inflateBack() will call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. Функция out() должна вернуть 0 в случае успеха, или ненулевое значение в случае ошибки. Если out() вернула ненулевое значение, то inflateBack() вернет ошибку. Ни для in(), ни для out() не разрешено менять содержимое окна, предоставленного для inflateBackInit(), которое также является буфером, который использует функция out() для записи. Длина записанных данных функцией out() будет самое большее размером окна. Любое не нулевое количество входных данных может быть предоставлено в функции in().

Для удобства inflateBack() может быть обеспечена входными данными при первом вызове путем установки strm->next_in и strm->avail_in. Если входные данные опустошились, то будет вызвана функция in(). Таким образом, strm->next_in должно быть инициализировано перед вызовом inflateBack(). Если strm->next_in равно Z_NULL, то будет немедленно вызвана in() для получения входных данных. Если strm->next_in не равно Z_NULL, то также должно быть инициализировано strm->avail_in, и тогда если strm->avail_in не равно zero, то сначала входные данные будут браться из strm->next_in[0 .. strm->avail_in - 1].

Параметры in_desc и out_desc функции inflateBack() передаются в качестве первого параметра функциям in() и out() соответственно, когда они будут вызваны. Эти дескрипторы могут опционально использоваться для передачи любой информации, предоставленной вызывающим кодом, которая может понадобиться функциям in() и out() для выполнения своей работы.

При возврате inflateBack() установит strm->next_in и strm->avail_in для передачи обратно любых не использованных входных данных, которые были предоставлены последним вызовом функции in(). Возвращаемые значения inflateBack() могут быть Z_STREAM_END в случае успешного завершения, Z_BUF_ERROR если in() или out() вернули ошибку, Z_DATA_ERROR если произошла ошибка формата в потоке сжатых данных deflate (в этом случае strm->msg будет установлена для индикации причины этой ошибки), или Z_STREAM_ERROR если поток не был правильно инициализирован. В случае Z_BUF_ERROR, ошибка входа или выхода может быть распознана с использованием strm->next_in, который будет Z_NULL только если ошибку вернула функция in(). Если strm->next_in не равно Z_NULL, то Z_BUF_ERROR была причиной ненулевого возврата функции out() (in() всегда вызывается перед out(), так что strm->next_in гарантированно определено, если out() вернет ненулевое значение). Обратите внимание, что inflateBack() не может вернуть Z_OK.

ZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm));

Вся память, выделенная вызовом inflateBackInit(), будет освобождена.

В случае успеха inflateBackEnd() вернет Z_OK, или будет возвращено Z_STREAM_ERROR, если состояние потока было противоречивым.

ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void));

Вернет флаги опций времени компиляции.

Размеры типа, 2 бита на каждый, 00 соответствует 16 битам, 01 для 32 бит, 10 для 64 бит, 11 для других значений:

• 1.0: размер uInt
• 3.2: размер uLong
• 5.4: размер voidpf (указатель)
• 7.6: размер z_off_t

Опции компилятора, ассемблера и отладки:

• 8: ZLIB_DEBUG
• 9: ASMV или ASMINF - использование кода ASM
• 10: ZLIB_WINAPI - экспортируемые функции используют соглашение о вызовах WINAPI
• 11: 0 (зарезервировано)

Однократная табличная сборка (код меньше, но не потокобезопасно, если выбрана сборка с таблицей):

• 12: BUILDFIXED - сборка со статическими таблицами декодирования, когда это необходимо
• 13: DYNAMIC_CRC_TABLE - сборка с табличным вычислением CRC, когда это необходимо
• 14,15: 0 (зарезервировано)

Содержимое библиотеки (показывает отсутствующий функционал):

• 16: NO_GZCOMPRESS - функции gz* не могут сжимать (чтобы избежать линковки кода deflate, когда он не нужен)
• 17: NO_GZIP - deflate не может записывать потоки gzip, и inflate не может детектировать и декодировать потоки gzip (чтобы избежать линковки кода CRC)
• 18-19: 0 (зарезервировано)

Варианты операций (изменения в функционале библиотеки):

• 20: PKZIP_BUG_WORKAROUND - слегка более разрешающий код inflate
• 21: FASTEST - алгоритм deflate всегда только один, с самым низким уровнем компрессии
• 22,23: 0 (зарезервировано)

Вариант sprintf, используемый функцией gzprintf (0 самый лучший):

• 24: 0 = vs*, 1 = s* - 1 означает ограничение в 20 аргументов после строки формата
• 25: 0 = *nprintf, 1 = *printf - 1 означает, что gzprintf() не безопасен!
• 26: 0 = возвращает значение, 1 = void - 1 означает вывод длины возвращаемой строки

Остальные биты:

• 27-31: 0 (зарезервировано)

[Функции утилит]

Следующие функции реализованы поверх базового потоко-ориентированного набора функций. Для упрощения интерфейса подразумевается некий набор опций по умолчанию (уровень компрессии и использования памяти, стандартные функции по динамическому выделению памяти). Исходный код этих функций утилит может быть просто модифицирован, если Вам нужны какие-то специальные опции.

ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen,
                                 const Bytef *source, uLong sourceLen));

Сжимает буфер source buffer в буфер dest. Параметр sourceLen байтовая длина буфера source. На входе destLen задает общий размер буфера назначения, длина которого должна быть как минимум значение, возвращенное compressBound(sourceLen). На выходе destLen содержит реальный размер сжатых данных. Функция compress() эквивалентна compress2() с параметром level, равным Z_DEFAULT_COMPRESSION.

Функция compress вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватило памяти, Z_BUF_ERROR если было недостаточно места в выходном буфере.

ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen,
                                  const Bytef *source, uLong sourceLen,
                                  int level));

Сжимает буфер source в буфер dest. Параметр имеет тот же смысл, что и функции deflateInit. Параметр sourceLen байтовая длина буфера source. На входе destLen содержит общую длину буфера назначения dest, длина должна быть как минимум равна значению, которое возвратил вызов compressBound(sourceLen). На выходе destLen содержит реальную длину сжатых данных.

Функция compress2 вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватило памяти, Z_BUF_ERROR если не хватило места в выходном буфере, Z_STREAM_ERROR если задан недопустимый параметр level.

ZEXTERN uLong ZEXPORT compressBound OF((uLong sourceLen));

Функция compressBound() вернет верхний предел размера сжатых данных после выполнения compress() или compress2() на sourceLen байтах. Она должна использоваться перед вызовом compress() или compress2() выделением памяти под буфер назначения.

ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen,
                                   const Bytef *source, uLong sourceLen));

Распаковывает буфер source в буфер dest. Параметр sourceLen это байтовая длина буфера source. На входе destLen задает общий размер буфера назначения, который должен быть достаточно большим, чтобы вместить все распакованные данные (размер распакованных данных должен быть предварительно сохранен компрессором и передан декомпрессору неким механизмом вне области действия этой библиотеки сжатия). На выходе destLen будет содержать реальную длину распакованных данных.

Функция uncompress вернет Z_OK в случае успеха, Z_MEM_ERROR если не хватает памяти, Z_BUF_ERROR если было недостаточно места в выходном буфере, или Z_DATA_ERROR, если входные данные были повреждены или неполные. В случае, когда было недостаточно места, uncompress() заполнит выходной буфер распакованными данными, насколько хватило места.

ZEXTERN int ZEXPORT uncompress2 OF((Bytef *dest,   uLongf *destLen,
                                    const Bytef *source, uLong *sourceLen));

То же самое, что и uncompress, различие только в том, что sourceLen это указатель, где длина буфера source находится в *sourceLen. На выходе *sourceLen будет содержать количество потребленных данных.

typedef struct gzFile_s *gzFile;    /* полупрозрачный дескриптор файла gzip */

ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode));

ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode));

ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size));

ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy));

ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len));

ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems,
                                     gzFile file));

ZEXTERN int ZEXPORT gzwrite OF((gzFile file,
                                voidpc buf, unsigned len));

ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size,
                                      z_size_t nitems, gzFile file));

ZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...));

ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s));

ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len));

ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c));

ZEXTERN int ZEXPORT gzgetc OF((gzFile file));

ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file));

ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush));

ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file,
                                   z_off_t offset, int whence));

ZEXTERN int ZEXPORT gzrewind OF((gzFile file));

ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file));

ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile file));

ZEXTERN int ZEXPORT gzeof OF((gzFile file));

ZEXTERN int ZEXPORT gzdirect OF((gzFile file));

ZEXTERN int ZEXPORT gzclose OF((gzFile file));

ZEXTERN int ZEXPORT gzclose_r OF((gzFile file));
ZEXTERN int ZEXPORT gzclose_w OF((gzFile file));

ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum));

ZEXTERN void ZEXPORT gzclearerr OF((gzFile file));

ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len));

     uLong adler = adler32(0L, Z_NULL, 0);
     while (read_buffer(buffer, length) != EOF) {
       adler = adler32(adler, buffer, length);
     }
     if (adler != original_adler)
        error();

ZEXTERN uLong ZEXPORT adler32_z OF((uLong adler, const Bytef *buf,
                                    z_size_t len));

ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2,
                                          z_off_t len2));

ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len));

     uLong crc = crc32(0L, Z_NULL, 0);
     while (read_buffer(buffer, length) != EOF) {
       crc = crc32(crc, buffer, length);
     }
     if (crc != original_crc)
        error();

ZEXTERN uLong ZEXPORT crc32_z OF((uLong adler, const Bytef *buf,
                                  z_size_t len));

ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2));

ZEXTERN const char   * ZEXPORT zError           OF((int));
ZEXTERN int            ZEXPORT inflateSyncPoint OF((z_streamp z));
ZEXTERN const z_crc_t FAR * ZEXPORT get_crc_table    OF((void));
ZEXTERN int            ZEXPORT inflateUndermine OF((z_streamp, int));
ZEXTERN int            ZEXPORT inflateValidate OF((z_streamp, int));
ZEXTERN unsigned long  ZEXPORT inflateCodesUsed OF ((z_streamp));
ZEXTERN int            ZEXPORT inflateResetKeep OF((z_streamp));
ZEXTERN int            ZEXPORT deflateResetKeep OF((z_streamp));

#if (defined(_WIN32) || defined(__CYGWIN__)) && !defined(Z_SOLO)
ZEXTERN gzFile         ZEXPORT gzopen_w OF((const wchar_t *path,
                                            const char *mode));

#endif

#if defined(STDC) || defined(Z_HAVE_STDARG_H)

#  ifndef Z_SOLO
ZEXTERN int            ZEXPORTVA gzvprintf Z_ARG((gzFile file,
                                                  const char *format,
                                                  va_list va));

#  endif

#endif

[Ссылки]

1. zlib 1.2.11 Manual site:zlib.net.
2. Пример использования библиотеки zlib.