summaryrefslogtreecommitdiffstats
path: root/contrib/libio/iostream.texi
blob: 641cd7da22f078aacf8767437fb37e7a63838d9d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
\input texinfo                                 @c -*-Texinfo-*-
@c Copyright (c) 1993 Free Software Foundation, Inc.

@c %**start of header 
@setfilename iostream.info
@settitle The GNU C++ Iostream Library
@setchapternewpage odd
@c %**end of header

@ifinfo
@format
START-INFO-DIR-ENTRY
* iostream: (iostream).                    The C++ input/output facility.
END-INFO-DIR-ENTRY
@end format

This file describes libio, the GNU library for C++ iostreams and C stdio.

libio includes software developed by the University of California,
Berkeley.

Copyright (C) 1993 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@finalout
@syncodeindex fn cp
@syncodeindex vr cp

@titlepage
@title The GNU C++ Iostream Library
@subtitle Reference Manual for @code{libio} Version 0.64
@sp 3
@author Per Bothner @hfill @code{bothner@@cygnus.com}
@author Cygnus Support @hfill @code{doc@@cygnus.com}
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Free Software Foundation, Inc.

@code{libio} includes software developed by the University of
California, Berkeley.

@code{libio} uses floating-point software written by David M. Gay, which
includes the following notice:

@quotation
The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire notice
is included in all copies of any software which is or includes a copy
or modification of this software and in all copies of the supporting
documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY
REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
@end quotation

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage

@ifinfo
@node Top
@top The GNU C++ Iostream Library

This file provides reference information on the GNU C++ iostream library
(@code{libio}), version 0.64.

@menu
* Introduction::
* Operators::			Operators and default streams.
* Streams::			Stream classes.
* Files and Strings::		Classes for files and strings.
* Streambuf::			Using the streambuf layer.
* Stdio::			C input and output.
* Index::
@end menu
@end ifinfo

@node Introduction
@chapter Introduction

The iostream classes implement most of the features of AT&T version 2.0
iostream library classes, and most of the features of the ANSI X3J16
library draft (which is based on the AT&T design).

This manual is meant as a reference; for tutorial material on iostreams,
see the corresponding section of any recent popular introduction to C++.

@menu
* Copying::		Special GNU licensing terms for libio.
* Acknowledgements::	Contributors to GNU iostream.
@end menu

@node Copying
@section Licensing terms for @code{libio}

Since the @code{iostream} classes are so fundamental to standard C++,
the Free Software Foundation has agreed to a special exception to its
standard license, when you link programs with @code{libio.a}:

@quotation
As a special exception, if you link this library with files
compiled with a GNU compiler to produce an executable, this does not cause
the resulting executable to be covered by the GNU General Public License.
This exception does not however invalidate any other reasons why
the executable file might be covered by the GNU General Public License.
@end quotation

The code is under the @sc{gnu} General Public License (version 2) for
all other purposes than linking with this library; that means that you
can modify and redistribute the code as usual, but remember that if you
do, your modifications, and anything you link with the modified code,
must be available to others on the same terms.

These functions are also available as part of the @code{libg++}
library; if you link with that library instead of @code{libio}, the
@sc{gnu} Library General Public License applies.

@node Acknowledgements
@section Acknowledgements

Per Bothner wrote most of the @code{iostream} library, but some portions
have their origins elsewhere in the free software community.  Heinz
Seidl wrote the IO manipulators.  The floating-point conversion software
is by David M. Gay of AT&T.  Some code was derived from parts of BSD
4.4, which was written at the University of California, Berkeley.

The iostream classes are found in the @code{libio} library.  An early
version was originally distributed in @code{libg++}, and they are still
included there as well, for convenience if you need other @code{libg++}
classes.  Doug Lea was the original author of @code{libg++}, and some of
the file-management code still in @code{libio} is his.

Various people found bugs or offered suggestions.  Hongjiu Lu worked
hard to use the library as the default stdio implementation for Linux,
and has provided much stress-testing of the library.

@node Operators
@chapter Operators and Default Streams

The @sc{gnu} iostream library, @file{libio}, implements the standard
input and output facilities for C++.  These facilities are roughly
analogous (in their purpose and ubiquity, at least) with those defined
by the C @file{stdio} functions.

Although these definitions come from a library, rather than being part
of the ``core language'', they are sufficiently central to be specified
in the latest working papers for C++.

You can use two operators defined in this library for basic input and
output operations.  They are familiar from any C++ introductory
textbook: @code{<<} for output, and @code{>>} for input.  (Think of data
flowing in the direction of the ``arrows''.)

These operators are often used in conjunction with three streams that
are open by default: 

@deftypevar ostream cout
The standard output stream, analogous to the C @code{stdout}.
@end deftypevar

@deftypevar istream cin
The standard input stream, analogous to the C @code{stdin}.
@end deftypevar

@deftypevar ostream cerr
An alternative output stream for errors, analogous to the C
@code{stderr}.
@end deftypevar

@noindent
For example, this bare-bones C++ version of the traditional ``hello''
program uses @code{<<} and @code{cout}:

@example
#include <iostream.h>

int main(int argc, char **argv)
@{
  cout << "Well, hi there.\n";
  return 0;
@}
@end example

Casual use of these operators may be seductive, but---other than in
writing throwaway code for your own use---it is not necessarily simpler
than managing input and output in any other language.  For example,
robust code should check the state of the input and output streams
between operations (for example, using the method @code{good}).
@xref{States,,Checking the state of a stream}.  You may also need to
adjust maximum input or output field widths, using manipulators like
@code{setw} or @code{setprecision}.

@defop Operator ostream <<
Write output to an open output stream of class @code{ostream}.
Defined by this library on any @var{object} of a C++ primitive type, and
on other classes of the library.  You can overload the definition for any
of your own applications' classes.

Returns a reference to the implied argument @code{*this} (the open stream it
writes on), permitting statements like
@example
cout << "The value of i is " << i << "\n";
@end example
@end defop

@defop Operator istream >>
Read input from an open input stream of class @code{istream}.  Defined
by this library on primitive numeric, pointer, and string types; you can
extend the definition for any of your own applications' classes.

Returns a reference to the implied argument @code{*this} (the open stream
it reads), permitting multiple inputs in one statement.
@end defop

@node Streams
@chapter Stream Classes

The previous chapter referred in passing to the classes @code{ostream}
and @code{istream}, for output and input respectively.  These classes
share certain properties, captured in their base class @code{ios}.

@menu
* Ios::       Shared properties.
* Ostream::   Managing output streams.
* Istream::   Managing input streams.
* Iostream::  Input and output together.
@end menu

@node Ios
@section Shared properties: class @code{ios}

The base class @code{ios} provides methods to test and manage the state
of input or output streams.

@code{ios} delegates the job of actually reading and writing bytes to
the abstract class @code{streambuf}, which is designed to provide
buffered streams (compatible with C, in the @sc{gnu} implementation).
@xref{Streambuf,,Using the @code{streambuf} layer}, for information on
the facilities available at the @code{streambuf} level.

@deftypefn Constructor {} ios::ios ([streambuf* @var{sb} @w{[, ostream*} @var{tie}])
The @code{ios} constructor by default initializes a new @code{ios}, and
if you supply a @code{streambuf} @var{sb} to associate with it, sets the
state @code{good} in the new @code{ios} object.  It also sets the
default properties of the new object.

@ignore
@c FIXME--future: this (a) doesn't work, (b) is controversial at ANSI
An @code{ios} without a @code{streambuf} has the state @code{bad} until
you supply a @code{streambuf}; you can do that by assigning a new value
to the @code{ios} with @samp{=}.
@end ignore

You can also supply an optional second argument @var{tie} to the
constructor: if present, it is an initial value for @code{ios::tie}, to
associate the new @code{ios} object with another stream.
@end deftypefn

@deftypefn Destructor {} ios::~ios ()
The @code{ios} destructor is virtual, permitting application-specific
behavior when a stream is closed---typically, the destructor frees any
storage associated with the stream and releases any other associated
objects.
@end deftypefn

@c FIXME-future:  Is @deftypefn really the best way of displaying these?

@c FIXME-future: Undocumented: ios::_throw_failure, ios::exceptions; things
@c controlled by _STREAM_COMPAT; ios::Init; ios::_IO_fix_vtable.

@menu
* States::		Checking the state of a stream.
* Format Control::	Choices in formatting.
* Manipulators::	Convenient ways of changing stream properties.
* Extending::		Extended data fields.
* Synchronization::	Synchronizing related streams.
* Streambuf from Ios::	Reaching the underlying streambuf.
@end menu

@node States
@subsection Checking the state of a stream

Use this collection of methods to test for (or signal) errors and other
exceptional conditions of streams:

@deftypefn Method {ios::operator void*} () const
You can do a quick check on the state of the most recent operation on a
stream by examining a pointer to the stream itself.  The pointer is
arbitrary except for its truth value; it is true if no failures have
occurred (@code{ios::fail} is not true).  For example, you might ask for
input on @code{cin} only if all prior output operations succeeded:

@example
if (cout)
@{
  // Everything OK so far
  cin >> new_value;
  @dots{}
@}
@end example
@end deftypefn

@deftypefn Method {ios::operator !} () const
In case it is more convenient to check whether something has failed, the
operator @code{!} returns true if @code{ios::fail} is true (an operation
has failed).  For example,
you might issue an error message if input failed:

@example
if (!cin)
@{
  // Oops
  cerr << "Eh?\n";
@}
@end example
@end deftypefn

@deftypefn Method iostate ios::rdstate () const
Return the state flags for this stream.  The value is from the
enumeration @code{iostate}.  You can test for any combination of

@vtable @code
@item goodbit
There are no indications of exceptional states on this stream.

@item eofbit
End of file.

@item failbit
An operation has failed on this stream; this usually indicates bad
format of input.

@item badbit
The stream is unusable.
@end vtable
@end deftypefn

@deftypefn Method void ios::setstate (iostate @var{state})
@findex ios::set
Set the state flag for this stream to @var{state} @emph{in addition to}
any state flags already set.  Synonym (for upward compatibility):
@code{ios::set}.

See @code{ios::clear} to set the stream state without regard to existing
state flags.  See @code{ios::good}, @code{ios::eof}, @code{ios::fail},
and @code{ios::bad}, to test the state.
@end deftypefn

@deftypefn Method int ios::good () const
Test the state flags associated with this stream; true if no error
indicators are set.
@end deftypefn

@deftypefn Method int ios::bad () const
Test whether a stream is marked as unusable.  (Whether
@code{ios::badbit} is set.)
@end deftypefn

@deftypefn Method int ios::eof () const
True if end of file was reached on this stream.  (If @code{ios::eofbit}
is set.)
@end deftypefn

@deftypefn Method int ios::fail () const
Test for any kind of failure on this stream: @emph{either} some
operation failed, @emph{or} the stream is marked as bad.  (If either
@code{ios::failbit} or @code{ios::badbit} is set.)
@end deftypefn

@deftypefn Method void ios::clear (iostate @var{state})
@c FIXME-future: There is some complication to do with buffering and _throw_failure
Set the state indication for this stream to the argument @var{state}.
You may call @code{ios::clear} with no argument, in which case the state
is set to @code{good} (no errors pending).

See @code{ios::good}, @code{ios::eof}, @code{ios::fail}, and
@code{ios::bad}, to test the state; see @code{ios::set} or
@code{ios::setstate} for an alternative way of setting the state.
@end deftypefn

@node Format Control
@subsection Choices in formatting

These methods control (or report on) settings for some details of
controlling streams, primarily to do with formatting output:

@deftypefn Method char ios::fill () const
Report on the padding character in use.
@end deftypefn

@deftypefn Method char ios::fill (char @var{padding})
Set the padding character.  You can also use the manipulator
@code{setfill}.  @xref{Manipulators,,Changing stream properties in
expressions}.

Default: blank.
@end deftypefn

@deftypefn Method int ios::precision () const
Report the number of significant digits currently in use for output of
floating point numbers.

Default: @code{6}.
@end deftypefn

@deftypefn Method int ios::precision (int @var{signif})
Set the number of significant digits (for input and output numeric
conversions) to @var{signif}.

@findex setprecision
@cindex setting @code{ios::precision}
You can also use the manipulator @code{setprecision} for this purpose.
@xref{Manipulators,,Changing stream properties using manipulators}.
@end deftypefn

@deftypefn Method int ios::width () const
Report the current output field width setting (the number of
characters to write on the next @samp{<<} output operation).

Default: @code{0}, which means to use as many characters as necessary.
@end deftypefn

@deftypefn Method int ios::width (int @var{num})
Set the input field width setting to @var{num}.  Return the
@emph{previous} value for this stream.

@findex setw
@cindex setting @code{ios::width}
This value resets to zero (the default) every time you use @samp{<<}; it is
essentially an additional implicit argument to that operator.  You can
also use the manipulator @code{setw} for this purpose.
@xref{Manipulators,,Changing stream properties using manipulators}.
@end deftypefn

@need 2000
@deftypefn Method fmtflags ios::flags () const
Return the current value of the complete collection of flags controlling
the format state.  These are the flags and their meanings when set:

@vtable @code
@item ios::dec
@itemx ios::oct
@itemx ios::hex
What numeric base to use in converting integers from internal to display
representation, or vice versa: decimal, octal, or hexadecimal,
respectively.  (You can change the base using the manipulator
@code{setbase}, or any of the manipulators @code{dec}, @code{oct}, or
@code{hex}; @pxref{Manipulators,,Changing stream properties in
expressions}.)

On input, if none of these flags is set, read numeric constants
according to the prefix: decimal if no prefix (or a @samp{.} suffix),
octal if a @samp{0} prefix is present, hexadecimal if a @samp{0x} prefix
is present.

Default: @code{dec}.

@item ios::fixed
Avoid scientific notation, and always show a fixed number of digits after
the decimal point, according to the output precision in effect.
Use @code{ios::precision} to set precision.

@item ios::left
@itemx ios::right
@itemx ios::internal
Where output is to appear in a fixed-width field; left-justified,
right-justified, or with padding in the middle (e.g. between a numeric
sign and the associated value), respectively.

@item ios::scientific
Use scientific (exponential) notation to display numbers.

@item ios::showbase
Display the conventional prefix as a visual indicator of the conversion
base: no prefix for decimal, @samp{0} for octal, @samp{0x} for hexadecimal.

@item ios::showpoint
Display a decimal point and trailing zeros after it to fill out numeric
fields, even when redundant.

@item ios::showpos
Display a positive sign on display of positive numbers.

@item ios::skipws
Skip white space.  (On by default).

@item ios::stdio
Flush the C @code{stdio} streams @code{stdout} and @code{stderr} after
each output operation (for programs that mix C and C++ output conventions).

@item ios::unitbuf
Flush after each output operation.

@item ios::uppercase
Use upper-case characters for the non-numeral elements in numeric
displays; for instance, @samp{0X7A} rather than @samp{0x7a}, or
@samp{3.14E+09} rather than @samp{3.14e+09}.
@end vtable
@end deftypefn

@deftypefn Method fmtflags ios::flags (fmtflags @var{value})
Set @var{value} as the complete collection of flags controlling the
format state.  The flag values are described under @samp{ios::flags ()}.

Use @code{ios::setf} or @code{ios::unsetf} to change one property at a
time.
@end deftypefn

@deftypefn Method fmtflags ios::setf (fmtflags @var{flag})
Set one particular flag (of those described for @samp{ios::flags ()};
return the complete collection of flags @emph{previously} in effect.
(Use @code{ios::unsetf} to cancel.)
@end deftypefn

@deftypefn Method fmtflags ios::setf (fmtflags @var{flag}, fmtflags @var{mask})
Clear the flag values indicated by @var{mask}, then set any of them that
are also in @var{flag}.  (Flag values are described for @samp{ios::flags
()}.)  Return the complete collection of flags @emph{previously} in
effect.  (See @code{ios::unsetf} for another way of clearing flags.)
@end deftypefn

@deftypefn Method fmtflags ios::unsetf (fmtflags @var{flag})
Make certain @var{flag} (a combination of flag values described for
@samp{ios::flags ()}) is not set for this stream; converse of
@code{ios::setf}.  Returns the old values of those flags.
@c FIXME-future: should probably be fixed to give same result as setf.
@end deftypefn

@node Manipulators
@subsection Changing stream properties using manipulators

For convenience, @var{manipulators} provide a way to change certain
properties of streams, or otherwise affect them, in the middle of
expressions involving @samp{<<} or @samp{>>}.  For example, you might
write

@example
cout << "|" << setfill('*') << setw(5) << 234 << "|";
@end example

@noindent
to produce @samp{|**234|} as output.

@deftypefn Manipulator {} ws
Skip whitespace.
@end deftypefn

@deftypefn Manipulator {} flush
Flush an output stream.  For example, @samp{cout << @dots{} <<flush;}
has the same effect as @samp{cout << @dots{}; cout.flush();}.
@end deftypefn

@deftypefn Manipulator {} endl
Write an end of line character @samp{\n}, then flushes the output stream.
@end deftypefn

@deftypefn Manipulator {} ends
Write @samp{\0} (the string terminator character).
@end deftypefn

@deftypefn Manipulator {} setprecision (int @var{signif})
You can change the value of @code{ios::precision} in @samp{<<}
expressions with the manipulator @samp{setprecision(@var{signif})}; for
example,

@example
cout << setprecision(2) << 4.567;
@end example

@noindent
prints @samp{4.6}.  Requires @file{#include <iomanip.h>}.
@end deftypefn

@deftypefn Manipulator {} setw (int @var{n})
You can change the value of @code{ios::width} in @samp{<<} expressions
with the manipulator @samp{setw(@var{n})}; for example,

@example
cout << setw(5) << 234;
@end example

@noindent
prints @w{@samp{  234}} with two leading blanks.  Requires @file{#include
<iomanip.h>}.
@end deftypefn

@deftypefn Manipulator {} setbase (int @var{base})
Where @var{base} is one of @code{10} (decimal), @code{8} (octal), or
@code{16} (hexadecimal), change the base value for numeric
representations.  Requires @file{#include <iomanip.h>}.
@end deftypefn

@deftypefn Manipulator {} dec
Select decimal base; equivalent to @samp{setbase(10)}.
@end deftypefn

@deftypefn Manipulator {} hex
Select hexadecimal base; equivalent to @samp{setbase(16)}.
@end deftypefn

@deftypefn Manipulator {} oct
Select octal base; equivalent to @samp{setbase(8)}.
@end deftypefn

@deftypefn Manipulator {} setfill (char @var{padding})
Set the padding character, in the same way as @code{ios::fill}.
Requires @file{#include <iomanip.h>}.
@end deftypefn

@node Extending
@subsection Extended data fields

A related collection of methods allows you to extend this collection of
flags and parameters for your own applications, without risk of conflict
between them:

@deftypefn Method {static fmtflags} ios::bitalloc ()
Reserve a bit (the single bit on in the result) to use as a flag.  Using
@code{bitalloc} guards against conflict between two packages that use
@code{ios} objects for different purposes.

This method is available for upward compatibility, but is not in the
@sc{ansi} working paper.  The number of bits available is limited; a
return value of @code{0} means no bit is available.
@end deftypefn

@deftypefn Method {static int} ios::xalloc ()
Reserve space for a long integer or pointer parameter.  The result is a
unique nonnegative integer.  You can use it as an index to
@code{ios::iword} or @code{ios::pword}.  Use @code{xalloc} to arrange
for arbitrary special-purpose data in your @code{ios} objects, without
risk of conflict between packages designed for different purposes.
@end deftypefn

@deftypefn Method long& ios::iword (int @var{index})
Return a reference to arbitrary data, of long integer type, stored in an
@code{ios} instance.  @var{index}, conventionally returned from
@code{ios::xalloc}, identifies what particular data you need.
@end deftypefn

@deftypefn Method long ios::iword (int @var{index}) const
Return the actual value of a long integer stored in an @code{ios}.
@end deftypefn

@deftypefn Method void*& ios::pword (int @var{index})
Return a reference to an arbitrary pointer, stored in an @code{ios}
instance.  @var{index}, originally returned from @code{ios::xalloc},
identifies what particular pointer you need.
@end deftypefn

@deftypefn Method void* ios::pword (int @var{index}) const
Return the actual value of a pointer stored in an @code{ios}.
@end deftypefn

@node Synchronization
@subsection Synchronizing related streams

You can use these methods to synchronize related streams with
one another:

@deftypefn Method ostream* ios::tie () const
Report on what output stream, if any, is to be flushed before accessing
this one.  A pointer value of @code{0} means no stream is tied.
@end deftypefn

@deftypefn Method ostream* ios::tie (ostream* @var{assoc})
Declare that output stream @var{assoc} must be flushed before accessing
this stream.
@end deftypefn

@deftypefn Method int ios::sync_with_stdio ([int @var{switch}])
Unless iostreams and C @code{stdio} are designed to work together, you
may have to choose between efficient C++ streams output and output
compatible with C @code{stdio}.  Use @samp{ios::sync_with_stdio()} to
select C compatibility.

The argument @var{switch} is a @sc{gnu} extension; use @code{0} as the
argument to choose output that is not necessarily compatible with C
@code{stdio}.  The default value for @var{switch} is @code{1}.

If you install the @code{stdio} implementation that comes with @sc{gnu}
@code{libio}, there are compatible input/output facilities for both C
and C++.  In that situation, this method is unnecessary---but you may
still want to write programs that call it, for portability.
@end deftypefn

@node Streambuf from Ios
@subsection Reaching the underlying @code{streambuf}

Finally, you can use this method to access the underlying object:

@deftypefn Method streambuf* ios::rdbuf () const
Return a pointer to the @code{streambuf} object that underlies this
@code{ios}.
@end deftypefn

@node Ostream
@section Managing output streams: class @code{ostream}

Objects of class @code{ostream} inherit the generic methods from
@code{ios}, and in addition have the following methods available.
Declarations for this class come from @file{iostream.h}.

@deftypefn Constructor {} ostream::ostream ()
The simplest form of the constructor for an @code{ostream} simply
allocates a new @code{ios} object.
@end deftypefn

@deftypefn Constructor {} ostream::ostream (streambuf* @var{sb} @w{[, ostream} @var{tie}])
This alternative constructor requires a first argument @var{sb} of type
@code{streambuf*}, to use an existing open stream for output.  It also
accepts an optional second argument @var{tie}, to specify a related
@code{ostream*} as the initial value for @code{ios::tie}.

If you give the @code{ostream} a @code{streambuf} explicitly, using
this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
closed) when the @code{ostream} is destroyed.
@end deftypefn

@menu
* Writing::		Writing on an ostream.
* Output Position::	Repositioning an ostream.
* Ostream Housekeeping:: Miscellaneous ostream utilities.
@end menu

@node Writing
@subsection Writing on an @code{ostream}

These methods write on an @code{ostream} (you may also use the operator
@code{<<}; @pxref{Operators,,Operators and Default Streams}).

@deftypefn Method ostream& ostream::put (char @var{c})
Write the single character @var{c}.
@end deftypefn

@deftypefn Method ostream& ostream::write (@var{string}, int @var{length})
Write @var{length} characters of a string to this @code{ostream},
beginning at the pointer @var{string}.

@var{string} may have any of these types: @code{char*}, @code{unsigned
char*}, @code{signed char*}.
@end deftypefn

@deftypefn Method ostream& ostream::form (const char *@var{format}, ...)
A @sc{gnu} extension, similar to @code{fprintf(@var{file},
@var{format}, ...)}.

@var{format} is a @code{printf}-style format control string, which is used
to format the (variable number of) arguments, printing the result on
this @code{ostream}.  See @code{ostream::vform} for a version that uses
an argument list rather than a variable number of arguments.
@end deftypefn

@deftypefn Method ostream& ostream::vform (const char *@var{format}, va_list @var{args})
A @sc{gnu} extension, similar to @code{vfprintf(@var{file},
@var{format}, @var{args})}.

@var{format} is a @code{printf}-style format control string, which is used
to format the argument list @var{args}, printing the result on
this @code{ostream}.  See @code{ostream::form} for a version that uses a
variable number of arguments rather than an argument list.
@end deftypefn

@node Output Position
@subsection Repositioning an @code{ostream}

You can control the output position (on output streams that actually
support positions, typically files) with these methods:
@c FIXME-future: sort out which classes support this and which
@c don't; fstream, filebuf?  And what is failure condition when not supported?

@deftypefn Method streampos ostream::tellp ()
Return the current write position in the stream.
@end deftypefn

@deftypefn Method ostream& ostream::seekp (streampos @var{loc})
Reset the output position to @var{loc} (which is usually the result of a
previous call to @code{ostream::tellp}).  @var{loc} specifies an
absolute position in the output stream.
@end deftypefn

@deftypefn Method ostream& ostream::seekp (streamoff @var{loc}, @var{rel})
@findex ios::seekdir
Reset the output position to @var{loc}, relative to the beginning, end,
or current output position in the stream, as indicated by @var{rel} (a
value from the enumeration @code{ios::seekdir}):

@vtable @code
@item beg
Interpret @var{loc} as an absolute offset from the beginning of the
file.

@item cur
Interpret @var{loc} as an offset relative to the current output
position.

@item end
Interpret @var{loc} as an offset from the current end of the output
stream.
@end vtable
@end deftypefn

@node Ostream Housekeeping
@subsection Miscellaneous @code{ostream} utilities

You may need to use these @code{ostream} methods for housekeeping:

@deftypefn Method ostream& flush ()
Deliver any pending buffered output for this @code{ostream}.
@end deftypefn

@deftypefn Method int ostream::opfx ()
@code{opfx} is a @dfn{prefix} method for operations on @code{ostream}
objects; it is designed to be called before any further processing.  See
@code{ostream::osfx} for the converse.
@c FIXME-future: specify sometime which methods start with opfx.

@code{opfx} tests that the stream is in state @code{good}, and if so
flushes any stream tied to this one.

The result is @code{1} when @code{opfx} succeeds; else (if the stream state is
not @code{good}), the result is @code{0}.
@end deftypefn

@deftypefn Method void ostream::osfx ()
@code{osfx} is a @dfn{suffix} method for operations on @code{ostream}
objects; it is designed to be called at the conclusion of any processing.  All
the @code{ostream} methods end by calling @code{osfx}.  See
@code{ostream::opfx} for the converse.

If the @code{unitbuf} flag is set for this stream, @code{osfx} flushes
any buffered output for it.

If the @code{stdio} flag is set for this stream, @code{osfx} flushes any
output buffered for the C output streams @file{stdout} and @file{stderr}.
@end deftypefn

@node Istream
@section Managing input streams: class @code{istream}

Class @code{istream} objects are specialized for input; as for
@code{ostream}, they are derived from @code{ios}, so you can use any of
the general-purpose methods from that base class.  Declarations for this
class also come from @file{iostream.h}.

@deftypefn Constructor {} istream::istream ()
When used without arguments, the @code{istream} constructor simply
allocates a new @code{ios} object and initializes the input counter (the
value reported by @code{istream::gcount}) to @code{0}.
@end deftypefn

@deftypefn Constructor {} istream::istream (streambuf *@var{sb} @w{[, ostream} @var{tie}])
You can also call the constructor with one or two arguments.  The first
argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
the constructor uses that @code{streambuf} for input.
You can use the second optional argument @var{tie} to specify a related
output stream as the initial value for @code{ios::tie}.

If you give the @code{istream} a @code{streambuf} explicitly, using
this constructor, the @var{sb} is @emph{not} destroyed (or deleted or
closed) when the @code{ostream} is destroyed.
@end deftypefn

@menu
* Char Input::		Reading one character.
* String Input::	Reading strings.
* Input Position::	Repositioning an istream.
* Istream Housekeeping:: Miscellaneous istream utilities.
@end menu

@node Char Input
@subsection Reading one character

Use these methods to read a single character from the input stream:

@deftypefn Method int istream::get ()
Read a single character (or @code{EOF}) from the input stream, returning
it (coerced to an unsigned char) as the result.
@end deftypefn

@deftypefn Method istream& istream::get (char& @var{c})
Read a single character from the input stream, into @code{&@var{c}}.
@end deftypefn

@deftypefn Method int istream::peek ()
Return the next available input character, but @emph{without} changing
the current input position.
@end deftypefn

@node String Input
@subsection Reading strings

Use these methods to read strings (for example, a line at a time) from
the input stream:

@deftypefn Method istream& istream::get (char* @var{c}, int @var{len} @w{[, char} @var{delim}])
Read a string from the input stream, into the array at @var{c}.

The remaining arguments limit how much to read: up to @samp{len-1}
characters, or up to (but not including) the first occurrence in the
input of a particular delimiter character @var{delim}---newline
(@code{\n}) by default.  (Naturally, if the stream reaches end of file
first, that too will terminate reading.)

If @var{delim} was present in the input, it remains available as if
unread; to discard it instead, see @code{iostream::getline}.

@code{get} writes @samp{\0} at the end of the string, regardless
of which condition terminates the read.
@end deftypefn

@deftypefn Method istream& istream::get (streambuf& @var{sb} @w{[, char} @var{delim}])
Read characters from the input stream and copy them on the
@code{streambuf} object @var{sb}.  Copying ends either just before the
next instance of the delimiter character @var{delim} (newline @code{\n}
by default), or when either stream ends.   If @var{delim} was present in
the input, it remains available as if unread.
@end deftypefn

@deftypefn Method istream& istream::getline (@var{charptr}, int @var{len} @w{[, char} @var{delim}])
Read a line from the input stream, into the array at @var{charptr}.
@var{charptr} may be any of three kinds of pointer: @code{char*},
@code{unsigned char*}, or @code{signed char*}.

The remaining arguments limit how much to read: up to (but not
including) the first occurrence in the input of a line delimiter
character @var{delim}---newline (@code{\n}) by default, or up to
@samp{len-1} characters (or to end of file, if that happens sooner).

If @code{getline} succeeds in reading a ``full line'', it also discards
the trailing delimiter character from the input stream.  (To preserve it
as available input, see the similar form of @code{iostream::get}.)

If @var{delim} was @emph{not} found before @var{len} characters or end
of file, @code{getline} sets the @code{ios::fail} flag, as well as the
@code{ios::eof} flag if appropriate.

@code{getline} writes a null character at the end of the string, regardless
of which condition terminates the read.
@end deftypefn

@deftypefn Method istream& istream::read (@var{pointer}, int @var{len})
Read @var{len} bytes into the location at @var{pointer}, unless the
input ends first.

@var{pointer} may be of type @code{char*}, @code{void*}, @code{unsigned
char*}, or @code{signed char*}.

If the @code{istream} ends before reading @var{len} bytes, @code{read}
sets the @code{ios::fail} flag.
@end deftypefn

@deftypefn Method istream& istream::gets (char **@var{s} @w{[, char} @var{delim}])
A @sc{gnu} extension, to read an arbitrarily long string
from the current input position to the next instance of the @var{delim}
character (newline @code{\n} by default).

To permit reading a string of arbitrary length, @code{gets} allocates
whatever memory is required.  Notice that the first argument @var{s} is
an address to record a character pointer, rather than the pointer
itself.
@end deftypefn

@deftypefn Method istream& istream::scan (const char *format ...)
A @sc{gnu} extension, similar to @code{fscanf(@var{file},
@var{format}, ...)}.  The @var{format} is a @code{scanf}-style format
control string, which is used to read the variables in the remainder of
the argument list from the @code{istream}.
@end deftypefn

@deftypefn Method istream& istream::vscan (const char *format, va_list args)
Like @code{istream::scan}, but takes a single @code{va_list} argument.
@end deftypefn

@node Input Position
@subsection Repositioning an @code{istream}

Use these methods to control the current input position:

@deftypefn Method streampos istream::tellg ()
Return the current read position, so that you can save it and return to
it later with @code{istream::seekg}.
@end deftypefn

@deftypefn Method istream& istream::seekg (streampos @var{p})
Reset the input pointer (if the input device permits it) to @var{p},
usually the result of an earlier call to @code{istream::tellg}.
@end deftypefn

@deftypefn Method istream& istream::seekg (streamoff @var{offset}, ios::seek_dir @var{ref})
Reset the input pointer (if the input device permits it) to @var{offset}
characters from the beginning of the input, the current position, or the
end of input.  Specify how to interpret @var{offset} with one of these
values for the second argument:

@vtable @code
@item ios::beg
Interpret @var{loc} as an absolute offset from the beginning of the
file.

@item ios::cur
Interpret @var{loc} as an offset relative to the current output
position.

@item ios::end
Interpret @var{loc} as an offset from the current end of the output
stream.
@end vtable
@end deftypefn

@node Istream Housekeeping
@subsection Miscellaneous @code{istream} utilities

Use these methods for housekeeping on @code{istream} objects:

@deftypefn Method int istream::gcount ()
Report how many characters were read from this @code{istream} in the
last unformatted input operation.
@c FIXME! Define "unformatted input" somewhere...
@end deftypefn

@deftypefn Method int istream::ipfx (int @var{keepwhite})
Ensure that the @code{istream} object is ready for reading; check for
errors and end of file and flush any tied stream.  @code{ipfx} skips
whitespace if you specify @code{0} as the @var{keepwhite}
argument, @emph{and} @code{ios::skipws} is set for this stream.

To avoid skipping whitespace (regardless of the @code{skipws} setting on
the stream), use @code{1} as the argument.

Call @code{istream::ipfx} to simplify writing your own methods for reading
@code{istream} objects.
@end deftypefn

@deftypefn Method void istream::isfx ()
A placeholder for compliance with the draft @sc{ansi} standard; this
method does nothing whatever.

If you wish to write portable standard-conforming code on @code{istream}
objects, call @code{isfx} after any operation that reads from an
@code{istream}; if @code{istream::ipfx} has any special effects that
must be cancelled when done, @code{istream::isfx} will cancel them.
@end deftypefn

@deftypefn Method istream& istream::ignore ([int @var{n}] @w{[, int} @var{delim}])
Discard some number of characters pending input.  The first optional
argument @var{n} specifies how many characters to skip.  The second
optional argument @var{delim} specifies a ``boundary'' character:
@code{ignore} returns immediately if this character appears in the
input.

By default, @var{delim} is @code{EOF}; that is, if you do not specify a
second argument, only the count @var{n} restricts how much to ignore
(while input is still available).

If you do not specify how many characters to ignore, @code{ignore}
returns after discarding only one character.
@end deftypefn

@deftypefn Method istream& istream::putback (char @var{ch})
Attempts to back up one character, replacing the character backed-up
over by @var{ch}.  Returns @code{EOF} if this is not allowed.  Putting
back the most recently read character is always allowed.  (This method
corresponds to the C function @code{ungetc}.)
@end deftypefn

@deftypefn Method istream& istream::unget ()
Attempt to back up one character.
@end deftypefn

@node Iostream
@section Input and output together: class @code{iostream}

If you need to use the same stream for input and output, you can use an
object of the class @code{iostream}, which is derived from @emph{both}
@code{istream} and @code{ostream}.

The constructors for @code{iostream} behave just like the constructors
for @code{istream}.

@deftypefn Constructor {} iostream::iostream ()
When used without arguments, the @code{iostream} constructor simply
allocates a new @code{ios} object, and initializes the input counter
(the value reported by @code{istream::gcount}) to @code{0}.
@end deftypefn

@deftypefn Constructor {} iostream::iostream (streambuf* @var{sb} @w{[, ostream*} @var{tie}])
You can also call a constructor with one or two arguments.  The first
argument @var{sb} is a @code{streambuf*}; if you supply this pointer,
the constructor uses that @code{streambuf} for input and output.

You can use the optional second argument @var{tie} (an @code{ostream*})
to specify a related output stream as the initial value for
@code{ios::tie}.
@end deftypefn

@cindex @code{iostream} destructor
@cindex destructor for @code{iostream}
As for @code{ostream} and @code{istream}, @code{iostream} simply uses
the @code{ios} destructor.  However, an @code{iostream} is not deleted by
its destructor.

You can use all the @code{istream}, @code{ostream}, and @code{ios}
methods with an @code{iostream} object.

@node Files and Strings
@chapter Classes for Files and Strings

There are two very common special cases of input and output: using files,
and using strings in memory.

@code{libio} defines four specialized classes for these cases:

@ftable @code
@item ifstream
Methods for reading files.

@item ofstream
Methods for writing files.

@item istrstream
Methods for reading strings from memory.

@item ostrstream
Methods for writing strings in memory.
@end ftable

@menu
* Files::	Reading and writing files.
* Strings::	Reading and writing strings in memory.
@end menu

@node Files
@section Reading and writing files

These methods are declared in @file{fstream.h}.

@findex ifstream
@cindex class @code{ifstream}
You can read data from class @code{ifstream} with any operation from class
@code{istream}.  There are also a few specialized facilities:

@deftypefn Constructor {} ifstream::ifstream ()
Make an @code{ifstream} associated with a new file for input.  (If you
use this version of the constructor, you need to call
@code{ifstream::open} before actually reading anything)
@end deftypefn

@deftypefn Constructor {} ifstream::ifstream (int @var{fd})
Make an @code{ifstream} for reading from a file that was already open,
using file descriptor @var{fd}.  (This constructor is compatible with
other versions of iostreams for @sc{posix} systems, but is not part of
the @sc{ansi} working paper.)
@end deftypefn

@deftypefn Constructor {} ifstream::ifstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
Open a file @code{*@var{fname}} for this @code{ifstream} object.

By default, the file is opened for input (with @code{ios::in} as
@var{mode}).  If you use this constructor, the file will be closed when
the @code{ifstream} is destroyed.

You can use the optional argument @var{mode} to specify how to open the
file, by combining these enumerated values (with @samp{|} bitwise or).
(These values are actually defined in class @code{ios}, so that all
file-related streams may inherit them.)  Only some of these modes are
defined in the latest draft @sc{ansi} specification; if portability is
important, you may wish to avoid the others.

@vtable @code
@item ios::in
Open for input.  (Included in @sc{ansi} draft.)

@item ios::out
Open for output.  (Included in @sc{ansi} draft.)

@item ios::ate
Set the initial input (or output) position to the end of the file.

@item ios::app
Seek to end of file before each write.  (Included in @sc{ansi} draft.)

@item ios::trunc
Guarantee a fresh file; discard any contents that were previously
associated with it.

@item ios::nocreate
Guarantee an existing file; fail if the specified file did not already
exist.

@item ios::noreplace
Guarantee a new file; fail if the specified file already existed.

@item ios::bin
Open as a binary file (on systems where binary and text files have different
properties, typically how @samp{\n} is mapped; included in @sc{ansi} draft).
@end vtable

@noindent
The last optional argument @var{prot} is specific to Unix-like systems;
it specifies the file protection (by default @samp{644}).
@end deftypefn

@deftypefn Method void ifstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
Open a file explicitly after the associated @code{ifstream} object
already exists (for instance, after using the default constructor).  The
arguments, options and defaults all have the same meanings as in the
fully specified @code{ifstream} constructor.
@end deftypefn

@findex ostream
@cindex class @code{ostream}
You can write data to class @code{ofstream} with any operation from class
@code{ostream}.  There are also a few specialized facilities:

@deftypefn Constructor {} ofstream::ofstream ()
Make an @code{ofstream} associated with a new file for output.
@end deftypefn

@deftypefn Constructor {} ofstream::ofstream (int @var{fd})
Make an @code{ofstream} for writing to a file that was already open,
using file descriptor @var{fd}.
@end deftypefn

@deftypefn Constructor {} ofstream::ofstream (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
Open a file @code{*@var{fname}} for this @code{ofstream} object.

By default, the file is opened for output (with @code{ios::out} as @var{mode}).
You can use the optional argument @var{mode} to specify how to open the
file, just as described for @code{ifstream::ifstream}.

The last optional argument @var{prot} specifies the file protection (by
default @samp{644}).
@end deftypefn

@deftypefn Destructor {} ofstream::~ofstream ()
The files associated with @code{ofstream} objects are closed when the
corresponding object is destroyed.
@end deftypefn

@deftypefn Method void ofstream::open (const char* @var{fname} @w{[, int} @var{mode} @w{[, int} @var{prot}]])
Open a file explicitly after the associated @code{ofstream} object
already exists (for instance, after using the default constructor).  The
arguments, options and defaults all have the same meanings as in the
fully specified @code{ofstream} constructor.
@end deftypefn

@findex fstream
@cindex class @code{fstream}
The class @code{fstream} combines the facilities of @code{ifstream} and
@code{ofstream}, just as @code{iostream} combines @code{istream} and
@code{ostream}.

@c FIXME-future: say something about fstream constructor, maybe.

@findex fstreambase
@cindex class @code{fstreambase}
The class @code{fstreambase} underlies both @code{ifstream} and
@code{ofstream}.  They both inherit this additional method:

@deftypefn Method void fstreambase::close ()
Close the file associated with this object, and set @code{ios::fail} in
this object to mark the event.
@end deftypefn

@node Strings
@section Reading and writing in memory

@c FIXME!! Per, there's a lot of guesswork here---please check carefully!

@findex istrstream
@cindex class @code{istrstream}
@findex ostrstream
@cindex class @code{ostrstream}
@findex strstream
@cindex class @code{strstream}
@findex strstreambase
@cindex class @code{strstreambase}
@findex strstreambuf
@cindex class @code{strstreambuf}
The classes @code{istrstream}, @code{ostrstream}, and @code{strstream}
provide some additional features for reading and writing strings in
memory---both static strings, and dynamically allocated strings.  The
underlying class @code{strstreambase} provides some features common to
all three; @code{strstreambuf} underlies that in turn.

@c FIXME-future:  Document strstreambuf methods one day, when we document
@c streambuf more fully.

@deftypefn Constructor {} istrstream::istrstream (const char* @var{str} @w{[, int} @var{size}])
Associate the new input string class @code{istrstream} with an existing
static string starting at @var{str}, of size @var{size}.  If you do not
specify @var{size}, the string is treated as a @code{NUL} terminated string.
@end deftypefn

@deftypefn Constructor {} ostrstream::ostrstream ()
Create a new stream for output to a dynamically managed string, which
will grow as needed.
@end deftypefn

@deftypefn Constructor {} ostrstream::ostrstream (char* @var{str}, int @var{size} [,int @var{mode}])
A new stream for output to a statically defined string of length
@var{size}, starting at @var{str}.  You may optionally specify one of
the modes described for @code{ifstream::ifstream}; if you do not specify
one, the new stream is simply open for output, with mode @code{ios::out}.
@end deftypefn

@deftypefn Method int ostrstream::pcount ()
Report the current length of the string associated with this @code{ostrstream}.
@end deftypefn

@deftypefn Method char* ostrstream::str ()
A pointer to the string managed by this @code{ostrstream}.  Implies
@samp{ostrstream::freeze()}.

Note that if you want the string to be nul-terminated,
you must do that yourself (perhaps by writing ends to the stream).
@end deftypefn

@deftypefn Method void ostrstream::freeze ([int @var{n}])
If @var{n} is nonzero (the default), declare that the string associated
with this @code{ostrstream} is not to change dynamically; while frozen,
it will not be reallocated if it needs more space, and it will not be
deallocated when the @code{ostrstream} is destroyed.  Use
@samp{freeze(1)} if you refer to the string as a pointer after creating
it via @code{ostrstream} facilities.

@samp{freeze(0)} cancels this declaration, allowing a dynamically
allocated string to be freed when its @code{ostrstream} is destroyed.

If this @code{ostrstream} is already static---that is, if it was created
to manage an existing statically allocated string---@code{freeze} is
unnecessary, and has no effect.
@end deftypefn

@deftypefn Method int ostrstream::frozen ()
Test whether @code{freeze(1)} is in effect for this string.
@end deftypefn

@deftypefn Method strstreambuf* strstreambase::rdbuf ()
A pointer to the underlying @code{strstreambuf}.
@end deftypefn

@node Streambuf
@chapter Using the @code{streambuf} Layer

The @code{istream} and @code{ostream} classes are meant to handle
conversion between objects in your program and their textual representation.

By contrast, the underlying @code{streambuf} class is for transferring
raw bytes between your program, and input sources or output sinks.
Different @code{streambuf} subclasses connect to different kinds of
sources and sinks.

The @sc{gnu} implementation of @code{streambuf} is still evolving; we
describe only some of the highlights.

@menu
* Areas::		Areas in a streambuf.
* Overflow::		Simple output re-direction
* Formatting::		C-style formatting for streambuf objects.
* Stdiobuf::		Wrappers for C stdio.
* Procbuf::             Reading/writing from/to a pipe
* Backing Up::		Marking and returning to a position.
* Indirectbuf::		Forwarding I/O activity.
@end menu

@node Areas
@section Areas of a @code{streambuf}

Streambuf buffer management is fairly sophisticated (this is a
nice way to say ``complicated'').  The standard protocol
has the following ``areas'':

@itemize @bullet
@item
@cindex put area
The @dfn{put area} contains characters waiting for output.

@item
@cindex get area
The @dfn{get area} contains characters available for reading.
@end itemize

The @sc{gnu} @code{streambuf} design extends this, but the details are
still evolving.

The following methods are used to manipulate these areas.
These are all protected methods, which are intended to be
used by virtual function in classes derived from @code{streambuf}.
They are also all ANSI/ISO-standard, and the ugly names
are traditional.
(Note that if a pointer points to the 'end' of an area,
it means that it points to the character after the area.)

@deftypefn Method char* streambuf::pbase () const
Returns a pointer to the start of the put area.
@end deftypefn

@deftypefn Method char* streambuf::epptr () const
Returns a pointer to the end of the put area.
@end deftypefn

@deftypefn Method char* streambuf::pptr () const
If @code{pptr() < epptr ()}, the @code{pptr()}
returns a pointer to the current put position.
(In that case, the next write will
overwrite @code{*pptr()}, and increment @code{pptr()}.)
Otherwise, there is no put position available
(and the next character written will cause @code{streambuf::overflow}
to be called).
@end deftypefn

@deftypefn Method void streambuf::pbump (int @var{N})
Add @var{N} to the current put pointer.
No error checking is done.
@end deftypefn

@deftypefn Method void streambuf::setp (char* @var{P}, char* @var{E})
Sets the start of the put area to @var{P}, the end of the put area to @var{E},
and the current put pointer to @var{P} (also).
@end deftypefn

@deftypefn Method char* streambuf::eback () const
Returns a pointer to the start of the get area.
@end deftypefn

@deftypefn Method char* streambuf::egptr () const
Returns a pointer to the end of the get area.
@end deftypefn

@deftypefn Method char* streambuf::gptr () const
If @code{gptr() < egptr ()}, then @code{gptr()}
returns a pointer to the current get position.
(In that case the next read will read @code{*gptr()},
and possibly increment @code{gptr()}.)
Otherwise, there is no read position available
(and the next read will cause @code{streambuf::underflow}
to be called).
@end deftypefn

@deftypefn Method void streambuf:gbump (int @var{N})
Add @var{N} to the current get pointer.
No error checking is done.
@end deftypefn

@deftypefn Method void streambuf::setg (char* @var{B}, char* @var{P}, char* @var{E})
Sets the start of the get area to @var{B}, the end of the get area to @var{E},
and the current put pointer to @var{P}.
@end deftypefn

@node Overflow
@section Simple output re-direction by redefining @code{overflow}

Suppose you have a function @code{write_to_window} that
writes characters to a @code{window} object.  If you want to use the
ostream function to write to it, here is one (portable) way to do it.
This depends on the default buffering (if any).

@cartouche
@smallexample
#include <iostream.h>
/* Returns number of characters successfully written to @var{win}. */
extern int write_to_window (window* win, char* text, int length);

class windowbuf : public streambuf @{
    window* win;
  public:
    windowbuf (window* w) @{ win = w; @}
    int sync ();
    int overflow (int ch);
    // Defining xsputn is an optional optimization.
    // (streamsize was recently added to ANSI C++, not portable yet.)
    streamsize xsputn (char* text, streamsize n);
@};

int windowbuf::sync ()
@{ streamsize n = pptr () - pbase ();
  return (n && write_to_window (win, pbase (), n) != n) ? EOF : 0;
@}

int windowbuf::overflow (int ch)
@{ streamsize n = pptr () - pbase ();
  if (n && sync ())
    return EOF;
  if (ch != EOF)
    @{
      char cbuf[1];
      cbuf[0] = ch;
      if (write_to_window (win, cbuf, 1) != 1)
        return EOF;
    @}
  pbump (-n);  // Reset pptr().
  return 0;
@}

streamsize windowbuf::xsputn (char* text, streamsize n)
@{ return sync () == EOF ? 0 : write_to_window (win, text, n); @}

int
main (int argc, char**argv)
@{
  window *win = ...;
  windowbuf wbuf(win);
  ostream wstr(&wbuf);
  wstr << "Hello world!\n";
@}
@end smallexample
@end cartouche



@node Formatting
@section C-style formatting for @code{streambuf} objects

The @sc{gnu} @code{streambuf} class supports @code{printf}-like
formatting and scanning.

@deftypefn Method int streambuf::form (const char *@var{format}, ...)
Similar to @code{fprintf(@var{file}, @var{format}, ...)}.
The @var{format} is a @code{printf}-style format control string, which is used
to format the (variable number of) arguments, printing the result on
the @code{this} streambuf.  The result is the number of characters printed.
@end deftypefn

@deftypefn Method int streambuf::vform (const char *@var{format}, va_list @var{args})
Similar to @code{vfprintf(@var{file}, @var{format}, @var{args})}.
The @var{format} is a @code{printf}-style format control string, which is used
to format the argument list @var{args}, printing the result on
the @code{this} streambuf.  The result is the number of characters printed.
@end deftypefn

@deftypefn Method int streambuf::scan (const char *@var{format}, ...)
Similar to @code{fscanf(@var{file}, @var{format}, ...)}.
The @var{format} is a @code{scanf}-style format control string, which is used
to read the (variable number of) arguments from the @code{this} streambuf.
The result is the number of items assigned, or @code{EOF} in case of
input failure before any conversion.
@end deftypefn

@deftypefn Method int streambuf::vscan (const char *@var{format}, va_list @var{args})
Like @code{streambuf::scan}, but takes a single @code{va_list} argument.
@end deftypefn

@node Stdiobuf
@section Wrappers for C @code{stdio}

A @dfn{stdiobuf} is a @code{streambuf} object that points to
a @code{FILE} object (as defined by @code{stdio.h}).
All @code{streambuf} operations on the @code{stdiobuf} are forwarded
to the @code{FILE}.  Thus the @code{stdiobuf} object provides a
wrapper around a @code{FILE}, allowing use of @code{streambuf}
operations on a @code{FILE}.  This can be useful when mixing
C code with C++ code.

The pre-defined streams @code{cin}, @code{cout}, and @code{cerr} are
normally implemented as @code{stdiobuf} objects that point to
respectively @code{stdin}, @code{stdout}, and @code{stderr}.  This is
convenient, but it does cost some extra overhead.

If you set things up to use the implementation of @code{stdio} provided
with this library, then @code{cin}, @code{cout}, and @code{cerr} will be
set up to use @code{stdiobuf} objects, since you get their benefits
for free.  @xref{Stdio,,C Input and Output}.

@ignore
@c FIXME-future: setbuf is not yet documented, hence this para is not useful.
Note that if you use @code{setbuf} to give a buffer to a @code{stdiobuf},
that buffer will provide intermediate buffering in addition that
whatever is done by the @code{FILE}.
@end ignore

@node Procbuf
@section Reading/writing from/to a pipe

The @dfn{procbuf} class is a @sc{gnu} extension.  It is derived from
@code{streambuf}.  A @code{procbuf} can be @dfn{closed} (in which case
it does nothing), or @dfn{open} (in which case it allows communicating
through a pipe with some other program).

@deftypefn Constructor {} procbuf::procbuf ()
Creates a @code{procbuf} in a @dfn{closed} state.
@end deftypefn

@deftypefn Method procbuf* procbuf::open (const char *@var{command}, int @var{mode})
Uses the shell (@file{/bin/sh}) to run a program specified by @var{command}.

If @var{mode} is @samp{ios::in}, standard output from the program is sent
to a pipe; you can read from the pipe by reading from the
@code{procbuf}.  (This is similar to @w{@samp{popen(@var{command}, "r")}}.)

If @var{mode} is @samp{ios::out}, output written to the
@code{procbuf} is written to a pipe; the program is set up to read its
standard input from (the other end of) the pipe.  (This is similar to
@w{@samp{popen(@var{command}, "w")}}.)

The @code{procbuf} must start out in the @dfn{closed} state.
Returns @samp{*this} on success, and @samp{NULL} on failure.
@end deftypefn

@deftypefn Constructor {} procbuf::procbuf (const char *@var{command}, int @var{mode})
Calls @samp{procbuf::open (@var{command}, @var{mode})}.
@end deftypefn

@deftypefn Method procbuf* procbuf::close ()
Waits for the program to finish executing,
and then cleans up the resources used.
Returns @samp{*this} on success, and @samp{NULL} on failure.
@end deftypefn

@deftypefn Destructor {} procbuf::~procbuf ()
Calls @samp{procbuf::close}.
@end deftypefn

@node Backing Up
@section Backing up

The @sc{gnu} iostream library allows you to ask a @code{streambuf} to
remember the current position.  This allows you to go back to this
position later, after reading further.  You can back up arbitrary
amounts, even on unbuffered files or multiple buffers' worth, as long as
you tell the library in advance.  This unbounded backup is very useful
for scanning and parsing applications.  This example shows a typical
scenario:

@cartouche
@smallexample
// Read either "dog", "hound", or "hounddog".
// If "dog" is found, return 1.
// If "hound" is found, return 2.
// If "hounddog" is found, return 3.
// If none of these are found, return -1.
int my_scan(streambuf* sb)
@{
    streammarker fence(sb);
    char buffer[20];
    // Try reading "hounddog":
    if (sb->sgetn(buffer, 8) == 8
        && strncmp(buffer, "hounddog", 8) == 0)
      return 3;
    // No, no "hounddog":  Back up to 'fence'
    sb->seekmark(fence); // 
    // ... and try reading "dog":
    if (sb->sgetn(buffer, 3) == 3
        && strncmp(buffer, "dog", 3) == 0)
      return 1;
    // No, no "dog" either:  Back up to 'fence'
    sb->seekmark(fence); // 
    // ... and try reading "hound":
    if (sb->sgetn(buffer, 5) == 5
        && strncmp(buffer, "hound", 5) == 0)
      return 2;
    // No, no "hound" either:  Back up and signal failure.
    sb->seekmark(fence); // Backup to 'fence'
    return -1;
@}
@end smallexample
@end cartouche

@deftypefn Constructor {} streammarker::streammarker (streambuf* @var{sbuf})
Create a @code{streammarker} associated with @var{sbuf}
that remembers the current position of the get pointer.
@end deftypefn

@deftypefn Method int streammarker::delta (streammarker& @var{mark2})
Return the difference between the get positions corresponding
to @code{*this} and @var{mark2} (which must point into the same
@code{streambuffer} as @code{this}).
@end deftypefn

@deftypefn Method int streammarker::delta ()
Return the position relative to the streambuffer's current get position.
@end deftypefn

@deftypefn Method int streambuf::seekmark (streammarker& @var{mark})
Move the get pointer to where it (logically) was when @var{mark}
was constructed.
@end deftypefn

@node Indirectbuf
@section Forwarding I/O activity

An @dfn{indirectbuf} is one that forwards all of its I/O requests
to another streambuf.

@ignore
@c FIXME-future: get_stream and put_stream are so far undocumented.
All get-related requests are sent to get_stream().
All put-related requests are sent to put_stream().
@end ignore

An @code{indirectbuf} can be used to implement Common Lisp
synonym-streams and two-way-streams:

@example
class synonymbuf : public indirectbuf @{
   Symbol *sym;
   synonymbuf(Symbol *s) @{ sym = s; @}
   virtual streambuf *lookup_stream(int mode) @{
       return coerce_to_streambuf(lookup_value(sym)); @}
@};
@end example

@node Stdio
@chapter C Input and Output

@code{libio} is distributed with a complete implementation of the ANSI C
@code{stdio} facility.  It is implemented using @code{streambuf}
objects.  @xref{Stdiobuf,,Wrappers for C @code{stdio}}.

The @code{stdio} package is intended as a replacement for the whatever
@code{stdio} is in your C library.
@ignore
@c FIXME-future:  This is not useful unless we specify what problems.
It can co-exist with C libraries that have alternate implementations of
stdio, but there may be some problems.
@end ignore
Since @code{stdio} works best when you build @code{libc} to contain it, and
that may be inconvenient, it is not installed by default.

Extensions beyond @sc{ansi}:

@itemize @bullet
@item
A stdio @code{FILE} is identical to a streambuf.
Hence there is no need to worry about synchronizing C and C++
input/output---they are by definition always synchronized.

@item
If you create a new streambuf sub-class (in C++), you can use it as a
@code{FILE} from C.  Thus the system is extensible using the standard
@code{streambuf} protocol.

@item
You can arbitrarily mix reading and writing, without having to seek
in between.

@item
Unbounded @code{ungetc()} buffer.
@end itemize

@ignore
@c FIXME-future: Per says this is not ready to go public at v0.5
@node Libio buffer management
@chapter Libio buffer management

The libio user functions present an abstract sequence of characters,
that they read and write from.  A number of buffers are used to go
between the user program and the abstract sequence.  These buffers are
concrete arrays of characters that contain some sub-sequence of the
abstract sequence.

The libio buffer management protocol is fairly complex.  Its design is
based on the C++ @code{streambuf} protocol, so that the C++
@code{streambuf} classes can be trivially implemented on top of the
libio protocol.

The @dfn{write area} contains characters waiting for output.

The @dfn{read area} contains characters available for reading.

The @dfn{reserve area} is available to virtual methods.
Usually, the get and/or put areas are part of the reserve area.

The @dfn{main get area} contains characters that have
been read in from the character source, but not yet
read by the application.

The @dfn{backup area} contains previously read data that is being saved
because of a user request, or that have been "unread" (put back).
@end ignore

@ignore
@c Per says this design is not finished
@node Streambuf internals
@chapter Streambuf internals

@menu
* Buffer management::
* Filebuf internals::
@end menu

@node Buffer management
@section Buffer management

@subsection Areas

NOTE:  This chapter is due for an update.

Streambuf buffer management is fairly sophisticated (this is a
nice way to say "complicated").  The standard protocol
has the following "areas":

@itemize @bullet
@cindex put area
@item
The @dfn{put area} contains characters waiting for output.
@cindex get area
@item
The @dfn{get area} contains characters available for reading.
@cindex reserve area
@item
The @dfn{reserve area} is available to virtual methods.
Usually, the get and/or put areas are part of the reserve area.
@end itemize

The @sc{gnu} @code{streambuf} design extends this by supporting two
get areas:
@itemize @bullet
@cindex main get area
@item
The @dfn{main get area} contains characters that have
been read in from the character source, but not yet
read by the application.
@cindex backup area
@item
The @dfn{backup area} contains previously read data that is being
saved because of a user request, or that have been "unread" (putback).
@end itemize

The backup and the main get area are logically contiguous:  That is,
the first character of the main get area follows the last character
of the backup area.

The @dfn{current get area} is whichever one of the backup or
main get areas that is currently being read from.
The other of the two is the @dfn{non-current get area}.

@subsection Pointers

The following @code{char*} pointers define the various areas.

@deftypefn Method char* streambuf::base ()
The start of the reserve area.
@end deftypefn

@deftypefn Method char* streambuf::ebuf ()
The end of the reserve area.
@end deftypefn

@deftypefn Method char* streambuf::Gbase ()
The start of the main get area.
@end deftypefn

@deftypefn Method char* streambuf::eGptr ()
The end of the main get area.
@end deftypefn

@deftypefn Method char* streambuf::Bbase ()
The start of the backup area.
@end deftypefn

@deftypefn Method char* streambuf::Bptr ()
The start of the used part of the backup area.
The area (@code{Bptr()} .. @code{eBptr()}) contains data that has been
pushed back, while (@code{Bbase()} .. @code{eBptr()}) contains unused
space available for future putbacks.
@end deftypefn

@deftypefn Method char* streambuf::eBptr ()
The end of the backup area.
@end deftypefn

@deftypefn Method char* streambuf::Nbase ()
The start of the non-current get area (either @code{main_gbase} or @code{backup_gbase}).
@end deftypefn

@deftypefn Method char* streambuf::eNptr ()
The end of the non-current get area.
@end deftypefn

@node Filebuf internals
@section Filebuf internals

The @code{filebuf} is used a lot, so it is importamt that it be
efficient.  It is also supports rather complex semantics.
so let us examine its implementation.

@subsection Tied read and write pointers

The streambuf model allows completely independent read and write pointers.
However, a @code{filebuf} has only a single logical pointer used
for both reads and writes.  Since the @code{streambuf} protocol
uses @code{gptr()} for reading and @code{pptr()} for writing,
we map the logical file pointer into either @code{gptr()} or @code{pptr()}
at different times.

@itemize @bullet
@item
Reading is allowed when @code{gptr() < egptr()}, which we call get mode.

@item
Writing is allowed when @code{pptr() < epptr()}, which we call put mode.
@end itemize

@noindent
A @code{filebuf} cannot be in get mode and put mode at the same time.

We have up to two buffers:

@itemize @bullet
@item
The backup area, defined by @code{Bbase()}, @code{Bptr()}, and @code{eBptr()}.
This can be empty.

@item
The reserve area, which also contains the main get area.
For an unbuffered file, the (@code{shortbuf()}..@code{shortbuf()+1}) is used,
where @code{shortbuf()} points to a 1-byte buffer that is part of
the @code{filebuf}.
@end itemize

@noindent
The file system's idea of the current position is @code{eGptr()}.

Characters that have been written into a buffer but not yet written
out (flushed) to the file systems are those between @code{pbase()}
and @code{pptr()}.

The end of the valid data bytes is:
@code{pptr() > eGptr() && pptr() < ebuf() ? pptr() : eGptr()}.

If the @code{filebuf} is unbuffered or line buffered,
the @code{eptr()} is @code{pbase()}.  This forces a call
to @code{overflow()} on each put of a character.
The logical @code{epptr()} is @code{epptr() ? ebuf() : NULL}.
(If the buffer is read-only, set @code{pbase()}, @code{pptr()},
and @code{epptr()} to @code{NULL}. NOT!)
@end ignore

@node Index
@unnumbered Index
@printindex cp

@contents
@bye
OpenPOWER on IntegriCloud