air_sys_types/

process.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Types fondamentaux de la famille `process`.
//!
//! Cf. `docs/specs/layer-0/family-process.md` et `air-sys-types.md`.
//!
//! `Pid` et `Tid` sont deux newtypes **distincts** sur `NonZeroI32` afin
//! d'empêcher par typage la confusion entre un identifiant de processus et un
//! identifiant de thread (application directe du Principe 7 et de la
//! convention 1 de l'ADR-021). Le reste du module héberge les types liés à
//! `clone3` (création de processus / thread) et `waitid` (attente
//! d'événement sur un enfant).

use core::num::NonZeroI32;
use core::sync::atomic::AtomicU32;

use bitflags::bitflags;

use crate::fd::{BorrowedFd, OwnedFd};
use crate::signal::Signal;

/// Identifiant kernel d'un processus (`pid_t`).
///
/// Garanti strictement positif par le kernel Linux : un PID nul ne désigne
/// jamais un processus réel (cf. `getpid(2)`). Le wrapper `NonZeroI32` encode
/// cet invariant dans le type, ce qui permet à `Option<Pid>` d'occuper la
/// même taille que `Pid`. La convention 1 de l'ADR-021 exploite cette
/// propriété pour remplacer les sentinelles kernel (`0` = « processus
/// courant ») par `None`.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Pid(NonZeroI32);

impl Pid {
    /// Construit un `Pid` à partir d'une valeur déjà validée.
    ///
    /// Réservé aux producteurs qui ont déjà la garantie que la valeur vient
    /// du kernel et est strictement positive (par exemple le wrapper
    /// `getpid` de la couche 0).
    #[must_use]
    #[inline]
    pub const fn from_nonzero(raw: NonZeroI32) -> Self {
        Self(raw)
    }

    /// Tente de construire un `Pid` à partir d'un `i32` brut.
    ///
    /// Retourne `None` si la valeur est négative ou nulle, deux cas qui
    /// n'identifient pas un processus valide.
    #[must_use]
    #[inline]
    pub const fn try_from_raw(raw: i32) -> Option<Self> {
        match NonZeroI32::new(raw) {
            Some(nz) if nz.get() > 0 => Some(Self(nz)),
            _ => None,
        }
    }

    /// Retourne la représentation brute (`i32`) du PID.
    ///
    /// L'expose pour l'interfaçage avec les wrappers de syscalls et les
    /// affichages humains ; éviter de manipuler des `i32` nus dans le
    /// reste du code (convention « newtypes systématiques »).
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> i32 {
        self.0.get()
    }
}

/// Identifiant kernel d'un thread (TID, `tid_t`).
///
/// Sur Linux, chaque thread possède un TID distinct. Le TID du thread
/// principal d'un processus est égal au PID du processus (invariant
/// `gettid() == getpid()` pour le thread principal).
///
/// Type **distinct** de [`Pid`] : on ne peut pas confondre les deux par
/// inadvertance.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Tid(NonZeroI32);

impl Tid {
    /// Construit un `Tid` à partir d'une valeur déjà validée.
    #[must_use]
    #[inline]
    pub const fn from_nonzero(raw: NonZeroI32) -> Self {
        Self(raw)
    }

    /// Tente de construire un `Tid` à partir d'un `i32` brut.
    ///
    /// Retourne `None` si la valeur est négative ou nulle.
    #[must_use]
    #[inline]
    pub const fn try_from_raw(raw: i32) -> Option<Self> {
        match NonZeroI32::new(raw) {
            Some(nz) if nz.get() > 0 => Some(Self(nz)),
            _ => None,
        }
    }

    /// Retourne la représentation brute (`i32`) du TID.
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> i32 {
        self.0.get()
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Identifiants d'utilisateur / de groupe (`uid_t` / `gid_t`).
//
// Spec : `docs/specs/layer-0/family-process-privsep.md` §1.
//
// Contrairement à `Pid`/`Tid` (toujours > 0), **`0` est une valeur valide**
// (root) : on n'utilise donc pas `NonZeroI32` mais un newtype `repr(transparent)`
// sur `u32` (= `uid_t`/`gid_t`). Newtypes typés systématiques (ADR-029 : jamais
// d'`u32` brut pour un identifiant ; `Uid` et `Gid` sont **distincts** pour
// empêcher toute confusion par typage).
// ─────────────────────────────────────────────────────────────────────────

/// Identifiant d'utilisateur (`uid_t`). `0` = root (valeur valide).
///
/// La valeur `(uid_t)-1` (`u32::MAX`) est **réservée** par le kernel comme
/// sentinelle « inchangé » de `setresuid` ; elle est exposée typée via
/// `Option<Uid>` (`None`), jamais comme un `Uid` de production.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Uid(u32);

impl Uid {
    /// L'utilisateur root (`uid == 0`).
    pub const ROOT: Self = Self(0);

    /// Construit un `Uid` à partir d'une valeur brute `uid_t`.
    #[must_use]
    #[inline]
    pub const fn from_raw(raw: u32) -> Self {
        Self(raw)
    }

    /// Retourne la représentation brute (`uid_t`) de l'identifiant.
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> u32 {
        self.0
    }
}

/// Identifiant de groupe (`gid_t`). `0` = groupe root (valeur valide).
///
/// Voir [`Uid`] pour la sentinelle `(gid_t)-1` (`None` de `setresgid`).
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Gid(u32);

impl Gid {
    /// Le groupe root (`gid == 0`).
    pub const ROOT: Self = Self(0);

    /// Construit un `Gid` à partir d'une valeur brute `gid_t`.
    #[must_use]
    #[inline]
    pub const fn from_raw(raw: u32) -> Self {
        Self(raw)
    }

    /// Retourne la représentation brute (`gid_t`) de l'identifiant.
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> u32 {
        self.0
    }
}

/// Triplet d'identité UID **réel / effectif / sauvegardé** (`getresuid`).
///
/// Le *saved-set-uid* est la composante qui rend une réduction de privilèges
/// **irréversible** : si `real == effective == saved == non-root`, le processus
/// ne peut plus regagner root (cf. `setresuid`, `family-process-privsep.md` §3).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResUid {
    /// UID réel.
    pub real: Uid,
    /// UID effectif (gouverne les contrôles d'accès).
    pub effective: Uid,
    /// UID sauvegardé (*saved-set-uid*).
    pub saved: Uid,
}

/// Triplet d'identité GID **réel / effectif / sauvegardé** (`getresgid`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResGid {
    /// GID réel.
    pub real: Gid,
    /// GID effectif.
    pub effective: Gid,
    /// GID sauvegardé (*saved-set-gid*).
    pub saved: Gid,
}

// ─────────────────────────────────────────────────────────────────────────
// Création de processus : types associés à `clone3`.
// Spec : `docs/specs/layer-0/family-process.md` sous-section 2.
// ─────────────────────────────────────────────────────────────────────────

/// File descriptor RAII qui référence un processus par pidfd.
///
/// Ferme automatiquement le FD sous-jacent à la destruction. Reste valide
/// même après la mort du processus référencé (le FD ne se transfère pas à
/// un éventuel nouveau processus qui recyclerait le PID).
#[derive(Debug)]
pub struct PidFd(OwnedFd);

impl PidFd {
    /// Construit un `PidFd` à partir d'un `OwnedFd` déjà ouvert sur un
    /// processus par le kernel (typiquement via `pidfd_open` ou `clone3`
    /// avec `CLONE_PIDFD`).
    #[must_use]
    #[inline]
    pub const fn from_owned_fd(fd: OwnedFd) -> Self {
        Self(fd)
    }

    /// Retourne une vue empruntée du FD sous-jacent.
    #[must_use]
    #[inline]
    pub fn as_fd(&self) -> BorrowedFd<'_> {
        use crate::fd::AsFd;
        self.0.as_fd()
    }

    /// Consomme le `PidFd` et restitue le `OwnedFd` sous-jacent.
    #[must_use]
    #[inline]
    pub fn into_fd(self) -> OwnedFd {
        self.0
    }
}

bitflags! {
    /// Drapeaux de `clone3` (cf. `linux/sched.h`).
    ///
    /// Représentation `u64` pour accepter les bits Linux ≥ 5.7 qui dépassent
    /// 32 bits (`CLEAR_SIGHAND`, `INTO_CGROUP`, `NEWTIME`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct CloneFlags: u64 {
        /// Partage l'espace d'adressage avec le parent (création de thread).
        const VM = 0x0000_0100;
        /// Partage la table FS (`umask`, `cwd`, `root`).
        const FS = 0x0000_0200;
        /// Partage la table des FD ouverts.
        const FILES = 0x0000_0400;
        /// Partage la table des dispositions de signaux.
        const SIGHAND = 0x0000_0800;
        /// Demande au kernel de créer un pidfd vers l'enfant.
        const PIDFD = 0x0000_1000;
        /// L'enfant peut être tracé par `ptrace`.
        const PTRACE = 0x0000_2000;
        /// Suspend l'appelant jusqu'à `execve`/`exit` de l'enfant (vfork).
        const VFORK = 0x0000_4000;
        /// Le parent de l'enfant est le parent du parent (sibling).
        const PARENT = 0x0000_8000;
        /// L'enfant est dans le même groupe de threads que l'appelant.
        const THREAD = 0x0001_0000;
        /// L'enfant est dans un nouveau mount namespace.
        const NEWNS = 0x0002_0000;
        /// Partage les sémaphores System V.
        const SYSVSEM = 0x0004_0000;
        /// Initialise le `tls` de l'enfant avec la valeur fournie.
        const SETTLS = 0x0008_0000;
        /// Écrit le TID enfant dans `parent_tid` (mémoire du parent).
        const PARENT_SETTID = 0x0010_0000;
        /// `CLEAR_TID` à la mort de l'enfant.
        const CHILD_CLEARTID = 0x0020_0000;
        /// Enfant détaché (le parent n'est pas SIGCHLD-notifié).
        const DETACHED = 0x0040_0000;
        /// Désactive le traçage hérité par `ptrace`.
        const UNTRACED = 0x0080_0000;
        /// Écrit le TID enfant dans `child_tid` (mémoire de l'enfant).
        const CHILD_SETTID = 0x0100_0000;
        /// Nouveau cgroup namespace.
        const NEWCGROUP = 0x0200_0000;
        /// Nouveau UTS namespace (hostname).
        const NEWUTS = 0x0400_0000;
        /// Nouveau IPC namespace.
        const NEWIPC = 0x0800_0000;
        /// Nouveau user namespace.
        const NEWUSER = 0x1000_0000;
        /// Nouveau PID namespace.
        const NEWPID = 0x2000_0000;
        /// Nouveau network namespace.
        const NEWNET = 0x4000_0000;
        /// Partage le contexte I/O du parent.
        const IO = 0x8000_0000;
        /// Réinitialise toutes les dispositions de signal de l'enfant.
        const CLEAR_SIGHAND = 0x1_0000_0000;
        /// Place l'enfant dans le cgroup référencé par l'`fd` fourni.
        const INTO_CGROUP = 0x2_0000_0000;
        /// Nouveau time namespace (offsets `CLOCK_MONOTONIC`/`BOOTTIME`).
        const NEWTIME = 0x4_0000_0000;
    }
}

bitflags! {
    /// Drapeaux de [`pidfd_open`](../../air_sys_syscall/process/fn.pidfd_open.html).
    ///
    /// La spec couche 0 (`docs/specs/layer-0/family-process.md`) ne définit
    /// qu'une seule valeur valide (`NONBLOCK`) ; les autres bits sont
    /// réservés et le kernel retourne `EINVAL` s'ils sont positionnés.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct PidFdOpenFlags: u32 {
        /// Le pidfd est créé en mode non-bloquant : `poll`/`epoll` sur
        /// ce FD retournera immédiatement (utile pour de la surveillance
        /// asynchrone). Valeur ABI `O_NONBLOCK = 0x800`.
        const NONBLOCK = 0x800;
    }
}

bitflags! {
    /// Drapeaux de [`execveat`](../../air_sys_syscall/process/fn.execveat.html).
    ///
    /// Variante *at préférée d'`execve` (ADR-021 : « variantes modernes
    /// préférées »). Correspond aux constantes `AT_*` de `<fcntl.h>`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct ExecveatFlags: i32 {
        /// `AT_SYMLINK_NOFOLLOW` : si le composant final du chemin est un lien
        /// symbolique, ne pas le suivre (échoue avec `ELOOP`).
        const SYMLINK_NOFOLLOW = 0x100;
        /// `AT_EMPTY_PATH` : `path` est vide (`c""`) et l'exécutable est
        /// désigné **directement** par le `dirfd` (un fd ouvert sur le binaire,
        /// typiquement avec `O_PATH`). Évite toute race sur le chemin
        /// filesystem entre l'ouverture et l'exec.
        const EMPTY_PATH = 0x1000;
    }
}

bitflags! {
    /// Drapeaux de [`dup3`](../../air_sys_syscall/process/fn.dup3.html).
    ///
    /// `dup3(2)` (et non `dup2`) impose de passer les drapeaux explicitement ;
    /// le seul drapeau valide est `O_CLOEXEC`. Contrairement à `dup2`, `dup3`
    /// échoue avec `EINVAL` si `old == new` — pas de no-op silencieux.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct Dup3Flags: i32 {
        /// `O_CLOEXEC` : le nouveau descripteur est marqué close-on-exec
        /// (fermé automatiquement lors d'un `execve`/`execveat` ultérieur).
        /// Valeur ABI `0o2000000`, identique sur x86_64 et aarch64.
        const CLOEXEC = 0o2_000_000;
    }
}

/// Spécification d'une pile pour la création d'un thread (`CLONE_VM`).
///
/// Le pointeur `addr` désigne l'**adresse de base** (octet le plus bas) d'une
/// région mémoire valide d'au moins `size` octets, propriété de l'appelant
/// (typiquement issue d'un `mmap` anonyme). Le kernel positionne le pointeur
/// de pile de l'enfant au **sommet** de la région (`addr + size`) ; sur les
/// deux architectures Air (x86_64, aarch64) la pile croît vers le bas.
///
/// **Répartition des rôles.** La création de thread se fait via
/// [`clone_thread`](../../air_sys_syscall/process/fn.clone_thread.html), qui
/// **exige** `Some(StackSpecification)` et valide en amont l'alignement
/// (`addr` et `size` multiples de 16) et la taille minimale. Le wrapper de fork
/// [`clone3`](../../air_sys_syscall/process/fn.clone3.html) — dont le modèle de
/// retour `CloneResult::Child` est *unsound* sur une pile neuve — **rejette**
/// au contraire `Some(StackSpecification)` avec
/// [`Errno::EINVAL`](crate::errno::Errno::EINVAL) (cf. la doc de `clone_thread`
/// pour la justification kernel : un retour Rust normal sur une pile neuve lit
/// des ordures).
#[derive(Debug, Clone, Copy)]
pub struct StackSpecification {
    /// Adresse de base de la pile.
    pub addr: *mut u8,
    /// Taille de la pile, en octets.
    pub size: usize,
}

/// Emplacement mémoire où le kernel écrit (`CLONE_PARENT_SETTID` /
/// `CLONE_CHILD_SETTID`) ou efface (`CLONE_CHILD_CLEARTID`) le TID d'un enfant
/// créé par `clone3`.
///
/// Encapsule l'adresse d'un **mot 32 bits partagé** ([`AtomicU32`]) — un
/// `tid_t` côté kernel — plutôt qu'un pointeur nu (convention 1 de l'ADR-021 :
/// pas de pointeur brut non typé exposé). Le pattern de *join* de thread :
///
/// - `CLONE_PARENT_SETTID` + `parent_tid = &mot` → le kernel écrit le TID dans
///   le mot, **dans le contexte du parent**, avant le retour de `clone3` (sans
///   course avec une terminaison précoce de l'enfant) ;
/// - `CLONE_CHILD_CLEARTID` + `child_tid = &mot` → à la mort du thread, le
///   kernel remet le mot à `0` **et** effectue un `FUTEX_WAKE` dessus. Le parent
///   joint donc en bouclant sur `futex_wait(&mot, tid)` jusqu'à lire `0`.
///
/// Le mot doit rester **vivant** (et l'`AtomicU32` non déplacé) jusqu'à la fin
/// du *join* ; cette garantie incombe à l'appelant de la fonction `unsafe`
/// `clone_thread`. Construire un `TidReceiver` est en soi inoffensif (on ne fait
/// qu'enregistrer une adresse).
#[derive(Debug, Clone, Copy)]
pub struct TidReceiver {
    /// Adresse du mot 32 bits (`tid_t`) partagé avec le kernel.
    word: *mut u32,
}

impl TidReceiver {
    /// Construit un récepteur à partir d'un mot atomique partagé vivant.
    ///
    /// On ne capture que l'**adresse** du mot ; sa validité au moment de l'appel
    /// `clone3`/`clone_thread` (et jusqu'au *join*) relève du contrat `unsafe`
    /// de ces fonctions.
    #[must_use]
    #[inline]
    pub fn new(word: &AtomicU32) -> Self {
        Self {
            word: word.as_ptr(),
        }
    }

    /// Retourne le pointeur brut du mot, pour le marshalling vers la structure
    /// `clone_args` du kernel (réservé aux wrappers de la couche 0).
    #[must_use]
    #[inline]
    pub fn as_ptr(self) -> *mut u32 {
        self.word
    }
}

/// Arguments pour `clone3`.
///
/// La spec couche 0 (`docs/specs/layer-0/family-process.md`) liste neuf
/// champs (flags, pidfd, child_tid, parent_tid, exit_signal, stack, tls,
/// set_tid, cgroup). Ce type en expose six : les trois du fork classique
/// (`flags`, `exit_signal`, `stack`) **plus** les trois requis par la
/// création de thread (`child_tid`, `parent_tid`, `tls`). Les restants
/// (`pidfd` en tant que récepteur typé, `set_tid`, `cgroup`) seront ajoutés au
/// fil des syscalls qui les exigent. L'évolution est strictement additive :
/// aucun champ existant n'est destiné à être renommé ou retiré.
///
/// Pour demander la création d'un pidfd sur l'enfant, positionner le bit
/// [`CloneFlags::PIDFD`] ; le `PidFd` résultant est retourné dans la
/// variante [`CloneResult::Parent`].
///
/// **Création de thread.** Renseigner `stack`, `child_tid`/`parent_tid` (pour
/// le *join* via `CLONE_CHILD_CLEARTID`) et éventuellement `tls`, puis appeler
/// [`clone_thread`](../../air_sys_syscall/process/fn.clone_thread.html) (et non
/// `clone3`, qui reste dédié au fork).
#[derive(Debug, Clone, Default)]
pub struct CloneArgs {
    /// Drapeaux de comportement (`CLONE_*`).
    pub flags: CloneFlags,
    /// Signal à délivrer au parent à la mort de l'enfant. `Some(SIGCHLD)`
    /// est le choix standard pour `clone3` style fork. **Doit être `None`**
    /// pour un thread (`CLONE_THREAD` interdit tout signal de sortie).
    pub exit_signal: Option<Signal>,
    /// Pile pour `CLONE_VM` (création de thread). `None` pour le fork classique
    /// (rejeté par `clone3` si renseigné) ; `Some(_)` est **requis** par
    /// `clone_thread`.
    pub stack: Option<StackSpecification>,
    /// Récepteur du TID enfant côté **enfant** (`CLONE_CHILD_SETTID` /
    /// `CLONE_CHILD_CLEARTID`). Pour le *join* de thread, le pointer sur le
    /// même mot que [`Self::parent_tid`] et positionner `CLONE_CHILD_CLEARTID`.
    pub child_tid: Option<TidReceiver>,
    /// Récepteur du TID enfant côté **parent** (`CLONE_PARENT_SETTID`). Écrit
    /// par le kernel avant le retour de `clone3`, sans course.
    pub parent_tid: Option<TidReceiver>,
    /// Adresse du bloc TLS de l'enfant (`CLONE_SETTLS`). `None` = pas de TLS
    /// dédié (l'enfant hérite alors du registre TLS du parent : n'utiliser
    /// **aucune** variable `thread_local` côté enfant dans ce cas). La spec
    /// couche 0 type ce champ en `u64` (adresse brute) — voir
    /// `docs/specs/layer-0/family-process.md`.
    pub tls: Option<u64>,
}

/// Résultat de `clone3`.
///
/// Distingue sans ambiguïté le côté parent (avec le PID enfant et,
/// optionnellement, un pidfd) du côté enfant (qui n'a rien d'autre à
/// connaître que sa propre identité, accessible via `getpid`/`gettid`).
#[derive(Debug)]
pub enum CloneResult {
    /// Retour côté parent.
    Parent {
        /// PID du nouvel enfant.
        child_pid: Pid,
        /// `PidFd` si [`CloneFlags::PIDFD`] était positionné, `None` sinon.
        child_pidfd: Option<PidFd>,
    },
    /// Retour côté enfant.
    ///
    /// L'enfant doit typiquement exécuter ses traitements puis terminer
    /// (`exit_group`, ou — dans les tests Air — `std::process::exit` qui
    /// flush les compteurs LLVM de couverture). Voir le pattern recommandé
    /// dans la spec.
    Child,
}

// ─────────────────────────────────────────────────────────────────────────
// Attente d'événements : types associés à `waitid`.
// Spec : `docs/specs/layer-0/family-process.md` sous-section 3.
// ─────────────────────────────────────────────────────────────────────────

/// Cible d'un appel `waitid`.
///
/// L'enum encode à la fois `idtype` et `id` du syscall, en évitant les
/// combinaisons invalides (`P_PIDFD` avec un id qui n'est pas un fd, etc.).
#[derive(Debug, Clone, Copy)]
pub enum WaitTarget<'fd> {
    /// `P_ALL` — n'importe quel enfant.
    AnyChild,
    /// `P_PID` — un enfant désigné par son PID.
    Pid(Pid),
    /// `P_PGID` — n'importe quel processus du groupe désigné.
    ProcessGroup(Pid),
    /// `P_PGID` avec `id = 0` — le groupe de processus du caller.
    AnyProcessGroup,
    /// `P_PIDFD` — l'enfant référencé par le pidfd.
    PidFd(BorrowedFd<'fd>),
}

bitflags! {
    /// Options de `waitid` (`W*` flags).
    ///
    /// Au moins un parmi [`Self::EXITED`], [`Self::STOPPED`],
    /// [`Self::CONTINUED`] doit être positionné, sinon le kernel n'a aucun
    /// événement à rapporter et retourne `EINVAL`. Le wrapper laisse cette
    /// validation au kernel.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct WaitOptions: i32 {
        /// `WNOHANG` — ne pas bloquer si aucun événement n'est disponible.
        const NOHANG = 1;
        /// `WSTOPPED` — rapporter les arrêts (`SIGSTOP`/`SIGTSTP`/…).
        const STOPPED = 2;
        /// `WEXITED` — rapporter les terminaisons (normal, par signal).
        const EXITED = 4;
        /// `WCONTINUED` — rapporter les reprises (`SIGCONT`).
        const CONTINUED = 8;
        /// `WNOWAIT` — ne pas consommer l'événement (peek).
        const NOWAIT = 0x0100_0000;
    }
}

/// État rapporté par `waitid` pour un événement enfant.
#[derive(Debug, Clone, Copy)]
pub struct WaitStatus {
    /// PID de l'enfant concerné.
    pub pid: Pid,
    /// UID effectif de l'enfant au moment de l'événement.
    pub uid: u32,
    /// Type d'événement (terminaison, signal, arrêt, reprise, …).
    pub event: WaitEvent,
}

/// Type d'événement remonté par `waitid`.
///
/// Le mapping kernel `si_code` → variante :
/// - `CLD_EXITED` (1) → [`Self::Exited`]
/// - `CLD_KILLED` (2) → [`Self::Killed { core_dumped: false }`](Self::Killed)
/// - `CLD_DUMPED` (3) → [`Self::Killed { core_dumped: true }`](Self::Killed)
/// - `CLD_TRAPPED` (4) → [`Self::Trapped`]
/// - `CLD_STOPPED` (5) → [`Self::Stopped`]
/// - `CLD_CONTINUED` (6) → [`Self::Continued`]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WaitEvent {
    /// L'enfant a terminé normalement (`exit_group` / retour de `main`).
    Exited {
        /// Code de sortie (low 8 bits du `exit_group(status)`).
        code: i32,
    },
    /// L'enfant a été terminé par un signal.
    Killed {
        /// Signal fatal.
        signal: Signal,
        /// Vrai si le kernel a généré un fichier `core` (`CLD_DUMPED`).
        core_dumped: bool,
    },
    /// L'enfant a été arrêté (`SIGSTOP`/`SIGTSTP`).
    Stopped {
        /// Signal d'arrêt.
        signal: Signal,
    },
    /// L'enfant a été repris (`SIGCONT`).
    Continued,
    /// `ptrace` trap.
    Trapped {
        /// Signal de trap.
        signal: Signal,
    },
}

// ─────────────────────────────────────────────────────────────────────────
// prctl : modes exposés (sous-section 5 de family-process.md).
// ─────────────────────────────────────────────────────────────────────────

/// Mode `dumpable` du processus (`prctl(PR_GET_DUMPABLE | PR_SET_DUMPABLE)`).
///
/// Contrôle si le processus peut être « dumpé » : produit un core, peut être
/// attaché par ptrace, peut voir ses pages mémoire via `/proc/PID/mem`, etc.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum DumpableMode {
    /// `SUID_DUMP_DISABLE` (0) : non-dumpable. État après `execve` d'un
    /// binaire SUID/SGID/cap-augmenté.
    NotDumpable = 0,
    /// `SUID_DUMP_USER` (1) : dumpable par le propriétaire du processus.
    /// Valeur par défaut pour la majorité des processus.
    Dumpable = 1,
    /// `SUID_DUMP_ROOT` (2, déprécié) : dumpable uniquement par root.
    /// Conservé pour compatibilité historique ; les kernels récents le
    /// traitent essentiellement comme `Dumpable`.
    SuidDumpable = 2,
}

// ─────────────────────────────────────────────────────────────────────────
// rlimits (sous-section 6 de family-process.md).
// ─────────────────────────────────────────────────────────────────────────

/// Type de ressource pour `getrlimit`/`setrlimit`/`prlimit`.
///
/// Valeurs `RLIMIT_*` extraites de `asm-generic/resource.h` (identiques
/// `x86_64` et `aarch64` — ABI kernel stable hors archs hors ADR-014).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Resource {
    /// `RLIMIT_CPU` (0) : temps CPU max en secondes.
    Cpu = 0,
    /// `RLIMIT_FSIZE` (1) : taille max d'un fichier (octets).
    FileSize = 1,
    /// `RLIMIT_DATA` (2) : taille max du segment data.
    Data = 2,
    /// `RLIMIT_STACK` (3) : taille max de la pile.
    Stack = 3,
    /// `RLIMIT_CORE` (4) : taille max d'un core dump.
    Core = 4,
    /// `RLIMIT_RSS` (5) : taille max du RSS (largement ignoré depuis 2.4).
    Rss = 5,
    /// `RLIMIT_NPROC` (6) : nombre max de processus pour l'UID réel.
    NProc = 6,
    /// `RLIMIT_NOFILE` (7) : numéro max + 1 de FD ouvrable.
    NoFile = 7,
    /// `RLIMIT_MEMLOCK` (8) : taille max de mémoire `mlock()`'ée.
    MemLock = 8,
    /// `RLIMIT_AS` (9) : taille max de l'espace d'adressage virtuel.
    As = 9,
    /// `RLIMIT_LOCKS` (10) : nombre max de verrous `flock()` / `fcntl()`.
    Locks = 10,
    /// `RLIMIT_SIGPENDING` (11) : nombre max de signaux pendants en file.
    SigPending = 11,
    /// `RLIMIT_MSGQUEUE` (12) : octets max alloués aux POSIX message queues.
    MsgQueue = 12,
    /// `RLIMIT_NICE` (13) : niveau `nice` ceiling (offset depuis 20).
    Nice = 13,
    /// `RLIMIT_RTPRIO` (14) : priorité temps-réel ceiling.
    RtPrio = 14,
    /// `RLIMIT_RTTIME` (15) : temps CPU max (µs) en politique RT sans bloquer.
    RtTime = 15,
}

/// Valeur d'une limite de ressource. `Infinity` correspond à
/// `RLIM_INFINITY` (`u64::MAX` sur LP64).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum RlimitValue {
    /// Limite finie.
    Finite(u64),
    /// `RLIM_INFINITY` côté kernel — pas de limite.
    Infinity,
}

/// Paire (soft, hard) de limites de ressource.
///
/// La soft limit est celle réellement appliquée. La hard limit est le
/// plafond que la soft limit ne peut excéder ; baisser la hard limit est
/// possible pour tout processus, la relever exige `CAP_SYS_RESOURCE`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Rlimit {
    /// Limite douce (effectivement appliquée).
    pub soft: RlimitValue,
    /// Limite dure (plafond pour la soft limit).
    pub hard: RlimitValue,
}

// ─────────────────────────────────────────────────────────────────────────
// Capabilities (sous-section 7 de family-process.md).
// ─────────────────────────────────────────────────────────────────────────

/// Capability Linux — permission fine remplaçant le modèle binaire
/// root/non-root.
///
/// **Ensemble complet.** Les **41** capabilities du noyau (`CAP_CHOWN` = 0 …
/// `CAP_CHECKPOINT_RESTORE` = 40 = `CAP_LAST_CAP` sur Linux ≥ 5.9) sont **toutes**
/// nommées (ADR-126, `couche-0-v1.14`). Un consommateur peut donc désigner
/// n'importe quelle capability — en particulier pour **réduire un bounding set à un
/// sous-ensemble exact** (privsep, ADR-124), ce que le stub partiel initial (20/41)
/// ne permettait pas.
///
/// **Valeurs numériques.** Tirées de `include/uapi/linux/capability.h` ;
/// identiques `x86_64` et `aarch64` (ABI kernel stable hors archs hors
/// ADR-014).
///
/// **Note de discipline (mot haut).** Les valeurs 32-40 (`CAP_MAC_OVERRIDE` …
/// `CAP_CHECKPOINT_RESTORE`) occupent le **mot haut** (bits 32-63) du
/// `CapabilityMask` (`u64`) et donc le second mot `u32` de l'ABI `capget`/`capset`.
/// La conversion lo/hi est faite par les helpers d'`air-sys-syscall`
/// (`mask_to_words`/`words_to_mask`) et testée explicitement (masque à bit ≥ 32)
/// pour catcher une éventuelle inversion lo/hi.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
#[repr(u32)]
pub enum Capability {
    /// `CAP_CHOWN` (0) : changer l'ownership d'un fichier arbitrairement.
    Chown = 0,
    /// `CAP_DAC_OVERRIDE` (1) : passer outre les vérifications DAC.
    DacOverride = 1,
    /// `CAP_DAC_READ_SEARCH` (2) : lire/parcourir tout fichier/répertoire.
    DacReadSearch = 2,
    /// `CAP_FOWNER` (3) : opérations habituellement réservées au propriétaire.
    Fowner = 3,
    /// `CAP_FSETID` (4) : ne pas vider SUID/SGID sur modification.
    Fsetid = 4,
    /// `CAP_KILL` (5) : envoyer signal à n'importe quel processus.
    Kill = 5,
    /// `CAP_SETGID` (6) : manipulation arbitraire des GID.
    Setgid = 6,
    /// `CAP_SETUID` (7) : manipulation arbitraire des UID.
    Setuid = 7,
    /// `CAP_SETPCAP` (8) : transfert/retrait de capabilities (dont `PR_CAPBSET_DROP`).
    Setpcap = 8,
    /// `CAP_LINUX_IMMUTABLE` (9) : poser les attributs `IMMUTABLE`/`APPEND`.
    LinuxImmutable = 9,
    /// `CAP_NET_BIND_SERVICE` (10) : bind sur ports < 1024.
    NetBindService = 10,
    /// `CAP_NET_BROADCAST` (11) : broadcast et écoute multicast.
    NetBroadcast = 11,
    /// `CAP_NET_ADMIN` (12) : configuration réseau (interfaces, routage…).
    NetAdmin = 12,
    /// `CAP_NET_RAW` (13) : sockets raw et packet.
    NetRaw = 13,
    /// `CAP_IPC_LOCK` (14) : verrouiller de la mémoire (`mlock`, `SHM_LOCK`).
    IpcLock = 14,
    /// `CAP_IPC_OWNER` (15) : passer outre les vérifications de propriété IPC.
    IpcOwner = 15,
    /// `CAP_SYS_MODULE` (16) : load/unload de modules kernel.
    SysModule = 16,
    /// `CAP_SYS_RAWIO` (17) : I/O ports, `/dev/mem`, etc.
    SysRawio = 17,
    /// `CAP_SYS_CHROOT` (18) : `chroot(2)`.
    SysChroot = 18,
    /// `CAP_SYS_PTRACE` (19) : `ptrace` arbitraire.
    SysPtrace = 19,
    /// `CAP_SYS_PACCT` (20) : `acct(2)` (comptabilité des processus).
    SysPacct = 20,
    /// `CAP_SYS_ADMIN` (21) : « capability fourre-tout » système.
    SysAdmin = 21,
    /// `CAP_SYS_BOOT` (22) : `reboot(2)` et `kexec_load(2)`.
    SysBoot = 22,
    /// `CAP_SYS_NICE` (23) : priorités CPU et politiques RT/IO.
    SysNice = 23,
    /// `CAP_SYS_RESOURCE` (24) : relever les hard limits et autres ceilings.
    SysResource = 24,
    /// `CAP_SYS_TIME` (25) : horloge système et RTC.
    SysTime = 25,
    /// `CAP_SYS_TTY_CONFIG` (26) : configuration TTY et `vhangup(2)`.
    SysTtyConfig = 26,
    /// `CAP_MKNOD` (27) : créer des fichiers spéciaux via `mknod(2)`.
    Mknod = 27,
    /// `CAP_LEASE` (28) : poser des baux (`fcntl(F_SETLEASE)`).
    Lease = 28,
    /// `CAP_AUDIT_WRITE` (29) : écrire des enregistrements dans le journal d'audit.
    AuditWrite = 29,
    /// `CAP_AUDIT_CONTROL` (30) : configurer/désactiver l'audit du kernel.
    AuditControl = 30,
    /// `CAP_SETFCAP` (31) : poser des file-capabilities.
    Setfcap = 31,
    /// `CAP_MAC_OVERRIDE` (32) : passer outre le MAC (LSM Smack…).
    MacOverride = 32,
    /// `CAP_MAC_ADMIN` (33) : administrer la politique MAC.
    MacAdmin = 33,
    /// `CAP_SYSLOG` (34) : opérations `syslog(2)` privilégiées.
    Syslog = 34,
    /// `CAP_WAKE_ALARM` (35) : armer un réveil qui sort le système de veille.
    WakeAlarm = 35,
    /// `CAP_BLOCK_SUSPEND` (36) : empêcher la mise en veille du système.
    BlockSuspend = 36,
    /// `CAP_AUDIT_READ` (37) : lire le journal d'audit via socket multicast.
    AuditRead = 37,
    /// `CAP_PERFMON` (38) : monitoring de performance (`perf_event_open`…).
    Perfmon = 38,
    /// `CAP_BPF` (39) : opérations `bpf(2)` privilégiées.
    Bpf = 39,
    /// `CAP_CHECKPOINT_RESTORE` (40) : checkpoint/restore (`CAP_LAST_CAP`).
    CheckpointRestore = 40,
}

impl Capability {
    /// Retourne l'index ABI kernel (valeur numérique de `CAP_*`).
    #[must_use]
    #[inline]
    pub const fn as_raw(self) -> u32 {
        self as u32
    }
}

/// Bitmask des capabilities.
///
/// Représentation interne `u64` : le bit `i` est positionné ssi la
/// `Capability` de valeur numérique `i` est dans le masque. Les Linux v3
/// capabilities (kernel ≥ 2.6.25) utilisent 64 bits côté kernel, exposés
/// par l'ABI `capget`/`capset` sous forme de deux mots `u32` (bits 0-31
/// puis bits 32-63) ; la conversion est réalisée par les helpers du
/// wrapper `air-sys-syscall`.
#[repr(transparent)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct CapabilityMask(u64);

impl CapabilityMask {
    /// Masque vide (aucune capability).
    #[must_use]
    #[inline]
    pub const fn empty() -> Self {
        Self(0)
    }

    /// Construit un masque depuis sa représentation brute u64.
    #[must_use]
    #[inline]
    pub const fn from_bits(bits: u64) -> Self {
        Self(bits)
    }

    /// Représentation brute u64 du masque.
    #[must_use]
    #[inline]
    pub const fn bits(self) -> u64 {
        self.0
    }

    /// Vrai si `cap` est dans le masque.
    #[must_use]
    #[inline]
    pub const fn contains(self, cap: Capability) -> bool {
        (self.0 & (1_u64 << cap.as_raw())) != 0
    }

    /// Retourne un nouveau masque avec `cap` positionné.
    #[must_use]
    #[inline]
    pub const fn with(self, cap: Capability) -> Self {
        Self(self.0 | (1_u64 << cap.as_raw()))
    }

    /// Retourne un nouveau masque avec `cap` retiré.
    #[must_use]
    #[inline]
    pub const fn without(self, cap: Capability) -> Self {
        Self(self.0 & !(1_u64 << cap.as_raw()))
    }
}

/// Triple des ensembles de capabilities pour un thread.
///
/// Trois ensembles indépendants :
/// - `effective` : capabilities **actuellement utilisables** par le thread.
/// - `permitted` : capabilities que le thread **peut activer** dans
///   `effective` (super-ensemble de `effective` typiquement).
/// - `inheritable` : capabilities **transmises** à travers `execve(2)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct CapabilitySet {
    /// Capabilities actuellement actives.
    pub effective: CapabilityMask,
    /// Capabilities activables dans `effective`.
    pub permitted: CapabilityMask,
    /// Capabilities transmises à `execve(2)`.
    pub inheritable: CapabilityMask,
}

/// Cible d'un appel `capget`/`capset`.
///
/// Per ADR-021 convention 1, l'invocation « pour soi-même » est exprimée
/// par la variante dédiée [`CapabilityTarget::CurrentThread`] plutôt que par une
/// sentinelle kernel `pid == 0`.
#[derive(Debug, Clone, Copy)]
pub enum CapabilityTarget {
    /// Thread courant (équivalent kernel `pid == 0`).
    CurrentThread,
    /// Thread désigné par son TID Linux.
    Thread(Tid),
    /// Processus désigné par son PID (premier thread du groupe).
    Process(Pid),
}

#[cfg(test)]
mod tests;

// ─────────────────────────────────────────────────────────────────────────
// Ressources — `getrusage(2)` (ADR-051, re-sceau couche-0-v1.7)
// ─────────────────────────────────────────────────────────────────────────

/// `struct timeval` du kernel (`time_t tv_sec`, `suseconds_t tv_usec`), tel que
/// rempli par `getrusage(2)`. Layout `#[repr(C)]` fidèle, cibles 64-bit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(C)]
pub struct Timeval {
    /// Secondes.
    pub tv_sec: i64,
    /// Microsecondes (`[0, 1_000_000)`).
    pub tv_usec: i64,
}

/// Cible d'une mesure [`Rusage`] pour `getrusage(2)`. Re-présente `RUSAGE_*` en
/// enum typé (pas de constante magique exposée — ADR-021).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RusageWho {
    /// Le processus appelant (`RUSAGE_SELF`).
    SelfProcess,
    /// Tous les enfants terminés **et attendus** (`RUSAGE_CHILDREN`).
    Children,
    /// Le thread appelant (`RUSAGE_THREAD`).
    Thread,
}

/// `struct rusage` du kernel : statistiques de ressources (`getrusage(2)`).
///
/// Layout `#[repr(C)]` **fidèle au kernel** (2 `timeval` + 14 `long`), cibles
/// 64-bit (ADR-014). Plusieurs champs ne sont **pas maintenus** par Linux (legacy
/// BSD) et restent à `0` — on les expose tels quels (transparence, kernel = bible).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(C)]
pub struct Rusage {
    /// Temps CPU passé en mode **utilisateur**.
    pub ru_utime: Timeval,
    /// Temps CPU passé en mode **noyau**.
    pub ru_stime: Timeval,
    /// Taille mémoire résidente **maximale** (Kio).
    pub ru_maxrss: i64,
    /// Mémoire partagée (non maintenu par Linux).
    pub ru_ixrss: i64,
    /// Mémoire data non partagée (non maintenu).
    pub ru_idrss: i64,
    /// Mémoire pile non partagée (non maintenu).
    pub ru_isrss: i64,
    /// Fautes de page **mineures** (sans I/O).
    pub ru_minflt: i64,
    /// Fautes de page **majeures** (avec I/O).
    pub ru_majflt: i64,
    /// Swaps (non maintenu).
    pub ru_nswap: i64,
    /// Lectures bloc en entrée.
    pub ru_inblock: i64,
    /// Écritures bloc en sortie.
    pub ru_oublock: i64,
    /// Messages IPC envoyés (non maintenu).
    pub ru_msgsnd: i64,
    /// Messages IPC reçus (non maintenu).
    pub ru_msgrcv: i64,
    /// Signaux reçus (non maintenu).
    pub ru_nsignals: i64,
    /// Changements de contexte **volontaires**.
    pub ru_nvcsw: i64,
    /// Changements de contexte **involontaires**.
    pub ru_nivcsw: i64,
}

#[cfg(test)]
mod rusage_types_tests;