std::basic_filebuf::setbuf

 

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)

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)

 

std::basic_filebuf

Public member functions

basic_filebuf::basic_filebuf

basic_filebuf::~basic_filebuf

basic_filebuf::operator= (C++11)

basic_filebuf::swap (C++11)

basic_filebuf::is_open

basic_filebuf::open

basic_filebuf::close

Protected member functions

basic_filebuf::showmanyc

basic_filebuf::underflow

basic_filebuf::uflow

basic_filebuf::pbackfail

basic_filebuf::overflow

basic_filebuf::setbuf

basic_filebuf::seekoff

basic_filebuf::seekpos

basic_filebuf::sync

basic_filebuf::imbue

Non-member functions

swap(std::basic_filebuf) (C++11)

 

protected: virtual std::basic_streambuf<CharT, Traits>* setbuf( char_type* s, std::streamsize n )

If s is a null pointer and n is zero, the filebuf becomes unbuffered for output, meaning pbase() and pptr() are null and any output is immediately sent to file.

Otherwise, a call to setbuf() replaces the internal buffer (the controlled character sequence) with the user-supplied character array whose first element is pointed to by s and allows this std::basic_filebuf object to use up to n bytes in that array for buffering.

This function is protected virtual, it may only be called through pubsetbuf() or from member functions of a user-defined class derived from std::basic_filebuf.

Parameters

s	-	pointer to the first byte in the user-provided buffer or null
n	-	the number of bytes in the user-provided buffer or zero

Return value

this.

Notes

The conditions when this function may be used and the way in which the provided buffer is used is implementation-defined.

• GCC 4.6 libstdc++

setbuf() may only be called when the std::basic_filebuf is not associated with a file (has no effect otherwise). With a user-provided buffer, reading from file reads n-1 bytes at a time.

• Clang++3.0 libc++

setbuf() may be called after opening the file, but before any I/O (may crash otherwise). With a user-provided buffer, reading from file reads largest multiples of 4096 that fit in the buffer.

• Visual Studio 2010

setbuf() may be called at any time, even after some I/O took place. Current contents of the buffer, if any, are lost.

The standard does not define any behavior for this function except that setbuf(0, 0) called before any I/O has taken place is required to set unbuffered output.

Example

provide a 10k buffer for reading. On linux, the strace utility may be used to observe the actual number of bytes read

Run this code

#include <fstream>
#include <iostream>
#include <string>
 
int main()
{
        int cnt = 0;
        std::ifstream file;
        char buf[10241];
 
        file.rdbuf()->pubsetbuf(buf, sizeof buf);
        file.open("/usr/share/dict/words");
 
        for (std::string line; getline(file, line); )
                ++cnt;
        std::cout << cnt << '\n';
}

See also

pubsetbuf	invokes setbuf() (public member function of std::basic_streambuf)
setvbuf	sets the buffer and its size for a file stream (function)