zlib 1.2.11 Manual | pc

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

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

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

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

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

Библиотека компрессии 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.

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

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

Приложение должно обновлять 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()).

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

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

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

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

Инициализирует внутреннее состояние потока для компрессии. Перед вызовом 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().

Функция 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() может быть вызвана снова с предоставлением дополнительного количества входных данных или места под выходные данные, чтобы компрессия продолжилась.

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

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

Инициализирует внутреннее состояние потока для декомпрессии. Поля 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().

Функция 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(), чтобы увидеть хороший блок сжатых данных, если сделана попытка частичного восстановления данных.

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

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

Это другая версия 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().

Инициализирует словарь сжатия из заданной последовательности байт без генерации каких-либо выходных сжатых данных. Эта функция должна быть вызвана сразу после 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().

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

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

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

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

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

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

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

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

Динамически обновляет уровень сжатия и стратегию компрессии. Интерпретация параметров 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() может быть вызвана снова с дополнительно предоставленным местом под выходные данные.

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

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

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

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

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

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

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

Функция 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 если исходный поток был противоречивым.

Это другая версия 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().

Инициирует словарь декомпрессии из указанной последовательности несжатых байт. Эта функция должна быть вызвана немедленно после вызова 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().

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

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

Пропускает неправильные сжатые данные, пока не будет найдена точка полной выгрузки (см. выше описание функции 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, каждый раз предоставляя дополнительные входные данные, пока не добьется успеха или не дойдет до конца входных данных.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функция 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 если исходный поток был противоречивым.

Инициализирует внутреннее состояние потока для декомпрессии с использованием вызова 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.

Функция 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.

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

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

Размеры типа, 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 означает вывод длины возвращаемой строки

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

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

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

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

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

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

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

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

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

Файловые функции gzip

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

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

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

Открывает файл gzip (.gz) для чтения или записи. Параметр mode как у fopen ("rb" или "wb"), но он также может включать уровень сжатия ("wb9") или стратегию: 'f' для фильтрованных данных ("wb6f"), 'h' для компрессии только по Хаффману ("wb1h"), 'R' для кодирования по типу run-length/RLE ("wb1R"), или 'F' для fixed code compression ("wb9F"). Подробности по параметру стратегии см. в описании deflateInit2. 'T' запрашивает прозрачную запись или добавление без сжатия и без использования формата gzip.

Атрибут 'a' может использоваться вместо 'w', чтобы сделать запрос добавления потока gzip, чтобы он был записан добавлением к существующему файлу. '+' приведет к ошибке, поскольку чтение и запись одного и того же файла gzip не поддерживается. Добавление 'x' при записи приведет к исключительному созданию файла, которое приведет к сбою операции, если файл уже существует. На операционных системах, которые это поддерживают, добавление 'e' при чтении или записи установит флаг для закрытия файла при вызове execve().

Эти функции, как и gzip, будут читать и декодировать последовательность потоков gzip в файл. Функция добавления gzopen() может использоваться для создания такого файла (также см. gzflush() для другого способа создания файла). При добавлении gzopen не проверяет, начинается ли файл с потока gzip, и не ищет конец потоков gzip для начала добавления. Функция gzopen будет просто добавлять поток gzip к существующему файлу.

Функция gzopen может использоваться для чтения файла, который не формате gzip; в этом случае gzread будет делать простое чтение файла без декомпрессии. При чтении это будет определяться автоматически путем просмотра на наличия магической двухбайтной сигнатуры заголовка gzip.

Функция gzopen вернет NULL, если файл не может быть открыт, если было недостаточно памяти для выделения состояния gzFile, или если указан недопустимый режим (не были предоставлены 'r', 'w' или 'a', или был указан '+'). Значение errno может быть проверено, чтобы определить причину сбоя gzopen, когда файл нельзя было открыть.

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

Функция gzdopen() связывает gzFile с дескриптором файла fd. Дескрипторы файла получаются из вызовов наподобие open, dup, creat, pipe или fileno (в файле, который был ранее открыт вызовом fopen). Параметр mode тот же, что и у gzopen. Следующий вызов gzclose на возвращенном gzFile также закроет файловый дескриптор fd, точно так же, как fclose(fdopen(fd), mode) закроет файловый дескриптор fd. Если Вы хотите сохранить fd открытым, то используйте fd = dup(fd_keep); gz = gzdopen(fd, mode);. Дубликат дескриптора должен быть сохранен во избежание утечки памяти, поскольку gzdopen не закроет fd если на нем произошел отказ. Если Вы используете fileno() для получения дескриптора файла из FILE *, то Вы должны будете использовать dup(), чтобы избежать двойного закрытия дескриптора файла. Обе функции gzclose() и fclose() закроют связанный с ними дескриптор файла, так что у них должны быть разные дескрипторы файлов.

Функция gzdopen вернет NULL, если было недостаточно памяти для выделения под состояние gzFile, если было указан недопустимый режим mode (не были предоставлены 'r', 'w' или 'a', или был указан '+'), или если fd равен –1. Дескриптор файла не используется, пока не будет произведена следующая операция gz* read, write, seek или close operation, так что gzdopen не определит, что fd недопустимый (кроме ситуации, когда fd равен –1).

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

Установит внутренний размер буфера, используемый функциями этой библиотеки. Размер буфера по умолчанию составляет 8192 байт. Эта функция должна быть вызвана после gzopen() или gzdopen(), и перед любым вызовом других функций, которые читают или записывают файл. Выделение буфера памяти всегда откладывается до момента первого чтения или записи. Увеличенный размер буфера, например 64K или 128K значительно повышает скорость декомпрессии (чтение).

Новый размер буфера также влияет на максимальную длину для gzprintf().

Функция gzbuffer() возвратит 0 в случае успеха, или –1 в случае ошибки, например если вызов был осуществлен слишком поздно.

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

Динамически обновляет уровень компрессии level или стратегию сжатия strategy. См. описание deflateInit2 для понимания смысла этих параметров. Ранее предоставленные данных сбрасываются на диск перед тем, как параметры будут изменены.

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

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

Читает указанное количество распакованных данных из сжатого файла архива. Если входной файл не имеет формат gzip, функция gzread копирует указанное количество байт в буфер напрямую из файла, без распаковки.

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

Функция gzread может использоваться для чтения файла gzip, который одновременно записывается. При достижении конца ввода gzread сделает возврат с доступными данными. Если будет возвращен код ошибки из функции gzerror, равный Z_OK или Z_BUF_ERROR, то функция gzclearerr может использоваться для очистки индикатора конца файла, чтобы разрешить повторную попытку использования gzread. Z_OK показывает, что поток gzip было завершен на последнем gzread. Z_BUF_ERROR показывает, что входной файл закончился посередине потока gzip. Обратите внимание, что gzread не возвращает –1 при событии неполного потока gzip. Эта ошибка откладывается на момент вызова gzclose(), которая вернет Z_BUF_ERROR, если последний gzread закончился посередине потока gzip. Альтернативно gzerror может использоваться перед gzclose, чтобы определить этот случай.

Функция gzread вернет количество реально прочитанных распакованных данных, меньшее, чем длина файла, когда он прочитан до конце, или –1 в случае ошибки. Если len слишком большое, чтобы поместиться в тип int, то ничего не будет прочитано, будет возвращено значение –1, и состояние ошибки будет установлено в Z_STREAM_ERROR.

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

Читает до nitems элементов размера size из файла в буфер buf, иначе работает так же, как и gzread(). Это дублирует интерфейс stdio fread(), с запросом size_t и возвращаемыми типами. Если библиотека определяет size_t, то z_size_t идентично size_t. Если нет, то z_size_t это тип unsigned int, который содержит указатель.

Функция gzfread() вернет количество полных прочитанных элементов размером size, или 0, если был достигнут конец файла, и не может быть полностью прочитан элемент, или если произошла ошибка. Должна использоваться функция gzerror(), если был возвращен 0, чтобы определить, была ли ошибка. Если перемножение size и nitems даст переполнение, например результат не укладывается в z_size_t, то ничего не будет прочитано, будет возвращен 0, и состояние ошибки будет установлено в Z_STREAM_ERROR.

При событии, когда был достигнут конец файла, и в конце была доступна только часть элемента, например длина оставшихся не сжатых данных не делится нацело на size, то последний частично прочитанный элемент все-таки будет сохранен в buf, и будет установлен флаг конца файла (end-of-file, EOF). Длина частично прочитанного элемента не предоставляется, но может быть выведен из результата gztell(). Это поведение то же самое, что и реализация fread() обычных библиотек, но это предотвращает использование gzfread() для чтения параллельно записываемого файла, со сбросом и попыткой повтора при достижении EOF, когда size не равно 1.

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

Записывает указанное количество несжатых байт в файл архива. Функция gzwrite вернет количество реально записанных несжатых байт, или вернет 0 в случае ошибки.

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

Функция gzfwrite() запишет nitems элементов размера size из буфера buf в файл file, дублируя интерфейс stdio-функции fwrite(), к запросом size_t и возвратом типов. Если библиотека определяет size_t, то z_size_t идентично size_t. Если нет, то z_size_t это тип unsigned int, который содержит указатель.

Функция gzfwrite() вернет количество полных записанных элементов, размера size, или 0, если произошла ошибка. Если произведение size на nitems приведет к переполнению, например если результат не укладывается в z_size_t, то ничего не будет записано, будет возвращен 0, и состояние ошибки установится в Z_STREAM_ERROR.

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

Преобразует, форматирует и записывает аргументы в сжатый файл под управлением формата format, точно так же, как это делает стандартная функция fprintf. Функция gzprintf вернет количество несжатых байт, которые реально были записаны, или отрицательный код ошибки zlib, если произошла ошибка. Количество несжатых данных ограничивается значением 8191, или значением, на 1 меньше значения, которое дает gzbuffer(). Вызывающий код должен гарантировать, что этот лимит не будет превышен. Если лимит превышен, то gzprintf() вернет ошибку (0), и ничего при этом не запишет. В таком случае может произойти переполнение буфера с непредсказуемым результатом, что может быть только если zlib была скомпилирована с небезопасными функциями sprintf() или vsprintf(), потому что безопасные функции snprintf() или vsnprintf() были недоступны. Это можно определить вызовом функции zlibCompileFlags().

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

Записывает указанную ASCIIZ-строку в файл архива, исключая завершающий нулевой символ. Вернет количество записанных символов, или –1 в случае ошибки.

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

Читает байты из файла архива, пока не будет прочитано len-1 символов или пока не будет прочитан и передан в буфер buf символ конца строки, или пока не произойдет событие достижения конца файла. Если прочитано любое количество символов, или если len == 1, то строка завершается нулевым символом. Если не было прочитано ни одного символа из-за конца файла, или если len < 1, то содержимое буфера не будет изменено.

Функция gzgets вернет buf со строкой ASCIIZ, или вернет NULL при достижении конца файла или в случае ошибки. Если произошла ошибка, то содержимое buf будет неопределенным.

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

Запишет в файл архива значение c, преобразованное в unsigned char. Вернет записанное значение, или –1 в случае ошибки.

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

Прочитает 1 байт из файла архива. Вернет этот байт, или –1 в случае достижения конца файла или если произошла ошибка. Для ускорения работы эта функция реализована в виде макроса. Таким образом, это не делает всех проверок, которые делают другие функции. Например, не проверяется, что file равен NULL, ни проверяется структура файла на предмет его повреждения.

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

Выталкивает один символ обратно в поток на чтение как первого символа для следующего чтения. Как минимум разрешается 1 символ для такой операции push-back. Функция gzungetc() вернет проталкиваемый символ, или –1 в случае ошибки. Функция gzungetc() потерпит отказ, если c равен –1, и также может произойти отказ, если символ протолкнулся, но пока не был прочитан обратно. Если gzungetc используется сразу после gzopen или gzdopen, то разрешается проталкивание как минимум количество символов размера выходного буфера (см. описание функции gzbuffer, приведенное ранее). Проталкиваемый символ будет отброшен, если текущая позиция в потоке меняется функциями gzseek() или gzrewind().

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

Сбрасывает в файл архива все ожидающие вывода данные. Параметр flush такой же, как и у функции deflate(). Возвращаемое значение - номер ошибки zlib (см. далее описание функции gzerror). Функция gzflush разрешена только если файл открыт на запись.

Если параметр flush равен Z_FINISH, то оставшиеся данные записываются и поток gzip завершается на выходе. Если снова вызвать gzwrite(), то на выходе будет запущен новый поток gzip. Для чтения таких склеенных потоков gzip может использоваться функция gzread().

Функция gzflush должна вызываться только если на это есть жесткая необходимость потому что слишком частый вызов приведет к ухудшению качества сжатия.

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

Устанавливает начальную позицию для следующего вызова gzread или gzwrite на указанном файле архива. Параметр смещения offset задает количество байт в распакованном потоке данных. Таким образом, этот параметр определен так же, как и lseek(2); значение SEEK_END не поддерживается.

Если файл открыт для чтения, эта функция эмулируется, но работает экстремально медленно. Если файл открыт для записи, то поддерживается только позиционирование вперед; тогда gzseek сжимает последовательность нулей до новой начальной позиции.

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

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

Отматывает в начало позицию чтения указанного файла. Эта функция поддерживается только для чтения. Функция gzrewind(file) эквивалентна (int)gzseek(file, 0L, SEEK_SET).

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

Возвращает начальную позицию следующего gzread или gzwrite на указанном файле архива. Эта позиция представлена количеством байт несжатого потока, и равна 0 в его начале, даже если используется добавление или чтение потока gzip от середины файла с помощью использования функции gzdopen().

Функция gztell(file) эквивалентна gzseek(file, 0L, SEEK_CUR).

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

Вернет текущее смещение в файле, который записывается или считывается. Это смещение включает количество байт, которое предшествует потоку gzip, например когда к одному потоку gzip добавляется другой поток gzip, или когда используется gzdopen() для чтения. При чтении смещение не включает пока не используемый буферизированный ввод. Эта информация может использоваться как прогресс-индикатор. При ошибке gzoffset() возвратит –1.

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

Вернет true (1), если был установлен индикатор конца файла при чтении, иначе будет возвращено false (0). Обратите внимание, что индикатор конца файла (end-of-file, EOF) устанавливается только если была попытка чтения за конец входных данных. Таким образом, только наподобие feof(), gzeof() может вернуть false, даже если нет больше данных для чтения, при событии запроса последнего чтения точного количества байт, оставшихся на входном файле. Это произойдет только если размер входного файла точно делится на размер буфера.

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

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

Вернет true (1), если файл при чтении копируется напрямую, или false (0), если распаковывается поток gzip.

Если входной файл пустой, то gzdirect() вернет true, поскольку вход не содержит поток gzip.

Если gzdirect() используется сразу после gzopen() или gzdopen(), то это приведет к выделению буферов, что позволит прочитать файл, чтобы определить, является ли он архивом gzip. Таким образом, если используется gzbuffer(), то это должно быть вызвано перед gzdirect().

При записи gzdirect() вернет true (1), если запрашивалась прозрачная запись ("wT" было указано для gzopen() mode), или иначе false (0) (имейте в виду: gzdirect() не нужна при записи. Прозрачная запись должна быть запрошена явно, так что приложение всегда знает ответ. При статической линковке использование gzdirect() подключит весь код zlib для чтения и декомпрессии файла gzip, что может быть нежелательным).

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

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

Функция gzclose вернет Z_STREAM_ERROR если файл неправильный, Z_ERRNO в случае ошибки операции с файлом, Z_MEM_ERROR если недостаточно памяти, Z_BUF_ERROR если последнее чтение было закончено посередине потока gzip, или Z_OK в случае успешного завершения.

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

То же самое, что и gzclose(), но gzclose_r() используется только когда файл читается, и gzclose_w() используется только когда файл записывается, или к нему добавляется поток сжатия. Достоинство использования от этих функций вместо gzclose() в том, что это позволяет избежать линковки кода компрессии или декомпрессии zlib, когда что-то из этого не требуется для использования (например, когда используется только чтение или запись соответственно). Если используется gzclose(), то в приложение все равно линкуется весь код, и компрессии и декомпрессии, когда zlib линкуется статически.

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

Возвратит код ошибки, которая случилась последней на указанном файле архива. Значение по указателю errnum устанавливается в номер ошибки zlib. Если произошла ошибка файловой системы, не относящаяся к библиотеки компрессии, то errnum установится в Z_ERRNO, и приложение может проконсультироваться с errno для получения точного кода ошибки.

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

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

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

Очищает ошибку и флаги end-of-file для файла file. Это работает аналогично функции clearerr() из набора stdio, что полезно для того, чтобы продолжить чтение файла, который одновременно еще и записывается.