Skip to content

Commit 694be09

Browse files
Aaron1011voidc
authored andcommitted
Add Linux-specific pidfd process extensions
Background: Over the last year, pidfd support was added to the Linux kernel. This allows interacting with other processes. In particular, this allows waiting on a child process with a timeout in a race-free way, bypassing all of the awful signal-handler tricks that are usually required. Pidfds can be obtained for a child process (as well as any other process) via the `pidfd_open` syscall. Unfortunately, this requires several conditions to hold in order to be race-free (i.e. the pid is not reused). Per `man pidfd_open`: ``` · the disposition of SIGCHLD has not been explicitly set to SIG_IGN (see sigaction(2)); · the SA_NOCLDWAIT flag was not specified while establishing a han‐ dler for SIGCHLD or while setting the disposition of that signal to SIG_DFL (see sigaction(2)); and · the zombie process was not reaped elsewhere in the program (e.g., either by an asynchronously executed signal handler or by wait(2) or similar in another thread). If any of these conditions does not hold, then the child process (along with a PID file descriptor that refers to it) should instead be created using clone(2) with the CLONE_PIDFD flag. ``` Sadly, these conditions are impossible to guarantee once any libraries are used. For example, C code runnng in a different thread could call `wait()`, which is impossible to detect from Rust code trying to open a pidfd. While pid reuse issues should (hopefully) be rare in practice, we can do better. By passing the `CLONE_PIDFD` flag to `clone()` or `clone3()`, we can obtain a pidfd for the child process in a guaranteed race-free manner. This PR: This PR adds Linux-specific process extension methods to allow obtaining pidfds for processes spawned via the standard `Command` API. Other than being made available to user code, the standard library does not make use of these pidfds in any way. In particular, the implementation of `Child::wait` is completely unchanged. Two Linux-specific helper methods are added: `CommandExt::create_pidfd` and `ChildExt::pidfd`. These methods are intended to serve as a building block for libraries to build higher-level abstractions - in particular, waiting on a process with a timeout. I've included a basic test, which verifies that pidfds are created iff the `create_pidfd` method is used. This test is somewhat special - it should always succeed on systems with the `clone3` system call available, and always fail on systems without `clone3` available. I'm not sure how to best ensure this programatically. This PR relies on the newer `clone3` system call to pass the `CLONE_FD`, rather than the older `clone` system call. `clone3` was added to Linux in the same release as pidfds, so this shouldn't unnecessarily limit the kernel versions that this code supports. Unresolved questions: * What should the name of the feature gate be for these newly added methods? * Should the `pidfd` method distinguish between an error occurring and `create_pidfd` not being called?
1 parent 9f2e753 commit 694be09

File tree

6 files changed

+186
-7
lines changed

6 files changed

+186
-7
lines changed

library/std/src/os/linux/mod.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44
#![doc(cfg(target_os = "linux"))]
55

66
pub mod fs;
7+
pub mod process;
78
pub mod raw;

library/std/src/os/linux/process.rs

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
//! Linux-specific extensions to primitives in the `std::process` module.
2+
3+
#![unstable(feature = "linux_pidfd", issue = "none")]
4+
5+
use crate::process;
6+
use crate::sys_common::AsInnerMut;
7+
use crate::io::Result;
8+
9+
/// Os-specific extensions to [`process::Child`]
10+
///
11+
/// [`process::Child`]: crate::process::Child
12+
pub trait ChildExt {
13+
/// Obtains the pidfd created for this child process, if available.
14+
///
15+
/// A pidfd will only ever be available if `create_pidfd(true)` was called
16+
/// when the corresponding `Command` was created.
17+
///
18+
/// Even if `create_pidfd(true)` is called, a pidfd may not be available
19+
/// due to an older version of Linux being in use, or if
20+
/// some other error occured.
21+
///
22+
/// See `man pidfd_open` for more details about pidfds.
23+
fn pidfd(&self) -> Result<i32>;
24+
}
25+
26+
/// Os-specific extensions to [`process::Command`]
27+
///
28+
/// [`process::Command`]: crate::process::Command
29+
pub trait CommandExt {
30+
/// Sets whether or this `Command` will attempt to create a pidfd
31+
/// for the child. If this method is never called, a pidfd will
32+
/// not be crated.
33+
///
34+
/// The pidfd can be retrieved from the child via [`ChildExt::pidfd`]
35+
///
36+
/// A pidfd will only be created if it is possible to do so
37+
/// in a guaranteed race-free manner (e.g. if the `clone3` system call is
38+
/// supported). Otherwise, [`ChildExit::pidfd`] will return an error.
39+
fn create_pidfd(&mut self, val: bool) -> &mut process::Command;
40+
}
41+
42+
impl CommandExt for process::Command {
43+
fn create_pidfd(&mut self, val: bool) -> &mut process::Command {
44+
self.as_inner_mut().create_pidfd(val);
45+
self
46+
}
47+
}

library/std/src/process.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};
166166
/// [`wait`]: Child::wait
167167
#[stable(feature = "process", since = "1.0.0")]
168168
pub struct Child {
169-
handle: imp::Process,
169+
pub(crate) handle: imp::Process,
170170

171171
/// The handle for writing to the child's standard input (stdin), if it has
172172
/// been captured. To avoid partially moving

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ pub struct Command {
7979
stdin: Option<Stdio>,
8080
stdout: Option<Stdio>,
8181
stderr: Option<Stdio>,
82+
pub(crate) make_pidfd: bool,
8283
}
8384

8485
// Create a new type for argv, so that we can make it `Send` and `Sync`
@@ -141,6 +142,7 @@ impl Command {
141142
stdin: None,
142143
stdout: None,
143144
stderr: None,
145+
make_pidfd: false,
144146
}
145147
}
146148

@@ -176,6 +178,10 @@ impl Command {
176178
pub fn groups(&mut self, groups: &[gid_t]) {
177179
self.groups = Some(Box::from(groups));
178180
}
181+
182+
pub fn create_pidfd(&mut self, val: bool) {
183+
self.make_pidfd = val;
184+
}
179185

180186
pub fn saw_nul(&self) -> bool {
181187
self.saw_nul

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

Lines changed: 104 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ use crate::ptr;
88
use crate::sys;
99
use crate::sys::cvt;
1010
use crate::sys::process::process_common::*;
11+
use crate::sync::atomic::{AtomicBool, Ordering};
12+
13+
#[cfg(target_os = "linux")]
14+
use crate::sys::weak::syscall;
1115

1216
#[cfg(any(
1317
target_os = "macos",
@@ -61,7 +65,8 @@ impl Command {
6165
// a lock any more because the parent won't do anything and the child is
6266
// in its own process. Thus the parent drops the lock guard while the child
6367
// forgets it to avoid unlocking it on a new thread, which would be invalid.
64-
let (env_lock, pid) = unsafe { (sys::os::env_read_lock(), cvt(libc::fork())?) };
68+
let env_lock = sys::os::env_read_lock();
69+
let (pid, pidfd) = self.do_fork()?;
6570

6671
if pid == 0 {
6772
crate::panic::always_abort();
@@ -90,7 +95,7 @@ impl Command {
9095
drop(env_lock);
9196
drop(output);
9297

93-
let mut p = Process { pid, status: None };
98+
let mut p = Process { pid, status: None, pidfd };
9499
let mut bytes = [0; 8];
95100

96101
// loop to handle EINTR
@@ -122,6 +127,85 @@ impl Command {
122127
}
123128
}
124129

130+
// Attempts to fork the process. If successful, returns
131+
// Ok((0, -1)) in the child, and Ok((child_pid, child_pidfd)) in the parent.
132+
fn do_fork(&mut self) -> Result<(libc::c_long, libc::pid_t), io::Error> {
133+
// If we fail to create a pidfd for any reason, this will
134+
// stay as -1, which indicates an error
135+
let mut pidfd: libc::pid_t = -1;
136+
137+
// On Linux, attempt to use the `clone3` syscall, which
138+
// supports more argument (in prarticular, the ability to create a pidfd).
139+
// If this fails, we will fall through this block to a call to `fork()`
140+
cfg_if::cfg_if! {
141+
if #[cfg(target_os = "linux")] {
142+
static HAS_CLONE3: AtomicBool = AtomicBool::new(true);
143+
144+
const CLONE_PIDFD: u64 = 0x00001000;
145+
146+
#[repr(C)]
147+
struct clone_args {
148+
flags: u64,
149+
pidfd: u64,
150+
child_tid: u64,
151+
parent_tid: u64,
152+
exit_signal: u64,
153+
stack: u64,
154+
stack_size: u64,
155+
tls: u64,
156+
set_tid: u64,
157+
set_tid_size: u64,
158+
cgroup: u64,
159+
}
160+
161+
syscall! {
162+
fn clone3(cl_args: *mut clone_args, len: libc::size_t) -> libc::c_long
163+
}
164+
165+
if HAS_CLONE3.load(Ordering::Relaxed) {
166+
let mut flags = 0;
167+
if self.make_pidfd {
168+
flags |= CLONE_PIDFD;
169+
}
170+
171+
let mut args = clone_args {
172+
flags,
173+
pidfd: &mut pidfd as *mut libc::pid_t as u64,
174+
child_tid: 0,
175+
parent_tid: 0,
176+
exit_signal: libc::SIGCHLD as u64,
177+
stack: 0,
178+
stack_size: 0,
179+
tls: 0,
180+
set_tid: 0,
181+
set_tid_size: 0,
182+
cgroup: 0
183+
};
184+
185+
let args_ptr = &mut args as *mut clone_args;
186+
let args_size = crate::mem::size_of::<clone_args>();
187+
188+
let res = cvt(unsafe { clone3(args_ptr, args_size) });
189+
match res {
190+
Ok(n) => return Ok((n, pidfd)),
191+
Err(e) => match e.raw_os_error() {
192+
// Multiple threads can race to execute this store,
193+
// but that's fine - that just means that multiple threads
194+
// will have tried and failed to execute the same syscall,
195+
// with no other side effects.
196+
Some(libc::ENOSYS) => HAS_CLONE3.store(false, Ordering::Relaxed),
197+
_ => return Err(e)
198+
}
199+
}
200+
}
201+
}
202+
}
203+
// If we get here, we are either not on Linux,
204+
// or we are on Linux and the 'clone3' syscall does not exist
205+
cvt(unsafe { libc::fork() }.into()).map(|res| (res, pidfd))
206+
}
207+
208+
125209
pub fn exec(&mut self, default: Stdio) -> io::Error {
126210
let envp = self.capture_env();
127211

@@ -276,8 +360,6 @@ impl Command {
276360
#[cfg(not(any(
277361
target_os = "macos",
278362
target_os = "freebsd",
279-
all(target_os = "linux", target_env = "gnu"),
280-
all(target_os = "linux", target_env = "musl"),
281363
)))]
282364
fn posix_spawn(
283365
&mut self,
@@ -292,8 +374,6 @@ impl Command {
292374
#[cfg(any(
293375
target_os = "macos",
294376
target_os = "freebsd",
295-
all(target_os = "linux", target_env = "gnu"),
296-
all(target_os = "linux", target_env = "musl"),
297377
))]
298378
fn posix_spawn(
299379
&mut self,
@@ -441,6 +521,12 @@ impl Command {
441521
pub struct Process {
442522
pid: pid_t,
443523
status: Option<ExitStatus>,
524+
// On Linux, stores the pidfd created for this child.
525+
// This is -1 if the user did not request pidfd creation,
526+
// or if the pidfd could not be created for some reason
527+
// (e.g. the `clone3` syscall was not available).
528+
#[cfg(target_os = "linux")]
529+
pidfd: libc::c_int,
444530
}
445531

446532
impl Process {
@@ -580,6 +666,18 @@ impl ExitStatusError {
580666
}
581667
}
582668

669+
#[cfg(target_os = "linux")]
670+
#[unstable(feature = "linux_pidfd", issue = "none")]
671+
impl crate::os::linux::process::ChildExt for crate::process::Child {
672+
fn pidfd(&self) -> crate::io::Result<i32> {
673+
if self.handle.pidfd > 0 {
674+
Ok(self.handle.pidfd)
675+
} else {
676+
Err(crate::io::Error::from(crate::io::ErrorKind::Other))
677+
}
678+
}
679+
}
680+
583681
#[cfg(test)]
584682
#[path = "process_unix/tests.rs"]
585683
mod tests;
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// run-pass
2+
// linux-only - pidfds are a linux-specific concept
3+
4+
#![feature(linux_pidfd)]
5+
use std::os::linux::process::{CommandExt, ChildExt};
6+
use std::process::Command;
7+
8+
fn main() {
9+
// We don't assert the precise value, since the standard libarary
10+
// may be opened other file descriptors before our code ran.
11+
let _ = Command::new("echo")
12+
.create_pidfd(true)
13+
.spawn()
14+
.unwrap()
15+
.pidfd().expect("failed to obtain pidfd");
16+
17+
let _ = Command::new("echo")
18+
.create_pidfd(false)
19+
.spawn()
20+
.unwrap()
21+
.pidfd().expect_err("pidfd should not have been created when create_pid(false) is set");
22+
23+
let _ = Command::new("echo")
24+
.spawn()
25+
.unwrap()
26+
.pidfd().expect_err("pidfd should not have been created");
27+
}

0 commit comments

Comments
 (0)