std::basic_filebuf::setbuf(3)

std::basic_filebuf::setbuf(3)

okay so bestie, this page comes from the C++ Standard Libary (yep, that's the spelling in the header — iconic typo energy, no cap 💀). It's all about std::basic_filebuf::setbuf, and it's giving protected-virtual-buffer makeover energy — highkey iconic. Let's go ✨💅

---

🌸 NAME 🌸

std::basic_filebuf::setbuf - std::basic_filebuf::setbuf

That's it. That's the name. We move. 🫶

🦋 Synopsis 🦋

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

So here's the tea: 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. periodt 💖

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 it allows this std::basic_filebuf object to use up to n bytes in that array for buffering. slay ✨

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

💖 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

literally just this — obsessed with the main character energy. 💅

🔥 Notes 🔥

Vibe check: the conditions when this function may be used and the way in which the provided buffer is used is implementation-defined. So yes, bestie, your implementation gets a vote. 🗳️

• 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.

⚠️ "may crash otherwise" is not a drill, bestie. Do not test it for fun. 💀

• 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. That's the one guaranteed lil' thing. periodt 🌈

🌸 Example 🌸

Provides a 10k buffer for reading. On linux, the strace utility may be used to observe the actual number of bytes read. nerd sniping, but make it cute 🔍

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

🍓 Possible output 🍓

356010

👑 Defect reports 👑

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. retroactive lore drop, honestly. 📜

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

🌈 See also 🌈

• pubsetbuf — invokes setbuf() (public member function of std::basic_streambuf<CharT,Traits>)
• setvbuf — sets the buffer and its size for a file stream (function)

---

mwah 💋 — source/version/date: http://cppreference.com, 2024.06.10, std::basic_filebuf::setbuf(3). Byeee 🫶 fr fr