NAME¶

std::setvbuf - std::setvbuf

Synopsis¶

Defined in header <cstdio>
int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );

Changes the buffering mode of the given file stream stream as indicated by the
argument mode. In addition,

* If buffer is a null pointer, resizes the internal buffer to size.
* If buffer is not a null pointer, instructs the stream to use the user-provided
buffer of size size beginning at buffer. The stream must be closed (with
std::fclose) before the lifetime of the array pointed to by buffer ends. The
contents of the array after a successful call to std::setvbuf are indeterminate
and any attempt to use it is undefined behavior.

Parameters¶

stream - the file stream to set the buffer to
buffer - pointer to a buffer for the stream to use or null pointer to change size
and mode only
buffering mode to use. It can be one of the following values:

mode - _IOFBF full buffering
_IOLBF line buffering
_IONBF no buffering
size - size of the buffer

Return value¶

0 on success or nonzero on failure.

Notes¶

This function may only be used after stream has been associated with an open file,
but before any other operation (other than a failed call to
std::setbuf/std::setvbuf).

Not all size bytes will necessarily be used for buffering: the actual buffer size is
usually rounded down to a multiple of 2, a multiple of page size, etc.

On many implementations, line buffering is only available for terminal input
streams.

A common error is setting the buffer of stdin or stdout to an array whose lifetime
ends before the program terminates:

int main() {
char buf[BUFSIZ];
std::setbuf(stdin, buf);
} // lifetime of buf ends, undefined behavior

The default buffer size BUFSIZ is expected to be the most efficient buffer size for
file I/O on the implementation, but POSIX fstat often provides a better estimate.

Example¶

one use case for changing buffer size is when a better size is known

// Run this code

#include <iostream>
#include <cstdio>
#include <cstdlib>
#include <sys/stat.h>

int main()
{
std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
if(!fp) {
std::perror("fopen"); return EXIT_FAILURE;
}

struct stat stats;
if(fstat(fileno(fp), &stats) == -1) { // POSIX only
std::perror("fstat"); return EXIT_FAILURE;
}

std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
<< stats.st_blksize << '\n';
if(std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0) {
std::perror("setvbuf failed"); // POSIX version sets errno
return EXIT_FAILURE;
}

// read entire file: use truss/strace
// to observe the read(2) syscalls used
for (int ch; (ch = std::fgetc(fp)) != EOF; ) {}

std::fclose(fp);
return EXIT_SUCCESS;
}

Possible output:¶

BUFSIZ is 8192, but optimal block size is 65536

See also¶

setbuf sets the buffer for a file stream
(function)
setbuf provides user-supplied buffer or turns this filebuf unbuffered
[virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>)