depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cppdraft_translate/cppdraft/file/streams.md
Leonov Artur (Depish) 043225d523 Init
2025-10-25 03:02:53 +03:00

1468 lines
61 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[file.streams]
# 31 Input/output library [[input.output]](./#input.output)
## 31.10 File-based streams [file.streams]
### [31.10.1](#fstream.syn) Header <fstream> synopsis [[fstream.syn]](fstream.syn)
[🔗](#header:%3cfstream%3e)
namespace std {// [[filebuf]](#filebuf "31.10.3 Class template basic_­filebuf"), class template basic_filebuftemplate<class charT, class traits = char_traits<charT>>class basic_filebuf; template<class charT, class traits>void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y); using filebuf = basic_filebuf<char>; using wfilebuf = basic_filebuf<wchar_t>; // [[ifstream]](#ifstream "31.10.4 Class template basic_­ifstream"), class template basic_ifstreamtemplate<class charT, class traits = char_traits<charT>>class basic_ifstream; template<class charT, class traits>void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y); using ifstream = basic_ifstream<char>; using wifstream = basic_ifstream<wchar_t>; // [[ofstream]](#ofstream "31.10.5 Class template basic_­ofstream"), class template basic_ofstreamtemplate<class charT, class traits = char_traits<charT>>class basic_ofstream; template<class charT, class traits>void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y); using ofstream = basic_ofstream<char>; using wofstream = basic_ofstream<wchar_t>; // [[fstream]](#fstream "31.10.6 Class template basic_­fstream"), class template basic_fstreamtemplate<class charT, class traits = char_traits<charT>>class basic_fstream; template<class charT, class traits>void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y); using fstream = basic_fstream<char>; using wfstream = basic_fstream<wchar_t>;}
[1](#fstream.syn-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10928)
The header [<fstream>](#header:%3cfstream%3e "31.10.1 Header <fstream> synopsis [fstream.syn]") defines four class templates and eight types
that associate stream buffers with files and assist
reading and writing files[.](#fstream.syn-1.sentence-1)
[2](#fstream.syn-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10934)
[*Note [1](#fstream.syn-note-1)*:
The class template basic_filebuf treats a file as a source or
sink of bytes[.](#fstream.syn-2.sentence-1)
In an environment that uses a large character set, the file
typically holds multibyte character sequences and the basic_filebuf object converts those multibyte sequences into wide character sequences[.](#fstream.syn-2.sentence-2)
— *end note*]
[3](#fstream.syn-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10942)
In subclause [file.streams], member functions taking arguments of const filesystem​::​path​::​value_type* are only provided on systems where filesystem​::​path​::​value_type ([[fs.class.path]](fs.class.path "31.12.6 Class path")) is not char[.](#fstream.syn-3.sentence-1)
[*Note [2](#fstream.syn-note-2)*:
These functions enable class path support for systems with a wide native path character type, such as wchar_t[.](#fstream.syn-3.sentence-2)
— *end note*]
### [31.10.2](#file.native) Native handles [[file.native]](file.native)
[1](#file.native-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10953)
Several classes described in [file.streams]
have a member native_handle_type[.](#file.native-1.sentence-1)
[2](#file.native-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10957)
The type native_handle_type represents a platform-specific[*native handle*](#def:handle,native "31.10.2 Native handles [file.native]") to a file[.](#file.native-2.sentence-1)
It is trivially copyable and models [semiregular](concepts.object#concept:semiregular "18.6 Object concepts [concepts.object]")[.](#file.native-2.sentence-2)
[*Note [1](#file.native-note-1)*:
For operating systems based on POSIX,native_handle_type is int[.](#file.native-2.sentence-3)
For Windows-based operating systems,native_handle_type is HANDLE[.](#file.native-2.sentence-4)
— *end note*]
### [31.10.3](#filebuf) Class template basic_filebuf [[filebuf]](filebuf)
#### [31.10.3.1](#filebuf.general) General [[filebuf.general]](filebuf.general)
[🔗](#lib:basic_filebuf)
namespace std {template<class charT, class traits = char_traits<charT>>class basic_filebuf : public basic_streambuf<charT, traits> {public:using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using native_handle_type = *implementation-defined*; // see [[file.native]](#file.native "31.10.2 Native handles")// [[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors"), constructors/destructor basic_filebuf();
basic_filebuf(const basic_filebuf&) = delete;
basic_filebuf(basic_filebuf&& rhs); virtual ~basic_filebuf(); // [[filebuf.assign]](#filebuf.assign "31.10.3.3 Assignment and swap"), assignment and swap basic_filebuf& operator=(const basic_filebuf&) = delete;
basic_filebuf& operator=(basic_filebuf&& rhs); void swap(basic_filebuf& rhs); // [[filebuf.members]](#filebuf.members "31.10.3.4 Member functions"), membersbool is_open() const;
basic_filebuf* open(const char* s, ios_base::openmode mode);
basic_filebuf* open(const filesystem::path::value_type* s,
ios_base::openmode mode); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis") basic_filebuf* open(const string& s, ios_base::openmode mode);
basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
basic_filebuf* close();
native_handle_type native_handle() const noexcept; protected:// [[filebuf.virtuals]](#filebuf.virtuals "31.10.3.5 Overridden virtual functions"), overridden virtual functions streamsize showmanyc() override;
int_type underflow() override;
int_type uflow() override;
int_type pbackfail(int_type c = traits::eof()) override;
int_type overflow (int_type c = traits::eof()) override;
basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n) override;
pos_type seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which = ios_base::in | ios_base::out) override;
pos_type seekpos(pos_type sp,
ios_base::openmode which = ios_base::in | ios_base::out) override; int sync() override; void imbue(const locale& loc) override; };}
[1](#filebuf.general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11028)
The classbasic_filebuf<charT, traits> associates both the input sequence and the output
sequence with a file[.](#filebuf.general-1.sentence-1)
[2](#filebuf.general-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11034)
The restrictions on reading and writing a sequence controlled by an
object of classbasic_filebuf<charT, traits> are the same as for reading and writing with the C standard libraryFILEs[.](#filebuf.general-2.sentence-1)
[3](#filebuf.general-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11041)
In particular:
- [(3.1)](#filebuf.general-3.1)
If the file is not open for reading the input sequence
cannot be read[.](#filebuf.general-3.1.sentence-1)
- [(3.2)](#filebuf.general-3.2)
If the file is not open for writing the output
sequence cannot be written[.](#filebuf.general-3.2.sentence-1)
- [(3.3)](#filebuf.general-3.3)
A joint file position is maintained for both the input sequence and
the output sequence[.](#filebuf.general-3.3.sentence-1)
[4](#filebuf.general-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11055)
An instance ofbasic_filebuf behaves as described in [[filebuf]](#filebuf "31.10.3 Class template basic_­filebuf") providedtraits​::​pos_type isfpos<traits​::​​state_type>[.](#filebuf.general-4.sentence-1)
Otherwise the behavior is undefined[.](#filebuf.general-4.sentence-2)
[5](#filebuf.general-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11064)
The file associated with a basic_filebuf has
an associated value of type native_handle_type,
called the native handle ([[file.native]](#file.native "31.10.2 Native handles")) of that file[.](#filebuf.general-5.sentence-1)
This native handle can be obtained by calling
the member function native_handle[.](#filebuf.general-5.sentence-2)
[6](#filebuf.general-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11071)
For any opened basic_filebuf f,
the native handle returned by f.native_handle() is
invalidated when f.close() is called, or f is destroyed[.](#filebuf.general-6.sentence-1)
[7](#filebuf.general-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11076)
In order to support file I/O and multibyte/wide character conversion,
conversions are performed using members of a facet, referred to asa_codecvt in following subclauses, obtained as if byconst codecvt<charT, char, typename traits::state_type>& a_codecvt = use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
#### [31.10.3.2](#filebuf.cons) Constructors [[filebuf.cons]](filebuf.cons)
[🔗](#lib:basic_filebuf,constructor)
`basic_filebuf();
`
[1](#filebuf.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11093)
*Effects*: Initializes the base class withbasic_streambuf<charT, traits>() ([[streambuf.cons]](streambuf.cons "31.6.3.2 Constructors"))[.](#filebuf.cons-1.sentence-1)
[2](#filebuf.cons-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11098)
*Postconditions*: is_open() == false[.](#filebuf.cons-2.sentence-1)
[🔗](#lib:basic_filebuf,constructor_)
`basic_filebuf(basic_filebuf&& rhs);
`
[3](#filebuf.cons-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11109)
*Effects*: It is implementation-defined whether the sequence pointers in *this (eback(), gptr(), egptr(),pbase(), pptr(), epptr()) obtain
the values which rhs had[.](#filebuf.cons-3.sentence-1)
Whether they do or not, *this and rhs reference separate buffers (if any at all) after the
construction[.](#filebuf.cons-3.sentence-2)
Additionally *this references the file
which rhs did before the construction, andrhs references no file after the construction[.](#filebuf.cons-3.sentence-3)
The
openmode, locale and any other state of rhs is also
copied[.](#filebuf.cons-3.sentence-4)
[4](#filebuf.cons-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11123)
*Postconditions*: Let rhs_p refer to the state ofrhs just prior to this construction and let rhs_a refer to the state of rhs just after this construction[.](#filebuf.cons-4.sentence-1)
- [(4.1)](#filebuf.cons-4.1)
is_open() == rhs_p.is_open()
- [(4.2)](#filebuf.cons-4.2)
rhs_a.is_open() == false
- [(4.3)](#filebuf.cons-4.3)
gptr() - eback() == rhs_p.gptr() - rhs_p.eback()
- [(4.4)](#filebuf.cons-4.4)
egptr() - eback() == rhs_p.egptr() - rhs_p.eback()
- [(4.5)](#filebuf.cons-4.5)
pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()
- [(4.6)](#filebuf.cons-4.6)
epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()
- [(4.7)](#filebuf.cons-4.7)
if (eback()) eback() != rhs_a.eback()
- [(4.8)](#filebuf.cons-4.8)
if (gptr()) gptr() != rhs_a.gptr()
- [(4.9)](#filebuf.cons-4.9)
if (egptr()) egptr() != rhs_a.egptr()
- [(4.10)](#filebuf.cons-4.10)
if (pbase()) pbase() != rhs_a.pbase()
- [(4.11)](#filebuf.cons-4.11)
if (pptr()) pptr() != rhs_a.pptr()
- [(4.12)](#filebuf.cons-4.12)
if (epptr()) epptr() != rhs_a.epptr()
[🔗](#lib:basic_filebuf,destructor)
`virtual ~basic_filebuf();
`
[5](#filebuf.cons-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11151)
*Effects*: Callsclose()[.](#filebuf.cons-5.sentence-1)
If an exception occurs during the destruction of the object, including the call to close(), the exception is caught but not rethrown (see [[res.on.exception.handling]](res.on.exception.handling "16.4.6.14 Restrictions on exception handling"))[.](#filebuf.cons-5.sentence-2)
#### [31.10.3.3](#filebuf.assign) Assignment and swap [[filebuf.assign]](filebuf.assign)
[🔗](#lib:operator=,basic_filebuf)
`basic_filebuf& operator=(basic_filebuf&& rhs);
`
[1](#filebuf.assign-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11166)
*Effects*: Calls close() then move assigns from rhs[.](#filebuf.assign-1.sentence-1)
After the
move assignment *this has the observable state it would have had if it
had been move constructed from rhs (see [[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors"))[.](#filebuf.assign-1.sentence-2)
[2](#filebuf.assign-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11172)
*Returns*: *this[.](#filebuf.assign-2.sentence-1)
[🔗](#lib:swap,basic_filebuf)
`void swap(basic_filebuf& rhs);
`
[3](#filebuf.assign-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11183)
*Effects*: Exchanges the state of *this and rhs[.](#filebuf.assign-3.sentence-1)
[🔗](#lib:swap,basic_filebuf_)
`template<class charT, class traits>
void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
`
[4](#filebuf.assign-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11196)
*Effects*: Equivalent to x.swap(y)[.](#filebuf.assign-4.sentence-1)
#### [31.10.3.4](#filebuf.members) Member functions [[filebuf.members]](filebuf.members)
[🔗](#lib:is_open,basic_filebuf)
`bool is_open() const;
`
[1](#filebuf.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11209)
*Returns*: true if a previous call toopen succeeded (returned a non-null value) and there has been no intervening
call to close[.](#filebuf.members-1.sentence-1)
[🔗](#lib:open,basic_filebuf)
`basic_filebuf* open(const char* s, ios_base::openmode mode);
basic_filebuf* open(const filesystem::path::value_type* s,
ios_base::openmode mode); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[2](#filebuf.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11226)
*Preconditions*: s points to an NTCTS ([[defns.ntcts]](defns.ntcts "3.36 NTCTS"))[.](#filebuf.members-2.sentence-1)
[3](#filebuf.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11230)
*Effects*: Ifis_open() != false,
returns a null pointer[.](#filebuf.members-3.sentence-1)
Otherwise,
initializes thefilebuf as required[.](#filebuf.members-3.sentence-2)
It then opens
the file to which s resolves, if possible,
as if by a call to fopenwith the second argument determined frommode & ~ios_base​::​ate as indicated in Table [146](#tab:filebuf.open.modes "Table 146: File open modes")[.](#filebuf.members-3.sentence-3)
If mode is not some combination of flags shown in the table then
the open fails[.](#filebuf.members-3.sentence-4)
Table [146](#tab:filebuf.open.modes) — File open modes [[tab:filebuf.open.modes]](./tab:filebuf.open.modes)
| [🔗](#tab:filebuf.open.modes-row-1)<br>ios_base flag combination | | | | | | stdio equivalent |
| --- | --- | --- | --- | --- | --- | --- |
| [🔗](#tab:filebuf.open.modes-row-2)<br>binary | in | out | trunc | app | noreplace |
| [🔗](#tab:filebuf.open.modes-row-3) | | + | | | | "w" |
| [🔗](#tab:filebuf.open.modes-row-4) | | + | | | + | "wx" |
| [🔗](#tab:filebuf.open.modes-row-5) | | + | + | | | "w" |
| [🔗](#tab:filebuf.open.modes-row-6) | | + | + | | + | "wx" |
| [🔗](#tab:filebuf.open.modes-row-7) | | + | | + | | "a" |
| [🔗](#tab:filebuf.open.modes-row-8) | | | | + | | "a" |
| [🔗](#tab:filebuf.open.modes-row-9) | + | | | | | "r" |
| [🔗](#tab:filebuf.open.modes-row-10) | + | + | | | | "r+" |
| [🔗](#tab:filebuf.open.modes-row-11) | + | + | + | | | "w+" |
| [🔗](#tab:filebuf.open.modes-row-12) | + | + | + | | + | "w+x" |
| [🔗](#tab:filebuf.open.modes-row-13) | + | + | | + | | "a+" |
| [🔗](#tab:filebuf.open.modes-row-14) | + | | | + | | "a+" |
| [🔗](#tab:filebuf.open.modes-row-15)<br>+ | | + | | | | "wb" |
| [🔗](#tab:filebuf.open.modes-row-16)<br>+ | | + | | | + | "wbx" |
| [🔗](#tab:filebuf.open.modes-row-17)<br>+ | | + | + | | | "wb" |
| [🔗](#tab:filebuf.open.modes-row-18)<br>+ | | + | + | | + | "wbx" |
| [🔗](#tab:filebuf.open.modes-row-19)<br>+ | | + | | + | | "ab" |
| [🔗](#tab:filebuf.open.modes-row-20)<br>+ | | | | + | | "ab" |
| [🔗](#tab:filebuf.open.modes-row-21)<br>+ | + | | | | | "rb" |
| [🔗](#tab:filebuf.open.modes-row-22)<br>+ | + | + | | | | "r+b" |
| [🔗](#tab:filebuf.open.modes-row-23)<br>+ | + | + | + | | | "w+b" |
| [🔗](#tab:filebuf.open.modes-row-24)<br>+ | + | + | + | | + | "w+bx" |
| [🔗](#tab:filebuf.open.modes-row-25)<br>+ | + | + | | + | | "a+b" |
| [🔗](#tab:filebuf.open.modes-row-26)<br>+ | + | | | + | | "a+b" |
[4](#filebuf.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11280)
If the open operation succeeds andios_base​::​ate is set in mode,
positions the file to the end
(as if by calling fseek(file, 0, SEEK_END), wherefile is the pointer returned by calling fopen)[.](#filebuf.members-4.sentence-1)[292](#footnote-292 "The macro SEEK_­END is defined, and the function signatures fopen(const char*, const char*) and fseek(FILE*, long, int) are declared, in <cstdio>.")
[5](#filebuf.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11297)
If the repositioning operation fails, callsclose() and returns a null pointer to indicate failure[.](#filebuf.members-5.sentence-1)
[6](#filebuf.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11302)
*Returns*: this if successful, a null pointer otherwise[.](#filebuf.members-6.sentence-1)
[🔗](#lib:open,basic_filebuf_)
`basic_filebuf* open(const string& s, ios_base::openmode mode);
basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
`
[7](#filebuf.members-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11315)
*Returns*: open(s.c_str(), mode);
[🔗](#lib:close,basic_filebuf)
`basic_filebuf* close();
`
[8](#filebuf.members-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11326)
*Effects*: Ifis_open() == false,
returns a null pointer[.](#filebuf.members-8.sentence-1)
If a put area exists, callsoverflow(traits​::​​eof()) to flush characters[.](#filebuf.members-8.sentence-2)
If the last virtual member function called on*this (betweenunderflow,overflow,seekoff,
andseekpos)
wasoverflow then callsa_codecvt.unshift (possibly several times) to determine a termination sequence, inserts those
characters and callsoverflow(traits​::​​eof()) again[.](#filebuf.members-8.sentence-3)
Finally, regardless of whether any of the preceding calls fails or throws an
exception, the function closes the file
(as if by callingfclose(file))[.](#filebuf.members-8.sentence-4)
If any of the calls made by the function, including fclose, fails,close fails by returning a null pointer[.](#filebuf.members-8.sentence-5)
If one of these calls throws an
exception, the exception is caught and rethrown after closing the file[.](#filebuf.members-8.sentence-6)
[9](#filebuf.members-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11359)
*Postconditions*: is_open() == false[.](#filebuf.members-9.sentence-1)
[10](#filebuf.members-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11363)
*Returns*: this on success, a null pointer otherwise[.](#filebuf.members-10.sentence-1)
[🔗](#lib:native_handle,basic_filebuf)
`native_handle_type native_handle() const noexcept;
`
[11](#filebuf.members-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11375)
*Preconditions*: is_open() is true[.](#filebuf.members-11.sentence-1)
[12](#filebuf.members-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11379)
*Returns*: The native handle associated with *this[.](#filebuf.members-12.sentence-1)
[292)](#footnote-292)[292)](#footnoteref-292)
The macro SEEK_END is defined, and the function signaturesfopen(const char*, const char*) andfseek(FILE*, long, int)are declared, in [<cstdio>](cstdio.syn#header:%3ccstdio%3e "31.13.1 Header <cstdio> synopsis [cstdio.syn]")[.](#footnote-292.sentence-1)
#### [31.10.3.5](#filebuf.virtuals) Overridden virtual functions [[filebuf.virtuals]](filebuf.virtuals)
[🔗](#lib:showmanyc,basic_filebuf)
`streamsize showmanyc() override;
`
[1](#filebuf.virtuals-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11392)
*Effects*: Behaves the same asbasic_streambuf​::​showmanyc() ([[streambuf.virtuals]](streambuf.virtuals "31.6.3.5 Virtual functions"))[.](#filebuf.virtuals-1.sentence-1)
[2](#filebuf.virtuals-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11398)
*Remarks*: An
implementation may provide an overriding definition for this function
signature if it can determine whether more characters can be read from the input
sequence[.](#filebuf.virtuals-2.sentence-1)
[🔗](#lib:underflow,basic_filebuf)
`int_type underflow() override;
`
[3](#filebuf.virtuals-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11412)
*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​underflow(),
with the specialization that a sequence of characters is read from the input
sequence as if by reading from the associated file
into an internal buffer (extern_buf)
and then as if by doing:char extern_buf[XSIZE];char* extern_end;
charT intern_buf[ISIZE];
charT* intern_end;
codecvt_base::result r = a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
intern_buf, intern_buf+ISIZE, intern_end);
This shall be done in such a way that the class can recover the
position
(fpos_t)
corresponding to each character betweenintern_buf andintern_end[.](#filebuf.virtuals-3.sentence-2)
If the value ofr indicates thata_codecvt.in() ran out of space inintern_buf,
retry with a largerintern_buf[.](#filebuf.virtuals-3.sentence-3)
[🔗](#lib:uflow,basic_filebuf)
`int_type uflow() override;
`
[4](#filebuf.virtuals-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11453)
*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​uflow(),
with the specialization that a sequence of characters is read from the input
with the same method as used byunderflow[.](#filebuf.virtuals-4.sentence-1)
[🔗](#lib:pbackfail,basic_filebuf)
`int_type pbackfail(int_type c = traits::eof()) override;
`
[5](#filebuf.virtuals-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11468)
*Effects*: Puts back the character designated by c to the input
sequence, if possible, in one of three ways:
- [(5.1)](#filebuf.virtuals-5.1)
Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and
if the function makes a putback position available
and iftraits​::​eq(to_char_type(c), gptr()[-1]) returnstrue,
decrements the next pointer for the input sequence,gptr()[.](#filebuf.virtuals-5.1.sentence-1)
Returns:c[.](#filebuf.virtuals-5.1.sentence-2)
- [(5.2)](#filebuf.virtuals-5.2)
Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and
if the function makes a putback position available
and if the function is permitted to assign to the putback position,
decrements the next pointer for the input sequence,
and stores c there[.](#filebuf.virtuals-5.2.sentence-1)
Returns:c[.](#filebuf.virtuals-5.2.sentence-2)
- [(5.3)](#filebuf.virtuals-5.3)
Iftraits​::​eq_int_type(c, traits​::​eof()) returnstrue,
and if either the input sequence has a putback position available or
the function makes a putback position available,
decrements the next pointer for the input sequence,gptr()[.](#filebuf.virtuals-5.3.sentence-1)
Returns:traits​::​not_eof(c)[.](#filebuf.virtuals-5.3.sentence-2)
[6](#filebuf.virtuals-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11518)
*Returns*: As specified above, ortraits​::​eof() to indicate failure[.](#filebuf.virtuals-6.sentence-1)
[7](#filebuf.virtuals-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11524)
*Remarks*: Ifis_open() == false,
the function always fails[.](#filebuf.virtuals-7.sentence-1)
[8](#filebuf.virtuals-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11530)
The function does not put back a character directly to the input sequence[.](#filebuf.virtuals-8.sentence-1)
[9](#filebuf.virtuals-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11533)
If the function can succeed in more than one of these ways, it is
unspecified which way is chosen[.](#filebuf.virtuals-9.sentence-1)
The function can alter the number of putback positions available as a result of any call[.](#filebuf.virtuals-9.sentence-2)
[🔗](#lib:overflow,basic_filebuf)
`int_type overflow(int_type c = traits::eof()) override;
`
[10](#filebuf.virtuals-10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11545)
*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​overflow(c),
except that the behavior of “consuming characters” is performed by first
converting as if by:charT* b = pbase();
charT* p = pptr();
charT* end;char xbuf[XSIZE];char* xbuf_end;
codecvt_base::result r = a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end); and then
- [(10.1)](#filebuf.virtuals-10.1)
If r == codecvt_base​::​error then fail[.](#filebuf.virtuals-10.1.sentence-1)
- [(10.2)](#filebuf.virtuals-10.2)
If r == codecvt_base​::​noconv then output characters fromb up to (and not including) p[.](#filebuf.virtuals-10.2.sentence-1)
- [(10.3)](#filebuf.virtuals-10.3)
If r == codecvt_base​::​partial then output to the file characters fromxbuf up to xbuf_end, and repeat using characters fromend to p[.](#filebuf.virtuals-10.3.sentence-1)
If output fails, fail (without repeating)[.](#filebuf.virtuals-10.3.sentence-2)
- [(10.4)](#filebuf.virtuals-10.4)
Otherwise output from xbuf to xbuf_end, and fail if output fails[.](#filebuf.virtuals-10.4.sentence-1)
At this point if b != p and b == end (xbuf isn't large
enough) then increase XSIZE and repeat from the beginning[.](#filebuf.virtuals-10.4.sentence-2)
Then establishes an observable checkpoint ([[intro.abstract]](intro.abstract "4.1.2 Abstract machine"))[.](#filebuf.virtuals-10.sentence-2)
[11](#filebuf.virtuals-11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11574)
*Returns*: traits​::​not_eof(c) to indicate success, andtraits​::​eof() to indicate failure[.](#filebuf.virtuals-11.sentence-1)
Ifis_open() == false,
the function always fails[.](#filebuf.virtuals-11.sentence-2)
[🔗](#lib:setbuf,basic_filebuf)
`basic_streambuf* setbuf(char_type* s, streamsize n) override;
`
[12](#filebuf.virtuals-12)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11591)
*Effects*: Ifsetbuf(0, 0) is called on a stream before any I/O has occurred on that stream, the
stream becomes unbuffered[.](#filebuf.virtuals-12.sentence-1)
Otherwise the results are implementation-defined[.](#filebuf.virtuals-12.sentence-2)
“Unbuffered” means thatpbase() andpptr() always return null
and output to the file should appear as soon as possible[.](#filebuf.virtuals-12.sentence-3)
[🔗](#lib:seekoff,basic_filebuf)
`pos_type seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which
= ios_base::in | ios_base::out) override;
`
[13](#filebuf.virtuals-13)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11615)
*Effects*: Letwidth denotea_codecvt.encoding()[.](#filebuf.virtuals-13.sentence-1)
Ifis_open() == false,
oroff != 0 && width <= 0,
then the positioning operation fails[.](#filebuf.virtuals-13.sentence-2)
Otherwise, ifway != basic_ios​::​cur oroff != 0,
and if the last operation was output,
then update the output sequence and write any unshift sequence[.](#filebuf.virtuals-13.sentence-3)
Next, seek to the new position: ifwidth > 0,
callfseek(file, width * off, whence),
otherwise callfseek(file, 0, whence)[.](#filebuf.virtuals-13.sentence-4)
[14](#filebuf.virtuals-14)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11639)
*Returns*: A newly constructedpos_type object that stores the resultant
stream position, if possible[.](#filebuf.virtuals-14.sentence-1)
If the positioning operation fails, or
if the object cannot represent the resultant stream position,
returnspos_type(off_type(-1))[.](#filebuf.virtuals-14.sentence-2)
[15](#filebuf.virtuals-15)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11650)
*Remarks*: “The last operation was output” means either
the last virtual operation was overflow or
the put buffer is non-empty[.](#filebuf.virtuals-15.sentence-1)
“Write any unshift sequence” means,
ifwidth is less than zero then calla_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end) and output the resulting unshift sequence[.](#filebuf.virtuals-15.sentence-2)
The function determines one of three values for the
argument whence, of typeint,
as indicated in Table [147](#tab:filebuf.seekoff "Table 147: seekoff effects")[.](#filebuf.virtuals-15.sentence-3)
Table [147](#tab:filebuf.seekoff) — seekoff effects [[tab:filebuf.seekoff]](./tab:filebuf.seekoff)
| [🔗](#tab:filebuf.seekoff-row-1)<br>**way Value** | **stdio Equivalent** |
| --- | --- |
| [🔗](#tab:filebuf.seekoff-row-2)<br>basic_ios​::​beg | SEEK_SET |
| [🔗](#tab:filebuf.seekoff-row-3)<br>basic_ios​::​cur | SEEK_CUR |
| [🔗](#tab:filebuf.seekoff-row-4)<br>basic_ios​::​end | SEEK_END |
[🔗](#lib:seekpos,basic_filebuf)
`pos_type seekpos(pos_type sp,
ios_base::openmode which
= ios_base::in | ios_base::out) override;
`
[16](#filebuf.virtuals-16)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11682)
Alters the file position, if possible, to correspond to the position
stored in sp (as described below)[.](#filebuf.virtuals-16.sentence-1)
Altering the file position performs as follows:
| [1.](#filebuf.virtuals-16.1) | if (om & ios_base​::​out) != 0, then update the output sequence and write any unshift sequence; |
| --- | --- |
| [2.](#filebuf.virtuals-16.2) | set the file position to sp as if by a call to fsetpos; |
| [3.](#filebuf.virtuals-16.3) | if (om & ios_base​::​in) != 0, then update the input sequence; |
where om is the open mode passed to the last call toopen()[.](#filebuf.virtuals-16.sentence-2)
The operation fails ifis_open() returns false[.](#filebuf.virtuals-16.sentence-3)
[17](#filebuf.virtuals-17)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11705)
If sp is an invalid stream position, or if the function positions
neither sequence, the positioning operation fails[.](#filebuf.virtuals-17.sentence-1)
If sp has not been obtained by a previous successful call to one of
the positioning functions
(seekoff orseekpos)
on the same file the effects are undefined[.](#filebuf.virtuals-17.sentence-2)
[18](#filebuf.virtuals-18)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11715)
*Returns*: sp on success[.](#filebuf.virtuals-18.sentence-1)
Otherwise returnspos_type(off_type(-1))[.](#filebuf.virtuals-18.sentence-2)
[🔗](#lib:sync,basic_filebuf)
`int sync() override;
`
[19](#filebuf.virtuals-19)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11729)
*Effects*: If a put area exists, callsfilebuf​::​overflow to write the characters to the file,
then flushes the file as if by calling fflush(file)[.](#filebuf.virtuals-19.sentence-1)
If a get area exists, the effect is implementation-defined[.](#filebuf.virtuals-19.sentence-2)
[🔗](#lib:imbue,basic_filebuf)
`void imbue(const locale& loc) override;
`
[20](#filebuf.virtuals-20)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11745)
*Preconditions*: If the file is not positioned at its beginning and the encoding of the current
locale as determined bya_codecvt.encoding() is state-dependent ([[locale.codecvt.virtuals]](locale.codecvt.virtuals "28.3.4.2.5.3 Virtual functions"))
then that facet is the same as
the corresponding facet of loc[.](#filebuf.virtuals-20.sentence-1)
[21](#filebuf.virtuals-21)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11754)
*Effects*: Causes characters inserted or extracted after this call
to be converted according to loc until another call ofimbue[.](#filebuf.virtuals-21.sentence-1)
[22](#filebuf.virtuals-22)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11760)
*Remarks*: This may require reconversion of previously converted characters[.](#filebuf.virtuals-22.sentence-1)
This in turn may require the implementation to be able to reconstruct
the original contents of the file[.](#filebuf.virtuals-22.sentence-2)
### [31.10.4](#ifstream) Class template basic_ifstream [[ifstream]](ifstream)
#### [31.10.4.1](#ifstream.general) General [[ifstream.general]](ifstream.general)
[🔗](#lib:basic_ifstream)
namespace std {template<class charT, class traits = char_traits<charT>>class basic_ifstream : public basic_istream<charT, traits> {public:using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using native_handle_type = typename basic_filebuf<charT, traits>::native_handle_type; // [[ifstream.cons]](#ifstream.cons "31.10.4.2 Constructors"), constructors basic_ifstream(); explicit basic_ifstream(const char* s,
ios_base::openmode mode = ios_base::in); explicit basic_ifstream(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in);// wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")explicit basic_ifstream(const string& s,
ios_base::openmode mode = ios_base::in); template<class T>explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
basic_ifstream(const basic_ifstream&) = delete;
basic_ifstream(basic_ifstream&& rhs);
basic_ifstream& operator=(const basic_ifstream&) = delete;
basic_ifstream& operator=(basic_ifstream&& rhs); // [[ifstream.swap]](#ifstream.swap "31.10.4.3 Swap"), swapvoid swap(basic_ifstream& rhs); // [[ifstream.members]](#ifstream.members "31.10.4.4 Member functions"), members basic_filebuf<charT, traits>* rdbuf() const;
native_handle_type native_handle() const noexcept; bool is_open() const; void open(const char* s, ios_base::openmode mode = ios_base::in); void open(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")void open(const string& s, ios_base::openmode mode = ios_base::in); void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in); void close(); private: basic_filebuf<charT, traits> *sb*; // *exposition only*};}
[1](#ifstream.general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11821)
The classbasic_ifstream<charT, traits> supports reading from named files[.](#ifstream.general-1.sentence-1)
It uses abasic_filebuf<​charT, traits> object to control the associated
sequence[.](#ifstream.general-1.sentence-2)
For the sake of exposition, the maintained data is presented here as:
- [(1.1)](#ifstream.general-1.1)
*sb*, the filebuf object[.](#ifstream.general-1.sentence-3)
#### [31.10.4.2](#ifstream.cons) Constructors [[ifstream.cons]](ifstream.cons)
[🔗](#lib:basic_ifstream,constructor)
`basic_ifstream();
`
[1](#ifstream.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11843)
*Effects*: Initializes the base class withbasic_istream<charT, traits>(addressof(*sb*)) ([[istream.cons]](istream.cons "31.7.5.2.2 Constructors"))
and *sb* withbasic_filebuf<charT, traits>() ([[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors"))[.](#ifstream.cons-1.sentence-1)
[🔗](#lib:basic_ifstream,constructor_)
`explicit basic_ifstream(const char* s,
ios_base::openmode mode = ios_base::in);
explicit basic_ifstream(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[2](#ifstream.cons-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11860)
*Effects*: Initializes the base class withbasic_istream<charT, traits>(addressof(*sb*)) ([[istream.cons]](istream.cons "31.7.5.2.2 Constructors"))
and *sb* withbasic_filebuf<charT, traits>() ([[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors")),
then callsrdbuf()->open(s, mode | ios_base​::​in)[.](#ifstream.cons-2.sentence-1)
If that function returns a null pointer, callssetstate(failbit)[.](#ifstream.cons-2.sentence-2)
[🔗](#lib:basic_ifstream,constructor__)
`explicit basic_ifstream(const string& s,
ios_base::openmode mode = ios_base::in);
`
[3](#ifstream.cons-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11879)
*Effects*: Equivalent to basic_ifstream(s.c_str(), mode)[.](#ifstream.cons-3.sentence-1)
[🔗](#lib:basic_ifstream,constructor___)
`template<class T>
explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
`
[4](#ifstream.cons-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11891)
*Constraints*: is_same_v<T, filesystem​::​path> is true[.](#ifstream.cons-4.sentence-1)
[5](#ifstream.cons-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11895)
*Effects*: Equivalent to basic_ifstream(s.c_str(), mode)[.](#ifstream.cons-5.sentence-1)
[🔗](#lib:basic_ifstream,constructor____)
`basic_ifstream(basic_ifstream&& rhs);
`
[6](#ifstream.cons-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11906)
*Effects*: Move constructs the base class, and the contained basic_filebuf[.](#ifstream.cons-6.sentence-1)
Then calls basic_istream<charT, traits>​::​set_rdbuf(​addressof(*sb*)) to install the contained basic_filebuf[.](#ifstream.cons-6.sentence-2)
#### [31.10.4.3](#ifstream.swap) Swap [[ifstream.swap]](ifstream.swap)
[🔗](#lib:swap,basic_ifstream)
`void swap(basic_ifstream& rhs);
`
[1](#ifstream.swap-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11921)
*Effects*: Exchanges the state of *this and rhs by callingbasic_istream<charT, traits>​::​swap(rhs) and*sb*.swap(rhs.*sb*)[.](#ifstream.swap-1.sentence-1)
[🔗](#lib:swap,basic_ifstream_)
`template<class charT, class traits>
void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
`
[2](#ifstream.swap-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11936)
*Effects*: Equivalent to x.swap(y)[.](#ifstream.swap-2.sentence-1)
#### [31.10.4.4](#ifstream.members) Member functions [[ifstream.members]](ifstream.members)
[🔗](#lib:rdbuf,basic_ifstream)
`basic_filebuf<charT, traits>* rdbuf() const;
`
[1](#ifstream.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11949)
*Returns*: const_cast<basic_filebuf<charT, traits>*>(addressof(*sb*))[.](#ifstream.members-1.sentence-1)
[🔗](#lib:native_handle,basic_ifstream)
`native_handle_type native_handle() const noexcept;
`
[2](#ifstream.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11960)
*Effects*: Equivalent to: return rdbuf()->native_handle();
[🔗](#lib:is_open,basic_ifstream)
`bool is_open() const;
`
[3](#ifstream.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11971)
*Returns*: rdbuf()->is_open()[.](#ifstream.members-3.sentence-1)
[🔗](#lib:open,basic_ifstream)
`void open(const char* s, ios_base::openmode mode = ios_base::in);
void open(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[4](#ifstream.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11984)
*Effects*: Callsrdbuf()->open(s, mode | ios_base​::​in)[.](#ifstream.members-4.sentence-1)
If that function does not return a null pointer
calls clear(),
otherwise callssetstate(failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#ifstream.members-4.sentence-2)
[🔗](#lib:open,basic_ifstream_)
`void open(const string& s, ios_base::openmode mode = ios_base::in);
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
`
[5](#ifstream.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12003)
*Effects*: Calls open(s.c_str(), mode)[.](#ifstream.members-5.sentence-1)
[🔗](#lib:close,basic_ifstream)
`void close();
`
[6](#ifstream.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12014)
*Effects*: Callsrdbuf()->close() and, if that function returns
a null pointer,
callssetstate(failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#ifstream.members-6.sentence-1)
### [31.10.5](#ofstream) Class template basic_ofstream [[ofstream]](ofstream)
#### [31.10.5.1](#ofstream.general) General [[ofstream.general]](ofstream.general)
[🔗](#lib:basic_ofstream)
namespace std {template<class charT, class traits = char_traits<charT>>class basic_ofstream : public basic_ostream<charT, traits> {public:using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using native_handle_type = typename basic_filebuf<charT, traits>::native_handle_type; // [[ofstream.cons]](#ofstream.cons "31.10.5.2 Constructors"), constructors basic_ofstream(); explicit basic_ofstream(const char* s,
ios_base::openmode mode = ios_base::out); explicit basic_ofstream(const filesystem::path::value_type* s, // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis") ios_base::openmode mode = ios_base::out); explicit basic_ofstream(const string& s,
ios_base::openmode mode = ios_base::out); template<class T>explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
basic_ofstream(const basic_ofstream&) = delete;
basic_ofstream(basic_ofstream&& rhs);
basic_ofstream& operator=(const basic_ofstream&) = delete;
basic_ofstream& operator=(basic_ofstream&& rhs); // [[ofstream.swap]](#ofstream.swap "31.10.5.3 Swap"), swapvoid swap(basic_ofstream& rhs); // [[ofstream.members]](#ofstream.members "31.10.5.4 Member functions"), members basic_filebuf<charT, traits>* rdbuf() const;
native_handle_type native_handle() const noexcept; bool is_open() const; void open(const char* s, ios_base::openmode mode = ios_base::out); void open(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")void open(const string& s, ios_base::openmode mode = ios_base::out); void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out); void close(); private: basic_filebuf<charT, traits> *sb*; // *exposition only*};}
[1](#ofstream.general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12080)
The classbasic_ofstream<charT, traits> supports writing to named files[.](#ofstream.general-1.sentence-1)
It uses abasic_filebuf<​charT, traits> object to control the associated
sequence[.](#ofstream.general-1.sentence-2)
For the sake of exposition, the maintained data is presented here as:
- [(1.1)](#ofstream.general-1.1)
*sb*, the filebuf object[.](#ofstream.general-1.sentence-3)
#### [31.10.5.2](#ofstream.cons) Constructors [[ofstream.cons]](ofstream.cons)
[🔗](#lib:basic_ofstream,constructor)
`basic_ofstream();
`
[1](#ofstream.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12102)
*Effects*: Initializes the base class withbasic_ostream<charT, traits>(addressof(*sb*)) ([[ostream.cons]](ostream.cons "31.7.6.2.2 Constructors"))
and *sb* withbasic_filebuf<charT, traits>() ([[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors"))[.](#ofstream.cons-1.sentence-1)
[🔗](#lib:basic_ofstream,constructor_)
`explicit basic_ofstream(const char* s,
ios_base::openmode mode = ios_base::out);
explicit basic_ofstream(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[2](#ofstream.cons-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12119)
*Effects*: Initializes the base class withbasic_ostream<charT, traits>(addressof(*sb*)) ([[ostream.cons]](ostream.cons "31.7.6.2.2 Constructors"))
and *sb* withbasic_filebuf<charT, traits>() ([[filebuf.cons]](#filebuf.cons "31.10.3.2 Constructors")),
then callsrdbuf()->open(s, mode | ios_base​::​out)[.](#ofstream.cons-2.sentence-1)
If that function returns a null pointer, callssetstate(​failbit)[.](#ofstream.cons-2.sentence-2)
[🔗](#lib:basic_ofstream,constructor__)
`explicit basic_ofstream(const string& s,
ios_base::openmode mode = ios_base::out);
`
[3](#ofstream.cons-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12138)
*Effects*: Equivalent to basic_ofstream(s.c_str(), mode)[.](#ofstream.cons-3.sentence-1)
[🔗](#lib:basic_ofstream,constructor___)
`template<class T>
explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
`
[4](#ofstream.cons-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12150)
*Constraints*: is_same_v<T, filesystem​::​path> is true[.](#ofstream.cons-4.sentence-1)
[5](#ofstream.cons-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12154)
*Effects*: Equivalent to basic_ofstream(s.c_str(), mode)[.](#ofstream.cons-5.sentence-1)
[🔗](#lib:basic_ofstream,constructor____)
`basic_ofstream(basic_ofstream&& rhs);
`
[6](#ofstream.cons-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12165)
*Effects*: Move constructs the base class, and the contained basic_filebuf[.](#ofstream.cons-6.sentence-1)
Then calls basic_ostream<charT, traits>​::​set_rdbuf(​addressof(*sb*)) to install the contained basic_filebuf[.](#ofstream.cons-6.sentence-2)
#### [31.10.5.3](#ofstream.swap) Swap [[ofstream.swap]](ofstream.swap)
[🔗](#lib:swap,basic_ofstream)
`void swap(basic_ofstream& rhs);
`
[1](#ofstream.swap-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12180)
*Effects*: Exchanges the state of *this and rhs by callingbasic_ostream<charT, traits>​::​swap(rhs) and*sb*.swap(rhs.*sb*)[.](#ofstream.swap-1.sentence-1)
[🔗](#lib:swap,basic_ofstream_)
`template<class charT, class traits>
void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
`
[2](#ofstream.swap-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12195)
*Effects*: Equivalent to x.swap(y)[.](#ofstream.swap-2.sentence-1)
#### [31.10.5.4](#ofstream.members) Member functions [[ofstream.members]](ofstream.members)
[🔗](#lib:rdbuf,basic_ofstream)
`basic_filebuf<charT, traits>* rdbuf() const;
`
[1](#ofstream.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12208)
*Returns*: const_cast<basic_filebuf<charT, traits>*>(addressof(*sb*))[.](#ofstream.members-1.sentence-1)
[🔗](#lib:native_handle,basic_ofstream)
`native_handle_type native_handle() const noexcept;
`
[2](#ofstream.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12219)
*Effects*: Equivalent to: return rdbuf()->native_handle();
[🔗](#lib:is_open,basic_ofstream)
`bool is_open() const;
`
[3](#ofstream.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12230)
*Returns*: rdbuf()->is_open()[.](#ofstream.members-3.sentence-1)
[🔗](#lib:open,basic_ofstream)
`void open(const char* s, ios_base::openmode mode = ios_base::out);
void open(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[4](#ofstream.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12243)
*Effects*: Callsrdbuf()->open(s, mode | ios_base​::​out)[.](#ofstream.members-4.sentence-1)
If that function does not return a null pointer
calls clear(),
otherwise callssetstate(​failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#ofstream.members-4.sentence-2)
[🔗](#lib:close,basic_ofstream)
`void close();
`
[5](#ofstream.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12261)
*Effects*: Callsrdbuf()->close() and, if that function fails (returns a null pointer), callssetstate(​failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#ofstream.members-5.sentence-1)
[🔗](#lib:open,basic_ofstream_)
`void open(const string& s, ios_base::openmode mode = ios_base::out);
void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
`
[6](#ofstream.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12278)
*Effects*: Calls open(s.c_str(), mode)[.](#ofstream.members-6.sentence-1)
### [31.10.6](#fstream) Class template basic_fstream [[fstream]](fstream)
#### [31.10.6.1](#fstream.general) General [[fstream.general]](fstream.general)
[🔗](#lib:basic_fstream)
namespace std {template<class charT, class traits = char_traits<charT>>class basic_fstream : public basic_iostream<charT, traits> {public:using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; using native_handle_type = typename basic_filebuf<charT, traits>::native_handle_type; // [[fstream.cons]](#fstream.cons "31.10.6.2 Constructors"), constructors basic_fstream(); explicit basic_fstream(const char* s,
ios_base::openmode mode = ios_base::in | ios_base::out); explicit basic_fstream(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")explicit basic_fstream(const string& s,
ios_base::openmode mode = ios_base::in | ios_base::out); template<class T>explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
basic_fstream(const basic_fstream&) = delete;
basic_fstream(basic_fstream&& rhs);
basic_fstream& operator=(const basic_fstream&) = delete;
basic_fstream& operator=(basic_fstream&& rhs); // [[fstream.swap]](#fstream.swap "31.10.6.3 Swap"), swapvoid swap(basic_fstream& rhs); // [[fstream.members]](#fstream.members "31.10.6.4 Member functions"), members basic_filebuf<charT, traits>* rdbuf() const;
native_handle_type native_handle() const noexcept; bool is_open() const; void open(const char* s,
ios_base::openmode mode = ios_base::in | ios_base::out); void open(const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")void open(const string& s,
ios_base::openmode mode = ios_base::in | ios_base::out); void open(const filesystem::path& s,
ios_base::openmode mode = ios_base::in | ios_base::out); void close(); private: basic_filebuf<charT, traits> *sb*; // *exposition only*};}
[1](#fstream.general-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12347)
The
class templatebasic_fstream<charT, traits> supports reading and writing from named files[.](#fstream.general-1.sentence-1)
It uses abasic_filebuf<charT, traits> object to control the associated sequences[.](#fstream.general-1.sentence-2)
For the sake of exposition, the maintained data is presented here as:
- [(1.1)](#fstream.general-1.1)
*sb*, the basic_filebuf object[.](#fstream.general-1.sentence-3)
#### [31.10.6.2](#fstream.cons) Constructors [[fstream.cons]](fstream.cons)
[🔗](#lib:basic_fstream,constructor)
`basic_fstream();
`
[1](#fstream.cons-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12369)
*Effects*: Initializes the base class withbasic_iostream<charT, traits>(addressof(*sb*)) ([[iostream.cons]](iostream.cons "31.7.5.7.2 Constructors"))
and*sb* with basic_filebuf<charT, traits>()[.](#fstream.cons-1.sentence-1)
[🔗](#lib:basic_fstream,constructor_)
`explicit basic_fstream(
const char* s,
ios_base::openmode mode = ios_base::in | ios_base::out);
explicit basic_fstream(
const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[2](#fstream.cons-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12388)
*Effects*: Initializes the base class withbasic_iostream<charT, traits>(addressof(*sb*)) ([[iostream.cons]](iostream.cons "31.7.5.7.2 Constructors"))
and*sb* with basic_filebuf<charT, traits>()[.](#fstream.cons-2.sentence-1)
Then callsrdbuf()->open(s, mode)[.](#fstream.cons-2.sentence-2)
If that function returns a null pointer, callssetstate(failbit)[.](#fstream.cons-2.sentence-3)
[🔗](#lib:basic_fstream,constructor__)
`explicit basic_fstream(
const string& s,
ios_base::openmode mode = ios_base::in | ios_base::out);
`
[3](#fstream.cons-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12408)
*Effects*: Equivalent to basic_fstream(s.c_str(), mode)[.](#fstream.cons-3.sentence-1)
[🔗](#lib:basic_fstream,constructor___)
`template<class T>
explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
`
[4](#fstream.cons-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12420)
*Constraints*: is_same_v<T, filesystem​::​path> is true[.](#fstream.cons-4.sentence-1)
[5](#fstream.cons-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12424)
*Effects*: Equivalent to basic_fstream(s.c_str(), mode)[.](#fstream.cons-5.sentence-1)
[🔗](#lib:basic_fstream,constructor____)
`basic_fstream(basic_fstream&& rhs);
`
[6](#fstream.cons-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12435)
*Effects*: Move constructs the base class, and the contained basic_filebuf[.](#fstream.cons-6.sentence-1)
Then calls basic_istream<charT, traits>​::​set_rdbuf(​addressof(*sb*)) to install the contained basic_filebuf[.](#fstream.cons-6.sentence-2)
#### [31.10.6.3](#fstream.swap) Swap [[fstream.swap]](fstream.swap)
[🔗](#lib:swap,basic_fstream)
`void swap(basic_fstream& rhs);
`
[1](#fstream.swap-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12450)
*Effects*: Exchanges the state of *this and rhs by callingbasic_iostream<charT,traits>​::​swap(rhs) and*sb*.swap(rhs.*sb*)[.](#fstream.swap-1.sentence-1)
[🔗](#lib:swap,basic_fstream_)
`template<class charT, class traits>
void swap(basic_fstream<charT, traits>& x,
basic_fstream<charT, traits>& y);
`
[2](#fstream.swap-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12466)
*Effects*: Equivalent to x.swap(y)[.](#fstream.swap-2.sentence-1)
#### [31.10.6.4](#fstream.members) Member functions [[fstream.members]](fstream.members)
[🔗](#lib:rdbuf,basic_fstream)
`basic_filebuf<charT, traits>* rdbuf() const;
`
[1](#fstream.members-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12479)
*Returns*: const_cast<basic_filebuf<charT, traits>*>(addressof(*sb*))[.](#fstream.members-1.sentence-1)
[🔗](#lib:native_handle,basic_fstream)
`native_handle_type native_handle() const noexcept;
`
[2](#fstream.members-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12490)
*Effects*: Equivalent to: return rdbuf()->native_handle();
[🔗](#lib:is_open,basic_fstream)
`bool is_open() const;
`
[3](#fstream.members-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12501)
*Returns*: rdbuf()->is_open()[.](#fstream.members-3.sentence-1)
[🔗](#lib:open,basic_fstream)
`void open(
const char* s,
ios_base::openmode mode = ios_base::in | ios_base::out);
void open(
const filesystem::path::value_type* s,
ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [[fstream.syn]](#fstream.syn "31.10.1 Header <fstream> synopsis")
`
[4](#fstream.members-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12517)
*Effects*: Callsrdbuf()->open(s, mode)[.](#fstream.members-4.sentence-1)
If that function does not return a null pointer calls clear(),
otherwise callssetstate(failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#fstream.members-4.sentence-2)
[🔗](#lib:open,basic_fstream_)
`void open(
const string& s,
ios_base::openmode mode = ios_base::in | ios_base::out);
void open(
const filesystem::path& s,
ios_base::openmode mode = ios_base::in | ios_base::out);
`
[5](#fstream.members-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12539)
*Effects*: Calls open(s.c_str(), mode)[.](#fstream.members-5.sentence-1)
[🔗](#lib:close,basic_fstream)
`void close();
`
[6](#fstream.members-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12550)
*Effects*: Callsrdbuf()->close() and, if that function
returns a null pointer,
callssetstate(failbit) (which may throwios_base​::​failure) ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions"))[.](#fstream.members-6.sentence-1)
Reference in New Issue View Git Blame Copy Permalink