Declares objects that control reading from and writing to the standard streams. This include is often the only header you need to do input and output from a C++ program.

#include <iostream>

The objects fall into two groups:

• cin, cout, cerr, and clog are byte oriented, doing conventional byte-at-a-time transfers.

• wcin, wcout, wcerr, and wclog are wide oriented, translating to and from the wide characters that the program manipulates internally.

Once you do certain operations on a stream, such as the standard input, you can't do operations of a different orientation on the same stream. Therefore, a program can't operate interchangeably on both cin and wcin, for example.

All the objects declared in this header share a peculiar property — you can assume they're constructed before any static objects you define, in a translation unit that includes <iostream>. Equally, you can assume that these objects aren't destroyed before the destructors for any such static objects you define. (The output streams are, however, flushed during program termination.) Therefore, you can safely read from or write to the standard streams before program startup and after program termination.

This guarantee isn't universal, however. A static constructor may call a function in another translation unit. The called function can't assume that the objects declared in this header have been constructed, given the uncertain order in which translation units participate in static construction. To use these objects in such a context, you must first construct an object of class ios_base::Init.

The object cerr controls output to a stream buffer associated with the object stderr, declared in <cstdio>.

extern ostream cerr;

An ostream object.

The object controls unbuffered insertions to the standard error output as a byte stream. Once the object is constructed, the expression cerr.flags & unitbuf is nonzero, and cerr.tie() == &cout. For more details, see cerr.flags and unitbuf.

// iostream_cerr.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

using namespace std;

void TestWide( )
{
   int i = 0;
   wcout << L"Enter a number: ";
   wcin >> i;
   wcerr << L"test for wcerr" << endl;
   wclog << L"test for wclog" << endl;
}

int main( )
{
   int i = 0;
   cout << "Enter a number: ";
   cin >> i;
   cerr << "test for cerr" << endl;
   clog << "test for clog" << endl;
   TestWide( );
}

Specifies the cin global stream.

extern istream cin;

An istream object.

The object controls extractions from the standard input as a byte stream. Once the object is constructed, the call cin.tie returns &cout.

In this example, cin sets the fail bit on the stream when it comes across non-numeric characters. The program clears the fail bit and strips the invalid character from the stream to continue.

// iostream_cin.cpp
// compile with: /EHsc
#include <iostream>
using namespace std;

int main()
{
   int x;
   cout << "enter choice:";
   cin >> x;
   while (x < 1 || x > 4)
   {
      cout << "Invalid choice, try again:";
      cin >> x;
      // not a numeric character, probably
      // clear the failure and pull off the non-numeric character
      if (cin.fail())
      {
         cin.clear();
         char c;
         cin >> c;
      }
   }
}

2

Specifies the clog global stream.

extern ostream clog;

An ostream object.

The object controls buffered insertions to the standard error output as a byte stream.

See cerr for an example of using clog.

Specifies the cout global stream.

extern ostream cout;

An ostream object.

The object controls insertions to the standard output as a byte stream.

See cerr for an example of using cout.

Specifies the wcerr global stream.

extern wostream wcerr;

A wostream object.

The object controls unbuffered insertions to the standard error output as a wide stream. Once the object is constructed, the expression wcerr.flags & unitbuf is nonzero. For more details, see wcerr.flags and unitbuf.

See cerr for an example of using wcerr.

Specifies the wcin global stream.

extern wistream wcin;

A wistream object.

The object controls extractions from the standard input as a wide stream. Once the object is constructed, the call wcin.tie returns &wcout.

See cerr for an example of using wcin.

Specifies the wclog global stream.

extern wostream wclog;

A wostream object.

The object controls buffered insertions to the standard error output as a wide stream.

See cerr for an example of using wclog.

Specifies the wcout global stream.

extern wostream wcout;

A wostream object.

The object controls insertions to the standard output as a wide stream.

See cerr for an example of using wcout.

CString instances in a wcout statement must be cast to const wchar_t*, as shown in the following example.

CString cs("meow");

wcout <<(const wchar_t*) cs <<endl;

For more information, see Basic CString Operations.

Header Files Reference
Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions