documentation of ios::nolock and ios::nolockbuf incorrect

• Key: STDCXX-1030
• Type: Bug
• Status: Open
• Priority: Major
• Assignee: Martin Sebor
• Reporter: Martin Sebor
• Component/s: Documentation
• Affects Version/s: 4.2.1
• Fix Version/s: 4.2.2

Description

Sounds like the documentation of the two bits in the User Guide is backwards. Quoting from this post:

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 similar errors.

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 change.

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: Level 2.

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.