NAME¶

std::basic_ios::tie - std::basic_ios::tie

Synopsis¶

std::basic_ostream<CharT, Traits>* tie() const; (1)
std::basic_ostream<CharT, Traits>* tie( std::basic_ostream<CharT, Traits>* str (2)
);

Manages the tied stream. A tied stream is an output stream which is synchronized
with the sequence controlled by the stream buffer (rdbuf()), that is, flush() is
called on the tied stream before any input/output operation on *this.

1) Returns the current tied stream. If there is no tied stream, a null pointer is
returned.
2) Sets the current tied stream to str. Returns the tied stream before the
operation. If there is no tied stream, a null pointer is returned. If str is not
null and tie() is reachable by traversing the linked list of tied stream objects
starting from str->tie(), the behavior is undefined.

Parameters¶

str - an output stream to set as the tied stream

Return value¶

The tied stream, or a null pointer if there was no tied stream.

Exceptions¶

May throw implementation-defined exceptions.

Notes¶

By default, the standard stream std::cout is tied to std::cin and std::cerr.
Similarly, its wide counterpart std::wcout is tied to std::wcin and std::wcerr.

Example¶

// Run this code

#include <fstream>
#include <iomanip>
#include <iostream>
#include <string>

int main()
{
std::ofstream os("test.txt");
std::ifstream is("test.txt");
std::string value("0");

os << "Hello";
is >> value;

std::cout << "Result before tie(): " << std::quoted(value) << "\n";
is.clear();
is.tie(&os);

is >> value;

std::cout << "Result after tie(): " << std::quoted(value) << "\n";
}

Output:¶

Result before tie(): "0"
Result after tie(): "Hello"

Defect reports

The following behavior-changing defect reports were applied retroactively to
previously published C++ standards.

DR Applied to Behavior as published Correct behavior
two streams could be tied to each
LWG 835 C++98 other^[1] the behavior is undefined
(either directly or through another in this case
intermediate stream object)

1. ↑ std::basic_ostream::flush() is an UnformattedOutputFunction, so it creates a
sentry object while being called. When flush() is called on a stream object, the
constructor of the sentry object will call flush() on its tied stream, and that
flush() will construct another sentry object and its constructor will call
flush() on the tied stream of that stream and so on. Therefore, if streams a and
b are (directly or indirectly) tied to each other, calling a.flush() will
eventually call b.flush(), which will eventually call a.flush(), and will result
in an infinite loop.