std::setvbuf(3)

💅 std::setvbuf(3) 💅

okay bestie, this page is from the C++ Standard Libary manual (yes, that spelling is in the header, we move 😭), and the main character is std::setvbuf — she changes how a file stream does its buffering. It's giving low-level stdio realness, no cap ✨

---

🌸 Synopsis 🌸

Defined in header <cstdio>:

int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );

So std::setvbuf changes the buffering mode of the file stream stream to whatever the argument mode says. In addition, here's the extra lore 💖

• If buffer is a null pointer, it resizes the internal buffer to size.
• If buffer is not a null pointer, it tells the stream to use the user-provided buffer of size size beginning at buffer. The stream must be closed (with std::fclose) before the lifetime of the array pointed to by buffer ends. The contents of the array after a successful call to std::setvbuf are indeterminate, and any attempt to use it is undefined behavior — like, absolutely do not, bestie 🫶

---

🎀 Parameters 🎀

• stream — the file stream to set the buffer to.
• buffer — pointer to a buffer for the stream to use, or a null pointer to change size and mode only.
• mode — the buffering mode to use. It can be one of these values:
  • _IOFBF — full buffering.
  • _IOLBF — line buffering.
  • _IONBF — no buffering.
• size — size of the buffer.

---

🔥 Return value 🔥

0 on success or nonzero on failure. That's it, that's the whole vibe check 💅

---

🫶 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. iykyk ⭐

---

🦋 Example 🦋

One use case for changing buffer size is when a better size is known. Okay, // Run this code era:

#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <sys/stat.h>

int main()
{
    std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
    if (!fp)
    {
        std::perror("fopen");
        return EXIT_FAILURE;
    }

    struct stat stats;
    if (fstat(fileno(fp), &stats) == -1) // POSIX only
    {
        std::perror("fstat");
        return EXIT_FAILURE;
    }

    std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
              << stats.st_blksize << '\n';
    if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0)
    {
        std::perror("setvbuf failed"); // POSIX version sets errno
        return EXIT_FAILURE;
    }

    // Read entire file: use truss/strace to observe the read(2) syscalls used
    for (int ch; (ch = std::fgetc(fp)) != EOF;)
    {}

    std::fclose(fp);
    return EXIT_SUCCESS;
}

---

⭐ Possible output ⭐

BUFSIZ is 8192, but optimal block size is 65536

---

🌈 See also 🌈

• setbuf — sets the buffer for a file stream (function).
• setbuf — provides user-supplied buffer or turns this filebuf unbuffered [virtual] (virtual protected member function of std::basic_filebuf<CharT,Traits>).
• C documentation for setvbuf — the C sibling, if you're feeling multilingual 💜

---

mwah 💖 this page is from http://cppreference.com, dated 2024.06.10, and it's literally page std::setvbuf(3) — slay.