air_sys_types/

fs.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 de la famille `fs` — filesystem, ouverture, métadonnées, etc.
//!
//! Cf. `docs/specs/layer-0/family-fs.md`.

use alloc::vec::Vec;

use bitflags::bitflags;

use crate::fd::BorrowedFd;

// ─────────────────────────────────────────────────────────────────────────
// Type de base : alias Mode
// ─────────────────────────────────────────────────────────────────────────

/// Permissions POSIX d'un fichier (bits `mode_t`).
///
/// Valeurs typiques : `0o644` (rw-r--r--), `0o755` (rwxr-xr-x),
/// `0o600` (rw-------). Seuls les 12 bits inférieurs sont significatifs
/// (9 bits de permission + 3 bits setuid/setgid/sticky).
pub type Mode = u32;

// ─────────────────────────────────────────────────────────────────────────
// DirFd — base pour les opérations *at
// ─────────────────────────────────────────────────────────────────────────

/// Base d'un appel `*at` (cf. ADR-021 convention 1).
///
/// Remplace la sentinelle kernel `AT_FDCWD` (`-100`) par une variante
/// `Cwd` typée. Air exige une base explicite sur toutes les opérations
/// filesystem — pas de dépendance implicite au `cwd` global du processus.
///
/// # Examples
///
/// ```no_run
/// use air_sys_types::fs::DirFd;
/// // Ouvrir un fichier par rapport au répertoire courant
/// let _dirfd = DirFd::Cwd;
/// ```
#[derive(Debug, Clone, Copy)]
pub enum DirFd<'fd> {
    /// Répertoire courant du processus (équivalent à `AT_FDCWD`).
    Cwd,
    /// FD d'un répertoire ouvert (accès relatif à ce répertoire).
    Fd(BorrowedFd<'fd>),
}

// ─────────────────────────────────────────────────────────────────────────
// openat2 / openat
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Flags d'ouverture de fichier pour `openat2(2)` / `openat(2)`.
    ///
    /// Correspond aux constantes `O_*` de `<fcntl.h>`.
    /// `CLOEXEC` est ajouté **automatiquement** par le wrapper — l'appelant
    /// ne doit pas l'insérer manuellement.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct OpenFlags: u64 {
        /// Lecture seule.
        const RDONLY    = 0;
        /// Écriture seule.
        const WRONLY    = 1;
        /// Lecture et écriture.
        const RDWR      = 2;
        /// Crée le fichier s'il n'existe pas.
        const CREAT     = 0o0000_0100;
        /// Échec si le fichier existe déjà (avec `CREAT`).
        const EXCL      = 0o0000_0200;
        /// Ne prend pas le terminal comme terminal de contrôle.
        const NOCTTY    = 0o0000_0400;
        /// Tronque le fichier existant à zéro.
        const TRUNC     = 0o0000_1000;
        /// Écriture en mode ajout.
        const APPEND    = 0o0000_2000;
        /// Non-bloquant.
        const NONBLOCK  = 0o0000_4000;
        /// Sync à chaque écriture sur les données et les métadonnées.
        const DSYNC     = 0o0001_0000;
        /// Mode asynchrone POSIX (SIGIO).
        const ASYNC     = 0o0002_0000;
        /// Accès direct (pas de cache kernel).
        ///
        /// **Valeur dépendante de l'architecture** (ABI `asm-generic` sur
        /// aarch64 vs `x86`) : `0o40000` sur x86_64, `0o200000` sur aarch64.
        const DIRECT    = if cfg!(target_arch = "x86_64") { 0o0004_0000 } else { 0o0020_0000 };
        /// Fichier potentiellement large (obsolète en 64 bits).
        ///
        /// **Valeur dépendante de l'architecture** : `0o100000` sur x86_64,
        /// `0o400000` sur aarch64.
        const LARGEFILE = if cfg!(target_arch = "x86_64") { 0o0010_0000 } else { 0o0040_0000 };
        /// Doit être un répertoire.
        ///
        /// **Valeur dépendante de l'architecture** : `0o200000` sur x86_64,
        /// `0o40000` sur aarch64. (Une valeur figée x86 cassait `openat` avec
        /// `EINVAL` sur aarch64 — elle y désignait en réalité `O_DIRECT`.)
        const DIRECTORY = if cfg!(target_arch = "x86_64") { 0o0020_0000 } else { 0o0004_0000 };
        /// Ne suit pas les liens symboliques.
        ///
        /// **Valeur dépendante de l'architecture** : `0o400000` sur x86_64,
        /// `0o100000` sur aarch64.
        const NOFOLLOW  = if cfg!(target_arch = "x86_64") { 0o0040_0000 } else { 0o0010_0000 };
        /// Pas de mise à jour de `atime`.
        const NOATIME   = 0o0100_0000;
        /// Ferme le FD à l'`exec` (ajouté automatiquement par le wrapper).
        const CLOEXEC   = 0o0200_0000;
        /// Ouvre sans accéder à l'objet (FD de chemin pur).
        const PATH      = 0o1000_0000;
        /// Crée un fichier temporaire sans nom dans le répertoire.
        ///
        /// `__O_TMPFILE | O_DIRECTORY` : hérite donc de la divergence d'arch
        /// d'`O_DIRECTORY` — `0o20200000` sur x86_64, `0o20040000` sur aarch64.
        const TMPFILE   = if cfg!(target_arch = "x86_64") { 0o2020_0000 } else { 0o2004_0000 };
    }
}

bitflags! {
    /// Flags de `close_range(2)` (Linux 5.9+) — fermeture en masse d'un intervalle
    /// de descripteurs. Utilisé par le confinement (ADR-122) : un enfant forké ferme
    /// tous les fd hérités hormis un keep-set avant de poser sa cage.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct CloseRangeFlags: u32 {
        /// `CLOSE_RANGE_UNSHARE` — détache la table de fd partagée avant la
        /// fermeture (n'affecte que ce processus, pas les partageurs de table).
        const UNSHARE = 0x0000_0002;
        /// `CLOSE_RANGE_CLOEXEC` — positionne `O_CLOEXEC` sur l'intervalle **au lieu**
        /// de le fermer (fermeture différée à l'`execve`).
        const CLOEXEC = 0x0000_0004;
    }
}

bitflags! {
    /// Flags de résolution de chemin pour `openat2(2)` (Linux 5.6+).
    ///
    /// Ces flags permettent une sandbox de résolution de chemin stricte.
    /// `BENEATH` et `IN_ROOT` sont particulièrement utiles pour les
    /// contextes sandboxés (launcher Air, couche 5).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct ResolveFlags: u64 {
        /// Refuse de traverser les frontières de système de fichiers.
        const NO_XDEV        = 0x01;
        /// Refuse les liens magiques (ex. `/proc/self/fd/X`).
        const NO_MAGICLINKS  = 0x02;
        /// Refuse tous les liens symboliques.
        const NO_SYMLINKS    = 0x04;
        /// La résolution ne peut pas remonter au-delà de `dirfd`
        /// (protection contre `../../`).
        const BENEATH        = 0x08;
        /// Traite `dirfd` comme la racine de la résolution.
        const IN_ROOT        = 0x10;
        /// Utilise uniquement le cache VFS (pas d'E/S si absent).
        const CACHED         = 0x20;
    }
}

/// Structure d'ouverture pour `openat2(2)`.
///
/// Combine flags, mode et flags de résolution en un seul argument.
/// `how.flags` inclut automatiquement `CLOEXEC` via le wrapper.
#[derive(Debug, Clone, Copy, Default)]
pub struct OpenHow {
    /// Flags d'accès et de comportement.
    pub flags: OpenFlags,
    /// Permissions de création (ignoré si `CREAT` absent).
    pub mode: Mode,
    /// Politique de résolution de chemin (Linux 5.6+).
    pub resolve: ResolveFlags,
}

// ─────────────────────────────────────────────────────────────────────────
// statx
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Flags pour `statx(2)` (comportement de résolution de chemin).
    ///
    /// Cf. `linux/stat.h` : constantes `AT_*`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct StatxFlags: u32 {
        /// Opère sur le FD lui-même sans résolution de chemin
        /// (équivalent à `AT_EMPTY_PATH`).
        const EMPTY_PATH        = 0x1000;
        /// Ne déclenche pas de montage automount.
        const NO_AUTOMOUNT      = 0x0800;
        /// Ne suit pas les liens symboliques.
        const SYMLINK_NOFOLLOW  = 0x0100;
    }
}

bitflags! {
    /// Masque des champs demandés / disponibles dans [`StatxResult`].
    ///
    /// Passé en entrée pour sélectionner les champs souhaités ;
    /// retourné dans `StatxResult::mask` pour indiquer quels champs ont
    /// été effectivement remplis par le kernel.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct StatxMask: u32 {
        /// Type de fichier (regular, dir, symlink…).
        const TYPE   = 0x0001;
        /// Bits de permissions (`mode & 0o7777`).
        const MODE   = 0x0002;
        /// Nombre de liens physiques.
        const NLINK  = 0x0004;
        /// UID du propriétaire.
        const UID    = 0x0008;
        /// GID du propriétaire.
        const GID    = 0x0010;
        /// Horodatage d'accès (`atime`).
        const ATIME  = 0x0020;
        /// Horodatage de modification de données (`mtime`).
        const MTIME  = 0x0040;
        /// Horodatage de modification de métadonnées (`ctime`).
        const CTIME  = 0x0080;
        /// Numéro d'inode.
        const INO    = 0x0100;
        /// Taille en octets.
        const SIZE   = 0x0200;
        /// Nombre de blocs de 512 octets alloués.
        const BLOCKS = 0x0400;
        /// Horodatage de création (`btime`, si supporté par le FS).
        const BTIME  = 0x0800;
        /// Identifiant de point de montage (Linux 5.8+).
        const MNT_ID = 0x1000;
        /// Tous les champs courants.
        const ALL    = 0x0fff;
    }
}

/// Horodatage retourné par `statx(2)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StatxTimestamp {
    /// Secondes depuis l'epoch Unix.
    pub seconds: i64,
    /// Nanosecondes (complément, toujours dans `[0, 999_999_999]`).
    pub nanoseconds: u32,
}

/// Résultat de `statx(2)`.
///
/// Les champs non demandés (absent de `mask` en entrée) ou non disponibles
/// (absent de `mask` en sortie) ont des valeurs indéfinies. Vérifiez
/// toujours `mask.contains(StatxMask::XYZ)` avant de lire un champ.
#[derive(Debug, Clone)]
pub struct StatxResult {
    /// Champs effectivement remplis par le kernel.
    pub mask: StatxMask,
    /// Granularité des E/S préférée (en octets).
    pub blksize: u32,
    /// Attributs supplémentaires (compressed, immutable, append-only…).
    pub attributes: u64,
    /// Nombre de liens physiques.
    pub nlink: u32,
    /// UID du propriétaire.
    pub uid: u32,
    /// GID du propriétaire.
    pub gid: u32,
    /// Type et permissions (`type << 12 | perm`).
    pub mode: u16,
    /// Numéro d'inode.
    pub ino: u64,
    /// Taille en octets.
    pub size: u64,
    /// Nombre de blocs de 512 octets alloués.
    pub blocks: u64,
    /// Horodatage d'accès.
    pub atime: StatxTimestamp,
    /// Horodatage de création.
    pub btime: StatxTimestamp,
    /// Horodatage de modification de métadonnées.
    pub ctime: StatxTimestamp,
    /// Horodatage de modification de données.
    pub mtime: StatxTimestamp,
    /// Numéro majeur du device (si fichier device).
    pub rdev_major: u32,
    /// Numéro mineur du device (si fichier device).
    pub rdev_minor: u32,
    /// Numéro majeur du device contenant le fichier.
    pub dev_major: u32,
    /// Numéro mineur du device contenant le fichier.
    pub dev_minor: u32,
    /// Identifiant du point de montage (Linux 5.8+, 0 si non disponible).
    pub mount_id: u64,
}

// ─────────────────────────────────────────────────────────────────────────
// faccessat
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Mode d'accès pour `faccessat(2)`.
    ///
    /// Cf. `linux/unistd.h` : constantes `F_OK`, `R_OK`, `W_OK`, `X_OK`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct AccessMode: u32 {
        /// Vérifie l'existence du fichier.
        const F_OK = 0;
        /// Vérifie les droits de lecture.
        const R_OK = 4;
        /// Vérifie les droits d'écriture.
        const W_OK = 2;
        /// Vérifie les droits d'exécution.
        const X_OK = 1;
    }
}

bitflags! {
    /// Flags comportementaux pour `faccessat(2)`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct AccessFlags: i32 {
        /// Utilise l'UID/GID effectif (plutôt que réel).
        const EACCESS         = 0x200;
        /// Ne suit pas les liens symboliques.
        const SYMLINK_NOFOLLOW = 0x100;
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Répertoires
// ─────────────────────────────────────────────────────────────────────────

/// Type d'entrée de répertoire retourné par `getdents64(2)`.
///
/// Correspond au champ `d_type` de la struct `linux_dirent64`.
/// La valeur `Unknown` (0) est produite sur les filesystems qui ne
/// stockent pas le type (ex. certains systèmes de fichiers en réseau).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum DirEntryType {
    /// Type inconnu (filesystem ne stocke pas le type).
    Unknown = 0,
    /// FIFO (pipe nommé).
    Fifo = 1,
    /// Fichier caractère.
    Character = 2,
    /// Répertoire.
    Directory = 4,
    /// Fichier bloc.
    Block = 6,
    /// Fichier régulier.
    Regular = 8,
    /// Lien symbolique.
    Symlink = 10,
    /// Socket Unix.
    Socket = 12,
}

/// Entrée de répertoire parsée depuis le buffer de `getdents64(2)`.
///
/// La durée de vie `'buffer` est liée au buffer de lecture — les données
/// ne sont pas copiées.
#[derive(Debug, Clone)]
pub struct DirEntry {
    /// Numéro d'inode.
    pub inode: u64,
    /// Offset de la prochaine entrée dans le flux de répertoire.
    pub offset: i64,
    /// Type de l'entrée.
    pub file_type: DirEntryType,
    /// Nom de l'entrée (sans le chemin parent), **octets bruts** propriétaires.
    ///
    /// Sur Unix un nom de fichier est une suite d'octets opaque (qui peut ne
    /// pas être de l'UTF-8 valide), terminée par `NUL` dans le buffer kernel
    /// mais stockée ici **sans** le `NUL`. Le type est volontairement
    /// [`alloc::vec::Vec<u8>`] (octets) et non `OsString`/`String` : la couche 0
    /// ne présume aucun encodage (Principe 3, doctrine « chemins = octets »).
    pub name: alloc::vec::Vec<u8>,
}

bitflags! {
    /// Flags pour `renameat2(2)` (cf. `linux/fs.h`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct RenameFlags: u32 {
        /// Ne remplace pas la destination si elle existe.
        const NOREPLACE = 1;
        /// Échange atomiquement source et destination.
        const EXCHANGE  = 2;
        /// Pose un whiteout sur la source (union mounts).
        const WHITEOUT  = 4;
    }
}

// ─────────────────────────────────────────────────────────────────────────
// lseek
// ─────────────────────────────────────────────────────────────────────────

/// Origine pour `lseek(2)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum SeekWhence {
    /// Depuis le début du fichier.
    Set = 0,
    /// Depuis la position courante.
    Current = 1,
    /// Depuis la fin du fichier.
    End = 2,
    /// Depuis la prochaine zone de données après l'offset (Linux).
    Data = 3,
    /// Depuis le prochain trou après l'offset (Linux).
    Hole = 4,
}

// ─────────────────────────────────────────────────────────────────────────
// utimensat
// ─────────────────────────────────────────────────────────────────────────

/// Valeur d'horodatage pour `utimensat(2)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UtimeValue {
    /// Met l'horodatage à l'heure courante (`UTIME_NOW`).
    Now,
    /// Ne modifie pas cet horodatage (`UTIME_OMIT`).
    Omit,
    /// Met l'horodatage à la valeur fournie.
    Time(StatxTimestamp),
}

// ─────────────────────────────────────────────────────────────────────────
// fallocate
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Mode pour `fallocate(2)` (cf. `linux/falloc.h`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct FallocateMode: i32 {
        /// Garde la taille du fichier inchangée (alloue de l'espace sans étendre).
        const KEEP_SIZE      = 0x01;
        /// Perfore un trou dans le fichier (libère les blocs, laisse un trou).
        const PUNCH_HOLE     = 0x02;
        /// Collapse une plage du fichier en supprimant les blocs.
        const COLLAPSE_RANGE = 0x08;
        /// Remplace une plage par des zéros sans désallouer les blocs.
        const ZERO_RANGE     = 0x10;
        /// Insère de l'espace dans le fichier (décale le contenu).
        const INSERT_RANGE   = 0x20;
        /// Dé-partage les blocs copy-on-write.
        const UNSHARE_RANGE  = 0x40;
    }
}

// ─────────────────────────────────────────────────────────────────────────
// fcntl individuel
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Flags de descripteur de fichier (`F_GETFD`/`F_SETFD`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct FdFlags: i32 {
        /// Ferme le FD à l'`exec`.
        const CLOEXEC = 1;
    }
}

bitflags! {
    /// Flags de statut de fichier (`F_GETFL`/`F_SETFL`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct StatusFlags: i32 {
        /// Mode non-bloquant.
        const NONBLOCK = 0x0000_0800;
        /// Mode append.
        const APPEND   = 0x0000_0400;
        /// Sync asynchrone.
        const ASYNC    = 0x0002_0000;
        /// Sync synchrone sur les données.
        const DSYNC    = 0x0000_1000;
        /// Accès direct (no cache).
        ///
        /// **Valeur dépendante de l'architecture** (`O_DIRECT`) : `0x4000` sur
        /// x86_64, `0x10000` sur aarch64.
        const DIRECT   = if cfg!(target_arch = "x86_64") { 0x0000_4000 } else { 0x0001_0000 };
    }
}

/// Type de verrou pour `flock` noyau (opérations `F_SETLK`/`F_GETLK`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i16)]
pub enum LockType {
    /// Verrou de lecture (partagé).
    Read = 0,
    /// Verrou d'écriture (exclusif).
    Write = 1,
    /// Libère le verrou.
    Unlock = 2,
}

/// Verrou de fichier POSIX (pour `fcntl F_SETLK`/`F_SETLKW`/`F_GETLK`).
///
/// Correspond à `struct flock` de `<fcntl.h>`.
#[derive(Debug, Clone, Copy)]
pub struct FileLock {
    /// Type du verrou.
    pub lock_type: LockType,
    /// Origine pour `start` (comme `SeekWhence`, `SeekWhence::Set` = 0).
    pub whence: SeekWhence,
    /// Offset de début (relatif à `whence`).
    pub start: i64,
    /// Longueur verrouillée (0 = jusqu'à la fin du fichier).
    pub length: i64,
    /// PID du processus détenant le verrou (rempli par `F_GETLK`).
    pub pid: i32,
}

bitflags! {
    /// Scellements d'un `memfd` (cf. `linux/fcntl.h` : `F_SEAL_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct Seals: u32 {
        /// Interdit d'ajouter de nouveaux scellements.
        const SEAL       = 1;
        /// Interdit de réduire la taille du fichier.
        const SHRINK     = 2;
        /// Interdit d'augmenter la taille du fichier.
        const GROW       = 4;
        /// Interdit toute écriture dans le fichier.
        const WRITE      = 8;
        /// Interdit les écritures futures même via des mappings existants.
        const FUTURE_WRITE = 16;
        /// Interdit la création de nouveaux mappings exécutables.
        const EXEC       = 32;
    }
}

// ─────────────────────────────────────────────────────────────────────────
// name_to_handle_at / open_by_handle_at
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Flags pour `name_to_handle_at(2)`.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct NameToHandleFlags: i32 {
        /// Ne suit pas les liens symboliques.
        const SYMLINK_NOFOLLOW = 0x100;
        /// Opère sur le FD lui-même (équivalent à `AT_EMPTY_PATH`).
        const EMPTY_PATH       = 0x1000;
    }
}

/// Handle de fichier persistant retourné par `name_to_handle_at(2)`.
///
/// Permet de référencer un fichier même après un changement de chemin.
/// Opaque : la taille et le contenu de `handle_bytes` dépendent du
/// filesystem.
///
/// **Allocation heap :** la taille du handle est dynamique et déterminée
/// par le kernel au premier appel. Nécessité documentée (ADR-021
/// convention 4).
#[derive(Debug, Clone)]
pub struct FileHandle {
    /// Identifiant de type de handle (opaque, défini par le filesystem).
    pub handle_type: i32,
    /// Octets du handle (taille et contenu définis par le filesystem).
    pub handle_bytes: Vec<u8>,
    /// Identifiant de point de montage (retourné par `name_to_handle_at`).
    pub mount_id: i32,
}

// ─────────────────────────────────────────────────────────────────────────
// statfs / fstatfs
// ─────────────────────────────────────────────────────────────────────────

/// Type de filesystem (champ `f_type` de `statfs(2)`).
///
/// Enveloppe la valeur magique retournée par le kernel identifiant le type de FS.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct FsType(pub i64);

impl FsType {
    /// ext4 (0xEF53)
    pub const EXT4: Self = Self(0xEF53);
    /// tmpfs (0x0102_1994)
    pub const TMPFS: Self = Self(0x0102_1994);
    /// proc (0x9FA0)
    pub const PROC: Self = Self(0x9FA0);
    /// sysfs (0x6265_6572)
    pub const SYSFS: Self = Self(0x6265_6572);
    /// btrfs (0x9123_683E)
    pub const BTRFS: Self = Self(0x9123_683E);
}

/// Résultat de `statfs(2)` / `fstatfs(2)` — informations sur le système de fichiers.
///
/// Mappé depuis la struct kernel `statfs64` de manière indépendante de l'architecture.
/// Le wrapper Air n'expose jamais le layout kernel brut.
#[derive(Debug, Clone, Copy)]
pub struct StatFsResult {
    /// Type du système de fichiers (voir [`FsType`]).
    pub f_type: FsType,
    /// Taille optimale des blocs de transfert (octets).
    pub f_bsize: i64,
    /// Taille de fragment (blocs FS fondamentaux, octets).
    pub f_frsize: i64,
    /// Nombre total de blocs de données.
    pub f_blocks: u64,
    /// Nombre de blocs libres.
    pub f_bfree: u64,
    /// Nombre de blocs disponibles pour les non-privilégiés.
    pub f_bavail: u64,
    /// Nombre total d'inodes.
    pub f_files: u64,
    /// Nombre d'inodes libres.
    pub f_ffree: u64,
    /// Identifiant du système de fichiers (opaque).
    pub f_fsid: [u32; 2],
    /// Longueur maximale d'un nom de fichier.
    pub f_namelen: i64,
    /// Drapeaux du FS (ex. `ST_RDONLY`, `ST_NOEXEC`).
    pub f_flags: i64,
}

// ─────────────────────────────────────────────────────────────────────────
// Types partagés ajoutés pour io_uring Temps 2a (cf.
// docs/specs/layer-0/io-uring-2a-filesystem.md). Ces types vivent dans la
// famille `fs` car ils décrivent la sémantique des opérations filesystem,
// qu'elles soient exposées de façon synchrone (`air-sys-syscall::fs`) ou
// asynchrone (`air-sys-syscall::io_uring`). Valeurs : uapi Linux 6.12.
// ─────────────────────────────────────────────────────────────────────────

bitflags! {
    /// Drapeaux de `fsync` via io_uring (`IORING_FSYNC_*`).
    ///
    /// `DATASYNC` sélectionne la sémantique `fdatasync` (ne synchronise pas les
    /// métadonnées non essentielles à la relecture des données).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct FsyncFlags: u32 {
        /// `IORING_FSYNC_DATASYNC` : sémantique `fdatasync`.
        const DATASYNC = 1 << 0;
    }
}

bitflags! {
    /// Drapeaux de `sync_file_range(2)` (cf. `linux/fs.h` : `SYNC_FILE_RANGE_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct SyncFileRangeFlags: u32 {
        /// Attend l'écriture des pages déjà en cours avant de lancer la plage.
        const WAIT_BEFORE = 1;
        /// Lance l'écriture des pages sales de la plage.
        const WRITE       = 2;
        /// Attend l'écriture des pages de la plage après les avoir lancées.
        const WAIT_AFTER  = 4;
    }
}

bitflags! {
    /// Drapeaux de changement de permissions pour `fchmodat2(2)` (`AT_*`).
    ///
    /// N'a de sens **qu'avec** `fchmodat2` (4 arguments, Linux ≥ 6.6) : le syscall
    /// historique `fchmodat` n'en prend que 3 et ne peut donc porter aucun drapeau.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct ChmodFlags: i32 {
        /// `AT_SYMLINK_NOFOLLOW` : opère sur le **lien** lui-même plutôt que sur sa
        /// cible. Un lien symbolique n'ayant pas de permissions modifiables sous
        /// Linux, l'appel échoue alors en `EOPNOTSUPP` — ce qui en fait une garantie
        /// utilisable : « ce chemin n'était pas un lien » (anti-TOCTOU).
        const SYMLINK_NOFOLLOW = 0x100;
    }
}

bitflags! {
    /// Drapeaux de suppression pour `unlinkat(2)` (`AT_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct UnlinkFlags: i32 {
        /// `AT_REMOVEDIR` : supprime un répertoire (sémantique `rmdir`).
        const REMOVEDIR = 0x200;
    }
}

bitflags! {
    /// Drapeaux de lien pour `linkat(2)` (`AT_*`).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct LinkFlags: i32 {
        /// `AT_SYMLINK_FOLLOW` : suit la cible si l'ancien chemin est un lien.
        const SYMLINK_FOLLOW = 0x400;
        /// `AT_EMPTY_PATH` : lie le FD lui-même (chemin vide).
        const EMPTY_PATH     = 0x1000;
    }
}

bitflags! {
    /// Drapeaux de création des attributs étendus (`setxattr(2)` : `XATTR_*`).
    ///
    /// Mutuellement exclusifs ; sans drapeau, l'attribut est créé ou remplacé.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct XattrFlags: i32 {
        /// `XATTR_CREATE` : échoue (`EEXIST`) si l'attribut existe déjà.
        const CREATE  = 1;
        /// `XATTR_REPLACE` : échoue (`ENODATA`) si l'attribut n'existe pas.
        const REPLACE = 2;
    }
}

/// Conseil d'accès pour `posix_fadvise(2)` (`POSIX_FADV_*`).
///
/// Distinct de [`crate::mem::MadviseAdvice`] : l'espace de valeurs de
/// `posix_fadvise` (fichier) n'est pas celui de `madvise` (mémoire), même si
/// la spec io_uring 2a les nomme tous deux « advice ». Sur les cibles tier-1
/// d'Air (x86_64/aarch64), les constantes valent 0..=5.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(i32)]
pub enum FadviseAdvice {
    /// `POSIX_FADV_NORMAL` : aucun conseil particulier.
    Normal = 0,
    /// `POSIX_FADV_RANDOM` : accès aléatoire (désactive le préfetch).
    Random = 1,
    /// `POSIX_FADV_SEQUENTIAL` : accès séquentiel (préfetch agressif).
    Sequential = 2,
    /// `POSIX_FADV_WILLNEED` : données bientôt nécessaires (préfetch).
    WillNeed = 3,
    /// `POSIX_FADV_DONTNEED` : données plus nécessaires (libère le cache).
    DontNeed = 4,
    /// `POSIX_FADV_NOREUSE` : données accédées une seule fois.
    NoReuse = 5,
}

impl FadviseAdvice {
    /// Valeur kernel (`POSIX_FADV_*`) du conseil.
    #[must_use]
    pub const fn as_raw(self) -> i32 {
        self as i32
    }
}

/// Horodatage brut du kernel (`struct statx_timestamp`, 16 octets).
///
/// Miroir `#[repr(C)]` écrit par le kernel ; cf. [`Statx`].
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct StatxTimestampRaw {
    /// Secondes depuis l'epoch Unix (`tv_sec`).
    pub tv_sec: i64,
    /// Nanosecondes (`tv_nsec`, dans `[0, 999_999_999]`).
    pub tv_nsec: u32,
    /// Réservé kernel (toujours 0).
    reserved: i32,
}

/// Miroir brut `#[repr(C)]` de `struct statx` (256 octets, cf. `linux/stat.h`).
///
/// Contrairement à [`StatxResult`] (forme décodée, indépendante de l'ABI), ce
/// type est le **tampon de sortie écrit directement par le kernel** :
/// `io_uring`'s `IORING_OP_STATX` y dépose les métadonnées de façon asynchrone.
/// Les champs portent les noms kernel (zone d'interface, ADR-029). Construire
/// via [`Statx::default`] (zéro-initialisé) avant de le confier au ring.
#[repr(C)]
#[derive(Debug, Clone, Default)]
pub struct Statx {
    /// Champs effectivement remplis (`stx_mask`).
    pub mask: u32,
    /// Granularité d'E/S préférée (`stx_blksize`).
    pub blksize: u32,
    /// Attributs supplémentaires (`stx_attributes`).
    pub attributes: u64,
    /// Nombre de liens physiques (`stx_nlink`).
    pub nlink: u32,
    /// UID du propriétaire (`stx_uid`).
    pub uid: u32,
    /// GID du propriétaire (`stx_gid`).
    pub gid: u32,
    /// Type et permissions (`stx_mode`).
    pub mode: u16,
    spare0: [u16; 1],
    /// Numéro d'inode (`stx_ino`).
    pub ino: u64,
    /// Taille en octets (`stx_size`).
    pub size: u64,
    /// Blocs de 512 octets alloués (`stx_blocks`).
    pub blocks: u64,
    /// Masque d'attributs supportés (`stx_attributes_mask`).
    pub attributes_mask: u64,
    /// Horodatage d'accès (`stx_atime`).
    pub atime: StatxTimestampRaw,
    /// Horodatage de création (`stx_btime`).
    pub btime: StatxTimestampRaw,
    /// Horodatage de modification de métadonnées (`stx_ctime`).
    pub ctime: StatxTimestampRaw,
    /// Horodatage de modification de données (`stx_mtime`).
    pub mtime: StatxTimestampRaw,
    /// Numéro majeur du device représenté (`stx_rdev_major`).
    pub rdev_major: u32,
    /// Numéro mineur du device représenté (`stx_rdev_minor`).
    pub rdev_minor: u32,
    /// Numéro majeur du device contenant (`stx_dev_major`).
    pub dev_major: u32,
    /// Numéro mineur du device contenant (`stx_dev_minor`).
    pub dev_minor: u32,
    /// Identifiant de point de montage (`stx_mnt_id`).
    pub mnt_id: u64,
    spare2: u64,
    spare3: [u64; 12],
}

impl Statx {
    /// Vrai si le bit de [`StatxMask`] `field` est présent dans `mask`.
    #[must_use]
    pub fn has(&self, field: StatxMask) -> bool {
        self.mask & field.bits() == field.bits()
    }
}

// Vérifications de layout ABI (figées par le kernel) : une dérive ferait
// échouer la compilation avant tout appel kernel.
const _: () = {
    assert!(core::mem::size_of::<StatxTimestampRaw>() == 16);
    assert!(core::mem::size_of::<Statx>() == 256);
    assert!(core::mem::align_of::<Statx>() == 8);
};

// ─────────────────────────────────────────────────────────────────────────
// inotify — surveillance de fichiers (sous-module `fs::inotify`)
// Cf. `docs/specs/layer-0/family-fs-inotify.md`.
// ─────────────────────────────────────────────────────────────────────────

/// Descripteur de surveillance (retour d'`inotify_add_watch`). Newtype typé
/// (jamais un `i32` brut) — ADR-029. Aussi le champ `wd` des événements lus.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct WatchDescriptor(i32);

impl WatchDescriptor {
    /// Construit depuis le `wd` brut rendu par `inotify_add_watch` (≥ 0) ou lu
    /// dans un événement. Usage interne aux wrappers/au décodeur.
    #[must_use]
    pub const fn from_raw(wd: i32) -> Self {
        Self(wd)
    }

    /// Valeur brute du descripteur (à passer à `inotify_rm_watch`).
    #[must_use]
    pub const fn as_raw(self) -> i32 {
        self.0
    }
}

bitflags! {
    /// Masque d'événements / d'options inotify (`IN_*`). Noms kernel conservés
    /// (ADR-029). Sert à la fois en **entrée** (`add_watch`) et en **sortie**
    /// (bits positionnés par le kernel dans l'événement lu).
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct InotifyEventMask: u32 {
        /// Fichier accédé (lecture).
        const ACCESS        = 0x0000_0001;
        /// Fichier modifié (écriture).
        const MODIFY        = 0x0000_0002;
        /// Métadonnées changées (permissions, horodatage…).
        const ATTRIB        = 0x0000_0004;
        /// Fichier ouvert en écriture fermé.
        const CLOSE_WRITE   = 0x0000_0008;
        /// Fichier ouvert en lecture seule fermé.
        const CLOSE_NOWRITE = 0x0000_0010;
        /// Fichier ouvert.
        const OPEN          = 0x0000_0020;
        /// Fichier déplacé **hors** du répertoire surveillé (corrèle par `cookie`).
        const MOVED_FROM    = 0x0000_0040;
        /// Fichier déplacé **dans** le répertoire surveillé (corrèle par `cookie`).
        const MOVED_TO      = 0x0000_0080;
        /// Fichier/répertoire créé.
        const CREATE        = 0x0000_0100;
        /// Fichier/répertoire supprimé.
        const DELETE        = 0x0000_0200;
        /// Le répertoire/fichier surveillé lui-même a été supprimé.
        const DELETE_SELF   = 0x0000_0400;
        /// Le répertoire/fichier surveillé lui-même a été déplacé.
        const MOVE_SELF     = 0x0000_0800;
        /// Le système de fichiers contenant l'objet surveillé a été démonté
        /// (positionné par le kernel).
        const UNMOUNT       = 0x0000_2000;
        /// La file d'événements a débordé (positionné par le kernel ; `wd = -1`).
        const Q_OVERFLOW    = 0x0000_4000;
        /// Le watch a été retiré (explicitement, ou objet supprimé/démonté).
        const IGNORED       = 0x0000_8000;
        /// L'objet de l'événement est un répertoire (positionné par le kernel).
        const ISDIR         = 0x4000_0000;
        /// Option : ne surveiller que si `path` est un répertoire.
        const ONLYDIR       = 0x0100_0000;
        /// Option : ne pas déréférencer `path` s'il est un lien symbolique.
        const DONT_FOLLOW   = 0x0200_0000;
        /// Option : exclure les événements des fichiers déjà unlinkés.
        const EXCL_UNLINK   = 0x0400_0000;
        /// Option : ajouter à (au lieu de remplacer) le masque d'un watch existant.
        const MASK_ADD      = 0x2000_0000;
        /// Option : surveiller une seule fois puis retirer le watch.
        const ONESHOT       = 0x8000_0000;
    }
}

bitflags! {
    /// Flags de création de l'instance inotify (`inotify_init1`). `CLOEXEC` est
    /// posé **par défaut** par le wrapper ([`inotify_init`]).
    ///
    /// [`inotify_init`]: ../../../air_sys_syscall/fs/inotify/fn.inotify_init.html
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
    pub struct InotifyFlags: i32 {
        /// `IN_NONBLOCK` (= `O_NONBLOCK`) : FD non bloquant (`read` → `EAGAIN`).
        const NONBLOCK = 0x800;
        /// `IN_CLOEXEC` (= `O_CLOEXEC`) : posé par défaut par le wrapper.
        const CLOEXEC  = 0x8_0000;
    }
}

/// Un événement inotify décodé, **empruntant** le buffer de lecture (zéro copie).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct InotifyEvent<'b> {
    /// Watch d'où provient l'événement (`-1` typé pour `Q_OVERFLOW`).
    pub wd: WatchDescriptor,
    /// Masque des événements survenus (`IN_*`).
    pub mask: InotifyEventMask,
    /// Corrèle un `MOVED_FROM` avec son `MOVED_TO` (0 si non applicable).
    pub cookie: u32,
    /// Nom (octets, **pas** d'UTF-8 présumé) relatif au watch, sans le NUL de
    /// padding ; `None` si l'événement ne porte pas de nom.
    pub name: Option<&'b [u8]>,
}

/// Entête fixe d'un `struct inotify_event` : `wd:i32 + mask:u32 + cookie:u32 +
/// len:u32` = 16 octets, suivi de `len` octets de `name` (padded NUL).
const INOTIFY_EVENT_HEADER_LEN: usize = 16;

/// Vue empruntée sur un buffer rempli par `read(2)` : suite d'événements de
/// **taille variable**, décodée par un itérateur **zéro allocation** (mêmes
/// principes que le parseur uevent : `get()` partout, jamais d'indexation
/// paniquante, `name` = `&[u8]`). **Zéro perte (ADR-032)** : tous les événements
/// complets sont rendus ; un enregistrement final **tronqué** est *signalé* via
/// [`InotifyEvents::truncated`] (jamais avalé silencieusement).
#[derive(Debug, Clone)]
pub struct InotifyEvents<'b> {
    data: &'b [u8],
    offset: usize,
    truncated: bool,
}

impl<'b> InotifyEvents<'b> {
    /// Décode un buffer (rempli par `read` du FD inotify). Donnée **externe**
    /// (kernel) au sens du Principe 3 : aucune entrée ne panique (cf. fuzz).
    #[must_use]
    pub const fn parse(data: &'b [u8]) -> Self {
        Self {
            data,
            offset: 0,
            truncated: false,
        }
    }

    /// `true` si, après itération, le buffer se terminait par un enregistrement
    /// **incomplet** (entête ou `name` coupé). Signale à l'appelant qu'un
    /// événement n'a pas pu être rendu (agrandir le buffer / relire) — ADR-032.
    #[must_use]
    pub const fn truncated(&self) -> bool {
        self.truncated
    }

    /// Lit un `u32` natif à `off` dans `data` (borné par `get`).
    fn read_u32(&self, off: usize) -> Option<u32> {
        let end = off.checked_add(4)?;
        let bytes: [u8; 4] = self.data.get(off..end)?.try_into().ok()?;
        Some(u32::from_ne_bytes(bytes))
    }
}

impl<'b> Iterator for InotifyEvents<'b> {
    type Item = InotifyEvent<'b>;

    fn next(&mut self) -> Option<Self::Item> {
        let start = self.offset;
        // Fin propre : exactement à une frontière d'enregistrement.
        if start == self.data.len() {
            return None;
        }
        // Entête (16 o) : s'il ne tient pas, c'est une queue tronquée.
        let Some(name_len_u32) = self.read_u32(start.checked_add(12)?) else {
            self.truncated = true;
            return None;
        };
        let wd = self.read_u32(start)?.cast_signed();
        let mask = self.read_u32(start.checked_add(4)?)?;
        let cookie = self.read_u32(start.checked_add(8)?)?;
        let name_len = usize::try_from(name_len_u32).ok()?;
        let name_start = start.checked_add(INOTIFY_EVENT_HEADER_LEN)?;
        let name_end = name_start.checked_add(name_len)?;
        // `name` annoncé mais coupé par la fin du buffer → queue tronquée.
        let Some(name_bytes) = self.data.get(name_start..name_end) else {
            self.truncated = true;
            return None;
        };
        self.offset = name_end;
        // Retire le padding NUL ; `None` si aucun nom (len == 0 ou tout NUL).
        let trimmed = match name_bytes.iter().position(|&b| b == 0) {
            Some(nul) => name_bytes.get(..nul).unwrap_or(&[]),
            None => name_bytes,
        };
        let name = if trimmed.is_empty() {
            None
        } else {
            Some(trimmed)
        };
        Some(InotifyEvent {
            wd: WatchDescriptor::from_raw(wd),
            mask: InotifyEventMask::from_bits_truncate(mask),
            cookie,
            name,
        })
    }
}

#[cfg(test)]
mod io_uring_2a_types_tests;

#[cfg(test)]
mod inotify_decoder_tests;