std::basic_fstream::open(3)

💅 std::basic_fstream::open(3) 💅

okay so we're on the C++ Standard Libary shelf of the manual (spelled exactly like that in the header, no cap 😭🫶). This page is all about std::basic_fstream::open, and it's basically the "attach this file stream to a file" moment. iconic. ✨

🌸 NAME 🌸

std::basic_fstream::open — std::basic_fstream::open (yes bestie, the NAME section really said it twice, and honestly? slay 💅).

✨ Synopsis ✨

Here are the overloads, defaults included. Do not lose the defaults, they are lowkey the whole vibe:

          void open( const char* filename,

                     std::ios_base::openmode mode                       (1)

                         = std::ios_base::in | std::ios_base::out );
          void open( const std::filesystem::path::value_type* filename,

                     std::ios_base::openmode mode                       (2)
       (since C++17)

                         = std::ios_base::in | std::ios_base::out );
          void open( const std::string& filename,

                     std::ios_base::openmode mode                       (3)
       (since C++11)

                         = std::ios_base::in | std::ios_base::out );
          void open( const std::filesystem::path& filename,

                     std::ios_base::openmode mode                       (4)
       (since C++17)

                         = std::ios_base::in | std::ios_base::out );

This opens the file with name filename and associates it with the file stream. On success it calls clear(). On failure it calls setstate(failbit). 🫶

• Overloads (1) and (2): effectively call rdbuf()->open(filename, mode) — see std::basic_filebuf::open for the details on the effects of that call. Overload (2) is only provided if std::filesystem::path::value_type is not char. (since C++17)
• Overloads (3) and (4): effectively call (1,2) as if by open(filename.c_str(), mode).

🎀 Parameters 🎀

• filename — the name of the file to be opened.
• mode — specifies stream open mode. It is a BitmaskType; the following constants are defined:
  • app — seek to the end of stream before each write
  • binary — open in binary mode
  • in — open for reading
  • out — open for writing
  • trunc — discard the contents of the stream when opening
  • ate — seek to the end of stream immediately after open
  • noreplace (C++23) — open in exclusive mode

💖 Return value 💖

(none) — literally nothing, bestie. That's the whole answer. 💀

🦋 Example 🦋

       // Run this code

        #include <fstream>
        #include <iostream>
        #include <string>

        int main()
        {
            std::string filename = "example.123";

            std::fstream fs;
            fs.open(filename);

            if (!fs.is_open())
            {
                fs.clear();
                fs.open(filename, std::ios::out); // create file
                fs.close();
                fs.open(filename);
            }

            std::cout << std::boolalpha;
            std::cout << "fs.is_open() = " << fs.is_open() << '\n';
            std::cout << "fs.good() = " << fs.good() << '\n';
        }

🔥 Defect reports 🔥

These behavior-changing defect reports were applied retroactively to previously published C++ standards, and yes they ate:

• DR LWG 22 — Applied to: C++98. Behavior as published: it was unclear how error state changes upon a successful open. Correct behavior: the error state is unchanged.
• DR LWG 409 — Applied to: C++98. Behavior as published: the error state was unchanged upon a successful open. Correct behavior: it is cleared^[1].
• DR LWG 460 — Applied to: C++98. Behavior as published: the default argument of mode in overload (1) was missing (it is present in the synopsis). Correct behavior: added.
• ^[1] The resolution of LWG issue #22 is overriden.

🌈 See also 🌈

• is_open — checks if the stream has an associated file (public member function)
• close — closes the associated file (public member function)
• open — opens a file and configures it as the associated character sequence (public member function of std::basic_filebuf<CharT,Traits>)

okay that's the whole page, bestie! cute little footer tea for you: source/version is http://cppreference.com, date is 2024.06.10, and the page is std::basic_fstream::open(3). bye 💖🦋✨