13.22. setbuf(), setvbuf()

Configure buffering for standard I/O operations

Prototypes

#include <stdio.h>
void setbuf(FILE *stream, char *buf);
int setvbuf(FILE *stream, char *buf, int mode, size_t size);

Description

Now brace yourself because this might come as a bit of a surprise to you: when you printf() or fprintf() or use any I/O functions like that, it does not normally work immediately. For the sake of efficiency, and to irritate you, the I/O on a FILE* stream is buffered away safely until certain conditions are met, and only then is the actual I/O performed. The functions setbuf() and setvbuf() allow you to change those conditions and the buffering behavior.

So what are the different buffering behaviors? The biggest is called "full buffering", wherein all I/O is stored in a big buffer until it is full, and then it is dumped out to disk (or whatever the file is). The next biggest is called "line buffering"; with line buffering, I/O is stored up a line at a time (until a newline ('\n') character is encountered) and then that line is processed. Finally, we have "unbuffered", which means I/O is processed immediately with every standard I/O call.

You might have seen and wondered why you could call putchar() time and time again and not see any output until you called putchar('\n'); that's right--stdout is line-buffered!

Since setbuf() is just a simplified version of setvbuf(), we'll talk about setvbuf() first.

The stream is the FILE* you wish to modify. The standard says you must make your call to setvbuf() before any I/O operation is performed on the stream, or else by then it might be too late.

The next argument, buf allows you to make your own buffer space (using malloc() or just a char array) to use for buffering. If you don't care to do this, just set buf to NULL.

Now we get to the real meat of the function: mode allows you to choose what kind of buffering you want to use on this stream. Set it to one of the following:

_IOFBF

stream will be fully buffered.

_IOLBF

stream will be line buffered.

_IONBF

stream will be unbuffered.

Finally, the size argument is the size of the array you passed in for buf...unless you passed NULL for buf, in which case it will resize the existing buffer to the size you specify.

Now what about this lesser function setbuf()? It's just like calling setvbuf() with some specific parameters, except setbuf() doesn't return a value. The following example shows the equivalency:

// these are the same:
setbuf(stream, buf);
setvbuf(stream, buf, _IOFBF, BUFSIZ); // fully buffered

// and these are the same:
setbuf(stream, NULL);
setvbuf(stream, NULL, _IONBF, BUFSIZ); // unbuffered

Return Value

setvbuf() returns zero on success, and nonzero on failure. setbuf() has no return value.

Example

FILE *fp;
char lineBuf[1024];

fp = fopen("somefile.txt", "r");
setvbuf(fp, lineBuf, _IOLBF, 1024);  // set to line buffering
// ...
fclose(fp);

fp = fopen("another.dat", "rb");
setbuf(fp, NULL); // set to unbuffered
// ...
fclose(fp);

See Also

fflush()