|
| 1 | +//! FreeBSD-specific extensions to primitives in the [`std::process`] module. |
| 2 | +//! |
| 3 | +//! [`std::process`]: crate::process |
| 4 | +// FIXME this file is identical to src/os/linux/process, except for documentation. Can we combine |
| 5 | +// the two? |
| 6 | + |
| 7 | +#![unstable(feature = "linux_pidfd", issue = "82971")] |
| 8 | + |
| 9 | +use crate::io::Result; |
| 10 | +use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; |
| 11 | +use crate::process::{self, ExitStatus}; |
| 12 | +use crate::sealed::Sealed; |
| 13 | +use crate::sys::{AsInner, AsInnerMut, FromInner, IntoInner}; |
| 14 | +#[cfg(not(doc))] |
| 15 | +use crate::sys::{fd::FileDesc, freebsd::pidfd::PidFd as InnerPidFd}; |
| 16 | + |
| 17 | +#[cfg(doc)] |
| 18 | +struct InnerPidFd; |
| 19 | + |
| 20 | +/// This type represents a file descriptor that refers to a process. |
| 21 | +/// |
| 22 | +/// A `PidFd` can be obtained by setting the corresponding option on [`Command`] |
| 23 | +/// with [`create_pidfd`]. Subsequently, the created pidfd can be retrieved |
| 24 | +/// from the [`Child`] by calling [`pidfd`] or [`into_pidfd`]. |
| 25 | +/// |
| 26 | +/// Example: |
| 27 | +/// ```no_run |
| 28 | +/// #![feature(linux_pidfd)] |
| 29 | +/// use std::os::freebsd::process::{CommandExt, ChildExt}; |
| 30 | +/// use std::process::Command; |
| 31 | +/// |
| 32 | +/// let mut child = Command::new("echo") |
| 33 | +/// .create_pidfd(true) |
| 34 | +/// .spawn() |
| 35 | +/// .expect("Failed to spawn child"); |
| 36 | +/// |
| 37 | +/// let pidfd = child |
| 38 | +/// .into_pidfd() |
| 39 | +/// .expect("Failed to retrieve pidfd"); |
| 40 | +/// |
| 41 | +/// // The file descriptor will be closed when `pidfd` is dropped. |
| 42 | +/// ``` |
| 43 | +/// Refer to the man page of [`pdfork(2)`] for further details. |
| 44 | +/// |
| 45 | +/// [`Command`]: process::Command |
| 46 | +/// [`create_pidfd`]: CommandExt::create_pidfd |
| 47 | +/// [`Child`]: process::Child |
| 48 | +/// [`pidfd`]: fn@ChildExt::pidfd |
| 49 | +/// [`into_pidfd`]: ChildExt::into_pidfd |
| 50 | +/// [`pdfork(2)`]: https://man.freebsd.org/cgi/man.cgi?query=pdfork |
| 51 | +#[derive(Debug)] |
| 52 | +#[repr(transparent)] |
| 53 | +pub struct PidFd { |
| 54 | + inner: InnerPidFd, |
| 55 | +} |
| 56 | + |
| 57 | +impl PidFd { |
| 58 | + /// Forces the child process to exit. |
| 59 | + /// |
| 60 | + /// Unlike [`Child::kill`] it is possible to attempt to kill |
| 61 | + /// reaped children since PidFd does not suffer from pid recycling |
| 62 | + /// races. But doing so will return an Error. |
| 63 | + /// |
| 64 | + /// [`Child::kill`]: process::Child::kill |
| 65 | + pub fn kill(&self) -> Result<()> { |
| 66 | + self.inner.kill() |
| 67 | + } |
| 68 | + |
| 69 | + /// Waits for the child to exit completely, returning the status that it exited with. |
| 70 | + pub fn wait(&self) -> Result<ExitStatus> { |
| 71 | + self.inner.wait().map(FromInner::from_inner) |
| 72 | + } |
| 73 | + |
| 74 | + /// Attempts to collect the exit status of the child if it has already exited. |
| 75 | + pub fn try_wait(&self) -> Result<Option<ExitStatus>> { |
| 76 | + Ok(self.inner.try_wait()?.map(FromInner::from_inner)) |
| 77 | + } |
| 78 | +} |
| 79 | + |
| 80 | +impl AsInner<InnerPidFd> for PidFd { |
| 81 | + #[inline] |
| 82 | + fn as_inner(&self) -> &InnerPidFd { |
| 83 | + &self.inner |
| 84 | + } |
| 85 | +} |
| 86 | + |
| 87 | +impl FromInner<InnerPidFd> for PidFd { |
| 88 | + fn from_inner(inner: InnerPidFd) -> PidFd { |
| 89 | + PidFd { inner } |
| 90 | + } |
| 91 | +} |
| 92 | + |
| 93 | +impl IntoInner<InnerPidFd> for PidFd { |
| 94 | + fn into_inner(self) -> InnerPidFd { |
| 95 | + self.inner |
| 96 | + } |
| 97 | +} |
| 98 | + |
| 99 | +impl AsRawFd for PidFd { |
| 100 | + #[inline] |
| 101 | + fn as_raw_fd(&self) -> RawFd { |
| 102 | + self.as_inner().as_inner().as_raw_fd() |
| 103 | + } |
| 104 | +} |
| 105 | + |
| 106 | +impl FromRawFd for PidFd { |
| 107 | + unsafe fn from_raw_fd(fd: RawFd) -> Self { |
| 108 | + Self::from_inner(InnerPidFd::from_raw_fd(fd)) |
| 109 | + } |
| 110 | +} |
| 111 | + |
| 112 | +impl IntoRawFd for PidFd { |
| 113 | + fn into_raw_fd(self) -> RawFd { |
| 114 | + self.into_inner().into_inner().into_raw_fd() |
| 115 | + } |
| 116 | +} |
| 117 | + |
| 118 | +impl AsFd for PidFd { |
| 119 | + fn as_fd(&self) -> BorrowedFd<'_> { |
| 120 | + self.as_inner().as_inner().as_fd() |
| 121 | + } |
| 122 | +} |
| 123 | + |
| 124 | +impl From<OwnedFd> for PidFd { |
| 125 | + fn from(fd: OwnedFd) -> Self { |
| 126 | + Self::from_inner(InnerPidFd::from_inner(FileDesc::from_inner(fd))) |
| 127 | + } |
| 128 | +} |
| 129 | + |
| 130 | +impl From<PidFd> for OwnedFd { |
| 131 | + fn from(pid_fd: PidFd) -> Self { |
| 132 | + pid_fd.into_inner().into_inner().into_inner() |
| 133 | + } |
| 134 | +} |
| 135 | + |
| 136 | +/// Os-specific extensions for [`Child`] |
| 137 | +/// |
| 138 | +/// [`Child`]: process::Child |
| 139 | +pub trait ChildExt: Sealed { |
| 140 | + /// Obtains a reference to the [`PidFd`] created for this [`Child`], if available. |
| 141 | + /// |
| 142 | + /// A pidfd will only be available if its creation was requested with |
| 143 | + /// [`create_pidfd`] when the corresponding [`Command`] was created. |
| 144 | + /// |
| 145 | + /// Even if requested, a pidfd may not be available if some other error occurred. |
| 146 | + /// |
| 147 | + /// [`Command`]: process::Command |
| 148 | + /// [`create_pidfd`]: CommandExt::create_pidfd |
| 149 | + /// [`Child`]: process::Child |
| 150 | + fn pidfd(&self) -> Result<&PidFd>; |
| 151 | + |
| 152 | + /// Returns the [`PidFd`] created for this [`Child`], if available. |
| 153 | + /// Otherwise self is returned. |
| 154 | + /// |
| 155 | + /// A pidfd will only be available if its creation was requested with |
| 156 | + /// [`create_pidfd`] when the corresponding [`Command`] was created. |
| 157 | + /// |
| 158 | + /// Taking ownership of the PidFd consumes the Child to avoid pid reuse |
| 159 | + /// races. Use [`pidfd`] and [`BorrowedFd::try_clone_to_owned`] if |
| 160 | + /// you don't want to disassemble the Child yet. |
| 161 | + /// |
| 162 | + /// [`Command`]: process::Command |
| 163 | + /// [`create_pidfd`]: CommandExt::create_pidfd |
| 164 | + /// [`pidfd`]: ChildExt::pidfd |
| 165 | + /// [`Child`]: process::Child |
| 166 | + fn into_pidfd(self) -> crate::result::Result<PidFd, Self> |
| 167 | + where |
| 168 | + Self: Sized; |
| 169 | +} |
| 170 | + |
| 171 | +/// Os-specific extensions for [`Command`] |
| 172 | +/// |
| 173 | +/// [`Command`]: process::Command |
| 174 | +pub trait CommandExt: Sealed { |
| 175 | + /// Sets whether a [`PidFd`](struct@PidFd) should be created for the [`Child`] |
| 176 | + /// spawned by this [`Command`]. |
| 177 | + /// By default, no pidfd will be created. |
| 178 | + /// |
| 179 | + /// The pidfd can be retrieved from the child with [`pidfd`] or [`into_pidfd`]. |
| 180 | + /// |
| 181 | + /// A pidfd will only be created if it is possible to do so |
| 182 | + /// in a guaranteed race-free manner. Otherwise, [`pidfd`] will return an error. |
| 183 | + /// |
| 184 | + /// If a pidfd has been successfully created and not been taken from the `Child` |
| 185 | + /// then calls to `kill()`, `wait()` and `try_wait()` will use the pidfd |
| 186 | + /// instead of the pid. This can prevent pid recycling races, e.g. |
| 187 | + /// those caused by rogue libraries in the same process prematurely reaping |
| 188 | + /// zombie children via `waitpid(-1, ...)` calls. |
| 189 | + /// |
| 190 | + /// [`Command`]: process::Command |
| 191 | + /// [`Child`]: process::Child |
| 192 | + /// [`pidfd`]: fn@ChildExt::pidfd |
| 193 | + /// [`into_pidfd`]: ChildExt::into_pidfd |
| 194 | + fn create_pidfd(&mut self, val: bool) -> &mut process::Command; |
| 195 | +} |
| 196 | + |
| 197 | +impl CommandExt for process::Command { |
| 198 | + fn create_pidfd(&mut self, val: bool) -> &mut process::Command { |
| 199 | + self.as_inner_mut().create_pidfd(val); |
| 200 | + self |
| 201 | + } |
| 202 | +} |
0 commit comments