pidfd_getfd 0.2.2

Binding to and a wrapper for the pidfd_getfd syscall
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

use libc::{syscall, SYS_pidfd_getfd};
use pidfd::PidFd;
use std::{
    fs::File,
    // `io::Result` is renamed to provide clearer hints with rust-analyzer
    io::{self, Result as IoResult},
    os::unix::prelude::{AsRawFd, FromRawFd, RawFd},
};

#[cfg(feature = "nightly")]
use std::os::linux::process::PidFd as StdPidFd;

/// Various flags used to configure calls to [`get_file_from_pidfd`].
///
/// Currently, there are no flags.
#[derive(Clone, Copy)]
#[non_exhaustive]
pub struct GetFdFlags;

impl GetFdFlags {
    pub const fn empty() -> Self {
        Self
    }

    pub const fn bits(&self) -> u32 {
        0
    }
}

/// An extension trait to provide a convenient interface to [`get_file_from_pidfd`].
pub trait PidFdExt {
    fn get_file(&self, target_fd: RawFd, flags: GetFdFlags) -> IoResult<File>;
}

impl PidFdExt for PidFd {
    fn get_file(&self, target_fd: RawFd, flags: GetFdFlags) -> IoResult<File> {
        get_file_from_pidfd(self.as_raw_fd(), target_fd, flags)
    }
}

#[cfg(feature = "nightly")]
impl PidFdExt for StdPidFd {
    fn get_file(&self, target_fd: RawFd, flags: GetFdFlags) -> IoResult<File> {
        get_file_from_pidfd(self.as_raw_fd(), target_fd, flags)
    }
}

/// Takes the file description referred to by `target_fd` within `pidfd`
/// and creates a duplicate of it within this process.
///
/// This is a convenience wrapper. For the raw syscall, see [`pidfd_getfd`].
///
/// For more information, including the meaning of any returned [`io::Error`]s,
/// see the man page for [`pidfd_getfd(2)`].
///
/// [`pidfd_getfd(2)`]: https://man7.org/linux/man-pages/man2/pidfd_getfd.2.html
pub fn get_file_from_pidfd(pidfd: RawFd, target_fd: RawFd, flags: GetFdFlags) -> IoResult<File> {
    // SAFETY: `flags` being 0 seems to be the only safety invariant for now.
    // Invalid fds return errors.
    let res = unsafe { pidfd_getfd(pidfd, target_fd, flags.bits()) };

    if res == -1 {
        Err(io::Error::last_os_error())
    } else {
        // SAFETY: `pidfd_getfd` returns a valid file descriptor
        // on success.
        Ok(unsafe { File::from_raw_fd(res) })
    }
}

/// Takes the file description referred to by `targetfd` within `pidfd`
/// and creates a duplicate of it within this process.
///
/// This is the raw syscall. For a somewhat more convenient wrapper, see
/// [`get_file_from_pidfd`].
///
/// If this syscall is successful, it returns the new file descriptor.
/// Otherwise, it returns -1 and sets `errno`. For more information, see
/// the man page for [`pidfd_getfd(2)`].
///
/// ## Safety
/// The caller is responsible for upholding any requirements detailed in the
/// aforementioned man page. At the time of writing (2021-08-05, kernel version
/// 5.10.28), `flags` must be set to 0.
///
/// [`pidfd_getfd(2)`]: https://man7.org/linux/man-pages/man2/pidfd_getfd.2.html
pub unsafe fn pidfd_getfd(
    pidfd: libc::c_int,
    targetfd: libc::c_int,
    flags: libc::c_uint,
) -> libc::c_int {
    // SAFETY: The caller is responsible for upholding the invariants of this
    // syscall.
    unsafe { syscall(SYS_pidfd_getfd, pidfd, targetfd, flags) as libc::c_int }
}