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
11 use crate::backend;
12 use crate::fd::OwnedFd;
13 use 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]
stdin() -> BorrowedFd<'static>41 pub 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]
take_stdin() -> OwnedFd71 pub 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]
stdout() -> BorrowedFd<'static>102 pub 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]
take_stdout() -> OwnedFd132 pub 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]
stderr() -> BorrowedFd<'static>162 pub 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]
take_stderr() -> OwnedFd192 pub 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]
raw_stdin() -> RawFd212 pub 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]
raw_stdout() -> RawFd232 pub 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]
raw_stderr() -> RawFd252 pub const fn raw_stderr() -> RawFd {
253 backend::io::types::STDERR_FILENO as RawFd
254 }
255