<iostream>

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.

Syntax

#include <iostream>

Note

The <iostream> library uses the #include <ios>, #include <streambuf>, #include <istream>, and #include <ostream> statements.

Remarks

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.

Global Stream Objects

Name Description
cerr Specifies the cerr global stream.
cin Specifies the cin global stream.
clog Specifies the clog global stream.
cout Specifies the cout global stream.
wcerr Specifies the wcerr global stream.
wcin Specifies the wcin global stream.
wclog Specifies the wclog global stream.
wcout Specifies the wcout global stream.

cerr

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

extern ostream cerr;

Return Value

An ostream object.

Remarks

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.

Example

// 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( );
}

cin

Specifies the cin global stream.

extern istream cin;

Return Value

An istream object.

Remarks

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

Example

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

clog

Specifies the clog global stream.

extern ostream clog;

Return Value

An ostream object.

Remarks

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

Example

See cerr for an example of using clog.

cout

Specifies the cout global stream.

extern ostream cout;

Return Value

An ostream object.

Remarks

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

Example

See cerr for an example of using cout.

wcerr

Specifies the wcerr global stream.

extern wostream wcerr;

Return Value

A wostream object.

Remarks

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.

Example

See cerr for an example of using wcerr.

wcin

Specifies the wcin global stream.

extern wistream wcin;

Return Value

A wistream object.

Remarks

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

Example

See cerr for an example of using wcin.

wclog

Specifies the wclog global stream.

extern wostream wclog;

Return Value

A wostream object.

Remarks

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

Example

See cerr for an example of using wclog.

wcout

Specifies the wcout global stream.

extern wostream wcout;

Return Value

A wostream object.

Remarks

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

Example

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.

See also

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