libstdc++: streambuf Source File

libstdc++

streambuf
Go to the documentation of this file.
1// Stream buffer classes -*- C++ -*-
2
3// Copyright (C) 1997-2026 Free Software Foundation, Inc.
4//
5// This file is part of the GNU ISO C++ Library. This library is free
6// software; you can redistribute it and/or modify it under the
7// terms of the GNU General Public License as published by the
8// Free Software Foundation; either version 3, or (at your option)
9// any later version.
10
11// This library is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// Under Section 7 of GPL version 3, you are granted additional
17// permissions described in the GCC Runtime Library Exception, version
18// 3.1, as published by the Free Software Foundation.
19
20// You should have received a copy of the GNU General Public License and
21// a copy of the GCC Runtime Library Exception along with this program;
22// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23// <http://www.gnu.org/licenses/>.
24
25/** @file include/streambuf
26 * This is a Standard C++ Library header.
27 */
28
29//
30// ISO C++ 14882: 27.5 Stream buffers
31//
32
33#ifndef _GLIBXX_STREAMBUF
34#define _GLIBXX_STREAMBUF 1
35
36#ifdef _GLIBCXX_SYSHDR
37#pragma GCC system_header
38#endif
39
40#include <bits/requires_hosted.h> // iostreams
41
42#include <bits/c++config.h>
43#include <bits/iosfwd.h>
44#include <bits/localefwd.h>
45#include <bits/ios_base.h>
46#include <bits/cpp_type_traits.h>
47#include <ext/type_traits.h>
48
49namespace std _GLIBCXX_VISIBILITY(default)
50{
51_GLIBCXX_BEGIN_NAMESPACE_VERSION
52
53#define _IsUnused __attribute__ ((__unused__))
54
55 template<typename _CharT, typename _Traits>
56 streamsize
57 __copy_streambufs_eof(basic_streambuf<_CharT, _Traits>*,
58 basic_streambuf<_CharT, _Traits>*, bool&);
59
60 /**
61 * @brief The actual work of input and output (interface).
62 * @ingroup io
63 *
64 * @tparam _CharT Type of character stream.
65 * @tparam _Traits Traits for character type, defaults to
66 * char_traits<_CharT>.
67 *
68 * This is a base class. Derived stream buffers each control a
69 * pair of character sequences: one for input, and one for output.
70 *
71 * Section [27.5.1] of the standard describes the requirements and
72 * behavior of stream buffer classes. That section (three paragraphs)
73 * is reproduced here, for simplicity and accuracy.
74 *
75 * -# Stream buffers can impose various constraints on the sequences
76 * they control. Some constraints are:
77 * - The controlled input sequence can be not readable.
78 * - The controlled output sequence can be not writable.
79 * - The controlled sequences can be associated with the contents of
80 * other representations for character sequences, such as external
81 * files.
82 * - The controlled sequences can support operations @e directly to or
83 * from associated sequences.
84 * - The controlled sequences can impose limitations on how the
85 * program can read characters from a sequence, write characters to
86 * a sequence, put characters back into an input sequence, or alter
87 * the stream position.
88 * .
89 * -# Each sequence is characterized by three pointers which, if non-null,
90 * all point into the same @c charT array object. The array object
91 * represents, at any moment, a (sub)sequence of characters from the
92 * sequence. Operations performed on a sequence alter the values
93 * stored in these pointers, perform reads and writes directly to or
94 * from associated sequences, and alter <em>the stream position</em> and
95 * conversion state as needed to maintain this subsequence relationship.
96 * The three pointers are:
97 * - the <em>beginning pointer</em>, or lowest element address in the
98 * array (called @e xbeg here);
99 * - the <em>next pointer</em>, or next element address that is a
100 * current candidate for reading or writing (called @e xnext here);
101 * - the <em>end pointer</em>, or first element address beyond the
102 * end of the array (called @e xend here).
103 * .
104 * -# The following semantic constraints shall always apply for any set
105 * of three pointers for a sequence, using the pointer names given
106 * immediately above:
107 * - If @e xnext is not a null pointer, then @e xbeg and @e xend shall
108 * also be non-null pointers into the same @c charT array, as
109 * described above; otherwise, @e xbeg and @e xend shall also be null.
110 * - If @e xnext is not a null pointer and @e xnext < @e xend for an
111 * output sequence, then a <em>write position</em> is available.
112 * In this case, @e *xnext shall be assignable as the next element
113 * to write (to put, or to store a character value, into the sequence).
114 * - If @e xnext is not a null pointer and @e xbeg < @e xnext for an
115 * input sequence, then a <em>putback position</em> is available.
116 * In this case, @e xnext[-1] shall have a defined value and is the
117 * next (preceding) element to store a character that is put back
118 * into the input sequence.
119 * - If @e xnext is not a null pointer and @e xnext< @e xend for an
120 * input sequence, then a <em>read position</em> is available.
121 * In this case, @e *xnext shall have a defined value and is the
122 * next element to read (to get, or to obtain a character value,
123 * from the sequence).
124 */
125 template<typename _CharT, typename _Traits>
126 class basic_streambuf
127 {
128 public:
129 ///@{
130 /**
131 * These are standard types. They permit a standardized way of
132 * referring to names of (or names dependent on) the template
133 * parameters, which are specific to the implementation.
134 */
135 typedef _CharT char_type;
136 typedef _Traits traits_type;
137 typedef typename traits_type::int_type int_type;
138 typedef typename traits_type::pos_type pos_type;
139 typedef typename traits_type::off_type off_type;
140 ///@}
141
142 ///@{
143 /// This is a non-standard type.
144 typedef basic_streambuf<char_type, traits_type> __streambuf_type;
145 ///@}
146
147 friend class basic_ios<char_type, traits_type>;
148 friend class basic_istream<char_type, traits_type>;
149 friend class basic_ostream<char_type, traits_type>;
150 friend class istreambuf_iterator<char_type, traits_type>;
151 friend class ostreambuf_iterator<char_type, traits_type>;
152
153 friend streamsize
154 __copy_streambufs_eof<>(basic_streambuf*, basic_streambuf*, bool&);
155
156 template<bool _IsMove, typename _CharT2>
157 friend typename __gnu_cxx::__enable_if<__is_char<_CharT2>::__value,
158 _CharT2*>::__type
159 __copy_move_a2(istreambuf_iterator<_CharT2>,
160 istreambuf_iterator<_CharT2>, _CharT2*);
161
162 template<typename _CharT2>
163 friend typename __gnu_cxx::__enable_if<__is_char<_CharT2>::__value,
164 istreambuf_iterator<_CharT2> >::__type
165 find(istreambuf_iterator<_CharT2>, istreambuf_iterator<_CharT2>,
166 const _CharT2&);
167
168 template<typename _CharT2, typename _Distance>
169 friend typename __gnu_cxx::__enable_if<__is_char<_CharT2>::__value,
170 void>::__type
171 advance(istreambuf_iterator<_CharT2>&, _Distance);
172
173 friend void __istream_extract(istream&, char*, streamsize);
174
175 template<typename _CharT2, typename _Traits2, typename _Alloc>
176 friend basic_istream<_CharT2, _Traits2>&
177 operator>>(basic_istream<_CharT2, _Traits2>&,
178 basic_string<_CharT2, _Traits2, _Alloc>&);
179
180 template<typename _CharT2, typename _Traits2, typename _Alloc>
181 friend basic_istream<_CharT2, _Traits2>&
182 getline(basic_istream<_CharT2, _Traits2>&,
183 basic_string<_CharT2, _Traits2, _Alloc>&, _CharT2);
184
185 protected:
186 /*
187 * This is based on _IO_FILE, just reordered to be more consistent,
188 * and is intended to be the most minimal abstraction for an
189 * internal buffer.
190 * - get == input == read
191 * - put == output == write
192 */
193 char_type* _M_in_beg; ///< Start of get area.
194 char_type* _M_in_cur; ///< Current read area.
195 char_type* _M_in_end; ///< End of get area.
196 char_type* _M_out_beg; ///< Start of put area.
197 char_type* _M_out_cur; ///< Current put area.
198 char_type* _M_out_end; ///< End of put area.
199
200 /// Current locale setting.
201 locale _M_buf_locale;
202
203 public:
204 /// Destructor deallocates no buffer space.
205 virtual
206 ~basic_streambuf()
207 { }
208
209 // [27.5.2.2.1] locales
210 /**
211 * @brief Entry point for imbue().
212 * @param __loc The new locale.
213 * @return The previous locale.
214 *
215 * Calls the derived imbue(__loc).
216 */
217 locale
218 pubimbue(const locale& __loc)
219 {
220 locale __tmp(this->getloc());
221 this->imbue(__loc);
222 _M_buf_locale = __loc;
223 return __tmp;
224 }
225
226 /**
227 * @brief Locale access.
228 * @return The current locale in effect.
229 *
230 * If pubimbue(loc) has been called, then the most recent @c loc
231 * is returned. Otherwise the global locale in effect at the time
232 * of construction is returned.
233 */
234 locale
235 getloc() const
236 { return _M_buf_locale; }
237
238 // [27.5.2.2.2] buffer management and positioning
239 ///@{
240 /**
241 * @brief Entry points for derived buffer functions.
242 *
243 * The public versions of @c pubfoo dispatch to the protected
244 * derived @c foo member functions, passing the arguments (if any)
245 * and returning the result unchanged.
246 */
247 basic_streambuf*
248 pubsetbuf(char_type* __s, streamsize __n)
249 { return this->setbuf(__s, __n); }
250
251 /**
252 * @brief Alters the stream position.
253 * @param __off Offset.
254 * @param __way Value for ios_base::seekdir.
255 * @param __mode Value for ios_base::openmode.
256 *
257 * Calls virtual seekoff function.
258 */
259 pos_type
260 pubseekoff(off_type __off, ios_base::seekdir __way,
261 ios_base::openmode __mode = ios_base::in | ios_base::out)
262 { return this->seekoff(__off, __way, __mode); }
263
264 /**
265 * @brief Alters the stream position.
266 * @param __sp Position
267 * @param __mode Value for ios_base::openmode.
268 *
269 * Calls virtual seekpos function.
270 */
271 pos_type
272 pubseekpos(pos_type __sp,
273 ios_base::openmode __mode = ios_base::in | ios_base::out)
274 { return this->seekpos(__sp, __mode); }
275
276 /**
277 * @brief Calls virtual sync function.
278 */
279 int
280 pubsync() { return this->sync(); }
281 ///@}
282
283 // [27.5.2.2.3] get area
284 /**
285 * @brief Looking ahead into the stream.
286 * @return The number of characters available.
287 *
288 * If a read position is available, returns the number of characters
289 * available for reading before the buffer must be refilled.
290 * Otherwise returns the derived @c showmanyc().
291 */
292 streamsize
293 in_avail()
294 {
295 const streamsize __ret = this->egptr() - this->gptr();
296 return __ret ? __ret : this->showmanyc();
297 }
298
299 /**
300 * @brief Getting the next character.
301 * @return The next character, or eof.
302 *
303 * Calls @c sbumpc(), and if that function returns
304 * @c traits::eof(), so does this function. Otherwise, @c sgetc().
305 */
306 int_type
307 snextc()
308 {
309 int_type __ret = traits_type::eof();
310 if (__builtin_expect(!traits_type::eq_int_type(this->sbumpc(),
311 __ret), true))
312 __ret = this->sgetc();
313 return __ret;
314 }
315
316 /**
317 * @brief Getting the next character.
318 * @return The next character, or eof.
319 *
320 * If the input read position is available, returns that character
321 * and increments the read pointer, otherwise calls and returns
322 * @c uflow().
323 */
324 int_type
325 sbumpc()
326 {
327 int_type __ret;
328 if (__builtin_expect(this->gptr() < this->egptr(), true))
329 {
330 __ret = traits_type::to_int_type(*this->gptr());
331 this->gbump(1);
332 }
333 else
334 __ret = this->uflow();
335 return __ret;
336 }
337
338 /**
339 * @brief Getting the next character.
340 * @return The next character, or eof.
341 *
342 * If the input read position is available, returns that character,
343 * otherwise calls and returns @c underflow(). Does not move the
344 * read position after fetching the character.
345 */
346 int_type
347 sgetc()
348 {
349 int_type __ret;
350 if (__builtin_expect(this->gptr() < this->egptr(), true))
351 __ret = traits_type::to_int_type(*this->gptr());
352 else
353 __ret = this->underflow();
354 return __ret;
355 }
356
357 /**
358 * @brief Entry point for xsgetn.
359 * @param __s A buffer area.
360 * @param __n A count.
361 *
362 * Returns xsgetn(__s,__n). The effect is to fill @a __s[0] through
363 * @a __s[__n-1] with characters from the input sequence, if possible.
364 */
365 streamsize
366 sgetn(char_type* __s, streamsize __n)
367 { return this->xsgetn(__s, __n); }
368
369 // [27.5.2.2.4] putback
370 /**
371 * @brief Pushing characters back into the input stream.
372 * @param __c The character to push back.
373 * @return The previous character, if possible.
374 *
375 * Similar to sungetc(), but @a __c is pushed onto the stream
376 * instead of <em>the previous character.</em> If successful,
377 * the next character fetched from the input stream will be @a
378 * __c.
379 */
380 int_type
381 sputbackc(char_type __c)
382 {
383 int_type __ret;
384 const bool __testpos = this->eback() < this->gptr();
385 if (__builtin_expect(!__testpos ||
386 !traits_type::eq(__c, this->gptr()[-1]), false))
387 __ret = this->pbackfail(traits_type::to_int_type(__c));
388 else
389 {
390 this->gbump(-1);
391 __ret = traits_type::to_int_type(*this->gptr());
392 }
393 return __ret;
394 }
395
396 /**
397 * @brief Moving backwards in the input stream.
398 * @return The previous character, if possible.
399 *
400 * If a putback position is available, this function decrements
401 * the input pointer and returns that character. Otherwise,
402 * calls and returns pbackfail(). The effect is to @a unget
403 * the last character @a gotten.
404 */
405 int_type
406 sungetc()
407 {
408 int_type __ret;
409 if (__builtin_expect(this->eback() < this->gptr(), true))
410 {
411 this->gbump(-1);
412 __ret = traits_type::to_int_type(*this->gptr());
413 }
414 else
415 __ret = this->pbackfail();
416 return __ret;
417 }
418
419 // [27.5.2.2.5] put area
420 /**
421 * @brief Entry point for all single-character output functions.
422 * @param __c A character to output.
423 * @return @a __c, if possible.
424 *
425 * One of two public output functions.
426 *
427 * If a write position is available for the output sequence (i.e.,
428 * the buffer is not full), stores @a __c in that position, increments
429 * the position, and returns @c traits::to_int_type(__c). If a write
430 * position is not available, returns @c overflow(__c).
431 */
432 int_type
433 sputc(char_type __c)
434 {
435 int_type __ret;
436 if (__builtin_expect(this->pptr() < this->epptr(), true))
437 {
438 *this->pptr() = __c;
439 this->pbump(1);
440 __ret = traits_type::to_int_type(__c);
441 }
442 else
443 __ret = this->overflow(traits_type::to_int_type(__c));
444 return __ret;
445 }
446
447 /**
448 * @brief Entry point for all single-character output functions.
449 * @param __s A buffer read area.
450 * @param __n A count.
451 *
452 * One of two public output functions.
453 *
454 *
455 * Returns xsputn(__s,__n). The effect is to write @a __s[0] through
456 * @a __s[__n-1] to the output sequence, if possible.
457 */
458 streamsize
459 sputn(const char_type* __s, streamsize __n)
460 { return this->xsputn(__s, __n); }
461
462 protected:
463 /**
464 * @brief Base constructor.
465 *
466 * Only called from derived constructors, and sets up all the
467 * buffer data to zero, including the pointers described in the
468 * basic_streambuf class description. Note that, as a result,
469 * - the class starts with no read nor write positions available,
470 * - this is not an error
471 */
472 basic_streambuf()
473 : _M_in_beg(0), _M_in_cur(0), _M_in_end(0),
474 _M_out_beg(0), _M_out_cur(0), _M_out_end(0),
475 _M_buf_locale(locale())
476 { }
477
478 // [27.5.2.3.1] get area access
479 ///@{
480 /**
481 * @brief Access to the get area.
482 *
483 * These functions are only available to other protected functions,
484 * including derived classes.
485 *
486 * - eback() returns the beginning pointer for the input sequence
487 * - gptr() returns the next pointer for the input sequence
488 * - egptr() returns the end pointer for the input sequence
489 */
490 char_type*
491 eback() const { return _M_in_beg; }
492
493 char_type*
494 gptr() const { return _M_in_cur; }
495
496 char_type*
497 egptr() const { return _M_in_end; }
498 ///@}
499
500 /**
501 * @brief Moving the read position.
502 * @param __n The delta by which to move.
503 *
504 * This just advances the read position without returning any data.
505 */
506 void
507 gbump(int __n) { _M_in_cur += __n; }
508
509 /**
510 * @brief Setting the three read area pointers.
511 * @param __gbeg A pointer.
512 * @param __gnext A pointer.
513 * @param __gend A pointer.
514 * @post @a __gbeg == @c eback(), @a __gnext == @c gptr(), and
515 * @a __gend == @c egptr()
516 */
517 void
518 setg(char_type* __gbeg, char_type* __gnext, char_type* __gend)
519 {
520 _M_in_beg = __gbeg;
521 _M_in_cur = __gnext;
522 _M_in_end = __gend;
523 }
524
525 // [27.5.2.3.2] put area access
526 ///@{
527 /**
528 * @brief Access to the put area.
529 *
530 * These functions are only available to other protected functions,
531 * including derived classes.
532 *
533 * - pbase() returns the beginning pointer for the output sequence
534 * - pptr() returns the next pointer for the output sequence
535 * - epptr() returns the end pointer for the output sequence
536 */
537 char_type*
538 pbase() const { return _M_out_beg; }
539
540 char_type*
541 pptr() const { return _M_out_cur; }
542
543 char_type*
544 epptr() const { return _M_out_end; }
545 ///@}
546
547 /**
548 * @brief Moving the write position.
549 * @param __n The delta by which to move.
550 *
551 * This just advances the write position without returning any data.
552 */
553 void
554 pbump(int __n) { _M_out_cur += __n; }
555
556 /**
557 * @brief Setting the three write area pointers.
558 * @param __pbeg A pointer.
559 * @param __pend A pointer.
560 * @post @a __pbeg == @c pbase(), @a __pbeg == @c pptr(), and
561 * @a __pend == @c epptr()
562 */
563 void
564 setp(char_type* __pbeg, char_type* __pend)
565 {
566 _M_out_beg = _M_out_cur = __pbeg;
567 _M_out_end = __pend;
568 }
569
570 // [27.5.2.4] virtual functions
571 // [27.5.2.4.1] locales
572 /**
573 * @brief Changes translations.
574 * @param __loc A new locale.
575 *
576 * Translations done during I/O which depend on the current
577 * locale are changed by this call. The standard adds,
578 * <em>Between invocations of this function a class derived
579 * from streambuf can safely cache results of calls to locale
580 * functions and to members of facets so obtained.</em>
581 *
582 * @note Base class version does nothing.
583 */
584 virtual void
585 imbue(const locale& __loc _IsUnused)
586 { }
587
588 // [27.5.2.4.2] buffer management and positioning
589 /**
590 * @brief Manipulates the buffer.
591 *
592 * Each derived class provides its own appropriate behavior. See
593 * the next-to-last paragraph of
594 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/streambufs.html#io.streambuf.buffering
595 * for more on this function.
596 *
597 * @note Base class version does nothing, returns @c this.
598 */
599 virtual basic_streambuf<char_type,_Traits>*
600 setbuf(char_type*, streamsize)
601 { return this; }
602
603 /**
604 * @brief Alters the stream positions.
605 *
606 * Each derived class provides its own appropriate behavior.
607 * @note Base class version does nothing, returns a @c pos_type
608 * that represents an invalid stream position.
609 */
610 virtual pos_type
611 seekoff(off_type, ios_base::seekdir,
612 ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
613 { return pos_type(off_type(-1)); }
614
615 /**
616 * @brief Alters the stream positions.
617 *
618 * Each derived class provides its own appropriate behavior.
619 * @note Base class version does nothing, returns a @c pos_type
620 * that represents an invalid stream position.
621 */
622 virtual pos_type
623 seekpos(pos_type,
624 ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
625 { return pos_type(off_type(-1)); }
626
627 /**
628 * @brief Synchronizes the buffer arrays with the controlled sequences.
629 * @return -1 on failure.
630 *
631 * Each derived class provides its own appropriate behavior,
632 * including the definition of @a failure.
633 * @note Base class version does nothing, returns zero.
634 */
635 virtual int
636 sync() { return 0; }
637
638 // [27.5.2.4.3] get area
639 /**
640 * @brief Investigating the data available.
641 * @return An estimate of the number of characters available in the
642 * input sequence, or -1.
643 *
644 * <em>If it returns a positive value, then successive calls to
645 * @c underflow() will not return @c traits::eof() until at
646 * least that number of characters have been supplied. If @c
647 * showmanyc() returns -1, then calls to @c underflow() or @c
648 * uflow() will fail.</em> [27.5.2.4.3]/1
649 *
650 * @note Base class version does nothing, returns zero.
651 * @note The standard adds that <em>the intention is not only that the
652 * calls [to underflow or uflow] will not return @c eof() but
653 * that they will return immediately.</em>
654 * @note The standard adds that <em>the morphemes of @c showmanyc are
655 * @b es-how-many-see, not @b show-manic.</em>
656 */
657 virtual streamsize
658 showmanyc() { return 0; }
659
660 /**
661 * @brief Multiple character extraction.
662 * @param __s A buffer area.
663 * @param __n Maximum number of characters to assign.
664 * @return The number of characters assigned.
665 *
666 * Fills @a __s[0] through @a __s[__n-1] with characters from the input
667 * sequence, as if by @c sbumpc(). Stops when either @a __n characters
668 * have been copied, or when @c traits::eof() would be copied.
669 *
670 * It is expected that derived classes provide a more efficient
671 * implementation by overriding this definition.
672 */
673 virtual streamsize
674 xsgetn(char_type* __s, streamsize __n);
675
676 /**
677 * @brief Fetches more data from the controlled sequence.
678 * @return The first character from the <em>pending sequence</em>.
679 *
680 * Informally, this function is called when the input buffer is
681 * exhausted (or does not exist, as buffering need not actually be
682 * done). If a buffer exists, it is @a refilled. In either case, the
683 * next available character is returned, or @c traits::eof() to
684 * indicate a null pending sequence.
685 *
686 * For a formal definition of the pending sequence, see a good text
687 * such as Langer & Kreft, or [27.5.2.4.3]/7-14.
688 *
689 * A functioning input streambuf can be created by overriding only
690 * this function (no buffer area will be used). For an example, see
691 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/streambufs.html
692 *
693 * @note Base class version does nothing, returns eof().
694 */
695 virtual int_type
696 underflow()
697 { return traits_type::eof(); }
698
699 /**
700 * @brief Fetches more data from the controlled sequence.
701 * @return The first character from the <em>pending sequence</em>.
702 *
703 * Informally, this function does the same thing as @c underflow(),
704 * and in fact is required to call that function. It also returns
705 * the new character, like @c underflow() does. However, this
706 * function also moves the read position forward by one.
707 */
708 virtual int_type
709 uflow()
710 {
711 int_type __ret = traits_type::eof();
712 const bool __testeof = traits_type::eq_int_type(this->underflow(),
713 __ret);
714 if (!__testeof)
715 {
716 __ret = traits_type::to_int_type(*this->gptr());
717 this->gbump(1);
718 }
719 return __ret;
720 }
721
722 // [27.5.2.4.4] putback
723 /**
724 * @brief Tries to back up the input sequence.
725 * @param __c The character to be inserted back into the sequence.
726 * @return eof() on failure, <em>some other value</em> on success
727 * @post The constraints of @c gptr(), @c eback(), and @c pptr()
728 * are the same as for @c underflow().
729 *
730 * @note Base class version does nothing, returns eof().
731 */
732 virtual int_type
733 pbackfail(int_type __c _IsUnused = traits_type::eof())
734 { return traits_type::eof(); }
735
736 // Put area:
737 /**
738 * @brief Multiple character insertion.
739 * @param __s A buffer area.
740 * @param __n Maximum number of characters to write.
741 * @return The number of characters written.
742 *
743 * Writes @a __s[0] through @a __s[__n-1] to the output sequence, as if
744 * by @c sputc(). Stops when either @a n characters have been
745 * copied, or when @c sputc() would return @c traits::eof().
746 *
747 * It is expected that derived classes provide a more efficient
748 * implementation by overriding this definition.
749 */
750 virtual streamsize
751 xsputn(const char_type* __s, streamsize __n);
752
753 /**
754 * @brief Consumes data from the buffer; writes to the
755 * controlled sequence.
756 * @param __c An additional character to consume.
757 * @return eof() to indicate failure, something else (usually
758 * @a __c, or not_eof())
759 *
760 * Informally, this function is called when the output buffer
761 * is full (or does not exist, as buffering need not actually
762 * be done). If a buffer exists, it is @a consumed, with
763 * <em>some effect</em> on the controlled sequence.
764 * (Typically, the buffer is written out to the sequence
765 * verbatim.) In either case, the character @a c is also
766 * written out, if @a __c is not @c eof().
767 *
768 * For a formal definition of this function, see a good text
769 * such as Langer & Kreft, or [27.5.2.4.5]/3-7.
770 *
771 * A functioning output streambuf can be created by overriding only
772 * this function (no buffer area will be used).
773 *
774 * @note Base class version does nothing, returns eof().
775 */
776 virtual int_type
777 overflow(int_type __c _IsUnused = traits_type::eof())
778 { return traits_type::eof(); }
779
780#if _GLIBCXX_USE_DEPRECATED && __cplusplus <= 201402L
781 // Annex D.6 (removed in C++17)
782 public:
783 /**
784 * @brief Tosses a character.
785 *
786 * Advances the read pointer, ignoring the character that would have
787 * been read.
788 *
789 * See http://gcc.gnu.org/ml/libstdc++/2002-05/msg00168.html
790 */
791 _GLIBCXX_DEPRECATED_SUGGEST("std::basic_streambuf::sbumpc")
792 void
793 stossc()
794 {
795 if (this->gptr() < this->egptr())
796 this->gbump(1);
797 else
798 this->uflow();
799 }
800#endif
801
802 // Also used by specializations for char and wchar_t in src.
803 void
804 __safe_gbump(streamsize __n) { _M_in_cur += __n; }
805
806 void
807 __safe_pbump(streamsize __n) { _M_out_cur += __n; }
808
809#if __cplusplus < 201103L
810 private:
811#else
812 protected:
813#endif
814 basic_streambuf(const basic_streambuf&);
815
816 basic_streambuf&
817 operator=(const basic_streambuf&);
818
819#if __cplusplus >= 201103L
820 void
821 swap(basic_streambuf& __sb)
822 {
823 std::swap(_M_in_beg, __sb._M_in_beg);
824 std::swap(_M_in_cur, __sb._M_in_cur);
825 std::swap(_M_in_end, __sb._M_in_end);
826 std::swap(_M_out_beg, __sb._M_out_beg);
827 std::swap(_M_out_cur, __sb._M_out_cur);
828 std::swap(_M_out_end, __sb._M_out_end);
829 std::swap(_M_buf_locale, __sb._M_buf_locale);
830 }
831#endif
832 };
833
834#if __cplusplus >= 201103L
835 template<typename _CharT, typename _Traits>
836 std::basic_streambuf<_CharT, _Traits>::
837 basic_streambuf(const basic_streambuf&) = default;
838
839 template<typename _CharT, typename _Traits>
840 std::basic_streambuf<_CharT, _Traits>&
841 std::basic_streambuf<_CharT, _Traits>::
842 operator=(const basic_streambuf&) = default;
843#endif
844
845 // Explicit specialization declarations, defined in src/streambuf.cc.
846 template<>
847 streamsize
848 __copy_streambufs_eof(basic_streambuf<char>* __sbin,
849 basic_streambuf<char>* __sbout, bool& __ineof);
850#ifdef _GLIBCXX_USE_WCHAR_T
851 template<>
852 streamsize
853 __copy_streambufs_eof(basic_streambuf<wchar_t>* __sbin,
854 basic_streambuf<wchar_t>* __sbout, bool& __ineof);
855#endif
856
857#undef _IsUnused
858
859_GLIBCXX_END_NAMESPACE_VERSION
860} // namespace
861
862#include <bits/streambuf.tcc>
863
864#endif /* _GLIBCXX_STREAMBUF */
cpp_type_traits.h
ios_base.h
localefwd.h
requires_hosted.h
streambuf.tcc
c++config.h
type_traits.h
std::istream
basic_istream< char > istream
Base class for char input streams.
Definition iosfwd.h:81
std
ISO C++ entities toplevel namespace is std.
std::streamsize
ptrdiff_t streamsize
Integral type for I/O operation counts and buffer sizes.
Definition postypes.h:73
std::basic_istream
Template class basic_istream.
Definition istream:73
std::basic_streambuf
The actual work of input and output (interface).
Definition streambuf:127
std::basic_streambuf::seekpos
virtual pos_type seekpos(pos_type, ios_base::openmode=ios_base::in|ios_base::out)
Alters the stream positions.
Definition streambuf:623
std::basic_streambuf< char_type, traits_type >::_M_in_beg
char_type * _M_in_beg
Definition streambuf:193
std::basic_streambuf::getloc
locale getloc() const
Locale access.
Definition streambuf:235
std::basic_streambuf< char_type, traits_type >::int_type
traits_type::int_type int_type
Definition streambuf:137
std::basic_streambuf::epptr
char_type * epptr() const
Access to the put area.
Definition streambuf:544
std::basic_streambuf< char_type, traits_type >::__streambuf_type
basic_streambuf< char_type, traits_type > __streambuf_type
Definition streambuf:144
std::basic_streambuf::overflow
virtual int_type overflow(int_type __c=traits_type::eof())
Consumes data from the buffer; writes to the controlled sequence.
Definition streambuf:777
std::basic_streambuf::xsputn
virtual streamsize xsputn(const char_type *__s, streamsize __n)
Multiple character insertion.
Definition streambuf.tcc:85
std::basic_streambuf::pubseekpos
pos_type pubseekpos(pos_type __sp, ios_base::openmode __mode=ios_base::in|ios_base::out)
Alters the stream position.
Definition streambuf:272
std::basic_streambuf::pptr
char_type * pptr() const
Access to the put area.
Definition streambuf:541
std::basic_streambuf< char_type, traits_type >::char_type
char_type char_type
Definition streambuf:135
std::basic_streambuf::setg
void setg(char_type *__gbeg, char_type *__gnext, char_type *__gend)
Setting the three read area pointers.
Definition streambuf:518
std::basic_streambuf::eback
char_type * eback() const
Access to the get area.
Definition streambuf:491
std::basic_streambuf::sync
virtual int sync()
Synchronizes the buffer arrays with the controlled sequences.
Definition streambuf:636
std::basic_streambuf::uflow
virtual int_type uflow()
Fetches more data from the controlled sequence.
Definition streambuf:709
std::basic_streambuf::egptr
char_type * egptr() const
Access to the get area.
Definition streambuf:497
std::basic_streambuf::gptr
char_type * gptr() const
Access to the get area.
Definition streambuf:494
std::basic_streambuf< char_type, traits_type >::pos_type
traits_type::pos_type pos_type
Definition streambuf:138
std::basic_streambuf::sputn
streamsize sputn(const char_type *__s, streamsize __n)
Entry point for all single-character output functions.
Definition streambuf:459
std::basic_streambuf::xsgetn
virtual streamsize xsgetn(char_type *__s, streamsize __n)
Multiple character extraction.
Definition streambuf.tcc:51
std::basic_streambuf< char_type, traits_type >::_M_out_beg
char_type * _M_out_beg
Definition streambuf:196
std::basic_streambuf::snextc
int_type snextc()
Getting the next character.
Definition streambuf:307
std::basic_streambuf::imbue
virtual void imbue(const locale &__loc)
Changes translations.
Definition streambuf:585
std::basic_streambuf::sbumpc
int_type sbumpc()
Getting the next character.
Definition streambuf:325
std::basic_streambuf< char_type, traits_type >::_M_in_cur
char_type * _M_in_cur
Definition streambuf:194
std::basic_streambuf::sgetn
streamsize sgetn(char_type *__s, streamsize __n)
Entry point for xsgetn.
Definition streambuf:366
std::basic_streambuf::pubsetbuf
basic_streambuf * pubsetbuf(char_type *__s, streamsize __n)
Entry points for derived buffer functions.
Definition streambuf:248
std::basic_streambuf::setbuf
virtual basic_streambuf< char_type, _Traits > * setbuf(char_type *, streamsize)
Manipulates the buffer.
Definition streambuf:600
std::basic_streambuf< char_type, traits_type >::_M_out_cur
char_type * _M_out_cur
Definition streambuf:197
std::basic_streambuf::showmanyc
virtual streamsize showmanyc()
Investigating the data available.
Definition streambuf:658
std::basic_streambuf::sungetc
int_type sungetc()
Moving backwards in the input stream.
Definition streambuf:406
std::basic_streambuf::pbackfail
virtual int_type pbackfail(int_type __c=traits_type::eof())
Tries to back up the input sequence.
Definition streambuf:733
std::basic_streambuf::pubimbue
locale pubimbue(const locale &__loc)
Entry point for imbue().
Definition streambuf:218
std::basic_streambuf::in_avail
streamsize in_avail()
Looking ahead into the stream.
Definition streambuf:293
std::basic_streambuf::gbump
void gbump(int __n)
Moving the read position.
Definition streambuf:507
std::basic_streambuf::underflow
virtual int_type underflow()
Fetches more data from the controlled sequence.
Definition streambuf:696
std::basic_streambuf::setp
void setp(char_type *__pbeg, char_type *__pend)
Setting the three write area pointers.
Definition streambuf:564
std::basic_streambuf< char_type, traits_type >::traits_type
traits_type traits_type
Definition streambuf:136
std::basic_streambuf::pubseekoff
pos_type pubseekoff(off_type __off, ios_base::seekdir __way, ios_base::openmode __mode=ios_base::in|ios_base::out)
Alters the stream position.
Definition streambuf:260
std::basic_streambuf::pbump
void pbump(int __n)
Moving the write position.
Definition streambuf:554
std::basic_streambuf::sgetc
int_type sgetc()
Getting the next character.
Definition streambuf:347
std::basic_streambuf::pubsync
int pubsync()
Calls virtual sync function.
Definition streambuf:280
std::basic_streambuf::seekoff
virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode=ios_base::in|ios_base::out)
Alters the stream positions.
Definition streambuf:611
std::basic_streambuf::pbase
char_type * pbase() const
Access to the put area.
Definition streambuf:538
std::basic_streambuf< char_type, traits_type >::_M_in_end
char_type * _M_in_end
Definition streambuf:195
std::basic_streambuf::~basic_streambuf
virtual ~basic_streambuf()
Destructor deallocates no buffer space.
Definition streambuf:206
std::basic_streambuf< char_type, traits_type >::off_type
traits_type::off_type off_type
Definition streambuf:139
std::basic_streambuf::sputbackc
int_type sputbackc(char_type __c)
Pushing characters back into the input stream.
Definition streambuf:381
std::basic_streambuf< char_type, traits_type >::_M_buf_locale
locale _M_buf_locale
Definition streambuf:201
std::basic_streambuf< char_type, traits_type >::_M_out_end
char_type * _M_out_end
Definition streambuf:198
std::basic_streambuf::sputc
int_type sputc(char_type __c)
Entry point for all single-character output functions.
Definition streambuf:433
std::basic_streambuf::basic_streambuf
basic_streambuf()
Base constructor.
Definition streambuf:472
std::basic_ios
Template class basic_ios, virtual base class for all stream classes.
Definition basic_ios.h:71
std::basic_string
Managing sequences of characters and character-like objects.
Definition basic_string.h:94
std::pos_type
std::ios_base::in
static const openmode in
Open for input. Default for ifstream and fstream.
Definition ios_base.h:498
std::ios_base::out
static const openmode out
Open for output. Default for ofstream and fstream.
Definition ios_base.h:501
std::ios_base::openmode
_Ios_Openmode openmode
This is a bitmask type.
Definition ios_base.h:484
std::ios_base::seekdir
_Ios_Seekdir seekdir
This is an enumerated type.
Definition ios_base.h:523
std::basic_ostream
Template class basic_ostream.
Definition ostream.h:72
std::istreambuf_iterator
Provides input iterator semantics for streambufs.
Definition streambuf_iterator.h:59
std::ostreambuf_iterator
Provides output iterator semantics for streambufs.
Definition streambuf_iterator.h:249
std::locale
Container class for localization functionality.
Definition locale_classes.h:70