zlib——Usage Example翻译

迷南。 2022-12-07 12:29 202阅读 0赞

我们经常会遇到有关应如何使用deflate()和inflate()函数的问题。 用户想知道何时应该提供更多的输入，何时应该使用更多的输出，如何处理Z\_BUF\_ERROR，如何确保进程正确终止，等等。 因此，对于那些读过zlib.h（几次）并且想要进一步启发的人，下面是C中的一个带注释的示例，该示例使用deflate()和inflate()将输入文件压缩和解压缩为输出文件的简单例程。 注释散布在代码行之间。 因此，请在两行之间阅读。 我们希望这有助于解释zlib的某些复杂之处。事不宜迟，这是程序zpipe.c：

/* zpipe.c: example of proper use of zlib's inflate() and deflate() Not copyrighted -- provided to the public domain Version 1.4 11 December 2005 Mark Adler */
    /* Version history: 1.0 30 Oct 2004 First version 1.1 8 Nov 2004 Add void casting for unused return values Use switch statement for inflate() return values 1.2 9 Nov 2004 Add assertions to document zlib guarantees 1.3 6 Apr 2005 Remove incorrect assertion in inf() 1.4 11 Dec 2005 Add hack to avoid MSDOS end-of-line conversions Avoid some compiler warnings for input and output buffers */

现在，我们包含所需定义的头文件。 从stdio.h中，我们使用fopen，fread，fwrite，feof，ferror和fclose用于文件io，并将fputs用于错误消息。 从string.h中，我们使用strcmp进行命令行参数处理。 在assert.h中，我们使用assert宏。 从zlib.h中，我们使用基本的压缩函数deflateInit，deflate和deflateEnd，以及基本的解压缩函数inflateInit，inflate和inflateEnd。

#include <stdio.h>
    #include <string.h>
    #include <assert.h>
    #include "zlib.h"

为避免Windows / MS-DOS系统上的输入和输出数据损坏，这是一个很丑陋的技巧。 没有这些，这些系统将假定输入和输出文件是文本，并尝试将行尾字符从一种标准转换为另一种标准（Without this, those systems would assume that the input and output files are text, and try to convert the end-of-line characters from one standard to another），将破坏二进制数据，特别是将使压缩数据不可用。 这些宏定义将输入和输出设置为二进制，从而抑制行尾转换。 SET\_BINARY\_MODE将在main函数开头对stdin和stdout进行设置。

#if defined(MSDOS) || defined(OS2) || defined(WIN32) || defined(__CYGWIN__)
    # include <fcntl.h>
    # include <io.h>
    # define SET_BINARY_MODE(file) setmode(fileno(file), O_BINARY)
    #else
    # define SET_BINARY_MODE(file)
    #endif

CHUNK定义了用于向zlib例程提供数据或从zlib例程中提取数据的缓冲区大小。 较大的缓冲区大小将更有效，尤其是对于inflate来说。 如果有可用的内存，则应使用128K或256K字节大小的缓冲区。

#define CHUNK 16384

def例程将数据从输入文件压缩到输出文件。 输出数据将采用zlib格式，与gzip或zip格式不同。zlib格式有一个很小的标头，只有两个字节，可以将其标识为zlib流并提供解码信息；还有一个具有快速检查值的four-byte trailer，用于在解码后验证未压缩数据的完整性。

/* Compress from file source to file dest until EOF on source. def() returns Z_OK on success, Z_MEM_ERROR if memory could not be allocated for processing, Z_STREAM_ERROR if an invalid compression level is supplied, Z_VERSION_ERROR if the version of zlib.h and the version of the library linked do not match, or Z_ERRNO if there is an error reading or writing the files. */
    int def(FILE *source, FILE *dest, int level)
    {

这是def的局部变量。 ret将用于zlib返回代码。 flush将跟踪deflate的当前刷新状态，该状态要么不刷新，要么在到达输入文件末尾后刷新至完成。 have是从deflate返回的数据量。 strm结构用于在zlib函数之间传递信息，并保持deflate状态。 in和out是deflate的输入和输出缓冲区。

int ret, flush;
        unsigned have;
        z_stream strm;
        unsigned char in[CHUNK];
        unsigned char out[CHUNK];

我们要做的第一件事是使用deflateInit初始化zlib状态以进行压缩。这必须在首次使用deflate之前完成。在调用deflateInit之前，必须初始化strm结构中的zalloc，zfree和opaque字段。在这里，它们被设置为zlib常数Z\_NULL，以请求zlib使用默认的内存分配例程。应用程序也可以在此处选择提供自定义内存分配例程。 deflateInit将为内部状态分配256K字节。 （请参阅zlib技术详细信息。）  
deflateInit通过指向要初始化的结构和压缩级别的指针来调用，压缩级别是-1到9范围内的整数。较低的压缩级别导致执行速度更快，但压缩较少。级别越高，压缩程度越大，但执行速度越慢。 zlib常数Z\_DEFAULT\_COMPRESSION等于-1，在压缩和速度之间提供了很好的折衷，并且等效于级别6。级别0实际上根本没有压缩，并且实际上稍微扩展了数据以产生zlib格式（不是输入的逐字节副本）。 zlib的更高级应用程序可以使用deflateInit2。这样的应用程序可能希望以一定的代价减少使用多少内存。或者，可能需要请求一个gzip标头和trailer，而不是zlib标头和trailer，或者完全不包含标头或预告片的原始编码。  
我们必须对照zlib常数Z\_OK检查deflateInit的返回值，以确保它能够为内部状态分配内存，并且所提供的参数有效。 deflateInit还将检查zlib.h文件来自的zlib版本是否与实际与程序链接的zlib版本匹配。这对于zlib是共享库的环境尤其重要。  
请注意，**应用程序可以初始化多个独立的zlib流，这些流可以并行运行**。结构中维护的状态信息允许zlib例程重新进入。

/* allocate deflate state */
        strm.zalloc = Z_NULL;
        strm.zfree = Z_NULL;
        strm.opaque = Z_NULL;
        ret = deflateInit(&strm, level);
        if (ret != Z_OK)
            return ret;

外部do循环读取所有输入文件，并在到达文件末尾时退出循环底部。 此循环包含deflate的唯一调用。 因此，我们必须确保已处理完所有输入数据，并且已生成并使用了所有输出数据，然后才能退出底部的循环。

/* compress until end of file */
        do {

我们首先从输入文件中读取数据。读取的字节数直接放入avail\_in，指向这些字节的指针放入next\_in。我们还使用feof检查是否已到达输入文件的末尾。如果我们在文件末尾，则将flush设置为zlib常数Z\_FINISH，稍后将其传递给deflate，以指示这是要压缩的输入数据的最后一块。如果还没有输入结束，则将传递zlib常数Z\_NO\_FLUSH，以指示我们仍在未压缩数据的中间。  
如果从输入文件读取错误，则该过程将中止，并在返回错误之前调用deflateEnd以释放分配的zlib状态。我们不想发生内存泄漏，现在可以了吗？可以在状态初始化后的任何时间调用deflateEnd。完成后，必须调用deflateInit（或deflateInit2）来启动新的压缩过程。这里没有必要检查deflateEnd返回代码。解除分配不会失败。

strm.avail_in = fread(in, 1, CHUNK, source);
            if (ferror(source)) { 
                (void)deflateEnd(&strm);
                return Z_ERRNO;
            }
            flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
            strm.next_in = in;

内部的do循环将我们的输入数据块传递给deflate，然后继续调用deflate直到完成生成输出为止。 一旦不再有新的输出，便保证deflate已消耗所有输入，即avail\_in将为零。

/* run deflate() on input until output buffer not full, finish compression if all of source has been read in */
            do {

通过将avail\_out设置为可用输出字节数，将next\_out设置为指向该空间的指针，可以为deflate提供输出空间。

strm.avail_out = CHUNK;
                strm.next_out = out;

现在我们将压缩引擎本身称为deflate。它在next\_in占用尽可能多的avail\_in字节，并将avail\_out字节写入next\_out。然后，这些计数器和指针将更新为新的输入数据并写入输出数据。可用的输出空间量可能会限制消耗多少输入。因此，内部循环可确保每次通过提供更多输出空间来消耗所有输入。由于avail\_in和next\_in由deflate更新，因此我们不必在deflate调用之间将它们弄乱，直到它们全部用完。

deflate的参数是指向包含输入和输出信息以及内部压缩引擎状态的strm结构的指针，以及指示如何将数据刷新到输出的参数。通常，deflate会在产生任何输出（头文件除外）之前消耗数K字节的输入数据，以便积累有关数据的统计信息以获得最佳压缩效果。然后它将发出一连串的压缩数据，并在下一个突发burst之前继续消耗更多的输入。最终，必须告知deflate终止流，使用提供的输入数据完成压缩，并写出trailer检查值。只要flush参数为Z\_NO\_FLUSH，deflate将继续正常压缩。提供Z\_FINISH参数后，deflate将开始完成压缩的输出流。但是，根据提供的输出空间的多少，甚至在使用完所有输入之后，可能不得不多次调用deflate直到提供完整的压缩流为止。对于这些后续调用，flush参数必须继续为Z\_FINISH。

在更高级的应用程序中还使用了flush参数的其他值。您可以强制deflate产生一连串的输出，该输出对到目前为止提供的所有输入数据进行编码，即使没有其他情况也是如此，例如，通过压缩数据控制链接上的数据等待时间。您还可以要求deflate做到这一点，并清除到目前为止的所有历史记录，以便可以对随后的内容进行独立解压缩，例如对于随机访问应用程序。这两个请求的压缩程度都会有所降低，具体取决于发出此类请求的频率。There are other values of the flush parameter that are used in more advanced applications. You can force deflate() to produce a burst of output that encodes all of the input data provided so far, even if it wouldn’t have otherwise, for example to control data latency on a link with compressed data. You can also ask that deflate() do that as well as erase any history up to that point so that what follows can be decompressed independently, for example for random access applications. Both requests will degrade compression by an amount depending on how often such requests are made.

deflate有一个返回值，该值可以指示错误，但是我们在此不进行检查。为什么不？好吧，事实证明deflate在这里不会出错。让我们浏览一下deflate的返回值，并一一免除它们。可能的值为Z\_OK，Z\_STREAM\_END，Z\_STREAM\_ERROR或Z\_BUF\_ERROR。 Z\_OK很好。 Z\_STREAM\_END也可以，并且将在上次调用deflate时返回。这已经可以通过使用Z\_FINISH调用deflate来保证，直到没有更多输出为止。只有在未正确初始化流的情况下才可能发生Z\_STREAM\_ERROR，但我们确实对其进行了初始化。在这里检查Z\_STREAM\_ERROR并没有什么害处，例如，检查应用程序的其他部分是否无意间破坏了包含zlib状态的内存的可能性。 Z\_BUF\_ERROR将在下面进一步解释，但足以说这仅仅是deflate不能消耗更多输入或产生更多输出的指示。可以使用更多的输出空间或更多的可用输入再次调用deflate，它将在此代码中。

ret = deflate(&strm, flush);    /* no bad return value */
                assert(ret != Z_STREAM_ERROR);  /* state not clobbered */

现在我们计算上一次deflate调用提供了多少输出，这是调用之前提供了多少空间，以及调用之后仍然有多少输出空间之间的差。 然后将该数据（如果有的话）写入输出文件。 然后，我们可以将输出缓冲区重用于下一个deflate调用。 同样，如果出现文件I / O错误，我们在返回之前调用deflateEnd以避免内存泄漏。

have = CHUNK - strm.avail_out;
                if (fwrite(out, 1, have, dest) != have || ferror(dest)) { 
                    (void)deflateEnd(&strm);
                    return Z_ERRNO;
                }

重复内部do循环，直到最后一个deflate调用未能填充提供的输出缓冲区为止。然后我们知道deflate已使用提供的输入完成了尽可能多的工作，并且所有这些输入都已被消耗。然后，我们可以退出此循环并重新使用输入缓冲区。  
我们了解到deflate没有更多输出的方法是，查看它没有填充输出缓冲区，而avail\_out大于零。但是，假设deflate没有更多输出，而恰好填充了输出缓冲区！ avail\_out为零，我们不能了解到deflate已完成所有工作。我们只知道，deflate为我们提供了更多输出。因此，我们再次调用它。但是现在deflate完全不产生任何输出，并且avail\_out保持为CHUNK不变。 deflate调用无法执行任何操作，要么消耗输入，要么产生输出，因此它返回Z\_BUF\_ERROR。 但是，这根本不是问题。现在，我们终于知道deflate确实完成了，因此我们退出了内部循环，再次为deflate提供了更多输入。  
将flush设置为Z\_FINISH时，这最后一组deflate调用将完成输出流。完成此操作后，如果flush参数不是Z\_FINISH，则随后的deflate调用将返回Z\_STREAM\_ERROR，并且在状态重新初始化之前不再进行任何处理。  
zlib的某些应用程序有两个调用deflate的循环，而不是我们在此处的单个内部循环。第一个循环将在不刷新的情况下进行调用，并将所有数据送入deflate。第二个循环将调用deflate，不再使用任何数据和Z\_FINISH参数来完成该过程。从该示例可以看到，只需跟踪当前的刷新状态就可以避免这种情况。

} while (strm.avail_out == 0);
            assert(strm.avail_in == 0);     /* all input will be used */

现在，我们检查是否已经处理了所有输入文件。 该信息已保存在flush变量中，因此我们可以查看是否将其设置为Z\_FINISH。 如果是这样，那么我们就完成了，我们脱离了外部循环。 我们保证从最后一个deflate调用中获取Z\_STREAM\_END，因为我们一直运行它直到消耗完最后一个输入块并生成了所有输出。

/* done when last data in file processed */
        } while (flush != Z_FINISH);
        assert(ret == Z_STREAM_END);        /* stream will be complete */

该过程已完成，但是我们仍然需要取消分配状态以避免内存泄漏（如果您不这样做，则更像是内存泄漏）。 最后，我们可以返回满意的返回值。

/* clean up and return */
        (void)deflateEnd(&strm);
        return Z_OK;
    }

现在，我们在inf例程中对减压执行相同的操作。 inf从输入文件中解压缩希望是有效的zlib流，并将未压缩的数据写入输出文件。 上面关于def的大部分讨论也适用于inf，因此这里的讨论将集中在两者之间的差异上。

/* Decompress from file source to file dest until stream ends or EOF. inf() returns Z_OK on success, Z_MEM_ERROR if memory could not be allocated for processing, Z_DATA_ERROR if the deflate data is invalid or incomplete, Z_VERSION_ERROR if the version of zlib.h and the version of the library linked do not match, or Z_ERRNO if there is an error reading or writing the files. */
    int inf(FILE *source, FILE *dest)
    {

局部变量具有与def相同的功能。 唯一的区别是没有刷新变量，因为inflate可以从zlib流本身判断出流何时完成。

int ret;
        unsigned have;
        z_stream strm;
        unsigned char in[CHUNK];
        unsigned char out[CHUNK];

状态的初始化是相同的，只是没有压缩级别，并且结构体strm的另外两个元素也已初始化。 avail\_in和next\_in必须在调用inflateInit之前初始化。 这是因为应用程序可以选择提供zlib流的开始，以便inflateInit可以访问有关压缩方法的信息以帮助进行内存分配。 在zlib的当前实现中（直到1.2.x版），无论如何，依赖于方法的内存分配都会推迟到inflate的第一次调用。 但是，必须初始化这些字段，因为提供更多压缩方法的更高版本的zlib可能会利用此接口。 无论如何，inflateInit都不会执行解压缩，因此在调用之前不需要初始化avail\_out和next\_out字段。此处avail\_in设置为零，next\_in设置为Z\_NULL以指示未提供输入数据。

/* allocate inflate state */
        strm.zalloc = Z_NULL;
        strm.zfree = Z_NULL;
        strm.opaque = Z_NULL;
        strm.avail_in = 0;
        strm.next_in = Z_NULL;
        ret = inflateInit(&strm);
        if (ret != Z_OK)
            return ret;

外部do循环对输入进行解压缩，直到inflate指示其已到达压缩数据的末尾并产生了所有未压缩的输出。 这与处理所有输入文件的def相反。 如果在压缩数据自我终止之前到达文件末尾，则压缩数据不完整，并返回错误。

/* decompress until deflate stream ends or end of file */
        do {

我们读取输入数据并相应地设置strm结构。 如果到达输入文件的末尾，则由于压缩的数据不完整，因此我们将离开外部循环并报告错误。 请注意，如果输入文件继续经过zlib流，则我们读取的数据可能比inflate最终消耗的数据更多。 对于将zlib流嵌入到其他数据中的应用程序，将需要修改此例程以返回未使用的数据，或者至少指示未使用多少输入数据，因此该应用程序将知道在zlib之后取走的位置流。

strm.avail_in = fread(in, 1, CHUNK, source);
            if (ferror(source)) { 
                (void)inflateEnd(&strm);
                return Z_ERRNO;
            }
            if (strm.avail_in == 0)
                break;
            strm.next_in = in;

内部的do循环具有与def中相同的功能，该功能是继续调用inflate，直到使用提供的输入生成了所有可以输出的输出为止。

/* run inflate() on input until output buffer not full */
            do {

内部的do循环具有与def中相同的功能，该功能是继续调用inflate，直到使用提供的输入生成了所有可以输出的输出为止。

strm.avail_out = CHUNK;
                strm.next_out = out;

现在，我们运行减压引擎本身。由于zlib格式是自终止的，因此无需调整flush参数。这里的主要区别在于，我们需要注意一些返回值。 Z\_DATA\_ERROR表示inflate检测到zlib压缩数据格式中的错误，这意味着该数据不是开头的zlib流，或者自压缩以来该数据在途中已损坏。另一个要处理的错误是Z\_MEM\_ERROR，它可能会发生，因为内存分配被延迟到inflate需要它为止，而不同于deflate，后者的内存是由deflateInit开始分配的。  
高级应用程序可以使用deflateSetDictionary对一组可能的数据进行deflate初始化，以改善前32K左右的压缩率。这在zlib标头中已注明，因此inflate要求在提供该字典开始解压缩之前提供该字典。如果没有字典，则无法正确解压缩。对于此例程，我们不知道字典是什么，因此Z\_NEED\_DICT指示转换为Z\_DATA\_ERROR。  
inflate也可以返回Z\_STREAM\_ERROR，这在这里应该是不可能的，但是可以像上面为def所述进行检查。出于检查def的相同原因，此处不需要检查Z\_BUF\_ERROR。Z\_STREAM\_END将在以后检查。

ret = inflate(&strm, Z_NO_FLUSH);
                assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
                switch (ret) { 
                case Z_NEED_DICT:
                    ret = Z_DATA_ERROR;     /* and fall through */
                case Z_DATA_ERROR:
                case Z_MEM_ERROR:
                    (void)inflateEnd(&strm);
                    return ret;
                }

inflate的输出与deflate的输出相同。

have = CHUNK - strm.avail_out;
                if (fwrite(out, 1, have, dest) != have || ferror(dest)) { 
                    (void)inflateEnd(&strm);
                    return Z_ERRNO;
                }

当inflate没有更多输出时（如不填充输出缓冲区所示），内部do循环结束，就像deflate一样。 在这种情况下，我们不能断言strm.avail\_in为零，因为deflate流可能在文件之前结束。

} while (strm.avail_out == 0);

当inflate报告已到达输入zlib流的末尾，已完成解压缩和完整性检查并已提供所有输出时，外部do循环结束。 这由inflate返回值Z\_STREAM\_END指示。 如果读取的输入文件的最后一块包含zlib流的末尾，则确保内部循环将ret等于Z\_STREAM\_END。 因此，如果返回值不是Z\_STREAM\_END，则循环将继续读取更多输入。

/* done when inflate() says it's done */
        } while (ret != Z_STREAM_END);

此时，解压缩成功完成，或者由于输入文件中没有更多数据而使我们退出了循环。 如果最后一个inflate返回值不是Z\_STREAM\_END，则zlib流不完整，并返回数据错误。 否则，我们将返回满意的返回值。 当然，首先调用inflateEnd以避免内存泄漏。

/* clean up and return */
        (void)inflateEnd(&strm);
        return ret == Z_STREAM_END ? Z_OK : Z_DATA_ERROR;
    }

这样就结束了直接使用zlib的例程。 下面的例程通过从上述stdin到stdout的例程来运行数据，并处理def或inf报告的任何错误，从而使该例程成为命令行程序。  
zerr（）用于解释def（）和inf（）中可能的错误代码，如上面的注释中所述，并打印出错误消息。 请注意，这些只是deflate（）和inflate（）可能返回值的子集。

/* report a zlib or i/o error */
    void zerr(int ret)
    { 
        fputs("zpipe: ", stderr);
        switch (ret) { 
        case Z_ERRNO:
            if (ferror(stdin))
                fputs("error reading stdin\n", stderr);
            if (ferror(stdout))
                fputs("error writing stdout\n", stderr);
            break;
        case Z_STREAM_ERROR:
            fputs("invalid compression level\n", stderr);
            break;
        case Z_DATA_ERROR:
            fputs("invalid or incomplete deflate data\n", stderr);
            break;
        case Z_MEM_ERROR:
            fputs("out of memory\n", stderr);
            break;
        case Z_VERSION_ERROR:
            fputs("zlib version mismatch!\n", stderr);
        }
    }

这是用于测试def（）和inf（）的main（）例程。 如果未提供任何参数，则zpipe命令只是从stdin到stdout的压缩管道，如果使用zpipe -d，则它是一个解压缩管道。 如果提供任何其他参数，则不执行压缩或解压缩。 而是显示用法消息。 示例包括zpipe <foo.txt> foo.txt.z进行压缩，以及zpipe -d <foo.txt.z> foo.txt进行解压缩。

/* compress or decompress from stdin to stdout */
    int main(int argc, char **argv)
    { 
        int ret;
    
        /* avoid end-of-line conversions */
        SET_BINARY_MODE(stdin);
        SET_BINARY_MODE(stdout);
    
        /* do compression if no arguments */
        if (argc == 1) { 
            ret = def(stdin, stdout, Z_DEFAULT_COMPRESSION);
            if (ret != Z_OK)
                zerr(ret);
            return ret;
        }
    
        /* do decompression if -d specified */
        else if (argc == 2 && strcmp(argv[1], "-d") == 0) { 
            ret = inf(stdin, stdout);
            if (ret != Z_OK)
                zerr(ret);
            return ret;
        }
    
        /* otherwise, report usage */
        else { 
            fputs("zpipe usage: zpipe [-d] < source > dest\n", stderr);
            return 1;
        }
    }

使用系统中的zlib库来编译该代码，并使用文件进行测试

gcc -l /usr/include -lz -o zpipe zpipe.c
    cat sample.txt | ./zpipe > sample.txt.zlib
    cat sample.txt.zlib | ./zpipe -d > sample.txt.zlib.raw

参考：http://www.zlib.net/zlib\_how.html