air_sys_types/

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

//! Terminal (termios) — types ABI de la couche 0.
//!
//! [`Termios`] est la structure d'échange **exacte** avec le kernel pour les
//! ioctls `TCGETS`/`TCSETS*` (cf. `<asm-generic/termbits.h>`). Sa disposition
//! mémoire (`#[repr(C)]`) reproduit `struct termios` du kernel — **identique sur
//! x86_64 et aarch64** (tous deux `asm-generic`). Les bits des quatre champs de
//! drapeaux sont exposés en [`bitflags`] typés (lecture via accesseurs), et la
//! vitesse encodée dans `CBAUD` via [`BaudRate`]. L'objet Rust **ergonomique**
//! (manipulation haut niveau, `isatty`, `ttyname`) vit en couche 1 (`air-terminal`).

use bitflags::bitflags;

/// Nombre d'entrées du tableau de caractères de contrôle `c_cc` (Linux `NCCS`).
pub const NCCS: usize = 19;

/// Indices des caractères de contrôle dans [`Termios::control_chars`] (`c_cc`).
///
/// Valeurs `<asm-generic/termbits.h>` (identiques x86_64/aarch64).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u8)]
pub enum ControlChar {
    /// `VINTR` — caractère d'interruption (SIGINT).
    Intr = 0,
    /// `VQUIT` — caractère de quit (SIGQUIT).
    Quit = 1,
    /// `VERASE` — effacement de caractère.
    Erase = 2,
    /// `VKILL` — effacement de ligne.
    Kill = 3,
    /// `VEOF` — fin de fichier (Ctrl-D).
    Eof = 4,
    /// `VTIME` — délai de lecture (dixièmes de seconde), mode non canonique.
    Time = 5,
    /// `VMIN` — nombre minimal d'octets, mode non canonique.
    Min = 6,
    /// `VSWTC` — caractère de bascule.
    Swtc = 7,
    /// `VSTART` — reprise du flux (XON).
    Start = 8,
    /// `VSTOP` — suspension du flux (XOFF).
    Stop = 9,
    /// `VSUSP` — suspension (SIGTSTP).
    Susp = 10,
    /// `VEOL` — fin de ligne additionnelle.
    Eol = 11,
    /// `VREPRINT` — réaffichage de la ligne.
    Reprint = 12,
    /// `VDISCARD` — abandon de la sortie.
    Discard = 13,
    /// `VWERASE` — effacement de mot.
    Werase = 14,
    /// `VLNEXT` — caractère littéral suivant.
    Lnext = 15,
    /// `VEOL2` — seconde fin de ligne.
    Eol2 = 16,
}

bitflags! {
    /// Drapeaux d'entrée (`c_iflag`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct InputFlags: u32 {
        /// `IGNBRK` — ignore les conditions BREAK.
        const IGNBRK = 0x0000_0001;
        /// `BRKINT` — un BREAK provoque une interruption.
        const BRKINT = 0x0000_0002;
        /// `IGNPAR` — ignore les octets en erreur de parité.
        const IGNPAR = 0x0000_0004;
        /// `PARMRK` — marque les erreurs de parité.
        const PARMRK = 0x0000_0008;
        /// `INPCK` — active le contrôle de parité en entrée.
        const INPCK = 0x0000_0010;
        /// `ISTRIP` — masque le 8e bit.
        const ISTRIP = 0x0000_0020;
        /// `INLCR` — convertit NL en CR en entrée.
        const INLCR = 0x0000_0040;
        /// `IGNCR` — ignore les CR en entrée.
        const IGNCR = 0x0000_0080;
        /// `ICRNL` — convertit CR en NL en entrée.
        const ICRNL = 0x0000_0100;
        /// `IUCLC` — convertit les majuscules en minuscules.
        const IUCLC = 0x0000_0200;
        /// `IXON` — active le contrôle de flux XON/XOFF en sortie.
        const IXON = 0x0000_0400;
        /// `IXANY` — tout caractère relance la sortie suspendue.
        const IXANY = 0x0000_0800;
        /// `IXOFF` — active le contrôle de flux XON/XOFF en entrée.
        const IXOFF = 0x0000_1000;
        /// `IMAXBEL` — sonne quand la file d'entrée est pleine.
        const IMAXBEL = 0x0000_2000;
        /// `IUTF8` — l'entrée est en UTF-8 (effacement canonique correct).
        const IUTF8 = 0x0000_4000;
    }

    /// Drapeaux de sortie (`c_oflag`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct OutputFlags: u32 {
        /// `OPOST` — active le post-traitement de sortie.
        const OPOST = 0x0000_0001;
        /// `OLCUC` — convertit les minuscules en majuscules.
        const OLCUC = 0x0000_0002;
        /// `ONLCR` — convertit NL en CR-NL en sortie.
        const ONLCR = 0x0000_0004;
        /// `OCRNL` — convertit CR en NL en sortie.
        const OCRNL = 0x0000_0008;
        /// `ONOCR` — pas de CR en colonne 0.
        const ONOCR = 0x0000_0010;
        /// `ONLRET` — NL effectue aussi le retour chariot.
        const ONLRET = 0x0000_0020;
        /// `OFILL` — caractères de remplissage pour la temporisation.
        const OFILL = 0x0000_0040;
        /// `OFDEL` — le caractère de remplissage est DEL.
        const OFDEL = 0x0000_0080;
    }

    /// Drapeaux de contrôle (`c_cflag`). La vitesse (`CBAUD`/`CBAUDEX`) se lit
    /// via [`Termios::input_speed`]/[`Termios::output_speed`], pas ici.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct ControlFlags: u32 {
        /// `CSTOPB` — deux bits de stop (sinon un).
        const CSTOPB = 0x0000_0040;
        /// `CREAD` — active la réception.
        const CREAD = 0x0000_0080;
        /// `PARENB` — active la génération/contrôle de parité.
        const PARENB = 0x0000_0100;
        /// `PARODD` — parité impaire (sinon paire).
        const PARODD = 0x0000_0200;
        /// `HUPCL` — raccroche à la fermeture du dernier descripteur.
        const HUPCL = 0x0000_0400;
        /// `CLOCAL` — ignore les lignes de contrôle modem.
        const CLOCAL = 0x0000_0800;
        /// `CRTSCTS` — contrôle de flux matériel (RTS/CTS).
        const CRTSCTS = 0x8000_0000;
    }

    /// Drapeaux locaux (`c_lflag`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct LocalFlags: u32 {
        /// `ISIG` — génère des signaux pour INTR/QUIT/SUSP.
        const ISIG = 0x0000_0001;
        /// `ICANON` — mode canonique (ligne par ligne).
        const ICANON = 0x0000_0002;
        /// `ECHO` — écho des caractères saisis.
        const ECHO = 0x0000_0008;
        /// `ECHOE` — ERASE efface visuellement.
        const ECHOE = 0x0000_0010;
        /// `ECHOK` — KILL efface la ligne visuellement.
        const ECHOK = 0x0000_0020;
        /// `ECHONL` — écho de NL même sans ECHO.
        const ECHONL = 0x0000_0040;
        /// `NOFLSH` — ne vide pas les files sur signal.
        const NOFLSH = 0x0000_0080;
        /// `TOSTOP` — SIGTTOU pour l'écriture par un processus en arrière-plan.
        const TOSTOP = 0x0000_0100;
        /// `ECHOCTL` — affiche les caractères de contrôle en `^X`.
        const ECHOCTL = 0x0000_0200;
        /// `ECHOPRT` — affiche les caractères effacés (imprimante).
        const ECHOPRT = 0x0000_0400;
        /// `ECHOKE` — KILL efface chaque caractère visuellement.
        const ECHOKE = 0x0000_0800;
        /// `FLUSHO` — sortie vidée (toggle par DISCARD).
        const FLUSHO = 0x0000_1000;
        /// `PENDIN` — entrée en attente de réaffichage.
        const PENDIN = 0x0000_4000;
        /// `IEXTEN` — active le traitement étendu (LNEXT, WERASE…).
        const IEXTEN = 0x0000_8000;
    }
}

/// Masque de la taille de caractère dans `c_cflag` (`CSIZE`).
const CSIZE_MASK: u32 = 0x0000_0030;
/// Masque de la vitesse encodée dans `c_cflag` (`CBAUD | CBAUDEX`).
const CBAUD_MASK: u32 = 0x0000_100f;

/// Nombre de bits de données par caractère (`CSIZE` : CS5/CS6/CS7/CS8).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum CharSize {
    /// `CS5` — 5 bits.
    Bits5 = 0x0000_0000,
    /// `CS6` — 6 bits.
    Bits6 = 0x0000_0010,
    /// `CS7` — 7 bits.
    Bits7 = 0x0000_0020,
    /// `CS8` — 8 bits.
    Bits8 = 0x0000_0030,
}

impl CharSize {
    /// Décode les bits `CSIZE` de `c_cflag`. Total (4 motifs) → jamais `None`.
    #[must_use]
    const fn from_cflag(cflag: u32) -> Self {
        match cflag & CSIZE_MASK {
            0x0000_0000 => Self::Bits5,
            0x0000_0010 => Self::Bits6,
            0x0000_0020 => Self::Bits7,
            // Le masque 2 bits n'a que 4 valeurs ; 0x30 est la dernière.
            _ => Self::Bits8,
        }
    }
}

/// Vitesse de transmission (valeur encodée `CBAUD`/`CBAUDEX` de `c_cflag`).
///
/// Couvre les vitesses POSIX standard. La conversion bidirectionnelle préserve
/// l'octet de vitesse ; une valeur kernel inconnue est rendue telle quelle via
/// [`BaudRate::from_code`]/[`BaudRate::code`] (pas de perte d'information —
/// doctrine « kernel = bible »).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BaudRate(u32);

impl BaudRate {
    /// `B0` — débit nul (raccroche).
    pub const B0: Self = Self(0x0000_0000);
    /// `B50`.
    pub const B50: Self = Self(0x0000_0001);
    /// `B75`.
    pub const B75: Self = Self(0x0000_0002);
    /// `B110`.
    pub const B110: Self = Self(0x0000_0003);
    /// `B134`.
    pub const B134: Self = Self(0x0000_0004);
    /// `B150`.
    pub const B150: Self = Self(0x0000_0005);
    /// `B200`.
    pub const B200: Self = Self(0x0000_0006);
    /// `B300`.
    pub const B300: Self = Self(0x0000_0007);
    /// `B600`.
    pub const B600: Self = Self(0x0000_0008);
    /// `B1200`.
    pub const B1200: Self = Self(0x0000_0009);
    /// `B1800`.
    pub const B1800: Self = Self(0x0000_000a);
    /// `B2400`.
    pub const B2400: Self = Self(0x0000_000b);
    /// `B4800`.
    pub const B4800: Self = Self(0x0000_000c);
    /// `B9600`.
    pub const B9600: Self = Self(0x0000_000d);
    /// `B19200`.
    pub const B19200: Self = Self(0x0000_000e);
    /// `B38400`.
    pub const B38400: Self = Self(0x0000_000f);
    /// `B57600`.
    pub const B57600: Self = Self(0x0000_1001);
    /// `B115200`.
    pub const B115200: Self = Self(0x0000_1002);
    /// `B230400`.
    pub const B230400: Self = Self(0x0000_1003);
    /// `B460800`.
    pub const B460800: Self = Self(0x0000_1004);
    /// `B921600`.
    pub const B921600: Self = Self(0x0000_1007);

    /// Construit depuis le code de vitesse brut (octet `CBAUD|CBAUDEX`).
    #[must_use]
    pub const fn from_code(code: u32) -> Self {
        Self(code & CBAUD_MASK)
    }

    /// Code de vitesse brut (octet `CBAUD|CBAUDEX`), pour réinjection dans `c_cflag`.
    #[must_use]
    pub const fn code(self) -> u32 {
        self.0
    }
}

/// Action de pose des attributs (`tcsetattr` : quand appliquer).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SetAction {
    /// `TCSANOW` — applique immédiatement (`TCSETS`).
    Now,
    /// `TCSADRAIN` — applique après vidage de la sortie (`TCSETSW`).
    Drain,
    /// `TCSAFLUSH` — applique après vidage sortie + purge entrée (`TCSETSF`).
    Flush,
}

/// File visée par `tcflush` (purge).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlushQueue {
    /// `TCIFLUSH` — purge les données reçues non lues.
    Input,
    /// `TCOFLUSH` — purge les données écrites non transmises.
    Output,
    /// `TCIOFLUSH` — purge les deux files.
    Both,
}

/// Action de contrôle de flux pour `tcflow`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlowAction {
    /// `TCOOFF` — suspend la sortie.
    SuspendOutput,
    /// `TCOON` — reprend la sortie.
    ResumeOutput,
    /// `TCIOFF` — émet un STOP (suspend l'entrée du terminal distant).
    SuspendInput,
    /// `TCION` — émet un START (reprend l'entrée du terminal distant).
    ResumeInput,
}

/// Attributs d'un terminal — image ABI de `struct termios` (`<asm-generic>`).
///
/// `#[repr(C)]`, disposition identique x86_64/aarch64. Champs bruts (compatibles
/// kernel) lus/écrits via accesseurs typés. À échanger avec le kernel par les
/// ioctls de `air-sys-syscall::terminal`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub struct Termios {
    /// `c_iflag` — drapeaux d'entrée (brut).
    pub c_iflag: u32,
    /// `c_oflag` — drapeaux de sortie (brut).
    pub c_oflag: u32,
    /// `c_cflag` — drapeaux de contrôle (brut, inclut la vitesse `CBAUD`).
    pub c_cflag: u32,
    /// `c_lflag` — drapeaux locaux (brut).
    pub c_lflag: u32,
    /// `c_line` — discipline de ligne.
    pub c_line: u8,
    /// `c_cc` — caractères de contrôle (indexés par [`ControlChar`]).
    pub c_cc: [u8; NCCS],
}

impl Termios {
    /// Image toute-à-zéro (pour recevoir un `TCGETS`).
    #[must_use]
    pub const fn zeroed() -> Self {
        Self {
            c_iflag: 0,
            c_oflag: 0,
            c_cflag: 0,
            c_lflag: 0,
            c_line: 0,
            c_cc: [0; NCCS],
        }
    }

    /// Drapeaux d'entrée typés. Les bits inconnus sont conservés (`from_bits_retain`).
    #[must_use]
    pub const fn input_flags(&self) -> InputFlags {
        InputFlags::from_bits_retain(self.c_iflag)
    }

    /// Drapeaux de sortie typés.
    #[must_use]
    pub const fn output_flags(&self) -> OutputFlags {
        OutputFlags::from_bits_retain(self.c_oflag)
    }

    /// Drapeaux de contrôle typés (hors bits de taille/vitesse).
    #[must_use]
    pub const fn control_flags(&self) -> ControlFlags {
        ControlFlags::from_bits_retain(self.c_cflag)
    }

    /// Drapeaux locaux typés.
    #[must_use]
    pub const fn local_flags(&self) -> LocalFlags {
        LocalFlags::from_bits_retain(self.c_lflag)
    }

    /// Positionne les drapeaux d'entrée (remplace `c_iflag`).
    pub const fn set_input_flags(&mut self, flags: InputFlags) {
        self.c_iflag = flags.bits();
    }

    /// Positionne les drapeaux de sortie.
    pub const fn set_output_flags(&mut self, flags: OutputFlags) {
        self.c_oflag = flags.bits();
    }

    /// Positionne les drapeaux de contrôle **en préservant** taille et vitesse
    /// (les bits `CSIZE`/`CBAUD` de `c_cflag` ne sont pas touchés).
    pub const fn set_control_flags(&mut self, flags: ControlFlags) {
        let preserved = self.c_cflag & (CSIZE_MASK | CBAUD_MASK);
        // `ControlFlags` n'inclut ni CSIZE ni CBAUD → pas de chevauchement.
        self.c_cflag = flags.bits() | preserved;
    }

    /// Positionne les drapeaux locaux.
    pub const fn set_local_flags(&mut self, flags: LocalFlags) {
        self.c_lflag = flags.bits();
    }

    /// Taille de caractère (`CSIZE`).
    #[must_use]
    pub const fn char_size(&self) -> CharSize {
        CharSize::from_cflag(self.c_cflag)
    }

    /// Positionne la taille de caractère (`CSIZE`).
    pub const fn set_char_size(&mut self, size: CharSize) {
        self.c_cflag = (self.c_cflag & !CSIZE_MASK) | (size as u32);
    }

    /// Vitesse encodée dans `c_cflag` (entrée et sortie partagent `CBAUD` sur
    /// Linux classique).
    #[must_use]
    pub const fn output_speed(&self) -> BaudRate {
        BaudRate::from_code(self.c_cflag)
    }

    /// Vitesse d'entrée (identique à la sortie en termios classique Linux).
    #[must_use]
    pub const fn input_speed(&self) -> BaudRate {
        BaudRate::from_code(self.c_cflag)
    }

    /// Positionne la vitesse (les bits `CBAUD|CBAUDEX` de `c_cflag`).
    pub const fn set_speed(&mut self, baud: BaudRate) {
        self.c_cflag = (self.c_cflag & !CBAUD_MASK) | baud.code();
    }

    /// Lit un caractère de contrôle (`c_cc[idx]`).
    #[must_use]
    pub const fn control_char(&self, which: ControlChar) -> u8 {
        self.c_cc[which as usize]
    }

    /// Positionne un caractère de contrôle (`c_cc[idx]`).
    pub const fn set_control_char(&mut self, which: ControlChar, value: u8) {
        self.c_cc[which as usize] = value;
    }
}

/// Taille d'une fenêtre de terminal — image ABI de `struct winsize`
/// (`<asm-generic/termios.h>`).
///
/// `#[repr(C)]`, disposition **identique x86_64/aarch64** (`asm-generic`). À
/// échanger avec le kernel par les ioctls `TIOCGWINSZ`/`TIOCSWINSZ` de
/// `air-sys-syscall::terminal`. Le kernel signale les changements de taille par
/// `SIGWINCH`. Les champs sont exposés bruts (`pub`) — comme [`Termios`] — pour
/// l'échange direct avec le kernel ; des accesseurs const nommés existent pour la
/// lecture ergonomique.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub struct Winsize {
    /// `ws_row` — nombre de lignes (rangées de caractères).
    pub ws_row: u16,
    /// `ws_col` — nombre de colonnes (caractères par ligne).
    pub ws_col: u16,
    /// `ws_xpixel` — largeur en pixels (souvent 0 : nombre de terminaux ne le
    /// renseignent pas).
    pub ws_xpixel: u16,
    /// `ws_ypixel` — hauteur en pixels (souvent 0, comme `ws_xpixel`).
    pub ws_ypixel: u16,
}

impl Winsize {
    /// Image toute-à-zéro (à passer à un `TIOCGWINSZ` qui la remplira).
    #[must_use]
    pub const fn zeroed() -> Self {
        Self {
            ws_row: 0,
            ws_col: 0,
            ws_xpixel: 0,
            ws_ypixel: 0,
        }
    }

    /// Nombre de lignes (`ws_row`).
    #[must_use]
    pub const fn rows(&self) -> u16 {
        self.ws_row
    }

    /// Nombre de colonnes (`ws_col`).
    #[must_use]
    pub const fn cols(&self) -> u16 {
        self.ws_col
    }

    /// Largeur en pixels (`ws_xpixel`), 0 si non renseigné.
    #[must_use]
    pub const fn x_pixels(&self) -> u16 {
        self.ws_xpixel
    }

    /// Hauteur en pixels (`ws_ypixel`), 0 si non renseigné.
    #[must_use]
    pub const fn y_pixels(&self) -> u16 {
        self.ws_ypixel
    }
}

/// Numéro de l'esclave d'un pseudo-terminal (`/dev/pts/N`).
///
/// Newtype d'identifiant (ADR-021 : newtypes typés systématiques, comme
/// [`Pid`](crate::Pid)/[`Tid`](crate::Tid)/[`PidFd`](crate::PidFd)) : jamais un
/// `u32` brut pour désigner un esclave de PTY. La valeur est celle rendue par
/// l'ioctl `TIOCGPTN` sur le maître `/dev/ptmx` — elle nomme le nœud
/// `/dev/pts/N` correspondant à l'esclave.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PtyNumber(u32);

impl PtyNumber {
    /// Construit un [`PtyNumber`] à partir du numéro brut rendu par `TIOCGPTN`.
    #[must_use]
    pub const fn new(value: u32) -> Self {
        Self(value)
    }

    /// Numéro brut de l'esclave (l'`N` de `/dev/pts/N`).
    #[must_use]
    pub const fn value(self) -> u32 {
        self.0
    }
}

#[cfg(test)]
mod tests;