std/os/fd/
stdio.rs

1use super::BorrowedFd;
2
3/// The file descriptor for the standard input stream of the current process.
4///
5/// See [`io::stdin()`][`crate::io::stdin`] for the higher level handle, which should be preferred
6/// whenever possible. See [`STDERR`] for why the file descriptor might be required and caveats.
7#[unstable(feature = "stdio_fd_consts", issue = "150836")]
8pub const STDIN: BorrowedFd<'static> = unsafe { BorrowedFd::borrow_raw(0) };
9
10/// The file descriptor for the standard output stream of the current process.
11///
12/// See [`io::stdout()`][`crate::io::stdout`] for the higher level handle, which should be preferred
13/// whenever possible. See [`STDERR`] for why the file descriptor might be required and caveats. In
14/// addition to the issues discussed there, note that [`Stdout`][`crate::io::Stdout`] is buffered by
15/// default, and writing to the file descriptor will bypass this buffer.
16#[unstable(feature = "stdio_fd_consts", issue = "150836")]
17pub const STDOUT: BorrowedFd<'static> = unsafe { BorrowedFd::borrow_raw(1) };
18
19/// The file descriptor for the standard error stream of the current process.
20///
21/// See [`io::stderr()`][`crate::io::stderr`] for the higher level handle, which should be preferred
22/// whenever possible. However, there are situations where touching the `std::io` handles (or most
23/// other parts of the standard library) risks deadlocks or other subtle bugs. For example:
24///
25/// - Global allocators must be careful to [avoid reentrancy][global-alloc-reentrancy], and the
26///   `std::io` handles may allocate memory on (some) accesses.
27/// - Signal handlers must be *async-signal-safe*, which rules out panicking, taking locks (may
28///   deadlock if the signal handler interrupted a thread holding that lock), allocating memory, or
29///   anything else that is not explicitly declared async-signal-safe.
30/// - `CommandExt::pre_exec` callbacks can safely panic (with some limitations), but otherwise must
31///   abide by similar limitations as signal handlers. In particular, at the time these callbacks
32///   run, the stdio file descriptors have already been replaced, but the locks protecting the
33///   `std::io` handles may be permanently locked if another thread held the lock at `fork()` time.
34///
35/// In these and similar cases, direct access to the file descriptor may be required. However, in
36/// most cases, using the `std::io` handles and accessing the file descriptor via the `AsFd`
37/// implementations is preferable, as it enables cooperation with the standard library's locking and
38/// buffering.
39///
40/// # I/O safety
41///
42/// This is a `BorrowedFd<'static>` because the standard input/output/error streams are shared
43/// resources that must remain available for the lifetime of the process. This is only true when
44/// linking `std`, and may not always hold for [code running before `main()`][before-after-main] or
45/// in `no_std` environments. It is [unsound][io-safety] to close these file descriptors. Safe
46/// patterns for changing these file descriptors are available on Unix via the `StdioExt` extension
47/// trait.
48///
49/// [before-after-main]: ../../../std/index.html#use-before-and-after-main
50/// [io-safety]: ../../../std/io/index.html#io-safety
51/// [global-alloc-reentrancy]: ../../../std/alloc/trait.GlobalAlloc.html#re-entrance
52#[unstable(feature = "stdio_fd_consts", issue = "150836")]
53pub const STDERR: BorrowedFd<'static> = unsafe { BorrowedFd::borrow_raw(2) };
std/os/fd/stdio.rs

std/os/fd/
stdio.rs
