Linux Certif

Toute la documentation sur la certification Linux LPI

fmemopen

NOM

fmemopen, open_memstream - Ouvrir de la mémoire comme un flux

SYNOPSIS

#define _GNU_SOURCE
#include <stdio.h>

FILE *fmemopen(void *buf, size_t size, const char *mode);

FILE *open_memstream(char **ptr, size_t *sizeloc)

DESCRIPTION

La fonction fmemopen() ouvre un flux qui permet l'accès spécifié par mode. Ce flux permet d'effectuer des entrées-sorties sur une chaîne ou un tampon mémoire pointé par buf. Ce tampon doit avoir une taille d'au moins size octets.

L'argument mode est le même que pour fopen(3). Si mode spécifie un mode d'ajout, la tête de lecture initiale du fichier est positionnée sur le premier octet nul (« \0 »). Autrement, elle est positionnée au début du tampon.

Lorsqu'un flux ouvert en écriture est vidé (fflush(3)) ou fermé (fclose(3)), un octet nul est écrit à la fin du tampon s'il y a la place. L'appelant devrait s'assurer qu'un octet supplémentaire soit disponible dans le tampon (et que size prenne en compte cet octet). Toute tentative d'écrire plus de size octets dans le tampon provoquera une erreur. (Par défaut, de telles erreurs ne seront visibles que lorsque le tampon stdio sera vidé. Désactiver le tamponage avec setbuf(fp, NULL) peut être utile pour détecter les erreurs au moment de l'opération de sortie. Alternativement, l'appelant peut explicitement remplir buf aveec le tampon du flux stdio, informant au même moment stdio de la taille du tampon avec setbuffer(fp, buf, size).)

Dans un flux ouvert en lecture, les opérations de lecture ne renverront par une indication « fin de fichier » lorsqu'elle rencontreront des octets nuls (« \0 ») dans le tampon. Une lecture n'indiquera la fin du fichier que lorsque la tête de lecture ira au delà de size octets après le début du tampon.

Si buf est spécifié comme NULL, fmemopen() allouera dynamiquement un tampon de size octets. Cela est utile pour une application qui veut écrire des données dans un tampon temporaire et les relire à nouveau. Le tampon est automatiquement libéré lorsque le flux est fermé. Notez que l'appelant n'a aucun moyen d'obtenir un pointeur sur le tampon temporaire alloué par cet appel (mais voir open_memstream() plus loin).

La fonction open_memstream() ouvre un flux en écriture sur un tampon. Le tampon est alloué dynamiquement (comme avec malloc(3)), et grandit automatiquement si nécessaire. Après la fermeture du flux, l'appelant doit libérer (free(3)) ce tampon.

Lorsque le flux est fermé (fclose(3)) ou vidé (fflush(3)), les variables pointées par ptr et sizeloc sont mises à jour avec, respectivement, le pointeur sur le tampon et la taille de ce dernier. Ces valeurs resteront valides aussi longtemps que l'appelant n'effectue pas de sortie sur le flux. Si d'autres sorties sont réalisées, le flux doit être vidé avant d'essayer d'accéder à ces variables.

Un octet nul est écrit à la fin du tampon. Cet octet n'est pas inclus dans la valeur de la taille enregistrée dans sizeloc.

VALEUR RENVOYÉE

Si elles réussissent, les fonctions fmemopen() et open_memstream() renvoient un pointeur FILE. Autrement, elles renvoient NULL et écrivent dans errno la valeur de l'erreur.

CONFORMITÉ

Ces fonctions sont des extensions GNU.

EXEMPLE

Le programme suivant utilise fmemopen() pour ouvrir un tampon d'entrée et open_memstream() pour ouvrir un tampon de sortie de taille dynamique. Le programme balaye sa chaîne d'entrée (récupérée du premier argument de la ligne de commande du programme) pour lire des entiers, et écrit le carré de ces entiers sur le tampon de sortie. Voici un exemple de la sortie produite par ce programme :

 
 $ ./a.out "1 23 43"
 size=11; ptr=1 529 1849
 
 #define _GNU_SOURCE
 #include <assert.h>
 #include <string.h>
 #include <stdio.h>
 #include <stdlib.h>
 
 #define die(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
 
 int
 main(int argc, char *argv[])
 {
     FILE *out, *in;
     int v, s;
     size_t size;
     char *ptr;
 
     assert(argc == 2);
 
     in = fmemopen(argv[1], strlen(argv[1]), "r");
     if (in == NULL)
         die("fmemopen");
 
     out = open_memstream(&ptr, &size);
     if (out == NULL)
         die("fmemopen");
 
     for (;;) {
         s = fscanf(in, "%d", &v);
         if (s <= 0)
             break;
 
         s = fprintf(out, "%d ", v * v);
         if (s == -1)
             die("fprintf");
     }
     fclose(in);
     fclose(out);
     printf("size=%ld; ptr=%s\n", (long) size, ptr);
     free(ptr);
     exit(EXIT_SUCCESS);
 }
 

VOIR AUSSI

open(3), feature_test_macros(7)

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 17 juillet 2006 et révisée le 27 novembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 fmemopen ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.