1 // Iostreams base classes -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
4 // 2006, 2007, 2008, 2009
5 // Free Software Foundation, Inc.
7 // This file is part of the GNU ISO C++ Library. This library is free
8 // software; you can redistribute it and/or modify it under the
9 // terms of the GNU General Public License as published by the
10 // Free Software Foundation; either version 3, or (at your option)
13 // This library is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // Under Section 7 of GPL version 3, you are granted additional
19 // permissions described in the GCC Runtime Library Exception, version
20 // 3.1, as published by the Free Software Foundation.
22 // You should have received a copy of the GNU General Public License and
23 // a copy of the GCC Runtime Library Exception along with this program;
24 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
25 // <http://www.gnu.org/licenses/>.
28 * This is an internal header file, included by other library headers.
29 * You should not attempt to use it directly.
33 // ISO C++ 14882: 27.4 Iostreams base classes
39 #pragma GCC system_header
41 #include <ext/atomicity.h>
42 #include <bits/localefwd.h>
43 #include <bits/locale_classes.h>
45 #ifndef _GLIBCXX_STDIO_MACROS
46 # include <cstdio> // For SEEK_CUR, SEEK_END
47 # define _IOS_BASE_SEEK_CUR SEEK_CUR
48 # define _IOS_BASE_SEEK_END SEEK_END
50 # define _IOS_BASE_SEEK_CUR 1
51 # define _IOS_BASE_SEEK_END 2
54 _GLIBCXX_BEGIN_NAMESPACE(std)
56 // The following definitions of bitmask types are enums, not ints,
57 // as permitted (but not required) in the standard, in order to provide
58 // better type safety in iostream calls. A side effect is that
59 // expressions involving them are no longer compile-time constants.
62 _S_boolalpha = 1L << 0,
66 _S_internal = 1L << 4,
70 _S_scientific = 1L << 8,
71 _S_showbase = 1L << 9,
72 _S_showpoint = 1L << 10,
73 _S_showpos = 1L << 11,
75 _S_unitbuf = 1L << 13,
76 _S_uppercase = 1L << 14,
77 _S_adjustfield = _S_left | _S_right | _S_internal,
78 _S_basefield = _S_dec | _S_oct | _S_hex,
79 _S_floatfield = _S_scientific | _S_fixed,
80 _S_ios_fmtflags_end = 1L << 16
84 operator&(_Ios_Fmtflags __a, _Ios_Fmtflags __b)
85 { return _Ios_Fmtflags(static_cast<int>(__a) & static_cast<int>(__b)); }
88 operator|(_Ios_Fmtflags __a, _Ios_Fmtflags __b)
89 { return _Ios_Fmtflags(static_cast<int>(__a) | static_cast<int>(__b)); }
92 operator^(_Ios_Fmtflags __a, _Ios_Fmtflags __b)
93 { return _Ios_Fmtflags(static_cast<int>(__a) ^ static_cast<int>(__b)); }
96 operator|=(_Ios_Fmtflags& __a, _Ios_Fmtflags __b)
97 { return __a = __a | __b; }
100 operator&=(_Ios_Fmtflags& __a, _Ios_Fmtflags __b)
101 { return __a = __a & __b; }
103 inline _Ios_Fmtflags&
104 operator^=(_Ios_Fmtflags& __a, _Ios_Fmtflags __b)
105 { return __a = __a ^ __b; }
108 operator~(_Ios_Fmtflags __a)
109 { return _Ios_Fmtflags(~static_cast<int>(__a)); }
120 _S_ios_openmode_end = 1L << 16
124 operator&(_Ios_Openmode __a, _Ios_Openmode __b)
125 { return _Ios_Openmode(static_cast<int>(__a) & static_cast<int>(__b)); }
128 operator|(_Ios_Openmode __a, _Ios_Openmode __b)
129 { return _Ios_Openmode(static_cast<int>(__a) | static_cast<int>(__b)); }
132 operator^(_Ios_Openmode __a, _Ios_Openmode __b)
133 { return _Ios_Openmode(static_cast<int>(__a) ^ static_cast<int>(__b)); }
135 inline _Ios_Openmode&
136 operator|=(_Ios_Openmode& __a, _Ios_Openmode __b)
137 { return __a = __a | __b; }
139 inline _Ios_Openmode&
140 operator&=(_Ios_Openmode& __a, _Ios_Openmode __b)
141 { return __a = __a & __b; }
143 inline _Ios_Openmode&
144 operator^=(_Ios_Openmode& __a, _Ios_Openmode __b)
145 { return __a = __a ^ __b; }
148 operator~(_Ios_Openmode __a)
149 { return _Ios_Openmode(~static_cast<int>(__a)); }
157 _S_failbit = 1L << 2,
158 _S_ios_iostate_end = 1L << 16
162 operator&(_Ios_Iostate __a, _Ios_Iostate __b)
163 { return _Ios_Iostate(static_cast<int>(__a) & static_cast<int>(__b)); }
166 operator|(_Ios_Iostate __a, _Ios_Iostate __b)
167 { return _Ios_Iostate(static_cast<int>(__a) | static_cast<int>(__b)); }
170 operator^(_Ios_Iostate __a, _Ios_Iostate __b)
171 { return _Ios_Iostate(static_cast<int>(__a) ^ static_cast<int>(__b)); }
174 operator|=(_Ios_Iostate& __a, _Ios_Iostate __b)
175 { return __a = __a | __b; }
178 operator&=(_Ios_Iostate& __a, _Ios_Iostate __b)
179 { return __a = __a & __b; }
182 operator^=(_Ios_Iostate& __a, _Ios_Iostate __b)
183 { return __a = __a ^ __b; }
186 operator~(_Ios_Iostate __a)
187 { return _Ios_Iostate(~static_cast<int>(__a)); }
192 _S_cur = _IOS_BASE_SEEK_CUR,
193 _S_end = _IOS_BASE_SEEK_END,
194 _S_ios_seekdir_end = 1L << 16
197 // 27.4.2 Class ios_base
199 * @brief The base of the I/O class hierarchy.
202 * This class defines everything that can be defined about I/O that does
203 * not depend on the type of characters being input or output. Most
204 * people will only see @c ios_base when they need to specify the full
205 * name of the various I/O flags (e.g., the openmodes).
212 * @brief These are thrown to indicate problems with io.
213 * @ingroup exceptions
215 * 27.4.2.1.1 Class ios_base::failure
217 class failure : public exception
220 // _GLIBCXX_RESOLVE_LIB_DEFECTS
221 // 48. Use of non-existent exception constructor
223 failure(const string& __str) throw();
225 // This declaration is not useless:
226 // http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Vague-Linkage.html
231 what() const throw();
237 // 27.4.2.1.2 Type ios_base::fmtflags
239 * @brief This is a bitmask type.
241 * @c "_Ios_Fmtflags" is implementation-defined, but it is valid to
242 * perform bitwise operations on these values and expect the Right
243 * Thing to happen. Defined objects of type fmtflags are:
263 typedef _Ios_Fmtflags fmtflags;
265 /// Insert/extract @c bool in alphabetic rather than numeric format.
266 static const fmtflags boolalpha = _S_boolalpha;
268 /// Converts integer input or generates integer output in decimal base.
269 static const fmtflags dec = _S_dec;
271 /// Generate floating-point output in fixed-point notation.
272 static const fmtflags fixed = _S_fixed;
274 /// Converts integer input or generates integer output in hexadecimal base.
275 static const fmtflags hex = _S_hex;
277 /// Adds fill characters at a designated internal point in certain
278 /// generated output, or identical to @c right if no such point is
280 static const fmtflags internal = _S_internal;
282 /// Adds fill characters on the right (final positions) of certain
283 /// generated output. (I.e., the thing you print is flush left.)
284 static const fmtflags left = _S_left;
286 /// Converts integer input or generates integer output in octal base.
287 static const fmtflags oct = _S_oct;
289 /// Adds fill characters on the left (initial positions) of certain
290 /// generated output. (I.e., the thing you print is flush right.)
291 static const fmtflags right = _S_right;
293 /// Generates floating-point output in scientific notation.
294 static const fmtflags scientific = _S_scientific;
296 /// Generates a prefix indicating the numeric base of generated integer
298 static const fmtflags showbase = _S_showbase;
300 /// Generates a decimal-point character unconditionally in generated
301 /// floating-point output.
302 static const fmtflags showpoint = _S_showpoint;
304 /// Generates a + sign in non-negative generated numeric output.
305 static const fmtflags showpos = _S_showpos;
307 /// Skips leading white space before certain input operations.
308 static const fmtflags skipws = _S_skipws;
310 /// Flushes output after each output operation.
311 static const fmtflags unitbuf = _S_unitbuf;
313 /// Replaces certain lowercase letters with their uppercase equivalents
314 /// in generated output.
315 static const fmtflags uppercase = _S_uppercase;
317 /// A mask of left|right|internal. Useful for the 2-arg form of @c setf.
318 static const fmtflags adjustfield = _S_adjustfield;
320 /// A mask of dec|oct|hex. Useful for the 2-arg form of @c setf.
321 static const fmtflags basefield = _S_basefield;
323 /// A mask of scientific|fixed. Useful for the 2-arg form of @c setf.
324 static const fmtflags floatfield = _S_floatfield;
326 // 27.4.2.1.3 Type ios_base::iostate
328 * @brief This is a bitmask type.
330 * @c "_Ios_Iostate" is implementation-defined, but it is valid to
331 * perform bitwise operations on these values and expect the Right
332 * Thing to happen. Defined objects of type iostate are:
338 typedef _Ios_Iostate iostate;
340 /// Indicates a loss of integrity in an input or output sequence (such
341 /// as an irrecoverable read error from a file).
342 static const iostate badbit = _S_badbit;
344 /// Indicates that an input operation reached the end of an input sequence.
345 static const iostate eofbit = _S_eofbit;
347 /// Indicates that an input operation failed to read the expected
348 /// characters, or that an output operation failed to generate the
349 /// desired characters.
350 static const iostate failbit = _S_failbit;
352 /// Indicates all is well.
353 static const iostate goodbit = _S_goodbit;
355 // 27.4.2.1.4 Type ios_base::openmode
357 * @brief This is a bitmask type.
359 * @c "_Ios_Openmode" is implementation-defined, but it is valid to
360 * perform bitwise operations on these values and expect the Right
361 * Thing to happen. Defined objects of type openmode are:
369 typedef _Ios_Openmode openmode;
371 /// Seek to end before each write.
372 static const openmode app = _S_app;
374 /// Open and seek to end immediately after opening.
375 static const openmode ate = _S_ate;
377 /// Perform input and output in binary mode (as opposed to text mode).
378 /// This is probably not what you think it is; see
379 /// http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch27s02.html
380 static const openmode binary = _S_bin;
382 /// Open for input. Default for @c ifstream and fstream.
383 static const openmode in = _S_in;
385 /// Open for output. Default for @c ofstream and fstream.
386 static const openmode out = _S_out;
388 /// Open for input. Default for @c ofstream.
389 static const openmode trunc = _S_trunc;
391 // 27.4.2.1.5 Type ios_base::seekdir
393 * @brief This is an enumerated type.
395 * @c "_Ios_Seekdir" is implementation-defined. Defined values
396 * of type seekdir are:
398 * - cur, equivalent to @c SEEK_CUR in the C standard library.
399 * - end, equivalent to @c SEEK_END in the C standard library.
401 typedef _Ios_Seekdir seekdir;
403 /// Request a seek relative to the beginning of the stream.
404 static const seekdir beg = _S_beg;
406 /// Request a seek relative to the current position within the sequence.
407 static const seekdir cur = _S_cur;
409 /// Request a seek relative to the current end of the sequence.
410 static const seekdir end = _S_end;
413 typedef int io_state;
414 typedef int open_mode;
415 typedef int seek_dir;
417 typedef std::streampos streampos;
418 typedef std::streamoff streamoff;
422 * @brief The set of events that may be passed to an event callback.
424 * erase_event is used during ~ios() and copyfmt(). imbue_event is used
425 * during imbue(). copyfmt_event is used during copyfmt().
435 * @brief The type of an event callback function.
436 * @param event One of the members of the event enum.
437 * @param ios_base Reference to the ios_base object.
438 * @param int The integer provided when the callback was registered.
440 * Event callbacks are user defined functions that get called during
441 * several ios_base and basic_ios functions, specifically imbue(),
442 * copyfmt(), and ~ios().
444 typedef void (*event_callback) (event, ios_base&, int);
447 * @brief Add the callback __fn with parameter __index.
448 * @param __fn The function to add.
449 * @param __index The integer to pass to the function when invoked.
451 * Registers a function as an event callback with an integer parameter to
452 * be passed to the function when invoked. Multiple copies of the
453 * function are allowed. If there are multiple callbacks, they are
454 * invoked in the order they were registered.
457 register_callback(event_callback __fn, int __index);
462 * ios_base data members (doc me)
464 streamsize _M_precision;
467 iostate _M_exception;
468 iostate _M_streambuf_state;
471 // 27.4.2.6 Members for callbacks
472 // 27.4.2.6 ios_base callbacks
473 struct _Callback_list
476 _Callback_list* _M_next;
477 ios_base::event_callback _M_fn;
479 _Atomic_word _M_refcount; // 0 means one reference.
481 _Callback_list(ios_base::event_callback __fn, int __index,
482 _Callback_list* __cb)
483 : _M_next(__cb), _M_fn(__fn), _M_index(__index), _M_refcount(0) { }
486 _M_add_reference() { __gnu_cxx::__atomic_add_dispatch(&_M_refcount, 1); }
488 // 0 => OK to delete.
490 _M_remove_reference()
491 { return __gnu_cxx::__exchange_and_add_dispatch(&_M_refcount, -1); }
494 _Callback_list* _M_callbacks;
497 _M_call_callbacks(event __ev) throw();
500 _M_dispose_callbacks(void);
502 // 27.4.2.5 Members for iword/pword storage
507 _Words() : _M_pword(0), _M_iword(0) { }
510 // Only for failed iword/pword calls.
513 // Guaranteed storage.
514 // The first 5 iword and pword slots are reserved for internal use.
515 enum { _S_local_word_size = 8 };
516 _Words _M_local_word[_S_local_word_size];
518 // Allocated storage.
523 _M_grow_words(int __index, bool __iword);
525 // Members for locale and locale caching.
526 locale _M_ios_locale;
533 // 27.4.2.1.6 Class ios_base::Init
534 // Used to initialize standard streams. In theory, g++ could use
535 // -finit-priority to order this stuff correctly without going
536 // through these machinations.
539 friend class ios_base;
545 static _Atomic_word _S_refcount;
546 static bool _S_synced_with_stdio;
549 // [27.4.2.2] fmtflags state functions
551 * @brief Access to format flags.
552 * @return The format control flags for both input and output.
559 * @brief Setting new format flags all at once.
560 * @param fmtfl The new flags to set.
561 * @return The previous format control flags.
563 * This function overwrites all the format flags with @a fmtfl.
566 flags(fmtflags __fmtfl)
568 fmtflags __old = _M_flags;
574 * @brief Setting new format flags.
575 * @param fmtfl Additional flags to set.
576 * @return The previous format control flags.
578 * This function sets additional flags in format control. Flags that
579 * were previously set remain set.
582 setf(fmtflags __fmtfl)
584 fmtflags __old = _M_flags;
590 * @brief Setting new format flags.
591 * @param fmtfl Additional flags to set.
592 * @param mask The flags mask for @a fmtfl.
593 * @return The previous format control flags.
595 * This function clears @a mask in the format flags, then sets
596 * @a fmtfl @c & @a mask. An example mask is @c ios_base::adjustfield.
599 setf(fmtflags __fmtfl, fmtflags __mask)
601 fmtflags __old = _M_flags;
603 _M_flags |= (__fmtfl & __mask);
608 * @brief Clearing format flags.
609 * @param mask The flags to unset.
611 * This function clears @a mask in the format flags.
614 unsetf(fmtflags __mask)
615 { _M_flags &= ~__mask; }
618 * @brief Flags access.
619 * @return The precision to generate on certain output operations.
621 * Be careful if you try to give a definition of "precision" here; see
626 { return _M_precision; }
629 * @brief Changing flags.
630 * @param prec The new precision value.
631 * @return The previous value of precision().
634 precision(streamsize __prec)
636 streamsize __old = _M_precision;
637 _M_precision = __prec;
642 * @brief Flags access.
643 * @return The minimum field width to generate on output operations.
645 * "Minimum field width" refers to the number of characters.
652 * @brief Changing flags.
653 * @param wide The new width value.
654 * @return The previous value of width().
657 width(streamsize __wide)
659 streamsize __old = _M_width;
664 // [27.4.2.4] ios_base static members
666 * @brief Interaction with the standard C I/O objects.
667 * @param sync Whether to synchronize or not.
668 * @return True if the standard streams were previously synchronized.
670 * The synchronization referred to is @e only that between the standard
671 * C facilities (e.g., stdout) and the standard C++ objects (e.g.,
672 * cout). User-declared streams are unaffected. See
673 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch28s02.html
676 sync_with_stdio(bool __sync = true);
678 // [27.4.2.3] ios_base locale functions
680 * @brief Setting a new locale.
681 * @param loc The new locale.
682 * @return The previous locale.
684 * Sets the new locale for this stream, and then invokes each callback
688 imbue(const locale& __loc);
691 * @brief Locale access
692 * @return A copy of the current locale.
694 * If @c imbue(loc) has previously been called, then this function
695 * returns @c loc. Otherwise, it returns a copy of @c std::locale(),
696 * the global C++ locale.
700 { return _M_ios_locale; }
703 * @brief Locale access
704 * @return A reference to the current locale.
706 * Like getloc above, but returns a reference instead of
711 { return _M_ios_locale; }
713 // [27.4.2.5] ios_base storage functions
715 * @brief Access to unique indices.
716 * @return An integer different from all previous calls.
718 * This function returns a unique integer every time it is called. It
719 * can be used for any purpose, but is primarily intended to be a unique
720 * index for the iword and pword functions. The expectation is that an
721 * application calls xalloc in order to obtain an index in the iword and
722 * pword arrays that can be used without fear of conflict.
724 * The implementation maintains a static variable that is incremented and
725 * returned on each invocation. xalloc is guaranteed to return an index
726 * that is safe to use in the iword and pword arrays.
732 * @brief Access to integer array.
733 * @param __ix Index into the array.
734 * @return A reference to an integer associated with the index.
736 * The iword function provides access to an array of integers that can be
737 * used for any purpose. The array grows as required to hold the
738 * supplied index. All integers in the array are initialized to 0.
740 * The implementation reserves several indices. You should use xalloc to
741 * obtain an index that is safe to use. Also note that since the array
742 * can grow dynamically, it is not safe to hold onto the reference.
747 _Words& __word = (__ix < _M_word_size)
748 ? _M_word[__ix] : _M_grow_words(__ix, true);
749 return __word._M_iword;
753 * @brief Access to void pointer array.
754 * @param __ix Index into the array.
755 * @return A reference to a void* associated with the index.
757 * The pword function provides access to an array of pointers that can be
758 * used for any purpose. The array grows as required to hold the
759 * supplied index. All pointers in the array are initialized to 0.
761 * The implementation reserves several indices. You should use xalloc to
762 * obtain an index that is safe to use. Also note that since the array
763 * can grow dynamically, it is not safe to hold onto the reference.
768 _Words& __word = (__ix < _M_word_size)
769 ? _M_word[__ix] : _M_grow_words(__ix, false);
770 return __word._M_pword;
775 * Invokes each callback with erase_event. Destroys local storage.
777 * Note that the ios_base object for the standard streams never gets
778 * destroyed. As a result, any callbacks registered with the standard
779 * streams will not get invoked with erase_event (unless copyfmt is
787 // _GLIBCXX_RESOLVE_LIB_DEFECTS
788 // 50. Copy constructor and assignment operator of ios_base
790 ios_base(const ios_base&);
793 operator=(const ios_base&);
796 // [27.4.5.1] fmtflags manipulators
797 /// Calls base.setf(ios_base::boolalpha).
799 boolalpha(ios_base& __base)
801 __base.setf(ios_base::boolalpha);
805 /// Calls base.unsetf(ios_base::boolalpha).
807 noboolalpha(ios_base& __base)
809 __base.unsetf(ios_base::boolalpha);
813 /// Calls base.setf(ios_base::showbase).
815 showbase(ios_base& __base)
817 __base.setf(ios_base::showbase);
821 /// Calls base.unsetf(ios_base::showbase).
823 noshowbase(ios_base& __base)
825 __base.unsetf(ios_base::showbase);
829 /// Calls base.setf(ios_base::showpoint).
831 showpoint(ios_base& __base)
833 __base.setf(ios_base::showpoint);
837 /// Calls base.unsetf(ios_base::showpoint).
839 noshowpoint(ios_base& __base)
841 __base.unsetf(ios_base::showpoint);
845 /// Calls base.setf(ios_base::showpos).
847 showpos(ios_base& __base)
849 __base.setf(ios_base::showpos);
853 /// Calls base.unsetf(ios_base::showpos).
855 noshowpos(ios_base& __base)
857 __base.unsetf(ios_base::showpos);
861 /// Calls base.setf(ios_base::skipws).
863 skipws(ios_base& __base)
865 __base.setf(ios_base::skipws);
869 /// Calls base.unsetf(ios_base::skipws).
871 noskipws(ios_base& __base)
873 __base.unsetf(ios_base::skipws);
877 /// Calls base.setf(ios_base::uppercase).
879 uppercase(ios_base& __base)
881 __base.setf(ios_base::uppercase);
885 /// Calls base.unsetf(ios_base::uppercase).
887 nouppercase(ios_base& __base)
889 __base.unsetf(ios_base::uppercase);
893 /// Calls base.setf(ios_base::unitbuf).
895 unitbuf(ios_base& __base)
897 __base.setf(ios_base::unitbuf);
901 /// Calls base.unsetf(ios_base::unitbuf).
903 nounitbuf(ios_base& __base)
905 __base.unsetf(ios_base::unitbuf);
909 // [27.4.5.2] adjustfield manipulators
910 /// Calls base.setf(ios_base::internal, ios_base::adjustfield).
912 internal(ios_base& __base)
914 __base.setf(ios_base::internal, ios_base::adjustfield);
918 /// Calls base.setf(ios_base::left, ios_base::adjustfield).
920 left(ios_base& __base)
922 __base.setf(ios_base::left, ios_base::adjustfield);
926 /// Calls base.setf(ios_base::right, ios_base::adjustfield).
928 right(ios_base& __base)
930 __base.setf(ios_base::right, ios_base::adjustfield);
934 // [27.4.5.3] basefield manipulators
935 /// Calls base.setf(ios_base::dec, ios_base::basefield).
937 dec(ios_base& __base)
939 __base.setf(ios_base::dec, ios_base::basefield);
943 /// Calls base.setf(ios_base::hex, ios_base::basefield).
945 hex(ios_base& __base)
947 __base.setf(ios_base::hex, ios_base::basefield);
951 /// Calls base.setf(ios_base::oct, ios_base::basefield).
953 oct(ios_base& __base)
955 __base.setf(ios_base::oct, ios_base::basefield);
959 // [27.4.5.4] floatfield manipulators
960 /// Calls base.setf(ios_base::fixed, ios_base::floatfield).
962 fixed(ios_base& __base)
964 __base.setf(ios_base::fixed, ios_base::floatfield);
968 /// Calls base.setf(ios_base::scientific, ios_base::floatfield).
970 scientific(ios_base& __base)
972 __base.setf(ios_base::scientific, ios_base::floatfield);
976 _GLIBCXX_END_NAMESPACE
978 #undef _IOS_BASE_SEEK_CUR
979 #undef _IOS_BASE_SEEK_END
981 #endif /* _IOS_BASE_H */