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 Consideration
 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 /// # Examples
 212 ///
 213 /// ```no_run
 214 /// use std::io;
 215 ///
 216 /// fn main() -> io::Result<()> {
 217 ///     let mut buffer = String::new();
 218 ///     let mut stdin = io::stdin(); // We get `Stdin` here.
 219 ///     stdin.read_line(&mut buffer)?;
 220 ///     Ok(())
 221 /// }
 222 /// ```
 223 #[stable(feature = "rust1", since = "1.0.0")]
 224 pub struct Stdin {
 225     inner: &'static Mutex<BufReader<StdinRaw>>,
 226 }
 227
 228 /// A locked reference to the [`Stdin`] handle.
 229 ///
 230 /// This handle implements both the [`Read`] and [`BufRead`] traits, and
 231 /// is constructed via the [`Stdin::lock`] method.
 232 ///
 233 /// ### Note: Windows Portability Consideration
 234 ///
 235 /// When operating in a console, the Windows implementation of this stream does not support
 236 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
 237 /// an error.
 238 ///
 239 /// # Examples
 240 ///
 241 /// ```no_run
 242 /// use std::io::{self, BufRead};
 243 ///
 244 /// fn main() -> io::Result<()> {
 245 ///     let mut buffer = String::new();
 246 ///     let stdin = io::stdin(); // We get `Stdin` here.
 247 ///     {
 248 ///         let mut handle = stdin.lock(); // We get `StdinLock` here.
 249 ///         handle.read_line(&mut buffer)?;
 250 ///     } // `StdinLock` is dropped here.
 251 ///     Ok(())
 252 /// }
 253 /// ```
 254 #[must_use = "if unused stdin will immediately unlock"]
 255 #[stable(feature = "rust1", since = "1.0.0")]
 256 pub struct StdinLock<'a> {
 257     inner: MutexGuard<'a, BufReader<StdinRaw>>,
 258 }
 259
 260 /// Constructs a new handle to the standard input of the current process.
 261 ///
 262 /// Each handle returned is a reference to a shared global buffer whose access
 263 /// is synchronized via a mutex. If you need more explicit control over
 264 /// locking, see the [`Stdin::lock`] method.
 265 ///
 266 /// ### Note: Windows Portability Consideration
 267 /// When operating in a console, the Windows implementation of this stream does not support
 268 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
 269 /// an error.
 270 ///
 271 /// # Examples
 272 ///
 273 /// Using implicit synchronization:
 274 ///
 275 /// ```no_run
 276 /// use std::io;
 277 ///
 278 /// fn main() -> io::Result<()> {
 279 ///     let mut buffer = String::new();
 280 ///     io::stdin().read_line(&mut buffer)?;
 281 ///     Ok(())
 282 /// }
 283 /// ```
 284 ///
 285 /// Using explicit synchronization:
 286 ///
 287 /// ```no_run
 288 /// use std::io::{self, BufRead};
 289 ///
 290 /// fn main() -> io::Result<()> {
 291 ///     let mut buffer = String::new();
 292 ///     let stdin = io::stdin();
 293 ///     let mut handle = stdin.lock();
 294 ///
 295 ///     handle.read_line(&mut buffer)?;
 296 ///     Ok(())
 297 /// }
 298 /// ```
 299 #[must_use]
 300 #[stable(feature = "rust1", since = "1.0.0")]
 301 pub fn stdin() -> Stdin {
 302     static INSTANCE: SyncOnceCell<Mutex<BufReader<StdinRaw>>> = SyncOnceCell::new();
 303     Stdin {
 304         inner: INSTANCE.get_or_init(|| {
 305             Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin_raw()))
 306         }),
 307     }
 308 }
 309
 310 impl Stdin {
 311     /// Locks this handle to the standard input stream, returning a readable
 312     /// guard.
 313     ///
 314     /// The lock is released when the returned lock goes out of scope. The
 315     /// returned guard also implements the [`Read`] and [`BufRead`] traits for
 316     /// accessing the underlying data.
 317     ///
 318     /// # Examples
 319     ///
 320     /// ```no_run
 321     /// use std::io::{self, BufRead};
 322     ///
 323     /// fn main() -> io::Result<()> {
 324     ///     let mut buffer = String::new();
 325     ///     let stdin = io::stdin();
 326     ///     let mut handle = stdin.lock();
 327     ///
 328     ///     handle.read_line(&mut buffer)?;
 329     ///     Ok(())
 330     /// }
 331     /// ```
 332     #[stable(feature = "rust1", since = "1.0.0")]
 333     pub fn lock(&self) -> StdinLock<'static> {
 334         // Locks this handle with 'static lifetime. This depends on the
 335         // implementation detail that the underlying `Mutex` is static.
 336         StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) }
 337     }
 338
 339     /// Locks this handle and reads a line of input, appending it to the specified buffer.
 340     ///
 341     /// For detailed semantics of this method, see the documentation on
 342     /// [`BufRead::read_line`].
 343     ///
 344     /// # Examples
 345     ///
 346     /// ```no_run
 347     /// use std::io;
 348     ///
 349     /// let mut input = String::new();
 350     /// match io::stdin().read_line(&mut input) {
 351     ///     Ok(n) => {
 352     ///         println!("{} bytes read", n);
 353     ///         println!("{}", input);
 354     ///     }
 355     ///     Err(error) => println!("error: {}", error),
 356     /// }
 357     /// ```
 358     ///
 359     /// You can run the example one of two ways:
 360     ///
 361     /// - Pipe some text to it, e.g., `printf foo | path/to/executable`
 362     /// - Give it text interactively by running the executable directly,
 363     ///   in which case it will wait for the Enter key to be pressed before
 364     ///   continuing
 365     #[stable(feature = "rust1", since = "1.0.0")]
 366     pub fn read_line(&self, buf: &mut String) -> io::Result<usize> {
 367         self.lock().read_line(buf)
 368     }
 369
 370     /// Consumes this handle and returns an iterator over input lines.
 371     ///
 372     /// For detailed semantics of this method, see the documentation on
 373     /// [`BufRead::lines`].
 374     ///
 375     /// # Examples
 376     ///
 377     /// ```no_run
 378     /// #![feature(stdin_forwarders)]
 379     /// use std::io;
 380     ///
 381     /// let lines = io::stdin().lines();
 382     /// for line in lines {
 383     ///     println!("got a line: {}", line.unwrap());
 384     /// }
 385     /// ```
 386     #[must_use = "`self` will be dropped if the result is not used"]
 387     #[unstable(feature = "stdin_forwarders", issue = "87096")]
 388     pub fn lines(self) -> Lines<StdinLock<'static>> {
 389         self.lock().lines()
 390     }
 391 }
 392
 393 #[stable(feature = "std_debug", since = "1.16.0")]
 394 impl fmt::Debug for Stdin {
 395     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 396         f.debug_struct("Stdin").finish_non_exhaustive()
 397     }
 398 }
 399
 400 #[stable(feature = "rust1", since = "1.0.0")]
 401 impl Read for Stdin {
 402     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 403         self.lock().read(buf)
 404     }
 405     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 406         self.lock().read_vectored(bufs)
 407     }
 408     #[inline]
 409     fn is_read_vectored(&self) -> bool {
 410         self.lock().is_read_vectored()
 411     }
 412     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 413         self.lock().read_to_end(buf)
 414     }
 415     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 416         self.lock().read_to_string(buf)
 417     }
 418     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 419         self.lock().read_exact(buf)
 420     }
 421 }
 422
 423 // only used by platform-dependent io::copy specializations, i.e. unused on some platforms
 424 #[cfg(any(target_os = "linux", target_os = "android"))]
 425 impl StdinLock<'_> {
 426     pub(crate) fn as_mut_buf(&mut self) -> &mut BufReader<impl Read> {
 427         &mut self.inner
 428     }
 429 }
 430
 431 #[stable(feature = "rust1", since = "1.0.0")]
 432 impl Read for StdinLock<'_> {
 433     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 434         self.inner.read(buf)
 435     }
 436
 437     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 438         self.inner.read_vectored(bufs)
 439     }
 440
 441     #[inline]
 442     fn is_read_vectored(&self) -> bool {
 443         self.inner.is_read_vectored()
 444     }
 445
 446     fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
 447         self.inner.read_to_end(buf)
 448     }
 449
 450     fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
 451         self.inner.read_to_string(buf)
 452     }
 453
 454     fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
 455         self.inner.read_exact(buf)
 456     }
 457 }
 458
 459 #[stable(feature = "rust1", since = "1.0.0")]
 460 impl BufRead for StdinLock<'_> {
 461     fn fill_buf(&mut self) -> io::Result<&[u8]> {
 462         self.inner.fill_buf()
 463     }
 464
 465     fn consume(&mut self, n: usize) {
 466         self.inner.consume(n)
 467     }
 468
 469     fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> io::Result<usize> {
 470         self.inner.read_until(byte, buf)
 471     }
 472
 473     fn read_line(&mut self, buf: &mut String) -> io::Result<usize> {
 474         self.inner.read_line(buf)
 475     }
 476 }
 477
 478 #[stable(feature = "std_debug", since = "1.16.0")]
 479 impl fmt::Debug for StdinLock<'_> {
 480     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 481         f.debug_struct("StdinLock").finish_non_exhaustive()
 482     }
 483 }
 484
 485 /// A handle to the global standard output stream of the current process.
 486 ///
 487 /// Each handle shares a global buffer of data to be written to the standard
 488 /// output stream. Access is also synchronized via a lock and explicit control
 489 /// over locking is available via the [`lock`] method.
 490 ///
 491 /// Created by the [`io::stdout`] method.
 492 ///
 493 /// ### Note: Windows Portability Consideration
 494 /// When operating in a console, the Windows implementation of this stream does not support
 495 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 496 /// an error.
 497 ///
 498 /// [`lock`]: Stdout::lock
 499 /// [`io::stdout`]: stdout
 500 #[stable(feature = "rust1", since = "1.0.0")]
 501 pub struct Stdout {
 502     // FIXME: this should be LineWriter or BufWriter depending on the state of
 503     //        stdout (tty or not). Note that if this is not line buffered it
 504     //        should also flush-on-panic or some form of flush-on-abort.
 505     inner: Pin<&'static ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>>,
 506 }
 507
 508 /// A locked reference to the [`Stdout`] handle.
 509 ///
 510 /// This handle implements the [`Write`] trait, and is constructed via
 511 /// the [`Stdout::lock`] method. See its documentation for more.
 512 ///
 513 /// ### Note: Windows Portability Consideration
 514 /// When operating in a console, the Windows implementation of this stream does not support
 515 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 516 /// an error.
 517 #[must_use = "if unused stdout will immediately unlock"]
 518 #[stable(feature = "rust1", since = "1.0.0")]
 519 pub struct StdoutLock<'a> {
 520     inner: ReentrantMutexGuard<'a, RefCell<LineWriter<StdoutRaw>>>,
 521 }
 522
 523 static STDOUT: SyncOnceCell<ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>> = SyncOnceCell::new();
 524
 525 /// Constructs a new handle to the standard output of the current process.
 526 ///
 527 /// Each handle returned is a reference to a shared global buffer whose access
 528 /// is synchronized via a mutex. If you need more explicit control over
 529 /// locking, see the [`Stdout::lock`] method.
 530 ///
 531 /// ### Note: Windows Portability Consideration
 532 /// When operating in a console, the Windows implementation of this stream does not support
 533 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 534 /// an error.
 535 ///
 536 /// # Examples
 537 ///
 538 /// Using implicit synchronization:
 539 ///
 540 /// ```no_run
 541 /// use std::io::{self, Write};
 542 ///
 543 /// fn main() -> io::Result<()> {
 544 ///     io::stdout().write_all(b"hello world")?;
 545 ///
 546 ///     Ok(())
 547 /// }
 548 /// ```
 549 ///
 550 /// Using explicit synchronization:
 551 ///
 552 /// ```no_run
 553 /// use std::io::{self, Write};
 554 ///
 555 /// fn main() -> io::Result<()> {
 556 ///     let stdout = io::stdout();
 557 ///     let mut handle = stdout.lock();
 558 ///
 559 ///     handle.write_all(b"hello world")?;
 560 ///
 561 ///     Ok(())
 562 /// }
 563 /// ```
 564 #[must_use]
 565 #[stable(feature = "rust1", since = "1.0.0")]
 566 pub fn stdout() -> Stdout {
 567     Stdout {
 568         inner: Pin::static_ref(&STDOUT).get_or_init_pin(
 569             || unsafe { ReentrantMutex::new(RefCell::new(LineWriter::new(stdout_raw()))) },
 570             |mutex| unsafe { mutex.init() },
 571         ),
 572     }
 573 }
 574
 575 pub fn cleanup() {
 576     if let Some(instance) = STDOUT.get() {
 577         // Flush the data and disable buffering during shutdown
 578         // by replacing the line writer by one with zero
 579         // buffering capacity.
 580         // We use try_lock() instead of lock(), because someone
 581         // might have leaked a StdoutLock, which would
 582         // otherwise cause a deadlock here.
 583         if let Some(lock) = Pin::static_ref(instance).try_lock() {
 584             *lock.borrow_mut() = LineWriter::with_capacity(0, stdout_raw());
 585         }
 586     }
 587 }
 588
 589 impl Stdout {
 590     /// Locks this handle to the standard output stream, returning a writable
 591     /// guard.
 592     ///
 593     /// The lock is released when the returned lock goes out of scope. The
 594     /// returned guard also implements the `Write` trait for writing data.
 595     ///
 596     /// # Examples
 597     ///
 598     /// ```no_run
 599     /// use std::io::{self, Write};
 600     ///
 601     /// fn main() -> io::Result<()> {
 602     ///     let mut stdout = io::stdout().lock();
 603     ///
 604     ///     stdout.write_all(b"hello world")?;
 605     ///
 606     ///     Ok(())
 607     /// }
 608     /// ```
 609     #[stable(feature = "rust1", since = "1.0.0")]
 610     pub fn lock(&self) -> StdoutLock<'static> {
 611         // Locks this handle with 'static lifetime. This depends on the
 612         // implementation detail that the underlying `ReentrantMutex` is
 613         // static.
 614         StdoutLock { inner: self.inner.lock() }
 615     }
 616 }
 617
 618 #[stable(feature = "std_debug", since = "1.16.0")]
 619 impl fmt::Debug for Stdout {
 620     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 621         f.debug_struct("Stdout").finish_non_exhaustive()
 622     }
 623 }
 624
 625 #[stable(feature = "rust1", since = "1.0.0")]
 626 impl Write for Stdout {
 627     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 628         (&*self).write(buf)
 629     }
 630     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 631         (&*self).write_vectored(bufs)
 632     }
 633     #[inline]
 634     fn is_write_vectored(&self) -> bool {
 635         io::Write::is_write_vectored(&&*self)
 636     }
 637     fn flush(&mut self) -> io::Result<()> {
 638         (&*self).flush()
 639     }
 640     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 641         (&*self).write_all(buf)
 642     }
 643     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 644         (&*self).write_all_vectored(bufs)
 645     }
 646     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 647         (&*self).write_fmt(args)
 648     }
 649 }
 650
 651 #[stable(feature = "write_mt", since = "1.48.0")]
 652 impl Write for &Stdout {
 653     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 654         self.lock().write(buf)
 655     }
 656     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 657         self.lock().write_vectored(bufs)
 658     }
 659     #[inline]
 660     fn is_write_vectored(&self) -> bool {
 661         self.lock().is_write_vectored()
 662     }
 663     fn flush(&mut self) -> io::Result<()> {
 664         self.lock().flush()
 665     }
 666     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 667         self.lock().write_all(buf)
 668     }
 669     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 670         self.lock().write_all_vectored(bufs)
 671     }
 672     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 673         self.lock().write_fmt(args)
 674     }
 675 }
 676
 677 #[stable(feature = "rust1", since = "1.0.0")]
 678 impl Write for StdoutLock<'_> {
 679     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 680         self.inner.borrow_mut().write(buf)
 681     }
 682     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 683         self.inner.borrow_mut().write_vectored(bufs)
 684     }
 685     #[inline]
 686     fn is_write_vectored(&self) -> bool {
 687         self.inner.borrow_mut().is_write_vectored()
 688     }
 689     fn flush(&mut self) -> io::Result<()> {
 690         self.inner.borrow_mut().flush()
 691     }
 692     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 693         self.inner.borrow_mut().write_all(buf)
 694     }
 695     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 696         self.inner.borrow_mut().write_all_vectored(bufs)
 697     }
 698 }
 699
 700 #[stable(feature = "std_debug", since = "1.16.0")]
 701 impl fmt::Debug for StdoutLock<'_> {
 702     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 703         f.debug_struct("StdoutLock").finish_non_exhaustive()
 704     }
 705 }
 706
 707 /// A handle to the standard error stream of a process.
 708 ///
 709 /// For more information, see the [`io::stderr`] method.
 710 ///
 711 /// [`io::stderr`]: stderr
 712 ///
 713 /// ### Note: Windows Portability Consideration
 714 /// When operating in a console, the Windows implementation of this stream does not support
 715 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 716 /// an error.
 717 #[stable(feature = "rust1", since = "1.0.0")]
 718 pub struct Stderr {
 719     inner: Pin<&'static ReentrantMutex<RefCell<StderrRaw>>>,
 720 }
 721
 722 /// A locked reference to the [`Stderr`] handle.
 723 ///
 724 /// This handle implements the [`Write`] trait and is constructed via
 725 /// the [`Stderr::lock`] method. See its documentation for more.
 726 ///
 727 /// ### Note: Windows Portability Consideration
 728 /// When operating in a console, the Windows implementation of this stream does not support
 729 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 730 /// an error.
 731 #[must_use = "if unused stderr will immediately unlock"]
 732 #[stable(feature = "rust1", since = "1.0.0")]
 733 pub struct StderrLock<'a> {
 734     inner: ReentrantMutexGuard<'a, RefCell<StderrRaw>>,
 735 }
 736
 737 /// Constructs a new handle to the standard error of the current process.
 738 ///
 739 /// This handle is not buffered.
 740 ///
 741 /// ### Note: Windows Portability Consideration
 742 /// When operating in a console, the Windows implementation of this stream does not support
 743 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
 744 /// an error.
 745 ///
 746 /// # Examples
 747 ///
 748 /// Using implicit synchronization:
 749 ///
 750 /// ```no_run
 751 /// use std::io::{self, Write};
 752 ///
 753 /// fn main() -> io::Result<()> {
 754 ///     io::stderr().write_all(b"hello world")?;
 755 ///
 756 ///     Ok(())
 757 /// }
 758 /// ```
 759 ///
 760 /// Using explicit synchronization:
 761 ///
 762 /// ```no_run
 763 /// use std::io::{self, Write};
 764 ///
 765 /// fn main() -> io::Result<()> {
 766 ///     let stderr = io::stderr();
 767 ///     let mut handle = stderr.lock();
 768 ///
 769 ///     handle.write_all(b"hello world")?;
 770 ///
 771 ///     Ok(())
 772 /// }
 773 /// ```
 774 #[must_use]
 775 #[stable(feature = "rust1", since = "1.0.0")]
 776 pub fn stderr() -> Stderr {
 777     // Note that unlike `stdout()` we don't use `at_exit` here to register a
 778     // destructor. Stderr is not buffered , so there's no need to run a
 779     // destructor for flushing the buffer
 780     static INSTANCE: SyncOnceCell<ReentrantMutex<RefCell<StderrRaw>>> = SyncOnceCell::new();
 781
 782     Stderr {
 783         inner: Pin::static_ref(&INSTANCE).get_or_init_pin(
 784             || unsafe { ReentrantMutex::new(RefCell::new(stderr_raw())) },
 785             |mutex| unsafe { mutex.init() },
 786         ),
 787     }
 788 }
 789
 790 impl Stderr {
 791     /// Locks this handle to the standard error stream, returning a writable
 792     /// guard.
 793     ///
 794     /// The lock is released when the returned lock goes out of scope. The
 795     /// returned guard also implements the [`Write`] trait for writing data.
 796     ///
 797     /// # Examples
 798     ///
 799     /// ```
 800     /// use std::io::{self, Write};
 801     ///
 802     /// fn foo() -> io::Result<()> {
 803     ///     let stderr = io::stderr();
 804     ///     let mut handle = stderr.lock();
 805     ///
 806     ///     handle.write_all(b"hello world")?;
 807     ///
 808     ///     Ok(())
 809     /// }
 810     /// ```
 811     #[stable(feature = "rust1", since = "1.0.0")]
 812     pub fn lock(&self) -> StderrLock<'static> {
 813         // Locks this handle with 'static lifetime. This depends on the
 814         // implementation detail that the underlying `ReentrantMutex` is
 815         // static.
 816         StderrLock { inner: self.inner.lock() }
 817     }
 818 }
 819
 820 #[stable(feature = "std_debug", since = "1.16.0")]
 821 impl fmt::Debug for Stderr {
 822     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 823         f.debug_struct("Stderr").finish_non_exhaustive()
 824     }
 825 }
 826
 827 #[stable(feature = "rust1", since = "1.0.0")]
 828 impl Write for Stderr {
 829     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 830         (&*self).write(buf)
 831     }
 832     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 833         (&*self).write_vectored(bufs)
 834     }
 835     #[inline]
 836     fn is_write_vectored(&self) -> bool {
 837         io::Write::is_write_vectored(&&*self)
 838     }
 839     fn flush(&mut self) -> io::Result<()> {
 840         (&*self).flush()
 841     }
 842     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 843         (&*self).write_all(buf)
 844     }
 845     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 846         (&*self).write_all_vectored(bufs)
 847     }
 848     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 849         (&*self).write_fmt(args)
 850     }
 851 }
 852
 853 #[stable(feature = "write_mt", since = "1.48.0")]
 854 impl Write for &Stderr {
 855     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 856         self.lock().write(buf)
 857     }
 858     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 859         self.lock().write_vectored(bufs)
 860     }
 861     #[inline]
 862     fn is_write_vectored(&self) -> bool {
 863         self.lock().is_write_vectored()
 864     }
 865     fn flush(&mut self) -> io::Result<()> {
 866         self.lock().flush()
 867     }
 868     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 869         self.lock().write_all(buf)
 870     }
 871     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 872         self.lock().write_all_vectored(bufs)
 873     }
 874     fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
 875         self.lock().write_fmt(args)
 876     }
 877 }
 878
 879 #[stable(feature = "rust1", since = "1.0.0")]
 880 impl Write for StderrLock<'_> {
 881     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
 882         self.inner.borrow_mut().write(buf)
 883     }
 884     fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 885         self.inner.borrow_mut().write_vectored(bufs)
 886     }
 887     #[inline]
 888     fn is_write_vectored(&self) -> bool {
 889         self.inner.borrow_mut().is_write_vectored()
 890     }
 891     fn flush(&mut self) -> io::Result<()> {
 892         self.inner.borrow_mut().flush()
 893     }
 894     fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
 895         self.inner.borrow_mut().write_all(buf)
 896     }
 897     fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
 898         self.inner.borrow_mut().write_all_vectored(bufs)
 899     }
 900 }
 901
 902 #[stable(feature = "std_debug", since = "1.16.0")]
 903 impl fmt::Debug for StderrLock<'_> {
 904     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 905         f.debug_struct("StderrLock").finish_non_exhaustive()
 906     }
 907 }
 908
 909 /// Sets the thread-local output capture buffer and returns the old one.
 910 #[unstable(
 911     feature = "internal_output_capture",
 912     reason = "this function is meant for use in the test crate \
 913         and may disappear in the future",
 914     issue = "none"
 915 )]
 916 #[doc(hidden)]
 917 pub fn set_output_capture(sink: Option<LocalStream>) -> Option<LocalStream> {
 918     if sink.is_none() && !OUTPUT_CAPTURE_USED.load(Ordering::Relaxed) {
 919         // OUTPUT_CAPTURE is definitely None since OUTPUT_CAPTURE_USED is false.
 920         return None;
 921     }
 922     OUTPUT_CAPTURE_USED.store(true, Ordering::Relaxed);
 923     OUTPUT_CAPTURE.with(move |slot| slot.replace(sink))
 924 }
 925
 926 /// Write `args` to the capture buffer if enabled and possible, or `global_s`
 927 /// otherwise. `label` identifies the stream in a panic message.
 928 ///
 929 /// This function is used to print error messages, so it takes extra
 930 /// care to avoid causing a panic when `local_s` is unusable.
 931 /// For instance, if the TLS key for the local stream is
 932 /// already destroyed, or if the local stream is locked by another
 933 /// thread, it will just fall back to the global stream.
 934 ///
 935 /// However, if the actual I/O causes an error, this function does panic.
 936 fn print_to<T>(args: fmt::Arguments<'_>, global_s: fn() -> T, label: &str)
 937 where
 938     T: Write,
 939 {
 940     if OUTPUT_CAPTURE_USED.load(Ordering::Relaxed)
 941         && OUTPUT_CAPTURE.try_with(|s| {
 942             // Note that we completely remove a local sink to write to in case
 943             // our printing recursively panics/prints, so the recursive
 944             // panic/print goes to the global sink instead of our local sink.
 945             s.take().map(|w| {
 946                 let _ = w.lock().unwrap_or_else(|e| e.into_inner()).write_fmt(args);
 947                 s.set(Some(w));
 948             })
 949         }) == Ok(Some(()))
 950     {
 951         // Successfully wrote to capture buffer.
 952         return;
 953     }
 954
 955     if let Err(e) = global_s().write_fmt(args) {
 956         panic!("failed printing to {}: {}", label, e);
 957     }
 958 }
 959
 960 #[unstable(
 961     feature = "print_internals",
 962     reason = "implementation detail which may disappear or be replaced at any time",
 963     issue = "none"
 964 )]
 965 #[doc(hidden)]
 966 #[cfg(not(test))]
 967 pub fn _print(args: fmt::Arguments<'_>) {
 968     print_to(args, stdout, "stdout");
 969 }
 970
 971 #[unstable(
 972     feature = "print_internals",
 973     reason = "implementation detail which may disappear or be replaced at any time",
 974     issue = "none"
 975 )]
 976 #[doc(hidden)]
 977 #[cfg(not(test))]
 978 pub fn _eprint(args: fmt::Arguments<'_>) {
 979     print_to(args, stderr, "stderr");
 980 }
 981
 982 #[cfg(test)]
 983 pub use realstd::io::{_eprint, _print};