air_sys_syscall/

terminal.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/.

//! Wrappers de la famille `terminal` (termios/tty).
//!
//! Cf. `docs/specs/layer-0/family-terminal.md` et
//! [ADR-060](../../../docs/adrs/ADR-060-descellement-couche0-termios-tty-fr.md).
//!
//! **Tranche 2 — groupe « Attributs ».** Les deux ioctls typés du cœur termios,
//! consommant le type [`Termios`] d'`air-sys-types` :
//! - [`tcgetattr`] (`TCGETS`) : lit les attributs courants du terminal ;
//! - [`tcsetattr`] (`TCSETS`/`TCSETSW`/`TCSETSF`) : les applique selon une
//!   [`SetAction`] typée (mapping par `match` exhaustif — **jamais** l'arithmétique
//!   `TCSETS + action`, fragile, pointée par l'audit musl §8).
//!
//! **Tranche 3 — groupes « Contrôle de ligne » et « Taille fenêtre ».** Les `tc*`
//! POSIX restants et les ioctls de dimension de fenêtre :
//! - [`tcdrain`] (`TCSBRK`, argument `1`) : attend la transmission de la sortie ;
//! - [`tcflush`] (`TCFLSH`) : purge une [`FlushQueue`] (entrée/sortie/les deux) ;
//! - [`tcflow`] (`TCXONC`) : suspend/reprend le flux selon une [`FlowAction`] ;
//! - [`tcsendbreak`] (`TCSBRK`, argument `0`) : envoie un break (durée **non
//!   paramétrée** — honnêteté de contrat, cf. audit musl §6/§8) ;
//! - [`get_winsize`]/[`set_winsize`] (`TIOCGWINSZ`/`TIOCSWINSZ`) : lit/écrit la
//!   [`Winsize`] du terminal.
//!
//! **Tranche 4 — groupe « PTY ».** Allocation d'une paire maître/esclave de
//! pseudo-terminal :
//! - [`open_pty_master`] : ouvre un nouveau maître via `/dev/ptmx` (dogfoode
//!   [`crate::fs::openat`]) ;
//! - [`pty_number`] (`TIOCGPTN`) : numéro [`PtyNumber`] de l'esclave (`/dev/pts/N`) ;
//! - [`pty_unlock`] (`TIOCSPTLCK`) : déverrouille l'esclave (prérequis d'ouverture) ;
//! - [`pty_peer`] (`TIOCGPTPEER`) : ouvre **directement** l'esclave (anti-TOCTOU,
//!   Linux 4.13+) — évite la résolution du chemin `/dev/pts/N`.
//!
//! **Tranche 5 — groupe « Session / job-control ».** Terminal de contrôle et
//! groupes de premier plan :
//! - [`tcgetpgrp`] (`TIOCGPGRP`) : groupe de premier plan du terminal
//!   (`Option<Pid>` — un `pid_t` `0` du kernel = **aucun** groupe, ADR-021 conv. 1) ;
//! - [`tcsetpgrp`] (`TIOCSPGRP`) : installe un groupe de premier plan typé ;
//! - [`session_id`] (`TIOCGSID`) : identifiant de session du terminal ;
//! - [`set_ctty`] (`TIOCSCTTY`, argument `0`) : fait du terminal le terminal de
//!   **contrôle** du leader de session appelant — **sans vol** (le vol `arg=1`
//!   exige `CAP_SYS_ADMIN`, hors périmètre — UNSUPPORTED) ;
//! - [`clear_ctty`] (`TIOCNOTTY`) : détache le terminal de contrôle.
//!
//! Ces cinq-là exigent, pour leur chemin **nominal**, un terminal de **contrôle**
//! (que le kernel refuse hors leader de session) : ils sont donc validés dans un
//! **enfant forké** `setsid` (tests), et les lignes de leur bras `Ok` — exécutées
//! uniquement dans cet enfant — sont des exceptions **CHILD-EXIT** (ADR-035 ;
//! profil LLVM non flushé côté enfant, async-signal-safe — cf. `process.rs`).
//!
//! Chaque opération est une **fonction dédiée typée** (ADR-021 conv. 3 : jamais
//! d'`ioctl(fd, REQ, …)` générique). Zéro allocation (le [`Termios`]/[`Winsize`]
//! vit sur la pile). `EINTR` est remonté tel quel à l'appelant (ADR-021 conv. 2),
//! aucun retry automatique — [`tcdrain`] est un point d'annulation (audit §3). Le
//! maître `/dev/ptmx` sert de tty réel dans les tests.

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd};
use core::num::NonZeroI32;

use air_sys_types::fs::{DirFd, OpenFlags};
use air_sys_types::{Errno, FlowAction, FlushQueue, Pid, PtyNumber, SetAction, Termios, Winsize};

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::terminal supporte uniquement x86_64 et aarch64 (ADR-014).");

// ─────────────────────────────────────────────────────────────────────────
// Constantes kernel — requêtes ioctl termios (identiques x86_64 / aarch64).
//
// Valeurs de `<asm-generic/ioctls.h>` : sur `asm-generic`, la famille `TC*` est
// numérotée en clair (pas d'encodage `_IOC`), et les deux architectures cibles
// (x86_64, aarch64) partagent ces mêmes valeurs.
// ─────────────────────────────────────────────────────────────────────────

/// `TCGETS` — lit `struct termios` du terminal.
const TCGETS: u64 = 0x5401;
/// `TCSETS` — écrit `struct termios` immédiatement (`TCSANOW`).
const TCSETS: u64 = 0x5402;
/// `TCSETSW` — écrit après vidage de la file de sortie (`TCSADRAIN`).
const TCSETSW: u64 = 0x5403;
/// `TCSETSF` — écrit après vidage sortie + purge de l'entrée (`TCSAFLUSH`).
const TCSETSF: u64 = 0x5404;
/// `TCSBRK` — envoie un break (argument `0`) ou draine la sortie (argument non
/// nul) ; l'argument entier distingue les deux sémantiques (cf. musl).
const TCSBRK: u64 = 0x5409;
/// `TCXONC` — contrôle de flux (démarrer/suspendre l'entrée ou la sortie).
const TCXONC: u64 = 0x540A;
/// `TCFLSH` — purge une (ou les deux) file(s) d'octets non transmis/non lus.
const TCFLSH: u64 = 0x540B;
/// `TIOCGWINSZ` — lit `struct winsize` (dimensions de la fenêtre du terminal).
const TIOCGWINSZ: u64 = 0x5413;
/// `TIOCSWINSZ` — écrit `struct winsize` (déclenche `SIGWINCH`).
const TIOCSWINSZ: u64 = 0x5414;

// Requêtes ioctl d'allocation PTY (tranche 4). Contrairement aux `TC*`
// numérotées en clair ci-dessus, ces trois-là suivent le schéma d'encodage
// `_IOC` arch-générique de `<asm-generic/ioctls.h>` (`_IOR`/`_IOW`/`_IO`) —
// **identiques sur x86_64 et aarch64** (tous deux `asm-generic`).

/// `TIOCGPTN` — `_IOR('T', 0x30, unsigned int)` : le kernel **écrit** le numéro
/// (`u32`) de l'esclave associé au maître `/dev/ptmx`.
const TIOCGPTN: u64 = 0x8004_5430;
/// `TIOCSPTLCK` — `_IOW('T', 0x31, int)` : le kernel **lit** un `int` de
/// (dé)verrouillage de l'esclave (`0` = déverrouille, prérequis à son ouverture).
const TIOCSPTLCK: u64 = 0x4004_5431;
/// `TIOCGPTPEER` — `_IO('T', 0x41)` : ouvre **directement** l'esclave du maître
/// (Linux 4.13+, évite le TOCTOU du chemin `/dev/pts/N`). L'argument est une
/// valeur entière de drapeaux d'ouverture ; la valeur de retour est le nouveau fd.
const TIOCGPTPEER: u64 = 0x5441;

// Requêtes ioctl de session / job-control (tranche 5). Numérotées en clair dans
// `<asm-generic/ioctls.h>` (comme les `TC*`), identiques x86_64/aarch64.

/// `TIOCSCTTY` — fait de `fd` le terminal de **contrôle** du leader de session
/// appelant. L'argument est un entier : `0` = acquisition **sans vol**.
const TIOCSCTTY: u64 = 0x540E;
/// `TIOCGPGRP` — le kernel **écrit** le `pid_t` (i32) du groupe de premier plan.
const TIOCGPGRP: u64 = 0x540F;
/// `TIOCSPGRP` — le kernel **lit** le `pid_t` (i32) du groupe de premier plan à
/// installer.
const TIOCSPGRP: u64 = 0x5410;
/// `TIOCNOTTY` — détache le terminal de **contrôle** du processus appelant.
const TIOCNOTTY: u64 = 0x5422;
/// `TIOCGSID` — le kernel **écrit** le `pid_t` (i32) du leader de session du
/// terminal.
const TIOCGSID: u64 = 0x5429;

/// Argument `TIOCSCTTY` : `0` → **acquisition sans vol**. Le vol (`arg = 1`) exige
/// `CAP_SYS_ADMIN` et n'est **pas** exposé (hors périmètre — UNSUPPORTED).
const TIOCSCTTY_NO_STEAL: u64 = 0;

// Arguments entiers (non pointeurs) des ioctls `TCSBRK`/`TCFLSH`/`TCXONC`.
// Valeurs `<asm-generic/termbits.h>`, identiques x86_64/aarch64.

/// Argument `TCSBRK` : `0` → **envoi de break** ([`tcsendbreak`]).
const TCSBRK_SEND_BREAK: u64 = 0;
/// Argument `TCSBRK` : `1` (non nul) → **drainage de la sortie** ([`tcdrain`]).
const TCSBRK_DRAIN: u64 = 1;
/// Argument `TCFLSH` : `TCIFLUSH` — purge les données reçues non lues.
const TCIFLUSH: u64 = 0;
/// Argument `TCFLSH` : `TCOFLUSH` — purge les données écrites non transmises.
const TCOFLUSH: u64 = 1;
/// Argument `TCFLSH` : `TCIOFLUSH` — purge les deux files.
const TCIOFLUSH: u64 = 2;
/// Argument `TCXONC` : `TCOOFF` — suspend la sortie.
const TCOOFF: u64 = 0;
/// Argument `TCXONC` : `TCOON` — reprend la sortie.
const TCOON: u64 = 1;
/// Argument `TCXONC` : `TCIOFF` — émet un STOP (suspend l'entrée distante).
const TCIOFF: u64 = 2;
/// Argument `TCXONC` : `TCION` — émet un START (reprend l'entrée distante).
const TCION: u64 = 3;

// ─────────────────────────────────────────────────────────────────────────
// Attributs — tcgetattr / tcsetattr.
// ─────────────────────────────────────────────────────────────────────────

/// `tcgetattr` (`TCGETS`) — lit les attributs courants du terminal `fd`.
///
/// Alloue un [`Termios::zeroed`] sur la pile, le fait remplir par le kernel via
/// l'ioctl `TCGETS`, puis le renvoie. Aucune allocation heap. Le retour est
/// **normalisé** (comme musl) : sur échec de l'ioctl, l'`Errno` correspondant ;
/// sinon le [`Termios`] rempli.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
/// - [`Errno::EINTR`] : interrompu par un signal (remonté tel quel, ADR-021 conv. 2).
pub fn tcgetattr(fd: BorrowedFd<'_>) -> Result<Termios, Errno> {
    let mut attributes = Termios::zeroed();
    // Le kernel écrit `sizeof(struct termios)` octets à cette adresse ; on la
    // passe en `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw mut attributes).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TCGETS, &mut termios) écrit `struct termios` à `argument`
    // — une variable de pile vivante, alignée, dimensionnée pour `Termios`
    // (image `#[repr(C)]` exacte du kernel). Aucune autre mémoire n'est touchée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TCGETS, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(attributes)
}

/// `tcsetattr` (`TCSETS`/`TCSETSW`/`TCSETSF`) — applique `attributes` au terminal
/// `fd`, à l'instant indiqué par `action`.
///
/// L'`action` est mappée vers la requête ioctl par un `match` **exhaustif** (et
/// non par l'arithmétique `TCSETS + action`, fragile car dépendante de la
/// contiguïté des constantes — audit musl §8) : [`SetAction::Now`] → `TCSETS`,
/// [`SetAction::Drain`] → `TCSETSW`, [`SetAction::Flush`] → `TCSETSF`.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
/// - [`Errno::EINTR`] : interrompu par un signal (remonté tel quel, ADR-021 conv. 2).
pub fn tcsetattr(fd: BorrowedFd<'_>, action: SetAction, attributes: &Termios) -> Result<(), Errno> {
    let request = match action {
        SetAction::Now => TCSETS,
        SetAction::Drain => TCSETSW,
        SetAction::Flush => TCSETSF,
    };
    // Le kernel lit `sizeof(struct termios)` octets à cette adresse ; on la passe
    // en `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (attributes as *const Termios).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TCSETS*, &termios) lit `struct termios` à `argument` —
    // le `Termios` emprunté par `attributes`, vivant et aligné (image `#[repr(C)]`
    // exacte du kernel). Aucune écriture de mémoire utilisateur.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), request, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Contrôle de ligne — tcdrain / tcflush / tcflow / tcsendbreak (tranche 3).
// ─────────────────────────────────────────────────────────────────────────

/// `tcdrain` (`TCSBRK`, argument **1**) — bloque jusqu'à ce que tous les octets
/// déjà écrits vers `fd` aient été transmis.
///
/// Sur Linux, `ioctl(fd, TCSBRK, arg)` avec un `arg` **non nul** ne fait pas un
/// envoi de break : il **draine** la file de sortie (sémantique `tcdrain`, cf.
/// musl). L'envoi de break correspond à `arg == 0` ([`tcsendbreak`]).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
/// - [`Errno::EINTR`] : interrompu par un signal pendant l'attente — **remonté
///   tel quel**, aucun retry automatique (ADR-021 conv. 2 ; l'appelant qui veut
///   retenter écrit la boucle). `tcdrain` est le point d'annulation de la famille
///   (audit musl §3).
pub fn tcdrain(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: ioctl(fd, TCSBRK, 1) — l'argument est une valeur entière (1 =
    // drainer la sortie), pas un pointeur : aucune mémoire utilisateur n'est lue
    // ni écrite par le kernel.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TCSBRK, TCSBRK_DRAIN) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `tcflush` (`TCFLSH`) — purge (jette) les octets non traités de la (des) file(s)
/// désignée(s) par `queue`.
///
/// Le mapping [`FlushQueue`] → argument entier se fait par un `match` **exhaustif**
/// (ADR-021 conv. 3) : [`FlushQueue::Input`] → `TCIFLUSH` (`0`),
/// [`FlushQueue::Output`] → `TCOFLUSH` (`1`), [`FlushQueue::Both`] → `TCIOFLUSH`
/// (`2`).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn tcflush(fd: BorrowedFd<'_>, queue: FlushQueue) -> Result<(), Errno> {
    let argument = match queue {
        FlushQueue::Input => TCIFLUSH,
        FlushQueue::Output => TCOFLUSH,
        FlushQueue::Both => TCIOFLUSH,
    };
    // SAFETY: ioctl(fd, TCFLSH, arg) — `arg` est une valeur entière (file à
    // purger), pas un pointeur : aucune mémoire utilisateur n'est accédée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TCFLSH, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `tcflow` (`TCXONC`) — suspend ou reprend le flux d'entrée ou de sortie de `fd`.
///
/// Le mapping [`FlowAction`] → argument entier se fait par un `match` **exhaustif**
/// (ADR-021 conv. 3) : [`FlowAction::SuspendOutput`] → `TCOOFF` (`0`),
/// [`FlowAction::ResumeOutput`] → `TCOON` (`1`), [`FlowAction::SuspendInput`] →
/// `TCIOFF` (`2`, émet un STOP), [`FlowAction::ResumeInput`] → `TCION` (`3`, émet
/// un START).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn tcflow(fd: BorrowedFd<'_>, action: FlowAction) -> Result<(), Errno> {
    let argument = match action {
        FlowAction::SuspendOutput => TCOOFF,
        FlowAction::ResumeOutput => TCOON,
        FlowAction::SuspendInput => TCIOFF,
        FlowAction::ResumeInput => TCION,
    };
    // SAFETY: ioctl(fd, TCXONC, arg) — `arg` est une valeur entière (action de
    // flux), pas un pointeur : aucune mémoire utilisateur n'est accédée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TCXONC, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `tcsendbreak` (`TCSBRK`, argument **0**) — transmet une séquence de bits `0`
/// (condition BREAK) sur une ligne asynchrone.
///
/// **Durée non paramétrée (honnêteté de contrat).** POSIX prévoit un paramètre de
/// durée, mais l'implémentation le rend *implementation-defined* et musl l'**ignore
/// silencieusement** (audit musl §6/§8). Plutôt que d'exposer un paramètre qui
/// serait avalé sans effet, Air n'en expose **aucun** : le break dure la durée par
/// défaut du kernel. Le contrat dit exactement ce qu'il fait (doctrine « la libc
/// fait ce qu'elle dit »).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn tcsendbreak(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: ioctl(fd, TCSBRK, 0) — l'argument est une valeur entière (0 = envoi
    // de break), pas un pointeur : aucune mémoire utilisateur n'est accédée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TCSBRK, TCSBRK_SEND_BREAK) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Taille fenêtre — get_winsize / set_winsize (tranche 3).
// ─────────────────────────────────────────────────────────────────────────

/// `get_winsize` (`TIOCGWINSZ`) — lit les dimensions courantes de la fenêtre du
/// terminal `fd`.
///
/// Alloue un [`Winsize::zeroed`] sur la pile, le fait remplir par le kernel via
/// l'ioctl `TIOCGWINSZ`, puis le renvoie. Aucune allocation heap. Sur échec de
/// l'ioctl, l'`Errno` correspondant.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn get_winsize(fd: BorrowedFd<'_>) -> Result<Winsize, Errno> {
    let mut size = Winsize::zeroed();
    // Le kernel écrit `sizeof(struct winsize)` octets à cette adresse ; on la
    // passe en `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw mut size).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TIOCGWINSZ, &mut winsize) écrit `struct winsize` à
    // `argument` — une variable de pile vivante, alignée, dimensionnée pour
    // `Winsize` (image `#[repr(C)]` exacte du kernel). Aucune autre mémoire touchée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCGWINSZ, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(size)
}

/// `set_winsize` (`TIOCSWINSZ`) — impose les dimensions `size` à la fenêtre du
/// terminal `fd` (le kernel émet `SIGWINCH` vers le groupe de premier plan).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn set_winsize(fd: BorrowedFd<'_>, size: &Winsize) -> Result<(), Errno> {
    // Le kernel lit `sizeof(struct winsize)` octets à cette adresse ; on la passe
    // en `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (size as *const Winsize).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TIOCSWINSZ, &winsize) lit `struct winsize` à `argument` —
    // le `Winsize` emprunté par `size`, vivant et aligné (image `#[repr(C)]` exacte
    // du kernel). Aucune écriture de mémoire utilisateur.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCSWINSZ, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// PTY — open_pty_master / pty_number / pty_unlock / pty_peer (tranche 4).
// ─────────────────────────────────────────────────────────────────────────

/// `open_pty_master` — ouvre un **nouveau** maître de pseudo-terminal via
/// `/dev/ptmx`.
///
/// Chaque appel alloue une **paire maître/esclave** distincte (le kernel crée un
/// nouvel esclave `/dev/pts/N` à chaque ouverture de `/dev/ptmx`). Le maître est
/// rendu en [`OwnedFd`] (RAII — fermé au `Drop`, ce qui libère la paire).
///
/// Dogfoode l'API `fs` : délègue à [`crate::fs::openat`] (qui ajoute `O_CLOEXEC`),
/// plutôt qu'un `open` brut. `O_RDWR` (lecture/écriture du maître) et `O_NOCTTY`
/// (le maître ne doit **pas** devenir le terminal contrôlant du processus).
///
/// Le déverrouillage de l'esclave ([`pty_unlock`]) puis son ouverture
/// ([`pty_peer`]) constituent la suite du flux d'allocation.
///
/// # Errors
///
/// - [`Errno::ENOSPC`] : plus aucun pseudo-terminal disponible (limite atteinte).
/// - [`Errno::EACCES`]/[`Errno::ENOENT`] : `/dev/ptmx` absent ou inaccessible.
/// - Toute erreur propagée par [`crate::fs::openat`].
pub fn open_pty_master() -> Result<OwnedFd, Errno> {
    crate::fs::openat(
        DirFd::Cwd,
        c"/dev/ptmx",
        OpenFlags::RDWR | OpenFlags::NOCTTY,
        0,
    )
}

/// `pty_number` (`TIOCGPTN`) — numéro de l'esclave associé au maître `master`.
///
/// Le kernel écrit un `unsigned int` (`u32`) à une adresse de pile ; on le
/// renvoie enveloppé dans un [`PtyNumber`] typé. C'est l'`N` du nœud
/// `/dev/pts/N`.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `master` n'est pas un maître de PTY.
/// - [`Errno::EBADF`] : `master` n'est pas un descripteur valide.
pub fn pty_number(master: BorrowedFd<'_>) -> Result<PtyNumber, Errno> {
    let mut number: u32 = 0;
    // Le kernel écrit `sizeof(unsigned int)` octets à cette adresse ; on la passe
    // en `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw mut number).cast::<u8>() as u64;
    // SAFETY: ioctl(master, TIOCGPTN, &mut number) écrit un `unsigned int` (u32) à
    // `argument` — une variable de pile vivante, alignée, dimensionnée pour un u32.
    // Aucune autre mémoire n'est touchée.
    let result = unsafe { raw_syscall_ioctl(master.as_raw_fd(), TIOCGPTN, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(PtyNumber::new(number))
}

/// `pty_unlock` (`TIOCSPTLCK`, valeur `0`) — déverrouille l'esclave de `master`.
///
/// Le déverrouillage est **obligatoire** avant d'ouvrir l'esclave (équivalent de
/// `unlockpt`). Le kernel **lit** un `int` à l'adresse passée : on lui présente un
/// `0` de pile. Le verrouillage (`1`) n'est **pas** exposé — seul le
/// déverrouillage est utile en pratique (comme `unlockpt`).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `master` n'est pas un maître de PTY.
/// - [`Errno::EBADF`] : `master` n'est pas un descripteur valide.
pub fn pty_unlock(master: BorrowedFd<'_>) -> Result<(), Errno> {
    let unlock: i32 = 0;
    // Le kernel lit `sizeof(int)` octets à cette adresse ; on la passe en `u64`
    // (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw const unlock).cast::<u8>() as u64;
    // SAFETY: ioctl(master, TIOCSPTLCK, &unlock) LIT un `int` à `argument` — une
    // variable de pile vivante, alignée, dimensionnée pour un i32 (valeur 0 =
    // déverrouiller). Aucune écriture de mémoire utilisateur.
    let result = unsafe { raw_syscall_ioctl(master.as_raw_fd(), TIOCSPTLCK, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `pty_peer` (`TIOCGPTPEER`) — ouvre **directement** l'esclave de `master` et
/// renvoie son descripteur.
///
/// Voie **moderne** (Linux 4.13+) : elle évite le TOCTOU du chemin `/dev/pts/N`
/// (où l'esclave pourrait être substitué entre la résolution du nom et
/// l'ouverture). L'argument ioctl est une **valeur entière** de drapeaux
/// d'ouverture — `O_RDWR | O_NOCTTY | O_CLOEXEC`, `O_CLOEXEC` étant demandé
/// **explicitement** (cet ioctl ne l'ajoute pas, contrairement à [`crate::fs::openat`]).
/// La **valeur de retour** de l'ioctl est le nouveau fd de l'esclave.
///
/// Prérequis : l'esclave doit être déverrouillé au préalable ([`pty_unlock`]).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `master` n'est pas un maître de PTY.
/// - [`Errno::EBADF`] : `master` n'est pas un descripteur valide.
/// - [`Errno::EINVAL`] : kernel antérieur à 4.13 (ioctl non pris en charge).
pub fn pty_peer(master: BorrowedFd<'_>) -> Result<OwnedFd, Errno> {
    // Drapeaux d'ouverture de l'esclave, passés comme ENTIER (pas un pointeur).
    let open_flags = (OpenFlags::RDWR | OpenFlags::NOCTTY | OpenFlags::CLOEXEC).bits();
    // SAFETY: ioctl(master, TIOCGPTPEER, flags) — `flags` est une valeur entière
    // (drapeaux d'ouverture), pas un pointeur : aucune mémoire utilisateur n'est
    // accédée. La valeur de retour (>= 0) est un descripteur fraîchement ouvert.
    let result = unsafe { raw_syscall_ioctl(master.as_raw_fd(), TIOCGPTPEER, open_flags) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    // Le kernel rend un fd valide, toujours dans l'intervalle `i32` (un descripteur
    // est < 2^31) : la troncature `as i32` est exacte, et le bras `Err` d'un
    // `i32::try_from(result)` serait **inatteignable** (motif du repo, cf.
    // `errno_from_negative_syscall_ret`).
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = result as i32;
    // SAFETY: `raw_fd` est un esclave de PTY fraîchement ouvert par le kernel via
    // TIOCGPTPEER (résultat >= 0, donc != -1) ; sa propriété est transférée à
    // l'appelant, qui le fermera au `Drop` de l'`OwnedFd`.
    Ok(unsafe { OwnedFd::from_raw_fd(raw_fd) })
}

// ─────────────────────────────────────────────────────────────────────────
// Session / job-control — tcgetpgrp / tcsetpgrp / session_id / set_ctty /
// clear_ctty (tranche 5).
// ─────────────────────────────────────────────────────────────────────────

/// `tcgetpgrp` (`TIOCGPGRP`) — groupe de premier plan du terminal `fd`.
///
/// Le kernel écrit un `pid_t` (i32) à une adresse de pile. Un `0` signifie
/// **« aucun groupe de premier plan »** : la sentinelle est convertie en
/// [`None`] (ADR-021 conv. 1). La conversion passe par [`Pid::try_from_raw`],
/// qui replie **tout** `pid_t` non strictement positif sur `None` — donc `0`
/// **comme** un éventuel `pid_t` négatif (aberrant : ce ioctl ne peut pas en
/// produire) donnent tous deux `Ok(None)` : défense en profondeur (Principe 5).
/// Un `pid_t > 0` est enveloppé dans un [`Pid`].
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas le terminal de contrôle de l'appelant.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn tcgetpgrp(fd: BorrowedFd<'_>) -> Result<Option<Pid>, Errno> {
    let mut process_group: i32 = 0;
    // Le kernel écrit `sizeof(pid_t)` octets à cette adresse ; on la passe en
    // `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw mut process_group).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TIOCGPGRP, &mut pgrp) écrit un `pid_t` (i32) à `argument`
    // — une variable de pile vivante, alignée, dimensionnée pour un i32. Aucune
    // autre mémoire n'est touchée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCGPGRP, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(Pid::try_from_raw(process_group))
}

/// `tcsetpgrp` (`TIOCSPGRP`) — installe `process_group` comme groupe de premier
/// plan du terminal `fd`.
///
/// Le kernel **lit** un `pid_t` (i32) à l'adresse passée : on lui présente la
/// valeur brute du [`Pid`] sur la pile. `Pid` étant non nul par typage, aucune
/// sentinelle `0` n'est jamais présentée au kernel (ADR-021 conv. 1).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas le terminal de contrôle de l'appelant.
/// - [`Errno::EPERM`] : `process_group` n'appartient pas à la session de `fd`.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn tcsetpgrp(fd: BorrowedFd<'_>, process_group: Pid) -> Result<(), Errno> {
    let raw_group: i32 = process_group.as_raw();
    // Le kernel lit `sizeof(pid_t)` octets à cette adresse ; on la passe en `u64`
    // (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw const raw_group).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TIOCSPGRP, &pgrp) LIT un `pid_t` (i32) à `argument` — une
    // variable de pile vivante, alignée, dimensionnée pour un i32. Aucune écriture
    // de mémoire utilisateur.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCSPGRP, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `session_id` (`TIOCGSID`) — identifiant de session du terminal `fd`.
///
/// Le kernel écrit le `pid_t` du leader de session à une adresse de pile ; il est
/// **toujours strictement positif** pour une session valide. La conversion via
/// [`Pid::try_from_raw`] est dénotée par `.expect` (même motif que `getsid` de la
/// famille process) : un `pid_t ≤ 0` violerait le contrat kernel — inatteignable
/// par construction.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'a pas de session associée (pas un terminal de
///   contrôle) ou n'est pas un terminal.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn session_id(fd: BorrowedFd<'_>) -> Result<Pid, Errno> {
    let mut session: i32 = 0;
    // Le kernel écrit `sizeof(pid_t)` octets à cette adresse ; on la passe en
    // `u64` (conversion pointeur→entier, non lossy sur LP64).
    let argument = (&raw mut session).cast::<u8>() as u64;
    // SAFETY: ioctl(fd, TIOCGSID, &mut sid) écrit un `pid_t` (i32) à `argument`
    // — une variable de pile vivante, alignée, dimensionnée pour un i32. Aucune
    // autre mémoire n'est touchée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCGSID, argument) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(Pid::try_from_raw(session).expect("kernel : SID de session strictement positif"))
}

/// `set_ctty` (`TIOCSCTTY`, argument **0**) — fait de `fd` le terminal de
/// **contrôle** du leader de session appelant.
///
/// L'appelant doit être **leader de session** ([`crate::process::setsid`]) et ne
/// pas déjà posséder de terminal de contrôle. L'argument **`0`** demande une
/// acquisition **sans vol** : Air n'expose **pas** le vol (`arg = 1`, qui exige
/// `CAP_SYS_ADMIN` — hors périmètre, listé en UNSUPPORTED).
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas un terminal, l'appelant n'est pas leader
///   de session, ou le terminal est déjà le terminal de contrôle d'une **autre**
///   session (vol refusé, `arg = 0`).
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn set_ctty(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: ioctl(fd, TIOCSCTTY, 0) — l'argument est une valeur entière (0 =
    // acquisition sans vol), pas un pointeur : aucune mémoire utilisateur n'est
    // accédée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCSCTTY, TIOCSCTTY_NO_STEAL) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

/// `clear_ctty` (`TIOCNOTTY`) — détache le terminal de **contrôle** du processus
/// appelant.
///
/// # Errors
///
/// - [`Errno::ENOTTY`] : `fd` n'est pas le terminal de contrôle de l'appelant.
/// - [`Errno::EBADF`] : `fd` n'est pas un descripteur valide.
pub fn clear_ctty(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: ioctl(fd, TIOCNOTTY, 0) — l'argument est ignoré (valeur entière),
    // pas un pointeur : aucune mémoire utilisateur n'est accédée.
    let result = unsafe { raw_syscall_ioctl(fd.as_raw_fd(), TIOCNOTTY, 0) };
    if result < 0 {
        return Err(errno_from_negative_syscall_ret(result));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// asm! wrapper ioctl x86_64 / aarch64 (propre au module, modèle de `device.rs`).
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_ioctl(fd: i32, request: u64, arg: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_ioctl (x86_64 = 16). L'effet mémoire dépend de `request` ;
    // chaque appelant a justifié la validité de `arg` pour sa requête : soit un
    // pointeur de pile valide (TCGETS/TIOCGWINSZ/TIOCGPTN/TIOCGPGRP/TIOCGSID
    // écrivent, TCSETS*/TIOCSWINSZ/TIOCSPTLCK/TIOCSPGRP lisent une valeur de
    // pile), soit une valeur entière sans déréférencement (TCSBRK/TCFLSH/TCXONC ;
    // TIOCSCTTY/TIOCNOTTY ; TIOCGPTPEER, dont le retour est le fd de l'esclave).
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 16_i64,
            in("rdi") i64::from(fd),
            in("rsi") request,
            in("rdx") arg,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_ioctl(fd: i32, request: u64, arg: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_ioctl (aarch64 = 29). L'effet mémoire dépend de `request` ;
    // chaque appelant a justifié la validité de `arg` pour sa requête : soit un
    // pointeur de pile valide (TCGETS/TIOCGWINSZ/TIOCGPTN/TIOCGPGRP/TIOCGSID
    // écrivent, TCSETS*/TIOCSWINSZ/TIOCSPTLCK/TIOCSPGRP lisent une valeur de
    // pile), soit une valeur entière sans déréférencement (TCSBRK/TCFLSH/TCXONC ;
    // TIOCSCTTY/TIOCNOTTY ; TIOCGPTPEER, dont le retour est le fd de l'esclave).
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 29_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") request,
            in("x2") arg,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// errno helper (propre au module, modèle de `device.rs`).
// ─────────────────────────────────────────────────────────────────────────

fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret.wrapping_neg() as i32;
    let nz = NonZeroI32::new(raw).expect("errno strictement positif par construction");
    Errno::from_nonzero(nz)
}

#[cfg(test)]
mod tests;