diff --git a/source/iostreams.tex b/source/iostreams.tex index 2447cadecc..bba66ad08e 100644 --- a/source/iostreams.tex +++ b/source/iostreams.tex @@ -10837,6 +10837,26 @@ These functions enable class \tcode{path} support for systems with a wide native path character type, such as \keyword{wchar_t}. \end{note} +\rSec2[file.native]{Native handles} + +\indexlibraryglobal{native_handle_type}% + +\pnum +Several classes described in \ref{file.streams} +have a member \tcode{native_handle_type}. + +\pnum +The type \tcode{native_handle_type} represents a platform-specific +\defnadj{native}{handle} to a file. +It is trivially copyable and models \libconcept{semiregular}. + +\begin{note} +For operating systems based on POSIX, +\tcode{native_handle_type} is \keyword{int}. +For Windows-based operating systems, +\tcode{native_handle_type} is \tcode{HANDLE}. +\end{note} + \rSec2[filebuf]{Class template \tcode{basic_filebuf}} \rSec3[filebuf.general]{General} @@ -10852,6 +10872,7 @@ using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; + using native_handle_type = @\impdefx{type of \tcode{native_handle_type}}@; // see \ref{file.native} // \ref{filebuf.cons}, constructors/destructor basic_filebuf(); @@ -10874,6 +10895,7 @@ basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode); basic_filebuf* close(); + native_handle_type native_handle() const noexcept; protected: // \ref{filebuf.virtuals}, overridden virtual functions @@ -10933,6 +10955,18 @@ \tcode{fpos}. Otherwise the behavior is undefined. +\pnum +The file associated with a \tcode{basic_filebuf} has +an associated value of type \tcode{native_handle_type}, +called the native handle\iref{file.native} of that file. +This native handle can be obtained by calling +the member function \tcode{native_handle}. + +\pnum +For any opened \tcode{basic_filebuf f}, +the native handle returned by \tcode{f.native_handle()} is +invalidated when \tcode{f.close()} is called, or \tcode{f} is destroyed. + \pnum In order to support file I/O and multibyte/wide character conversion, conversions are performed using members of a facet, referred to as @@ -11226,6 +11260,21 @@ on success, a null pointer otherwise. \end{itemdescr} +\indexlibrarymember{native_handle}{basic_filebuf}% +\begin{itemdecl} +native_handle_type native_handle() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{is_open()} is \tcode{true}. + +\pnum +\returns +The native handle associated with \tcode{*this}. +\end{itemdescr} + \rSec3[filebuf.virtuals]{Overridden virtual functions} \indexlibrarymember{showmanyc}{basic_filebuf}% @@ -11624,6 +11673,7 @@ 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::native_handle_type; // \ref{ifstream.cons}, constructors basic_ifstream(); @@ -11646,6 +11696,7 @@ // \ref{ifstream.members}, members basic_filebuf* 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); @@ -11794,6 +11845,17 @@ \tcode{const_cast*>(addressof(sb))}. \end{itemdescr} +\indexlibrarymember{native_handle}{basic_ifstream}% +\begin{itemdecl} +native_handle_type native_handle() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: \tcode{return rdbuf()->native_handle();} +\end{itemdescr} + \indexlibrarymember{is_open}{basic_ifstream}% \begin{itemdecl} bool is_open() const; @@ -11870,6 +11932,7 @@ 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::native_handle_type; // \ref{ofstream.cons}, constructors basic_ofstream(); @@ -11892,6 +11955,7 @@ // \ref{ofstream.members}, members basic_filebuf* 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); @@ -12040,6 +12104,17 @@ \tcode{const_cast*>(addressof(sb))}. \end{itemdescr} +\indexlibrarymember{native_handle}{basic_ofstream}% +\begin{itemdecl} +native_handle_type native_handle() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: \tcode{return rdbuf()->native_handle();} +\end{itemdescr} + \indexlibrarymember{is_open}{basic_ofstream}% \begin{itemdecl} bool is_open() const; @@ -12114,6 +12189,7 @@ 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::native_handle_type; // \ref{fstream.cons}, constructors basic_fstream(); @@ -12139,6 +12215,8 @@ // \ref{fstream.members}, members basic_filebuf* rdbuf() const; + native_handle_type native_handle() const noexcept; + bool is_open() const; void open( const char* s, @@ -12297,6 +12375,17 @@ \tcode{const_cast*>(addressof(sb))}. \end{itemdescr} +\indexlibrarymember{native_handle}{basic_fstream}% +\begin{itemdecl} +native_handle_type native_handle() const noexcept; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: \tcode{return rdbuf()->native_handle();} +\end{itemdescr} + \indexlibrarymember{is_open}{basic_fstream}% \begin{itemdecl} bool is_open() const; diff --git a/source/support.tex b/source/support.tex index d4e2f65796..04072f868d 100644 --- a/source/support.tex +++ b/source/support.tex @@ -648,6 +648,7 @@ #define @\defnlibxname{cpp_lib_freestanding_ratio}@ 202306L // freestanding, also in \libheader{ratio} #define @\defnlibxname{cpp_lib_freestanding_tuple}@ 202306L // freestanding, also in \libheader{tuple} #define @\defnlibxname{cpp_lib_freestanding_utility}@ 202306L // freestanding, also in \libheader{utility} +#define @\defnlibxname{cpp_lib_fstream_native_handle}@ 202306L // also in \libheader{fstream} #define @\defnlibxname{cpp_lib_function_ref}@ 202306L // also in \libheader{functional} #define @\defnlibxname{cpp_lib_gcd_lcm}@ 201606L // also in \libheader{numeric} #define @\defnlibxname{cpp_lib_generator}@ 202207L // also in \libheader{generator}