# <ostream>

<head><title>&lt;ostream&gt;</title></head>

# `<ostream>`

* * *

    namespace std {
    template<class Elem, class Tr = char_traits<Elem> >
        class basic_ostream;
    typedef basic_ostream<char, char_traits<char> >
        ostream;
    typedef basic_ostream<wchar_t, char_traits<wchar_t> >
        wostream;
    
            // INSERTERS
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const Elem *str);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                Elem ch);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const char *str);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const char *str);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const signed char *str);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                signed char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const unsigned char *str);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                unsigned char ch);
    
            // MANIPULATORS
    template class<Elem, Tr>
        basic_ostream<Elem, Tr>&
            endl(basic_ostream<Elem, Tr>& ostr);
    template class<Elem, Tr>
        basic_ostream<Elem, Tr>&
            ends(basic_ostream<Elem, Tr>& ostr);
    template class<Elem, Tr>
        basic_ostream<Elem, Tr>&
            flush(basic_ostream<Elem, Tr>& ostr);
    }  // namespace stdCopy to clipboard

Include the [iostreams](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cpp.html#iostreams)
standard header **`<ostream>`** to define
template
class `basic_ostream`,
which mediates insertions for the iostreams.
The header also defines several related
[manipulators](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#manipulators).
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)

## `basic_ostream`

* * *

**`basic_ostream· flush· operator<<· put· seekp· sentry· tellp· write`**

* * *

    template <class Elem, class Tr = char_traits<Elem> >
        class basic_ostream
            : virtual public basic_ios<Elem, Tr> {
    public:
        typedef typename basic_ios<Elem, Tr>::char_type char_type;
        typedef typename basic_ios<Elem, Tr>::traits_type traits_type;
        typedef typename basic_ios<Elem, Tr>::int_type int_type;
        typedef typename basic_ios<Elem, Tr>::pos_type pos_type;
        typedef typename basic_ios<Elem, Tr>::off_type off_type;
    
        explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);
    
        class sentry;
        virtual ~basic_ostream();
    
        basic_ostream& operator<<(
            basic_ostream& (*pfn)(basic_ostream&));
        basic_ostream& operator<<(
            ios_base;& (*pfn)(ios_base&));
        basic_ostream& operator<<(
            basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
        basic_ostream& operator<<(
            basic_streambuf<Elem, Tr> *strbuf);
        basic_ostream& operator<<(bool val);
        basic_ostream& operator<<(short val);
        basic_ostream& operator<<(unsigned short val);
        basic_ostream& operator<<(int val);
        basic_ostream& operator<<(unsigned int val);
        basic_ostream& operator<<(long val);
        basic_ostream& operator<<(unsigned long val);
        basic_ostream& operator<<(float val);
        basic_ostream& operator<<(double val);
        basic_ostream& operator<<(long double val);
        basic_ostream& operator<<(const void *val);
    
        basic_ostream& put(char_type ch);
        basic_ostream& write(char_type *str, streamsize count);
        basic_ostream& flush();
    
        pos_type tellp();
        basic_ostream& seekp(pos_type pos);
        basic_ostream& seekp(off_type off,
            ios_base::seek_dir way);
        };Copy to clipboard

The template class describes an object that controls
insertion of elements and encoded objects into a
[stream buffer](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_streambu.html#stream%20buffer)
with elements of type `Elem`, also known as
`char_type`, whose
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits) are determined by the
class `Tr`, also known as
`traits_type`.

Most of the member functions that overload
`operator<<`
are **formatted output functions**.
They follow the pattern:

        iostate state = goodbit;
        const sentry ok(*this);
        if (ok)
            {try
                {<convert and insert elements
                accumulate flags in state> }
            catch (...)
                {try
                    {setstate(badbit); }
                catch (...)
                    {}
                if ((exceptions() & badbit) != 0)
                    throw; }}
        width(0);    // except for operator<<(Elem)
        setstate(state);
        return (*this);Copy to clipboard

Two other member functions are
**unformatted output functions**.
They follow the pattern:

        iostate state = goodbit;
        const sentry ok(*this);
        if (!ok)
            state |= badbit;
        else
            {try
                {<obtain and insert elements
                accumulate flags in state> }
            catch (...)
                {try
                    {setstate(badbit); }
                catch (...)
                    {}
                if ((exceptions() & badbit) != 0)
                    throw; }}
        setstate(state);
        return (*this);Copy to clipboard

Both groups of functions call
`setstate(badbit)`
if they encounter a failure while inserting elements.

An object of class `basic_ostream<Elem, Tr>` stores only
a virtual public base object of class
**`basic_ios<Elem, Tr>`**

### `basic_ostream::basic_ostream`

    explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);Copy to clipboard

The constructor initializes the base class by calling
`init(strbuf)`.

### `basic_ostream::flush`

    basic_ostream& flush();Copy to clipboard

If `rdbuf()` is
not a null pointer, the function calls
`rdbuf()->pubsync()`.
If that returns -1, the function calls
`setstate(badbit)`.
It returns `*this`.

### `basic_ostream::operator<<`

    basic_ostream& operator<<(
        basic_ostream& (*pfn)(basic_ostream&));
    basic_ostream& operator<<(
        ios_base& (*pfn)(ios_base&));
    basic_ostream& operator<<(
        basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
    basic_ostream& operator<<(
        basic_streambuf<Elem, Tr> *strbuf);
    basic_ostream& operator<<(bool val);
    basic_ostream& operator<<(short val);
    basic_ostream& operator<<(unsigned short val);
    basic_ostream& operator<<(int val);
    basic_ostream& operator<<(unsigned int val);
    basic_ostream& operator<<(long val);
    basic_ostream& operator<<(unsigned long val);
    basic_ostream& operator<<(float val);
    basic_ostream& operator<<(double val);
    basic_ostream& operator<<(long double val);
    basic_ostream& operator<<(const void *val);Copy to clipboard

The first member function ensures that an expression of the
form `ostr << endl` calls
`endl(ostr)`, then returns `*this`.
The second and third functions ensure that other
[manipulators](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#manipulators),
such as `hex` behave
similarly. The remaining functions are all
[formatted output functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#formatted%20output%20functions).

The function:

    basic_ostream& operator<<(
        basic_streambuf<Elem, Tr> *strbuf);Copy to clipboard

extracts elements from `strbuf`,
if `strbuf` is not a null pointer, and inserts them.
If `strbuf` is a null pointer, the function calls
`setstate(badbit)`.
Otherwise, extraction stops on end-of-file,
or if an extraction throws an exception (which is rethrown).
It also stops, without extracting the element in question,
if an insertion fails. If the function inserts no elements, or
if an extraction throws an exception, the function calls
`setstate(failbit)`.
In any case, the function returns `*this`.

The function:

    basic_ostream& operator<<(bool val);Copy to clipboard

converts `val` to a boolean field and inserts it by calling
`use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val)`. Here, `OutIt` is defined as
`ostreambuf_iterator<Elem,
Tr>`.
The function returns `*this`.

The functions:

    basic_ostream& operator<<(short val);
    basic_ostream& operator<<(unsigned short val);
    basic_ostream& operator<<(int val);
    basic_ostream& operator<<(unsigned int val);
    basic_ostream& operator<<(long val);
    basic_ostream& operator<<(unsigned long val);
    basic_ostream& operator<<(const void *val);Copy to clipboard

each convert `val` to a numeric field and insert it by calling
`use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val)`. Here, `OutIt` is defined as
`ostreambuf_iterator<Elem,
Tr>`.

The function returns `*this`.

The functions:

    basic_ostream& operator<<(float val);
    basic_ostream& operator<<(double val);
    basic_ostream& operator<<(long double val);Copy to clipboard

each convert `val` to a numeric field and insert it by calling
`use_facet<num_put<Elem,
OutIt>(getloc()).
put(OutIt(
rdbuf()), *this,
getloc(), val)`. Here, `OutIt` is defined as
`ostreambuf_iterator<Elem,
Tr>`. The function returns `*this`.

### `basic_ostream::put`

    basic_ostream& put(char_type ch);Copy to clipboard

The [unformatted output function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#unformatted%20output%20functions)
inserts the element `ch`. It returns `*this`.

### `basic_ostream::seekp`

    basic_ostream& seekp(pos_type pos);
    basic_ostream& seekp(off_type off,
        ios_base::seek_dir way);Copy to clipboard

If `fail()` is false,
the first member function calls
`newpos = rdbuf()->
pubseekpos(pos,
out)`,
for some `pos_type` temporary object `newpos`.
If `fail()` is false, the second function calls
`newpos = rdbuf()->
pubseekoff(off, way,
out)`.
In either case, if `(off_type)newpos == (off_type)(-1)`
(the positioning operation fails) the function calls
`istr.setstate(failbit)`.
Both functions return `*this`.

### `basic_ostream::sentry`

    class sentry {
    public:
        explicit sentry(basic_ostream<Elem, Tr>& ostr);
        operator bool() const;
        ~sentry();
    private:
        sentry(const sentry&);  // not defined
        sentry& operator=(const sentry&);  // not defined
        bool status;
        };Copy to clipboard

The nested class describes an object whose declaration structures the
[formatted output functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#formatted%20output%20functions)
and the
[unformatted output functions](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#unformatted%20output%20functions).
If `ostr.good()` is true, and
`ostr.tie()` is not
a null pointer, the constructor calls
`ostr.tie->flush()`.
The constructor then stores the value returned by `ostr.good()`
in **status**.
A later call to `operator bool()` delivers this stored value.

If

`uncaught_exception()`
returns false and
`flags() &
unitbuf` is nonzero,
the destructor calls
`flush()`.

### `basic_ostream::tellp`

    pos_type tellp();Copy to clipboard

If `fail()` is false,
the member function returns
`rdbuf()->
pubseekoff(0,
cur,
in)`.
Otherwise, it returns `pos_type(-1)`.

### `basic_ostream::write`

    basic_ostream& write(const char_type *str, streamsize count);Copy to clipboard

The [unformatted output function](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#unformatted%20output%20functions)
inserts the sequence of `count` elements
beginning at `str`.

## `endl`

    template class<Elem, Tr>
        basic_ostream<Elem, Tr>& endl(basic_ostream<Elem, Tr>& ostr);Copy to clipboard

The manipulator calls
`ostr.put(ostr.
widen('\n'))`,
then calls
`ostr.flush()`.
It returns `ostr`.

## `ends`

    template class<Elem, Tr>
        basic_ostream<Elem, Tr>& ends(basic_ostream<Elem, Tr>& ostr);Copy to clipboard

The manipulator calls
`ostr.put(Elem('\0'))`.
It returns `ostr`.

## `flush`

    template class<Elem, Tr>
        basic_ostream<Elem, Tr>& flush(basic_ostream<Elem, Tr>& ostr);Copy to clipboard

The manipulator calls
`ostr.flush()`.
It returns `ostr`.

## `operator<<`

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const Elem *str);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                Elem ch);
        template<class Elem, class Tr>
            basic_ostream<Elem, Tr>&
                operator<<(basic_ostream<Elem, Tr>& ostr,
                    const char *str);
        template<class Elem, class Tr>
            basic_ostream<Elem, Tr>&
                operator<<(basic_ostream<Elem, Tr>& ostr,
                    char ch);
        template<class Tr>
            basic_ostream<char, Tr>&
                operator<<(basic_ostream<char, Tr>& ostr,
                    const char *str);
        template<class Tr>
            basic_ostream<char, Tr>&
                operator<<(basic_ostream<char, Tr>& ostr,
                    char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const signed char *str);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                signed char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const unsigned char *str);
    template<class Tr>
       basic_ostream<char, Tr>&
           operator<<(basic_ostream<char, Tr>& ostr,
               unsigned char ch);Copy to clipboard

The template function:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const Elem *str);Copy to clipboard

determines the length `N =
traits_type::length(str)`
of the sequence beginning at `str`, and inserts the sequence. If
`N < ostr.width()`,
then the function also inserts a repetition of `ostr.width() - N`
[fill characters](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#fill%20character).
The repetition precedes the sequence if
`(ostr.flags() &
adjustfield !=
left`.
Otherwise, the repetition follows the sequence.
The function returns `ostr`.

The template function:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                Elem ch);Copy to clipboard

inserts the element `ch`. If
`1 < ostr.width()`,
then the function also inserts a repetition of `ostr.width() - 1`
[fill characters](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ios.html#fill%20character).
The repetition precedes the sequence if
`(ostr.flags() &
adjustfield !=
left`.
Otherwise, the repetition follows the sequence.
It returns `ostr`.

The template function:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const char *str);Copy to clipboard

behaves the same as:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const Elem *str);Copy to clipboard

except that each element `ch` of the sequence beginning
at `str` is converted to an object of type `Elem` by calling
`ostr.put(ostr.
widen(ch))`.

The template function:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                char ch);Copy to clipboard

behaves the same as:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                Elem ch);Copy to clipboard

except that `ch` is converted to an object
of type `Elem` by calling
`ostr.put(ostr.
widen(ch))`.

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const char *str);Copy to clipboard

behaves the same as:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const Elem *str);Copy to clipboard

(It does not have to widen the elements before inserting them.)

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                char ch);Copy to clipboard

behaves the same as:

    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                Elem ch);Copy to clipboard

(It does not have to widen `ch` before inserting it.)

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const signed char *str);Copy to clipboard

returns `ostr << (const char *)str`.

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                signed char ch);Copy to clipboard

returns `ostr << (char)ch`.

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const unsigned char *str);Copy to clipboard

returns `ostr << (const char *)str`.

The template function:

    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                unsigned char ch);Copy to clipboard

returns `ostr << (char)ch`.

## `ostream`

    typedef basic_ostream<char, char_traits<char> > ostream;Copy to clipboard

The type is a synonym for template class
[`basic_ostream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#basic_ostream), specialized
for elements of type *char* with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).

## `wostream`

    typedef basic_ostream<wchar_t, char_traits<wchar_t> >
        wostream;Copy to clipboard

The type is a synonym for template class
[`basic_ostream`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_ostream.html#basic_ostream), specialized
for elements of type `wchar_t` with default
[character traits](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_string2.html#character%20traits).

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<numeric></numeric> Next Topic

<queue></queue>