1//! Functions returning the stdio file descriptors. 2//! 3//! # Safety 4//! 5//! These access the file descriptors by absolute index value, and nothing 6//! prevents them from being closed and reused. They should only be used in 7//! `main` or other situations where one is in control of the process' 8//! stdio streams. 9#![allow(unsafe_code)] 10 11use crate::backend; 12use crate::fd::OwnedFd; 13use backend::fd::{BorrowedFd, FromRawFd, RawFd}; 14 15/// `STDIN_FILENO`—Standard input, borrowed. 16/// 17/// # Safety 18/// 19/// This function must be called from code which knows how the process' 20/// standard input is being used. Often, this will be the `main` function or 21/// code that knows its relationship with the `main` function. 22/// 23/// The stdin file descriptor can be closed, potentially on other threads, in 24/// which case the file descriptor index value could be dynamically reused for 25/// other purposes, potentially on different threads. 26/// 27/// # Other hazards 28/// 29/// Stdin could be redirected from arbitrary input sources, and unless one 30/// knows how the process' standard input is being used, one could consume 31/// bytes that are expected to be consumed by other parts of the process. 32/// 33/// # References 34/// - [POSIX] 35/// - [Linux] 36/// 37/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html 38/// [Linux]: https://man7.org/linux/man-pages/man3/stdin.3.html 39#[doc(alias = "STDIN_FILENO")] 40#[inline] 41pub const unsafe fn stdin() -> BorrowedFd<'static> { 42 BorrowedFd::borrow_raw(backend::io::types::STDIN_FILENO as RawFd) 43} 44 45/// `STDIN_FILENO`—Standard input, owned. 46/// 47/// This is similar to [`stdin`], however it returns an `OwnedFd` which closes 48/// standard input when it is dropped. 49/// 50/// # Safety 51/// 52/// This is unsafe for the same reasons as [`stdin`]. 53/// 54/// # Other hazards 55/// 56/// This has the same hazards as [`stdin`]. 57/// 58/// And, when the `OwnedFd` is dropped, subsequent newly created file 59/// descriptors may unknowingly reuse the stdin file descriptor number, which 60/// may break common assumptions, so it should typically only be dropped at the 61/// end of a program when no more file descriptors will be created. 62/// 63/// # References 64/// - [POSIX] 65/// - [Linux] 66/// 67/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html 68/// [Linux]: https://man7.org/linux/man-pages/man3/stdin.3.html 69#[doc(alias = "STDIN_FILENO")] 70#[inline] 71pub unsafe fn take_stdin() -> OwnedFd { 72 backend::fd::OwnedFd::from_raw_fd(backend::io::types::STDIN_FILENO as RawFd) 73} 74 75/// `STDOUT_FILENO`—Standard output, borrowed. 76/// 77/// # Safety 78/// 79/// This function must be called from code which knows how the process' 80/// standard output is being used. Often, this will be the `main` function or 81/// code that knows its relationship with the `main` function. 82/// 83/// The stdout file descriptor can be closed, potentially on other threads, in 84/// which case the file descriptor index value could be dynamically reused for 85/// other purposes, potentially on different threads. 86/// 87/// # Other hazards 88/// 89/// Stdout could be redirected to arbitrary output sinks, and unless one 90/// knows how the process' standard output is being used, one could 91/// unexpectedly inject bytes into a stream being written by another part of 92/// the process. 93/// 94/// # References 95/// - [POSIX] 96/// - [Linux] 97/// 98/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdout.html 99/// [Linux]: https://man7.org/linux/man-pages/man3/stdout.3.html 100#[doc(alias = "STDOUT_FILENO")] 101#[inline] 102pub const unsafe fn stdout() -> BorrowedFd<'static> { 103 BorrowedFd::borrow_raw(backend::io::types::STDOUT_FILENO as RawFd) 104} 105 106/// `STDOUT_FILENO`—Standard output, owned. 107/// 108/// This is similar to [`stdout`], however it returns an `OwnedFd` which closes 109/// standard output when it is dropped. 110/// 111/// # Safety 112/// 113/// This is unsafe for the same reasons as [`stdout`]. 114/// 115/// # Other hazards 116/// 117/// This has the same hazards as [`stdout`]. 118/// 119/// And, when the `OwnedFd` is dropped, subsequent newly created file 120/// descriptors may unknowingly reuse the stdout file descriptor number, which 121/// may break common assumptions, so it should typically only be dropped at the 122/// end of a program when no more file descriptors will be created. 123/// 124/// # References 125/// - [POSIX] 126/// - [Linux] 127/// 128/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdout.html 129/// [Linux]: https://man7.org/linux/man-pages/man3/stdout.3.html 130#[doc(alias = "STDOUT_FILENO")] 131#[inline] 132pub unsafe fn take_stdout() -> OwnedFd { 133 backend::fd::OwnedFd::from_raw_fd(backend::io::types::STDOUT_FILENO as RawFd) 134} 135 136/// `STDERR_FILENO`—Standard error, borrowed. 137/// 138/// # Safety 139/// 140/// This function must be called from code which knows how the process' 141/// standard error is being used. Often, this will be the `main` function or 142/// code that knows its relationship with the `main` function. 143/// 144/// The stderr file descriptor can be closed, potentially on other threads, in 145/// which case the file descriptor index value could be dynamically reused for 146/// other purposes, potentially on different threads. 147/// 148/// # Other hazards 149/// 150/// Stderr could be redirected to arbitrary output sinks, and unless one 151/// knows how the process' standard error is being used, one could unexpectedly 152/// inject bytes into a stream being written by another part of the process. 153/// 154/// # References 155/// - [POSIX] 156/// - [Linux] 157/// 158/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stderr.html 159/// [Linux]: https://man7.org/linux/man-pages/man3/stderr.3.html 160#[doc(alias = "STDERR_FILENO")] 161#[inline] 162pub const unsafe fn stderr() -> BorrowedFd<'static> { 163 BorrowedFd::borrow_raw(backend::io::types::STDERR_FILENO as RawFd) 164} 165 166/// `STDERR_FILENO`—Standard error, owned. 167/// 168/// This is similar to [`stdout`], however it returns an `OwnedFd` which closes 169/// standard output when it is dropped. 170/// 171/// # Safety 172/// 173/// This is unsafe for the same reasons as [`stderr`]. 174/// 175/// # Other hazards 176/// 177/// This has the same hazards as [`stderr`]. 178/// 179/// And, when the `OwnedFd` is dropped, subsequent newly created file 180/// descriptors may unknowingly reuse the stderr file descriptor number, which 181/// may break common assumptions, so it should typically only be dropped at the 182/// end of a program when no more file descriptors will be created. 183/// 184/// # References 185/// - [POSIX] 186/// - [Linux] 187/// 188/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stderr.html 189/// [Linux]: https://man7.org/linux/man-pages/man3/stderr.3.html 190#[doc(alias = "STDERR_FILENO")] 191#[inline] 192pub unsafe fn take_stderr() -> OwnedFd { 193 backend::fd::OwnedFd::from_raw_fd(backend::io::types::STDERR_FILENO as RawFd) 194} 195 196/// `STDIN_FILENO`—Standard input, raw. 197/// 198/// This is similar to [`stdin`], however it returns a `RawFd`. 199/// 200/// # Other hazards 201/// 202/// This has the same hazards as [`stdin`]. 203/// 204/// # References 205/// - [POSIX] 206/// - [Linux] 207/// 208/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html 209/// [Linux]: https://man7.org/linux/man-pages/man3/stdin.3.html 210#[doc(alias = "STDIN_FILENO")] 211#[inline] 212pub const fn raw_stdin() -> RawFd { 213 backend::io::types::STDIN_FILENO as RawFd 214} 215 216/// `STDOUT_FILENO`—Standard output, raw. 217/// 218/// This is similar to [`stdout`], however it returns a `RawFd`. 219/// 220/// # Other hazards 221/// 222/// This has the same hazards as [`stdout`]. 223/// 224/// # References 225/// - [POSIX] 226/// - [Linux] 227/// 228/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdout.html 229/// [Linux]: https://man7.org/linux/man-pages/man3/stdout.3.html 230#[doc(alias = "STDOUT_FILENO")] 231#[inline] 232pub const fn raw_stdout() -> RawFd { 233 backend::io::types::STDOUT_FILENO as RawFd 234} 235 236/// `STDERR_FILENO`—Standard error, raw. 237/// 238/// This is similar to [`stderr`], however it returns a `RawFd`. 239/// 240/// # Other hazards 241/// 242/// This has the same hazards as [`stderr`]. 243/// 244/// # References 245/// - [POSIX] 246/// - [Linux] 247/// 248/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/stderr.html 249/// [Linux]: https://man7.org/linux/man-pages/man3/stderr.3.html 250#[doc(alias = "STDERR_FILENO")] 251#[inline] 252pub const fn raw_stderr() -> RawFd { 253 backend::io::types::STDERR_FILENO as RawFd 254} 255