1 #![cfg_attr(test, allow(unused))]
6 use crate::io::prelude::*;
8 use crate::cell::{Cell, RefCell};
10 use crate::io::{self, BufReader, IoSlice, IoSliceMut, LineWriter, Lines};
11 use crate::lazy::SyncOnceCell;
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};
18 type LocalStream = Arc<Mutex<Vec<u8>>>;
21 /// Used by the test crate to capture the output of the print macros and panics.
22 static OUTPUT_CAPTURE: Cell<Option<LocalStream>> = {
27 /// Flag to indicate OUTPUT_CAPTURE is used.
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.
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);
41 /// A handle to a raw instance of the standard input stream of this process.
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);
47 /// A handle to a raw instance of the standard output stream of this process.
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);
53 /// A handle to a raw instance of the standard output stream of this process.
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);
59 /// Constructs a new raw handle to the standard input of this process.
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.
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())
71 /// Constructs a new raw handle to the standard output stream of this process.
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.
78 /// The returned handle has no external synchronization or buffering layered on
80 #[unstable(feature = "libstd_sys_internals", issue = "none")]
81 const fn stdout_raw() -> StdoutRaw {
82 StdoutRaw(stdio::Stdout::new())
85 /// Constructs a new raw handle to the standard error stream of this process.
87 /// The returned handle does not interact with any other handles created nor
88 /// handles returned by `std::io::stderr`.
90 /// The returned handle has no external synchronization or buffering layered on
92 #[unstable(feature = "libstd_sys_internals", issue = "none")]
93 const fn stderr_raw() -> StderrRaw {
94 StderrRaw(stdio::Stderr::new())
97 impl Read for StdinRaw {
98 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
99 handle_ebadf(self.0.read(buf), 0)
102 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
103 handle_ebadf(self.0.read_vectored(bufs), 0)
107 fn is_read_vectored(&self) -> bool {
108 self.0.is_read_vectored()
111 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
112 handle_ebadf(self.0.read_to_end(buf), 0)
115 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
116 handle_ebadf(self.0.read_to_string(buf), 0)
120 impl Write for StdoutRaw {
121 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
122 handle_ebadf(self.0.write(buf), buf.len())
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)
131 fn is_write_vectored(&self) -> bool {
132 self.0.is_write_vectored()
135 fn flush(&mut self) -> io::Result<()> {
136 handle_ebadf(self.0.flush(), ())
139 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
140 handle_ebadf(self.0.write_all(buf), ())
143 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
144 handle_ebadf(self.0.write_all_vectored(bufs), ())
147 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
148 handle_ebadf(self.0.write_fmt(fmt), ())
152 impl Write for StderrRaw {
153 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
154 handle_ebadf(self.0.write(buf), buf.len())
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)
163 fn is_write_vectored(&self) -> bool {
164 self.0.is_write_vectored()
167 fn flush(&mut self) -> io::Result<()> {
168 handle_ebadf(self.0.flush(), ())
171 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
172 handle_ebadf(self.0.write_all(buf), ())
175 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
176 handle_ebadf(self.0.write_all_vectored(bufs), ())
179 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
180 handle_ebadf(self.0.write_fmt(fmt), ())
184 fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> {
186 Err(ref e) if stdio::is_ebadf(e) => Ok(default),
191 /// A handle to the standard input stream of a process.
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
198 /// This handle implements the `Read` trait, but beware that concurrent reads
199 /// of `Stdin` must be executed with care.
201 /// Created by the [`io::stdin`] method.
203 /// [`io::stdin`]: stdin
205 /// ### Note: Windows Portability Considerations
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
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.
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)?;
229 #[stable(feature = "rust1", since = "1.0.0")]
231 inner: &'static Mutex<BufReader<StdinRaw>>,
234 /// A locked reference to the [`Stdin`] handle.
236 /// This handle implements both the [`Read`] and [`BufRead`] traits, and
237 /// is constructed via the [`Stdin::lock`] method.
239 /// ### Note: Windows Portability Considerations
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
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.
254 /// use std::io::{self, BufRead};
256 /// fn main() -> io::Result<()> {
257 /// let mut buffer = String::new();
258 /// let stdin = io::stdin(); // We get `Stdin` here.
260 /// let mut handle = stdin.lock(); // We get `StdinLock` here.
261 /// handle.read_line(&mut buffer)?;
262 /// } // `StdinLock` is dropped here.
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>>,
272 /// Constructs a new handle to the standard input of the current process.
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.
278 /// ### Note: Windows Portability Considerations
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
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.
292 /// Using implicit synchronization:
297 /// fn main() -> io::Result<()> {
298 /// let mut buffer = String::new();
299 /// io::stdin().read_line(&mut buffer)?;
304 /// Using explicit synchronization:
307 /// use std::io::{self, BufRead};
309 /// fn main() -> io::Result<()> {
310 /// let mut buffer = String::new();
311 /// let stdin = io::stdin();
312 /// let mut handle = stdin.lock();
314 /// handle.read_line(&mut buffer)?;
319 #[stable(feature = "rust1", since = "1.0.0")]
320 pub fn stdin() -> Stdin {
321 static INSTANCE: SyncOnceCell<Mutex<BufReader<StdinRaw>>> = SyncOnceCell::new();
323 inner: INSTANCE.get_or_init(|| {
324 Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin_raw()))
330 /// Locks this handle to the standard input stream, returning a readable
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.
340 /// use std::io::{self, BufRead};
342 /// fn main() -> io::Result<()> {
343 /// let mut buffer = String::new();
344 /// let stdin = io::stdin();
345 /// let mut handle = stdin.lock();
347 /// handle.read_line(&mut buffer)?;
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()) }
358 /// Locks this handle and reads a line of input, appending it to the specified buffer.
360 /// For detailed semantics of this method, see the documentation on
361 /// [`BufRead::read_line`].
368 /// let mut input = String::new();
369 /// match io::stdin().read_line(&mut input) {
371 /// println!("{n} bytes read");
372 /// println!("{input}");
374 /// Err(error) => println!("error: {error}"),
378 /// You can run the example one of two ways:
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
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)
389 /// Consumes this handle and returns an iterator over input lines.
391 /// For detailed semantics of this method, see the documentation on
392 /// [`BufRead::lines`].
399 /// let lines = io::stdin().lines();
400 /// for line in lines {
401 /// println!("got a line: {}", line.unwrap());
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>> {
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()
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)
423 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
424 self.lock().read_vectored(bufs)
427 fn is_read_vectored(&self) -> bool {
428 self.lock().is_read_vectored()
430 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
431 self.lock().read_to_end(buf)
433 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
434 self.lock().read_to_string(buf)
436 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
437 self.lock().read_exact(buf)
441 // only used by platform-dependent io::copy specializations, i.e. unused on some platforms
442 #[cfg(any(target_os = "linux", target_os = "android"))]
444 pub(crate) fn as_mut_buf(&mut self) -> &mut BufReader<impl Read> {
449 #[stable(feature = "rust1", since = "1.0.0")]
450 impl Read for StdinLock<'_> {
451 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
455 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
456 self.inner.read_vectored(bufs)
460 fn is_read_vectored(&self) -> bool {
461 self.inner.is_read_vectored()
464 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
465 self.inner.read_to_end(buf)
468 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
469 self.inner.read_to_string(buf)
472 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
473 self.inner.read_exact(buf)
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()
483 fn consume(&mut self, n: usize) {
484 self.inner.consume(n)
487 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> io::Result<usize> {
488 self.inner.read_until(byte, buf)
491 fn read_line(&mut self, buf: &mut String) -> io::Result<usize> {
492 self.inner.read_line(buf)
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()
503 /// A handle to the global standard output stream of the current process.
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.
509 /// Created by the [`io::stdout`] method.
511 /// ### Note: Windows Portability Considerations
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
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.
523 /// [`lock`]: Stdout::lock
524 /// [`io::stdout`]: stdout
525 #[stable(feature = "rust1", since = "1.0.0")]
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>>>>,
533 /// A locked reference to the [`Stdout`] handle.
535 /// This handle implements the [`Write`] trait, and is constructed via
536 /// the [`Stdout::lock`] method. See its documentation for more.
538 /// ### Note: Windows Portability Considerations
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
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>>>,
555 static STDOUT: SyncOnceCell<ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>> = SyncOnceCell::new();
557 /// Constructs a new handle to the standard output of the current process.
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.
563 /// ### Note: Windows Portability Considerations
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
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.
577 /// Using implicit synchronization:
580 /// use std::io::{self, Write};
582 /// fn main() -> io::Result<()> {
583 /// io::stdout().write_all(b"hello world")?;
589 /// Using explicit synchronization:
592 /// use std::io::{self, Write};
594 /// fn main() -> io::Result<()> {
595 /// let stdout = io::stdout();
596 /// let mut handle = stdout.lock();
598 /// handle.write_all(b"hello world")?;
604 #[stable(feature = "rust1", since = "1.0.0")]
605 pub fn stdout() -> 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() },
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());
629 /// Locks this handle to the standard output stream, returning a writable
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.
638 /// use std::io::{self, Write};
640 /// fn main() -> io::Result<()> {
641 /// let mut stdout = io::stdout().lock();
643 /// stdout.write_all(b"hello world")?;
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
653 StdoutLock { inner: self.inner.lock() }
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()
664 #[stable(feature = "rust1", since = "1.0.0")]
665 impl Write for Stdout {
666 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
669 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
670 (&*self).write_vectored(bufs)
673 fn is_write_vectored(&self) -> bool {
674 io::Write::is_write_vectored(&&*self)
676 fn flush(&mut self) -> io::Result<()> {
679 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
680 (&*self).write_all(buf)
682 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
683 (&*self).write_all_vectored(bufs)
685 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
686 (&*self).write_fmt(args)
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)
695 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
696 self.lock().write_vectored(bufs)
699 fn is_write_vectored(&self) -> bool {
700 self.lock().is_write_vectored()
702 fn flush(&mut self) -> io::Result<()> {
705 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
706 self.lock().write_all(buf)
708 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
709 self.lock().write_all_vectored(bufs)
711 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
712 self.lock().write_fmt(args)
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)
721 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
722 self.inner.borrow_mut().write_vectored(bufs)
725 fn is_write_vectored(&self) -> bool {
726 self.inner.borrow_mut().is_write_vectored()
728 fn flush(&mut self) -> io::Result<()> {
729 self.inner.borrow_mut().flush()
731 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
732 self.inner.borrow_mut().write_all(buf)
734 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
735 self.inner.borrow_mut().write_all_vectored(bufs)
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()
746 /// A handle to the standard error stream of a process.
748 /// For more information, see the [`io::stderr`] method.
750 /// [`io::stderr`]: stderr
752 /// ### Note: Windows Portability Considerations
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
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")]
765 inner: Pin<&'static ReentrantMutex<RefCell<StderrRaw>>>,
768 /// A locked reference to the [`Stderr`] handle.
770 /// This handle implements the [`Write`] trait and is constructed via
771 /// the [`Stderr::lock`] method. See its documentation for more.
773 /// ### Note: Windows Portability Considerations
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
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>>,
790 /// Constructs a new handle to the standard error of the current process.
792 /// This handle is not buffered.
794 /// ### Note: Windows Portability Considerations
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
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.
808 /// Using implicit synchronization:
811 /// use std::io::{self, Write};
813 /// fn main() -> io::Result<()> {
814 /// io::stderr().write_all(b"hello world")?;
820 /// Using explicit synchronization:
823 /// use std::io::{self, Write};
825 /// fn main() -> io::Result<()> {
826 /// let stderr = io::stderr();
827 /// let mut handle = stderr.lock();
829 /// handle.write_all(b"hello world")?;
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();
843 inner: Pin::static_ref(&INSTANCE).get_or_init_pin(
844 || unsafe { ReentrantMutex::new(RefCell::new(stderr_raw())) },
845 |mutex| unsafe { mutex.init() },
851 /// Locks this handle to the standard error stream, returning a writable
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.
860 /// use std::io::{self, Write};
862 /// fn foo() -> io::Result<()> {
863 /// let stderr = io::stderr();
864 /// let mut handle = stderr.lock();
866 /// handle.write_all(b"hello world")?;
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
876 StderrLock { inner: self.inner.lock() }
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()
887 #[stable(feature = "rust1", since = "1.0.0")]
888 impl Write for Stderr {
889 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
892 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
893 (&*self).write_vectored(bufs)
896 fn is_write_vectored(&self) -> bool {
897 io::Write::is_write_vectored(&&*self)
899 fn flush(&mut self) -> io::Result<()> {
902 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
903 (&*self).write_all(buf)
905 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
906 (&*self).write_all_vectored(bufs)
908 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
909 (&*self).write_fmt(args)
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)
918 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
919 self.lock().write_vectored(bufs)
922 fn is_write_vectored(&self) -> bool {
923 self.lock().is_write_vectored()
925 fn flush(&mut self) -> io::Result<()> {
928 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
929 self.lock().write_all(buf)
931 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
932 self.lock().write_all_vectored(bufs)
934 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
935 self.lock().write_fmt(args)
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)
944 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
945 self.inner.borrow_mut().write_vectored(bufs)
948 fn is_write_vectored(&self) -> bool {
949 self.inner.borrow_mut().is_write_vectored()
951 fn flush(&mut self) -> io::Result<()> {
952 self.inner.borrow_mut().flush()
954 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
955 self.inner.borrow_mut().write_all(buf)
957 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
958 self.inner.borrow_mut().write_all_vectored(bufs)
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()
969 /// Sets the thread-local output capture buffer and returns the old one.
971 feature = "internal_output_capture",
972 reason = "this function is meant for use in the test crate \
973 and may disappear in the future",
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.
982 OUTPUT_CAPTURE_USED.store(true, Ordering::Relaxed);
983 OUTPUT_CAPTURE.with(move |slot| slot.replace(sink))
986 /// Write `args` to the capture buffer if enabled and possible, or `global_s`
987 /// otherwise. `label` identifies the stream in a panic message.
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.
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)
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.
1006 let _ = w.lock().unwrap_or_else(|e| e.into_inner()).write_fmt(args);
1011 // Successfully wrote to capture buffer.
1015 if let Err(e) = global_s().write_fmt(args) {
1016 panic!("failed printing to {label}: {e}");
1021 feature = "print_internals",
1022 reason = "implementation detail which may disappear or be replaced at any time",
1027 pub fn _print(args: fmt::Arguments<'_>) {
1028 print_to(args, stdout, "stdout");
1032 feature = "print_internals",
1033 reason = "implementation detail which may disappear or be replaced at any time",
1038 pub fn _eprint(args: fmt::Arguments<'_>) {
1039 print_to(args, stderr, "stderr");
1043 pub use realstd::io::{_eprint, _print};