std::basic_filebuf<CharT,Traits>::setbuf

From cppreference.com
< cpp‎ | io‎ | basic filebuf
 
C++
 
Input/output library
I/O manipulators
Print functions (C++23)
C-style I/O
Buffers
(C++23)
(deprecated in C++98)
(C++20)
Streams
Abstractions
File I/O
String I/O
Array I/O
(C++23)
(C++23)
(C++23)
(deprecated in C++98)
(deprecated in C++98)
(deprecated in C++98)
Synchronized Output
(C++20)
Types
Error category interface
(C++11)
(C++11)
 
std::basic_filebuf
 
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 CharT in the user-provided buffer or null
n - the number of CharT elements 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

Provides 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';
}

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 173 C++98 the type of n was misspecified as int corrected to std::streamsize

See also

 invokes setbuf()
(public member function of std::basic_streambuf<CharT,Traits>)
sets the buffer and its size for a file stream
(function)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/io/basic_filebuf/setbuf&oldid=143610"