rustix/
pid.rs

1//! The `Pid` type.
2
3#![allow(unsafe_code)]
4
5use crate::backend::c;
6use core::num::NonZeroI32;
7
8/// A process identifier as a raw integer.
9pub type RawPid = c::pid_t;
10
11/// `pid_t`—A non-zero Unix process ID.
12///
13/// This is a pid, and not a pidfd. It is not a file descriptor, and the
14/// process it refers to could disappear at any time and be replaced by
15/// another, unrelated, process.
16#[repr(transparent)]
17#[derive(Copy, Clone, Eq, PartialEq, Debug, Hash)]
18pub struct Pid(NonZeroI32);
19
20impl Pid {
21    /// A `Pid` corresponding to the init process (pid 1).
22    pub const INIT: Self = Self(match NonZeroI32::new(1) {
23        Some(n) => n,
24        None => panic!("unreachable"),
25    });
26
27    /// Converts a `RawPid` into a `Pid`.
28    ///
29    /// Returns `Some` for positive `RawPid`s. Otherwise, returns `None`.
30    ///
31    /// This is safe because a `Pid` is a number without any guarantees for the
32    /// kernel. Non-child `Pid`s are always racy for any syscalls, but can only
33    /// cause logic errors. If you want race-free access to or control of
34    /// non-child processes, please consider other mechanisms like [pidfd] on
35    /// Linux.
36    ///
37    /// [pidfd]: https://man7.org/linux/man-pages/man2/pidfd_open.2.html
38    #[inline]
39    pub const fn from_raw(raw: RawPid) -> Option<Self> {
40        if raw > 0 {
41            // SAFETY: We just checked that `raw > 0`.
42            unsafe { Some(Self::from_raw_unchecked(raw)) }
43        } else {
44            None
45        }
46    }
47
48    /// Converts a known positive `RawPid` into a `Pid`.
49    ///
50    /// # Safety
51    ///
52    /// The caller must guarantee `raw` is positive.
53    #[inline]
54    pub const unsafe fn from_raw_unchecked(raw: RawPid) -> Self {
55        debug_assert!(raw > 0);
56        Self(NonZeroI32::new_unchecked(raw))
57    }
58
59    /// Creates a `Pid` holding the ID of the given child process.
60    #[cfg(feature = "std")]
61    #[inline]
62    pub fn from_child(child: &std::process::Child) -> Self {
63        let id = child.id();
64        // SAFETY: We know the returned ID is valid because it came directly
65        // from an OS API.
66        unsafe { Self::from_raw_unchecked(id as i32) }
67    }
68
69    /// Converts a `Pid` into a `NonZeroI32`.
70    #[inline]
71    pub const fn as_raw_nonzero(self) -> NonZeroI32 {
72        self.0
73    }
74
75    /// Converts an `Option<Pid>` into a `RawPid`.
76    #[inline]
77    pub fn as_raw(pid: Option<Self>) -> RawPid {
78        pid.map_or(0, |pid| pid.0.get())
79    }
80
81    /// Test whether this pid represents the init process (pid 1).
82    #[inline]
83    pub const fn is_init(self) -> bool {
84        self.0.get() == Self::INIT.0.get()
85    }
86}
87
88#[test]
89fn test_sizes() {
90    use core::mem::transmute;
91
92    assert_eq_size!(RawPid, NonZeroI32);
93    assert_eq_size!(RawPid, Pid);
94    assert_eq_size!(RawPid, Option<Pid>);
95
96    // Rustix doesn't depend on `Option<Pid>` matching the ABI of a raw integer
97    // for correctness, but it should work nonetheless.
98    const_assert_eq!(0 as RawPid, unsafe {
99        transmute::<Option<Pid>, RawPid>(None)
100    });
101    const_assert_eq!(4567 as RawPid, unsafe {
102        transmute::<Option<Pid>, RawPid>(Some(Pid::from_raw_unchecked(4567)))
103    });
104}
rustix/pid.rs

rustix/
pid.rs
