Where in the documentation/spec does it describe how '\n' is converted in text-mode to platform-specific line-endings?

Question

I know, from experience, that the following code:

#include <iostream>

int main()
{
    std::cout << "Hello World!\n";
    return 0;
}

results in different line-endings being printed on different platforms (e.g. Linux: LF, Windows:CRLF) and that I sometimes have to switch count to binary mode if I want specific behaviour. Likewise I know that with filestreams I open myself I have to be careful to specify text or binary mode for my desired line-ending behaviour.

However I'm struggling to find where this behaviour of converting \n to CRLF is actually documented!

I've looked in the C++ spec (specifically C++98 through to 22) and the various online references (e.g. cppreference.com) and can't find which class / library routine is responsible for *actually converting the \n into the platform specific line end`. (Also, don't ask ChaptGPT, it's happily making up quotes from the spec that don't exist)

Or to phrase it another way: Where is the behaviour of C++'s text-mode and binary-mode streams specified?

If it cannot be found in the C++ spec, then the question is: Is it inherited behaviour from C? If so where is that defined?

Or is this something that C just inherits from the platforms it runs on?

Answer 1

From the C standard, 7.21.2 Streams, emphasis mine:

A text stream is an ordered sequence of characters composed into lines, each line consisting of zero or more characters plus a terminating new-line character. Whether the last line requires a terminating new-line character is implementation-defined. Characters may have to be added, altered, or deleted on input and output to conform to differing conventions for representing text in the host environment. Thus, there need not be a one-to-one correspondence between the characters in a stream and those in the external representation. Data read in from a text stream will necessarily compare equal to the data that were earlier written out to that stream only if: the data consist only of printing characters and the control characters horizontal tab and new-line; no new-line character is immediately preceded by space characters; and the last character is a new-line character. Whether space characters that are written out immediately before a new-line character appear when read in is implementation-defined.

A binary stream is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream shall compare equal to the data that were earlier written out to that stream, under the same implementation. Such a stream may, however, hav e an implementation-defined number of null characters appended to the end of the stream.

C++ basically inherits this definition.

Referring to the edit of your question:

If no documentation can be found, then a substitute answer would be knowledge of which specific API does this in the C++ stdlib, C stdlib or various OS platforms.

The "API" you are looking for is opening the stream in text mode.

You write printf( "Hello Bob!\n" ) or std::cout << "Hello Bob!\n", and the library implementation does whatever conversion is necessary (which might not be limited to line endings).