From Jason Turner

[file.streams]

C++23 → Trunk 23.1 KB 215 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpiev2zk_8/{from.md → to.md} +129 -63
tmp/tmpiev2zk_8/{from.md → to.md} RENAMED
@@ -2,37 +2,41 @@
2
 
3
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
4
 
5
  ``` cpp
6
  namespace std {
 
7
  template<class charT, class traits = char_traits<charT>>
8
  class basic_filebuf;
9
 
10
  template<class charT, class traits>
11
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
12
 
13
  using filebuf = basic_filebuf<char>;
14
  using wfilebuf = basic_filebuf<wchar_t>;
15
 
 
16
  template<class charT, class traits = char_traits<charT>>
17
  class basic_ifstream;
18
 
19
  template<class charT, class traits>
20
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
21
 
22
  using ifstream = basic_ifstream<char>;
23
  using wifstream = basic_ifstream<wchar_t>;
24
 
 
25
  template<class charT, class traits = char_traits<charT>>
26
  class basic_ofstream;
27
 
28
  template<class charT, class traits>
29
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
30
 
31
  using ofstream = basic_ofstream<char>;
32
  using wofstream = basic_ofstream<wchar_t>;
33
 
 
34
  template<class charT, class traits = char_traits<charT>>
35
  class basic_fstream;
36
 
37
  template<class charT, class traits>
38
  void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
@@ -57,24 +61,38 @@ In subclause  [[file.streams]], member functions taking arguments of
57
  `filesystem::path::value_type` [[fs.class.path]] is not `char`.
58
 
59
  [*Note 2*: These functions enable class `path` support for systems with
60
  a wide native path character type, such as `wchar_t`. — *end note*]
61
 
 
 
 
 
 
 
 
 
 
 
 
 
 
62
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
63
 
64
  #### General <a id="filebuf.general">[[filebuf.general]]</a>
65
 
66
  ``` cpp
67
  namespace std {
68
  template<class charT, class traits = char_traits<charT>>
69
  class basic_filebuf : public basic_streambuf<charT, traits> {
70
  public:
71
  using char_type = charT;
72
- using int_type = typename traits::int_type;
73
- using pos_type = typename traits::pos_type;
74
- using off_type = typename traits::off_type;
75
  using traits_type = traits;
 
76
 
77
  // [filebuf.cons], constructors/destructor
78
  basic_filebuf();
79
  basic_filebuf(const basic_filebuf&) = delete;
80
  basic_filebuf(basic_filebuf&& rhs);
@@ -88,32 +106,30 @@ namespace std {
88
  // [filebuf.members], members
89
  bool is_open() const;
90
  basic_filebuf* open(const char* s, ios_base::openmode mode);
91
  basic_filebuf* open(const filesystem::path::value_type* s,
92
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
93
- basic_filebuf* open(const string& s,
94
- ios_base::openmode mode);
95
- basic_filebuf* open(const filesystem::path& s,
96
- ios_base::openmode mode);
97
  basic_filebuf* close();
 
98
 
99
  protected:
100
  // [filebuf.virtuals], overridden virtual functions
101
  streamsize showmanyc() override;
102
  int_type underflow() override;
103
  int_type uflow() override;
104
  int_type pbackfail(int_type c = traits::eof()) override;
105
  int_type overflow (int_type c = traits::eof()) override;
106
 
107
- basic_streambuf<charT, traits>* setbuf(char_type* s,
108
- streamsize n) override;
109
  pos_type seekoff(off_type off, ios_base::seekdir way,
110
- ios_base::openmode which
111
- = ios_base::in | ios_base::out) override;
112
  pos_type seekpos(pos_type sp,
113
- ios_base::openmode which
114
- = ios_base::in | ios_base::out) override;
115
  int sync() override;
116
  void imbue(const locale& loc) override;
117
  };
118
  }
119
  ```
@@ -135,10 +151,19 @@ In particular:
135
 
136
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
137
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
138
  the behavior is undefined.
139
 
 
 
 
 
 
 
 
 
 
140
  In order to support file I/O and multibyte/wide character conversion,
141
  conversions are performed using members of a facet, referred to as
142
  `a_codecvt` in following subclauses, obtained as if by
143
 
144
  ``` cpp
@@ -217,11 +242,11 @@ void swap(basic_filebuf& rhs);
217
  ``` cpp
218
  template<class charT, class traits>
219
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
220
  ```
221
 
222
- *Effects:* Equivalent to: `x.swap(y)`.
223
 
224
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
225
 
226
  ``` cpp
227
  bool is_open() const;
@@ -234,11 +259,11 @@ non-null value) and there has been no intervening call to close.
234
  basic_filebuf* open(const char* s, ios_base::openmode mode);
235
  basic_filebuf* open(const filesystem::path::value_type* s,
236
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
237
  ```
238
 
239
- *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
240
 
241
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
242
  initializes the `filebuf` as required. It then opens the file to which
243
  `s` resolves, if possible, as if by a call to `fopen` with the second
244
  argument determined from `mode & ~ios_base::ate` as indicated in
@@ -311,10 +336,18 @@ after closing the file.
311
 
312
  *Ensures:* `is_open() == false`.
313
 
314
  *Returns:* `this` on success, a null pointer otherwise.
315
 
 
 
 
 
 
 
 
 
316
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
317
 
318
  ``` cpp
319
  streamsize showmanyc() override;
320
  ```
@@ -336,11 +369,11 @@ that a sequence of characters is read from the input sequence as if by
336
  reading from the associated file into an internal buffer (`extern_buf`)
337
  and then as if by doing:
338
 
339
  ``` cpp
340
  char extern_buf[XSIZE];
341
- char* extern_end;
342
  charT intern_buf[ISIZE];
343
  charT* intern_end;
344
  codecvt_base::result r =
345
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
346
  intern_buf, intern_buf+ISIZE, intern_end);
@@ -401,11 +434,11 @@ int_type overflow(int_type c = traits::eof()) override;
401
  of “consuming characters” is performed by first converting as if by:
402
 
403
  ``` cpp
404
  charT* b = pbase();
405
  charT* p = pptr();
406
- charT* end;
407
  char xbuf[XSIZE];
408
  char* xbuf_end;
409
  codecvt_base::result r =
410
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
411
  ```
@@ -420,10 +453,12 @@ and then
420
  to `p`. If output fails, fail (without repeating).
421
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
422
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
423
  then increase `XSIZE` and repeat from the beginning.
424
 
 
 
425
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
426
  to indicate failure. If `is_open() == false`, the function always fails.
427
 
428
  ``` cpp
429
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
@@ -454,11 +489,11 @@ resultant stream position, if possible. If the positioning operation
454
  fails, or if the object cannot represent the resultant stream position,
455
  returns `pos_type(off_type(-1))`.
456
 
457
  *Remarks:* “The last operation was output” means either the last virtual
458
  operation was overflow or the put buffer is non-empty. “Write any
459
- unshift sequence” means, if `width` if less than zero then call
460
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
461
  resulting unshift sequence. The function determines one of three values
462
  for the argument `whence`, of type `int`, as indicated in
463
  [[filebuf.seekoff]].
464
 
@@ -529,14 +564,15 @@ reconstruct the original contents of the file.
529
  namespace std {
530
  template<class charT, class traits = char_traits<charT>>
531
  class basic_ifstream : public basic_istream<charT, traits> {
532
  public:
533
  using char_type = charT;
534
- using int_type = typename traits::int_type;
535
- using pos_type = typename traits::pos_type;
536
- using off_type = typename traits::off_type;
537
  using traits_type = traits;
 
538
 
539
  // [ifstream.cons], constructors
540
  basic_ifstream();
541
  explicit basic_ifstream(const char* s,
542
  ios_base::openmode mode = ios_base::in);
@@ -555,10 +591,11 @@ namespace std {
555
  // [ifstream.swap], swap
556
  void swap(basic_ifstream& rhs);
557
 
558
  // [ifstream.members], members
559
  basic_filebuf<charT, traits>* rdbuf() const;
 
560
 
561
  bool is_open() const;
562
  void open(const char* s, ios_base::openmode mode = ios_base::in);
563
  void open(const filesystem::path::value_type* s,
564
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
@@ -575,83 +612,91 @@ namespace std {
575
  The class `basic_ifstream<charT, traits>` supports reading from named
576
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
577
  associated sequence. For the sake of exposition, the maintained data is
578
  presented here as:
579
 
580
- - `sb`, the `filebuf` object.
581
 
582
  #### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
583
 
584
  ``` cpp
585
  basic_ifstream();
586
  ```
587
 
588
  *Effects:* Initializes the base class with
589
- `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
590
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
591
 
592
  ``` cpp
593
  explicit basic_ifstream(const char* s,
594
  ios_base::openmode mode = ios_base::in);
595
  explicit basic_ifstream(const filesystem::path::value_type* s,
596
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
597
  ```
598
 
599
  *Effects:* Initializes the base class with
600
- `basic_istream<charT, traits>(addressof(sb))` [[istream.cons]] and `sb`
601
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
602
  `rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
603
  pointer, calls `setstate(failbit)`.
604
 
605
  ``` cpp
606
  explicit basic_ifstream(const string& s,
607
  ios_base::openmode mode = ios_base::in);
608
  ```
609
 
610
- *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
611
 
612
  ``` cpp
613
  template<class T>
614
  explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
615
  ```
616
 
617
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
618
 
619
- *Effects:* Equivalent to: `basic_ifstream(s.c_str(), mode)`.
620
 
621
  ``` cpp
622
  basic_ifstream(basic_ifstream&& rhs);
623
  ```
624
 
625
  *Effects:* Move constructs the base class, and the contained
626
  `basic_filebuf`. Then calls
627
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
628
- contained `basic_filebuf`.
629
 
630
  #### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
631
 
632
  ``` cpp
633
  void swap(basic_ifstream& rhs);
634
  ```
635
 
636
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
637
- `basic_istream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
638
 
639
  ``` cpp
640
  template<class charT, class traits>
641
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
642
  ```
643
 
644
- *Effects:* Equivalent to: `x.swap(y)`.
645
 
646
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
647
 
648
  ``` cpp
649
  basic_filebuf<charT, traits>* rdbuf() const;
650
  ```
651
 
652
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
653
 
654
  ``` cpp
655
  bool is_open() const;
656
  ```
657
 
@@ -691,14 +736,15 @@ pointer, calls `setstate(failbit)` (which may throw
691
  namespace std {
692
  template<class charT, class traits = char_traits<charT>>
693
  class basic_ofstream : public basic_ostream<charT, traits> {
694
  public:
695
  using char_type = charT;
696
- using int_type = typename traits::int_type;
697
- using pos_type = typename traits::pos_type;
698
- using off_type = typename traits::off_type;
699
  using traits_type = traits;
 
700
 
701
  // [ofstream.cons], constructors
702
  basic_ofstream();
703
  explicit basic_ofstream(const char* s,
704
  ios_base::openmode mode = ios_base::out);
@@ -717,10 +763,11 @@ namespace std {
717
  // [ofstream.swap], swap
718
  void swap(basic_ofstream& rhs);
719
 
720
  // [ofstream.members], members
721
  basic_filebuf<charT, traits>* rdbuf() const;
 
722
 
723
  bool is_open() const;
724
  void open(const char* s, ios_base::openmode mode = ios_base::out);
725
  void open(const filesystem::path::value_type* s,
726
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
@@ -737,83 +784,91 @@ namespace std {
737
  The class `basic_ofstream<charT, traits>` supports writing to named
738
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
739
  associated sequence. For the sake of exposition, the maintained data is
740
  presented here as:
741
 
742
- - `sb`, the `filebuf` object.
743
 
744
  #### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
745
 
746
  ``` cpp
747
  basic_ofstream();
748
  ```
749
 
750
  *Effects:* Initializes the base class with
751
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
752
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
753
 
754
  ``` cpp
755
  explicit basic_ofstream(const char* s,
756
  ios_base::openmode mode = ios_base::out);
757
  explicit basic_ofstream(const filesystem::path::value_type* s,
758
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
759
  ```
760
 
761
  *Effects:* Initializes the base class with
762
- `basic_ostream<charT, traits>(addressof(sb))` [[ostream.cons]] and `sb`
763
- with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
764
  `rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
765
  null pointer, calls `setstate(failbit)`.
766
 
767
  ``` cpp
768
  explicit basic_ofstream(const string& s,
769
  ios_base::openmode mode = ios_base::out);
770
  ```
771
 
772
- *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
773
 
774
  ``` cpp
775
  template<class T>
776
  explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
777
  ```
778
 
779
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
780
 
781
- *Effects:* Equivalent to: `basic_ofstream(s.c_str(), mode)`.
782
 
783
  ``` cpp
784
  basic_ofstream(basic_ofstream&& rhs);
785
  ```
786
 
787
  *Effects:* Move constructs the base class, and the contained
788
  `basic_filebuf`. Then calls
789
- `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))` to install the
790
- contained `basic_filebuf`.
791
 
792
  #### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
793
 
794
  ``` cpp
795
  void swap(basic_ofstream& rhs);
796
  ```
797
 
798
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
799
- `basic_ostream<charT, traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
800
 
801
  ``` cpp
802
  template<class charT, class traits>
803
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
804
  ```
805
 
806
- *Effects:* Equivalent to: `x.swap(y)`.
807
 
808
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
809
 
810
  ``` cpp
811
  basic_filebuf<charT, traits>* rdbuf() const;
812
  ```
813
 
814
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
815
 
816
  ``` cpp
817
  bool is_open() const;
818
  ```
819
 
@@ -853,14 +908,15 @@ void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
853
  namespace std {
854
  template<class charT, class traits = char_traits<charT>>
855
  class basic_fstream : public basic_iostream<charT, traits> {
856
  public:
857
  using char_type = charT;
858
- using int_type = typename traits::int_type;
859
- using pos_type = typename traits::pos_type;
860
- using off_type = typename traits::off_type;
861
  using traits_type = traits;
 
862
 
863
  // [fstream.cons], constructors
864
  basic_fstream();
865
  explicit basic_fstream(
866
  const char* s,
@@ -882,10 +938,12 @@ namespace std {
882
  // [fstream.swap], swap
883
  void swap(basic_fstream& rhs);
884
 
885
  // [fstream.members], members
886
  basic_filebuf<charT, traits>* rdbuf() const;
 
 
887
  bool is_open() const;
888
  void open(
889
  const char* s,
890
  ios_base::openmode mode = ios_base::in | ios_base::out);
891
  void open(
@@ -908,21 +966,21 @@ namespace std {
908
  The class template `basic_fstream<charT, traits>` supports reading and
909
  writing from named files. It uses a `basic_filebuf<charT, traits>`
910
  object to control the associated sequences. For the sake of exposition,
911
  the maintained data is presented here as:
912
 
913
- - `sb`, the `basic_filebuf` object.
914
 
915
  #### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
916
 
917
  ``` cpp
918
  basic_fstream();
919
  ```
920
 
921
  *Effects:* Initializes the base class with
922
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
923
- `sb` with `basic_filebuf<charT, traits>()`.
924
 
925
  ``` cpp
926
  explicit basic_fstream(
927
  const char* s,
928
  ios_base::openmode mode = ios_base::in | ios_base::out);
@@ -930,65 +988,73 @@ explicit basic_fstream(
930
  const filesystem::path::value_type* s,
931
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
932
  ```
933
 
934
  *Effects:* Initializes the base class with
935
- `basic_iostream<charT, traits>(addressof(sb))` [[iostream.cons]] and
936
- `sb` with `basic_filebuf<charT, traits>()`. Then calls
937
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
938
  `setstate(failbit)`.
939
 
940
  ``` cpp
941
  explicit basic_fstream(
942
  const string& s,
943
  ios_base::openmode mode = ios_base::in | ios_base::out);
944
  ```
945
 
946
- *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
947
 
948
  ``` cpp
949
  template<class T>
950
  explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
951
  ```
952
 
953
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
954
 
955
- *Effects:* Equivalent to: `basic_fstream(s.c_str(), mode)`.
956
 
957
  ``` cpp
958
  basic_fstream(basic_fstream&& rhs);
959
  ```
960
 
961
  *Effects:* Move constructs the base class, and the contained
962
  `basic_filebuf`. Then calls
963
- `basic_istream<charT, traits>::set_rdbuf(addressof(sb))` to install the
964
- contained `basic_filebuf`.
965
 
966
  #### Swap <a id="fstream.swap">[[fstream.swap]]</a>
967
 
968
  ``` cpp
969
  void swap(basic_fstream& rhs);
970
  ```
971
 
972
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
973
- `basic_iostream<charT,traits>::swap(rhs)` and `sb.swap(rhs.sb)`.
 
974
 
975
  ``` cpp
976
  template<class charT, class traits>
977
  void swap(basic_fstream<charT, traits>& x,
978
  basic_fstream<charT, traits>& y);
979
  ```
980
 
981
- *Effects:* Equivalent to: `x.swap(y)`.
982
 
983
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
984
 
985
  ``` cpp
986
  basic_filebuf<charT, traits>* rdbuf() const;
987
  ```
988
 
989
- *Returns:* `const_cast<basic_filebuf<charT, traits>*>(addressof(sb))`.
 
 
 
 
 
 
 
990
 
991
  ``` cpp
992
  bool is_open() const;
993
  ```
994
 
 
2
 
3
  ### Header `<fstream>` synopsis <a id="fstream.syn">[[fstream.syn]]</a>
4
 
5
  ``` cpp
6
  namespace std {
7
+ // [filebuf], class template basic_filebuf
8
  template<class charT, class traits = char_traits<charT>>
9
  class basic_filebuf;
10
 
11
  template<class charT, class traits>
12
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
13
 
14
  using filebuf = basic_filebuf<char>;
15
  using wfilebuf = basic_filebuf<wchar_t>;
16
 
17
+ // [ifstream], class template basic_ifstream
18
  template<class charT, class traits = char_traits<charT>>
19
  class basic_ifstream;
20
 
21
  template<class charT, class traits>
22
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
23
 
24
  using ifstream = basic_ifstream<char>;
25
  using wifstream = basic_ifstream<wchar_t>;
26
 
27
+ // [ofstream], class template basic_ofstream
28
  template<class charT, class traits = char_traits<charT>>
29
  class basic_ofstream;
30
 
31
  template<class charT, class traits>
32
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
33
 
34
  using ofstream = basic_ofstream<char>;
35
  using wofstream = basic_ofstream<wchar_t>;
36
 
37
+ // [fstream], class template basic_fstream
38
  template<class charT, class traits = char_traits<charT>>
39
  class basic_fstream;
40
 
41
  template<class charT, class traits>
42
  void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);
 
61
  `filesystem::path::value_type` [[fs.class.path]] is not `char`.
62
 
63
  [*Note 2*: These functions enable class `path` support for systems with
64
  a wide native path character type, such as `wchar_t`. — *end note*]
65
 
66
+ ### Native handles <a id="file.native">[[file.native]]</a>
67
+
68
+ Several classes described in [[file.streams]] have a member
69
+ `native_handle_type`.
70
+
71
+ The type `native_handle_type` represents a platform-specific
72
+ *native handle* to a file. It is trivially copyable and models
73
+ `semiregular`.
74
+
75
+ [*Note 1*: For operating systems based on POSIX, `native_handle_type`
76
+ is `int`. For Windows-based operating systems, `native_handle_type` is
77
+ `HANDLE`. — *end note*]
78
+
79
  ### Class template `basic_filebuf` <a id="filebuf">[[filebuf]]</a>
80
 
81
  #### General <a id="filebuf.general">[[filebuf.general]]</a>
82
 
83
  ``` cpp
84
  namespace std {
85
  template<class charT, class traits = char_traits<charT>>
86
  class basic_filebuf : public basic_streambuf<charT, traits> {
87
  public:
88
  using char_type = charT;
89
+ using int_type = traits::int_type;
90
+ using pos_type = traits::pos_type;
91
+ using off_type = traits::off_type;
92
  using traits_type = traits;
93
+ using native_handle_type = implementation-defined // type of native_handle_type; // see [file.native]
94
 
95
  // [filebuf.cons], constructors/destructor
96
  basic_filebuf();
97
  basic_filebuf(const basic_filebuf&) = delete;
98
  basic_filebuf(basic_filebuf&& rhs);
 
106
  // [filebuf.members], members
107
  bool is_open() const;
108
  basic_filebuf* open(const char* s, ios_base::openmode mode);
109
  basic_filebuf* open(const filesystem::path::value_type* s,
110
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
111
+ basic_filebuf* open(const string& s, ios_base::openmode mode);
112
+ basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
 
 
113
  basic_filebuf* close();
114
+ native_handle_type native_handle() const noexcept;
115
 
116
  protected:
117
  // [filebuf.virtuals], overridden virtual functions
118
  streamsize showmanyc() override;
119
  int_type underflow() override;
120
  int_type uflow() override;
121
  int_type pbackfail(int_type c = traits::eof()) override;
122
  int_type overflow (int_type c = traits::eof()) override;
123
 
124
+ basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n) override;
125
+
126
  pos_type seekoff(off_type off, ios_base::seekdir way,
127
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
 
128
  pos_type seekpos(pos_type sp,
129
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
130
+
131
  int sync() override;
132
  void imbue(const locale& loc) override;
133
  };
134
  }
135
  ```
 
151
 
152
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
153
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
154
  the behavior is undefined.
155
 
156
+ The file associated with a `basic_filebuf` has an associated value of
157
+ type `native_handle_type`, called the native handle [[file.native]] of
158
+ that file. This native handle can be obtained by calling the member
159
+ function `native_handle`.
160
+
161
+ For any opened `basic_filebuf f`, the native handle returned by
162
+ `f.native_handle()` is invalidated when `f.close()` is called, or `f` is
163
+ destroyed.
164
+
165
  In order to support file I/O and multibyte/wide character conversion,
166
  conversions are performed using members of a facet, referred to as
167
  `a_codecvt` in following subclauses, obtained as if by
168
 
169
  ``` cpp
 
242
  ``` cpp
243
  template<class charT, class traits>
244
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
245
  ```
246
 
247
+ *Effects:* Equivalent to `x.swap(y)`.
248
 
249
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
250
 
251
  ``` cpp
252
  bool is_open() const;
 
259
  basic_filebuf* open(const char* s, ios_base::openmode mode);
260
  basic_filebuf* open(const filesystem::path::value_type* s,
261
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
262
  ```
263
 
264
+ *Preconditions:* `s` points to an NTCTS [[defns.ntcts]].
265
 
266
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
267
  initializes the `filebuf` as required. It then opens the file to which
268
  `s` resolves, if possible, as if by a call to `fopen` with the second
269
  argument determined from `mode & ~ios_base::ate` as indicated in
 
336
 
337
  *Ensures:* `is_open() == false`.
338
 
339
  *Returns:* `this` on success, a null pointer otherwise.
340
 
341
+ ``` cpp
342
+ native_handle_type native_handle() const noexcept;
343
+ ```
344
+
345
+ *Preconditions:* `is_open()` is `true`.
346
+
347
+ *Returns:* The native handle associated with `*this`.
348
+
349
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
350
 
351
  ``` cpp
352
  streamsize showmanyc() override;
353
  ```
 
369
  reading from the associated file into an internal buffer (`extern_buf`)
370
  and then as if by doing:
371
 
372
  ``` cpp
373
  char extern_buf[XSIZE];
374
+ const char* extern_end;
375
  charT intern_buf[ISIZE];
376
  charT* intern_end;
377
  codecvt_base::result r =
378
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
379
  intern_buf, intern_buf+ISIZE, intern_end);
 
434
  of “consuming characters” is performed by first converting as if by:
435
 
436
  ``` cpp
437
  charT* b = pbase();
438
  charT* p = pptr();
439
+ const charT* end;
440
  char xbuf[XSIZE];
441
  char* xbuf_end;
442
  codecvt_base::result r =
443
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
444
  ```
 
453
  to `p`. If output fails, fail (without repeating).
454
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
455
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
456
  then increase `XSIZE` and repeat from the beginning.
457
 
458
+ Then establishes an observable checkpoint [[intro.abstract]].
459
+
460
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
461
  to indicate failure. If `is_open() == false`, the function always fails.
462
 
463
  ``` cpp
464
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
 
489
  fails, or if the object cannot represent the resultant stream position,
490
  returns `pos_type(off_type(-1))`.
491
 
492
  *Remarks:* “The last operation was output” means either the last virtual
493
  operation was overflow or the put buffer is non-empty. “Write any
494
+ unshift sequence” means, if `width` is less than zero then call
495
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
496
  resulting unshift sequence. The function determines one of three values
497
  for the argument `whence`, of type `int`, as indicated in
498
  [[filebuf.seekoff]].
499
 
 
564
  namespace std {
565
  template<class charT, class traits = char_traits<charT>>
566
  class basic_ifstream : public basic_istream<charT, traits> {
567
  public:
568
  using char_type = charT;
569
+ using int_type = traits::int_type;
570
+ using pos_type = traits::pos_type;
571
+ using off_type = traits::off_type;
572
  using traits_type = traits;
573
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
574
 
575
  // [ifstream.cons], constructors
576
  basic_ifstream();
577
  explicit basic_ifstream(const char* s,
578
  ios_base::openmode mode = ios_base::in);
 
591
  // [ifstream.swap], swap
592
  void swap(basic_ifstream& rhs);
593
 
594
  // [ifstream.members], members
595
  basic_filebuf<charT, traits>* rdbuf() const;
596
+ native_handle_type native_handle() const noexcept;
597
 
598
  bool is_open() const;
599
  void open(const char* s, ios_base::openmode mode = ios_base::in);
600
  void open(const filesystem::path::value_type* s,
601
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
 
612
  The class `basic_ifstream<charT, traits>` supports reading from named
613
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
614
  associated sequence. For the sake of exposition, the maintained data is
615
  presented here as:
616
 
617
+ - *`sb`*, the `filebuf` object.
618
 
619
  #### Constructors <a id="ifstream.cons">[[ifstream.cons]]</a>
620
 
621
  ``` cpp
622
  basic_ifstream();
623
  ```
624
 
625
  *Effects:* Initializes the base class with
626
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream.cons]] and
627
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
628
 
629
  ``` cpp
630
  explicit basic_ifstream(const char* s,
631
  ios_base::openmode mode = ios_base::in);
632
  explicit basic_ifstream(const filesystem::path::value_type* s,
633
  ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]
634
  ```
635
 
636
  *Effects:* Initializes the base class with
637
+ `basic_istream<charT, traits>(addressof(`*`sb`*`))` [[istream.cons]] and
638
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
639
  `rdbuf()->open(s, mode | ios_base::in)`. If that function returns a null
640
  pointer, calls `setstate(failbit)`.
641
 
642
  ``` cpp
643
  explicit basic_ifstream(const string& s,
644
  ios_base::openmode mode = ios_base::in);
645
  ```
646
 
647
+ *Effects:* Equivalent to `basic_ifstream(s.c_str(), mode)`.
648
 
649
  ``` cpp
650
  template<class T>
651
  explicit basic_ifstream(const T& s, ios_base::openmode mode = ios_base::in);
652
  ```
653
 
654
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
655
 
656
+ *Effects:* Equivalent to `basic_ifstream(s.c_str(), mode)`.
657
 
658
  ``` cpp
659
  basic_ifstream(basic_ifstream&& rhs);
660
  ```
661
 
662
  *Effects:* Move constructs the base class, and the contained
663
  `basic_filebuf`. Then calls
664
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
665
+ install the contained `basic_filebuf`.
666
 
667
  #### Swap <a id="ifstream.swap">[[ifstream.swap]]</a>
668
 
669
  ``` cpp
670
  void swap(basic_ifstream& rhs);
671
  ```
672
 
673
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
674
+ `basic_istream<charT, traits>::swap(rhs)` and
675
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
676
 
677
  ``` cpp
678
  template<class charT, class traits>
679
  void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);
680
  ```
681
 
682
+ *Effects:* Equivalent to `x.swap(y)`.
683
 
684
  #### Member functions <a id="ifstream.members">[[ifstream.members]]</a>
685
 
686
  ``` cpp
687
  basic_filebuf<charT, traits>* rdbuf() const;
688
  ```
689
 
690
+ *Returns:*
691
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
692
+
693
+ ``` cpp
694
+ native_handle_type native_handle() const noexcept;
695
+ ```
696
+
697
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
698
 
699
  ``` cpp
700
  bool is_open() const;
701
  ```
702
 
 
736
  namespace std {
737
  template<class charT, class traits = char_traits<charT>>
738
  class basic_ofstream : public basic_ostream<charT, traits> {
739
  public:
740
  using char_type = charT;
741
+ using int_type = traits::int_type;
742
+ using pos_type = traits::pos_type;
743
+ using off_type = traits::off_type;
744
  using traits_type = traits;
745
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
746
 
747
  // [ofstream.cons], constructors
748
  basic_ofstream();
749
  explicit basic_ofstream(const char* s,
750
  ios_base::openmode mode = ios_base::out);
 
763
  // [ofstream.swap], swap
764
  void swap(basic_ofstream& rhs);
765
 
766
  // [ofstream.members], members
767
  basic_filebuf<charT, traits>* rdbuf() const;
768
+ native_handle_type native_handle() const noexcept;
769
 
770
  bool is_open() const;
771
  void open(const char* s, ios_base::openmode mode = ios_base::out);
772
  void open(const filesystem::path::value_type* s,
773
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
 
784
  The class `basic_ofstream<charT, traits>` supports writing to named
785
  files. It uses a `basic_filebuf<{}charT, traits>` object to control the
786
  associated sequence. For the sake of exposition, the maintained data is
787
  presented here as:
788
 
789
+ - *`sb`*, the `filebuf` object.
790
 
791
  #### Constructors <a id="ofstream.cons">[[ofstream.cons]]</a>
792
 
793
  ``` cpp
794
  basic_ofstream();
795
  ```
796
 
797
  *Effects:* Initializes the base class with
798
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream.cons]] and
799
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]].
800
 
801
  ``` cpp
802
  explicit basic_ofstream(const char* s,
803
  ios_base::openmode mode = ios_base::out);
804
  explicit basic_ofstream(const filesystem::path::value_type* s,
805
  ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]
806
  ```
807
 
808
  *Effects:* Initializes the base class with
809
+ `basic_ostream<charT, traits>(addressof(`*`sb`*`))` [[ostream.cons]] and
810
+ *sb* with `basic_filebuf<charT, traits>()` [[filebuf.cons]], then calls
811
  `rdbuf()->open(s, mode | ios_base::out)`. If that function returns a
812
  null pointer, calls `setstate(failbit)`.
813
 
814
  ``` cpp
815
  explicit basic_ofstream(const string& s,
816
  ios_base::openmode mode = ios_base::out);
817
  ```
818
 
819
+ *Effects:* Equivalent to `basic_ofstream(s.c_str(), mode)`.
820
 
821
  ``` cpp
822
  template<class T>
823
  explicit basic_ofstream(const T& s, ios_base::openmode mode = ios_base::out);
824
  ```
825
 
826
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
827
 
828
+ *Effects:* Equivalent to `basic_ofstream(s.c_str(), mode)`.
829
 
830
  ``` cpp
831
  basic_ofstream(basic_ofstream&& rhs);
832
  ```
833
 
834
  *Effects:* Move constructs the base class, and the contained
835
  `basic_filebuf`. Then calls
836
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
837
+ install the contained `basic_filebuf`.
838
 
839
  #### Swap <a id="ofstream.swap">[[ofstream.swap]]</a>
840
 
841
  ``` cpp
842
  void swap(basic_ofstream& rhs);
843
  ```
844
 
845
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
846
+ `basic_ostream<charT, traits>::swap(rhs)` and
847
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
848
 
849
  ``` cpp
850
  template<class charT, class traits>
851
  void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);
852
  ```
853
 
854
+ *Effects:* Equivalent to `x.swap(y)`.
855
 
856
  #### Member functions <a id="ofstream.members">[[ofstream.members]]</a>
857
 
858
  ``` cpp
859
  basic_filebuf<charT, traits>* rdbuf() const;
860
  ```
861
 
862
+ *Returns:*
863
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
864
+
865
+ ``` cpp
866
+ native_handle_type native_handle() const noexcept;
867
+ ```
868
+
869
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
870
 
871
  ``` cpp
872
  bool is_open() const;
873
  ```
874
 
 
908
  namespace std {
909
  template<class charT, class traits = char_traits<charT>>
910
  class basic_fstream : public basic_iostream<charT, traits> {
911
  public:
912
  using char_type = charT;
913
+ using int_type = traits::int_type;
914
+ using pos_type = traits::pos_type;
915
+ using off_type = traits::off_type;
916
  using traits_type = traits;
917
+ using native_handle_type = basic_filebuf<charT, traits>::native_handle_type;
918
 
919
  // [fstream.cons], constructors
920
  basic_fstream();
921
  explicit basic_fstream(
922
  const char* s,
 
938
  // [fstream.swap], swap
939
  void swap(basic_fstream& rhs);
940
 
941
  // [fstream.members], members
942
  basic_filebuf<charT, traits>* rdbuf() const;
943
+ native_handle_type native_handle() const noexcept;
944
+
945
  bool is_open() const;
946
  void open(
947
  const char* s,
948
  ios_base::openmode mode = ios_base::in | ios_base::out);
949
  void open(
 
966
  The class template `basic_fstream<charT, traits>` supports reading and
967
  writing from named files. It uses a `basic_filebuf<charT, traits>`
968
  object to control the associated sequences. For the sake of exposition,
969
  the maintained data is presented here as:
970
 
971
+ - *`sb`*, the `basic_filebuf` object.
972
 
973
  #### Constructors <a id="fstream.cons">[[fstream.cons]]</a>
974
 
975
  ``` cpp
976
  basic_fstream();
977
  ```
978
 
979
  *Effects:* Initializes the base class with
980
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
981
+ and *sb* with `basic_filebuf<charT, traits>()`.
982
 
983
  ``` cpp
984
  explicit basic_fstream(
985
  const char* s,
986
  ios_base::openmode mode = ios_base::in | ios_base::out);
 
988
  const filesystem::path::value_type* s,
989
  ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]
990
  ```
991
 
992
  *Effects:* Initializes the base class with
993
+ `basic_iostream<charT, traits>(addressof(`*`sb`*`))` [[iostream.cons]]
994
+ and *sb* with `basic_filebuf<charT, traits>()`. Then calls
995
  `rdbuf()->open(s, mode)`. If that function returns a null pointer, calls
996
  `setstate(failbit)`.
997
 
998
  ``` cpp
999
  explicit basic_fstream(
1000
  const string& s,
1001
  ios_base::openmode mode = ios_base::in | ios_base::out);
1002
  ```
1003
 
1004
+ *Effects:* Equivalent to `basic_fstream(s.c_str(), mode)`.
1005
 
1006
  ``` cpp
1007
  template<class T>
1008
  explicit basic_fstream(const T& s, ios_base::openmode mode = ios_base::in | ios_base::out);
1009
  ```
1010
 
1011
  *Constraints:* `is_same_v<T, filesystem::path>` is `true`.
1012
 
1013
+ *Effects:* Equivalent to `basic_fstream(s.c_str(), mode)`.
1014
 
1015
  ``` cpp
1016
  basic_fstream(basic_fstream&& rhs);
1017
  ```
1018
 
1019
  *Effects:* Move constructs the base class, and the contained
1020
  `basic_filebuf`. Then calls
1021
+ `basic_istream<charT, traits>::set_rdbuf(addressof(`*`sb`*`))` to
1022
+ install the contained `basic_filebuf`.
1023
 
1024
  #### Swap <a id="fstream.swap">[[fstream.swap]]</a>
1025
 
1026
  ``` cpp
1027
  void swap(basic_fstream& rhs);
1028
  ```
1029
 
1030
  *Effects:* Exchanges the state of `*this` and `rhs` by calling
1031
+ `basic_iostream<charT,traits>::swap(rhs)` and
1032
+ *`sb`*`.swap(rhs.`*`sb`*`)`.
1033
 
1034
  ``` cpp
1035
  template<class charT, class traits>
1036
  void swap(basic_fstream<charT, traits>& x,
1037
  basic_fstream<charT, traits>& y);
1038
  ```
1039
 
1040
+ *Effects:* Equivalent to `x.swap(y)`.
1041
 
1042
  #### Member functions <a id="fstream.members">[[fstream.members]]</a>
1043
 
1044
  ``` cpp
1045
  basic_filebuf<charT, traits>* rdbuf() const;
1046
  ```
1047
 
1048
+ *Returns:*
1049
+ `const_cast<basic_filebuf<charT, traits>*>(addressof(`*`sb`*`))`.
1050
+
1051
+ ``` cpp
1052
+ native_handle_type native_handle() const noexcept;
1053
+ ```
1054
+
1055
+ *Effects:* Equivalent to: `return rdbuf()->native_handle();`
1056
 
1057
  ``` cpp
1058
  bool is_open() const;
1059
  ```
1060