New upstream version 1.64.0+dfsg1

[rustc.git] / library / std / src / os / unix / process.rs

diff --git a/library/std/src/os/unix/process.rs b/library/std/src/os/unix/process.rs
index 5065530e8d4d003b8e373aed9ba4bcfa5e7a0ff1..09b2bfe39f094d6c50ca4312202ecbedc3321ba4 100644 (file)
--- a/library/std/src/os/unix/process.rs
+++ b/library/std/src/os/unix/process.rs
@@ -148,9 +148,36 @@ pub trait CommandExt: Sealed {
     where
         S: AsRef<OsStr>;
 
-    /// Sets the process group ID of the child process. Translates to a `setpgid` call in the child
-    /// process.
-    #[unstable(feature = "process_set_process_group", issue = "93857")]
+    /// Sets the process group ID (PGID) of the child process. Equivalent to a
+    /// `setpgid` call in the child process, but may be more efficient.
+    ///
+    /// Process groups determine which processes receive signals.
+    ///
+    /// # Examples
+    ///
+    /// Pressing Ctrl-C in a terminal will send SIGINT to all processes in
+    /// the current foreground process group. By spawning the `sleep`
+    /// subprocess in a new process group, it will not receive SIGINT from the
+    /// terminal.
+    ///
+    /// The parent process could install a signal handler and manage the
+    /// subprocess on its own terms.
+    ///
+    /// A process group ID of 0 will use the process ID as the PGID.
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    /// use std::os::unix::process::CommandExt;
+    ///
+    /// Command::new("sleep")
+    ///     .arg("10")
+    ///     .process_group(0)
+    ///     .spawn()?
+    ///     .wait()?;
+    /// #
+    /// # Ok::<_, Box<dyn std::error::Error>>(())
+    /// ```
+    #[stable(feature = "process_set_process_group", since = "1.64.0")]
     fn process_group(&mut self, pgroup: i32) -> &mut process::Command;
 }