Document error suppression in standard stream & move upstack

[masklinn]

Background

This is a long-standing issue related to rust-lang/rfcs#1014 "Don't panic when stdout doesn't exist" (rendered), implemented in #25977

The RFC aimed to make the "convenience macros" writing to stdout/stderr not panic in case of a non-existing or closed standard stream.

Issues

None of the convenience macros actually documents this error suppression. All of them claim that they panic on write errors which is sort-of true from their internal perspective but not really from the user's.

More annoyingly, because of the way it was implemented, not only do convenience macros not error anymore (which was intended), the error-reporting macros don't get the errors either: the actual stream was wrapped in a Maybe which converts EBADF / ERROR_INVALID_HANDLE to a success, as well as the stream being missing entirely (on Windows).

Direct usage of write! or Write methods on standard streams would indicate a desire to be notified of and handle errors, including (and possibly especially) the standard streams being closed or full. But currently in order to get that information on Unices it's necessary to notice that this information is not delivered, and re-create the standard stream using the relevant raw fds. This is unexpected, and not exactly consistent I feel.

Possible solution

• document the error suppression on the relevant macros
• move the error suppression outside of the stream objects
  • make a missing stream bubble up a sensible-ish synthetic error code on windows?

Alternate solution

Don't touch anything but document the behaviour clearly on the standard stream pages.

Aside

EPIPE and ENOSPC are somewhat oddly not suppressed in the same conditions, despite the logical failure and issues being similar to EBADF (when writing to a closed pipe), cf #57931, #82791

Related issues

#83904
#47271