pidfd 0.1.0__py3-none-any.whl

pidfd/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: 0BSD
+"""Python bindings for Linux pidfds.
+
+A pidfd is a file descriptor referring to a process. It is a stable
+handle: signaling through it can never hit a recycled pid, it becomes
+pollable-readable when the task exits, and it can be waited on with
+waitid(2) or used to duplicate the task's file descriptors with
+pidfd_getfd(2). Everything goes through raw syscalls via ctypes. There
+are no runtime dependencies.
+
+Kernel references: pidfd_open(2), pidfd_send_signal(2), pidfd_getfd(2),
+waitid(2).
+"""
+
+from .errors import PidFdError, UnsupportedError
+from .pidfd import (
+    OpenFlag,
+    PidFd,
+    SigInfo,
+    SignalFlag,
+    WaitCode,
+    WaitFlag,
+    WaitResult,
+    pidfd_send_signal,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OpenFlag",
+    "PidFd",
+    "PidFdError",
+    "SigInfo",
+    "SignalFlag",
+    "UnsupportedError",
+    "WaitCode",
+    "WaitFlag",
+    "WaitResult",
+    "__version__",
+    "pidfd_send_signal",
+]

pidfd/_syscall.py

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: 0BSD
+"""Raw ctypes bindings for the pidfd syscalls and waitid(2).
+
+glibc has no wrappers for pidfd_open, pidfd_send_signal or pidfd_getfd,
+so all four calls go through libc's syscall(2). The numbers differ per
+architecture for waitid only. The three pidfd calls share the common
+numbering on every supported arch.
+
+Kernel references: pidfd_open(2), pidfd_send_signal(2), pidfd_getfd(2),
+waitid(2), asm/unistd*.h, asm-generic/unistd.h.
+"""
+
+import ctypes
+import ctypes.util
+import errno
+import os
+import platform
+import sys
+from typing import NoReturn
+
+from .errors import PidFdError, UnsupportedError
+
+P_PIDFD = 3
+
+
+class _SigChld(ctypes.Structure):
+    """The _sifields._sigchld member of the kernel siginfo_t."""
+
+    _fields_ = [
+        ("si_pid", ctypes.c_int32),
+        ("si_uid", ctypes.c_uint32),
+        ("si_status", ctypes.c_int32),
+        ("si_utime", ctypes.c_long),
+        ("si_stime", ctypes.c_long),
+    ]
+
+
+class _SiFields(ctypes.Union):
+    """union __sifields, padded so the whole siginfo stays writable."""
+
+    _fields_ = [
+        ("sigchld", _SigChld),
+        ("pad", ctypes.c_byte * 128),
+    ]
+
+
+class SigInfo(ctypes.Structure):
+    """The kernel siginfo_t used by waitid(2) and pidfd_send_signal(2).
+
+    Only the SIGCHLD member of union __sifields is decoded. The rest is
+    padding. The buffer is deliberately larger than the kernel's
+    128-byte siginfo_t so waitid's user access check always succeeds.
+    """
+
+    _fields_ = [
+        ("si_signo", ctypes.c_int),
+        ("si_errno", ctypes.c_int),
+        ("si_code", ctypes.c_int),
+        ("_sifields", _SiFields),
+    ]
+
+    @property
+    def si_pid(self) -> int:
+        return int(self._sifields.sigchld.si_pid)
+
+    @si_pid.setter
+    def si_pid(self, value: int) -> None:
+        self._sifields.sigchld.si_pid = value
+
+    @property
+    def si_uid(self) -> int:
+        return int(self._sifields.sigchld.si_uid)
+
+    @si_uid.setter
+    def si_uid(self, value: int) -> None:
+        self._sifields.sigchld.si_uid = value
+
+    @property
+    def si_status(self) -> int:
+        return int(self._sifields.sigchld.si_status)
+
+    @si_status.setter
+    def si_status(self, value: int) -> None:
+        self._sifields.sigchld.si_status = value
+
+
+_libc: ctypes.CDLL | None = None
+_numbers: tuple[int, int, int, int] | None = None
+
+
+def _get_libc() -> ctypes.CDLL:
+    global _libc
+    if _libc is None:
+        if sys.platform != "linux":
+            raise UnsupportedError("pidfds are only available on Linux")
+        name = ctypes.util.find_library("c")
+        _libc = ctypes.CDLL(name or None, use_errno=True)
+        _libc.syscall.restype = ctypes.c_long
+    return _libc
+
+
+def _syscall_numbers() -> tuple[int, int, int, int]:
+    """Return (pidfd_open, pidfd_send_signal, pidfd_getfd, waitid)."""
+    global _numbers
+    if _numbers is not None:
+        return _numbers
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        if ctypes.sizeof(ctypes.c_void_p) == 4:
+            # The x32 ABI carries different numbers and a differently
+            # aligned siginfo_t. Reject it rather than call the wrong
+            # syscall.
+            raise UnsupportedError("the x32 ABI is not supported")
+        _numbers = (434, 424, 438, 247)
+    elif machine in ("i386", "i486", "i586", "i686", "x86"):
+        _numbers = (434, 424, 438, 284)
+    elif machine in ("aarch64", "arm64", "riscv32", "riscv64", "loongarch64"):
+        _numbers = (434, 424, 438, 95)
+    elif machine in ("armv6l", "armv7l", "arm"):
+        _numbers = (434, 424, 438, 280)
+    elif machine.startswith("ppc"):
+        _numbers = (434, 424, 438, 272)
+    elif machine.startswith("s390"):
+        _numbers = (434, 424, 438, 281)
+    else:
+        raise UnsupportedError(f"no pidfd syscall numbers for architecture {machine}")
+    return _numbers
+
+
+def _raise_errno(err: int) -> NoReturn:
+    if err == errno.ENOSYS:
+        raise UnsupportedError(err, os.strerror(err))
+    raise PidFdError(err, os.strerror(err))
+
+
+def _call(nr: int, *args: object) -> int:
+    ret = int(_get_libc().syscall(nr, *args))
+    if ret == -1:
+        _raise_errno(ctypes.get_errno())
+    return ret
+
+
+def pidfd_open(pid: int, flags: int = 0) -> int:
+    """Open a pidfd for pid and return the new file descriptor."""
+    return _call(_syscall_numbers()[0], pid, flags)
+
+
+def pidfd_send_signal(
+    pidfd: int, sig: int, info: SigInfo | None, flags: int = 0
+) -> None:
+    """Send sig to the process the pidfd refers to."""
+    ref = ctypes.byref(info) if info is not None else None
+    _call(_syscall_numbers()[1], pidfd, sig, ref, flags)
+
+
+def pidfd_getfd(pidfd: int, targetfd: int, flags: int = 0) -> int:
+    """Duplicate targetfd from the pidfd's process into our fd table."""
+    return _call(_syscall_numbers()[2], pidfd, targetfd, flags)
+
+
+def waitid(idtype: int, upid: int, info: SigInfo, options: int) -> int:
+    """waitid(2) filling info; the rusage argument stays NULL."""
+    return _call(_syscall_numbers()[3], idtype, upid, ctypes.byref(info), options, 0)

pidfd/errors.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: 0BSD
+"""Exception types raised by pidfd."""
+
+
+class PidFdError(OSError):
+    """A pidfd syscall failed."""
+
+
+class UnsupportedError(PidFdError):
+    """The running kernel or architecture lacks the requested pidfd feature."""

pidfd/pidfd.py

@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: 0BSD
+"""PidFd: a file descriptor that refers to a process.
+
+A pidfd is a stable reference to a task: unlike a raw pid it cannot be
+recycled, so signaling through it cannot hit an unrelated process. The
+descriptor becomes readable (POLLIN) once the task exits and turns into
+a zombie, and reports POLLHUP once it is reaped. waitid(2) with idtype
+P_PIDFD reaps a child through it.
+
+Kernel references: pidfd_open(2), pidfd_send_signal(2), pidfd_getfd(2),
+waitid(2), linux/pidfd.h.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass
+from enum import IntEnum, IntFlag
+from types import TracebackType
+
+from . import _syscall
+from ._syscall import SigInfo
+
+__all__ = [
+    "OpenFlag",
+    "PidFd",
+    "SigInfo",
+    "SignalFlag",
+    "WaitCode",
+    "WaitFlag",
+    "WaitResult",
+    "pidfd_send_signal",
+]
+
+
+class OpenFlag(IntFlag):
+    """Flags for pidfd_open(2), mirroring linux/pidfd.h.
+
+    NONBLOCK makes wait() fail with EAGAIN instead of blocking while the
+    task is still running (Linux 5.10+). THREAD pins the fd to a single
+    thread instead of the thread-group leader (Linux 6.9+).
+    """
+
+    NONBLOCK = 0o4000  # O_NONBLOCK
+    THREAD = 0o200  # O_EXCL
+
+
+class SignalFlag(IntFlag):
+    """Scope flags for pidfd_send_signal(2), Linux 6.9+."""
+
+    THREAD = 1 << 0
+    THREAD_GROUP = 1 << 1
+    PROCESS_GROUP = 1 << 2
+
+
+class WaitFlag(IntFlag):
+    """Option bits for waitid(2), mirroring linux/wait.h.
+
+    At least one of WEXITED, WSTOPPED or WCONTINUED is required.
+    """
+
+    WNOHANG = 0x00000001
+    WSTOPPED = 0x00000002
+    WEXITED = 0x00000004
+    WCONTINUED = 0x00000008
+    WNOWAIT = 0x01000000
+
+
+class WaitCode(IntEnum):
+    """si_code values the kernel reports in a SIGCHLD siginfo (CLD_*)."""
+
+    CLD_EXITED = 1
+    CLD_KILLED = 2
+    CLD_DUMPED = 3
+    CLD_TRAPPED = 4
+    CLD_STOPPED = 5
+    CLD_CONTINUED = 6
+
+
+@dataclass(frozen=True)
+class WaitResult:
+    """The fields waitid(2) fills into the siginfo_t for a child.
+
+    code holds a WaitCode (CLD_*) value. Its meaning for status is that
+    of waitpid(2): an exit status when code is CLD_EXITED, a signal
+    number for CLD_KILLED/CLD_DUMPED/CLD_STOPPED/CLD_CONTINUED. A result
+    with signo 0 means the call returned without an event, which only
+    happens when WNOHANG was requested.
+    """
+
+    pid: int
+    uid: int
+    signo: int
+    code: int
+    status: int
+
+
+class PidFd:
+    """A pidfd file descriptor referring to a process.
+
+    Obtain one with open() or wrap an existing descriptor in the
+    constructor. Instances own their fd: close() is idempotent and the
+    context manager closes on exit.
+    """
+
+    def __init__(self, fd: int) -> None:
+        self._fd = -1  # keeps __del__ safe when validation fails
+        if fd < 0:
+            raise ValueError(f"fd must not be negative: {fd}")
+        self._fd = fd
+
+    @classmethod
+    def open(cls, pid: int, flags: OpenFlag | int = 0) -> PidFd:
+        """Open a pidfd for pid via pidfd_open(2) (Linux 5.3+)."""
+        return cls(_syscall.pidfd_open(int(pid), int(flags)))
+
+    def fileno(self) -> int:
+        """Return the underlying descriptor, or -1 once closed."""
+        return self._fd
+
+    @property
+    def closed(self) -> bool:
+        """Whether close() has released the descriptor."""
+        return self._fd < 0
+
+    def _check_open(self) -> int:
+        if self._fd < 0:
+            raise ValueError("pidfd is closed")
+        return self._fd
+
+    def close(self) -> None:
+        """Close the descriptor. Safe to call more than once."""
+        if self._fd >= 0:
+            fd, self._fd = self._fd, -1
+            os.close(fd)
+
+    def detach(self) -> int:
+        """Release the descriptor without closing it.
+
+        Returns the raw fd and marks the PidFd closed, transferring
+        ownership of the descriptor to the caller.
+        """
+        fd = self._check_open()
+        self._fd = -1
+        return fd
+
+    def signal(
+        self,
+        sig: int,
+        siginfo: SigInfo | None = None,
+        flags: SignalFlag | int = 0,
+    ) -> None:
+        """Send sig to the referenced process via pidfd_send_signal(2).
+
+        siginfo=None selects the same implicit fields kill(2) supplies.
+        Pass a populated SigInfo for rt_sigqueueinfo(2)-style delivery,
+        where si_code must be a negative SI_* value such as SI_QUEUE
+        when the target is not the caller. flags accepts the SignalFlag
+        bits on Linux 6.9+. 0 is the only value older kernels allow.
+        ESRCH means the task is already gone
+        and reaped, never that the pid was recycled.
+        """
+        _syscall.pidfd_send_signal(self._check_open(), int(sig), siginfo, int(flags))
+
+    def wait(self, flags: WaitFlag | int = WaitFlag.WEXITED) -> WaitResult:
+        """waitid(P_PIDFD) on the referenced child (Linux 5.4+).
+
+        The pidfd must refer to a child of the caller, otherwise the
+        kernel answers ECHILD. A pidfd opened with OpenFlag.NONBLOCK
+        fails with EAGAIN while the child is still running. On a
+        blocking pidfd add WaitFlag.WNOHANG for a poll-style call that
+        returns a WaitResult with signo 0.
+        """
+        info = SigInfo()
+        _syscall.waitid(_syscall.P_PIDFD, self._check_open(), info, int(flags))
+        return WaitResult(
+            pid=info.si_pid,
+            uid=info.si_uid,
+            signo=info.si_signo,
+            code=info.si_code,
+            status=info.si_status,
+        )
+
+    def getfd(self, targetfd: int, flags: int = 0) -> int:
+        """Duplicate targetfd of the referenced process into our fd table.
+
+        The returned fd shares the open file description with the
+        target's fd and has close-on-exec set. Access is governed by a
+        PTRACE_MODE_ATTACH_REALCREDS ptrace check (see ptrace(2)): under
+        yama ptrace_scope that typically means the target must be a
+        descendant, or the caller needs CAP_SYS_PTRACE.
+        """
+        return _syscall.pidfd_getfd(self._check_open(), int(targetfd), int(flags))
+
+    def __enter__(self) -> PidFd:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __index__(self) -> int:
+        return self._check_open()
+
+    def __repr__(self) -> str:
+        state = self._fd if self._fd >= 0 else "closed"
+        return f"PidFd(fd={state})"
+
+    def __del__(self) -> None:
+        with contextlib.suppress(OSError):
+            self.close()
+
+
+def pidfd_send_signal(fd: int | PidFd, sig: int, flags: SignalFlag | int = 0) -> None:
+    """Send sig through a pidfd without wrapping it in PidFd first."""
+    raw = fd.fileno() if isinstance(fd, PidFd) else int(fd)
+    _syscall.pidfd_send_signal(raw, int(sig), None, int(flags))

pidfd-0.1.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: pidfd
+Version: 0.1.0
+Summary: Python bindings for Linux pidfds
+Project-URL: Homepage, https://quad4.io
+Project-URL: Repository, https://github.com/Quad4-Software/pidfd
+Project-URL: Issues, https://github.com/Quad4-Software/pidfd/issues
+Project-URL: Changelog, https://github.com/Quad4-Software/pidfd/blob/master/CHANGELOG.md
+Author: Quad4
+License-Expression: 0BSD
+License-File: LICENSE
+Keywords: linux,pidfd,process,signals
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pidfd
+
+[![CI](https://github.com/Quad4-Software/pidfd/actions/workflows/ci.yml/badge.svg)](https://github.com/Quad4-Software/pidfd/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Quad4-Software/pidfd/actions/workflows/codeql.yml/badge.svg)](https://github.com/Quad4-Software/pidfd/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Quad4-Software/pidfd/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Quad4-Software/pidfd)
+[![PyPI](https://img.shields.io/pypi/v/pidfd.svg)](https://pypi.org/project/pidfd/)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue)](LICENSE)
+
+Dependency-free Python bindings for Linux pidfds. A pidfd is a file
+descriptor referring to a process: a stable handle that can never hit a
+recycled pid, becomes readable when the task exits, can be waited on
+with waitid(2), and can duplicate the task's file descriptors with
+pidfd_getfd(2). Everything goes through pidfd_open(2),
+pidfd_send_signal(2), pidfd_getfd(2) and waitid(2) via ctypes. There
+are no runtime dependencies.
+
+Requires Python 3.10+ and Linux.
+
+## Install
+
+    pip install pidfd
+
+## Usage
+
+```python
+import select, signal, subprocess
+from pidfd import PidFd, WaitCode
+
+proc = subprocess.Popen(["sleep", "30"])
+with PidFd.open(proc.pid) as pf:
+    # poll(2) reports the fd readable once the task is a zombie
+    pf.signal(signal.SIGKILL)
+
+    poller = select.poll()
+    poller.register(pf.fileno(), select.POLLIN)
+    poller.poll()
+
+    result = pf.wait()  # waitid(P_PIDFD)
+    assert result.code == WaitCode.CLD_KILLED
+```
+
+`PidFd.open(pid, OpenFlag.NONBLOCK)` makes `wait()` fail with EAGAIN
+instead of blocking. `pf.getfd(fd)` duplicates one of the target's open
+fds (ptrace access rules apply).
+
+## Development
+
+    uv sync --group dev
+    make check
+
+License: 0BSD. Quad4 Software, https://quad4.io

pidfd-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pidfd/__init__.py,sha256=7QQYwDE6IBcBBRbLIdsQo9POpSfTzgf19H52Qk200HU,958
+pidfd/_syscall.py,sha256=m8jK6DrmLy7uqN7W2dLir1o441Z3NaHeHwH1QjAy3o8,5071
+pidfd/errors.py,sha256=aKqnr7V60Y-DDLsYzMQfBvPH_Xkh56F9PmL-lPqBcUA,252
+pidfd/pidfd.py,sha256=l7GTn4L88B6-R2jonBLuYdA-uZo0QSu-qrZLUb-g7CE,6892
+pidfd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pidfd-0.1.0.dist-info/METADATA,sha256=D6SZpssZhfYI8bfuzjTTjGXBeWV-j_vp_YTYxEBUEPw,3015
+pidfd-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pidfd-0.1.0.dist-info/licenses/LICENSE,sha256=3Hnwsz5EXuTC9iTlGjzA171dKQtIVsgjFoF5DEMRl48,633
+pidfd-0.1.0.dist-info/RECORD,,

pidfd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pidfd-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Quad4
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.