Clarify Command::new behavior if passed programs with arguments · model-checking/verify-rust-std@02bf152 (original) (raw)

Original file line number Diff line number Diff line change
@@ -629,6 +629,25 @@ impl Command {
629 629 /// .spawn()
630 630 /// .expect("sh command failed to start");
631 631 /// ```
632 + ///
633 + /// # Caveats
634 + ///
635 + /// [`Command::new`] is only intended to accept the path of the program. If you pass a program
636 + /// path along with arguments like `Command::new("ls -l").spawn()`, it will try to search for
637 + /// `ls -l` literally. The arguments need to be passed separately, such as via [`arg`] or
638 + /// [`args`].
639 + ///
640 + /// ```no_run
641 + /// use std::process::Command;
642 + ///
643 + /// Command::new("ls")
644 + /// .arg("-l") // arg passed separately
645 + /// .spawn()
646 + /// .expect("ls command failed to start");
647 + /// ```
648 + ///
649 + /// [`arg`]: Self::arg
650 + /// [`args`]: Self::args
632 651 #[stable(feature = "process", since = "1.0.0")]
633 652 pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
634 653 Command { inner: imp::Command::new(program.as_ref()) }