You're right, the documentation is confusing. In fact, I'd say
the documentation is downright wrong: when ios::nolock is *set*
the stream does not get locked and thus is *not thread safe*,
while when it's *clear*, it does get locked and the stream is
*thread safe*. I filed STDCXX-1030 to correct the docs:
This is a documentation issue in the multi-thread safe section of the users
guide for the stdcxx iostreams.
In addition, I am posting the error we observed so others can search for
The following is the error that was observed. However, the error only showed
up intermittently when the system was under sufficient load:
stopped in __rw::__rw_sputn<char,std::char_traits<char> > at 0x84028
0x00084028: __rw_sputn+0x00e0: stb %l1, [%l0]
We were able to solve the problem using the information in the users guide,
but the section was a little confusing in regards to applying the code
When it became obvious this was a multi-thread issue with the standard
stdcxx C++ library iostreams. Searching the documentation we found the
following in the Stdcxx Library User's Guide section 44.1 Multithread-Safe:
The part that is a little confusing is the following:
Thread safety is controlled by two bits, ios_base::nolock and
ios_base::nolockbuf. These bits can be set on an iostream object (such as
std::cout) using the public member function std::ios_base::setf(). When the
bits are set, the object behaves in a thread-safe way as described above.
The public member function std::ios_base::unsetf() clears both bits. When
the bits are not set, the object is not thread-safe. It is also possible to
set the bits individually to allow the stream thread-unsafe access on the
stream data (nolock), or to prevent the stream from locking prior to
accessing the stream buffer (nolockbuf).
Particularly the part that reads as follows:
"These bits can be set on an iostream object (such as std::cout) using the
public member function std::ios_base::setf(). When the bits are set, the
object behaves in a thread-safe way as described above. "
And in the following sentence as well:
"When the bits are not set, the object is not thread-safe."
If you want thread-safe iostreams you would do the following:
std::ios_base::unsetf( std::ios_base::nolock | std::ios_base::nolockbuf )
If you do not want a thread-safe iostreams you would do the following:
std::ios_base::setf( std::ios_base::nolock | std::ios_base::nolockbuf )
The documentation is rather confusing on exactly how this needs to be set
for thread-safe or the default with no thread-safe behavior.