std: Add Child::terminate as an alternative to Child::kill

Using SIGKILL to stop child processes doesn't always work well,
especially if a child process needs to free a file lock.

SIGTERM lets child processes cleanup before exiting, and it's usually a
better default. Note that the Unix `kill` utility sends SIGTERM by
default.

Author: peterdelevoryas

library/std/src/process.rs

@@ -2019,6 +2019,36 @@ impl Child {
         self.handle.kill()
     }
 
+    /// Ask a child process to exit.
+    ///
+    /// On Unix platforms this sends SIGTERM, which can be blocked, handled, or ignored.
+    ///
+    /// On Windows, and other platforms where there isn't a corrollary to SIGTERM, this just
+    /// executes `Child::kill`.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```no_run
+    /// #![feature(process_terminate)]
+    /// use std::process::Command;
+    ///
+    /// let mut command = Command::new("yes");
+    /// if let Ok(mut child) = command.spawn() {
+    ///     if let Err(e) = child.terminate() {
+    ///         println!("Child didn't respond to terminate");
+    ///         child.kill().expect("command couldn't be killed");
+    ///     }
+    /// } else {
+    ///     println!("yes command didn't start");
+    /// }
+    /// ```
+    #[unstable(feature = "process_terminate", issue = "none")]
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.handle.terminate()
+    }
+
     /// Returns the OS-assigned process identifier associated with this child.
     ///
     /// # Examples

library/std/src/process/tests.rs

@@ -1,6 +1,6 @@
 use crate::io::prelude::*;
 
-use super::{Command, Output, Stdio};
+use super::{Child, Command, Output, Stdio};
 use crate::io::{BorrowedBuf, ErrorKind};
 use crate::mem::MaybeUninit;
 use crate::str;
@@ -61,11 +61,13 @@ fn exit_reported_right() {
 fn signal_reported_right() {
     use crate::os::unix::process::ExitStatusExt;
 
-    let mut p = shell_cmd().arg("-c").arg("read a").stdin(Stdio::piped()).spawn().unwrap();
-    p.kill().unwrap();
-    match p.wait().unwrap().signal() {
-        Some(9) => {}
-        result => panic!("not terminated by signal 9 (instead, {result:?})"),
+    for (kill, signal) in [Child::kill, Child::terminate].into_iter().zip([9, 15]) {
+        let mut p = shell_cmd().arg("-c").arg("read a").stdin(Stdio::piped()).spawn().unwrap();
+        kill(&mut p).unwrap();
+        match p.wait().unwrap().signal() {
+            Some(got) if got == signal => {}
+            result => panic!("not terminated by signal {signal} (instead, {result:?})"),
+        }
     }
 }
 
@@ -715,15 +717,17 @@ fn run_canonical_bat_script() {
 
 #[test]
 fn terminate_exited_process() {
-    let mut cmd = if cfg!(target_os = "android") {
-        let mut p = shell_cmd();
-        p.args(&["-c", "true"]);
-        p
-    } else {
-        known_command()
-    };
-    let mut p = cmd.stdout(Stdio::null()).spawn().unwrap();
-    p.wait().unwrap();
-    assert!(p.kill().is_ok());
-    assert!(p.kill().is_ok());
+    for kill in [Child::kill, Child::terminate] {
+        let mut cmd = if cfg!(target_os = "android") {
+            let mut p = shell_cmd();
+            p.args(&["-c", "true"]);
+            p
+        } else {
+            known_command()
+        };
+        let mut p = cmd.stdout(Stdio::null()).spawn().unwrap();
+        p.wait().unwrap();
+        assert!(kill(&mut p).is_ok());
+        assert!(kill(&mut p).is_ok());
+    }
 }

library/std/src/sys/unix/process/process_fuchsia.rs

@@ -165,6 +165,10 @@ impl Process {
         Ok(())
     }
 
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.kill()
+    }
+
     pub fn wait(&mut self) -> io::Result<ExitStatus> {
         use crate::sys::process::zircon::*;
 

library/std/src/sys/unix/process/process_unix.rs

@@ -812,13 +812,21 @@ impl Process {
     }
 
     pub fn kill(&mut self) -> io::Result<()> {
+        self.send_signal(libc::SIGKILL)
+    }
+
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.send_signal(libc::SIGTERM)
+    }
+
+    fn send_signal(&mut self, signal: c_int) -> io::Result<()> {
         // If we've already waited on this process then the pid can be recycled
         // and used for another process, and we probably shouldn't be killing
         // random processes, so return Ok because the process has exited already.
         if self.status.is_some() {
             Ok(())
         } else {
-            cvt(unsafe { libc::kill(self.pid, libc::SIGKILL) }).map(drop)
+            cvt(unsafe { libc::kill(self.pid, signal) }).map(drop)
         }
     }
 

library/std/src/sys/unix/process/process_vxworks.rs

@@ -142,13 +142,21 @@ impl Process {
     }
 
     pub fn kill(&mut self) -> io::Result<()> {
+        self.send_signal(libc::SIGKILL)
+    }
+
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.send_signal(libc::SIGTERM)
+    }
+
+    fn send_signal(&mut self, signal: c_int) -> io::Result<()> {
         // If we've already waited on this process then the pid can be recycled
         // and used for another process, and we probably shouldn't be killing
         // random processes, so return Ok because the process has exited already.
         if self.status.is_some() {
             Ok(())
         } else {
-            cvt(unsafe { libc::kill(self.pid, libc::SIGKILL) }).map(drop)
+            cvt(unsafe { libc::kill(self.pid, signal) }).map(drop)
         }
     }
 

library/std/src/sys/unsupported/process.rs

@@ -207,6 +207,10 @@ impl Process {
         self.0
     }
 
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.0
+    }
+
     pub fn wait(&mut self) -> io::Result<ExitStatus> {
         self.0
     }

library/std/src/sys/windows/process.rs

@@ -656,6 +656,10 @@ impl Process {
         Ok(())
     }
 
+    pub fn terminate(&mut self) -> io::Result<()> {
+        self.kill()
+    }
+
     pub fn id(&self) -> u32 {
         unsafe { c::GetProcessId(self.handle.as_raw_handle()) as u32 }
     }