From dfbc1f712d61340dab653ac8d54bdc701b64e2ec Mon Sep 17 00:00:00 2001
From: Usama Arif <usama.arif@bytedance.com>
Date: Sun, 4 Sep 2022 18:43:18 +0100
Subject: [PATCH] stdio: Document no support for writing to non-blocking
 stdio/stderr

Printing to stdio/stderr that have been opened with non-blocking
(O_NONBLOCK in linux) can result in an error, which is not handled
by std::io module causing a panic.

Signed-off-by: Usama Arif <usama.arif@bytedance.com>
---
 library/std/src/io/stdio.rs |  3 +++
 library/std/src/macros.rs   | 12 ++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/library/std/src/io/stdio.rs b/library/std/src/io/stdio.rs
index 91cff3217d21b..2dc12a18a8a66 100644
--- a/library/std/src/io/stdio.rs
+++ b/library/std/src/io/stdio.rs
@@ -992,6 +992,9 @@ pub fn set_output_capture(sink: Option<LocalStream>) -> Option<LocalStream> {
 /// the global stream.
 ///
 /// However, if the actual I/O causes an error, this function does panic.
+///
+/// Writing to non-blocking stdout/stderr can cause an error, which will lead
+/// this function to panic.
 fn print_to<T>(args: fmt::Arguments<'_>, global_s: fn() -> T, label: &str)
 where
     T: Write,
diff --git a/library/std/src/macros.rs b/library/std/src/macros.rs
index a5003c66fcad7..6e4ba1404e551 100644
--- a/library/std/src/macros.rs
+++ b/library/std/src/macros.rs
@@ -49,6 +49,9 @@ macro_rules! panic {
 ///
 /// Panics if writing to `io::stdout()` fails.
 ///
+/// Writing to non-blocking stdout can cause an error, which will lead
+/// this macro to panic.
+///
 /// # Examples
 ///
 /// ```
@@ -107,6 +110,9 @@ macro_rules! print {
 ///
 /// Panics if writing to [`io::stdout`] fails.
 ///
+/// Writing to non-blocking stdout can cause an error, which will lead
+/// this macro to panic.
+///
 /// [`io::stdout`]: crate::io::stdout
 ///
 /// # Examples
@@ -147,6 +153,9 @@ macro_rules! println {
 ///
 /// Panics if writing to `io::stderr` fails.
 ///
+/// Writing to non-blocking stdout can cause an error, which will lead
+/// this macro to panic.
+///
 /// # Examples
 ///
 /// ```
@@ -179,6 +188,9 @@ macro_rules! eprint {
 ///
 /// Panics if writing to `io::stderr` fails.
 ///
+/// Writing to non-blocking stdout can cause an error, which will lead
+/// this macro to panic.
+///
 /// # Examples
 ///
 /// ```