setbuf, setbuffer, setlinebuf, setvbuf − Agir sur les buffers d’un flux.

#include <stdio.h>

void setbuf (FILE *stream, char *buf);
void setbuffer (FILE *stream, char *buf, size_t size);
void setlinebuf (FILE *stream);
int setvbuf (FILE *stream, char *buf, int mode , size_t size);

Les trois types de buffers disponibles sont les suivants : pas de buffers, buffers de blocs, et buffers de lignes. Quand un flux de sortie n’a pas de buffer, les données apparaissent dans le fichier destination, ou sur le terminal, dès qu’elles sont écrites. Avec les buffers par blocs, une certaine quantité de données est conservée avant d’être écrite en tant que bloc. Avec les buffers de lignes, les caractères sont conservés jusqu’à ce qu’un saut de ligne soit transmis, ou que l’on réclame une lecture sur un flux attaché au terminal (typiquement stdin). La fonction fflush(3) peut être utilisée pour forcer l’écriture à n’importe quel moment. (Voir fclose(3).)

Normalement tous les fichiers utilisent des buffers de blocs. Quand une première opération d’entrée/sortie se déroule sur un fichier, malloc(3) est appelé, et un buffer est créé. Si le flux se rapporte à un terminal (comme stdout habituellement) il s’agit d’un buffer de ligne. Le flux standard de sortie d’erreur stderr n’a jamais de buffer par défaut.

La fonction setvbuf peut être utilisée sur n’importe quel flux ouvert pour modifier son type de buffer. La paramètre mode doit correspondre à l’une des constantes symboliques suivantes :

_IONBF

pas de buffer

_IOLBF

buffer de ligne

_IOFBF

buffer complet

A l’exception des fichiers sans buffers, l’argument buf doit pointer sur un buffer contenant au moins size octets. Ce nouveau buffer sera utilisé à la place de l’ancien. Si l’argument buf est NULL, seul le mode est affecté. Un nouveau buffer sera alloué automatiquement lors de la prochaine opération de lecture ou d’écriture. La fonction setvbuf ne peut être utilisée qu’après l’ouverture du flux, et avant toute opération dessus.

Les trois autres appels sont, en fait, simplement des alias pour l’appel de setvbuf. la fonction setbuf est exactement équivalente Ã

setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

La fonction setbuffer est identique, sauf que la taille du buffer est indiquée par l’appelant plutôt que la valeur par défaut BUFSIZ. La fonction setlinebuf est exactement équivalente à :

setvbuf(stream, (char *)NULL, _IOLBF, 0);

La fonction setvbuf renvoie zéro si elle réussit. Elle peut renvoyer n’importe quelle valeur en cas d’échec, mais renvoie zéro si le mode est invalide, ou si la requête ne peut pas être honorée. Elle peut remplir errno en cas d’erreur. Les autres fonctions ne renvoient rien.

Les fonctions setbuf et setvbuf sont conformes à ANSI X3.159-1989 (‘‘ANSI C’’).

Les fonctions setbuffer et setlinebuf ne sont pas portables sur les systèmes BSD antérieurs à 4.2BSD, et sont isponibles sous Linux depuis la LibC 4.5.21. Sur les systèmes 4.2BSD et 4.3BSD, setbuf utilise toujours une taille de buffer non-optimale, et doit être évitée.

Il faut toujours s’assurer que buf et son contenu existent encore au moment de la fermeture du flux (qui se produit automatiquement à la fin du programme).

Par exemple, ceci est INCORRECT :

#include <stdio.h>

int
main (void)
{
    char   buf [BUFSIZ];

   setbuf (stdin, buf);
    printf ("Hello, world!\n");
    return (0);
}

fclose(3), fflush(3), fopen(3), fread(3), malloc(3), printf(3), puts(3)

Christophe Blaess, 1997.