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]
pidfd_getfd<Fd: AsFd>( pidfd: Fd, targetfd: ForeignRawFd, flags: PidfdGetfdFlags, ) -> io::Result<OwnedFd>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.as_fd(), targetfd, flags)
56 }
57