Make rustix::io::stdout a safe function, in std mode. (#519)

* Make `rustix::io::stdout` a safe function, in std mode.

Revisit the safety considerations of `rustix::io::stdout` and friends.
The Rust standard library assumes that the stdin, stdout, and stderr
file descriptors are always open, to the point where it's even willing
to hand out a [`'static` borrow for them]. Consequently, rustix doesn't
need to treat these as unsafe when std is in use.

[`'static` borrow for them]: https://doc.rust-lang.org/stable/std/io/struct.Stdin.html#method.lock

* Fix an unused-unsafe warning in an example.

Author: sunfishcode

examples/hello.rs

@@ -11,12 +11,8 @@ fn main() -> std::io::Result<()> {
     // need the ability to compute substrings at arbitrary byte offsets.
     let mut bytes = message.as_bytes();
 
-    // Safety: See [here] for the safety conditions for calling `stdout`. In
-    // this example, the code is inside `main` itself so we know how `stdout`
-    // is being used and we know that it's not dropped.
-    //
-    // [here]: https://docs.rs/rustix/*/rustix/io/fn.stdout.html#safety
-    let stdout = unsafe { rustix::io::stdout() };
+    // In a std-using configuration, `stdout` is always open.
+    let stdout = rustix::io::stdout();
 
     while !bytes.is_empty() {
         match rustix::io::write(&stdout, bytes) {

examples/stdio.rs

@@ -19,7 +19,7 @@ use rustix::termios::ttyname;
 
 #[cfg(not(windows))]
 fn main() -> io::Result<()> {
-    let (stdin, stdout, stderr) = unsafe { (stdin(), stdout(), stderr()) };
+    let (stdin, stdout, stderr) = (stdin(), stdout(), stderr());
 
     println!("Stdin:");
     show(&stdin)?;

src/io/stdio.rs

@@ -14,28 +14,57 @@ use backend::fd::{BorrowedFd, FromRawFd, RawFd};
 
 /// `STDIN_FILENO`—Standard input, borrowed.
 ///
-/// # Safety
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stdin file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
 ///
-/// This function must be called from code which knows how the process'
-/// standard input is being used. Often, this will be the `main` function or
-/// code that knows its relationship with the `main` function.
+/// # Warning
 ///
-/// The stdin file descriptor can be closed, potentially on other threads, in
-/// which case the file descriptor index value could be dynamically reused for
-/// other purposes, potentially on different threads.
+/// This function allows reading directly from stdin without coordinating
+/// with the buffering performed by [`std::io::Stdin`], so it could cause
+/// corrupted input.
 ///
-/// # Other hazards
+/// # References
+///  - [POSIX]
+///  - [Linux]
+///
+/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html
+/// [Linux]: https://man7.org/linux/man-pages/man3/stdin.3.html
+#[cfg(feature = "std")]
+#[doc(alias = "STDIN_FILENO")]
+#[inline]
+pub const fn stdin() -> BorrowedFd<'static> {
+    // Safety: When "std" is enabled, the standard library assumes that the stdio
+    // file descriptors are all valid.
+    unsafe { BorrowedFd::borrow_raw(backend::io::types::STDIN_FILENO as RawFd) }
+}
+
+/// `STDIN_FILENO`—Standard input, borrowed.
+///
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stdin file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
+///
+/// # Safety
+///
+/// In `no_std` configurations, the stdin file descriptor can be closed,
+/// potentially on other threads, in which case the file descriptor index
+/// value could be dynamically reused for other purposes, potentially on
+/// different threads.
 ///
-/// Stdin could be redirected from arbitrary input sources, and unless one
-/// knows how the process' standard input is being used, one could consume
-/// bytes that are expected to be consumed by other parts of the process.
+/// # Warning
+///
+/// This function allows reading directly from stdin without coordinating
+/// with the buffering performed by [`std::io::Stdin`], so it could cause
+/// corrupted input.
 ///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/stdin.3.html
+#[cfg(not(feature = "std"))]
 #[doc(alias = "STDIN_FILENO")]
 #[inline]
 pub const unsafe fn stdin() -> BorrowedFd<'static> {
@@ -49,17 +78,14 @@ pub const unsafe fn stdin() -> BorrowedFd<'static> {
 ///
 /// # Safety
 ///
-/// This is unsafe for the same reasons as [`stdin`].
+/// Safe `std`-using Rust code is permitted to assume that the stdin file
+/// descriptor is always valid. This function returns an `OwnedFd` which will
+/// close the stdin file descriptor when dropped.
 ///
-/// # Other hazards
+/// # Warning
 ///
 /// This has the same hazards as [`stdin`].
 ///
-/// And, when the `OwnedFd` is dropped, subsequent newly created file
-/// descriptors may unknowingly reuse the stdin file descriptor number, which
-/// may break common assumptions, so it should typically only be dropped at the
-/// end of a program when no more file descriptors will be created.
-///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
@@ -74,29 +100,57 @@ pub unsafe fn take_stdin() -> OwnedFd {
 
 /// `STDOUT_FILENO`—Standard output, borrowed.
 ///
-/// # Safety
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stdout file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
 ///
-/// This function must be called from code which knows how the process'
-/// standard output is being used. Often, this will be the `main` function or
-/// code that knows its relationship with the `main` function.
+/// # Warning
 ///
-/// The stdout file descriptor can be closed, potentially on other threads, in
-/// which case the file descriptor index value could be dynamically reused for
-/// other purposes, potentially on different threads.
+/// This function allows reading directly from stdout without coordinating
+/// with the buffering performed by [`std::io::Stdout`], so it could cause
+/// corrupted input.
 ///
-/// # Other hazards
+/// # References
+///  - [POSIX]
+///  - [Linux]
+///
+/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdout.html
+/// [Linux]: https://man7.org/linux/man-pages/man3/stdout.3.html
+#[cfg(feature = "std")]
+#[doc(alias = "STDOUT_FILENO")]
+#[inline]
+pub const fn stdout() -> BorrowedFd<'static> {
+    // Safety: When "std" is enabled, the standard library assumes that the stdio
+    // file descriptors are all valid.
+    unsafe { BorrowedFd::borrow_raw(backend::io::types::STDOUT_FILENO as RawFd) }
+}
+
+/// `STDOUT_FILENO`—Standard output, borrowed.
 ///
-/// Stdout could be redirected to arbitrary output sinks, and unless one
-/// knows how the process' standard output is being used, one could
-/// unexpectedly inject bytes into a stream being written by another part of
-/// the process.
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stdin file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
+///
+/// # Safety
+///
+/// In `no_std` configurations, the stdout file descriptor can be closed,
+/// potentially on other threads, in which case the file descriptor index
+/// value could be dynamically reused for other purposes, potentially on
+/// different threads.
+///
+/// # Warning
+///
+/// This function allows reading directly from stdout without coordinating
+/// with the buffering performed by [`std::io::Stdout`], so it could cause
+/// corrupted input.
 ///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdout.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/stdout.3.html
+#[cfg(not(feature = "std"))]
 #[doc(alias = "STDOUT_FILENO")]
 #[inline]
 pub const unsafe fn stdout() -> BorrowedFd<'static> {
@@ -110,17 +164,14 @@ pub const unsafe fn stdout() -> BorrowedFd<'static> {
 ///
 /// # Safety
 ///
-/// This is unsafe for the same reasons as [`stdout`].
+/// Safe `std`-using Rust code is permitted to assume that the stdout file
+/// descriptor is always valid. This function returns an `OwnedFd` which will
+/// close the stdout file descriptor when dropped.
 ///
-/// # Other hazards
+/// # Warning
 ///
 /// This has the same hazards as [`stdout`].
 ///
-/// And, when the `OwnedFd` is dropped, subsequent newly created file
-/// descriptors may unknowingly reuse the stdout file descriptor number, which
-/// may break common assumptions, so it should typically only be dropped at the
-/// end of a program when no more file descriptors will be created.
-///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
@@ -135,28 +186,45 @@ pub unsafe fn take_stdout() -> OwnedFd {
 
 /// `STDERR_FILENO`—Standard error, borrowed.
 ///
-/// # Safety
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stderr file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
 ///
-/// This function must be called from code which knows how the process'
-/// standard error is being used. Often, this will be the `main` function or
-/// code that knows its relationship with the `main` function.
+/// # References
+///  - [POSIX]
+///  - [Linux]
 ///
-/// The stderr file descriptor can be closed, potentially on other threads, in
-/// which case the file descriptor index value could be dynamically reused for
-/// other purposes, potentially on different threads.
+/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stderr.html
+/// [Linux]: https://man7.org/linux/man-pages/man3/stderr.3.html
+#[cfg(feature = "std")]
+#[doc(alias = "STDERR_FILENO")]
+#[inline]
+pub const fn stderr() -> BorrowedFd<'static> {
+    // Safety: When "std" is enabled, the standard library assumes that the stdio
+    // file descriptors are all valid.
+    unsafe { BorrowedFd::borrow_raw(backend::io::types::STDERR_FILENO as RawFd) }
+}
+
+/// `STDERR_FILENO`—Standard error, borrowed.
 ///
-/// # Other hazards
+/// In `std`-using configurations, this is a safe function, because the
+/// standard library already assumes that the stderr file descriptor is always
+/// valid. In `no_std` configurations, it is `unsafe`.
+///
+/// # Safety
 ///
-/// Stderr could be redirected to arbitrary output sinks, and unless one
-/// knows how the process' standard error is being used, one could unexpectedly
-/// inject bytes into a stream being written by another part of the process.
+/// In `no_std` configurations, the stderr file descriptor can be closed,
+/// potentially on other threads, in which case the file descriptor index
+/// value could be dynamically reused for other purposes, potentially on
+/// different threads.
 ///
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stderr.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/stderr.3.html
+#[cfg(not(feature = "std"))]
 #[doc(alias = "STDERR_FILENO")]
 #[inline]
 pub const unsafe fn stderr() -> BorrowedFd<'static> {
@@ -170,7 +238,9 @@ pub const unsafe fn stderr() -> BorrowedFd<'static> {
 ///
 /// # Safety
 ///
-/// This is unsafe for the same reasons as [`stderr`].
+/// Safe std-using Rust code is permitted to assume that the stderr file
+/// descriptor is always valid. This function returns an `OwnedFd` which will
+/// close the stderr file descriptor when dropped.
 ///
 /// # Other hazards
 ///

tests/termios/isatty.rs

@@ -52,18 +52,16 @@ fn stdio_descriptors() {
     #[cfg(target_os = "wasi")]
     use std::os::wasi::io::AsRawFd;
 
-    unsafe {
-        assert_eq!(
-            rustix::io::stdin().as_raw_fd(),
-            std::io::stdin().as_raw_fd()
-        );
-        assert_eq!(
-            rustix::io::stdout().as_raw_fd(),
-            std::io::stdout().as_raw_fd()
-        );
-        assert_eq!(
-            rustix::io::stderr().as_raw_fd(),
-            std::io::stderr().as_raw_fd()
-        );
-    }
+    assert_eq!(
+        rustix::io::stdin().as_raw_fd(),
+        std::io::stdin().as_raw_fd()
+    );
+    assert_eq!(
+        rustix::io::stdout().as_raw_fd(),
+        std::io::stdout().as_raw_fd()
+    );
+    assert_eq!(
+        rustix::io::stderr().as_raw_fd(),
+        std::io::stderr().as_raw_fd()
+    );
 }