library/std/src/io/stdio.rs

   1 #![cfg_attr(test, allow(unused))]
   2
   3 #[cfg(test)]
   4 mod tests;
   5
   6 use crate::io::prelude::*;
   7
   8 use crate::cell::{Cell, RefCell};
   9 use crate::fmt;
  10 use crate::io::{self, BufReader, IoSlice, IoSliceMut, LineWriter, Lines};
  11 use crate::lazy::SyncOnceCell;
  12 use crate::pin::Pin;
  13 use crate::sync::atomic::{AtomicBool, Ordering};
  14 use crate::sync::{Arc, Mutex, MutexGuard};
  15 use crate::sys::stdio;
  16 use crate::sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
  17
  18 type LocalStream = Arc<Mutex<Vec<u8>>>;
  19
  20 thread_local! {
  21     /// Used by the test crate to capture the output of the print macros and panics.
  22     static OUTPUT_CAPTURE: Cell<Option<LocalStream>> = {
  23         Cell::new(None)
  24     }
  25 }
  26
  27 /// Flag to indicate OUTPUT_CAPTURE is used.
  28 ///
  29 /// If it is None and was never set on any thread, this flag is set to false,
  30 /// and OUTPUT_CAPTURE can be safely ignored on all threads, saving some time
  31 /// and memory registering an unused thread local.
  32 ///
  33 /// Note about memory ordering: This contains information about whether a
  34 /// thread local variable might be in use. Although this is a global flag, the
  35 /// memory ordering between threads does not matter: we only want this flag to
  36 /// have a consistent order between set_output_capture and print_to *within
  37 /// the same thread*. Within the same thread, things always have a perfectly
  38 /// consistent order. So Ordering::Relaxed is fine.
  39 static OUTPUT_CAPTURE_USED: AtomicBool = AtomicBool::new(false);
  40
  41 /// A handle to a raw instance of the standard input stream of this process.
  42 ///
  43 /// This handle is not synchronized or buffered in any fashion. Constructed via
  44 /// the `std::io::stdio::stdin_raw` function.
  45 struct StdinRaw(stdio::Stdin);
  46
  47 /// A handle to a raw instance of the standard output stream of this process.
  48 ///
  49 /// This handle is not synchronized or buffered in any fashion. Constructed via
  50 /// the `std::io::stdio::stdout_raw` function.
  51 struct StdoutRaw(stdio::Stdout);
  52
  53 /// A handle to a raw instance of the standard output stream of this process.
  54 ///
  55 /// This handle is not synchronized or buffered in any fashion. Constructed via
  56 /// the `std::io::stdio::stderr_raw` function.
  57 struct StderrRaw(stdio::Stderr);
  58
  59 /// Constructs a new raw handle to the standard input of this process.
  60 ///
  61 /// The returned handle does not interact with any other handles created nor
  62 /// handles returned by `std::io::stdin`. Data buffered by the `std::io::stdin`
  63 /// handles is **not** available to raw handles returned from this function.
  64 ///
  65 /// The returned handle has no external synchronization or buffering.
  66 #[unstable(feature = "libstd_sys_internals", issue = "none")]
  67 const fn stdin_raw() -> StdinRaw {
  68     StdinRaw(stdio::Stdin::new())
  69 }
  70
  71 /// Constructs a new raw handle to the standard output stream of this process.
  72 ///
  73 /// The returned handle does not interact with any other handles created nor
  74 /// handles returned by `std::io::stdout`. Note that data is buffered by the
  75 /// `std::io::stdout` handles so writes which happen via this raw handle may
  76 /// appear before previous writes.
  77 ///
  78 /// The returned handle has no external synchronization or buffering layered on
  79 /// top.
  80 #[unstable(feature = "libstd_sys_internals", issue = "none")]
  81 const fn stdout_raw() -> StdoutRaw {
  82     StdoutRaw(stdio::Stdout::new())
  83 }
  84
  85 /// Constructs a new raw handle to the standard error stream of this process.
  86 ///
  87 /// The returned handle does not interact with any other handles created nor
  88 /// handles returned by `std::io::stderr`.
  89 ///
  90 /// The returned handle has no external synchronization or buffering layered on
  91 /// top.
  92 #[unstable(feature = "libstd_sys_internals", issue = "none")]
  93 const fn stderr_raw() -> StderrRaw {
  94     StderrRaw(stdio::Stderr::new())
  95 }
  96
  97 impl Read for StdinRaw {
  98     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
  99         handle_ebadf(self.0.read(buf), 0)
 100     }
 101
 102     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 103         handle_ebadf(self.0.read_vectored(bufs), 0)
 104     }
 105
 106     #[inline]
 107     fn is_read_vectored(&self) -> bool {
 108         self.0.is_read_vectored()
 109     }
 110
 111     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 112         handle_ebadf(self.0.read_to_end(buf), 0)
 113     }
 114
 115     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 116         handle_ebadf(self.0.read_to_string(buf), 0)
 117     }
 118 }
 119
 120 impl Write for StdoutRaw {
 121     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 122         handle_ebadf(self.0.write(buf), buf.len())
 123     }
 124
 125     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 126         let total = bufs.iter().map(|b| b.len()).sum();
 127         handle_ebadf(self.0.write_vectored(bufs), total)
 128     }
 129
 130     #[inline]
 131     fn is_write_vectored(&self) -> bool {
 132         self.0.is_write_vectored()
 133     }
 134
 135     fn flush(&mut self) -> io::Result<()> {
 136         handle_ebadf(self.0.flush(), ())
 137     }
 138
 139     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 140         handle_ebadf(self.0.write_all(buf), ())
 141     }
 142
 143     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 144         handle_ebadf(self.0.write_all_vectored(bufs), ())
 145     }
 146
 147     fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
 148         handle_ebadf(self.0.write_fmt(fmt), ())
 149     }
 150 }
 151
 152 impl Write for StderrRaw {
 153     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 154         handle_ebadf(self.0.write(buf), buf.len())
 155     }
 156
 157     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 158         let total = bufs.iter().map(|b| b.len()).sum();
 159         handle_ebadf(self.0.write_vectored(bufs), total)
 160     }
 161
 162     #[inline]
 163     fn is_write_vectored(&self) -> bool {
 164         self.0.is_write_vectored()
 165     }
 166
 167     fn flush(&mut self) -> io::Result<()> {
 168         handle_ebadf(self.0.flush(), ())
 169     }
 170
 171     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 172         handle_ebadf(self.0.write_all(buf), ())
 173     }
 174
 175     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 176         handle_ebadf(self.0.write_all_vectored(bufs), ())
 177     }
 178
 179     fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
 180         handle_ebadf(self.0.write_fmt(fmt), ())
 181     }
 182 }
 183
 184 fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> {
 185     match r {
 186         Err(ref e) if stdio::is_ebadf(e) => Ok(default),
 187         r => r,
 188     }
 189 }
 190
 191 /// A handle to the standard input stream of a process.
 192 ///
 193 /// Each handle is a shared reference to a global buffer of input data to this
 194 /// process. A handle can be `lock`'d to gain full access to [`BufRead`] methods
 195 /// (e.g., `.lines()`). Reads to this handle are otherwise locked with respect
 196 /// to other reads.
 197 ///
 198 /// This handle implements the `Read` trait, but beware that concurrent reads
 199 /// of `Stdin` must be executed with care.
 200 ///
 201 /// Created by the [`io::stdin`] method.
 202 ///
 203 /// [`io::stdin`]: stdin
 204 ///
 205 /// ### Note: Windows Portability Considerations
 206 ///
 207 /// When operating in a console, the Windows implementation of this stream does not support
 208 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
 209 /// an error.
 210 ///
 211 /// In a process with a detached console, such as one using
 212 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 213 /// the contained handle will be null. In such cases, the standard library's `Read` and
 214 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 215 /// standard library or via raw Windows API calls, will fail.
 216 ///
 217 /// # Examples
 218 ///
 219 /// ```no_run
 220 /// use std::io;
 221 ///
 222 /// fn main() -> io::Result<()> {
 223 ///     let mut buffer = String::new();
 224 ///     let mut stdin = io::stdin(); // We get `Stdin` here.
 225 ///     stdin.read_line(&mut buffer)?;
 226 ///     Ok(())
 227 /// }
 228 /// ```
 229 #[stable(feature = "rust1", since = "1.0.0")]
 230 pub struct Stdin {
 231     inner: &'static Mutex<BufReader<StdinRaw>>,
 232 }
 233
 234 /// A locked reference to the [`Stdin`] handle.
 235 ///
 236 /// This handle implements both the [`Read`] and [`BufRead`] traits, and
 237 /// is constructed via the [`Stdin::lock`] method.
 238 ///
 239 /// ### Note: Windows Portability Considerations
 240 ///
 241 /// When operating in a console, the Windows implementation of this stream does not support
 242 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
 243 /// an error.
 244 ///
 245 /// In a process with a detached console, such as one using
 246 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 247 /// the contained handle will be null. In such cases, the standard library's `Read` and
 248 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 249 /// standard library or via raw Windows API calls, will fail.
 250 ///
 251 /// # Examples
 252 ///
 253 /// ```no_run
 254 /// use std::io::{self, BufRead};
 255 ///
 256 /// fn main() -> io::Result<()> {
 257 ///     let mut buffer = String::new();
 258 ///     let stdin = io::stdin(); // We get `Stdin` here.
 259 ///     {
 260 ///         let mut handle = stdin.lock(); // We get `StdinLock` here.
 261 ///         handle.read_line(&mut buffer)?;
 262 ///     } // `StdinLock` is dropped here.
 263 ///     Ok(())
 264 /// }
 265 /// ```
 266 #[must_use = "if unused stdin will immediately unlock"]
 267 #[stable(feature = "rust1", since = "1.0.0")]
 268 pub struct StdinLock<'a> {
 269     inner: MutexGuard<'a, BufReader<StdinRaw>>,
 270 }
 271
 272 /// Constructs a new handle to the standard input of the current process.
 273 ///
 274 /// Each handle returned is a reference to a shared global buffer whose access
 275 /// is synchronized via a mutex. If you need more explicit control over
 276 /// locking, see the [`Stdin::lock`] method.
 277 ///
 278 /// ### Note: Windows Portability Considerations
 279 ///
 280 /// When operating in a console, the Windows implementation of this stream does not support
 281 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
 282 /// an error.
 283 ///
 284 /// In a process with a detached console, such as one using
 285 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 286 /// the contained handle will be null. In such cases, the standard library's `Read` and
 287 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 288 /// standard library or via raw Windows API calls, will fail.
 289 ///
 290 /// # Examples
 291 ///
 292 /// Using implicit synchronization:
 293 ///
 294 /// ```no_run
 295 /// use std::io;
 296 ///
 297 /// fn main() -> io::Result<()> {
 298 ///     let mut buffer = String::new();
 299 ///     io::stdin().read_line(&mut buffer)?;
 300 ///     Ok(())
 301 /// }
 302 /// ```
 303 ///
 304 /// Using explicit synchronization:
 305 ///
 306 /// ```no_run
 307 /// use std::io::{self, BufRead};
 308 ///
 309 /// fn main() -> io::Result<()> {
 310 ///     let mut buffer = String::new();
 311 ///     let stdin = io::stdin();
 312 ///     let mut handle = stdin.lock();
 313 ///
 314 ///     handle.read_line(&mut buffer)?;
 315 ///     Ok(())
 316 /// }
 317 /// ```
 318 #[must_use]
 319 #[stable(feature = "rust1", since = "1.0.0")]
 320 pub fn stdin() -> Stdin {
 321     static INSTANCE: SyncOnceCell<Mutex<BufReader<StdinRaw>>> = SyncOnceCell::new();
 322     Stdin {
 323         inner: INSTANCE.get_or_init(|| {
 324             Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin_raw()))
 325         }),
 326     }
 327 }
 328
 329 impl Stdin {
 330     /// Locks this handle to the standard input stream, returning a readable
 331     /// guard.
 332     ///
 333     /// The lock is released when the returned lock goes out of scope. The
 334     /// returned guard also implements the [`Read`] and [`BufRead`] traits for
 335     /// accessing the underlying data.
 336     ///
 337     /// # Examples
 338     ///
 339     /// ```no_run
 340     /// use std::io::{self, BufRead};
 341     ///
 342     /// fn main() -> io::Result<()> {
 343     ///     let mut buffer = String::new();
 344     ///     let stdin = io::stdin();
 345     ///     let mut handle = stdin.lock();
 346     ///
 347     ///     handle.read_line(&mut buffer)?;
 348     ///     Ok(())
 349     /// }
 350     /// ```
 351     #[stable(feature = "rust1", since = "1.0.0")]
 352     pub fn lock(&self) -> StdinLock<'static> {
 353         // Locks this handle with 'static lifetime. This depends on the
 354         // implementation detail that the underlying `Mutex` is static.
 355         StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) }
 356     }
 357
 358     /// Locks this handle and reads a line of input, appending it to the specified buffer.
 359     ///
 360     /// For detailed semantics of this method, see the documentation on
 361     /// [`BufRead::read_line`].
 362     ///
 363     /// # Examples
 364     ///
 365     /// ```no_run
 366     /// use std::io;
 367     ///
 368     /// let mut input = String::new();
 369     /// match io::stdin().read_line(&mut input) {
 370     ///     Ok(n) => {
 371     ///         println!("{n} bytes read");
 372     ///         println!("{input}");
 373     ///     }
 374     ///     Err(error) => println!("error: {error}"),
 375     /// }
 376     /// ```
 377     ///
 378     /// You can run the example one of two ways:
 379     ///
 380     /// - Pipe some text to it, e.g., `printf foo | path/to/executable`
 381     /// - Give it text interactively by running the executable directly,
 382     ///   in which case it will wait for the Enter key to be pressed before
 383     ///   continuing
 384     #[stable(feature = "rust1", since = "1.0.0")]
 385     pub fn read_line(&self, buf: &mut String) -> io::Result<usize> {
 386         self.lock().read_line(buf)
 387     }
 388
 389     /// Consumes this handle and returns an iterator over input lines.
 390     ///
 391     /// For detailed semantics of this method, see the documentation on
 392     /// [`BufRead::lines`].
 393     ///
 394     /// # Examples
 395     ///
 396     /// ```no_run
 397     /// use std::io;
 398     ///
 399     /// let lines = io::stdin().lines();
 400     /// for line in lines {
 401     ///     println!("got a line: {}", line.unwrap());
 402     /// }
 403     /// ```
 404     #[must_use = "`self` will be dropped if the result is not used"]
 405     #[stable(feature = "stdin_forwarders", since = "1.62.0")]
 406     pub fn lines(self) -> Lines<StdinLock<'static>> {
 407         self.lock().lines()
 408     }
 409 }
 410
 411 #[stable(feature = "std_debug", since = "1.16.0")]
 412 impl fmt::Debug for Stdin {
 413     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 414         f.debug_struct("Stdin").finish_non_exhaustive()
 415     }
 416 }
 417
 418 #[stable(feature = "rust1", since = "1.0.0")]
 419 impl Read for Stdin {
 420     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 421         self.lock().read(buf)
 422     }
 423     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 424         self.lock().read_vectored(bufs)
 425     }
 426     #[inline]
 427     fn is_read_vectored(&self) -> bool {
 428         self.lock().is_read_vectored()
 429     }
 430     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 431         self.lock().read_to_end(buf)
 432     }
 433     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 434         self.lock().read_to_string(buf)
 435     }
 436     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 437         self.lock().read_exact(buf)
 438     }
 439 }
 440
 441 // only used by platform-dependent io::copy specializations, i.e. unused on some platforms
 442 #[cfg(any(target_os = "linux", target_os = "android"))]
 443 impl StdinLock<'_> {
 444     pub(crate) fn as_mut_buf(&mut self) -> &mut BufReader<impl Read> {
 445         &mut self.inner
 446     }
 447 }
 448
 449 #[stable(feature = "rust1", since = "1.0.0")]
 450 impl Read for StdinLock<'_> {
 451     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 452         self.inner.read(buf)
 453     }
 454
 455     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 456         self.inner.read_vectored(bufs)
 457     }
 458
 459     #[inline]
 460     fn is_read_vectored(&self) -> bool {
 461         self.inner.is_read_vectored()
 462     }
 463
 464     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 465         self.inner.read_to_end(buf)
 466     }
 467
 468     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 469         self.inner.read_to_string(buf)
 470     }
 471
 472     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 473         self.inner.read_exact(buf)
 474     }
 475 }
 476
 477 #[stable(feature = "rust1", since = "1.0.0")]
 478 impl BufRead for StdinLock<'_> {
 479     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 480         self.inner.fill_buf()
 481     }
 482
 483     fn consume(&mut self, n: usize) {
 484         self.inner.consume(n)
 485     }
 486
 487     fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> io::Result<usize> {
 488         self.inner.read_until(byte, buf)
 489     }
 490
 491     fn read_line(&mut self, buf: &mut String) -> io::Result<usize> {
 492         self.inner.read_line(buf)
 493     }
 494 }
 495
 496 #[stable(feature = "std_debug", since = "1.16.0")]
 497 impl fmt::Debug for StdinLock<'_> {
 498     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 499         f.debug_struct("StdinLock").finish_non_exhaustive()
 500     }
 501 }
 502
 503 /// A handle to the global standard output stream of the current process.
 504 ///
 505 /// Each handle shares a global buffer of data to be written to the standard
 506 /// output stream. Access is also synchronized via a lock and explicit control
 507 /// over locking is available via the [`lock`] method.
 508 ///
 509 /// Created by the [`io::stdout`] method.
 510 ///
 511 /// ### Note: Windows Portability Considerations
 512 ///
 513 /// When operating in a console, the Windows implementation of this stream does not support
 514 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 515 /// an error.
 516 ///
 517 /// In a process with a detached console, such as one using
 518 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 519 /// the contained handle will be null. In such cases, the standard library's `Read` and
 520 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 521 /// standard library or via raw Windows API calls, will fail.
 522 ///
 523 /// [`lock`]: Stdout::lock
 524 /// [`io::stdout`]: stdout
 525 #[stable(feature = "rust1", since = "1.0.0")]
 526 pub struct Stdout {
 527     // FIXME: this should be LineWriter or BufWriter depending on the state of
 528     //        stdout (tty or not). Note that if this is not line buffered it
 529     //        should also flush-on-panic or some form of flush-on-abort.
 530     inner: Pin<&'static ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>>,
 531 }
 532
 533 /// A locked reference to the [`Stdout`] handle.
 534 ///
 535 /// This handle implements the [`Write`] trait, and is constructed via
 536 /// the [`Stdout::lock`] method. See its documentation for more.
 537 ///
 538 /// ### Note: Windows Portability Considerations
 539 ///
 540 /// When operating in a console, the Windows implementation of this stream does not support
 541 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 542 /// an error.
 543 ///
 544 /// In a process with a detached console, such as one using
 545 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 546 /// the contained handle will be null. In such cases, the standard library's `Read` and
 547 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 548 /// standard library or via raw Windows API calls, will fail.
 549 #[must_use = "if unused stdout will immediately unlock"]
 550 #[stable(feature = "rust1", since = "1.0.0")]
 551 pub struct StdoutLock<'a> {
 552     inner: ReentrantMutexGuard<'a, RefCell<LineWriter<StdoutRaw>>>,
 553 }
 554
 555 static STDOUT: SyncOnceCell<ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>> = SyncOnceCell::new();
 556
 557 /// Constructs a new handle to the standard output of the current process.
 558 ///
 559 /// Each handle returned is a reference to a shared global buffer whose access
 560 /// is synchronized via a mutex. If you need more explicit control over
 561 /// locking, see the [`Stdout::lock`] method.
 562 ///
 563 /// ### Note: Windows Portability Considerations
 564 ///
 565 /// When operating in a console, the Windows implementation of this stream does not support
 566 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 567 /// an error.
 568 ///
 569 /// In a process with a detached console, such as one using
 570 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 571 /// the contained handle will be null. In such cases, the standard library's `Read` and
 572 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 573 /// standard library or via raw Windows API calls, will fail.
 574 ///
 575 /// # Examples
 576 ///
 577 /// Using implicit synchronization:
 578 ///
 579 /// ```no_run
 580 /// use std::io::{self, Write};
 581 ///
 582 /// fn main() -> io::Result<()> {
 583 ///     io::stdout().write_all(b"hello world")?;
 584 ///
 585 ///     Ok(())
 586 /// }
 587 /// ```
 588 ///
 589 /// Using explicit synchronization:
 590 ///
 591 /// ```no_run
 592 /// use std::io::{self, Write};
 593 ///
 594 /// fn main() -> io::Result<()> {
 595 ///     let stdout = io::stdout();
 596 ///     let mut handle = stdout.lock();
 597 ///
 598 ///     handle.write_all(b"hello world")?;
 599 ///
 600 ///     Ok(())
 601 /// }
 602 /// ```
 603 #[must_use]
 604 #[stable(feature = "rust1", since = "1.0.0")]
 605 pub fn stdout() -> Stdout {
 606     Stdout {
 607         inner: Pin::static_ref(&STDOUT).get_or_init_pin(
 608             || unsafe { ReentrantMutex::new(RefCell::new(LineWriter::new(stdout_raw()))) },
 609             |mutex| unsafe { mutex.init() },
 610         ),
 611     }
 612 }
 613
 614 pub fn cleanup() {
 615     if let Some(instance) = STDOUT.get() {
 616         // Flush the data and disable buffering during shutdown
 617         // by replacing the line writer by one with zero
 618         // buffering capacity.
 619         // We use try_lock() instead of lock(), because someone
 620         // might have leaked a StdoutLock, which would
 621         // otherwise cause a deadlock here.
 622         if let Some(lock) = Pin::static_ref(instance).try_lock() {
 623             *lock.borrow_mut() = LineWriter::with_capacity(0, stdout_raw());
 624         }
 625     }
 626 }
 627
 628 impl Stdout {
 629     /// Locks this handle to the standard output stream, returning a writable
 630     /// guard.
 631     ///
 632     /// The lock is released when the returned lock goes out of scope. The
 633     /// returned guard also implements the `Write` trait for writing data.
 634     ///
 635     /// # Examples
 636     ///
 637     /// ```no_run
 638     /// use std::io::{self, Write};
 639     ///
 640     /// fn main() -> io::Result<()> {
 641     ///     let mut stdout = io::stdout().lock();
 642     ///
 643     ///     stdout.write_all(b"hello world")?;
 644     ///
 645     ///     Ok(())
 646     /// }
 647     /// ```
 648     #[stable(feature = "rust1", since = "1.0.0")]
 649     pub fn lock(&self) -> StdoutLock<'static> {
 650         // Locks this handle with 'static lifetime. This depends on the
 651         // implementation detail that the underlying `ReentrantMutex` is
 652         // static.
 653         StdoutLock { inner: self.inner.lock() }
 654     }
 655 }
 656
 657 #[stable(feature = "std_debug", since = "1.16.0")]
 658 impl fmt::Debug for Stdout {
 659     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 660         f.debug_struct("Stdout").finish_non_exhaustive()
 661     }
 662 }
 663
 664 #[stable(feature = "rust1", since = "1.0.0")]
 665 impl Write for Stdout {
 666     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 667         (&*self).write(buf)
 668     }
 669     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 670         (&*self).write_vectored(bufs)
 671     }
 672     #[inline]
 673     fn is_write_vectored(&self) -> bool {
 674         io::Write::is_write_vectored(&&*self)
 675     }
 676     fn flush(&mut self) -> io::Result<()> {
 677         (&*self).flush()
 678     }
 679     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 680         (&*self).write_all(buf)
 681     }
 682     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 683         (&*self).write_all_vectored(bufs)
 684     }
 685     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 686         (&*self).write_fmt(args)
 687     }
 688 }
 689
 690 #[stable(feature = "write_mt", since = "1.48.0")]
 691 impl Write for &Stdout {
 692     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 693         self.lock().write(buf)
 694     }
 695     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 696         self.lock().write_vectored(bufs)
 697     }
 698     #[inline]
 699     fn is_write_vectored(&self) -> bool {
 700         self.lock().is_write_vectored()
 701     }
 702     fn flush(&mut self) -> io::Result<()> {
 703         self.lock().flush()
 704     }
 705     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 706         self.lock().write_all(buf)
 707     }
 708     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 709         self.lock().write_all_vectored(bufs)
 710     }
 711     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 712         self.lock().write_fmt(args)
 713     }
 714 }
 715
 716 #[stable(feature = "rust1", since = "1.0.0")]
 717 impl Write for StdoutLock<'_> {
 718     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 719         self.inner.borrow_mut().write(buf)
 720     }
 721     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 722         self.inner.borrow_mut().write_vectored(bufs)
 723     }
 724     #[inline]
 725     fn is_write_vectored(&self) -> bool {
 726         self.inner.borrow_mut().is_write_vectored()
 727     }
 728     fn flush(&mut self) -> io::Result<()> {
 729         self.inner.borrow_mut().flush()
 730     }
 731     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 732         self.inner.borrow_mut().write_all(buf)
 733     }
 734     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 735         self.inner.borrow_mut().write_all_vectored(bufs)
 736     }
 737 }
 738
 739 #[stable(feature = "std_debug", since = "1.16.0")]
 740 impl fmt::Debug for StdoutLock<'_> {
 741     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 742         f.debug_struct("StdoutLock").finish_non_exhaustive()
 743     }
 744 }
 745
 746 /// A handle to the standard error stream of a process.
 747 ///
 748 /// For more information, see the [`io::stderr`] method.
 749 ///
 750 /// [`io::stderr`]: stderr
 751 ///
 752 /// ### Note: Windows Portability Considerations
 753 ///
 754 /// When operating in a console, the Windows implementation of this stream does not support
 755 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 756 /// an error.
 757 ///
 758 /// In a process with a detached console, such as one using
 759 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 760 /// the contained handle will be null. In such cases, the standard library's `Read` and
 761 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 762 /// standard library or via raw Windows API calls, will fail.
 763 #[stable(feature = "rust1", since = "1.0.0")]
 764 pub struct Stderr {
 765     inner: Pin<&'static ReentrantMutex<RefCell<StderrRaw>>>,
 766 }
 767
 768 /// A locked reference to the [`Stderr`] handle.
 769 ///
 770 /// This handle implements the [`Write`] trait and is constructed via
 771 /// the [`Stderr::lock`] method. See its documentation for more.
 772 ///
 773 /// ### Note: Windows Portability Considerations
 774 ///
 775 /// When operating in a console, the Windows implementation of this stream does not support
 776 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 777 /// an error.
 778 ///
 779 /// In a process with a detached console, such as one using
 780 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 781 /// the contained handle will be null. In such cases, the standard library's `Read` and
 782 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 783 /// standard library or via raw Windows API calls, will fail.
 784 #[must_use = "if unused stderr will immediately unlock"]
 785 #[stable(feature = "rust1", since = "1.0.0")]
 786 pub struct StderrLock<'a> {
 787     inner: ReentrantMutexGuard<'a, RefCell<StderrRaw>>,
 788 }
 789
 790 /// Constructs a new handle to the standard error of the current process.
 791 ///
 792 /// This handle is not buffered.
 793 ///
 794 /// ### Note: Windows Portability Considerations
 795 ///
 796 /// When operating in a console, the Windows implementation of this stream does not support
 797 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 798 /// an error.
 799 ///
 800 /// In a process with a detached console, such as one using
 801 /// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process,
 802 /// the contained handle will be null. In such cases, the standard library's `Read` and
 803 /// `Write` will do nothing and silently succeed. All other I/O operations, via the
 804 /// standard library or via raw Windows API calls, will fail.
 805 ///
 806 /// # Examples
 807 ///
 808 /// Using implicit synchronization:
 809 ///
 810 /// ```no_run
 811 /// use std::io::{self, Write};
 812 ///
 813 /// fn main() -> io::Result<()> {
 814 ///     io::stderr().write_all(b"hello world")?;
 815 ///
 816 ///     Ok(())
 817 /// }
 818 /// ```
 819 ///
 820 /// Using explicit synchronization:
 821 ///
 822 /// ```no_run
 823 /// use std::io::{self, Write};
 824 ///
 825 /// fn main() -> io::Result<()> {
 826 ///     let stderr = io::stderr();
 827 ///     let mut handle = stderr.lock();
 828 ///
 829 ///     handle.write_all(b"hello world")?;
 830 ///
 831 ///     Ok(())
 832 /// }
 833 /// ```
 834 #[must_use]
 835 #[stable(feature = "rust1", since = "1.0.0")]
 836 pub fn stderr() -> Stderr {
 837     // Note that unlike `stdout()` we don't use `at_exit` here to register a
 838     // destructor. Stderr is not buffered , so there's no need to run a
 839     // destructor for flushing the buffer
 840     static INSTANCE: SyncOnceCell<ReentrantMutex<RefCell<StderrRaw>>> = SyncOnceCell::new();
 841
 842     Stderr {
 843         inner: Pin::static_ref(&INSTANCE).get_or_init_pin(
 844             || unsafe { ReentrantMutex::new(RefCell::new(stderr_raw())) },
 845             |mutex| unsafe { mutex.init() },
 846         ),
 847     }
 848 }
 849
 850 impl Stderr {
 851     /// Locks this handle to the standard error stream, returning a writable
 852     /// guard.
 853     ///
 854     /// The lock is released when the returned lock goes out of scope. The
 855     /// returned guard also implements the [`Write`] trait for writing data.
 856     ///
 857     /// # Examples
 858     ///
 859     /// ```
 860     /// use std::io::{self, Write};
 861     ///
 862     /// fn foo() -> io::Result<()> {
 863     ///     let stderr = io::stderr();
 864     ///     let mut handle = stderr.lock();
 865     ///
 866     ///     handle.write_all(b"hello world")?;
 867     ///
 868     ///     Ok(())
 869     /// }
 870     /// ```
 871     #[stable(feature = "rust1", since = "1.0.0")]
 872     pub fn lock(&self) -> StderrLock<'static> {
 873         // Locks this handle with 'static lifetime. This depends on the
 874         // implementation detail that the underlying `ReentrantMutex` is
 875         // static.
 876         StderrLock { inner: self.inner.lock() }
 877     }
 878 }
 879
 880 #[stable(feature = "std_debug", since = "1.16.0")]
 881 impl fmt::Debug for Stderr {
 882     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 883         f.debug_struct("Stderr").finish_non_exhaustive()
 884     }
 885 }
 886
 887 #[stable(feature = "rust1", since = "1.0.0")]
 888 impl Write for Stderr {
 889     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 890         (&*self).write(buf)
 891     }
 892     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 893         (&*self).write_vectored(bufs)
 894     }
 895     #[inline]
 896     fn is_write_vectored(&self) -> bool {
 897         io::Write::is_write_vectored(&&*self)
 898     }
 899     fn flush(&mut self) -> io::Result<()> {
 900         (&*self).flush()
 901     }
 902     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 903         (&*self).write_all(buf)
 904     }
 905     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 906         (&*self).write_all_vectored(bufs)
 907     }
 908     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 909         (&*self).write_fmt(args)
 910     }
 911 }
 912
 913 #[stable(feature = "write_mt", since = "1.48.0")]
 914 impl Write for &Stderr {
 915     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 916         self.lock().write(buf)
 917     }
 918     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 919         self.lock().write_vectored(bufs)
 920     }
 921     #[inline]
 922     fn is_write_vectored(&self) -> bool {
 923         self.lock().is_write_vectored()
 924     }
 925     fn flush(&mut self) -> io::Result<()> {
 926         self.lock().flush()
 927     }
 928     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 929         self.lock().write_all(buf)
 930     }
 931     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 932         self.lock().write_all_vectored(bufs)
 933     }
 934     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 935         self.lock().write_fmt(args)
 936     }
 937 }
 938
 939 #[stable(feature = "rust1", since = "1.0.0")]
 940 impl Write for StderrLock<'_> {
 941     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 942         self.inner.borrow_mut().write(buf)
 943     }
 944     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 945         self.inner.borrow_mut().write_vectored(bufs)
 946     }
 947     #[inline]
 948     fn is_write_vectored(&self) -> bool {
 949         self.inner.borrow_mut().is_write_vectored()
 950     }
 951     fn flush(&mut self) -> io::Result<()> {
 952         self.inner.borrow_mut().flush()
 953     }
 954     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 955         self.inner.borrow_mut().write_all(buf)
 956     }
 957     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 958         self.inner.borrow_mut().write_all_vectored(bufs)
 959     }
 960 }
 961
 962 #[stable(feature = "std_debug", since = "1.16.0")]
 963 impl fmt::Debug for StderrLock<'_> {
 964     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 965         f.debug_struct("StderrLock").finish_non_exhaustive()
 966     }
 967 }
 968
 969 /// Sets the thread-local output capture buffer and returns the old one.
 970 #[unstable(
 971     feature = "internal_output_capture",
 972     reason = "this function is meant for use in the test crate \
 973         and may disappear in the future",
 974     issue = "none"
 975 )]
 976 #[doc(hidden)]
 977 pub fn set_output_capture(sink: Option<LocalStream>) -> Option<LocalStream> {
 978     if sink.is_none() && !OUTPUT_CAPTURE_USED.load(Ordering::Relaxed) {
 979         // OUTPUT_CAPTURE is definitely None since OUTPUT_CAPTURE_USED is false.
 980         return None;
 981     }
 982     OUTPUT_CAPTURE_USED.store(true, Ordering::Relaxed);
 983     OUTPUT_CAPTURE.with(move |slot| slot.replace(sink))
 984 }
 985
 986 /// Write `args` to the capture buffer if enabled and possible, or `global_s`
 987 /// otherwise. `label` identifies the stream in a panic message.
 988 ///
 989 /// This function is used to print error messages, so it takes extra
 990 /// care to avoid causing a panic when `local_s` is unusable.
 991 /// For instance, if the TLS key for the local stream is
 992 /// already destroyed, or if the local stream is locked by another
 993 /// thread, it will just fall back to the global stream.
 994 ///
 995 /// However, if the actual I/O causes an error, this function does panic.
 996 fn print_to<T>(args: fmt::Arguments<'_>, global_s: fn() -> T, label: &str)
 997 where
 998     T: Write,
 999 {
1000     if OUTPUT_CAPTURE_USED.load(Ordering::Relaxed)
1001         && OUTPUT_CAPTURE.try_with(|s| {
1002             // Note that we completely remove a local sink to write to in case
1003             // our printing recursively panics/prints, so the recursive
1004             // panic/print goes to the global sink instead of our local sink.
1005             s.take().map(|w| {
1006                 let _ = w.lock().unwrap_or_else(|e| e.into_inner()).write_fmt(args);
1007                 s.set(Some(w));
1008             })
1009         }) == Ok(Some(()))
1010     {
1011         // Successfully wrote to capture buffer.
1012         return;
1013     }
1014
1015     if let Err(e) = global_s().write_fmt(args) {
1016         panic!("failed printing to {label}: {e}");
1017     }
1018 }
1019
1020 #[unstable(
1021     feature = "print_internals",
1022     reason = "implementation detail which may disappear or be replaced at any time",
1023     issue = "none"
1024 )]
1025 #[doc(hidden)]
1026 #[cfg(not(test))]
1027 pub fn _print(args: fmt::Arguments<'_>) {
1028     print_to(args, stdout, "stdout");
1029 }
1030
1031 #[unstable(
1032     feature = "print_internals",
1033     reason = "implementation detail which may disappear or be replaced at any time",
1034     issue = "none"
1035 )]
1036 #[doc(hidden)]
1037 #[cfg(not(test))]
1038 pub fn _eprint(args: fmt::Arguments<'_>) {
1039     print_to(args, stderr, "stderr");
1040 }
1041
1042 #[cfg(test)]
1043 pub use realstd::io::{_eprint, _print};