Les fonctions d'accès aux fichiers gzip

Cette bibliothèque prend en charge la lecture et l'écriture de fichiers au format gzip (.gz) avec une interface similaire à celle de stdio, en utilisant les fonctions commençant par «gz». Le format gzip est différent du format zlib. gzip est un enveloppe gzip, documenté dans la RFC 1952, enveloppé autour d'un flux deflate.

Ouvrez le fichier gzip (.gz) à l'adresse path pour le lire et le décompresser, ou le compresser et l'écrire. Le paramètre mode est comme dans fopen («rb» ou «wb») mais peut également inclure un niveau de compression («wb9») ou une stratégie : «f» pour les données filtrées comme dans «wb6f», «h» pour la compression Huffman uniquement comme dans «wb1h», «R» pour le codage de longueur d'exécution comme dans «wb1R», ou «F» pour la compression de code fixe comme dans «wb9F». (Voir la description de deflateInit2 pour plus d'informations sur le paramètre strategy.) «T» demandera une écriture transparente ou un ajout sans compression et sans utiliser le format gzip.

«a» peut être utilisé à la place de «w» pour demander que le flux gzip étant écrit soit ajouté au fichier. «+» entraînera une erreur, car la lecture et l'écriture dans le même fichier gzip ne sont pas prises en charge. L'ajout de «x» lors de l'écriture créera le fichier de manière exclusive, ce qui échoue si le fichier existe déjà. Sur les systèmes qui le prennent en charge, l'ajout de «e» lors de la lecture ou de l'écriture définira l'indicateur pour fermer le fichier lors d'un appel à execve().

Ces fonctions, ainsi que gzip, liront et décoderont une séquence de flux gzip dans un fichier. La fonction append de gzopen() peut être utilisée pour créer un tel fichier. (Voir aussi gzflush() pour une autre façon de procéder.) Lors de l'ajout, gzopen ne teste pas si le fichier commence par un flux gzip, ni ne recherche la fin des flux gzip pour commencer l'ajout. gzopen ajoutera simplement un flux gzip au fichier existant.

gzopen peut être utilisé pour lire un fichier n'étant pas au format gzip ; dans ce cas, gzread lira directement le fichier sans décompression. Lors de la lecture, cela sera détecté automatiquement en recherchant l'entête gzip magique de deux octets.

gzopen renvoie NULL si le fichier n'a pas pu être ouvert, s'il n'y avait pas suffisamment de mémoire pour allouer l'état gzFile ou si un mode non valide a été spécifié (un «r», «w» ou «a» n'a pas été fourni, ou «+» a été fourni). errno peut être vérifié pour déterminer si la raison de l'échec de gzopen était que le fichier n'a pas pu être ouvert.

Associez un gzFile au descripteur de fichier fd. Les descripteurs de fichiers sont obtenus à partir d'appels tels que open, dup, creat, pipe ou fileno (si le fichier a été précédemment ouvert avec fopen). Le paramètre mode est le même que dans gzopen.

L'appel suivant de gzclose sur le gzFile renvoyé fermera également le descripteur de fichier fd, tout comme fclose(fdopen(fd), mode) ferme le descripteur de fichier fd. Si vous souhaitez garder fd ouvert, utilisez fd = dup(fd_keep); gz = gzdopen(fd, mode);. Le descripteur dupliqué doit être enregistré pour éviter une fuite, car gzdopen ne ferme pas fd en cas d'échec. Si vous utilisez fileno() pour obtenir le descripteur de fichier à partir d'un FILE *, vous devrez alors utiliser dup() pour éviter de fermer le descripteur de fichier en double. gzclose() et fclose() fermeront tous deux le descripteur de fichier associé, ils doivent donc avoir des descripteurs de fichier différents.

gzdopen renvoie NULL s'il n'y a pas suffisamment de mémoire pour allouer l'état gzFile, si un mode non valide a été spécifié (aucun «r», «w» ou «a» n'a été fourni, ou «+» a été fourni), ou si fd est -1. Le descripteur de fichier n'est pas utilisé jusqu'à la prochaine opération de lecture, d'écriture, de recherche ou de fermeture de gz*, donc gzdopen ne détectera pas si fd est non valide (à moins que fd ne soit -1).

Définissez la taille de la mémoire tampon interne utilisée par les fonctions de cette bibliothèque pour le fichier sur size. La taille de la mémoire tampon par défaut est de 8192 octets. Cette fonction doit être appelée après gzopen() ou gzdopen(), et avant tout autre appel lisant ou écrivant le fichier. L'allocation de mémoire tampon est toujours différée à la première lecture ou écriture. Trois fois cette taille dans l'espace tampon est allouée. Une taille de mémoire tampon plus grande, par exemple 64 Ko ou 128 Ko, augmentera sensiblement la vitesse de décompression (lecture).

La nouvelle taille de mémoire tampon affecte également la longueur maximale de gzprintf().

gzbuffer() renvoie 0 en cas de succès ou -1 en cas d'échec, par exemple en cas d'appel trop tardif.

Mettre à jour dynamiquement le niveau de compression et la stratégie du fichier. Voir la description de deflateInit2 pour la signification de ces paramètres. Les données fournies précédemment sont vidées avant d'appliquer les modifications de paramètres.

gzsetparams renvoie Z_OK en cas de succès, Z_STREAM_ERROR si le fichier n'a pas été ouvert pour l'écriture, Z_ERRNO en cas d'erreur lors de l'écriture des données vidées ou Z_MEM_ERROR en cas d'erreur d'allocation de mémoire.

Lire et décompresser jusqu'à len octets non compressés du fichier dans buf. Si le fichier d'entrée n'est pas au format gzip, gzread copie le nombre donné d'octets dans le tampon directement à partir du fichier.

Après avoir atteint la fin d'un flux gzip dans l'entrée, gzread continuera à lire, à la recherche d'un autre flux gzip. N'importe quel nombre de flux gzip peut être concaténé dans le fichier d'entrée, et seront tous décompressés par gzread(). Si quelque chose d'autre qu'un flux gzip est rencontré après un flux gzip, le reste de déchets de fin est ignoré (et aucune erreur n'est renvoyée).

gzread peut être utilisé pour lire un fichier gzip étant en cours d'écriture simultanée. Une fois la fin de l'entrée atteinte, gzread reviendra avec les données disponibles. Si le code d'erreur renvoyé par gzerror est Z_OK ou Z_BUF_ERROR, alors gzclearerr peut être utilisé pour effacer l'indicateur de fin de fichier afin de permettre à gzread d'être réessayé. Z_OK indique qu'un flux gzip a été terminé lors du dernier gzread. Z_BUF_ERROR indique que le fichier d'entrée s'est terminé au milieu d'un flux gzip. Notez que gzread ne renvoie pas -1 en cas de flux gzip incomplet. Cette erreur est différée jusqu'à gzclose(), renvoyant Z_BUF_ERROR si le dernier gzread s'est terminé au milieu d'un flux gzip. Alternativement, gzerror peut être utilisé avant gzclose pour détecter ce cas.

gzread renvoie le nombre d'octets non compressés réellement lus, inférieur à len pour la fin du fichier, ou -1 pour l'erreur. Si len est trop grand pour tenir dans un int, alors rien n'est lu, -1 est renvoyé et l'état d'erreur est défini sur Z_STREAM_ERROR.

Lire et décompresser jusqu'à nitems éléments de taille size du fichier vers buf, sinon fonctionner comme le fait gzread(). Cela duplique l'interface de fread() de stdio, avec des types de requête et de retour size_t. Si la bibliothèque définit size_t, alors z_size_t est identique à size_t. Sinon, alors z_size_t est un type entier non signé pouvant contenir un pointeur.

gzfread() renvoie le nombre d'éléments complets lus de taille size, ou zéro si la fin du fichier a été atteinte et qu'un élément complet n'a pas pu être lu, ou s'il y a eu une erreur. gzerror() doit être consulté si zéro est renvoyé afin de déterminer s'il y a eu une erreur. Si la multiplication de size et nitems déborde, c'est-à-dire que le produit ne rentre pas dans un z_size_t, alors rien n'est lu, zéro est renvoyé et l'état d'erreur est défini sur Z_STREAM_ERROR.

Dans le cas où la fin du fichier est atteinte et que seul un élément partiel est disponible à la fin, c'est-à-dire que la longueur des données non compressées restantes n'est pas un multiple de la taille, l'élément partiel final est néanmoins lu dans buf et l'indicateur de fin de fichier est défini. La longueur de l'élément partiel lu n'est pas fournie, mais peut être déduite du résultat de gztell(). Ce comportement est le même que celui des implémentations de fread() dans les bibliothèques courantes, mais il empêche l'utilisation directe de gzfread() pour lire un fichier écrit simultanément, en le réinitialisant et en réessayant à la fin du fichier, lorsque la taille n'est pas égale à 1.

Compressez et écrivez les len octets non compressés de buf dans le fichier. gzwrite renvoie le nombre d'octets non compressés écrits ou 0 en cas d'erreur.

Compresser et écrire les éléments nitems de taille size de buf vers file, en dupliquant l'interface de fwrite() de stdio, avec les types de requête et de retour size_t. Si la bibliothèque définit size_t, alors z_size_t est identique à size_t. Sinon, alors z_size_t est un type entier non signé qui peut contenir un pointeur.

gzfwrite() renvoie le nombre d'éléments complets écrits de taille size, ou zéro en cas d'erreur. Si la multiplication de size et nitems déborde, c'est-à-dire que le produit ne rentre pas dans un z_size_t, alors rien n'est écrit, zéro est renvoyé et l'état d'erreur est défini sur Z_STREAM_ERROR.

Convertir, formater, compresser et écrire les paramètres (...) dans un fichier sous le contrôle du format de chaîne, comme dans fprintf. gzprintf renvoie le nombre d'octets non compressés réellement écrits, ou un code d'erreur zlib négatif en cas d'erreur. Le nombre d'octets non compressés écrits est limité à 8191, soit un de moins que la taille de la mémoire tampon donnée à gzbuffer(). L'appelant doit s'assurer que cette limite n'est pas dépassée. Si elle est dépassée, gzprintf() renverra une erreur (0) sans rien écrire. Dans ce cas, il peut également y avoir un dépassement de tampon aux conséquences imprévisibles, ce qui n'est possible que si zlib a été compilé avec les fonctions non sécurisées sprintf() ou vsprintf(), car les fonctions sécurisées snprintf() ou vsnprintf() n'étaient pas disponibles. Cela peut être déterminé en utilisant zlibCompileFlags().

Compressez et écrivez la chaîne de caractères terminée par un caractère nul donnée dans le fichier, en excluant le caractère nul de fin.

gzputs renvoie le nombre de caractères écrits, ou -1 en cas d'erreur.

Lire et décompresser les octets du fichier dans buf, jusqu'à ce que len-1 caractères soient lus, ou jusqu'à ce qu'un caractère de nouvelle ligne soit lu et transféré dans buf, ou qu'une condition de fin de fichier soit rencontrée. Si des caractères sont lus ou si len est égal à 1, la chaîne se termine par un caractère nul. Si aucun caractère n'est lu en raison d'une fin de fichier ou si len est inférieur à 1, le tampon reste intact.

gzgets renvoie buf étant une chaîne de caractères terminée par un caractère nul, ou renvoie NULL pour la fin de fichier ou en cas d'erreur. En cas d'erreur, le contenu de buf est indéterminé.

Compressez et écrivez c, converti en un caractère non signé, dans le fichier. gzputc renvoie la valeur qui a été écrite, ou -1 en cas d'erreur.

Lit et décompresse un octet du fichier. gzgetc renvoie cet octet ou -1 en cas de fin de fichier ou d'erreur. Ceci est implémenté comme une macro pour la vitesse. En tant que tel, il n'effectue pas toutes les vérifications effectuées par les autres fonctions. C'est-à-dire qu'il ne vérifie pas si le fichier est NULL, ni si la structure vers laquelle pointe le fichier a été écrasée ou non.

Repoussez c dans le flux pour que le fichier soit lu comme premier caractère lors de la lecture suivante. Au moins un caractère de repoussé est toujours autorisé. gzungetc() renvoie le caractère poussé, ou -1 en cas d'échec. gzungetc() échouera si c est -1, et peut échouer si un caractère a été poussé mais pas encore lu. Si gzungetc est utilisé immédiatement après gzopen ou gzdopen, au moins la taille du tampon de sortie des caractères poussés est autorisée. (Voir gzbuffer ci-dessus.) Le caractère poussé sera ignoré si le flux est repositionné avec gzseek() ou gzrewind().

Vide toutes les sorties en attente dans un fichier. Le paramètre flush est le même que dans la fonction deflate(). La valeur de retour est le numéro d'erreur zlib (voir la fonction gzerror ci-dessous). gzflush n'est autorisé que lors de l'écriture.

Si le paramètre flush est Z_FINISH, les données restantes sont écrites et le flux gzip est complété dans la sortie. Si gzwrite() est appelé à nouveau, un nouveau flux gzip sera démarré dans la sortie. gzread() est capable de lire de tels flux gzip concaténés.

gzflush ne doit être appelé que lorsque cela est strictement nécessaire car il dégradera la compression s'il est appelé trop souvent.

Définissez la position de départ sur un décalage relatif à whence pour le prochain gzread ou gzwrite sur le fichier. Le décalage représente un nombre d'octets dans le flux de données non compressé. Le paramètre whence est défini comme dans lseek; la valeur SEEK_END n'est pas prise en charge.

Si le fichier est ouvert pour la lecture, cette fonction est émulée mais peut être extrêmement lente. Si le fichier est ouvert pour l'écriture, seules les recherches vers l'avant sont prises en charge; gzseek compresse ensuite une séquence de zéros jusqu'à la nouvelle position de départ.

gzseek renvoie l'emplacement de décalage résultant tel que mesuré en octets à partir du début du flux non compressé, ou -1 en cas d'erreur, en particulier si le fichier est ouvert pour l'écriture et que la nouvelle position de départ serait avant la position actuelle.

Rembobine le fichier. Cette fonction n'est prise en charge que pour la lecture.

gzrewind(file) est équivalent à (int)gzseek(file, 0L, SEEK_SET).

Renvoie la position de départ pour la prochaine lecture ou écriture gzread sur le fichier. Cette position représente un nombre d'octets dans le flux de données non compressé et est égale à zéro au démarrage, même si vous ajoutez ou lisez un flux gzip depuis le milieu d'un fichier à l'aide de gzdopen().

gztell(fichier) est équivalent à gzseek(fichier, 0L, SEEK_CUR).

Renvoie le décalage de lecture ou d'écriture compressé (réel) actuel du fichier. Ce décalage inclut le nombre d'octets précédant le flux gzip, par exemple lors de l'ajout ou lors de l'utilisation de gzdopen() pour la lecture. Lors de la lecture, le décalage n'inclut pas les entrées tamponnées non encore utilisées. Ces informations peuvent être utilisées comme indicateur de progression. En cas d'erreur, gzoffset() renvoie -1.

Renvoie true (1) si l'indicateur de fin de fichier pour le fichier a été défini pendant la lecture, false (0) dans le cas contraire. Notez que l'indicateur de fin de fichier est défini uniquement si la lecture a essayé de dépasser la fin de l'entrée, mais n'a pas réussi. Par conséquent, tout comme feof(), gzeof() peut renvoyer false même s'il n'y a plus de données à lire, dans le cas où la dernière demande de lecture concernait le nombre exact d'octets restant dans le fichier d'entrée. Cela se produira si la taille du fichier d'entrée est un multiple exact de la taille du tampon.

Si gzeof() renvoie true, les fonctions de lecture ne renverront plus de données, à moins que l'indicateur de fin de fichier ne soit réinitialisé par gzclearerr() et que le fichier d'entrée n'ait augmenté depuis que la fin de fichier précédente a été détectée.

Renvoie true (1) si le fichier est copié directement pendant la lecture, ou false (0) si le fichier est un flux gzip en cours de décompression.

Si le fichier d'entrée est vide, gzdirect() renvoie true, car l'entrée ne contient pas de flux gzip.

Si gzdirect() est utilisé immédiatement après gzopen() ou gzdopen(), il provoquera l'allocation de tampons pour permettre la lecture du fichier afin de déterminer s'il s'agit d'un fichier gzip. Par conséquent, si gzbuffer() est utilisé, il doit être appelé avant gzdirect().

Lors de l'écriture, gzdirect() renvoie true si l'écriture transparente a été demandée ("wT" pour le mode gzopen()), ou false (0) dans le cas contraire. (Remarque : gzdirect() n'est pas nécessaire lors de l'écriture. L'écriture transparente doit être explicitement demandée, de sorte que l'application connaisse déjà la réponse. Lors de la liaison statique, l'utilisation de gzdirect() inclura tout le code zlib pour la lecture et la décompression du fichier gzip, ce qui peut ne pas être souhaité.)

Videz toutes les sorties en attente pour le fichier, si nécessaire, fermez le fichier et libérez l'état de (dé)compression. Notez qu'une fois le fichier fermé, vous ne pouvez pas appeler gzerror avec le fichier, car ses structures ont été libérées. gzclose ne doit pas être appelé plus d'une fois sur le même fichier, tout comme free ne doit pas être appelé plus d'une fois sur la même allocation.

gzclose renverra Z_STREAM_ERROR si le fichier n'est pas valide, Z_ERRNO en cas d'erreur d'opération sur le fichier, Z_MEM_ERROR en cas de manque de mémoire, Z_BUF_ERROR si la dernière lecture s'est terminée au milieu d'un flux gzip, ou Z_OK en cas de succès.

Identique à gzclose(), mais gzclose_r() n'est utilisé qu'en lecture, et gzclose_w() n'est utilisé qu'en écriture ou en ajout. L'avantage de les utiliser à la place de gzclose() est qu'ils évitent de lier du code de compression ou de décompression zlib n'étant pas utilisé uniquement en lecture ou uniquement en écriture, respectivement. Si gzclose() est utilisé, le code de compression et de décompression sera inclus dans l'application lors de la liaison à une bibliothèque zlib statique.

Renvoie le message d'erreur de la dernière erreur survenue sur le fichier. errnum est défini sur le numéro d'erreur zlib. Si une erreur s'est produite dans le système de fichiers et non dans la bibliothèque de compression, errnum est défini sur Z_ERRNO et l'application peut consulter errno pour obtenir le code d'erreur exact.

L'application ne doit pas modifier la chaîne renvoyée. Les appels ultérieurs à cette fonction peuvent invalider la chaîne renvoyée précédemment. Si le fichier est fermé, la chaîne renvoyée précédemment par gzerror ne sera plus disponible.

gzerror() doit être utilisé pour distinguer les erreurs de fin de fichier pour les fonctions ci-dessus ne distinguant pas ces cas dans leurs valeurs de retour.

Efface les indicateurs d'erreur et de fin de fichier pour le fichier. Ceci est analogue à la fonction clearerr() dans stdio. Ceci est utile pour continuer à lire un fichier gzip étant en cours d'écriture simultanément.