1//! A module for working with processes.
2//!
3//! This module is mostly concerned with spawning and interacting with child
4//! processes, but it also provides [`abort`] and [`exit`] for terminating the
5//! current process.
6//!
7//! # Spawning a process
8//!
9//! The [`Command`] struct is used to configure and spawn processes:
10//!
11//! ```no_run
12//! use std::process::Command;
13//!
14//! let output = Command::new("echo")
15//! .arg("Hello world")
16//! .output()
17//! .expect("Failed to execute command");
18//!
19//! assert_eq!(b"Hello world\n", output.stdout.as_slice());
20//! ```
21//!
22//! Several methods on [`Command`], such as [`spawn`] or [`output`], can be used
23//! to spawn a process. In particular, [`output`] spawns the child process and
24//! waits until the process terminates, while [`spawn`] will return a [`Child`]
25//! that represents the spawned child process.
26//!
27//! # Handling I/O
28//!
29//! The [`stdout`], [`stdin`], and [`stderr`] of a child process can be
30//! configured by passing an [`Stdio`] to the corresponding method on
31//! [`Command`]. Once spawned, they can be accessed from the [`Child`]. For
32//! example, piping output from one command into another command can be done
33//! like so:
34//!
35//! ```no_run
36//! use std::process::{Command, Stdio};
37//!
38//! // stdout must be configured with `Stdio::piped` in order to use
39//! // `echo_child.stdout`
40//! let echo_child = Command::new("echo")
41//! .arg("Oh no, a tpyo!")
42//! .stdout(Stdio::piped())
43//! .spawn()
44//! .expect("Failed to start echo process");
45//!
46//! // Note that `echo_child` is moved here, but we won't be needing
47//! // `echo_child` anymore
48//! let echo_out = echo_child.stdout.expect("Failed to open echo stdout");
49//!
50//! let mut sed_child = Command::new("sed")
51//! .arg("s/tpyo/typo/")
52//! .stdin(Stdio::from(echo_out))
53//! .stdout(Stdio::piped())
54//! .spawn()
55//! .expect("Failed to start sed process");
56//!
57//! let output = sed_child.wait_with_output().expect("Failed to wait on sed");
58//! assert_eq!(b"Oh no, a typo!\n", output.stdout.as_slice());
59//! ```
60//!
61//! Note that [`ChildStderr`] and [`ChildStdout`] implement [`Read`] and
62//! [`ChildStdin`] implements [`Write`]:
63//!
64//! ```no_run
65//! use std::process::{Command, Stdio};
66//! use std::io::Write;
67//!
68//! let mut child = Command::new("/bin/cat")
69//! .stdin(Stdio::piped())
70//! .stdout(Stdio::piped())
71//! .spawn()
72//! .expect("failed to execute child");
73//!
74//! // If the child process fills its stdout buffer, it may end up
75//! // waiting until the parent reads the stdout, and not be able to
76//! // read stdin in the meantime, causing a deadlock.
77//! // Writing from another thread ensures that stdout is being read
78//! // at the same time, avoiding the problem.
79//! let mut stdin = child.stdin.take().expect("failed to get stdin");
80//! std::thread::spawn(move || {
81//! stdin.write_all(b"test").expect("failed to write to stdin");
82//! });
83//!
84//! let output = child
85//! .wait_with_output()
86//! .expect("failed to wait on child");
87//!
88//! assert_eq!(b"test", output.stdout.as_slice());
89//! ```
90//!
91//! # Windows argument splitting
92//!
93//! On Unix systems arguments are passed to a new process as an array of strings,
94//! but on Windows arguments are passed as a single commandline string and it is
95//! up to the child process to parse it into an array. Therefore the parent and
96//! child processes must agree on how the commandline string is encoded.
97//!
98//! Most programs use the standard C run-time `argv`, which in practice results
99//! in consistent argument handling. However, some programs have their own way of
100//! parsing the commandline string. In these cases using [`arg`] or [`args`] may
101//! result in the child process seeing a different array of arguments than the
102//! parent process intended.
103//!
104//! Two ways of mitigating this are:
105//!
106//! * Validate untrusted input so that only a safe subset is allowed.
107//! * Use [`raw_arg`] to build a custom commandline. This bypasses the escaping
108//! rules used by [`arg`] so should be used with due caution.
109//!
110//! `cmd.exe` and `.bat` files use non-standard argument parsing and are especially
111//! vulnerable to malicious input as they may be used to run arbitrary shell
112//! commands. Untrusted arguments should be restricted as much as possible.
113//! For examples on handling this see [`raw_arg`].
114//!
115//! ### Batch file special handling
116//!
117//! On Windows, `Command` uses the Windows API function [`CreateProcessW`] to
118//! spawn new processes. An undocumented feature of this function is that
119//! when given a `.bat` file as the application to run, it will automatically
120//! convert that into running `cmd.exe /c` with the batch file as the next argument.
121//!
122//! For historical reasons Rust currently preserves this behavior when using
123//! [`Command::new`], and escapes the arguments according to `cmd.exe` rules.
124//! Due to the complexity of `cmd.exe` argument handling, it might not be
125//! possible to safely escape some special characters, and using them will result
126//! in an error being returned at process spawn. The set of unescapeable
127//! special characters might change between releases.
128//!
129//! Also note that running batch scripts in this way may be removed in the
130//! future and so should not be relied upon.
131//!
132//! [`spawn`]: Command::spawn
133//! [`output`]: Command::output
134//!
135//! [`stdout`]: Command::stdout
136//! [`stdin`]: Command::stdin
137//! [`stderr`]: Command::stderr
138//!
139//! [`Write`]: io::Write
140//! [`Read`]: io::Read
141//!
142//! [`arg`]: Command::arg
143//! [`args`]: Command::args
144//! [`raw_arg`]: crate::os::windows::process::CommandExt::raw_arg
145//!
146//! [`CreateProcessW`]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw
147
148#![stable(feature = "process", since = "1.0.0")]
149#![deny(unsafe_op_in_unsafe_fn)]
150
151#[cfg(all(
152 test,
153 not(any(
154 target_os = "emscripten",
155 target_os = "wasi",
156 target_env = "sgx",
157 target_os = "xous",
158 target_os = "trusty",
159 ))
160))]
161mod tests;
162
163use crate::convert::Infallible;
164use crate::ffi::OsStr;
165use crate::io::prelude::*;
166use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut};
167use crate::num::NonZero;
168use crate::path::Path;
169use crate::sys::pipe::{AnonPipe, read2};
170use crate::sys::process as imp;
171#[stable(feature = "command_access", since = "1.57.0")]
172pub use crate::sys_common::process::CommandEnvs;
173use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};
174use crate::{fmt, fs, str};
175
176/// Representation of a running or exited child process.
177///
178/// This structure is used to represent and manage child processes. A child
179/// process is created via the [`Command`] struct, which configures the
180/// spawning process and can itself be constructed using a builder-style
181/// interface.
182///
183/// There is no implementation of [`Drop`] for child processes,
184/// so if you do not ensure the `Child` has exited then it will continue to
185/// run, even after the `Child` handle to the child process has gone out of
186/// scope.
187///
188/// Calling [`wait`] (or other functions that wrap around it) will make
189/// the parent process wait until the child has actually exited before
190/// continuing.
191///
192/// # Warning
193///
194/// On some systems, calling [`wait`] or similar is necessary for the OS to
195/// release resources. A process that terminated but has not been waited on is
196/// still around as a "zombie". Leaving too many zombies around may exhaust
197/// global resources (for example process IDs).
198///
199/// The standard library does *not* automatically wait on child processes (not
200/// even if the `Child` is dropped), it is up to the application developer to do
201/// so. As a consequence, dropping `Child` handles without waiting on them first
202/// is not recommended in long-running applications.
203///
204/// # Examples
205///
206/// ```should_panic
207/// use std::process::Command;
208///
209/// let mut child = Command::new("/bin/cat")
210/// .arg("file.txt")
211/// .spawn()
212/// .expect("failed to execute child");
213///
214/// let ecode = child.wait().expect("failed to wait on child");
215///
216/// assert!(ecode.success());
217/// ```
218///
219/// [`wait`]: Child::wait
220#[stable(feature = "process", since = "1.0.0")]
221#[cfg_attr(not(test), rustc_diagnostic_item = "Child")]
222pub struct Child {
223 pub(crate) handle: imp::Process,
224
225 /// The handle for writing to the child's standard input (stdin), if it
226 /// has been captured. You might find it helpful to do
227 ///
228 /// ```ignore (incomplete)
229 /// let stdin = child.stdin.take().expect("handle present");
230 /// ```
231 ///
232 /// to avoid partially moving the `child` and thus blocking yourself from calling
233 /// functions on `child` while using `stdin`.
234 #[stable(feature = "process", since = "1.0.0")]
235 pub stdin: Option<ChildStdin>,
236
237 /// The handle for reading from the child's standard output (stdout), if it
238 /// has been captured. You might find it helpful to do
239 ///
240 /// ```ignore (incomplete)
241 /// let stdout = child.stdout.take().expect("handle present");
242 /// ```
243 ///
244 /// to avoid partially moving the `child` and thus blocking yourself from calling
245 /// functions on `child` while using `stdout`.
246 #[stable(feature = "process", since = "1.0.0")]
247 pub stdout: Option<ChildStdout>,
248
249 /// The handle for reading from the child's standard error (stderr), if it
250 /// has been captured. You might find it helpful to do
251 ///
252 /// ```ignore (incomplete)
253 /// let stderr = child.stderr.take().expect("handle present");
254 /// ```
255 ///
256 /// to avoid partially moving the `child` and thus blocking yourself from calling
257 /// functions on `child` while using `stderr`.
258 #[stable(feature = "process", since = "1.0.0")]
259 pub stderr: Option<ChildStderr>,
260}
261
262/// Allows extension traits within `std`.
263#[unstable(feature = "sealed", issue = "none")]
264impl crate::sealed::Sealed for Child {}
265
266impl AsInner<imp::Process> for Child {
267 #[inline]
268 fn as_inner(&self) -> &imp::Process {
269 &self.handle
270 }
271}
272
273impl FromInner<(imp::Process, imp::StdioPipes)> for Child {
274 fn from_inner((handle: Process, io: StdioPipes): (imp::Process, imp::StdioPipes)) -> Child {
275 Child {
276 handle,
277 stdin: io.stdin.map(ChildStdin::from_inner),
278 stdout: io.stdout.map(ChildStdout::from_inner),
279 stderr: io.stderr.map(ChildStderr::from_inner),
280 }
281 }
282}
283
284impl IntoInner<imp::Process> for Child {
285 fn into_inner(self) -> imp::Process {
286 self.handle
287 }
288}
289
290#[stable(feature = "std_debug", since = "1.16.0")]
291impl fmt::Debug for Child {
292 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
293 f&mut DebugStruct<'_, '_>.debug_struct("Child")
294 .field("stdin", &self.stdin)
295 .field("stdout", &self.stdout)
296 .field(name:"stderr", &self.stderr)
297 .finish_non_exhaustive()
298 }
299}
300
301/// A handle to a child process's standard input (stdin).
302///
303/// This struct is used in the [`stdin`] field on [`Child`].
304///
305/// When an instance of `ChildStdin` is [dropped], the `ChildStdin`'s underlying
306/// file handle will be closed. If the child process was blocked on input prior
307/// to being dropped, it will become unblocked after dropping.
308///
309/// [`stdin`]: Child::stdin
310/// [dropped]: Drop
311#[stable(feature = "process", since = "1.0.0")]
312pub struct ChildStdin {
313 inner: AnonPipe,
314}
315
316// In addition to the `impl`s here, `ChildStdin` also has `impl`s for
317// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
318// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and
319// `AsHandle`/`From<OwnedHandle>`/`Into<OwnedHandle>` and
320// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
321
322#[stable(feature = "process", since = "1.0.0")]
323impl Write for ChildStdin {
324 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
325 (&*self).write(buf)
326 }
327
328 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
329 (&*self).write_vectored(bufs)
330 }
331
332 fn is_write_vectored(&self) -> bool {
333 io::Write::is_write_vectored(&&*self)
334 }
335
336 #[inline]
337 fn flush(&mut self) -> io::Result<()> {
338 (&*self).flush()
339 }
340}
341
342#[stable(feature = "write_mt", since = "1.48.0")]
343impl Write for &ChildStdin {
344 fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
345 self.inner.write(buf)
346 }
347
348 fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
349 self.inner.write_vectored(bufs)
350 }
351
352 fn is_write_vectored(&self) -> bool {
353 self.inner.is_write_vectored()
354 }
355
356 #[inline]
357 fn flush(&mut self) -> io::Result<()> {
358 Ok(())
359 }
360}
361
362impl AsInner<AnonPipe> for ChildStdin {
363 #[inline]
364 fn as_inner(&self) -> &AnonPipe {
365 &self.inner
366 }
367}
368
369impl IntoInner<AnonPipe> for ChildStdin {
370 fn into_inner(self) -> AnonPipe {
371 self.inner
372 }
373}
374
375impl FromInner<AnonPipe> for ChildStdin {
376 fn from_inner(pipe: AnonPipe) -> ChildStdin {
377 ChildStdin { inner: pipe }
378 }
379}
380
381#[stable(feature = "std_debug", since = "1.16.0")]
382impl fmt::Debug for ChildStdin {
383 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
384 f.debug_struct(name:"ChildStdin").finish_non_exhaustive()
385 }
386}
387
388/// A handle to a child process's standard output (stdout).
389///
390/// This struct is used in the [`stdout`] field on [`Child`].
391///
392/// When an instance of `ChildStdout` is [dropped], the `ChildStdout`'s
393/// underlying file handle will be closed.
394///
395/// [`stdout`]: Child::stdout
396/// [dropped]: Drop
397#[stable(feature = "process", since = "1.0.0")]
398pub struct ChildStdout {
399 inner: AnonPipe,
400}
401
402// In addition to the `impl`s here, `ChildStdout` also has `impl`s for
403// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
404// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and
405// `AsHandle`/`From<OwnedHandle>`/`Into<OwnedHandle>` and
406// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
407
408#[stable(feature = "process", since = "1.0.0")]
409impl Read for ChildStdout {
410 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
411 self.inner.read(buf)
412 }
413
414 fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
415 self.inner.read_buf(buf)
416 }
417
418 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
419 self.inner.read_vectored(bufs)
420 }
421
422 #[inline]
423 fn is_read_vectored(&self) -> bool {
424 self.inner.is_read_vectored()
425 }
426
427 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
428 self.inner.read_to_end(buf)
429 }
430}
431
432impl AsInner<AnonPipe> for ChildStdout {
433 #[inline]
434 fn as_inner(&self) -> &AnonPipe {
435 &self.inner
436 }
437}
438
439impl IntoInner<AnonPipe> for ChildStdout {
440 fn into_inner(self) -> AnonPipe {
441 self.inner
442 }
443}
444
445impl FromInner<AnonPipe> for ChildStdout {
446 fn from_inner(pipe: AnonPipe) -> ChildStdout {
447 ChildStdout { inner: pipe }
448 }
449}
450
451#[stable(feature = "std_debug", since = "1.16.0")]
452impl fmt::Debug for ChildStdout {
453 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
454 f.debug_struct(name:"ChildStdout").finish_non_exhaustive()
455 }
456}
457
458/// A handle to a child process's stderr.
459///
460/// This struct is used in the [`stderr`] field on [`Child`].
461///
462/// When an instance of `ChildStderr` is [dropped], the `ChildStderr`'s
463/// underlying file handle will be closed.
464///
465/// [`stderr`]: Child::stderr
466/// [dropped]: Drop
467#[stable(feature = "process", since = "1.0.0")]
468pub struct ChildStderr {
469 inner: AnonPipe,
470}
471
472// In addition to the `impl`s here, `ChildStderr` also has `impl`s for
473// `AsFd`/`From<OwnedFd>`/`Into<OwnedFd>` and
474// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and
475// `AsHandle`/`From<OwnedHandle>`/`Into<OwnedHandle>` and
476// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows.
477
478#[stable(feature = "process", since = "1.0.0")]
479impl Read for ChildStderr {
480 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
481 self.inner.read(buf)
482 }
483
484 fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> {
485 self.inner.read_buf(buf)
486 }
487
488 fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
489 self.inner.read_vectored(bufs)
490 }
491
492 #[inline]
493 fn is_read_vectored(&self) -> bool {
494 self.inner.is_read_vectored()
495 }
496
497 fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
498 self.inner.read_to_end(buf)
499 }
500}
501
502impl AsInner<AnonPipe> for ChildStderr {
503 #[inline]
504 fn as_inner(&self) -> &AnonPipe {
505 &self.inner
506 }
507}
508
509impl IntoInner<AnonPipe> for ChildStderr {
510 fn into_inner(self) -> AnonPipe {
511 self.inner
512 }
513}
514
515impl FromInner<AnonPipe> for ChildStderr {
516 fn from_inner(pipe: AnonPipe) -> ChildStderr {
517 ChildStderr { inner: pipe }
518 }
519}
520
521#[stable(feature = "std_debug", since = "1.16.0")]
522impl fmt::Debug for ChildStderr {
523 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
524 f.debug_struct(name:"ChildStderr").finish_non_exhaustive()
525 }
526}
527
528/// A process builder, providing fine-grained control
529/// over how a new process should be spawned.
530///
531/// A default configuration can be
532/// generated using `Command::new(program)`, where `program` gives a path to the
533/// program to be executed. Additional builder methods allow the configuration
534/// to be changed (for example, by adding arguments) prior to spawning:
535///
536/// ```
537/// use std::process::Command;
538///
539/// let output = if cfg!(target_os = "windows") {
540/// Command::new("cmd")
541/// .args(["/C", "echo hello"])
542/// .output()
543/// .expect("failed to execute process")
544/// } else {
545/// Command::new("sh")
546/// .arg("-c")
547/// .arg("echo hello")
548/// .output()
549/// .expect("failed to execute process")
550/// };
551///
552/// let hello = output.stdout;
553/// ```
554///
555/// `Command` can be reused to spawn multiple processes. The builder methods
556/// change the command without needing to immediately spawn the process.
557///
558/// ```no_run
559/// use std::process::Command;
560///
561/// let mut echo_hello = Command::new("sh");
562/// echo_hello.arg("-c").arg("echo hello");
563/// let hello_1 = echo_hello.output().expect("failed to execute process");
564/// let hello_2 = echo_hello.output().expect("failed to execute process");
565/// ```
566///
567/// Similarly, you can call builder methods after spawning a process and then
568/// spawn a new process with the modified settings.
569///
570/// ```no_run
571/// use std::process::Command;
572///
573/// let mut list_dir = Command::new("ls");
574///
575/// // Execute `ls` in the current directory of the program.
576/// list_dir.status().expect("process failed to execute");
577///
578/// println!();
579///
580/// // Change `ls` to execute in the root directory.
581/// list_dir.current_dir("/");
582///
583/// // And then execute `ls` again but in the root directory.
584/// list_dir.status().expect("process failed to execute");
585/// ```
586#[stable(feature = "process", since = "1.0.0")]
587#[cfg_attr(not(test), rustc_diagnostic_item = "Command")]
588pub struct Command {
589 inner: imp::Command,
590}
591
592/// Allows extension traits within `std`.
593#[unstable(feature = "sealed", issue = "none")]
594impl crate::sealed::Sealed for Command {}
595
596impl Command {
597 /// Constructs a new `Command` for launching the program at
598 /// path `program`, with the following default configuration:
599 ///
600 /// * No arguments to the program
601 /// * Inherit the current process's environment
602 /// * Inherit the current process's working directory
603 /// * Inherit stdin/stdout/stderr for [`spawn`] or [`status`], but create pipes for [`output`]
604 ///
605 /// [`spawn`]: Self::spawn
606 /// [`status`]: Self::status
607 /// [`output`]: Self::output
608 ///
609 /// Builder methods are provided to change these defaults and
610 /// otherwise configure the process.
611 ///
612 /// If `program` is not an absolute path, the `PATH` will be searched in
613 /// an OS-defined way.
614 ///
615 /// The search path to be used may be controlled by setting the
616 /// `PATH` environment variable on the Command,
617 /// but this has some implementation limitations on Windows
618 /// (see issue #37519).
619 ///
620 /// # Platform-specific behavior
621 ///
622 /// Note on Windows: For executable files with the .exe extension,
623 /// it can be omitted when specifying the program for this Command.
624 /// However, if the file has a different extension,
625 /// a filename including the extension needs to be provided,
626 /// otherwise the file won't be found.
627 ///
628 /// # Examples
629 ///
630 /// ```no_run
631 /// use std::process::Command;
632 ///
633 /// Command::new("sh")
634 /// .spawn()
635 /// .expect("sh command failed to start");
636 /// ```
637 ///
638 /// # Caveats
639 ///
640 /// [`Command::new`] is only intended to accept the path of the program. If you pass a program
641 /// path along with arguments like `Command::new("ls -l").spawn()`, it will try to search for
642 /// `ls -l` literally. The arguments need to be passed separately, such as via [`arg`] or
643 /// [`args`].
644 ///
645 /// ```no_run
646 /// use std::process::Command;
647 ///
648 /// Command::new("ls")
649 /// .arg("-l") // arg passed separately
650 /// .spawn()
651 /// .expect("ls command failed to start");
652 /// ```
653 ///
654 /// [`arg`]: Self::arg
655 /// [`args`]: Self::args
656 #[stable(feature = "process", since = "1.0.0")]
657 pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
658 Command { inner: imp::Command::new(program.as_ref()) }
659 }
660
661 /// Adds an argument to pass to the program.
662 ///
663 /// Only one argument can be passed per use. So instead of:
664 ///
665 /// ```no_run
666 /// # std::process::Command::new("sh")
667 /// .arg("-C /path/to/repo")
668 /// # ;
669 /// ```
670 ///
671 /// usage would be:
672 ///
673 /// ```no_run
674 /// # std::process::Command::new("sh")
675 /// .arg("-C")
676 /// .arg("/path/to/repo")
677 /// # ;
678 /// ```
679 ///
680 /// To pass multiple arguments see [`args`].
681 ///
682 /// [`args`]: Command::args
683 ///
684 /// Note that the argument is not passed through a shell, but given
685 /// literally to the program. This means that shell syntax like quotes,
686 /// escaped characters, word splitting, glob patterns, variable substitution,
687 /// etc. have no effect.
688 ///
689 /// <div class="warning">
690 ///
691 /// On Windows, use caution with untrusted inputs. Most applications use the
692 /// standard convention for decoding arguments passed to them. These are safe to
693 /// use with `arg`. However, some applications such as `cmd.exe` and `.bat` files
694 /// use a non-standard way of decoding arguments. They are therefore vulnerable
695 /// to malicious input.
696 ///
697 /// In the case of `cmd.exe` this is especially important because a malicious
698 /// argument can potentially run arbitrary shell commands.
699 ///
700 /// See [Windows argument splitting][windows-args] for more details
701 /// or [`raw_arg`] for manually implementing non-standard argument encoding.
702 ///
703 /// [`raw_arg`]: crate::os::windows::process::CommandExt::raw_arg
704 /// [windows-args]: crate::process#windows-argument-splitting
705 ///
706 /// </div>
707 ///
708 /// # Examples
709 ///
710 /// ```no_run
711 /// use std::process::Command;
712 ///
713 /// Command::new("ls")
714 /// .arg("-l")
715 /// .arg("-a")
716 /// .spawn()
717 /// .expect("ls command failed to start");
718 /// ```
719 #[stable(feature = "process", since = "1.0.0")]
720 pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
721 self.inner.arg(arg.as_ref());
722 self
723 }
724
725 /// Adds multiple arguments to pass to the program.
726 ///
727 /// To pass a single argument see [`arg`].
728 ///
729 /// [`arg`]: Command::arg
730 ///
731 /// Note that the arguments are not passed through a shell, but given
732 /// literally to the program. This means that shell syntax like quotes,
733 /// escaped characters, word splitting, glob patterns, variable substitution, etc.
734 /// have no effect.
735 ///
736 /// <div class="warning">
737 ///
738 /// On Windows, use caution with untrusted inputs. Most applications use the
739 /// standard convention for decoding arguments passed to them. These are safe to
740 /// use with `arg`. However, some applications such as `cmd.exe` and `.bat` files
741 /// use a non-standard way of decoding arguments. They are therefore vulnerable
742 /// to malicious input.
743 ///
744 /// In the case of `cmd.exe` this is especially important because a malicious
745 /// argument can potentially run arbitrary shell commands.
746 ///
747 /// See [Windows argument splitting][windows-args] for more details
748 /// or [`raw_arg`] for manually implementing non-standard argument encoding.
749 ///
750 /// [`raw_arg`]: crate::os::windows::process::CommandExt::raw_arg
751 /// [windows-args]: crate::process#windows-argument-splitting
752 ///
753 /// </div>
754 ///
755 /// # Examples
756 ///
757 /// ```no_run
758 /// use std::process::Command;
759 ///
760 /// Command::new("ls")
761 /// .args(["-l", "-a"])
762 /// .spawn()
763 /// .expect("ls command failed to start");
764 /// ```
765 #[stable(feature = "process", since = "1.0.0")]
766 pub fn args<I, S>(&mut self, args: I) -> &mut Command
767 where
768 I: IntoIterator<Item = S>,
769 S: AsRef<OsStr>,
770 {
771 for arg in args {
772 self.arg(arg.as_ref());
773 }
774 self
775 }
776
777 /// Inserts or updates an explicit environment variable mapping.
778 ///
779 /// This method allows you to add an environment variable mapping to the spawned process or
780 /// overwrite a previously set value. You can use [`Command::envs`] to set multiple environment
781 /// variables simultaneously.
782 ///
783 /// Child processes will inherit environment variables from their parent process by default.
784 /// Environment variables explicitly set using [`Command::env`] take precedence over inherited
785 /// variables. You can disable environment variable inheritance entirely using
786 /// [`Command::env_clear`] or for a single key using [`Command::env_remove`].
787 ///
788 /// Note that environment variable names are case-insensitive (but
789 /// case-preserving) on Windows and case-sensitive on all other platforms.
790 ///
791 /// # Examples
792 ///
793 /// ```no_run
794 /// use std::process::Command;
795 ///
796 /// Command::new("ls")
797 /// .env("PATH", "/bin")
798 /// .spawn()
799 /// .expect("ls command failed to start");
800 /// ```
801 #[stable(feature = "process", since = "1.0.0")]
802 pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
803 where
804 K: AsRef<OsStr>,
805 V: AsRef<OsStr>,
806 {
807 self.inner.env_mut().set(key.as_ref(), val.as_ref());
808 self
809 }
810
811 /// Inserts or updates multiple explicit environment variable mappings.
812 ///
813 /// This method allows you to add multiple environment variable mappings to the spawned process
814 /// or overwrite previously set values. You can use [`Command::env`] to set a single environment
815 /// variable.
816 ///
817 /// Child processes will inherit environment variables from their parent process by default.
818 /// Environment variables explicitly set using [`Command::envs`] take precedence over inherited
819 /// variables. You can disable environment variable inheritance entirely using
820 /// [`Command::env_clear`] or for a single key using [`Command::env_remove`].
821 ///
822 /// Note that environment variable names are case-insensitive (but case-preserving) on Windows
823 /// and case-sensitive on all other platforms.
824 ///
825 /// # Examples
826 ///
827 /// ```no_run
828 /// use std::process::{Command, Stdio};
829 /// use std::env;
830 /// use std::collections::HashMap;
831 ///
832 /// let filtered_env : HashMap<String, String> =
833 /// env::vars().filter(|&(ref k, _)|
834 /// k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
835 /// ).collect();
836 ///
837 /// Command::new("printenv")
838 /// .stdin(Stdio::null())
839 /// .stdout(Stdio::inherit())
840 /// .env_clear()
841 /// .envs(&filtered_env)
842 /// .spawn()
843 /// .expect("printenv failed to start");
844 /// ```
845 #[stable(feature = "command_envs", since = "1.19.0")]
846 pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
847 where
848 I: IntoIterator<Item = (K, V)>,
849 K: AsRef<OsStr>,
850 V: AsRef<OsStr>,
851 {
852 for (ref key, ref val) in vars {
853 self.inner.env_mut().set(key.as_ref(), val.as_ref());
854 }
855 self
856 }
857
858 /// Removes an explicitly set environment variable and prevents inheriting it from a parent
859 /// process.
860 ///
861 /// This method will remove the explicit value of an environment variable set via
862 /// [`Command::env`] or [`Command::envs`]. In addition, it will prevent the spawned child
863 /// process from inheriting that environment variable from its parent process.
864 ///
865 /// After calling [`Command::env_remove`], the value associated with its key from
866 /// [`Command::get_envs`] will be [`None`].
867 ///
868 /// To clear all explicitly set environment variables and disable all environment variable
869 /// inheritance, you can use [`Command::env_clear`].
870 ///
871 /// # Examples
872 ///
873 /// Prevent any inherited `GIT_DIR` variable from changing the target of the `git` command,
874 /// while allowing all other variables, like `GIT_AUTHOR_NAME`.
875 ///
876 /// ```no_run
877 /// use std::process::Command;
878 ///
879 /// Command::new("git")
880 /// .arg("commit")
881 /// .env_remove("GIT_DIR")
882 /// .spawn()?;
883 /// # std::io::Result::Ok(())
884 /// ```
885 #[stable(feature = "process", since = "1.0.0")]
886 pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Command {
887 self.inner.env_mut().remove(key.as_ref());
888 self
889 }
890
891 /// Clears all explicitly set environment variables and prevents inheriting any parent process
892 /// environment variables.
893 ///
894 /// This method will remove all explicitly added environment variables set via [`Command::env`]
895 /// or [`Command::envs`]. In addition, it will prevent the spawned child process from inheriting
896 /// any environment variable from its parent process.
897 ///
898 /// After calling [`Command::env_clear`], the iterator from [`Command::get_envs`] will be
899 /// empty.
900 ///
901 /// You can use [`Command::env_remove`] to clear a single mapping.
902 ///
903 /// # Examples
904 ///
905 /// The behavior of `sort` is affected by `LANG` and `LC_*` environment variables.
906 /// Clearing the environment makes `sort`'s behavior independent of the parent processes' language.
907 ///
908 /// ```no_run
909 /// use std::process::Command;
910 ///
911 /// Command::new("sort")
912 /// .arg("file.txt")
913 /// .env_clear()
914 /// .spawn()?;
915 /// # std::io::Result::Ok(())
916 /// ```
917 #[stable(feature = "process", since = "1.0.0")]
918 pub fn env_clear(&mut self) -> &mut Command {
919 self.inner.env_mut().clear();
920 self
921 }
922
923 /// Sets the working directory for the child process.
924 ///
925 /// # Platform-specific behavior
926 ///
927 /// If the program path is relative (e.g., `"./script.sh"`), it's ambiguous
928 /// whether it should be interpreted relative to the parent's working
929 /// directory or relative to `current_dir`. The behavior in this case is
930 /// platform specific and unstable, and it's recommended to use
931 /// [`canonicalize`] to get an absolute program path instead.
932 ///
933 /// # Examples
934 ///
935 /// ```no_run
936 /// use std::process::Command;
937 ///
938 /// Command::new("ls")
939 /// .current_dir("/bin")
940 /// .spawn()
941 /// .expect("ls command failed to start");
942 /// ```
943 ///
944 /// [`canonicalize`]: crate::fs::canonicalize
945 #[stable(feature = "process", since = "1.0.0")]
946 pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
947 self.inner.cwd(dir.as_ref().as_ref());
948 self
949 }
950
951 /// Configuration for the child process's standard input (stdin) handle.
952 ///
953 /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and
954 /// defaults to [`piped`] when used with [`output`].
955 ///
956 /// [`inherit`]: Stdio::inherit
957 /// [`piped`]: Stdio::piped
958 /// [`spawn`]: Self::spawn
959 /// [`status`]: Self::status
960 /// [`output`]: Self::output
961 ///
962 /// # Examples
963 ///
964 /// ```no_run
965 /// use std::process::{Command, Stdio};
966 ///
967 /// Command::new("ls")
968 /// .stdin(Stdio::null())
969 /// .spawn()
970 /// .expect("ls command failed to start");
971 /// ```
972 #[stable(feature = "process", since = "1.0.0")]
973 pub fn stdin<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
974 self.inner.stdin(cfg.into().0);
975 self
976 }
977
978 /// Configuration for the child process's standard output (stdout) handle.
979 ///
980 /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and
981 /// defaults to [`piped`] when used with [`output`].
982 ///
983 /// [`inherit`]: Stdio::inherit
984 /// [`piped`]: Stdio::piped
985 /// [`spawn`]: Self::spawn
986 /// [`status`]: Self::status
987 /// [`output`]: Self::output
988 ///
989 /// # Examples
990 ///
991 /// ```no_run
992 /// use std::process::{Command, Stdio};
993 ///
994 /// Command::new("ls")
995 /// .stdout(Stdio::null())
996 /// .spawn()
997 /// .expect("ls command failed to start");
998 /// ```
999 #[stable(feature = "process", since = "1.0.0")]
1000 pub fn stdout<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
1001 self.inner.stdout(cfg.into().0);
1002 self
1003 }
1004
1005 /// Configuration for the child process's standard error (stderr) handle.
1006 ///
1007 /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and
1008 /// defaults to [`piped`] when used with [`output`].
1009 ///
1010 /// [`inherit`]: Stdio::inherit
1011 /// [`piped`]: Stdio::piped
1012 /// [`spawn`]: Self::spawn
1013 /// [`status`]: Self::status
1014 /// [`output`]: Self::output
1015 ///
1016 /// # Examples
1017 ///
1018 /// ```no_run
1019 /// use std::process::{Command, Stdio};
1020 ///
1021 /// Command::new("ls")
1022 /// .stderr(Stdio::null())
1023 /// .spawn()
1024 /// .expect("ls command failed to start");
1025 /// ```
1026 #[stable(feature = "process", since = "1.0.0")]
1027 pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
1028 self.inner.stderr(cfg.into().0);
1029 self
1030 }
1031
1032 /// Executes the command as a child process, returning a handle to it.
1033 ///
1034 /// By default, stdin, stdout and stderr are inherited from the parent.
1035 ///
1036 /// # Examples
1037 ///
1038 /// ```no_run
1039 /// use std::process::Command;
1040 ///
1041 /// Command::new("ls")
1042 /// .spawn()
1043 /// .expect("ls command failed to start");
1044 /// ```
1045 #[stable(feature = "process", since = "1.0.0")]
1046 pub fn spawn(&mut self) -> io::Result<Child> {
1047 self.inner.spawn(imp::Stdio::Inherit, true).map(Child::from_inner)
1048 }
1049
1050 /// Executes the command as a child process, waiting for it to finish and
1051 /// collecting all of its output.
1052 ///
1053 /// By default, stdout and stderr are captured (and used to provide the
1054 /// resulting output). Stdin is not inherited from the parent and any
1055 /// attempt by the child process to read from the stdin stream will result
1056 /// in the stream immediately closing.
1057 ///
1058 /// # Examples
1059 ///
1060 /// ```should_panic
1061 /// use std::process::Command;
1062 /// use std::io::{self, Write};
1063 /// let output = Command::new("/bin/cat")
1064 /// .arg("file.txt")
1065 /// .output()?;
1066 ///
1067 /// println!("status: {}", output.status);
1068 /// io::stdout().write_all(&output.stdout)?;
1069 /// io::stderr().write_all(&output.stderr)?;
1070 ///
1071 /// assert!(output.status.success());
1072 /// # io::Result::Ok(())
1073 /// ```
1074 #[stable(feature = "process", since = "1.0.0")]
1075 pub fn output(&mut self) -> io::Result<Output> {
1076 let (status, stdout, stderr) = self.inner.output()?;
1077 Ok(Output { status: ExitStatus(status), stdout, stderr })
1078 }
1079
1080 /// Executes a command as a child process, waiting for it to finish and
1081 /// collecting its status.
1082 ///
1083 /// By default, stdin, stdout and stderr are inherited from the parent.
1084 ///
1085 /// # Examples
1086 ///
1087 /// ```should_panic
1088 /// use std::process::Command;
1089 ///
1090 /// let status = Command::new("/bin/cat")
1091 /// .arg("file.txt")
1092 /// .status()
1093 /// .expect("failed to execute process");
1094 ///
1095 /// println!("process finished with: {status}");
1096 ///
1097 /// assert!(status.success());
1098 /// ```
1099 #[stable(feature = "process", since = "1.0.0")]
1100 pub fn status(&mut self) -> io::Result<ExitStatus> {
1101 self.inner
1102 .spawn(imp::Stdio::Inherit, true)
1103 .map(Child::from_inner)
1104 .and_then(|mut p| p.wait())
1105 }
1106
1107 /// Returns the path to the program that was given to [`Command::new`].
1108 ///
1109 /// # Examples
1110 ///
1111 /// ```
1112 /// use std::process::Command;
1113 ///
1114 /// let cmd = Command::new("echo");
1115 /// assert_eq!(cmd.get_program(), "echo");
1116 /// ```
1117 #[must_use]
1118 #[stable(feature = "command_access", since = "1.57.0")]
1119 pub fn get_program(&self) -> &OsStr {
1120 self.inner.get_program()
1121 }
1122
1123 /// Returns an iterator of the arguments that will be passed to the program.
1124 ///
1125 /// This does not include the path to the program as the first argument;
1126 /// it only includes the arguments specified with [`Command::arg`] and
1127 /// [`Command::args`].
1128 ///
1129 /// # Examples
1130 ///
1131 /// ```
1132 /// use std::ffi::OsStr;
1133 /// use std::process::Command;
1134 ///
1135 /// let mut cmd = Command::new("echo");
1136 /// cmd.arg("first").arg("second");
1137 /// let args: Vec<&OsStr> = cmd.get_args().collect();
1138 /// assert_eq!(args, &["first", "second"]);
1139 /// ```
1140 #[stable(feature = "command_access", since = "1.57.0")]
1141 pub fn get_args(&self) -> CommandArgs<'_> {
1142 CommandArgs { inner: self.inner.get_args() }
1143 }
1144
1145 /// Returns an iterator of the environment variables explicitly set for the child process.
1146 ///
1147 /// Environment variables explicitly set using [`Command::env`], [`Command::envs`], and
1148 /// [`Command::env_remove`] can be retrieved with this method.
1149 ///
1150 /// Note that this output does not include environment variables inherited from the parent
1151 /// process.
1152 ///
1153 /// Each element is a tuple key/value pair `(&OsStr, Option<&OsStr>)`. A [`None`] value
1154 /// indicates its key was explicitly removed via [`Command::env_remove`]. The associated key for
1155 /// the [`None`] value will no longer inherit from its parent process.
1156 ///
1157 /// An empty iterator can indicate that no explicit mappings were added or that
1158 /// [`Command::env_clear`] was called. After calling [`Command::env_clear`], the child process
1159 /// will not inherit any environment variables from its parent process.
1160 ///
1161 /// # Examples
1162 ///
1163 /// ```
1164 /// use std::ffi::OsStr;
1165 /// use std::process::Command;
1166 ///
1167 /// let mut cmd = Command::new("ls");
1168 /// cmd.env("TERM", "dumb").env_remove("TZ");
1169 /// let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
1170 /// assert_eq!(envs, &[
1171 /// (OsStr::new("TERM"), Some(OsStr::new("dumb"))),
1172 /// (OsStr::new("TZ"), None)
1173 /// ]);
1174 /// ```
1175 #[stable(feature = "command_access", since = "1.57.0")]
1176 pub fn get_envs(&self) -> CommandEnvs<'_> {
1177 self.inner.get_envs()
1178 }
1179
1180 /// Returns the working directory for the child process.
1181 ///
1182 /// This returns [`None`] if the working directory will not be changed.
1183 ///
1184 /// # Examples
1185 ///
1186 /// ```
1187 /// use std::path::Path;
1188 /// use std::process::Command;
1189 ///
1190 /// let mut cmd = Command::new("ls");
1191 /// assert_eq!(cmd.get_current_dir(), None);
1192 /// cmd.current_dir("/bin");
1193 /// assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));
1194 /// ```
1195 #[must_use]
1196 #[stable(feature = "command_access", since = "1.57.0")]
1197 pub fn get_current_dir(&self) -> Option<&Path> {
1198 self.inner.get_current_dir()
1199 }
1200}
1201
1202#[stable(feature = "rust1", since = "1.0.0")]
1203impl fmt::Debug for Command {
1204 /// Format the program and arguments of a Command for display. Any
1205 /// non-utf8 data is lossily converted using the utf8 replacement
1206 /// character.
1207 ///
1208 /// The default format approximates a shell invocation of the program along with its
1209 /// arguments. It does not include most of the other command properties. The output is not guaranteed to work
1210 /// (e.g. due to lack of shell-escaping or differences in path resolution).
1211 /// On some platforms you can use [the alternate syntax] to show more fields.
1212 ///
1213 /// Note that the debug implementation is platform-specific.
1214 ///
1215 /// [the alternate syntax]: fmt#sign0
1216 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1217 self.inner.fmt(f)
1218 }
1219}
1220
1221impl AsInner<imp::Command> for Command {
1222 #[inline]
1223 fn as_inner(&self) -> &imp::Command {
1224 &self.inner
1225 }
1226}
1227
1228impl AsInnerMut<imp::Command> for Command {
1229 #[inline]
1230 fn as_inner_mut(&mut self) -> &mut imp::Command {
1231 &mut self.inner
1232 }
1233}
1234
1235/// An iterator over the command arguments.
1236///
1237/// This struct is created by [`Command::get_args`]. See its documentation for
1238/// more.
1239#[must_use = "iterators are lazy and do nothing unless consumed"]
1240#[stable(feature = "command_access", since = "1.57.0")]
1241#[derive(Debug)]
1242pub struct CommandArgs<'a> {
1243 inner: imp::CommandArgs<'a>,
1244}
1245
1246#[stable(feature = "command_access", since = "1.57.0")]
1247impl<'a> Iterator for CommandArgs<'a> {
1248 type Item = &'a OsStr;
1249 fn next(&mut self) -> Option<&'a OsStr> {
1250 self.inner.next()
1251 }
1252 fn size_hint(&self) -> (usize, Option<usize>) {
1253 self.inner.size_hint()
1254 }
1255}
1256
1257#[stable(feature = "command_access", since = "1.57.0")]
1258impl<'a> ExactSizeIterator for CommandArgs<'a> {
1259 fn len(&self) -> usize {
1260 self.inner.len()
1261 }
1262 fn is_empty(&self) -> bool {
1263 self.inner.is_empty()
1264 }
1265}
1266
1267/// The output of a finished process.
1268///
1269/// This is returned in a Result by either the [`output`] method of a
1270/// [`Command`], or the [`wait_with_output`] method of a [`Child`]
1271/// process.
1272///
1273/// [`output`]: Command::output
1274/// [`wait_with_output`]: Child::wait_with_output
1275#[derive(PartialEq, Eq, Clone)]
1276#[stable(feature = "process", since = "1.0.0")]
1277pub struct Output {
1278 /// The status (exit code) of the process.
1279 #[stable(feature = "process", since = "1.0.0")]
1280 pub status: ExitStatus,
1281 /// The data that the process wrote to stdout.
1282 #[stable(feature = "process", since = "1.0.0")]
1283 pub stdout: Vec<u8>,
1284 /// The data that the process wrote to stderr.
1285 #[stable(feature = "process", since = "1.0.0")]
1286 pub stderr: Vec<u8>,
1287}
1288
1289// If either stderr or stdout are valid utf8 strings it prints the valid
1290// strings, otherwise it prints the byte sequence instead
1291#[stable(feature = "process_output_debug", since = "1.7.0")]
1292impl fmt::Debug for Output {
1293 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1294 let stdout_utf8: Result<&str, Utf8Error> = str::from_utf8(&self.stdout);
1295 let stdout_debug: &dyn fmt::Debug = match stdout_utf8 {
1296 Ok(ref s: &&str) => s,
1297 Err(_) => &self.stdout,
1298 };
1299
1300 let stderr_utf8: Result<&str, Utf8Error> = str::from_utf8(&self.stderr);
1301 let stderr_debug: &dyn fmt::Debug = match stderr_utf8 {
1302 Ok(ref s: &&str) => s,
1303 Err(_) => &self.stderr,
1304 };
1305
1306 fmt&mut DebugStruct<'_, '_>.debug_struct("Output")
1307 .field("status", &self.status)
1308 .field("stdout", stdout_debug)
1309 .field(name:"stderr", value:stderr_debug)
1310 .finish()
1311 }
1312}
1313
1314/// Describes what to do with a standard I/O stream for a child process when
1315/// passed to the [`stdin`], [`stdout`], and [`stderr`] methods of [`Command`].
1316///
1317/// [`stdin`]: Command::stdin
1318/// [`stdout`]: Command::stdout
1319/// [`stderr`]: Command::stderr
1320#[stable(feature = "process", since = "1.0.0")]
1321pub struct Stdio(imp::Stdio);
1322
1323impl Stdio {
1324 /// A new pipe should be arranged to connect the parent and child processes.
1325 ///
1326 /// # Examples
1327 ///
1328 /// With stdout:
1329 ///
1330 /// ```no_run
1331 /// use std::process::{Command, Stdio};
1332 ///
1333 /// let output = Command::new("echo")
1334 /// .arg("Hello, world!")
1335 /// .stdout(Stdio::piped())
1336 /// .output()
1337 /// .expect("Failed to execute command");
1338 ///
1339 /// assert_eq!(String::from_utf8_lossy(&output.stdout), "Hello, world!\n");
1340 /// // Nothing echoed to console
1341 /// ```
1342 ///
1343 /// With stdin:
1344 ///
1345 /// ```no_run
1346 /// use std::io::Write;
1347 /// use std::process::{Command, Stdio};
1348 ///
1349 /// let mut child = Command::new("rev")
1350 /// .stdin(Stdio::piped())
1351 /// .stdout(Stdio::piped())
1352 /// .spawn()
1353 /// .expect("Failed to spawn child process");
1354 ///
1355 /// let mut stdin = child.stdin.take().expect("Failed to open stdin");
1356 /// std::thread::spawn(move || {
1357 /// stdin.write_all("Hello, world!".as_bytes()).expect("Failed to write to stdin");
1358 /// });
1359 ///
1360 /// let output = child.wait_with_output().expect("Failed to read stdout");
1361 /// assert_eq!(String::from_utf8_lossy(&output.stdout), "!dlrow ,olleH");
1362 /// ```
1363 ///
1364 /// Writing more than a pipe buffer's worth of input to stdin without also reading
1365 /// stdout and stderr at the same time may cause a deadlock.
1366 /// This is an issue when running any program that doesn't guarantee that it reads
1367 /// its entire stdin before writing more than a pipe buffer's worth of output.
1368 /// The size of a pipe buffer varies on different targets.
1369 ///
1370 #[must_use]
1371 #[stable(feature = "process", since = "1.0.0")]
1372 pub fn piped() -> Stdio {
1373 Stdio(imp::Stdio::MakePipe)
1374 }
1375
1376 /// The child inherits from the corresponding parent descriptor.
1377 ///
1378 /// # Examples
1379 ///
1380 /// With stdout:
1381 ///
1382 /// ```no_run
1383 /// use std::process::{Command, Stdio};
1384 ///
1385 /// let output = Command::new("echo")
1386 /// .arg("Hello, world!")
1387 /// .stdout(Stdio::inherit())
1388 /// .output()
1389 /// .expect("Failed to execute command");
1390 ///
1391 /// assert_eq!(String::from_utf8_lossy(&output.stdout), "");
1392 /// // "Hello, world!" echoed to console
1393 /// ```
1394 ///
1395 /// With stdin:
1396 ///
1397 /// ```no_run
1398 /// use std::process::{Command, Stdio};
1399 /// use std::io::{self, Write};
1400 ///
1401 /// let output = Command::new("rev")
1402 /// .stdin(Stdio::inherit())
1403 /// .stdout(Stdio::piped())
1404 /// .output()?;
1405 ///
1406 /// print!("You piped in the reverse of: ");
1407 /// io::stdout().write_all(&output.stdout)?;
1408 /// # io::Result::Ok(())
1409 /// ```
1410 #[must_use]
1411 #[stable(feature = "process", since = "1.0.0")]
1412 pub fn inherit() -> Stdio {
1413 Stdio(imp::Stdio::Inherit)
1414 }
1415
1416 /// This stream will be ignored. This is the equivalent of attaching the
1417 /// stream to `/dev/null`.
1418 ///
1419 /// # Examples
1420 ///
1421 /// With stdout:
1422 ///
1423 /// ```no_run
1424 /// use std::process::{Command, Stdio};
1425 ///
1426 /// let output = Command::new("echo")
1427 /// .arg("Hello, world!")
1428 /// .stdout(Stdio::null())
1429 /// .output()
1430 /// .expect("Failed to execute command");
1431 ///
1432 /// assert_eq!(String::from_utf8_lossy(&output.stdout), "");
1433 /// // Nothing echoed to console
1434 /// ```
1435 ///
1436 /// With stdin:
1437 ///
1438 /// ```no_run
1439 /// use std::process::{Command, Stdio};
1440 ///
1441 /// let output = Command::new("rev")
1442 /// .stdin(Stdio::null())
1443 /// .stdout(Stdio::piped())
1444 /// .output()
1445 /// .expect("Failed to execute command");
1446 ///
1447 /// assert_eq!(String::from_utf8_lossy(&output.stdout), "");
1448 /// // Ignores any piped-in input
1449 /// ```
1450 #[must_use]
1451 #[stable(feature = "process", since = "1.0.0")]
1452 pub fn null() -> Stdio {
1453 Stdio(imp::Stdio::Null)
1454 }
1455
1456 /// Returns `true` if this requires [`Command`] to create a new pipe.
1457 ///
1458 /// # Example
1459 ///
1460 /// ```
1461 /// #![feature(stdio_makes_pipe)]
1462 /// use std::process::Stdio;
1463 ///
1464 /// let io = Stdio::piped();
1465 /// assert_eq!(io.makes_pipe(), true);
1466 /// ```
1467 #[unstable(feature = "stdio_makes_pipe", issue = "98288")]
1468 pub fn makes_pipe(&self) -> bool {
1469 matches!(self.0, imp::Stdio::MakePipe)
1470 }
1471}
1472
1473impl FromInner<imp::Stdio> for Stdio {
1474 fn from_inner(inner: imp::Stdio) -> Stdio {
1475 Stdio(inner)
1476 }
1477}
1478
1479#[stable(feature = "std_debug", since = "1.16.0")]
1480impl fmt::Debug for Stdio {
1481 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1482 f.debug_struct(name:"Stdio").finish_non_exhaustive()
1483 }
1484}
1485
1486#[stable(feature = "stdio_from", since = "1.20.0")]
1487impl From<ChildStdin> for Stdio {
1488 /// Converts a [`ChildStdin`] into a [`Stdio`].
1489 ///
1490 /// # Examples
1491 ///
1492 /// `ChildStdin` will be converted to `Stdio` using `Stdio::from` under the hood.
1493 ///
1494 /// ```rust,no_run
1495 /// use std::process::{Command, Stdio};
1496 ///
1497 /// let reverse = Command::new("rev")
1498 /// .stdin(Stdio::piped())
1499 /// .spawn()
1500 /// .expect("failed reverse command");
1501 ///
1502 /// let _echo = Command::new("echo")
1503 /// .arg("Hello, world!")
1504 /// .stdout(reverse.stdin.unwrap()) // Converted into a Stdio here
1505 /// .output()
1506 /// .expect("failed echo command");
1507 ///
1508 /// // "!dlrow ,olleH" echoed to console
1509 /// ```
1510 fn from(child: ChildStdin) -> Stdio {
1511 Stdio::from_inner(child.into_inner().into())
1512 }
1513}
1514
1515#[stable(feature = "stdio_from", since = "1.20.0")]
1516impl From<ChildStdout> for Stdio {
1517 /// Converts a [`ChildStdout`] into a [`Stdio`].
1518 ///
1519 /// # Examples
1520 ///
1521 /// `ChildStdout` will be converted to `Stdio` using `Stdio::from` under the hood.
1522 ///
1523 /// ```rust,no_run
1524 /// use std::process::{Command, Stdio};
1525 ///
1526 /// let hello = Command::new("echo")
1527 /// .arg("Hello, world!")
1528 /// .stdout(Stdio::piped())
1529 /// .spawn()
1530 /// .expect("failed echo command");
1531 ///
1532 /// let reverse = Command::new("rev")
1533 /// .stdin(hello.stdout.unwrap()) // Converted into a Stdio here
1534 /// .output()
1535 /// .expect("failed reverse command");
1536 ///
1537 /// assert_eq!(reverse.stdout, b"!dlrow ,olleH\n");
1538 /// ```
1539 fn from(child: ChildStdout) -> Stdio {
1540 Stdio::from_inner(child.into_inner().into())
1541 }
1542}
1543
1544#[stable(feature = "stdio_from", since = "1.20.0")]
1545impl From<ChildStderr> for Stdio {
1546 /// Converts a [`ChildStderr`] into a [`Stdio`].
1547 ///
1548 /// # Examples
1549 ///
1550 /// ```rust,no_run
1551 /// use std::process::{Command, Stdio};
1552 ///
1553 /// let reverse = Command::new("rev")
1554 /// .arg("non_existing_file.txt")
1555 /// .stderr(Stdio::piped())
1556 /// .spawn()
1557 /// .expect("failed reverse command");
1558 ///
1559 /// let cat = Command::new("cat")
1560 /// .arg("-")
1561 /// .stdin(reverse.stderr.unwrap()) // Converted into a Stdio here
1562 /// .output()
1563 /// .expect("failed echo command");
1564 ///
1565 /// assert_eq!(
1566 /// String::from_utf8_lossy(&cat.stdout),
1567 /// "rev: cannot open non_existing_file.txt: No such file or directory\n"
1568 /// );
1569 /// ```
1570 fn from(child: ChildStderr) -> Stdio {
1571 Stdio::from_inner(child.into_inner().into())
1572 }
1573}
1574
1575#[stable(feature = "stdio_from", since = "1.20.0")]
1576impl From<fs::File> for Stdio {
1577 /// Converts a [`File`](fs::File) into a [`Stdio`].
1578 ///
1579 /// # Examples
1580 ///
1581 /// `File` will be converted to `Stdio` using `Stdio::from` under the hood.
1582 ///
1583 /// ```rust,no_run
1584 /// use std::fs::File;
1585 /// use std::process::Command;
1586 ///
1587 /// // With the `foo.txt` file containing "Hello, world!"
1588 /// let file = File::open("foo.txt")?;
1589 ///
1590 /// let reverse = Command::new("rev")
1591 /// .stdin(file) // Implicit File conversion into a Stdio
1592 /// .output()?;
1593 ///
1594 /// assert_eq!(reverse.stdout, b"!dlrow ,olleH");
1595 /// # std::io::Result::Ok(())
1596 /// ```
1597 fn from(file: fs::File) -> Stdio {
1598 Stdio::from_inner(file.into_inner().into())
1599 }
1600}
1601
1602#[stable(feature = "stdio_from_stdio", since = "1.74.0")]
1603impl From<io::Stdout> for Stdio {
1604 /// Redirect command stdout/stderr to our stdout
1605 ///
1606 /// # Examples
1607 ///
1608 /// ```rust
1609 /// #![feature(exit_status_error)]
1610 /// use std::io;
1611 /// use std::process::Command;
1612 ///
1613 /// # fn test() -> Result<(), Box<dyn std::error::Error>> {
1614 /// let output = Command::new("whoami")
1615 // "whoami" is a command which exists on both Unix and Windows,
1616 // and which succeeds, producing some stdout output but no stderr.
1617 /// .stdout(io::stdout())
1618 /// .output()?;
1619 /// output.status.exit_ok()?;
1620 /// assert!(output.stdout.is_empty());
1621 /// # Ok(())
1622 /// # }
1623 /// #
1624 /// # if cfg!(unix) {
1625 /// # test().unwrap();
1626 /// # }
1627 /// ```
1628 fn from(inherit: io::Stdout) -> Stdio {
1629 Stdio::from_inner(inherit.into())
1630 }
1631}
1632
1633#[stable(feature = "stdio_from_stdio", since = "1.74.0")]
1634impl From<io::Stderr> for Stdio {
1635 /// Redirect command stdout/stderr to our stderr
1636 ///
1637 /// # Examples
1638 ///
1639 /// ```rust
1640 /// #![feature(exit_status_error)]
1641 /// use std::io;
1642 /// use std::process::Command;
1643 ///
1644 /// # fn test() -> Result<(), Box<dyn std::error::Error>> {
1645 /// let output = Command::new("whoami")
1646 /// .stdout(io::stderr())
1647 /// .output()?;
1648 /// output.status.exit_ok()?;
1649 /// assert!(output.stdout.is_empty());
1650 /// # Ok(())
1651 /// # }
1652 /// #
1653 /// # if cfg!(unix) {
1654 /// # test().unwrap();
1655 /// # }
1656 /// ```
1657 fn from(inherit: io::Stderr) -> Stdio {
1658 Stdio::from_inner(inherit.into())
1659 }
1660}
1661
1662#[stable(feature = "anonymous_pipe", since = "1.87.0")]
1663impl From<io::PipeWriter> for Stdio {
1664 fn from(pipe: io::PipeWriter) -> Self {
1665 Stdio::from_inner(pipe.into_inner().into())
1666 }
1667}
1668
1669#[stable(feature = "anonymous_pipe", since = "1.87.0")]
1670impl From<io::PipeReader> for Stdio {
1671 fn from(pipe: io::PipeReader) -> Self {
1672 Stdio::from_inner(pipe.into_inner().into())
1673 }
1674}
1675
1676/// Describes the result of a process after it has terminated.
1677///
1678/// This `struct` is used to represent the exit status or other termination of a child process.
1679/// Child processes are created via the [`Command`] struct and their exit
1680/// status is exposed through the [`status`] method, or the [`wait`] method
1681/// of a [`Child`] process.
1682///
1683/// An `ExitStatus` represents every possible disposition of a process. On Unix this
1684/// is the **wait status**. It is *not* simply an *exit status* (a value passed to `exit`).
1685///
1686/// For proper error reporting of failed processes, print the value of `ExitStatus` or
1687/// `ExitStatusError` using their implementations of [`Display`](crate::fmt::Display).
1688///
1689/// # Differences from `ExitCode`
1690///
1691/// [`ExitCode`] is intended for terminating the currently running process, via
1692/// the `Termination` trait, in contrast to `ExitStatus`, which represents the
1693/// termination of a child process. These APIs are separate due to platform
1694/// compatibility differences and their expected usage; it is not generally
1695/// possible to exactly reproduce an `ExitStatus` from a child for the current
1696/// process after the fact.
1697///
1698/// [`status`]: Command::status
1699/// [`wait`]: Child::wait
1700//
1701// We speak slightly loosely (here and in various other places in the stdlib docs) about `exit`
1702// vs `_exit`. Naming of Unix system calls is not standardised across Unices, so terminology is a
1703// matter of convention and tradition. For clarity we usually speak of `exit`, even when we might
1704// mean an underlying system call such as `_exit`.
1705#[derive(PartialEq, Eq, Clone, Copy, Debug)]
1706#[stable(feature = "process", since = "1.0.0")]
1707pub struct ExitStatus(imp::ExitStatus);
1708
1709/// The default value is one which indicates successful completion.
1710#[stable(feature = "process_exitstatus_default", since = "1.73.0")]
1711impl Default for ExitStatus {
1712 fn default() -> Self {
1713 // Ideally this would be done by ExitCode::default().into() but that is complicated.
1714 ExitStatus::from_inner(imp::ExitStatus::default())
1715 }
1716}
1717
1718/// Allows extension traits within `std`.
1719#[unstable(feature = "sealed", issue = "none")]
1720impl crate::sealed::Sealed for ExitStatus {}
1721
1722impl ExitStatus {
1723 /// Was termination successful? Returns a `Result`.
1724 ///
1725 /// # Examples
1726 ///
1727 /// ```
1728 /// #![feature(exit_status_error)]
1729 /// # if cfg!(unix) {
1730 /// use std::process::Command;
1731 ///
1732 /// let status = Command::new("ls")
1733 /// .arg("/dev/nonexistent")
1734 /// .status()
1735 /// .expect("ls could not be executed");
1736 ///
1737 /// println!("ls: {status}");
1738 /// status.exit_ok().expect_err("/dev/nonexistent could be listed!");
1739 /// # } // cfg!(unix)
1740 /// ```
1741 #[unstable(feature = "exit_status_error", issue = "84908")]
1742 pub fn exit_ok(&self) -> Result<(), ExitStatusError> {
1743 self.0.exit_ok().map_err(ExitStatusError)
1744 }
1745
1746 /// Was termination successful? Signal termination is not considered a
1747 /// success, and success is defined as a zero exit status.
1748 ///
1749 /// # Examples
1750 ///
1751 /// ```rust,no_run
1752 /// use std::process::Command;
1753 ///
1754 /// let status = Command::new("mkdir")
1755 /// .arg("projects")
1756 /// .status()
1757 /// .expect("failed to execute mkdir");
1758 ///
1759 /// if status.success() {
1760 /// println!("'projects/' directory created");
1761 /// } else {
1762 /// println!("failed to create 'projects/' directory: {status}");
1763 /// }
1764 /// ```
1765 #[must_use]
1766 #[stable(feature = "process", since = "1.0.0")]
1767 pub fn success(&self) -> bool {
1768 self.0.exit_ok().is_ok()
1769 }
1770
1771 /// Returns the exit code of the process, if any.
1772 ///
1773 /// In Unix terms the return value is the **exit status**: the value passed to `exit`, if the
1774 /// process finished by calling `exit`. Note that on Unix the exit status is truncated to 8
1775 /// bits, and that values that didn't come from a program's call to `exit` may be invented by the
1776 /// runtime system (often, for example, 255, 254, 127 or 126).
1777 ///
1778 /// On Unix, this will return `None` if the process was terminated by a signal.
1779 /// [`ExitStatusExt`](crate::os::unix::process::ExitStatusExt) is an
1780 /// extension trait for extracting any such signal, and other details, from the `ExitStatus`.
1781 ///
1782 /// # Examples
1783 ///
1784 /// ```no_run
1785 /// use std::process::Command;
1786 ///
1787 /// let status = Command::new("mkdir")
1788 /// .arg("projects")
1789 /// .status()
1790 /// .expect("failed to execute mkdir");
1791 ///
1792 /// match status.code() {
1793 /// Some(code) => println!("Exited with status code: {code}"),
1794 /// None => println!("Process terminated by signal")
1795 /// }
1796 /// ```
1797 #[must_use]
1798 #[stable(feature = "process", since = "1.0.0")]
1799 pub fn code(&self) -> Option<i32> {
1800 self.0.code()
1801 }
1802}
1803
1804impl AsInner<imp::ExitStatus> for ExitStatus {
1805 #[inline]
1806 fn as_inner(&self) -> &imp::ExitStatus {
1807 &self.0
1808 }
1809}
1810
1811impl FromInner<imp::ExitStatus> for ExitStatus {
1812 fn from_inner(s: imp::ExitStatus) -> ExitStatus {
1813 ExitStatus(s)
1814 }
1815}
1816
1817#[stable(feature = "process", since = "1.0.0")]
1818impl fmt::Display for ExitStatus {
1819 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1820 self.0.fmt(f)
1821 }
1822}
1823
1824/// Allows extension traits within `std`.
1825#[unstable(feature = "sealed", issue = "none")]
1826impl crate::sealed::Sealed for ExitStatusError {}
1827
1828/// Describes the result of a process after it has failed
1829///
1830/// Produced by the [`.exit_ok`](ExitStatus::exit_ok) method on [`ExitStatus`].
1831///
1832/// # Examples
1833///
1834/// ```
1835/// #![feature(exit_status_error)]
1836/// # if cfg!(unix) {
1837/// use std::process::{Command, ExitStatusError};
1838///
1839/// fn run(cmd: &str) -> Result<(), ExitStatusError> {
1840/// Command::new(cmd).status().unwrap().exit_ok()?;
1841/// Ok(())
1842/// }
1843///
1844/// run("true").unwrap();
1845/// run("false").unwrap_err();
1846/// # } // cfg!(unix)
1847/// ```
1848#[derive(PartialEq, Eq, Clone, Copy, Debug)]
1849#[unstable(feature = "exit_status_error", issue = "84908")]
1850// The definition of imp::ExitStatusError should ideally be such that
1851// Result<(), imp::ExitStatusError> has an identical representation to imp::ExitStatus.
1852pub struct ExitStatusError(imp::ExitStatusError);
1853
1854#[unstable(feature = "exit_status_error", issue = "84908")]
1855impl ExitStatusError {
1856 /// Reports the exit code, if applicable, from an `ExitStatusError`.
1857 ///
1858 /// In Unix terms the return value is the **exit status**: the value passed to `exit`, if the
1859 /// process finished by calling `exit`. Note that on Unix the exit status is truncated to 8
1860 /// bits, and that values that didn't come from a program's call to `exit` may be invented by the
1861 /// runtime system (often, for example, 255, 254, 127 or 126).
1862 ///
1863 /// On Unix, this will return `None` if the process was terminated by a signal. If you want to
1864 /// handle such situations specially, consider using methods from
1865 /// [`ExitStatusExt`](crate::os::unix::process::ExitStatusExt).
1866 ///
1867 /// If the process finished by calling `exit` with a nonzero value, this will return
1868 /// that exit status.
1869 ///
1870 /// If the error was something else, it will return `None`.
1871 ///
1872 /// If the process exited successfully (ie, by calling `exit(0)`), there is no
1873 /// `ExitStatusError`. So the return value from `ExitStatusError::code()` is always nonzero.
1874 ///
1875 /// # Examples
1876 ///
1877 /// ```
1878 /// #![feature(exit_status_error)]
1879 /// # #[cfg(unix)] {
1880 /// use std::process::Command;
1881 ///
1882 /// let bad = Command::new("false").status().unwrap().exit_ok().unwrap_err();
1883 /// assert_eq!(bad.code(), Some(1));
1884 /// # } // #[cfg(unix)]
1885 /// ```
1886 #[must_use]
1887 pub fn code(&self) -> Option<i32> {
1888 self.code_nonzero().map(Into::into)
1889 }
1890
1891 /// Reports the exit code, if applicable, from an `ExitStatusError`, as a [`NonZero`].
1892 ///
1893 /// This is exactly like [`code()`](Self::code), except that it returns a <code>[NonZero]<[i32]></code>.
1894 ///
1895 /// Plain `code`, returning a plain integer, is provided because it is often more convenient.
1896 /// The returned value from `code()` is indeed also nonzero; use `code_nonzero()` when you want
1897 /// a type-level guarantee of nonzeroness.
1898 ///
1899 /// # Examples
1900 ///
1901 /// ```
1902 /// #![feature(exit_status_error)]
1903 ///
1904 /// # if cfg!(unix) {
1905 /// use std::num::NonZero;
1906 /// use std::process::Command;
1907 ///
1908 /// let bad = Command::new("false").status().unwrap().exit_ok().unwrap_err();
1909 /// assert_eq!(bad.code_nonzero().unwrap(), NonZero::new(1).unwrap());
1910 /// # } // cfg!(unix)
1911 /// ```
1912 #[must_use]
1913 pub fn code_nonzero(&self) -> Option<NonZero<i32>> {
1914 self.0.code()
1915 }
1916
1917 /// Converts an `ExitStatusError` (back) to an `ExitStatus`.
1918 #[must_use]
1919 pub fn into_status(&self) -> ExitStatus {
1920 ExitStatus(self.0.into())
1921 }
1922}
1923
1924#[unstable(feature = "exit_status_error", issue = "84908")]
1925impl From<ExitStatusError> for ExitStatus {
1926 fn from(error: ExitStatusError) -> Self {
1927 Self(error.0.into())
1928 }
1929}
1930
1931#[unstable(feature = "exit_status_error", issue = "84908")]
1932impl fmt::Display for ExitStatusError {
1933 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1934 write!(f, "process exited unsuccessfully: {}", self.into_status())
1935 }
1936}
1937
1938#[unstable(feature = "exit_status_error", issue = "84908")]
1939impl crate::error::Error for ExitStatusError {}
1940
1941/// This type represents the status code the current process can return
1942/// to its parent under normal termination.
1943///
1944/// `ExitCode` is intended to be consumed only by the standard library (via
1945/// [`Termination::report()`]). For forwards compatibility with potentially
1946/// unusual targets, this type currently does not provide `Eq`, `Hash`, or
1947/// access to the raw value. This type does provide `PartialEq` for
1948/// comparison, but note that there may potentially be multiple failure
1949/// codes, some of which will _not_ compare equal to `ExitCode::FAILURE`.
1950/// The standard library provides the canonical `SUCCESS` and `FAILURE`
1951/// exit codes as well as `From<u8> for ExitCode` for constructing other
1952/// arbitrary exit codes.
1953///
1954/// # Portability
1955///
1956/// Numeric values used in this type don't have portable meanings, and
1957/// different platforms may mask different amounts of them.
1958///
1959/// For the platform's canonical successful and unsuccessful codes, see
1960/// the [`SUCCESS`] and [`FAILURE`] associated items.
1961///
1962/// [`SUCCESS`]: ExitCode::SUCCESS
1963/// [`FAILURE`]: ExitCode::FAILURE
1964///
1965/// # Differences from `ExitStatus`
1966///
1967/// `ExitCode` is intended for terminating the currently running process, via
1968/// the `Termination` trait, in contrast to [`ExitStatus`], which represents the
1969/// termination of a child process. These APIs are separate due to platform
1970/// compatibility differences and their expected usage; it is not generally
1971/// possible to exactly reproduce an `ExitStatus` from a child for the current
1972/// process after the fact.
1973///
1974/// # Examples
1975///
1976/// `ExitCode` can be returned from the `main` function of a crate, as it implements
1977/// [`Termination`]:
1978///
1979/// ```
1980/// use std::process::ExitCode;
1981/// # fn check_foo() -> bool { true }
1982///
1983/// fn main() -> ExitCode {
1984/// if !check_foo() {
1985/// return ExitCode::from(42);
1986/// }
1987///
1988/// ExitCode::SUCCESS
1989/// }
1990/// ```
1991#[derive(Clone, Copy, Debug, PartialEq)]
1992#[stable(feature = "process_exitcode", since = "1.61.0")]
1993pub struct ExitCode(imp::ExitCode);
1994
1995/// Allows extension traits within `std`.
1996#[unstable(feature = "sealed", issue = "none")]
1997impl crate::sealed::Sealed for ExitCode {}
1998
1999#[stable(feature = "process_exitcode", since = "1.61.0")]
2000impl ExitCode {
2001 /// The canonical `ExitCode` for successful termination on this platform.
2002 ///
2003 /// Note that a `()`-returning `main` implicitly results in a successful
2004 /// termination, so there's no need to return this from `main` unless
2005 /// you're also returning other possible codes.
2006 #[stable(feature = "process_exitcode", since = "1.61.0")]
2007 pub const SUCCESS: ExitCode = ExitCode(imp::ExitCode::SUCCESS);
2008
2009 /// The canonical `ExitCode` for unsuccessful termination on this platform.
2010 ///
2011 /// If you're only returning this and `SUCCESS` from `main`, consider
2012 /// instead returning `Err(_)` and `Ok(())` respectively, which will
2013 /// return the same codes (but will also `eprintln!` the error).
2014 #[stable(feature = "process_exitcode", since = "1.61.0")]
2015 pub const FAILURE: ExitCode = ExitCode(imp::ExitCode::FAILURE);
2016
2017 /// Exit the current process with the given `ExitCode`.
2018 ///
2019 /// Note that this has the same caveats as [`process::exit()`][exit], namely that this function
2020 /// terminates the process immediately, so no destructors on the current stack or any other
2021 /// thread's stack will be run. Also see those docs for some important notes on interop with C
2022 /// code. If a clean shutdown is needed, it is recommended to simply return this ExitCode from
2023 /// the `main` function, as demonstrated in the [type documentation](#examples).
2024 ///
2025 /// # Differences from `process::exit()`
2026 ///
2027 /// `process::exit()` accepts any `i32` value as the exit code for the process; however, there
2028 /// are platforms that only use a subset of that value (see [`process::exit` platform-specific
2029 /// behavior][exit#platform-specific-behavior]). `ExitCode` exists because of this; only
2030 /// `ExitCode`s that are supported by a majority of our platforms can be created, so those
2031 /// problems don't exist (as much) with this method.
2032 ///
2033 /// # Examples
2034 ///
2035 /// ```
2036 /// #![feature(exitcode_exit_method)]
2037 /// # use std::process::ExitCode;
2038 /// # use std::fmt;
2039 /// # enum UhOhError { GenericProblem, Specific, WithCode { exit_code: ExitCode, _x: () } }
2040 /// # impl fmt::Display for UhOhError {
2041 /// # fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { unimplemented!() }
2042 /// # }
2043 /// // there's no way to gracefully recover from an UhOhError, so we just
2044 /// // print a message and exit
2045 /// fn handle_unrecoverable_error(err: UhOhError) -> ! {
2046 /// eprintln!("UH OH! {err}");
2047 /// let code = match err {
2048 /// UhOhError::GenericProblem => ExitCode::FAILURE,
2049 /// UhOhError::Specific => ExitCode::from(3),
2050 /// UhOhError::WithCode { exit_code, .. } => exit_code,
2051 /// };
2052 /// code.exit_process()
2053 /// }
2054 /// ```
2055 #[unstable(feature = "exitcode_exit_method", issue = "97100")]
2056 pub fn exit_process(self) -> ! {
2057 exit(self.to_i32())
2058 }
2059}
2060
2061impl ExitCode {
2062 // This is private/perma-unstable because ExitCode is opaque; we don't know that i32 will serve
2063 // all usecases, for example windows seems to use u32, unix uses the 8-15th bits of an i32, we
2064 // likely want to isolate users anything that could restrict the platform specific
2065 // representation of an ExitCode
2066 //
2067 // More info: https://internals.rust-lang.org/t/mini-pre-rfc-redesigning-process-exitstatus/5426
2068 /// Converts an `ExitCode` into an i32
2069 #[unstable(
2070 feature = "process_exitcode_internals",
2071 reason = "exposed only for libstd",
2072 issue = "none"
2073 )]
2074 #[inline]
2075 #[doc(hidden)]
2076 pub fn to_i32(self) -> i32 {
2077 self.0.as_i32()
2078 }
2079}
2080
2081/// The default value is [`ExitCode::SUCCESS`]
2082#[stable(feature = "process_exitcode_default", since = "1.75.0")]
2083impl Default for ExitCode {
2084 fn default() -> Self {
2085 ExitCode::SUCCESS
2086 }
2087}
2088
2089#[stable(feature = "process_exitcode", since = "1.61.0")]
2090impl From<u8> for ExitCode {
2091 /// Constructs an `ExitCode` from an arbitrary u8 value.
2092 fn from(code: u8) -> Self {
2093 ExitCode(imp::ExitCode::from(code))
2094 }
2095}
2096
2097impl AsInner<imp::ExitCode> for ExitCode {
2098 #[inline]
2099 fn as_inner(&self) -> &imp::ExitCode {
2100 &self.0
2101 }
2102}
2103
2104impl FromInner<imp::ExitCode> for ExitCode {
2105 fn from_inner(s: imp::ExitCode) -> ExitCode {
2106 ExitCode(s)
2107 }
2108}
2109
2110impl Child {
2111 /// Forces the child process to exit. If the child has already exited, `Ok(())`
2112 /// is returned.
2113 ///
2114 /// The mapping to [`ErrorKind`]s is not part of the compatibility contract of the function.
2115 ///
2116 /// This is equivalent to sending a SIGKILL on Unix platforms.
2117 ///
2118 /// # Examples
2119 ///
2120 /// ```no_run
2121 /// use std::process::Command;
2122 ///
2123 /// let mut command = Command::new("yes");
2124 /// if let Ok(mut child) = command.spawn() {
2125 /// child.kill().expect("command couldn't be killed");
2126 /// } else {
2127 /// println!("yes command didn't start");
2128 /// }
2129 /// ```
2130 ///
2131 /// [`ErrorKind`]: io::ErrorKind
2132 /// [`InvalidInput`]: io::ErrorKind::InvalidInput
2133 #[stable(feature = "process", since = "1.0.0")]
2134 #[cfg_attr(not(test), rustc_diagnostic_item = "child_kill")]
2135 pub fn kill(&mut self) -> io::Result<()> {
2136 self.handle.kill()
2137 }
2138
2139 /// Returns the OS-assigned process identifier associated with this child.
2140 ///
2141 /// # Examples
2142 ///
2143 /// ```no_run
2144 /// use std::process::Command;
2145 ///
2146 /// let mut command = Command::new("ls");
2147 /// if let Ok(child) = command.spawn() {
2148 /// println!("Child's ID is {}", child.id());
2149 /// } else {
2150 /// println!("ls command didn't start");
2151 /// }
2152 /// ```
2153 #[must_use]
2154 #[stable(feature = "process_id", since = "1.3.0")]
2155 #[cfg_attr(not(test), rustc_diagnostic_item = "child_id")]
2156 pub fn id(&self) -> u32 {
2157 self.handle.id()
2158 }
2159
2160 /// Waits for the child to exit completely, returning the status that it
2161 /// exited with. This function will continue to have the same return value
2162 /// after it has been called at least once.
2163 ///
2164 /// The stdin handle to the child process, if any, will be closed
2165 /// before waiting. This helps avoid deadlock: it ensures that the
2166 /// child does not block waiting for input from the parent, while
2167 /// the parent waits for the child to exit.
2168 ///
2169 /// # Examples
2170 ///
2171 /// ```no_run
2172 /// use std::process::Command;
2173 ///
2174 /// let mut command = Command::new("ls");
2175 /// if let Ok(mut child) = command.spawn() {
2176 /// child.wait().expect("command wasn't running");
2177 /// println!("Child has finished its execution!");
2178 /// } else {
2179 /// println!("ls command didn't start");
2180 /// }
2181 /// ```
2182 #[stable(feature = "process", since = "1.0.0")]
2183 pub fn wait(&mut self) -> io::Result<ExitStatus> {
2184 drop(self.stdin.take());
2185 self.handle.wait().map(ExitStatus)
2186 }
2187
2188 /// Attempts to collect the exit status of the child if it has already
2189 /// exited.
2190 ///
2191 /// This function will not block the calling thread and will only
2192 /// check to see if the child process has exited or not. If the child has
2193 /// exited then on Unix the process ID is reaped. This function is
2194 /// guaranteed to repeatedly return a successful exit status so long as the
2195 /// child has already exited.
2196 ///
2197 /// If the child has exited, then `Ok(Some(status))` is returned. If the
2198 /// exit status is not available at this time then `Ok(None)` is returned.
2199 /// If an error occurs, then that error is returned.
2200 ///
2201 /// Note that unlike `wait`, this function will not attempt to drop stdin.
2202 ///
2203 /// # Examples
2204 ///
2205 /// ```no_run
2206 /// use std::process::Command;
2207 ///
2208 /// let mut child = Command::new("ls").spawn()?;
2209 ///
2210 /// match child.try_wait() {
2211 /// Ok(Some(status)) => println!("exited with: {status}"),
2212 /// Ok(None) => {
2213 /// println!("status not ready yet, let's really wait");
2214 /// let res = child.wait();
2215 /// println!("result: {res:?}");
2216 /// }
2217 /// Err(e) => println!("error attempting to wait: {e}"),
2218 /// }
2219 /// # std::io::Result::Ok(())
2220 /// ```
2221 #[stable(feature = "process_try_wait", since = "1.18.0")]
2222 pub fn try_wait(&mut self) -> io::Result<Option<ExitStatus>> {
2223 Ok(self.handle.try_wait()?.map(ExitStatus))
2224 }
2225
2226 /// Simultaneously waits for the child to exit and collect all remaining
2227 /// output on the stdout/stderr handles, returning an `Output`
2228 /// instance.
2229 ///
2230 /// The stdin handle to the child process, if any, will be closed
2231 /// before waiting. This helps avoid deadlock: it ensures that the
2232 /// child does not block waiting for input from the parent, while
2233 /// the parent waits for the child to exit.
2234 ///
2235 /// By default, stdin, stdout and stderr are inherited from the parent.
2236 /// In order to capture the output into this `Result<Output>` it is
2237 /// necessary to create new pipes between parent and child. Use
2238 /// `stdout(Stdio::piped())` or `stderr(Stdio::piped())`, respectively.
2239 ///
2240 /// # Examples
2241 ///
2242 /// ```should_panic
2243 /// use std::process::{Command, Stdio};
2244 ///
2245 /// let child = Command::new("/bin/cat")
2246 /// .arg("file.txt")
2247 /// .stdout(Stdio::piped())
2248 /// .spawn()
2249 /// .expect("failed to execute child");
2250 ///
2251 /// let output = child
2252 /// .wait_with_output()
2253 /// .expect("failed to wait on child");
2254 ///
2255 /// assert!(output.status.success());
2256 /// ```
2257 ///
2258 #[stable(feature = "process", since = "1.0.0")]
2259 pub fn wait_with_output(mut self) -> io::Result<Output> {
2260 drop(self.stdin.take());
2261
2262 let (mut stdout, mut stderr) = (Vec::new(), Vec::new());
2263 match (self.stdout.take(), self.stderr.take()) {
2264 (None, None) => {}
2265 (Some(mut out), None) => {
2266 let res = out.read_to_end(&mut stdout);
2267 res.unwrap();
2268 }
2269 (None, Some(mut err)) => {
2270 let res = err.read_to_end(&mut stderr);
2271 res.unwrap();
2272 }
2273 (Some(out), Some(err)) => {
2274 let res = read2(out.inner, &mut stdout, err.inner, &mut stderr);
2275 res.unwrap();
2276 }
2277 }
2278
2279 let status = self.wait()?;
2280 Ok(Output { status, stdout, stderr })
2281 }
2282}
2283
2284/// Terminates the current process with the specified exit code.
2285///
2286/// This function will never return and will immediately terminate the current
2287/// process. The exit code is passed through to the underlying OS and will be
2288/// available for consumption by another process.
2289///
2290/// Note that because this function never returns, and that it terminates the
2291/// process, no destructors on the current stack or any other thread's stack
2292/// will be run. If a clean shutdown is needed it is recommended to only call
2293/// this function at a known point where there are no more destructors left
2294/// to run; or, preferably, simply return a type implementing [`Termination`]
2295/// (such as [`ExitCode`] or `Result`) from the `main` function and avoid this
2296/// function altogether:
2297///
2298/// ```
2299/// # use std::io::Error as MyError;
2300/// fn main() -> Result<(), MyError> {
2301/// // ...
2302/// Ok(())
2303/// }
2304/// ```
2305///
2306/// In its current implementation, this function will execute exit handlers registered with `atexit`
2307/// as well as other platform-specific exit handlers (e.g. `fini` sections of ELF shared objects).
2308/// This means that Rust requires that all exit handlers are safe to execute at any time. In
2309/// particular, if an exit handler cleans up some state that might be concurrently accessed by other
2310/// threads, it is required that the exit handler performs suitable synchronization with those
2311/// threads. (The alternative to this requirement would be to not run exit handlers at all, which is
2312/// considered undesirable. Note that returning from `main` also calls `exit`, so making `exit` an
2313/// unsafe operation is not an option.)
2314///
2315/// ## Platform-specific behavior
2316///
2317/// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit`
2318/// will be visible to a parent process inspecting the exit code. On most
2319/// Unix-like platforms, only the eight least-significant bits are considered.
2320///
2321/// For example, the exit code for this example will be `0` on Linux, but `256`
2322/// on Windows:
2323///
2324/// ```no_run
2325/// use std::process;
2326///
2327/// process::exit(0x0100);
2328/// ```
2329///
2330/// ### Safe interop with C code
2331///
2332/// On Unix, this function is currently implemented using the `exit` C function [`exit`][C-exit]. As
2333/// of C23, the C standard does not permit multiple threads to call `exit` concurrently. Rust
2334/// mitigates this with a lock, but if C code calls `exit`, that can still cause undefined behavior.
2335/// Note that returning from `main` is equivalent to calling `exit`.
2336///
2337/// Therefore, it is undefined behavior to have two concurrent threads perform the following
2338/// without synchronization:
2339/// - One thread calls Rust's `exit` function or returns from Rust's `main` function
2340/// - Another thread calls the C function `exit` or `quick_exit`, or returns from C's `main` function
2341///
2342/// Note that if a binary contains multiple copies of the Rust runtime (e.g., when combining
2343/// multiple `cdylib` or `staticlib`), they each have their own separate lock, so from the
2344/// perspective of code running in one of the Rust runtimes, the "outside" Rust code is basically C
2345/// code, and concurrent `exit` again causes undefined behavior.
2346///
2347/// Individual C implementations might provide more guarantees than the standard and permit concurrent
2348/// calls to `exit`; consult the documentation of your C implementation for details.
2349///
2350/// For some of the on-going discussion to make `exit` thread-safe in C, see:
2351/// - [Rust issue #126600](https://github.com/rust-lang/rust/issues/126600)
2352/// - [Austin Group Bugzilla (for POSIX)](https://austingroupbugs.net/view.php?id=1845)
2353/// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=31997)
2354///
2355/// [C-exit]: https://en.cppreference.com/w/c/program/exit
2356#[stable(feature = "rust1", since = "1.0.0")]
2357#[cfg_attr(not(test), rustc_diagnostic_item = "process_exit")]
2358pub fn exit(code: i32) -> ! {
2359 crate::rt::cleanup();
2360 crate::sys::os::exit(code)
2361}
2362
2363/// Terminates the process in an abnormal fashion.
2364///
2365/// The function will never return and will immediately terminate the current
2366/// process in a platform specific "abnormal" manner. As a consequence,
2367/// no destructors on the current stack or any other thread's stack
2368/// will be run, Rust IO buffers (eg, from `BufWriter`) will not be flushed,
2369/// and C stdio buffers will (on most platforms) not be flushed.
2370///
2371/// This is in contrast to the default behavior of [`panic!`] which unwinds
2372/// the current thread's stack and calls all destructors.
2373/// When `panic="abort"` is set, either as an argument to `rustc` or in a
2374/// crate's Cargo.toml, [`panic!`] and `abort` are similar. However,
2375/// [`panic!`] will still call the [panic hook] while `abort` will not.
2376///
2377/// If a clean shutdown is needed it is recommended to only call
2378/// this function at a known point where there are no more destructors left
2379/// to run.
2380///
2381/// The process's termination will be similar to that from the C `abort()`
2382/// function. On Unix, the process will terminate with signal `SIGABRT`, which
2383/// typically means that the shell prints "Aborted".
2384///
2385/// # Examples
2386///
2387/// ```no_run
2388/// use std::process;
2389///
2390/// fn main() {
2391/// println!("aborting");
2392///
2393/// process::abort();
2394///
2395/// // execution never gets here
2396/// }
2397/// ```
2398///
2399/// The `abort` function terminates the process, so the destructor will not
2400/// get run on the example below:
2401///
2402/// ```no_run
2403/// use std::process;
2404///
2405/// struct HasDrop;
2406///
2407/// impl Drop for HasDrop {
2408/// fn drop(&mut self) {
2409/// println!("This will never be printed!");
2410/// }
2411/// }
2412///
2413/// fn main() {
2414/// let _x = HasDrop;
2415/// process::abort();
2416/// // the destructor implemented for HasDrop will never get run
2417/// }
2418/// ```
2419///
2420/// [panic hook]: crate::panic::set_hook
2421#[stable(feature = "process_abort", since = "1.17.0")]
2422#[cold]
2423#[cfg_attr(not(test), rustc_diagnostic_item = "process_abort")]
2424pub fn abort() -> ! {
2425 crate::sys::abort_internal();
2426}
2427
2428/// Returns the OS-assigned process identifier associated with this process.
2429///
2430/// # Examples
2431///
2432/// ```no_run
2433/// use std::process;
2434///
2435/// println!("My pid is {}", process::id());
2436/// ```
2437#[must_use]
2438#[stable(feature = "getpid", since = "1.26.0")]
2439pub fn id() -> u32 {
2440 crate::sys::os::getpid()
2441}
2442
2443/// A trait for implementing arbitrary return types in the `main` function.
2444///
2445/// The C-main function only supports returning integers.
2446/// So, every type implementing the `Termination` trait has to be converted
2447/// to an integer.
2448///
2449/// The default implementations are returning `libc::EXIT_SUCCESS` to indicate
2450/// a successful execution. In case of a failure, `libc::EXIT_FAILURE` is returned.
2451///
2452/// Because different runtimes have different specifications on the return value
2453/// of the `main` function, this trait is likely to be available only on
2454/// standard library's runtime for convenience. Other runtimes are not required
2455/// to provide similar functionality.
2456#[cfg_attr(not(any(test, doctest)), lang = "termination")]
2457#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2458#[rustc_on_unimplemented(on(
2459 cause = "MainFunctionType",
2460 message = "`main` has invalid return type `{Self}`",
2461 label = "`main` can only return types that implement `{Termination}`"
2462))]
2463pub trait Termination {
2464 /// Is called to get the representation of the value as status code.
2465 /// This status code is returned to the operating system.
2466 #[stable(feature = "termination_trait_lib", since = "1.61.0")]
2467 fn report(self) -> ExitCode;
2468}
2469
2470#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2471impl Termination for () {
2472 #[inline]
2473 fn report(self) -> ExitCode {
2474 ExitCode::SUCCESS
2475 }
2476}
2477
2478#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2479impl Termination for ! {
2480 fn report(self) -> ExitCode {
2481 self
2482 }
2483}
2484
2485#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2486impl Termination for Infallible {
2487 fn report(self) -> ExitCode {
2488 match self {}
2489 }
2490}
2491
2492#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2493impl Termination for ExitCode {
2494 #[inline]
2495 fn report(self) -> ExitCode {
2496 self
2497 }
2498}
2499
2500#[stable(feature = "termination_trait_lib", since = "1.61.0")]
2501impl<T: Termination, E: fmt::Debug> Termination for Result<T, E> {
2502 fn report(self) -> ExitCode {
2503 match self {
2504 Ok(val: T) => val.report(),
2505 Err(err: E) => {
2506 io::attempt_print_to_stderr(args:format_args_nl!("Error: {err:?}"));
2507 ExitCode::FAILURE
2508 }
2509 }
2510 }
2511}
2512