1 | //! The [`pidfd_getfd`] function and supporting types. |
2 | |
3 | #![allow (unsafe_code)] |
4 | use crate::fd::OwnedFd; |
5 | use crate::{backend, io}; |
6 | use backend::fd::{AsFd, RawFd}; |
7 | |
8 | /// Raw file descriptor in another process. |
9 | /// |
10 | /// A distinct type alias is used here to inform the user that normal file |
11 | /// descriptors from the calling process should not be used. The provided file |
12 | /// descriptor is used by the kernel as the index into the file descriptor |
13 | /// table of an entirely different process. |
14 | pub type ForeignRawFd = RawFd; |
15 | |
16 | bitflags::bitflags! { |
17 | /// All flags are reserved for future use. |
18 | #[repr (transparent)] |
19 | #[derive (Copy, Clone, Eq, PartialEq, Hash, Debug)] |
20 | pub struct PidfdGetfdFlags: backend::c::c_uint { |
21 | /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags> |
22 | const _ = !0; |
23 | } |
24 | } |
25 | |
26 | /// `syscall(SYS_pidfd_getfd, pidfd, flags)`—Obtain a duplicate of another |
27 | /// process' file descriptor. |
28 | /// |
29 | /// # References |
30 | /// - [Linux] |
31 | /// |
32 | /// # Warning |
33 | /// |
34 | /// This function is generally safe for the calling process, but it can impact |
35 | /// the target process in unexpected ways. If you want to ensure that Rust I/O |
36 | /// safety assumptions continue to hold in the target process, then the target |
37 | /// process must have communicated the file description number to the calling |
38 | /// process from a value of a type that implements `AsRawFd`, and the target |
39 | /// process must not drop that value until after the calling process has |
40 | /// returned from `pidfd_getfd`. |
41 | /// |
42 | /// When `pidfd_getfd` is used to debug the target, or the target is not a Rust |
43 | /// application, or `pidfd_getfd` is used in any other way, then extra care |
44 | /// should be taken to avoid unexpected behaviour or crashes. |
45 | /// |
46 | /// For further details, see the references above. |
47 | /// |
48 | /// [Linux]: https://man7.org/linux/man-pages/man2/pidfd_getfd.2.html |
49 | #[inline ] |
50 | pub fn pidfd_getfd<Fd: AsFd>( |
51 | pidfd: Fd, |
52 | targetfd: ForeignRawFd, |
53 | flags: PidfdGetfdFlags, |
54 | ) -> io::Result<OwnedFd> { |
55 | backend::process::syscalls::pidfd_getfd(pidfd:pidfd.as_fd(), targetfd, flags) |
56 | } |
57 | |