Merge 2023-06 LWG Motion 23

P1759R6 Native handles and file streams

Author: tkoeppe

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<traits::\brk{}state_type>}.
 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<charT, traits>::native_handle_type;
 
     // \ref{ifstream.cons}, constructors
     basic_ifstream();
@@ -11646,6 +11696,7 @@
 
     // \ref{ifstream.members}, 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);
@@ -11794,6 +11845,17 @@
 \tcode{const_cast<basic_filebuf<charT, traits>*>(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<charT, traits>::native_handle_type;
 
     // \ref{ofstream.cons}, constructors
     basic_ofstream();
@@ -11892,6 +11955,7 @@
 
     // \ref{ofstream.members}, 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);
@@ -12040,6 +12104,17 @@
 \tcode{const_cast<basic_filebuf<charT, traits>*>(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<charT, traits>::native_handle_type;
 
     // \ref{fstream.cons}, constructors
     basic_fstream();
@@ -12139,6 +12215,8 @@
 
     // \ref{fstream.members}, members
     basic_filebuf<charT, traits>* 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<basic_filebuf<charT, traits>*>(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;

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}