std::basic_filebuf::close(3)

💖 NAME 💖

okay bestie, welcome to the manual page for std::basic_filebuf::close(3) from the C++ Standard Libary — yes, that's the spelling in the header and we're keeping it, no notes 😭✨

std::basic_filebuf::close — literally the name, and also std::basic_filebuf::close again. It's giving "the NAME line said it twice and we respect the hustle" 💅

---

✨ Synopsis ✨

std::basic_filebuf<CharT, Traits>* close();

So here's the tea: if a put area exists (like when the file was opened for writing), it first calls overflow(Traits::eof()) to write all pending output to the file, including any unshift sequences. 🫶

If the most recently called function out of underflow(), overflow(), seekpos(), and seekoff() was overflow(), then it calls std::codecvt::unshift(), maybe multiple times, to determine the unshift sequence according to the imbued locale, and writes that sequence to the file with overflow(Traits::eof()). ✨

Then it closes the file as if by calling std::fclose(), regardless of whether any of the preceding calls succeeded or failed. no cap.

If any of the function calls made, including the call to std::fclose(), fails, it returns a null pointer. If any of the function calls made throws an exception, the exception is caught and rethrown after closing the file. If the file is already closed, it returns a null pointer right away. 💀

In any case, it updates the private member variable that is accessed by is_open(). 👑

🎀 Parameters 🎀

• (none) — literally none, bestie. 🎀

🌸 Return value 🌸

• this on success
• a null pointer on failure

🦋 Notes 🦋

close() is typically called through the destructor of std::basic_filebuf (which, in turn, is typically called by the destructor of std::basic_fstream). so it's kind of a background main character, yk? 💜

⭐ Example ⭐

This section is incomplete Reason: no example 🙈

🌈 Defect reports 🌈

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. 📚

• DR LWG 443, applied to C++98 — behavior as published: the file was written using overflow(EOF); correct behavior: changed to overflow(Traits::eof()). 🔥
• DR LWG 622, applied to C++98 — behavior as published: it was unclear how to handle the exception thrown during closing; correct behavior: it is rethrown after closing the file. 💅

👀 See also 👀

• is_open — checks if the associated file is open (public member function)
• destructor — destructs a basic_filebuf object and closes the file if it is open [virtual] (virtual public member function)

🏷️ Category 🏷️

• * Todo no example

---

source/version: http://cppreference.com · date: 2024.06.10 · page: std::basic_filebuf::close(3) — bye bestie, mwah 💋🎀