Les premiers pas

La base de zlib repose les fonctions deflate() et inflate(). Les utilisateurs se demandent quand ils doivent fournir plus d'entrées, quand ils doivent utiliser plus de sorties, que faire avec une Z_BUF_ERROR, comment s'assurer que le processus se termine correctement,... Voici un exemple annoté en C de routines simples pour compresser et décompresser d'un fichier d'entrée vers un fichier de sortie en utilisant respectivement deflate() et inflate(). Les annotations sont intercalées entre les lignes du code. Veuillez donc lire entre les lignes. Nous espérons que cela vous aidera à comprendre certaines des subtilités de zlib.

Sans plus attendre, voici le programme zpipe.c traduit en français :

Nous incluons maintenant les fichiers d'entête pour les définitions requises. Depuis stdio.h, nous utilisons fopen(), fread(), fwrite(), feof(), ferror() et fclose() pour les entrées/sorties de fichiers et fputs() pour les messages d'erreur. Depuis string.h, nous utilisons strcmp() pour le traitement des paramètres de la ligne de commande. Depuis assert.h, nous utilisons la macro assert(). Depuis zlib.h, nous utilisons les fonctions de compression de base deflateInit(), deflate() et deflateEnd(), ainsi que les fonctions de décompression de base inflateInit(), inflate() et inflateEnd().

Il s'agit d'un hack malicieux nécessaire pour éviter la corruption des données d'entrée et de sortie sur les systèmes Windows/MS-DOS. Sans cela, ces systèmes supposeraient que les fichiers d'entrée et de sortie sont du texte et essaieraient de convertir les caractères de fin de ligne d'un standard à un autre. Cela corrompra les données binaires et, en particulier, rendrait les données compressées inutilisables. Cela définit l'entrée et la sortie en binaire, ce qui supprime les conversions de fin de ligne. SET_BINARY_MODE() sera utilisé plus tard sur stdin et stdout, au début de main() :

CHUNK est simplement la taille du tampon pour alimenter et extraire les données des routines zlib. Des tailles de tampon plus grandes seraient plus efficaces, en particulier pour inflate(). Si la mémoire est disponible, des tailles de tampon de l'ordre de 128 Ko ou 256 Ko doivent être utilisées.

La routine def() compresse les données d'un fichier d'entrée vers un fichier de sortie. Les données de sortie seront au format zlib, étant différent des formats gzip ou zip. Le format zlib possède un très petit entête de seulement deux octets pour l'identifier comme un flux zlib et pour fournir des informations de décodage, ainsi qu'une fin de bande de quatre octets avec une valeur de contrôle rapide pour vérifier l'intégrité des données non compressées après le décodage.

Voici les variables locales pour def(). ret sera utilisé pour les codes de retour zlib. flush gardera une trace de l'état de vidage actuel pour deflate(), étant soit aucun vidage, soit un vidage complet une fois la fin du fichier d'entrée atteinte. have est la quantité de données renvoyées par deflate(). La structure strm est utilisée pour transmettre des informations vers et depuis les routines zlib, et pour maintenir l'état deflate(). in et out sont les tampons d'entrée et de sortie pour deflate().

La première chose que nous faisons est d'initialiser l'état zlib pour la compression en utilisant deflateInit(). Cela doit être fait avant la première utilisation de deflate(). Les champs zalloc, zfree et opaque dans la structure strm doivent être initialisés avant d'appeler deflateInit(). Ici, ils sont définis sur la constante zlib Z_NULL pour demander que zlib utilise les routines d'allocation de mémoire par défaut. Une application peut également choisir de fournir ici des routines d'allocation de mémoire personnalisées. deflateInit() allouera de l'ordre de 256 Ko pour l'état interne.

deflateInit() est appelé avec un pointeur vers la structure à initialiser et le niveau de compression, étant un entier compris entre -1 et 9. Des niveaux de compression inférieurs entraînent une exécution plus rapide, mais une compression moindre. Des niveaux plus élevés entraînent une compression plus importante, mais une exécution plus lente. La constante zlib Z_DEFAULT_COMPRESSION, égale à -1, offre un bon compromis entre compression et vitesse et est équivalente au niveau 6. Le niveau 0 ne fait en réalité aucune compression et étend en fait légèrement les données pour produire le format zlib (il ne s'agit pas d'une copie octet par octet de l'entrée). Les applications zlib plus avancées peuvent ici utiliser deflateInit2(). Une telle application peut vouloir réduire la quantité de mémoire étant utilisée, à un certain prix en termes de compression. Ou elle peut avoir besoin de demander un entête et une bande-annonce gzip au lieu d'un entête et d'une bande-annonce zlib, ou un codage brut sans entête ni bande-annonce du tout.

Nous devons vérifier la valeur de retour de deflateInit() par rapport à la constante zlib Z_OK pour nous assurer qu'elle a pu allouer de la mémoire pour l'état interne et que les arguments fournis étaient valides. deflateInit() vérifiera également que la version de zlib d'où provient le fichier zlib.h correspond à la version de zlib réellement liée au programme. Ceci est particulièrement important pour les environnements dans lesquels zlib est une bibliothèque partagée.

Notez qu'une application peut initialiser plusieurs flux zlib indépendants, qui peuvent fonctionner en parallèle. Les informations d'état conservées dans la structure permettent aux routines zlib d'être réentrantes.

Maintenant que les choses sérieuses sont faites, nous pouvons passer aux choses sérieuses. La boucle externe lit tout le fichier d'entrée et sort en bas de la boucle une fois la fin du fichier atteinte. Cette boucle contient le seul appel de deflate(). Nous devons donc nous assurer que toutes les données d'entrée ont été traitées et que toutes les données de sortie ont été générées et consommées avant de sortir de la boucle en bas.

Nous commençons par lire les données du fichier d'entrée. Le nombre d'octets lus est placé directement dans avail_in, et un pointeur vers ces octets est placé dans next_in. Nous vérifions également si la fin du fichier sur l'entrée a été atteinte en utilisant feof(). Si nous sommes à la fin du fichier, flush est défini sur la constante zlib Z_FINISH, étant ensuite passée à deflate() pour indiquer qu'il s'agit du dernier bloc de données d'entrée à compresser. Si nous ne sommes pas encore à la fin de l'entrée, la constante zlib Z_NO_FLUSH sera passée à deflate pour indiquer que nous sommes toujours au milieu des données non compressées.

S'il y a une erreur lors de la lecture du fichier d'entrée, le processus est interrompu et deflateEnd() est appelé pour libérer l'état zlib alloué avant de renvoyer l'erreur. Nous ne voudrions pas de fuite de mémoire, n'est-ce pas ? deflateEnd() peut être appelé à tout moment après l'initialisation de l'état. Une fois cela fait, deflateInit() (ou deflateInit2()) devra être appelé pour démarrer un nouveau processus de compression. Il n'y a aucun intérêt ici à vérifier le code de retour deflateEnd(). La désallocation ne peut pas échouer.

La boucle interne transmet notre bloc de données d'entrée à deflate(), puis continue d'appeler deflate() jusqu'à ce qu'elle ait fini de produire une sortie. Une fois qu'il n'y a plus de nouvelle sortie, deflate() est assuré d'avoir consommé toute l'entrée, c'est-à-dire que avail_in sera nul.

L'espace de sortie est fourni à deflate() en définissant avail_out sur le nombre d'octets de sortie disponibles et next_out sur un pointeur vers cet espace.

Nous appelons maintenant le moteur de compression lui-même, deflate(). Il prend autant d'octets avail_in dans next_in qu'il peut traiter et écrit autant d'octets avail_out dans next_out. Ces compteurs et pointeurs sont ensuite mis à jour après la consommation des données d'entrée et l'écriture des données de sortie. C'est la quantité d'espace de sortie disponible pouvant limiter la quantité d'entrée consommée. D'où la boucle interne pour s'assurer que toutes les entrées sont consommées en fournissant plus d'espace de sortie à chaque fois. Étant donné que avail_in et next_in sont mis à jour par deflate(), nous n'avons pas à les manipuler entre les appels deflate() jusqu'à ce qu'ils soient tous utilisés.

Les paramètres de deflate() sont un pointeur vers la structure strm contenant les informations d'entrée et de sortie et l'état interne du moteur de compression, et un paramètre indiquant si et comment vider les données vers la sortie. Normalement, deflate consommera plusieurs K octets de données d'entrée avant de produire une sortie (à l'exception de l'entête), afin d'accumuler des statistiques sur les données pour une compression optimale. Il émettra ensuite une salve de données compressées et continuera à consommer plus d'entrées avant la salve suivante. Finalement, il faut dire à deflate() de terminer le flux, de terminer la compression avec les données d'entrée fournies et d'écrire la valeur de contrôle de la remorque. deflate() continuera à compresser normalement tant que le paramètre de vidage est Z_NO_FLUSH. Une fois le paramètre Z_FINISH fourni, deflate() commencera à terminer le flux de sortie compressé. Cependant, en fonction de la quantité d'espace de sortie fourni, deflate() peut devoir être appelé plusieurs fois jusqu'à ce qu'il ait fourni le flux compressé complet, même après avoir consommé toutes les entrées. Le paramètre de vidage doit continuer à être Z_FINISH pour ces appels ultérieurs.

Il existe d'autres valeurs du paramètre de vidage étant utilisées dans des applications plus avancées. Vous pouvez forcer deflate() à produire une salve de sortie encodant toutes les données d'entrée fournies jusqu'à présent, même si cela n'aurait pas été le cas autrement, par exemple pour contrôler la latence des données sur une liaison avec des données compressées. Vous pouvez également demander à deflate() de faire cela ainsi que d'effacer tout historique jusqu'à ce point afin que ce qui suit puisse être décompressé indépendamment, par exemple pour les applications à accès aléatoire. Les deux requêtes dégraderont la compression d'un montant dépendant de la fréquence de ces requêtes.

deflate() a une valeur de retour pouvant indiquer des erreurs, mais nous ne la vérifions pas ici. Pourquoi pas ? Eh bien, il s'avère que deflate() ne peut pas faire d'erreur ici. Examinons les valeurs de retour de deflate() et éliminons-les une par une. Les valeurs possibles sont Z_OK, Z_STREAM_END, Z_STREAM_ERROR ou Z_BUF_ERROR. Z_OK signifie correcte et que donc tout c'est bien passé. Z_STREAM_END est également un équivalent de ok et sera renvoyé pour le dernier appel de deflate(). Ceci est déjà garanti en appelant deflate() avec Z_FINISH jusqu'à ce qu'il n'y ait plus de sortie. Z_STREAM_ERROR n'est possible que si le flux n'est pas initialisé correctement, mais nous l'avons initialisé correctement. Il n'y a aucun mal à vérifier ici Z_STREAM_ERROR, par exemple pour vérifier la possibilité qu'une autre partie de l'application ait par inadvertance écrasé la mémoire contenant l'état zlib. Z_BUF_ERROR sera expliqué plus loin, mais il suffit de dire que c'est simplement une indication que deflate() n'a pas pu consommer plus d'entrées ou produire plus de sorties. deflate() peut être appelé à nouveau avec plus d'espace de sortie ou plus d'entrées disponibles, ce qui sera le cas dans ce code.

Nous calculons maintenant la quantité de sortie fournie par deflate() lors du dernier appel, ce qui correspond à la différence entre la quantité d'espace fournie avant l'appel et la quantité d'espace de sortie encore disponible après l'appel. Ensuite, ces données, le cas échéant, sont écrites dans le fichier de sortie. Nous pouvons ensuite réutiliser le tampon de sortie pour le prochain appel de deflate(). Encore une fois, s'il y a une erreur d'entrée/sortie de fichier, nous appelons deflateEnd() avant de revenir pour éviter une fuite de mémoire.

La boucle interne est répétée jusqu'à ce que le dernier appel deflate() ne parvienne pas à remplir le tampon de sortie fourni. Nous savons alors que deflate() a fait tout ce qu'il pouvait avec l'entrée fournie, et que toute cette entrée a été consommée. Nous pouvons alors sortir de cette boucle et réutiliser le tampon d'entrée.

La façon dont nous savons que deflate() n'a plus de sortie est de voir qu'il n'a pas rempli le tampon de sortie, laissant avail_out supérieur à zéro. Cependant, supposons que deflate() n'ait plus de sortie, mais qu'il ait juste rempli le tampon de sortie ! avail_out est nul, et nous ne pouvons pas dire que deflate() a fait tout ce qu'il pouvait. Pour autant que nous le sachions, deflate() a plus de sortie pour nous. Nous l'appelons donc à nouveau. Mais maintenant deflate() ne produit aucune sortie du tout, et avail_out reste inchangé en tant que CHUNK. Cet appel deflate() n'a rien pu faire, ni consommer l'entrée ni produire la sortie, et il renvoie donc Z_BUF_ERROR. Cependant, ce n'est pas du tout un problème. Maintenant, nous avons enfin l'indication souhaitée que deflate() est vraiment terminé, et nous sortons donc de la boucle interne pour fournir plus d'entrées à deflate().

Avec flush défini sur Z_FINISH, cet ensemble final d'appels deflate() complètera le flux de sortie. Une fois cela fait, les appels suivants de deflate() renverraient Z_STREAM_ERROR si le paramètre flush n'est pas Z_FINISH, et n'effectueraient plus de traitement jusqu'à ce que l'état soit réinitialisé.

Certaines applications de zlib ont deux boucles appelant deflate() au lieu de la seule boucle interne que nous avons ici. La première boucle appellerait sans vidage et alimenterait toutes les données à deflate(). La deuxième boucle appellerait deflate() sans plus de données et le paramètre Z_FINISH pour terminer le processus. Comme vous pouvez le voir dans cet exemple, cela peut être évité en gardant simplement une trace de l'état de vidage actuel.

Nous vérifions maintenant si nous avons déjà traité l'intégralité du fichier d'entrée. Ces informations ont été enregistrées dans la variable flush, nous voyons donc si elle a été définie sur Z_FINISH. Si c'est le cas, nous avons terminé et nous sortons de la boucle externe. Nous sommes assurés d'obtenir Z_STREAM_END à partir du dernier appel deflate(), puisque nous l'avons exécuté jusqu'à ce que le dernier bloc d'entrée soit consommé et que toute la sortie soit générée.

Le processus est terminé, mais nous devons encore désallouer l'état pour éviter une fuite de mémoire (ou plutôt une hémorragie de mémoire si vous ne l'avez pas fait). Ensuite, nous pouvons enfin revenir avec une valeur de retour satisfaisante.

Nous faisons maintenant la même chose pour la décompression dans la routine inf(). inf() décompresse ce qui est, espérons-le, un flux zlib valide à partir du fichier d'entrée et écrit les données non compressées dans le fichier de sortie. Une grande partie de la discussion ci-dessus pour def() s'applique également à inf(), la discussion ici se concentrera donc sur les différences entre les deux.

Les variables locales ont les mêmes fonctionnalités que pour def(). La seule différence est qu'il n'y a pas de variable de vidage, car inflate() peut savoir à partir du flux zlib lui-même quand le flux est terminé.

L'initialisation de l'état est la même, sauf qu'il n'y a pas de niveau de compression, bien sûr, et que deux autres éléments de la structure sont initialisés. avail_in et next_in doivent être initialisés avant d'appeler inflateInit(). Cela est dû au fait que l'application a la possibilité de fournir le début du flux zlib afin que inflateInit() ait accès aux informations sur la méthode de compression pour aider à l'allocation de mémoire. Dans l'implémentation actuelle de zlib (jusqu'aux versions 1.2.x), les allocations de mémoire dépendantes de la méthode sont de toute façon différées au premier appel de inflate(). Cependant, ces champs doivent être initialisés car les versions ultérieures de zlib fournissant plus de méthodes de compression peuvent tirer parti de cette interface. Dans tous les cas, aucune décompression n'est effectuée par inflateInit(), donc les champs avail_out et next_out n'ont pas besoin d'être initialisés avant l'appel.

Ici, avail_in est défini sur zéro et next_in est défini sur Z_NULL pour indiquer qu'aucune donnée d'entrée n'est fournie.

La boucle externe do-loop décompresse l'entrée jusqu'à ce que inflate() indique qu'elle a atteint la fin des données compressées et a produit toute la sortie non compressée. Ceci est en contraste avec def() traitant tout le fichier d'entrée. Si la fin du fichier est atteinte avant que les données compressées ne se terminent automatiquement, alors les données compressées sont incomplètes et une erreur est renvoyée.

Nous lisons les données d'entrée et définissons la structure strm en conséquence. Si nous avons atteint la fin du fichier d'entrée, nous quittons la boucle externe et signalons une erreur, car les données compressées sont incomplètes. Notez que nous pouvons lire plus de données que ce qui est finalement consommé par inflate(), si le fichier d'entrée continue au-delà du flux zlib. Pour les applications où les flux zlib sont intégrés dans d'autres données, cette routine doit être modifiée pour renvoyer les données inutilisées, ou au moins indiquer la quantité de données d'entrée qui n'a pas été utilisée, afin que l'application sache où récupérer après le flux zlib.

La boucle interne do-loop a la même fonction que dans def(), consistant à continuer à appeler inflate() jusqu'à ce qu'elle ait généré toute la sortie possible avec l'entrée fournie.

Tout comme dans def(), le même espace de sortie est fourni pour chaque appel de inflate().

Maintenant, nous exécutons le moteur de décompression lui-même. Il n'est pas nécessaire d'ajuster le paramètre flush, car le format zlib est auto-terminé. La principale différence ici est qu'il existe des valeurs de retour auxquelles nous devons prêter attention. Z_DATA_ERROR indique que inflate() a détecté une erreur dans le format de données compressées zlib, ce qui signifie que soit les données ne sont pas un flux zlib au départ, soit que les données ont été corrompues quelque part en cours de route car elles ont été compressées. L'autre erreur à traiter est Z_MEM_ERROR, pouvant se produire car l'allocation de mémoire est différée jusqu'à ce que inflate() en ait besoin, contrairement à deflate(), dont la mémoire est allouée au début par deflateInit().

Les applications avancées peuvent utiliser deflateSetDictionary() pour amorcer deflate() avec un ensemble de données probables pour améliorer les 32 premiers Ko environ de compression. Cela est noté dans l'entête zlib, donc inflate() demande que ce dictionnaire soit fourni avant de pouvoir commencer la décompression. Sans le dictionnaire, une décompression correcte n'est pas possible. Pour cette routine, nous n'avons aucune idée de ce qu'est le dictionnaire, donc l'indication Z_NEED_DICT est convertie en Z_DATA_ERROR.

inflate() peut également renvoyer Z_STREAM_ERROR, ce qui ne devrait pas être possible ici, mais pourrait être vérifié comme indiqué ci-dessus pour def(). Z_BUF_ERROR n'a pas besoin d'être vérifié ici, pour les mêmes raisons que celles indiquées pour def(). Z_STREAM_END sera vérifié plus tard.

La sortie de inflate() est gérée de manière identique à celle de deflate().

La boucle interne do-loop se termine lorsque inflate() n'a plus de sortie comme indiqué par le fait que le tampon de sortie ne soit pas rempli, tout comme pour deflate(). Dans ce cas, nous ne pouvons pas affirmer que strm.avail_in sera nul, car le flux deflate peut se terminer avant le fichier.

La boucle externe do-loop se termine lorsque inflate() signale qu'elle a atteint la fin du flux zlib d'entrée, a terminé la décompression et la vérification d'intégrité et a fourni toutes les sorties. Ceci est indiqué par la valeur de retour inflate() Z_STREAM_END. La boucle interne est garantie de laisser ret égal à Z_STREAM_END si le dernier fragment du fichier d'entrée lu contenait la fin du flux zlib. Donc si la valeur de retour n'est pas Z_STREAM_END, la boucle continue à lire plus d'entrées.

À ce stade, la décompression s'est terminée avec succès ou nous sommes sortis de la boucle car il n'y avait plus de données disponibles dans le fichier d'entrée. Si la dernière valeur de retour de inflate() n'est pas Z_STREAM_END, alors le flux zlib était incomplet et une erreur de données est renvoyée. Sinon, nous revenons avec une valeur de retour satisfaisante. Bien sûr, inflateEnd() est appelé en premier pour éviter une fuite de mémoire.

Cela met fin aux routines qui utilisent directement zlib. Les routines suivantes transforment ce programme en programme de ligne de commande en exécutant les données via les routines ci-dessus de stdin à stdout, et en gérant les erreurs signalées par def() ou inf().

zerr() est utilisé pour interpréter les codes d'erreur possibles de def() et inf(), comme détaillé dans leurs commentaires ci-dessus, et afficher un message d'erreur. Notez qu'il ne s'agit que d'un sous-ensemble des valeurs de retour possibles de deflate() et inflate().

Voici la routine main() utilisée pour tester def() et inf(). La commande zpipe est simplement un tube de compression de stdin vers stdout, si aucun paramètre n'est fourni, ou c'est un tube de décompression si zpipe -d est utilisé. Si d'autres paramètres sont fournis, aucune compression ou décompression n'est effectuée. À la place, un message d'utilisation est affiché. Les exemples sont zpipe < foo.txt > foo.txt.z pour compresser, et zpipe -d < foo.txt.z > foo.txt pour décompresser.