27 Input/output library [input.output]

27.9 File-based streams [file.streams]

27.9.1 File streams [fstreams] Member functions [filebuf.members]

bool is_open() const;

Returns: true if a previous call to open succeeded (returned a non-null value) and there has been no intervening call to close.

basic_filebuf<charT,traits>* open(const char* s, ios_base::openmode mode);

Effects: If is_open() != false, returns a null pointer. Otherwise, initializes the filebuf as required. It then opens a file, if possible, whose name is the ntbs s (as if by calling std::fopen(s,modstr)). The ntbs modstr is determined from mode & ~ios_base::ate as indicated in Table [tab:iostreams.file.open.modes]. If mode is not some combination of flags shown in the table then the open fails.

Table 132 — File open modes
ios_base flag combination stdio equivalent
binary in out trunc app
+ "w"
+ + "a"
+ "a"
+ + "w"
+ "r"
+ + "r+"
+ + + "w+"
+ + + "a+"
+ + "a+"
+ + "wb"
+ + + "ab"
+ + "ab"
+ + + "wb"
+ + "rb"
+ + + "r+b"
+ + + + "w+b"
+ + + + "a+b"
+ + + "a+b"

If the open operation succeeds and (mode & ios_base::ate) != 0, positions the file to the end (as if by calling std::fseek(file,0,SEEK_END)).334

If the repositioning operation fails, calls close() and returns a null pointer to indicate failure.

Returns: this if successful, a null pointer otherwise.

basic_filebuf<charT,traits>* open(const string& s, ios_base::openmode mode);

Returns: open(s.c_str(), mode);

basic_filebuf<charT,traits>* close();

Effects: If is_open() == false, returns a null pointer. If a put area exists, calls overflow(traits::eof()) to flush characters. If the last virtual member function called on *this (between underflow, overflow, seekoff, and seekpos) was overflow then calls a_codecvt.unshift (possibly several times) to determine a termination sequence, inserts those characters and calls overflow(traits::eof()) again. Finally, regardless of whether any of the preceding calls fails or throws an exception, the function closes the file (as if by calling std::fclose(file)).335 If any of the calls made by the function, including std::fclose, fails, close fails by returning a null pointer. If one of these calls throws an exception, the exception is caught and rethrown after closing the file.

Returns: this on success, a null pointer otherwise.

Postcondition: is_open() == false.

The macro SEEK_END is defined, and the function signatures fopen(const char*, const char*) and fseek(FILE*, long, int) are declared, in <cstdio> ([c.files]).

The function signature fclose(FILE*) is declared in <cstdio> ([c.files]).