C Reference ยท stdio.h
C setvbuf() function and stream buffering
Reference for C setvbuf() and setbuf(): the three buffering modes (full, line, none), supplying your own buffer, when to call it and how buffering affects output.
Standard C streams do not talk to the operating system one character at a time. They collect data in a buffer and transfer it in blocks. setvbuf() lets you choose the buffering mode of a stream, and optionally provide the buffer memory yourself.
There are three modes. Fully buffered streams transfer data when the buffer fills. Line buffered streams also transfer at every newline. Unbuffered streams pass everything on immediately. By default, files are fully buffered, stderr is unbuffered, and stdout is line buffered when it is a terminal and fully buffered otherwise.
#include <stdio.h> int setvbuf(FILE *restrict stream, char *restrict buf, int mode, size_t size); void setbuf(FILE *restrict stream, char *restrict buf);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
int setvbuf(FILE *restrict stream, char *restrict buf, int mode, size_t size); void setbuf(FILE *restrict stream, char *restrict buf);
| Name | Description |
|---|---|
stream |
An open stream on which no other operation has been done yet. |
buf |
Your buffer, or NULL to let the library allocate one. |
mode |
_IOFBF (full), _IOLBF (line) or _IONBF (none). |
size |
Size of buf in bytes; with NULL it is only a hint and may be ignored. |
Returns: 0 on success, non-zero if mode is invalid or the request cannot be honored.
setbuf(stream, buf) is the older form: with a buffer of at least BUFSIZ bytes it means setvbuf(stream, buf, _IOFBF, BUFSIZ), with NULL it turns buffering off. Prefer setvbuf(), which reports failure.
Errors / undefined behavior: calling it after any read or write on the stream is undefined behavior. A buffer that disappears (a local array whose function returned) while the stream is still open is undefined behavior: the buffer must live at least until fclose().
Usage notes
- Call it first. Right after
fopen(), or at the very start ofmain()for the standard streams, before anything is printed. - The buffer must outlive the stream. Use a
staticarray, a heap block, or an array in a scope that also closes the file. Closing the stream before the function ends is the simplest rule (as in the first example). - Unbuffered is slow for files. Every
fputc()becomes a system call. Use_IONBFonly for debugging output or interactive streams. - Line buffering for logs (
_IOLBF) is a good compromise when something else tails the file and you want whole lines to appear at once. - Interleaving
stdoutandstderr.stderris unbuffered andstdoutis not, so if both go to the same file or pipe their text can arrive out of order. Switchingstdoutto line buffering (or flushing) fixes the ordering. Seefflush(). - Output may still be buffered below C. Even an unbuffered C stream passes data to the operating system, which has its own cache.
- Larger buffers can speed up big sequential transfers, for example
setvbuf(f, NULL, _IOFBF, 1 << 16), but the gain is usually small compared with callingfread()on large blocks. - Input streams are buffered too;
_IONBFonstdinmakes the C library read one byte at a time, but a terminal still delivers whole lines in canonical mode.