Skip to content

[LWG motion 23] P1759R6 Native handles and file streams #6347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 21, 2023
Merged

[LWG motion 23] P1759R6 Native handles and file streams #6347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions source/iostreams.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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();
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}%
Expand Down Expand Up @@ -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();
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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();
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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();
Expand All @@ -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,
Expand Down Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions source/support.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down