NOM
fmemopen, open_memstream, open_wmemstream - 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);
#define _GNU_SOURCE
#include <wchar.h>
FILE *open_wmemstream(wchar_t **ptr, size_t *sizeloc);
La fonction fmemopen() ouvre un flux qui permet l’accès spécifié par
mode. Le flux permet d’effectuer des entrées sorties sur la chaîne ou
la mémoire du tampon pointée par buf. Ce tampon doit au moins être
d’une longueur de size octets.
L’argument mode est le même que celui de la fonction fopen(3). Si mode
spécifie un mode d’ajout (« append mode »), alors la position initiale
du fichier est définie à la position du premier octet nul ('\0') du
tampon ; sinon la position initiale est définie au début du tampon.
Depuis la glibc 2.9, la lettre « b »peut être spécifiée comme second
caractère de mode. Ceci fournit le mode binaire : une écriture
n’implique pas d’ajouter un caractère nul de terminaison et fseek(3)
SEEK_END est relative à la fin du tampon (c-a-d la valeur spécifié par
size) au lieu de la taille de la chaîne courante.
Lorsqu’un flux ouvert en écriture est vidé (voyez fflush(3)), ou fermé
(voyez fclose(3)), un octet nul est écrit à la fin du tampon s’il y a
de la place. L’appelant devrait s’assurer qu’un octet supplémentaire
est disponible dans le tampon (et que size en tient compte) pour
permettre ceci.
Essayer d’écrire plus de size octets dans le tampon crée une erreur.
(Par défaut, de telles erreurs ne sont seulement visibles que lorsque
le tampon stdio est vidé. Désactiver la mise en tampon avec
setbuf(fp, NULL) peut être utile pour détecter les erreurs au moment
d’une opération de sortie. Alternativement, l’appelant peut
explicitement définir buf comme un tampon de flux stdio, au même moment
en informant stdio de la taille du tampon avec setbuffer(fp, buf,
size)).
Avec un flux ouvert en lecture, un octet nul dans le tampon ne crée pas
d’opérations de lecture et renvoie une indication de fin de fichier.
Une lecture depuis le tampon indiquera seulement la fin du fichier
quand le pointeur de fichier aura avancé de plus de size octets par
rapport au début du tampon.
Si l’argument buf vaut NULL, alors la fonction fmemopen() alloue
dynamiquement un tampon de size octets. C’est utile pour les
applications qui veulent écrire des données dans un tampon temporaire
et les lire ensuite. Le tampon est automatiquement supprimé lorsque le
flux est fermé. Notez que l’appelant ne peut pas obtenir un pointeur
vers le tampon alloué temporairement avec cette fonction (c’est
possible avec open_memstream(), ci-dessous).
La fonction open_memstream() ouvre un flux en écriture vers un tampon.
Le tampon est dynamiquement alloué (comme avec malloc(3)) et grandit
automatiquement à la demande. Après la fermeture du flux, l’appelant
doit libérer (free(3)) ce tampon.
Lorsqu’un flux est fermé (fclose(3)) ou vidé (fflush(3)), les adresses
pointées par ptr et sizeloc sont mises à jour, avec respectivement, un
pointeur vers le tampon et la taille du tampon actuel. Ces valeurs
restent valides tant que l’appelant n’effectue pas de sortie sur le
flux. Si d’autres sorties sont réalisées, alors le flux doit être ne
nouveau vidé avant d’essayer d’accéder à ces variables.
Un octet nul est conservé à la fin du tampon. Cet octet nest pas
inclus dans la valeur de la taille stockée dans sizeloc.
La position du flux de fichier peut être changée avec fseek(3) ou
fseeko(3). Déplacer la position après la fin des données déjà écrites
remplit l’intervalle vide avec des zéros.
La fonction open_wmemstream() est similaire à open_memstream(), mais
elle opère sur les caractères larges et non sur des octets.
VALEUR RENVOYÉE
Si elles réussissent intégralement, les fonctions fmemopen(),
open_memstream() et open_wmemstream() renvoient un pointeur de type
FILE. Sinon, elles renvoient NULL et errno est définie avec le code
d’erreur.
VERSIONS
fmemopen() est open_memstream() sont déjà disponibles dans la
glibc 1.0.x. open_wmemstream() est disponible depuis la glibc 2.4.
CONFORMITÉ
POSIX.1-2008. Ces fonctions ne sont pas spécifiées dans POSIX.1-2001 et
ne sont que rarement disponible sur d’autres systèmes.
NOTES
Il n’y a pas de descripteur de fichier associé avec le flux renvoyé par
ces fonctions (par exemple, fileno(3) retournera une erreur si elle est
appelée avec un tel flux).
BOGUES
Avant la glibc 2.7, un positionnement après la fin d’un flux crée par
open_memstream() n’agrandit pas le tampon ; l’appel à fseek() échoue et
renvoie -1.
EXEMPLE
Le programme ci-dessous utilise fmemopen() pour ouvrir un tampon
d’entrée et open_memstream() pour ouvrir un tampon de sortie de taille
dynamique. Ce programme scrute la chaînes en entrée (récupérée du
premier argument de la ligne de commande du programme) sous forme
d’entiers, et écrit le carré de ces entiers dans 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
Source du programme
#define _GNU_SOURCE
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#define handle_error(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;
if (argc != 2) {
fprintf(stderr, "Usage: %s <file>\n", argv[0]);
exit(EXIT_FAILURE);
}
in = fmemopen(argv[1], strlen(argv[1]), "r");
if (in == NULL)
handle_error("fmemopen");
out = open_memstream(&ptr, &size);
if (out == NULL)
handle_error("fmemopen");
for (;;) {
s = fscanf(in, "%d", &v);
if (s <= 0)
break;
s = fprintf(out, "%d ", v * v);
if (s == -1)
handle_error("fprintf");
}
fclose(in);
fclose(out);
printf("size=%ld; ptr=%s\n", (long) size, ptr);
free(ptr);
exit(EXIT_SUCCESS);
}
VOIR AUSSI
fopen(3), fopencookie(3), feature_test_macros(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».