1 #![cfg_attr(test, allow(unused))]
6 use crate::io::prelude::*;
8 use crate::cell::{Cell, RefCell};
10 use crate::io::{self, BufReader, Initializer, IoSlice, IoSliceMut, LineWriter};
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()
112 unsafe fn initializer(&self) -> Initializer {
116 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
117 handle_ebadf(self.0.read_to_end(buf), 0)
120 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
121 handle_ebadf(self.0.read_to_string(buf), 0)
125 impl Write for StdoutRaw {
126 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
127 handle_ebadf(self.0.write(buf), buf.len())
130 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
131 let total = bufs.iter().map(|b| b.len()).sum();
132 handle_ebadf(self.0.write_vectored(bufs), total)
136 fn is_write_vectored(&self) -> bool {
137 self.0.is_write_vectored()
140 fn flush(&mut self) -> io::Result<()> {
141 handle_ebadf(self.0.flush(), ())
144 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
145 handle_ebadf(self.0.write_all(buf), ())
148 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
149 handle_ebadf(self.0.write_all_vectored(bufs), ())
152 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
153 handle_ebadf(self.0.write_fmt(fmt), ())
157 impl Write for StderrRaw {
158 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
159 handle_ebadf(self.0.write(buf), buf.len())
162 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
163 let total = bufs.iter().map(|b| b.len()).sum();
164 handle_ebadf(self.0.write_vectored(bufs), total)
168 fn is_write_vectored(&self) -> bool {
169 self.0.is_write_vectored()
172 fn flush(&mut self) -> io::Result<()> {
173 handle_ebadf(self.0.flush(), ())
176 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
177 handle_ebadf(self.0.write_all(buf), ())
180 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
181 handle_ebadf(self.0.write_all_vectored(bufs), ())
184 fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> {
185 handle_ebadf(self.0.write_fmt(fmt), ())
189 fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> {
191 Err(ref e) if stdio::is_ebadf(e) => Ok(default),
196 /// A handle to the standard input stream of a process.
198 /// Each handle is a shared reference to a global buffer of input data to this
199 /// process. A handle can be `lock`'d to gain full access to [`BufRead`] methods
200 /// (e.g., `.lines()`). Reads to this handle are otherwise locked with respect
203 /// This handle implements the `Read` trait, but beware that concurrent reads
204 /// of `Stdin` must be executed with care.
206 /// Created by the [`io::stdin`] method.
208 /// [`io::stdin`]: stdin
210 /// ### Note: Windows Portability Consideration
212 /// When operating in a console, the Windows implementation of this stream does not support
213 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
219 /// use std::io::{self, Read};
221 /// fn main() -> io::Result<()> {
222 /// let mut buffer = String::new();
223 /// let mut stdin = io::stdin(); // We get `Stdin` here.
224 /// stdin.read_to_string(&mut buffer)?;
228 #[stable(feature = "rust1", since = "1.0.0")]
230 inner: &'static Mutex<BufReader<StdinRaw>>,
233 /// A locked reference to the [`Stdin`] handle.
235 /// This handle implements both the [`Read`] and [`BufRead`] traits, and
236 /// is constructed via the [`Stdin::lock`] method.
238 /// ### Note: Windows Portability Consideration
240 /// When operating in a console, the Windows implementation of this stream does not support
241 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
247 /// use std::io::{self, Read};
249 /// fn main() -> io::Result<()> {
250 /// let mut buffer = String::new();
251 /// let stdin = io::stdin(); // We get `Stdin` here.
253 /// let mut handle = stdin.lock(); // We get `StdinLock` here.
254 /// handle.read_to_string(&mut buffer)?;
255 /// } // `StdinLock` is dropped here.
259 #[stable(feature = "rust1", since = "1.0.0")]
260 pub struct StdinLock<'a> {
261 inner: MutexGuard<'a, BufReader<StdinRaw>>,
264 /// Constructs a new handle to the standard input of the current process.
266 /// Each handle returned is a reference to a shared global buffer whose access
267 /// is synchronized via a mutex. If you need more explicit control over
268 /// locking, see the [`Stdin::lock`] method.
270 /// ### Note: Windows Portability Consideration
271 /// When operating in a console, the Windows implementation of this stream does not support
272 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
277 /// Using implicit synchronization:
280 /// use std::io::{self, Read};
282 /// fn main() -> io::Result<()> {
283 /// let mut buffer = String::new();
284 /// io::stdin().read_to_string(&mut buffer)?;
289 /// Using explicit synchronization:
292 /// use std::io::{self, Read};
294 /// fn main() -> io::Result<()> {
295 /// let mut buffer = String::new();
296 /// let stdin = io::stdin();
297 /// let mut handle = stdin.lock();
299 /// handle.read_to_string(&mut buffer)?;
303 #[stable(feature = "rust1", since = "1.0.0")]
304 pub fn stdin() -> Stdin {
305 static INSTANCE: SyncOnceCell<Mutex<BufReader<StdinRaw>>> = SyncOnceCell::new();
307 inner: INSTANCE.get_or_init(|| {
308 Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin_raw()))
313 /// Constructs a new locked handle to the standard input of the current
316 /// Each handle returned is a guard granting locked access to a shared
317 /// global buffer whose access is synchronized via a mutex. If you need
318 /// more explicit control over locking, for example, in a multi-threaded
319 /// program, use the [`io::stdin`] function to obtain an unlocked handle,
320 /// along with the [`Stdin::lock`] method.
322 /// The lock is released when the returned guard goes out of scope. The
323 /// returned guard also implements the [`Read`] and [`BufRead`] traits for
324 /// accessing the underlying data.
326 /// **Note**: The mutex locked by this handle is not reentrant. Even in a
327 /// single-threaded program, calling other code that accesses [`Stdin`]
328 /// could cause a deadlock or panic, if this locked handle is held across
331 /// ### Note: Windows Portability Consideration
332 /// When operating in a console, the Windows implementation of this stream does not support
333 /// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return
339 /// #![feature(stdio_locked)]
340 /// use std::io::{self, Read};
342 /// fn main() -> io::Result<()> {
343 /// let mut buffer = String::new();
344 /// let mut handle = io::stdin_locked();
346 /// handle.read_to_string(&mut buffer)?;
350 #[unstable(feature = "stdio_locked", issue = "none")]
351 pub fn stdin_locked() -> StdinLock<'static> {
352 stdin().into_locked()
356 /// Locks this handle to the standard input stream, returning a readable
359 /// The lock is released when the returned lock goes out of scope. The
360 /// returned guard also implements the [`Read`] and [`BufRead`] traits for
361 /// accessing the underlying data.
366 /// use std::io::{self, Read};
368 /// fn main() -> io::Result<()> {
369 /// let mut buffer = String::new();
370 /// let stdin = io::stdin();
371 /// let mut handle = stdin.lock();
373 /// handle.read_to_string(&mut buffer)?;
377 #[stable(feature = "rust1", since = "1.0.0")]
378 pub fn lock(&self) -> StdinLock<'_> {
382 /// Locks this handle and reads a line of input, appending it to the specified buffer.
384 /// For detailed semantics of this method, see the documentation on
385 /// [`BufRead::read_line`].
392 /// let mut input = String::new();
393 /// match io::stdin().read_line(&mut input) {
395 /// println!("{} bytes read", n);
396 /// println!("{}", input);
398 /// Err(error) => println!("error: {}", error),
402 /// You can run the example one of two ways:
404 /// - Pipe some text to it, e.g., `printf foo | path/to/executable`
405 /// - Give it text interactively by running the executable directly,
406 /// in which case it will wait for the Enter key to be pressed before
408 #[stable(feature = "rust1", since = "1.0.0")]
409 pub fn read_line(&self, buf: &mut String) -> io::Result<usize> {
410 self.lock().read_line(buf)
413 // Locks this handle with any lifetime. This depends on the
414 // implementation detail that the underlying `Mutex` is static.
415 fn lock_any<'a>(&self) -> StdinLock<'a> {
416 StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) }
419 /// Consumes this handle to the standard input stream, locking the
420 /// shared global buffer associated with the stream and returning a
423 /// The lock is released when the returned guard goes out of scope. The
424 /// returned guard also implements the [`Read`] and [`BufRead`] traits
425 /// for accessing the underlying data.
427 /// It is often simpler to directly get a locked handle using the
428 /// [`stdin_locked`] function instead, unless nearby code also needs to
429 /// use an unlocked handle.
434 /// #![feature(stdio_locked)]
435 /// use std::io::{self, Read};
437 /// fn main() -> io::Result<()> {
438 /// let mut buffer = String::new();
439 /// let mut handle = io::stdin().into_locked();
441 /// handle.read_to_string(&mut buffer)?;
445 #[unstable(feature = "stdio_locked", issue = "none")]
446 pub fn into_locked(self) -> StdinLock<'static> {
451 #[stable(feature = "std_debug", since = "1.16.0")]
452 impl fmt::Debug for Stdin {
453 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
454 f.debug_struct("Stdin").finish_non_exhaustive()
458 #[stable(feature = "rust1", since = "1.0.0")]
459 impl Read for Stdin {
460 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
461 self.lock().read(buf)
463 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
464 self.lock().read_vectored(bufs)
467 fn is_read_vectored(&self) -> bool {
468 self.lock().is_read_vectored()
471 unsafe fn initializer(&self) -> Initializer {
474 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
475 self.lock().read_to_end(buf)
477 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
478 self.lock().read_to_string(buf)
480 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
481 self.lock().read_exact(buf)
485 // only used by platform-dependent io::copy specializations, i.e. unused on some platforms
486 #[cfg(any(target_os = "linux", target_os = "android"))]
488 pub(crate) fn as_mut_buf(&mut self) -> &mut BufReader<impl Read> {
493 #[stable(feature = "rust1", since = "1.0.0")]
494 impl Read for StdinLock<'_> {
495 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
499 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
500 self.inner.read_vectored(bufs)
504 fn is_read_vectored(&self) -> bool {
505 self.inner.is_read_vectored()
509 unsafe fn initializer(&self) -> Initializer {
513 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
514 self.inner.read_to_end(buf)
517 fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
518 self.inner.read_to_string(buf)
521 fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
522 self.inner.read_exact(buf)
526 #[stable(feature = "rust1", since = "1.0.0")]
527 impl BufRead for StdinLock<'_> {
528 fn fill_buf(&mut self) -> io::Result<&[u8]> {
529 self.inner.fill_buf()
532 fn consume(&mut self, n: usize) {
533 self.inner.consume(n)
536 fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> io::Result<usize> {
537 self.inner.read_until(byte, buf)
540 fn read_line(&mut self, buf: &mut String) -> io::Result<usize> {
541 self.inner.read_line(buf)
545 #[stable(feature = "std_debug", since = "1.16.0")]
546 impl fmt::Debug for StdinLock<'_> {
547 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
548 f.debug_struct("StdinLock").finish_non_exhaustive()
552 /// A handle to the global standard output stream of the current process.
554 /// Each handle shares a global buffer of data to be written to the standard
555 /// output stream. Access is also synchronized via a lock and explicit control
556 /// over locking is available via the [`lock`] method.
558 /// Created by the [`io::stdout`] method.
560 /// ### Note: Windows Portability Consideration
561 /// When operating in a console, the Windows implementation of this stream does not support
562 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
565 /// [`lock`]: Stdout::lock
566 /// [`io::stdout`]: stdout
567 #[stable(feature = "rust1", since = "1.0.0")]
569 // FIXME: this should be LineWriter or BufWriter depending on the state of
570 // stdout (tty or not). Note that if this is not line buffered it
571 // should also flush-on-panic or some form of flush-on-abort.
572 inner: Pin<&'static ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>>,
575 /// A locked reference to the [`Stdout`] handle.
577 /// This handle implements the [`Write`] trait, and is constructed via
578 /// the [`Stdout::lock`] method. See its documentation for more.
580 /// ### Note: Windows Portability Consideration
581 /// When operating in a console, the Windows implementation of this stream does not support
582 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
584 #[stable(feature = "rust1", since = "1.0.0")]
585 pub struct StdoutLock<'a> {
586 inner: ReentrantMutexGuard<'a, RefCell<LineWriter<StdoutRaw>>>,
589 static STDOUT: SyncOnceCell<ReentrantMutex<RefCell<LineWriter<StdoutRaw>>>> = SyncOnceCell::new();
591 /// Constructs a new handle to the standard output of the current process.
593 /// Each handle returned is a reference to a shared global buffer whose access
594 /// is synchronized via a mutex. If you need more explicit control over
595 /// locking, see the [`Stdout::lock`] method.
597 /// ### Note: Windows Portability Consideration
598 /// When operating in a console, the Windows implementation of this stream does not support
599 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
604 /// Using implicit synchronization:
607 /// use std::io::{self, Write};
609 /// fn main() -> io::Result<()> {
610 /// io::stdout().write_all(b"hello world")?;
616 /// Using explicit synchronization:
619 /// use std::io::{self, Write};
621 /// fn main() -> io::Result<()> {
622 /// let stdout = io::stdout();
623 /// let mut handle = stdout.lock();
625 /// handle.write_all(b"hello world")?;
630 #[stable(feature = "rust1", since = "1.0.0")]
631 pub fn stdout() -> Stdout {
633 inner: Pin::static_ref(&STDOUT).get_or_init_pin(
634 || unsafe { ReentrantMutex::new(RefCell::new(LineWriter::new(stdout_raw()))) },
635 |mutex| unsafe { mutex.init() },
640 /// Constructs a new locked handle to the standard output of the current
643 /// Each handle returned is a guard granting locked access to a shared
644 /// global buffer whose access is synchronized via a mutex. If you need
645 /// more explicit control over locking, for example, in a multi-threaded
646 /// program, use the [`io::stdout`] function to obtain an unlocked handle,
647 /// along with the [`Stdout::lock`] method.
649 /// The lock is released when the returned guard goes out of scope. The
650 /// returned guard also implements the [`Write`] trait for writing data.
652 /// ### Note: Windows Portability Consideration
653 /// When operating in a console, the Windows implementation of this stream does not support
654 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
660 /// #![feature(stdio_locked)]
661 /// use std::io::{self, Write};
663 /// fn main() -> io::Result<()> {
664 /// let mut handle = io::stdout_locked();
666 /// handle.write_all(b"hello world")?;
671 #[unstable(feature = "stdio_locked", issue = "none")]
672 pub fn stdout_locked() -> StdoutLock<'static> {
673 stdout().into_locked()
677 if let Some(instance) = STDOUT.get() {
678 // Flush the data and disable buffering during shutdown
679 // by replacing the line writer by one with zero
680 // buffering capacity.
681 // We use try_lock() instead of lock(), because someone
682 // might have leaked a StdoutLock, which would
683 // otherwise cause a deadlock here.
684 if let Some(lock) = Pin::static_ref(instance).try_lock() {
685 *lock.borrow_mut() = LineWriter::with_capacity(0, stdout_raw());
691 /// Locks this handle to the standard output stream, returning a writable
694 /// The lock is released when the returned lock goes out of scope. The
695 /// returned guard also implements the `Write` trait for writing data.
700 /// use std::io::{self, Write};
702 /// fn main() -> io::Result<()> {
703 /// let stdout = io::stdout();
704 /// let mut handle = stdout.lock();
706 /// handle.write_all(b"hello world")?;
711 #[stable(feature = "rust1", since = "1.0.0")]
712 pub fn lock(&self) -> StdoutLock<'_> {
716 // Locks this handle with any lifetime. This depends on the
717 // implementation detail that the underlying `ReentrantMutex` is
719 fn lock_any<'a>(&self) -> StdoutLock<'a> {
720 StdoutLock { inner: self.inner.lock() }
723 /// Consumes this handle to the standard output stream, locking the
724 /// shared global buffer associated with the stream and returning a
727 /// The lock is released when the returned lock goes out of scope. The
728 /// returned guard also implements the [`Write`] trait for writing data.
730 /// It is often simpler to directly get a locked handle using the
731 /// [`io::stdout_locked`] function instead, unless nearby code also
732 /// needs to use an unlocked handle.
737 /// #![feature(stdio_locked)]
738 /// use std::io::{self, Write};
740 /// fn main() -> io::Result<()> {
741 /// let mut handle = io::stdout().into_locked();
743 /// handle.write_all(b"hello world")?;
748 #[unstable(feature = "stdio_locked", issue = "none")]
749 pub fn into_locked(self) -> StdoutLock<'static> {
754 #[stable(feature = "std_debug", since = "1.16.0")]
755 impl fmt::Debug for Stdout {
756 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
757 f.debug_struct("Stdout").finish_non_exhaustive()
761 #[stable(feature = "rust1", since = "1.0.0")]
762 impl Write for Stdout {
763 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
766 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
767 (&*self).write_vectored(bufs)
770 fn is_write_vectored(&self) -> bool {
771 io::Write::is_write_vectored(&&*self)
773 fn flush(&mut self) -> io::Result<()> {
776 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
777 (&*self).write_all(buf)
779 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
780 (&*self).write_all_vectored(bufs)
782 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
783 (&*self).write_fmt(args)
787 #[stable(feature = "write_mt", since = "1.48.0")]
788 impl Write for &Stdout {
789 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
790 self.lock().write(buf)
792 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
793 self.lock().write_vectored(bufs)
796 fn is_write_vectored(&self) -> bool {
797 self.lock().is_write_vectored()
799 fn flush(&mut self) -> io::Result<()> {
802 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
803 self.lock().write_all(buf)
805 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
806 self.lock().write_all_vectored(bufs)
808 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
809 self.lock().write_fmt(args)
813 #[stable(feature = "rust1", since = "1.0.0")]
814 impl Write for StdoutLock<'_> {
815 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
816 self.inner.borrow_mut().write(buf)
818 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
819 self.inner.borrow_mut().write_vectored(bufs)
822 fn is_write_vectored(&self) -> bool {
823 self.inner.borrow_mut().is_write_vectored()
825 fn flush(&mut self) -> io::Result<()> {
826 self.inner.borrow_mut().flush()
828 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
829 self.inner.borrow_mut().write_all(buf)
831 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
832 self.inner.borrow_mut().write_all_vectored(bufs)
836 #[stable(feature = "std_debug", since = "1.16.0")]
837 impl fmt::Debug for StdoutLock<'_> {
838 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
839 f.debug_struct("StdoutLock").finish_non_exhaustive()
843 /// A handle to the standard error stream of a process.
845 /// For more information, see the [`io::stderr`] method.
847 /// [`io::stderr`]: stderr
849 /// ### Note: Windows Portability Consideration
850 /// When operating in a console, the Windows implementation of this stream does not support
851 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
853 #[stable(feature = "rust1", since = "1.0.0")]
855 inner: Pin<&'static ReentrantMutex<RefCell<StderrRaw>>>,
858 /// A locked reference to the [`Stderr`] handle.
860 /// This handle implements the [`Write`] trait and is constructed via
861 /// the [`Stderr::lock`] method. See its documentation for more.
863 /// ### Note: Windows Portability Consideration
864 /// When operating in a console, the Windows implementation of this stream does not support
865 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
867 #[stable(feature = "rust1", since = "1.0.0")]
868 pub struct StderrLock<'a> {
869 inner: ReentrantMutexGuard<'a, RefCell<StderrRaw>>,
872 /// Constructs a new handle to the standard error of the current process.
874 /// This handle is not buffered.
876 /// ### Note: Windows Portability Consideration
877 /// When operating in a console, the Windows implementation of this stream does not support
878 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
883 /// Using implicit synchronization:
886 /// use std::io::{self, Write};
888 /// fn main() -> io::Result<()> {
889 /// io::stderr().write_all(b"hello world")?;
895 /// Using explicit synchronization:
898 /// use std::io::{self, Write};
900 /// fn main() -> io::Result<()> {
901 /// let stderr = io::stderr();
902 /// let mut handle = stderr.lock();
904 /// handle.write_all(b"hello world")?;
909 #[stable(feature = "rust1", since = "1.0.0")]
910 pub fn stderr() -> Stderr {
911 // Note that unlike `stdout()` we don't use `at_exit` here to register a
912 // destructor. Stderr is not buffered , so there's no need to run a
913 // destructor for flushing the buffer
914 static INSTANCE: SyncOnceCell<ReentrantMutex<RefCell<StderrRaw>>> = SyncOnceCell::new();
917 inner: Pin::static_ref(&INSTANCE).get_or_init_pin(
918 || unsafe { ReentrantMutex::new(RefCell::new(stderr_raw())) },
919 |mutex| unsafe { mutex.init() },
924 /// Constructs a new locked handle to the standard error of the current
927 /// This handle is not buffered.
929 /// ### Note: Windows Portability Consideration
930 /// When operating in a console, the Windows implementation of this stream does not support
931 /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
937 /// #![feature(stdio_locked)]
938 /// use std::io::{self, Write};
940 /// fn main() -> io::Result<()> {
941 /// let mut handle = io::stderr_locked();
943 /// handle.write_all(b"hello world")?;
948 #[unstable(feature = "stdio_locked", issue = "none")]
949 pub fn stderr_locked() -> StderrLock<'static> {
950 stderr().into_locked()
954 /// Locks this handle to the standard error stream, returning a writable
957 /// The lock is released when the returned lock goes out of scope. The
958 /// returned guard also implements the [`Write`] trait for writing data.
963 /// use std::io::{self, Write};
965 /// fn foo() -> io::Result<()> {
966 /// let stderr = io::stderr();
967 /// let mut handle = stderr.lock();
969 /// handle.write_all(b"hello world")?;
974 #[stable(feature = "rust1", since = "1.0.0")]
975 pub fn lock(&self) -> StderrLock<'_> {
979 // Locks this handle with any lifetime. This depends on the
980 // implementation detail that the underlying `ReentrantMutex` is
982 fn lock_any<'a>(&self) -> StderrLock<'a> {
983 StderrLock { inner: self.inner.lock() }
986 /// Locks and consumes this handle to the standard error stream,
987 /// returning a writable guard.
989 /// The lock is released when the returned guard goes out of scope. The
990 /// returned guard also implements the [`Write`] trait for writing
996 /// #![feature(stdio_locked)]
997 /// use std::io::{self, Write};
999 /// fn foo() -> io::Result<()> {
1000 /// let stderr = io::stderr();
1001 /// let mut handle = stderr.into_locked();
1003 /// handle.write_all(b"hello world")?;
1008 #[unstable(feature = "stdio_locked", issue = "none")]
1009 pub fn into_locked(self) -> StderrLock<'static> {
1014 #[stable(feature = "std_debug", since = "1.16.0")]
1015 impl fmt::Debug for Stderr {
1016 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1017 f.debug_struct("Stderr").finish_non_exhaustive()
1021 #[stable(feature = "rust1", since = "1.0.0")]
1022 impl Write for Stderr {
1023 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1026 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
1027 (&*self).write_vectored(bufs)
1030 fn is_write_vectored(&self) -> bool {
1031 io::Write::is_write_vectored(&&*self)
1033 fn flush(&mut self) -> io::Result<()> {
1036 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
1037 (&*self).write_all(buf)
1039 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
1040 (&*self).write_all_vectored(bufs)
1042 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
1043 (&*self).write_fmt(args)
1047 #[stable(feature = "write_mt", since = "1.48.0")]
1048 impl Write for &Stderr {
1049 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1050 self.lock().write(buf)
1052 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
1053 self.lock().write_vectored(bufs)
1056 fn is_write_vectored(&self) -> bool {
1057 self.lock().is_write_vectored()
1059 fn flush(&mut self) -> io::Result<()> {
1062 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
1063 self.lock().write_all(buf)
1065 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
1066 self.lock().write_all_vectored(bufs)
1068 fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> {
1069 self.lock().write_fmt(args)
1073 #[stable(feature = "rust1", since = "1.0.0")]
1074 impl Write for StderrLock<'_> {
1075 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
1076 self.inner.borrow_mut().write(buf)
1078 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
1079 self.inner.borrow_mut().write_vectored(bufs)
1082 fn is_write_vectored(&self) -> bool {
1083 self.inner.borrow_mut().is_write_vectored()
1085 fn flush(&mut self) -> io::Result<()> {
1086 self.inner.borrow_mut().flush()
1088 fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
1089 self.inner.borrow_mut().write_all(buf)
1091 fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> {
1092 self.inner.borrow_mut().write_all_vectored(bufs)
1096 #[stable(feature = "std_debug", since = "1.16.0")]
1097 impl fmt::Debug for StderrLock<'_> {
1098 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1099 f.debug_struct("StderrLock").finish_non_exhaustive()
1103 /// Sets the thread-local output capture buffer and returns the old one.
1105 feature = "internal_output_capture",
1106 reason = "this function is meant for use in the test crate \
1107 and may disappear in the future",
1111 pub fn set_output_capture(sink: Option<LocalStream>) -> Option<LocalStream> {
1112 if sink.is_none() && !OUTPUT_CAPTURE_USED.load(Ordering::Relaxed) {
1113 // OUTPUT_CAPTURE is definitely None since OUTPUT_CAPTURE_USED is false.
1116 OUTPUT_CAPTURE_USED.store(true, Ordering::Relaxed);
1117 OUTPUT_CAPTURE.with(move |slot| slot.replace(sink))
1120 /// Write `args` to the capture buffer if enabled and possible, or `global_s`
1121 /// otherwise. `label` identifies the stream in a panic message.
1123 /// This function is used to print error messages, so it takes extra
1124 /// care to avoid causing a panic when `local_s` is unusable.
1125 /// For instance, if the TLS key for the local stream is
1126 /// already destroyed, or if the local stream is locked by another
1127 /// thread, it will just fall back to the global stream.
1129 /// However, if the actual I/O causes an error, this function does panic.
1130 fn print_to<T>(args: fmt::Arguments<'_>, global_s: fn() -> T, label: &str)
1134 if OUTPUT_CAPTURE_USED.load(Ordering::Relaxed)
1135 && OUTPUT_CAPTURE.try_with(|s| {
1136 // Note that we completely remove a local sink to write to in case
1137 // our printing recursively panics/prints, so the recursive
1138 // panic/print goes to the global sink instead of our local sink.
1140 let _ = w.lock().unwrap_or_else(|e| e.into_inner()).write_fmt(args);
1145 // Succesfully wrote to capture buffer.
1149 if let Err(e) = global_s().write_fmt(args) {
1150 panic!("failed printing to {}: {}", label, e);
1155 feature = "print_internals",
1156 reason = "implementation detail which may disappear or be replaced at any time",
1161 pub fn _print(args: fmt::Arguments<'_>) {
1162 print_to(args, stdout, "stdout");
1166 feature = "print_internals",
1167 reason = "implementation detail which may disappear or be replaced at any time",
1172 pub fn _eprint(args: fmt::Arguments<'_>) {
1173 print_to(args, stderr, "stderr");
1177 pub use realstd::io::{_eprint, _print};