std::setvbuf

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Input/output library

I/O manipulators

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

strstreambuf (deprecated)

Streams

Abstractions

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

File I/O

basic_ifstream

basic_ofstream

basic_fstream

String I/O

basic_istringstream

basic_ostringstream

basic_stringstream

Array I/O

istrstream (deprecated)

ostrstream (deprecated)

strstream (deprecated)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

 

C-style I/O

Functions
File access
fopen freopen fclose fflush	fwide setbuf setvbuf
Direct input/output
fread
fwrite
Unformatted input/output
fgetc fgets fputc fputs getchar gets (until C++14) putchar puts ungetc	fgetwc fgetws fputwc fputws getwchar putwchar ungetwc
Formatted input/output
scanffscanfsscanf vscanfvfscanfvsscanf (C++11)(C++11)(C++11) printffprintfsprintfsnprintf (C++11) vprintfvfprintfvsprintfvsnprintf (C++11)	wscanffwscanfswscanf vwscanfvfwscanfvswscanf (C++11)(C++11)(C++11) wprintffwprintfswprintf vwprintfvfwprintfvswprintf
File positioning
ftell
fgetpos
fseek
fsetpos
rewind
Error handling
clearerr
feof
ferror
perror
Operations on files
remove
rename
tmpfile
tmpnam

 

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

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

• If buffer is a null pointer, resizes of 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 fclose) before the lifetime of the array pointed to by buffer ends. The contents of the array after a successful call to setvbuf are indeterminate and any attempt to use it is undefined behavior.

Parameters

stream	-	the file stream to set the buffer to or null pointer to change size and mode only
buffer	-	pointer to a buffer for the stream to use
mode	-	buffering mode to use. It can be one of the following values: _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 <stdlib.h>
#include <sys/stat.h>
 
int main()
{
    std::FILE* fp = std::fopen("test.txt", "r");
    if(!fp) {
       std::perror("fopen"); return 1;
    }
 
    struct stat stats;
    if(fstat(fileno(fp), &stats) == -1) { // POSIX only
        std::perror("fstat"); return 1;
    }
 
    std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
              << stats.st_blksize << '\n';
    if(std::setvbuf(fp, NULL, _IOFBF, stats.st_blksize) != 0) {
       perror("setvbuf failed"); // POSIX version sets errno
       return 1;
    }
 
    int ch;
    while((ch=std::fgetc(fp)) != EOF); // read entire file: use truss/strace to
                                       // observe the read(2) syscalls used
    std::fclose(fp);
}

Possible output:

BUFSIZ is 8192, but optimal block size is 65536

See also

setbuf	sets the buffer for a file stream (function)
setbuf [virtual]	provides user-supplied buffer or turns this filebuf unbuffered (virtual protected member function of std::basic_filebuf)
C documentation for setvbuf