Skip to main content

PidFdExt

pidfd_util

Trait PidFdExt 

Source 
pub trait PidFdExt {
    // Required methods
    fn from_self() -> Result<PidFd>;
    fn from_pid(pid: i32) -> Result<PidFd>;
    fn get_pid(&self) -> Result<i32>;
    fn get_ppid(&self) -> Result<i32>;
    fn get_id(&self) -> Result<u64>;
    fn get_creds(&self) -> Result<PidFdCreds>;
    fn get_cgroupid(&self) -> Result<u64>;
    fn get_namespace(&self, ns: &PidFdGetNamespace) -> Result<OwnedFd>;
    fn access_proc<R, F: FnOnce() -> R>(&self, func: F) -> Result<R>;
    fn send_signal(&self, signal: i32) -> Result<()>;
    fn set_namespace(&self, ns: CloneFlags) -> Result<()>;
    fn get_remote_fd(&self, target_fd: i32) -> Result<OwnedFd>;
}
Expand description

Extension trait providing additional operations on PidFd.

This trait extends the basic PidFd functionality with methods for querying process information, manipulating namespaces, and accessing remote file descriptors.

Required Methods§

Source

fn from_self() -> Result<PidFd>

Creates a PidFd for the current process.

Source

fn from_pid(pid: i32) -> Result<PidFd>

Creates a PidFd from a process ID. Calling this is highly discouraged as it is racy and the resulting pidfd might not refer to the expected process.

See the crate documentation for more details on how to obtain a pidfd in a race-free way.

§Errors

Returns an error if the process does not exist or if pidfd creation fails.

Source

fn get_pid(&self) -> Result<i32>

Gets the process ID of the process referred to by the pidfd.

Source

fn get_ppid(&self) -> Result<i32>

Gets the process ID of the parent process referred to by the pidfd.

Source

fn get_id(&self) -> Result<u64>

Gets a unique identifier of the process referred to by the pidfd.

Returns a unique 64-bit identifier that, like a pidfd, will never be reused. This ID can be used to safely identify a process without risk of confusion with a different process, even after the original process exits.

This is useful when you need to identify a process but cannot use the pidfd directly, such as:

  • Writing process identifiers to logs
  • Passing process identifiers to other processes where sending file descriptors is difficult
  • Storing process identifiers in data structures where holding file descriptors is impractical
§Errors

Returns ErrorKind::Unsupported if the kernel doesn’t support retrieving a unique process ID.

Source

fn get_creds(&self) -> Result<PidFdCreds>

Gets the credentials (UIDs and GIDs) of the process referred to by the pidfd.

Returns real, effective, saved, and filesystem UID/GID values. Requires Linux 6.9+ (uses pidfd ioctl).

§Errors

Returns ErrorKind::Unsupported if the kernel doesn’t support the required ioctl.

Source

fn get_cgroupid(&self) -> Result<u64>

Gets the cgroup ID of the process.

Requires Linux 6.9+ (uses pidfd ioctl).

§Errors

Returns ErrorKind::Unsupported if the kernel doesn’t support the required ioctl.

Source

fn get_namespace(&self, ns: &PidFdGetNamespace) -> Result<OwnedFd>

Gets a file descriptor to a namespace of type ns of the process referred to by the pidfd.

The returned file descriptor can be used with setns() to enter the namespace.

§Errors

Returns an error if the namespace type is not supported or if the ioctl fails.

Source

fn access_proc<R, F: FnOnce() -> R>(&self, func: F) -> Result<R>

Executes a function with protection against PID reuse.

This method verifies that the PID hasn’t changed before and after executing the function func, protecting against race conditions where the process exits and the PID is reused between checks.

§Errors

Returns ErrorKind::NotFound if the PID changed during execution.

§Examples
#![cfg_attr(feature = "nightly", feature(linux_pidfd))]
use pidfd_util::{PidFd, PidFdExt};
use std::fs;

let pidfd = PidFd::from_pid(1234)?;
let result = pidfd.access_proc(|| {
    // This operation is protected against PID reuse
    fs::read_to_string("/proc/1234/status")
})?;
Source

fn send_signal(&self, signal: i32) -> Result<()>

Sends a signal (e.g., libc::SIGTERM) to the process referred to by the pidfd.

§Errors

Returns an error if the signal cannot be sent (e.g., insufficient permissions).

Source

fn set_namespace(&self, ns: CloneFlags) -> Result<()>

Moves the calling process into the namespaces of the process referred to by the pidfd.

The ns argument is a bit mask, specifying the namespaces to enter into. This is equivalent to calling setns() with this pidfd and the specified namespace flags. After this call, the current thread will be in the specified namespace(s) of the target process.

§Errors

Returns an error if setns() fails (e.g., insufficient permissions).

Source

fn get_remote_fd(&self, target_fd: i32) -> Result<OwnedFd>

Installs a duplicate of a file descriptor from the process referred to by the pidfd in the current process.

This allows accessing file descriptors from another process. The returned file descriptor refers to the same open file description as the file descriptor with the number target_fd in the target process.

Requires CAP_SYS_PTRACE or PTRACE_MODE_ATTACH_REALCREDS permissions.

§Errors

Returns an error if permissions are insufficient or the target FD doesn’t exist.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§