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

> C++ Atlas: `cppatlas.com/w/cpp/io/basic_filebuf/setbuf` | Source: https://en.cppreference.com/w/cpp/io/basic_filebuf/setbuf | Domain: Input/output

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.

## Official Specification Summary (cppreference)

```cpp
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.

```cpp
#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';
}
```

Possible output:

```text
356010
```

### 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

- [`pubsetbuf`](https://en.cppreference.com/w/cpp/io/basic_streambuf/pubsetbuf): invokes `setbuf()` (public member function of `std::basic_streambuf<CharT,Traits>`)
- [`setvbuf`](https://en.cppreference.com/w/cpp/io/c/setvbuf): sets the buffer and its size for a file stream (function)

---
Attribution: content from https://en.cppreference.com/w/cpp/io/basic_filebuf/setbuf (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.