Using hi(rdbuf)tt(ios::rdbuf) streams can be forced to share their
tt(streambuf) objects. Thus information written to one
stream is actually written to another stream; a phenomenon normally
called emi(redirection). Redirection is commonly implemented at the
operating system level, and sometimes that is still necessary (see
section ref(REDIRECTION)).

A common situation where redirection is useful is when error messages should
be written to file rather than to the standard error stream, usually indicated
by its i(file descriptor) number 2. In the i(Unix) operating system using the
ti(bash) shell, this can be realized as follows:
        verb(    program 2>/tmp/error.log)

Following this command any error messages written by tt(program) are
written to tt(/tmp/error.log), instead of appearing on the screen.

    Here is an example showing how this can be implemented using tt(streambuf)
objects. Assume tt(program) expects an argument defining the name
of the file to write the error messages to. It could be called as follows:
        verb(    program /tmp/error.log)

The program looks like this, an explanation is provided below the
program's source text:
        verbinclude(-a examples/redirection.cc)
    itemization(
    it() At lines 1-2 local variables are defined: tt(errlog) is the
tt(ofstream) to write the error messages to, and tt(cerr_buffer) is a pointer
to a tt(streambuf), to point to the original tt(cerr) buffer.
    it() At line 3  the alternate error stream is opened.
    it() At line 4  redirection takes place: tt(cerr) now writes to
the tt(streambuf) defined by tt(errlog). It is important that
the original buffer used by tt(cerr) is saved, as explained below.
    it() At line 5  we pause. At this point, two lines were written to
the alternate error file. We get a chance to take a look at its content:
there were indeed two lines written to the file.
    it() At line 6  the redirection is terminated. This is very important, as
the tt(errlog) object is destroyed at the end of tt(main). If tt(cerr)'s
buffer would not have been restored, then at that point
tt(cerr) would refer to a non-existing tt(streambuf) object, which might
produce unexpected results. It is the responsibility of the programmer to
make sure that an original tt(streambuf) is saved before redirection, and is
restored when the redirection ends.
    it() Finally, at line 7, tt(Done) is again written to the screen, as
the redirection has been terminated.
    )
