std::basic_filebuf::open(3)

💖 std::basic_filebuf::open 💖

Okay bestie, buckle up — this is std::basic_filebuf::open from the C++ Standard Libary (section 3, mwah), and it's literally the function that makes files exist in your program's world. Lowkey iconic. Let's get into it 🫶

---

🌸 SYNOPSIS 🌸

basic_filebuf* open( const char* s, std::ios_base::openmode mode );
basic_filebuf* open( const std::string& str,
                     std::ios_base::openmode mode );
basic_filebuf* open( const std::filesystem::path& p,
                     std::ios_base::openmode mode );
basic_filebuf* open( const std::filesystem::path::value_type* s,
                     std::ios_base::openmode mode );

The tea on which overload landed when ☕:

• (1) — the const char* s one, the OG 💅
• (2) — the const std::string& str one, since C++11 ✨
• (3) — the const std::filesystem::path& p one, since C++17 🌈
• (4) — the const std::filesystem::path::value_type* s one, since C++17 🦋

---

💫 DESCRIPTION 💫

First vibe check: if the associated file was already open (is_open() != false), it returns a null pointer right away. No drama, no retry, just nope 🙈.

Otherwise, it opens the file with the given name — that's s, p.c_str() (since C++17), or str.c_str(), depending on which overload you took. And hey, std::ios_base::openmode values may be written as, e.g., std::ios_base::out | std::ios_base::app — OR them together, that's the whole aesthetic 🔥

Real talk: overload (4) is only provided if std::filesystem::path::value_type is not char. (since C++17) Not every platform, not every day. Periodt.

The file is opened as if by calling std::fopen with the second argument (the file access mode) determined by the result of mode & ~std::ios_base::ate as follows — and heads up, open() fails if the result is not some combination of flags shown in the table 🎀

The six flag columns are, in order: binary, in, out, trunc, app, noreplace (that last one is since C++23). The dance goes:

When the fopen access mode is "r" — action if file already exists: Read from start / if it does not exist: Failure to open

• - + - - - - → "r"
• + + - - - - → "rb"

When it's "r+" — action if file already exists: Read from start / if it does not exist: Error

• - + + - - - → "r+"
• + + + - - - → "r+b"

When it's "w" — action if file already exists: Destroy contents / if it does not exist: Create new

• - - + - - - → "w"
• - - + + - -
• + - + - - - → "wb"
• + - + + - -
• - + + + - - → "w+"
• + + + + - - → "w+b"

When it's "wx" — action if file already exists: Failure to open / if it does not exist: Create new

• - - + - - + → "wx"
• - - + + - +
• + - + - - + → "wbx"
• + - + + - +
• - + + + - + → "w+x"
• + + + + - + → "w+bx"

When it's "a" — action if file already exists: Write to end / if it does not exist: Create new

• - - + - + - → "a"
• - - - - + -
• + - + - + - → "ab"
• + - - - + -
• - + + - + - → "a+"
• - + - - + -
• + + + - + - → "a+b"
• + + - - + -

✨ And now the ate moment: if the open operation succeeds and (openmode & std::ios_base::ate) != 0 (the ate bit is set), it repositions the file position to the end of file, as if by calling std::fseek(file, 0, SEEK_END), where file is the pointer returned by calling std::fopen. And if that repositioning fails? It calls close() and returns a null pointer to indicate failure 😭 The audacity, honestly.

---

🎀 PARAMETERS 🎀

• s, str, p — the file name to open; s must point to a null-terminated string (no playing around with that one, bestie)
• openmode — the file opening mode, a binary OR of the std::ios_base::openmode modes

---

✨ RETURN VALUE ✨

this on success, a null pointer on failure. That's it. That's the whole personality 💅

---

🦋 NOTES 🦋

open() is typically called through the constructor or the open() member function of std::basic_fstream. So like, you'll meet it through a friend, yk? 👑

---

🍓 EXAMPLE 🍓

// Run this code

#include <fstream>
#include <iostream>

int main()
{
    std::string filename = "Test.b";
    std::filebuf fb;

    // prepare a file to read
    double d = 3.14;
    if (!fb.open(filename, std::ios::binary | std::ios::out))
    {
        std::cout << "Open file " << filename << " for write failed\n";
        return 1;
    }
    fb.sputn(reinterpret_cast<char*>(&d), sizeof d);
    fb.close();

    // open file for reading
    double d2 = 0.0;
    if (!fb.open(filename, std::ios::binary | std::ios::in))
    {
        std::cout << "Open file " << filename << " for read failed\n";
        return 1;
    }

    auto got = fb.sgetn(reinterpret_cast<char*>(&d2), sizeof d2);
    if (sizeof(d2) != got)
        std::cout << "Read of " << filename << " failed\n";
    else
        std::cout << "Read back from file: " << d2 << '\n';
}

Output:

Read back from file: 3.14

She wrote it, she read it back, she ate. No crumbs. 🍽️✨

---

💅 DEFECT REPORTS 💅

The following behavior-changing defect reports were applied retroactively to previously published C++ standards — yes, they went back and fixed the lore 🙈

• LWG 596 — Applied to C++98 — behavior as published: open() could not open files in append mode. Correct behavior: can open in append mode. Glow-up of the century, honestly 🔥

---

🔥 SEE ALSO 🔥

• is_open — checks if the associated file is open (public member function) 👀
• close — flushes the put area buffer and closes the associated file (public member function) 🚪

---

Okay that's the whole page, bestie! Sourced straight from cppreference.com and dated 2024.06.10, and yeah, the page is std::basic_filebuf::open(3) — go open some files, but, like, responsibly 💖🎀🦋