air_sys_syscall/

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

//! Wrappers de la famille `fs` — filesystem, I/O synchrone, métadonnées.
//!
//! Cf. `docs/specs/layer-0/family-fs.md`.

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

use air_sys_types::fd::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd, RawFd};
use alloc::vec::Vec;
use core::ffi::CStr;
use core::num::NonZeroI32;

use air_sys_types::Errno;
use air_sys_types::fs::{
    AccessFlags, AccessMode, DirEntry, DirEntryType, DirFd, FallocateMode, FdFlags, FileHandle,
    FileLock, FsType, Mode, NameToHandleFlags, OpenFlags, OpenHow, RenameFlags, Seals, SeekWhence,
    StatFsResult, StatusFlags, StatxFlags, StatxMask, StatxResult, StatxTimestamp, UtimeValue,
};
use air_sys_types::net::{IoSlice, IoSliceMut};

// ─────────────────────────────────────────────────────────────────────────
// Constantes kernel
// ─────────────────────────────────────────────────────────────────────────

const AT_FDCWD: i32 = -100;
const O_CLOEXEC: u64 = 0o2_000_000;

/// Surveillance de fichiers (inotify). Sous-module dédié `fs::inotify`
/// (cf. `docs/specs/layer-0/family-fs-inotify.md`).
pub mod inotify;

// fcntl commands
const F_DUPFD_CLOEXEC: i32 = 1030;
const F_GETFD: i32 = 1;
const F_SETFD: i32 = 2;
const F_GETFL: i32 = 3;
const F_SETFL: i32 = 4;
const F_GETPIPE_SZ: i32 = 1032;
const F_SETPIPE_SZ: i32 = 1031;
const F_SETLK: i32 = 6;
const F_SETLKW: i32 = 7;
const F_ADD_SEALS: i32 = 1033;
const F_GET_SEALS: i32 = 1034;

// utimensat special values
const UTIME_NOW: i64 = 0x3FFF_FFFF;
const UTIME_OMIT: i64 = 0x3FFF_FFFE;

// ─────────────────────────────────────────────────────────────────────────
// Helpers internes
// ─────────────────────────────────────────────────────────────────────────

fn dirfd_to_raw(dirfd: DirFd<'_>) -> i32 {
    match dirfd {
        DirFd::Cwd => AT_FDCWD,
        DirFd::Fd(fd) => fd.as_raw_fd(),
    }
}

/// Convertit un fd (i32, potentiellement AT_FDCWD = -100) en u64 pour le syscall ABI.
///
/// Un fd négatif (AT_FDCWD = -100) est une sentinelle valide du kernel ; la
/// représentation u64 en complément à deux correspond exactement à ce que le kernel attend.
#[inline]
fn fd_to_u64(fd: i32) -> u64 {
    // SAFETY: les syscalls sur x86_64/aarch64 prennent les arguments dans des
    // registres 64 bits. Un fd négatif (ex. AT_FDCWD = -100) est transmis en
    // extension de signe vers 64 bits, ce que le cast i32 → i64 → u64 produit.
    #[allow(clippy::cast_sign_loss)]
    {
        fd as u64
    }
}

/// Convertit un i32 en u64 (extension de signe) pour les arguments syscall.
#[inline]
fn i32_to_u64(v: i32) -> u64 {
    // Les valeurs i32 négatives (ex. O_* flags, AT_REMOVEDIR, whence) sont des
    // arguments syscall valides ; leur représentation u64 en complément à deux
    // est correcte pour l'ABI kernel.
    #[allow(clippy::cast_sign_loss)]
    {
        v as u64
    }
}

/// Convertit un i64 retourné par un syscall en usize.
///
/// Précondition : `ret >= 0` (déjà vérifié avant l'appel).
#[inline]
fn ret_to_usize(ret: i64) -> usize {
    // ret >= 0 et <= SSIZE_MAX sur toutes les cibles 64 bits Air (ADR-014) ;
    // la troncature en usize est exacte sur les cibles 64 bits.
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    {
        ret as usize
    }
}

/// Convertit un i64 en u64 (interprétation bit-à-bit) pour les arguments syscall.
///
/// Utilisé pour les offsets signés passés au kernel (ex. lseek, ftruncate, fallocate).
/// L'ABI syscall Linux attend les valeurs dans des registres 64 bits ; un offset
/// négatif est valide et représenté en complément à deux.
#[inline]
fn i64_to_u64(v: i64) -> u64 {
    #[allow(clippy::cast_sign_loss)]
    {
        v as u64
    }
}

/// Wraps `ret_to_usize` dans un `Ok()` — utilisé comme dernière expression des fonctions
/// de type I/O retournant un compte d'octets.
#[inline]
fn ret_to_usize_ok(ret: i64) -> Result<usize, Errno> {
    Ok(ret_to_usize(ret))
}
fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    // `ret.wrapping_neg()` est donc dans `[1, 4095]` — toujours fit in i32.
    #[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)
}

// ─────────────────────────────────────────────────────────────────────────
// Structs kernel privées
// ─────────────────────────────────────────────────────────────────────────

#[repr(C)]
struct KernelOpenHow {
    flags: u64,
    mode: u64,
    resolve: u64,
}

const _: () = assert!(core::mem::size_of::<KernelOpenHow>() == 24);

#[repr(C)]
struct KernelStatxTimestamp {
    tv_sec: i64,
    tv_nsec: u32,
    __reserved: i32,
}

#[repr(C)]
struct KernelStatx {
    stx_mask: u32,
    stx_blksize: u32,
    stx_attributes: u64,
    stx_nlink: u32,
    stx_uid: u32,
    stx_gid: u32,
    stx_mode: u16,
    __spare0: [u16; 1],
    stx_ino: u64,
    stx_size: u64,
    stx_blocks: u64,
    stx_attributes_mask: u64,
    stx_atime: KernelStatxTimestamp,
    stx_btime: KernelStatxTimestamp,
    stx_ctime: KernelStatxTimestamp,
    stx_mtime: KernelStatxTimestamp,
    stx_rdev_major: u32,
    stx_rdev_minor: u32,
    stx_dev_major: u32,
    stx_dev_minor: u32,
    stx_mnt_id: u64,
    __spare2: u64,
    __spare3: [u64; 12],
}

const _: () = assert!(core::mem::size_of::<KernelStatx>() == 256);

#[repr(C)]
struct KernelStatfs {
    f_type: i64,
    f_bsize: i64,
    f_blocks: u64,
    f_bfree: u64,
    f_bavail: u64,
    f_files: u64,
    f_ffree: u64,
    f_fsid: [u32; 2],
    f_namelen: i64,
    f_frsize: i64,
    f_flags: i64,
    f_spare: [i64; 4],
}

const _: () = assert!(core::mem::size_of::<KernelStatfs>() == 120);

#[repr(C)]
struct KernelFlock {
    l_type: i16,
    l_whence: i16,
    _pad: i32,
    l_start: i64,
    l_len: i64,
    l_pid: i32,
    _pad2: i32,
}

#[repr(C)]
struct KernelFileHandle {
    handle_bytes: u32,
    handle_type: i32,
    f_handle: [u8; 128],
}

// ─────────────────────────────────────────────────────────────────────────
// Syscall raw helpers — x86_64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall1(nr: i64, a0: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall2(nr: i64, a0: u64, a1: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            in("rsi") a1,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall3(nr: i64, a0: u64, a1: u64, a2: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            in("rsi") a1,
            in("rdx") a2,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall4(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            in("rsi") a1,
            in("rdx") a2,
            in("r10") a3,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall5(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            in("rsi") a1,
            in("rdx") a2,
            in("r10") a3,
            in("r8") a4,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn syscall6(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64, a5: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") nr,
            in("rdi") a0,
            in("rsi") a1,
            in("rdx") a2,
            in("r10") a3,
            in("r8") a4,
            in("r9") a5,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Syscall raw helpers — aarch64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall1(nr: i64, a0: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall2(nr: i64, a0: u64, a1: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            in("x1") a1,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall3(nr: i64, a0: u64, a1: u64, a2: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            in("x1") a1,
            in("x2") a2,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall4(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            in("x1") a1,
            in("x2") a2,
            in("x3") a3,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall5(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            in("x1") a1,
            in("x2") a2,
            in("x3") a3,
            in("x4") a4,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn syscall6(nr: i64, a0: u64, a1: u64, a2: u64, a3: u64, a4: u64, a5: u64) -> i64 {
    let ret: i64;
    // SAFETY: appelant garantit la validité des arguments.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") nr,
            inout("x0") a0 => ret,
            in("x1") a1,
            in("x2") a2,
            in("x3") a3,
            in("x4") a4,
            in("x5") a5,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Numéros de syscall par architecture
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
mod nr {
    pub const READ: i64 = 0;
    pub const WRITE: i64 = 1;
    pub const CLOSE: i64 = 3;
    pub const LSEEK: i64 = 8;
    pub const PREAD64: i64 = 17;
    pub const PWRITE64: i64 = 18;
    pub const READV: i64 = 19;
    pub const WRITEV: i64 = 20;
    pub const PREADV: i64 = 295;
    pub const PWRITEV: i64 = 296;
    pub const FCNTL: i64 = 72;
    pub const FLOCK: i64 = 73;
    pub const FSYNC: i64 = 74;
    pub const FDATASYNC: i64 = 75;
    pub const FCHMOD: i64 = 91;
    pub const FCHOWN: i64 = 93;
    pub const SENDFILE: i64 = 40;
    pub const FTRUNCATE: i64 = 77;
    pub const GETDENTS64: i64 = 217;
    pub const STATFS: i64 = 137;
    pub const FSTATFS: i64 = 138;
    pub const FALLOCATE: i64 = 285;
    pub const OPENAT: i64 = 257;
    pub const MKDIRAT: i64 = 258;
    pub const MKNODAT: i64 = 259;
    pub const FCHOWNAT: i64 = 260;
    pub const UNLINKAT: i64 = 263;
    pub const LINKAT: i64 = 265;
    pub const SYMLINKAT: i64 = 266;
    pub const READLINKAT: i64 = 267;
    pub const FCHMODAT: i64 = 268;
    pub const FACCESSAT: i64 = 269;
    pub const FACCESSAT2: i64 = 439;
    pub const UTIMENSAT: i64 = 280;
    pub const COPY_FILE_RANGE: i64 = 326;
    pub const STATX: i64 = 332;
    pub const NAME_TO_HANDLE_AT: i64 = 303;
    pub const OPEN_BY_HANDLE_AT: i64 = 304;
    pub const SYNC_FILE_RANGE: i64 = 277;
    pub const RENAMEAT2: i64 = 316;
    pub const OPENAT2: i64 = 437;
    pub const INOTIFY_INIT1: i64 = 294;
    pub const INOTIFY_ADD_WATCH: i64 = 254;
    pub const INOTIFY_RM_WATCH: i64 = 255;
}

#[cfg(target_arch = "aarch64")]
mod nr {
    pub const READ: i64 = 63;
    pub const WRITE: i64 = 64;
    pub const CLOSE: i64 = 57;
    pub const LSEEK: i64 = 62;
    pub const PREAD64: i64 = 67;
    pub const PWRITE64: i64 = 68;
    pub const READV: i64 = 65;
    pub const WRITEV: i64 = 66;
    pub const PREADV: i64 = 69;
    pub const PWRITEV: i64 = 70;
    pub const FCNTL: i64 = 25;
    pub const FLOCK: i64 = 32;
    pub const FSYNC: i64 = 82;
    pub const FDATASYNC: i64 = 83;
    pub const FCHMOD: i64 = 52;
    pub const FCHOWN: i64 = 55;
    pub const SENDFILE: i64 = 71;
    pub const FTRUNCATE: i64 = 46;
    pub const GETDENTS64: i64 = 61;
    pub const STATFS: i64 = 43;
    pub const FSTATFS: i64 = 44;
    pub const FALLOCATE: i64 = 47;
    pub const OPENAT: i64 = 56;
    pub const MKDIRAT: i64 = 34;
    pub const MKNODAT: i64 = 33;
    pub const FCHOWNAT: i64 = 54;
    pub const UNLINKAT: i64 = 35;
    pub const LINKAT: i64 = 37;
    pub const SYMLINKAT: i64 = 36;
    pub const READLINKAT: i64 = 78;
    pub const FCHMODAT: i64 = 53;
    pub const FACCESSAT: i64 = 48;
    pub const FACCESSAT2: i64 = 439;
    pub const UTIMENSAT: i64 = 88;
    pub const COPY_FILE_RANGE: i64 = 285;
    pub const STATX: i64 = 291;
    pub const NAME_TO_HANDLE_AT: i64 = 264;
    pub const OPEN_BY_HANDLE_AT: i64 = 265;
    pub const SYNC_FILE_RANGE: i64 = 84;
    pub const RENAMEAT2: i64 = 276;
    pub const OPENAT2: i64 = 437;
    pub const INOTIFY_INIT1: i64 = 26;
    pub const INOTIFY_ADD_WATCH: i64 = 27;
    pub const INOTIFY_RM_WATCH: i64 = 28;
}

// ─────────────────────────────────────────────────────────────────────────
// Ouverture et fermeture
// ─────────────────────────────────────────────────────────────────────────

/// Ouvre un fichier avec contrôle de résolution de chemin avancé.
///
/// Wrappeur de `openat2(2)` (Linux 5.6+, numéro 437). Préféré à
/// [`openat`] car il permet de contraindre la résolution de chemin via
/// [`OpenHow::resolve`]. Retombe automatiquement sur [`openat`] si le
/// kernel retourne `ENOSYS` (< Linux 5.6).
///
/// `O_CLOEXEC` est **toujours** ajouté aux flags par le wrapper —
/// tous les FDs ouverts par Air ont `CLOEXEC` par défaut.
///
/// # Parameters
///
/// - `dirfd` : répertoire de base pour la résolution ([`DirFd::Cwd`] ou
///   un FD de répertoire).
/// - `path` : chemin relatif à `dirfd` (ou absolu si `dirfd` est ignoré).
/// - `how` : flags, mode et politique de résolution.
///
/// # Errors
///
/// - `EACCES` : permissions insuffisantes.
/// - `ENOENT` : chemin inexistant (sans `CREAT`).
/// - `EEXIST` : fichier existant avec `CREAT | EXCL`.
/// - `EISDIR` : ouverture en écriture d'un répertoire.
/// - `ENOTDIR` : un composant du chemin n'est pas un répertoire.
/// - `EXDEV` : violation de `RESOLVE_NO_XDEV`.
/// - `EAGAIN` : violation de `RESOLVE_BENEATH` ou `RESOLVE_NO_SYMLINKS`.
/// - `ENFILE` / `EMFILE` : quotas FD atteints.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::openat2;
/// use air_sys_types::fs::{DirFd, OpenHow, OpenFlags, ResolveFlags};
///
/// let how = OpenHow {
///     flags: OpenFlags::RDONLY,
///     mode: 0,
///     resolve: ResolveFlags::BENEATH | ResolveFlags::NO_SYMLINKS,
/// };
/// let fd = openat2(DirFd::Cwd, c"./config.toml", how).expect("openat2");
/// ```
pub fn openat2(dirfd: DirFd<'_>, path: &CStr, how: OpenHow) -> Result<OwnedFd, Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);
    let kernel_how = KernelOpenHow {
        flags: how.flags.bits() | O_CLOEXEC,
        mode: u64::from(how.mode),
        resolve: how.resolve.bits(),
    };
    let path_ptr = path.as_ptr() as u64;
    let how_ptr = &kernel_how as *const KernelOpenHow as u64;
    let how_size = core::mem::size_of::<KernelOpenHow>();

    // SAFETY:
    // - path_ptr pointe sur un CStr nul-terminé valide pour la durée du syscall.
    // - how_ptr pointe sur KernelOpenHow local valide, size_of correct.
    // - raw_dirfd est AT_FDCWD ou un fd valide fourni par l'appelant.
    let ret = unsafe {
        syscall4(
            nr::OPENAT2,
            fd_to_u64(raw_dirfd),
            path_ptr,
            how_ptr,
            how_size as u64,
        )
    };

    if ret < 0 {
        let err = errno_from_negative_syscall_ret(ret);
        // Fallback sur openat si ENOSYS (kernel < 5.6)
        if err == Errno::ENOSYS {
            return openat(dirfd, path, how.flags, how.mode);
        }
        return Err(err);
    }

    // SAFETY: ret est un fd valide retourné par le kernel après succès.
    #[allow(clippy::cast_possible_truncation)]
    Ok(unsafe { OwnedFd::from_raw_fd(ret as i32) })
}

/// Ouvre un fichier (version sans contrôle de résolution avancé).
///
/// Wrappeur de `openat(2)`. Utilisé en fallback quand `openat2` n'est
/// pas disponible (kernel < 5.6). `O_CLOEXEC` est toujours ajouté.
///
/// # Parameters
///
/// - `dirfd` : répertoire de base.
/// - `path` : chemin relatif ou absolu.
/// - `flags` : flags d'ouverture.
/// - `mode` : permissions de création (significatif seulement avec `CREAT`).
///
/// # Errors
///
/// Voir [`openat2`] (sans les codes liés à `RESOLVE_*`).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::openat;
/// use air_sys_types::fs::{DirFd, OpenFlags};
///
/// let fd = openat(DirFd::Cwd, c"./data.bin", OpenFlags::RDONLY, 0)
///     .expect("openat");
/// ```
pub fn openat(
    dirfd: DirFd<'_>,
    path: &CStr,
    flags: OpenFlags,
    mode: Mode,
) -> Result<OwnedFd, Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);
    let raw_flags = flags.bits() | O_CLOEXEC;
    // raw_flags fits in i32 (O_* constants are all < 2^31).
    #[allow(clippy::cast_possible_truncation)]
    let raw_flags_i32 = raw_flags as i32;
    let path_ptr = path.as_ptr() as u64;

    // SAFETY:
    // - path_ptr est un CStr nul-terminé valide pour la durée du syscall.
    // - raw_dirfd est AT_FDCWD ou un fd valide.
    // - raw_flags_i32 contient des bits O_* valides.
    // - mode est une valeur Mode (u32) ; les 12 bits inférieurs sont utilisés.
    let ret = unsafe {
        syscall4(
            nr::OPENAT,
            fd_to_u64(raw_dirfd),
            path_ptr,
            i32_to_u64(raw_flags_i32),
            u64::from(mode),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // SAFETY: ret est un fd valide retourné par le kernel après succès.
    #[allow(clippy::cast_possible_truncation)]
    Ok(unsafe { OwnedFd::from_raw_fd(ret as i32) })
}

/// Ferme un FD explicitement et récupère l'erreur éventuelle.
///
/// Consomme l'[`OwnedFd`]. Le `Drop` automatique ferme aussi le FD mais
/// ignore les erreurs (ex. `EIO` sur NFS en cas de panne). Cette
/// fonction permet de les détecter.
///
/// # Errors
///
/// - `EIO` : erreur d'E/S lors de la fermeture (ex. NFS).
/// - `EINTR` : interrompu par un signal. Sur Linux, le FD est quand même
///   fermé après `EINTR` (ne pas réessayer).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::{openat, close};
/// use air_sys_types::fs::{DirFd, OpenFlags};
///
/// let fd = openat(DirFd::Cwd, c"./out.log", OpenFlags::WRONLY, 0)
///     .expect("openat");
/// close(fd).expect("close");
/// ```
pub fn close(fd: OwnedFd) -> Result<(), Errno> {
    let raw = fd.as_raw_fd();
    // Consomme le OwnedFd sans appeler son Drop (qui fermerait le fd une 2e fois).
    core::mem::forget(fd);

    // SAFETY:
    // - raw est le fd de l'OwnedFd consommé, valide au moment de l'appel.
    // - close(2) ne lit ni n'écrit de mémoire utilisateur.
    let ret = unsafe { syscall1(nr::CLOSE, fd_to_u64(raw)) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// I/O synchrone
// ─────────────────────────────────────────────────────────────────────────

/// Lit depuis un FD dans `buffer`.
///
/// Wrappeur de `read(2)`. Peut retourner moins d'octets que `buffer.len()`
/// (short read). L'appelant doit boucler si un read complet est requis.
///
/// # Errors
///
/// - `EAGAIN` : FD non-bloquant sans données disponibles.
/// - `EINTR` : interrompu par un signal (retry à la charge de l'appelant).
/// - `EIO` : erreur I/O bas niveau.
/// - `EBADF` : FD invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::read;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 1024];
/// let n = read(fd, &mut buffer).expect("read");
/// # }
/// ```
pub fn read(fd: BorrowedFd<'_>, buffer: &mut [u8]) -> Result<usize, Errno> {
    // SAFETY:
    // - buffer est un slice mutable valide pour la durée du syscall.
    // - fd est un BorrowedFd valide.
    // - read(2) écrit au plus buffer.len() octets dans buffer.
    let ret = unsafe {
        syscall3(
            nr::READ,
            fd_to_u64(fd.as_raw_fd()),
            buffer.as_mut_ptr() as u64,
            buffer.len() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // ret >= 0, au plus buffer.len() <= usize::MAX : cast sûr.
    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Écrit `buffer` sur un FD.
///
/// Wrappeur de `write(2)`. Peut retourner moins d'octets écrits que
/// `buffer.len()` (short write). L'appelant doit boucler si nécessaire.
///
/// # Errors
///
/// - `EAGAIN` : FD non-bloquant et buffer kernel plein.
/// - `EINTR` : interrompu par un signal.
/// - `EIO` : erreur I/O bas niveau.
/// - `ENOSPC` : plus d'espace sur le device.
/// - `EPIPE` : extrémité de lecture du pipe fermée.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::write;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let n = write(fd, b"hello\n").expect("write");
/// # }
/// ```
pub fn write(fd: BorrowedFd<'_>, buffer: &[u8]) -> Result<usize, Errno> {
    // SAFETY:
    // - buffer est un slice immuable valide pour la durée du syscall.
    // - write(2) lit au plus buffer.len() octets depuis buffer.
    let ret = unsafe {
        syscall3(
            nr::WRITE,
            fd_to_u64(fd.as_raw_fd()),
            buffer.as_ptr() as u64,
            buffer.len() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Lit depuis une position absolue sans modifier la position courante du FD.
///
/// # Errors
///
/// Voir [`read`]. De plus : `ESPIPE` si le FD n'est pas seekable (pipe, socket).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::pread;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 512];
/// let n = pread(fd, &mut buffer, 1024).expect("pread");
/// # }
/// ```
pub fn pread(fd: BorrowedFd<'_>, buffer: &mut [u8], offset: u64) -> Result<usize, Errno> {
    // SAFETY: buffer est un slice mutable valide ; pread64 écrit au plus buffer.len() octets.
    let ret = unsafe {
        syscall4(
            nr::PREAD64,
            fd_to_u64(fd.as_raw_fd()),
            buffer.as_mut_ptr() as u64,
            buffer.len() as u64,
            offset,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Écrit à une position absolue sans modifier la position courante du FD.
///
/// # Errors
///
/// Voir [`write()`]. De plus : `ESPIPE` si FD non seekable.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::pwrite;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let n = pwrite(fd, b"data", 0).expect("pwrite");
/// # }
/// ```
pub fn pwrite(fd: BorrowedFd<'_>, buffer: &[u8], offset: u64) -> Result<usize, Errno> {
    // SAFETY: buffer est un slice immuable valide ; pwrite64 lit au plus buffer.len() octets.
    let ret = unsafe {
        syscall4(
            nr::PWRITE64,
            fd_to_u64(fd.as_raw_fd()),
            buffer.as_ptr() as u64,
            buffer.len() as u64,
            offset,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Lecture scatter vers plusieurs buffers (`readv(2)`).
///
/// # Errors
///
/// Voir [`read`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::readv;
/// use air_sys_types::net::IoSliceMut;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut a = [0u8; 64];
/// let mut b = [0u8; 64];
/// let mut iov = [IoSliceMut::new(&mut a), IoSliceMut::new(&mut b)];
/// let n = readv(fd, &mut iov).expect("readv");
/// # }
/// ```
pub fn readv(fd: BorrowedFd<'_>, iov: &mut [IoSliceMut<'_>]) -> Result<usize, Errno> {
    // SAFETY:
    // - iov est un slice de IoSliceMut (repr(C), layout iovec) valide.
    // - readv(2) écrit dans les buffers pointés par chaque iovec.
    let ret = unsafe {
        syscall3(
            nr::READV,
            fd_to_u64(fd.as_raw_fd()),
            iov.as_ptr() as u64,
            iov.len() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Écriture gather depuis plusieurs buffers (`writev(2)`).
///
/// # Errors
///
/// Voir [`write()`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::writev;
/// use air_sys_types::net::IoSlice;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let a = b"header";
/// let b = b"payload";
/// let iov = [IoSlice::new(a), IoSlice::new(b)];
/// let n = writev(fd, &iov).expect("writev");
/// # }
/// ```
pub fn writev(fd: BorrowedFd<'_>, iov: &[IoSlice<'_>]) -> Result<usize, Errno> {
    // SAFETY:
    // - iov est un slice de IoSlice (repr(C), layout iovec) valide.
    // - writev(2) lit dans les buffers pointés par chaque iovec.
    let ret = unsafe {
        syscall3(
            nr::WRITEV,
            fd_to_u64(fd.as_raw_fd()),
            iov.as_ptr() as u64,
            iov.len() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Lecture scatter positionnée (`preadv(2)`).
pub fn preadv(fd: BorrowedFd<'_>, iov: &mut [IoSliceMut<'_>], offset: u64) -> Result<usize, Errno> {
    // preadv ABI: (fd, iov, iovcnt, offset_lo, offset_hi) on x86_64
    // On aarch64 : (fd, iov, iovcnt, offset) — offset is a single 64-bit register.
    // We pass offset as a5 (r8/x4) with a4=0 on x86_64 for simplicity using 5-arg form.
    // Actually the Linux preadv ABI on x86_64 takes offset split into two 32-bit args
    // in r8 (low) and r9 (high). We use syscall6 to pass both halves.
    let off_lo = offset & 0xFFFF_FFFF;
    let off_hi = offset >> 32;

    // SAFETY:
    // - iov est un slice de IoSliceMut valide.
    // - preadv écrit dans les buffers référencés par iov.
    // - offset est une position valide (non vérifiée par le wrapper, ESPIPE si non seekable).
    let ret = unsafe {
        syscall6(
            nr::PREADV,
            fd_to_u64(fd.as_raw_fd()),
            iov.as_ptr() as u64,
            iov.len() as u64,
            off_lo,
            off_hi,
            0,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Écriture gather positionnée (`pwritev(2)`).
pub fn pwritev(fd: BorrowedFd<'_>, iov: &[IoSlice<'_>], offset: u64) -> Result<usize, Errno> {
    let off_lo = offset & 0xFFFF_FFFF;
    let off_hi = offset >> 32;

    // SAFETY:
    // - iov est un slice de IoSlice valide.
    // - pwritev lit dans les buffers référencés par iov.
    let ret = unsafe {
        syscall6(
            nr::PWRITEV,
            fd_to_u64(fd.as_raw_fd()),
            iov.as_ptr() as u64,
            iov.len() as u64,
            off_lo,
            off_hi,
            0,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

// ─────────────────────────────────────────────────────────────────────────
// Positionnement
// ─────────────────────────────────────────────────────────────────────────

/// Modifie la position courante d'un FD seekable.
///
/// Wrappeur de `lseek(2)`. Retourne la nouvelle position absolue.
///
/// # Parameters
///
/// - `fd` : FD seekable.
/// - `offset` : déplacement.
/// - `whence` : origine ([`SeekWhence::Set`], `Current`, `End`, `Data`, `Hole`).
///
/// # Errors
///
/// - `ESPIPE` : FD non seekable (pipe, socket).
/// - `EINVAL` : position résultante négative.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::lseek;
/// use air_sys_types::fs::SeekWhence;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let pos = lseek(fd, 0, SeekWhence::End).expect("lseek");
/// # }
/// ```
pub fn lseek(fd: BorrowedFd<'_>, offset: i64, whence: SeekWhence) -> Result<u64, Errno> {
    // SAFETY: lseek(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::LSEEK,
            fd_to_u64(fd.as_raw_fd()),
            i64_to_u64(offset),
            i32_to_u64(whence as i32),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // La nouvelle position est non-négative.
    #[allow(clippy::cast_sign_loss)]
    #[allow(clippy::cast_sign_loss)]
    Ok(ret as u64)
}

// ─────────────────────────────────────────────────────────────────────────
// Métadonnées
// ─────────────────────────────────────────────────────────────────────────

/// Lit les métadonnées d'un fichier (API unifiée et moderne).
///
/// Wrappeur de `statx(2)` (Linux 4.11+, numéro x86_64: 332, aarch64: 291).
/// Remplace tous les anciens `stat`/`fstat`/`lstat`/`fstatat` — seul
/// wrapper de métadonnées exposé par Air.
///
/// Le paramètre `mask` sélectionne les champs souhaités ;
/// `StatxResult::mask` en sortie indique les champs effectivement
/// disponibles (sous-ensemble possible si le FS ne les supporte pas).
///
/// # Parameters
///
/// - `dirfd` : base de résolution.
/// - `path` : chemin (peut être vide avec `StatxFlags::EMPTY_PATH` pour
///   opérer directement sur le FD).
/// - `flags` : comportement de résolution.
/// - `mask` : champs à récupérer.
///
/// # Errors
///
/// - `ENOENT` : chemin inexistant.
/// - `EACCES` : permissions insuffisantes.
/// - `ENOSYS` : kernel < 4.11.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::statx;
/// use air_sys_types::fs::{DirFd, StatxFlags, StatxMask};
///
/// let result = statx(
///     DirFd::Cwd,
///     c"./config.toml",
///     StatxFlags::empty(),
///     StatxMask::SIZE | StatxMask::MTIME,
/// ).expect("statx");
/// if result.mask.contains(StatxMask::SIZE) {
///     println!("size: {}", result.size);
/// }
/// ```
pub fn statx(
    dirfd: DirFd<'_>,
    path: &CStr,
    flags: StatxFlags,
    mask: StatxMask,
) -> Result<StatxResult, Errno> {
    let mut kstatx = KernelStatx {
        stx_mask: 0,
        stx_blksize: 0,
        stx_attributes: 0,
        stx_nlink: 0,
        stx_uid: 0,
        stx_gid: 0,
        stx_mode: 0,
        __spare0: [0],
        stx_ino: 0,
        stx_size: 0,
        stx_blocks: 0,
        stx_attributes_mask: 0,
        stx_atime: KernelStatxTimestamp {
            tv_sec: 0,
            tv_nsec: 0,
            __reserved: 0,
        },
        stx_btime: KernelStatxTimestamp {
            tv_sec: 0,
            tv_nsec: 0,
            __reserved: 0,
        },
        stx_ctime: KernelStatxTimestamp {
            tv_sec: 0,
            tv_nsec: 0,
            __reserved: 0,
        },
        stx_mtime: KernelStatxTimestamp {
            tv_sec: 0,
            tv_nsec: 0,
            __reserved: 0,
        },
        stx_rdev_major: 0,
        stx_rdev_minor: 0,
        stx_dev_major: 0,
        stx_dev_minor: 0,
        stx_mnt_id: 0,
        __spare2: 0,
        __spare3: [0u64; 12],
    };

    let raw_dirfd = dirfd_to_raw(dirfd);
    let path_ptr = path.as_ptr() as u64;
    let buf_ptr = &mut kstatx as *mut KernelStatx as u64;

    // SAFETY:
    // - path_ptr est un CStr nul-terminé valide.
    // - buf_ptr pointe sur KernelStatx local correctement dimensionné (256 octets).
    // - Le kernel remplit la structure si le syscall réussit.
    let ret = unsafe {
        syscall5(
            nr::STATX,
            fd_to_u64(raw_dirfd),
            path_ptr,
            u64::from(flags.bits()),
            u64::from(mask.bits()),
            buf_ptr,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    let ts_from = |ts: &KernelStatxTimestamp| StatxTimestamp {
        seconds: ts.tv_sec,
        nanoseconds: ts.tv_nsec,
    };

    Ok(StatxResult {
        mask: StatxMask::from_bits_truncate(kstatx.stx_mask),
        blksize: kstatx.stx_blksize,
        attributes: kstatx.stx_attributes,
        nlink: kstatx.stx_nlink,
        uid: kstatx.stx_uid,
        gid: kstatx.stx_gid,
        mode: kstatx.stx_mode,
        ino: kstatx.stx_ino,
        size: kstatx.stx_size,
        blocks: kstatx.stx_blocks,
        atime: ts_from(&kstatx.stx_atime),
        btime: ts_from(&kstatx.stx_btime),
        ctime: ts_from(&kstatx.stx_ctime),
        mtime: ts_from(&kstatx.stx_mtime),
        rdev_major: kstatx.stx_rdev_major,
        rdev_minor: kstatx.stx_rdev_minor,
        dev_major: kstatx.stx_dev_major,
        dev_minor: kstatx.stx_dev_minor,
        mount_id: kstatx.stx_mnt_id,
    })
}

/// Teste les permissions d'accès à un fichier sans l'ouvrir.
///
/// Wrappeur de `faccessat(2)`. **Attention :** sujet à des races
/// TOCTOU — préférer ouvrir directement et gérer l'erreur.
///
/// # Routage par flags (faccessat vs faccessat2)
///
/// Le syscall noyau `faccessat` historique ne prend **que 3 arguments**
/// (`dirfd`, `path`, `mode`) : il **ignore silencieusement** tout flag
/// comportemental. Honorer `AT_SYMLINK_NOFOLLOW` / `AT_EACCESS` exige le
/// syscall `faccessat2` (numéro 439 sur x86_64 **et** aarch64, Linux 5.8+,
/// 4 arguments). Comme la glibc, ce wrapper route donc selon `flags` :
///
/// - `flags.is_empty()` → `faccessat` (3-arg, universellement disponible) ;
/// - `flags` non vide → `faccessat2` (4-arg, qui **applique** réellement les
///   flags).
///
/// La signature publique est inchangée ; seul le syscall sous-jacent diffère.
/// Sur un noyau < 5.8 sans `faccessat2`, un appel avec flags retourne `ENOSYS`
/// (l'appelant n'obtient jamais un résultat où le flag aurait été ignoré).
///
/// # Errors
///
/// - `EACCES` : accès refusé.
/// - `ENOENT` : chemin inexistant.
/// - `ENOSYS` : `faccessat2` indisponible (noyau < 5.8) et `flags` non vide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::faccessat;
/// use air_sys_types::fs::{AccessFlags, AccessMode, DirFd};
///
/// let result = faccessat(DirFd::Cwd, c"./script.sh", AccessMode::X_OK, AccessFlags::empty());
/// ```
pub fn faccessat(
    dirfd: DirFd<'_>,
    path: &CStr,
    mode: AccessMode,
    flags: AccessFlags,
) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    let ret = if flags.is_empty() {
        // SAFETY: SYS_faccessat (x86_64 = 269) / SYS_faccessat (aarch64 = 48).
        // 3 arguments : (dirfd, path, mode). path est un CStr nul-terminé valide
        // pour la durée du syscall. Flags vides → le syscall 3-arg historique
        // suffit (il ne porte de toute façon aucun flag) et reste universellement
        // disponible.
        unsafe {
            syscall3(
                nr::FACCESSAT,
                fd_to_u64(raw_dirfd),
                path.as_ptr() as u64,
                u64::from(mode.bits()),
            )
        }
    } else {
        // SAFETY: SYS_faccessat2 (x86_64 = 439) / SYS_faccessat2 (aarch64 = 439).
        // 4 arguments : (dirfd, path, mode, flags). path est un CStr nul-terminé
        // valide pour la durée du syscall. C'est le seul syscall qui HONORE
        // réellement AT_SYMLINK_NOFOLLOW / AT_EACCESS — le 3-arg les ignore.
        unsafe {
            syscall4(
                nr::FACCESSAT2,
                fd_to_u64(raw_dirfd),
                path.as_ptr() as u64,
                u64::from(mode.bits()),
                i32_to_u64(flags.bits()),
            )
        }
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

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

/// Crée un répertoire.
///
/// # Errors
///
/// - `EEXIST` : chemin existant.
/// - `ENOENT` : répertoire parent inexistant.
/// - `EACCES` : permissions insuffisantes.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::mkdirat;
/// use air_sys_types::fs::DirFd;
///
/// mkdirat(DirFd::Cwd, c"./newdir", 0o755).expect("mkdirat");
/// ```
pub fn mkdirat(dirfd: DirFd<'_>, path: &CStr, mode: Mode) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: path_ptr est un CStr nul-terminé valide.
    let ret = unsafe {
        syscall3(
            nr::MKDIRAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            u64::from(mode),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit les entrées d'un répertoire.
///
/// Wrappeur de `getdents64(2)`. Le paramètre `buffer` est un buffer brut
/// dont le format binaire est parsé en interne. Utiliser
/// [`parse_dirents`] pour itérer sur les entrées.
///
/// **Allocation intrinsèque :** le buffer est alloué par l'appelant (pas
/// de contrainte sur la taille, mais 4096+ octets est recommandé).
///
/// # Parameters
///
/// - `fd` : FD d'un répertoire ouvert avec `DIRECTORY`.
/// - `buffer` : buffer de lecture (au moins quelques Ko recommandés).
///
/// # Errors
///
/// - `EINVAL` : buffer trop petit pour contenir une entrée.
/// - `ENOTDIR` : FD n'est pas un répertoire.
/// - `EBADF` : FD invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::{getdents64, parse_dirents};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(dir_fd: BorrowedFd<'_>) {
/// let mut buffer = vec![0u8; 4096];
/// let n = getdents64(dir_fd, &mut buffer).expect("getdents64");
/// for entry in parse_dirents(&buffer[..n]) {
///     println!("{:?}", entry.name);
/// }
/// # }
/// ```
pub fn getdents64(fd: BorrowedFd<'_>, buffer: &mut [u8]) -> Result<usize, Errno> {
    // SAFETY:
    // - buffer est un slice mutable valide pour la durée du syscall.
    // - getdents64 écrit au plus buffer.len() octets dans buffer.
    let ret = unsafe {
        syscall3(
            nr::GETDENTS64,
            fd_to_u64(fd.as_raw_fd()),
            buffer.as_mut_ptr() as u64,
            buffer.len() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Itère sur les entrées de répertoire depuis un buffer `getdents64`.
///
/// Retourne un itérateur sur les [`DirEntry`] parsées depuis `buffer`.
/// Le buffer doit être valide pour toute la durée de l'itération.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::parse_dirents;
///
/// # fn example(buffer: &[u8]) {
/// for entry in parse_dirents(buffer) {
///     println!("inode={} name={:?}", entry.inode, entry.name);
/// }
/// # }
/// ```
pub fn parse_dirents(buffer: &[u8]) -> impl Iterator<Item = DirEntry> + '_ {
    ParseDirents {
        buf: buffer,
        offset: 0,
    }
}

/// Itérateur sur les entrées `linux_dirent64` dans un buffer brut.
struct ParseDirents<'a> {
    buf: &'a [u8],
    offset: usize,
}

impl<'a> Iterator for ParseDirents<'a> {
    type Item = DirEntry;

    fn next(&mut self) -> Option<Self::Item> {
        if self.offset >= self.buf.len() {
            return None;
        }

        let buffer = self.buf.get(self.offset..)?;

        // struct linux_dirent64 header: ino(8) + offset(8) + reclen(2) + type(1) = 19 bytes minimum
        if buffer.len() < 19 {
            return None;
        }

        let ino = u64::from_ne_bytes(buffer.get(0..8)?.try_into().ok()?);
        let offset = i64::from_ne_bytes(buffer.get(8..16)?.try_into().ok()?);
        let reclen = u16::from_ne_bytes(buffer.get(16..18)?.try_into().ok()?) as usize;
        let file_type_byte = *buffer.get(18)?;

        if reclen == 0 || reclen > buffer.len() {
            return None;
        }

        // Name starts at byte 19, null-terminated, within the record.
        let name_region = buffer.get(19..reclen)?;
        let nul_pos = name_region
            .iter()
            .position(|&b| b == 0)
            .unwrap_or(name_region.len());
        let name_bytes = name_region.get(..nul_pos)?;

        let file_type = match file_type_byte {
            1 => DirEntryType::Fifo,
            2 => DirEntryType::Character,
            4 => DirEntryType::Directory,
            6 => DirEntryType::Block,
            8 => DirEntryType::Regular,
            10 => DirEntryType::Symlink,
            12 => DirEntryType::Socket,
            _ => DirEntryType::Unknown,
        };

        // Nom = octets bruts (sans le `NUL`), aucune présomption d'encodage
        // (Principe 3, doctrine « chemins = octets ») : copie propriétaire.
        let name = name_bytes.to_vec();

        self.offset = self.offset.checked_add(reclen)?;

        Some(DirEntry {
            inode: ino,
            offset,
            file_type,
            name,
        })
    }
}

/// Supprime un fichier ou un répertoire vide.
///
/// Wrappeur de `unlinkat(2)`. Passer `AT_REMOVEDIR` dans `flags` pour
/// supprimer un répertoire (équivalent à `rmdir`).
///
/// # Errors
///
/// - `ENOENT` : fichier inexistant.
/// - `ENOTEMPTY` / `EEXIST` : répertoire non vide (avec `AT_REMOVEDIR`).
/// - `EACCES` : permissions insuffisantes.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::unlinkat;
/// use air_sys_types::fs::DirFd;
///
/// unlinkat(DirFd::Cwd, c"./old.tmp", 0).expect("unlinkat");
/// ```
pub fn unlinkat(dirfd: DirFd<'_>, path: &CStr, flags: i32) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: path_ptr est un CStr nul-terminé valide.
    let ret = unsafe {
        syscall3(
            nr::UNLINKAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            i32_to_u64(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Renomme (et éventuellement échange) des entrées filesystem.
///
/// Wrappeur de `renameat2(2)` (Linux 3.15+). `RenameFlags::EXCHANGE`
/// permet un échange atomique de deux entrées.
///
/// # Errors
///
/// - `EEXIST` : destination existante avec `NOREPLACE`.
/// - `ENOENT` : source inexistante.
/// - `EXDEV` : source et destination sur des FS différents.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::renameat2;
/// use air_sys_types::fs::{DirFd, RenameFlags};
///
/// renameat2(DirFd::Cwd, c"./new.tmp", DirFd::Cwd, c"./current", RenameFlags::NOREPLACE)
///     .expect("renameat2");
/// ```
pub fn renameat2(
    old_dirfd: DirFd<'_>,
    old_path: &CStr,
    new_dirfd: DirFd<'_>,
    new_path: &CStr,
    flags: RenameFlags,
) -> Result<(), Errno> {
    let raw_old = dirfd_to_raw(old_dirfd);
    let raw_new = dirfd_to_raw(new_dirfd);

    // SAFETY: old_path et new_path sont des CStr nul-terminés valides.
    let ret = unsafe {
        syscall5(
            nr::RENAMEAT2,
            fd_to_u64(raw_old),
            old_path.as_ptr() as u64,
            fd_to_u64(raw_new),
            new_path.as_ptr() as u64,
            u64::from(flags.bits()),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Crée un lien physique.
pub fn linkat(
    old_dirfd: DirFd<'_>,
    old_path: &CStr,
    new_dirfd: DirFd<'_>,
    new_path: &CStr,
    flags: i32,
) -> Result<(), Errno> {
    let raw_old = dirfd_to_raw(old_dirfd);
    let raw_new = dirfd_to_raw(new_dirfd);

    // SAFETY: les deux CStr sont nul-terminés et valides pour la durée du syscall.
    let ret = unsafe {
        syscall5(
            nr::LINKAT,
            fd_to_u64(raw_old),
            old_path.as_ptr() as u64,
            fd_to_u64(raw_new),
            new_path.as_ptr() as u64,
            i32_to_u64(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Crée un lien symbolique.
pub fn symlinkat(target: &CStr, new_dirfd: DirFd<'_>, link_path: &CStr) -> Result<(), Errno> {
    let raw_new = dirfd_to_raw(new_dirfd);

    // SAFETY: target et link_path sont des CStr nul-terminés valides.
    let ret = unsafe {
        syscall3(
            nr::SYMLINKAT,
            target.as_ptr() as u64,
            fd_to_u64(raw_new),
            link_path.as_ptr() as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit la cible d'un lien symbolique.
///
/// **Allocation heap :** le résultat est une `Vec<u8>` car la longueur
/// n'est connue qu'à l'exécution (nécessité documentée, ADR-021
/// convention 4).
///
/// # Errors
///
/// - `ENOENT` : lien inexistant.
/// - `EINVAL` : le chemin n'est pas un lien symbolique.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::readlinkat;
/// use air_sys_types::fs::DirFd;
///
/// let target = readlinkat(DirFd::Cwd, c"./link").expect("readlinkat");
/// ```
pub fn readlinkat(dirfd: DirFd<'_>, path: &CStr) -> Result<Vec<u8>, Errno> {
    // Commence avec PATH_MAX (4096). Si la cible est plus longue (rare),
    // on double le buffer et on réessaie.
    let mut buffer = vec![0u8; 4096];
    let raw_dirfd = dirfd_to_raw(dirfd);

    loop {
        let cap = buffer.len();

        // SAFETY:
        // - path est un CStr nul-terminé valide.
        // - buffer est un Vec mutable de taille `cap`.
        // - readlinkat(2) écrit au plus `cap` octets (sans NUL terminal).
        let ret = unsafe {
            syscall4(
                nr::READLINKAT,
                fd_to_u64(raw_dirfd),
                path.as_ptr() as u64,
                buffer.as_mut_ptr() as u64,
                cap as u64,
            )
        };

        if ret < 0 {
            return Err(errno_from_negative_syscall_ret(ret));
        }

        let n = ret_to_usize(ret);

        if n < cap {
            // Résultat tient dans le buffer.
            buffer.truncate(n);
            return Ok(buffer);
        }

        // Résultat peut-être tronqué : doubler le buffer et réessayer.
        // Checked pour éviter overflow sur des systèmes pathologiques.
        let new_cap = cap.checked_mul(2).ok_or_else(|| {
            Errno::from_nonzero(NonZeroI32::new(libc_enomem()).expect("ENOMEM non-zero"))
        })?;
        buffer.resize(new_cap, 0);
    }
}

// ENOMEM = 12, utilisé uniquement dans le chemin d'erreur de readlinkat.
#[inline(always)]
fn libc_enomem() -> i32 {
    12
}

/// Crée un nœud de périphérique, une FIFO ou un fichier régulier.
pub fn mknodat(dirfd: DirFd<'_>, path: &CStr, mode: Mode, dev: u64) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: path est un CStr nul-terminé valide.
    let ret = unsafe {
        syscall4(
            nr::MKNODAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            u64::from(mode),
            dev,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Permissions
// ─────────────────────────────────────────────────────────────────────────

/// Modifie les permissions d'un fichier.
pub fn fchmodat(dirfd: DirFd<'_>, path: &CStr, mode: Mode, flags: i32) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: path est un CStr nul-terminé valide.
    let ret = unsafe {
        syscall4(
            nr::FCHMODAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            u64::from(mode),
            i32_to_u64(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie le propriétaire d'un fichier.
pub fn fchownat(
    dirfd: DirFd<'_>,
    path: &CStr,
    uid: u32,
    gid: u32,
    flags: i32,
) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: path est un CStr nul-terminé valide.
    let ret = unsafe {
        syscall5(
            nr::FCHOWNAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            u64::from(uid),
            u64::from(gid),
            i32_to_u64(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie les horodatages d'accès et de modification d'un fichier.
///
/// # Parameters
///
/// - `atime` : nouvel horodatage d'accès (`Now`, `Omit`, ou valeur).
/// - `mtime` : nouvel horodatage de modification.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::utimensat;
/// use air_sys_types::fs::{DirFd, UtimeValue};
///
/// utimensat(DirFd::Cwd, c"./file", UtimeValue::Now, UtimeValue::Omit, 0)
///     .expect("utimensat");
/// ```
pub fn utimensat(
    dirfd: DirFd<'_>,
    path: &CStr,
    atime: UtimeValue,
    mtime: UtimeValue,
    flags: i32,
) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // struct timespec : [i64; 2] = [tv_sec, tv_nsec]
    let atime_ts = utimevalue_to_kernel(atime);
    let mtime_ts = utimevalue_to_kernel(mtime);
    // Paire consécutive en mémoire, comme struct timespec[2].
    let times: [[i64; 2]; 2] = [atime_ts, mtime_ts];

    // SAFETY:
    // - path est un CStr nul-terminé valide.
    // - times est un tableau de deux struct timespec (2×[i64;2]) sur la pile, valide.
    // - utimensat(2) lit les deux entrées de times pour mettre à jour les horodatages.
    let ret = unsafe {
        syscall4(
            nr::UTIMENSAT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            times.as_ptr() as u64,
            i32_to_u64(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie les permissions d'un fichier **par descripteur** (`fchmod(2)`) —
/// **descellement additif [ADR-085](../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md)**
/// pour la face libc (`int fchmod(int, mode_t)`). Complète `fchmodat` (par chemin).
pub fn fchmod(fd: BorrowedFd<'_>, mode: Mode) -> Result<(), Errno> {
    // SAFETY: fchmod(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall2(nr::FCHMOD, fd_to_u64(fd.as_raw_fd()), u64::from(mode)) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie le propriétaire d'un fichier **par descripteur** (`fchown(2)`) —
/// descellement additif [ADR-085] pour la face libc (`int fchown(int, uid_t, gid_t)`).
/// Complète `fchownat` (par chemin).
///
/// [ADR-085]: ../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md
pub fn fchown(fd: BorrowedFd<'_>, uid: u32, gid: u32) -> Result<(), Errno> {
    // SAFETY: fchown(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCHOWN,
            fd_to_u64(fd.as_raw_fd()),
            u64::from(uid),
            u64::from(gid),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie les horodatages d'accès/modification d'un fichier **par descripteur**
/// (`utimensat(fd, NULL, …)`) — descellement additif [ADR-085] pour la face libc
/// (`int futimens(int, const struct timespec[2])`). Complète `utimensat` (dont la
/// variante couche 0 exige un `&CStr`, jamais `NULL`).
///
/// [ADR-085]: ../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md
pub fn futimens(fd: BorrowedFd<'_>, atime: UtimeValue, mtime: UtimeValue) -> Result<(), Errno> {
    // struct timespec[2] : [tv_sec, tv_nsec] × 2, consécutifs en mémoire.
    let times: [[i64; 2]; 2] = [utimevalue_to_kernel(atime), utimevalue_to_kernel(mtime)];

    // SAFETY:
    // - pointeur de chemin **NULL** (0) : `utimensat` opère alors sur le fd (`dirfd`
    //   emprunté ci-dessus), sémantique exacte de `futimens(3)`.
    // - times est un tableau de deux struct timespec sur la pile, valide et lu par le
    //   kernel pour poser les horodatages.
    let ret = unsafe {
        syscall4(
            nr::UTIMENSAT,
            fd_to_u64(fd.as_raw_fd()),
            0, // path == NULL ⇒ opère sur le descripteur
            times.as_ptr() as u64,
            0, // flags
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Transfert **zéro-copie** kernel de `count` octets de `in_fd` vers `out_fd`
/// (`sendfile(2)`) — descellement additif [ADR-085] pour la face libc. `offset` :
/// `Some` = position de départ **explicite** (que le kernel met à jour ; la position de
/// `in_fd` reste inchangée) ; `None` = position **courante** de `in_fd` (que le kernel
/// avance). Rend le nombre d'octets **effectivement** transférés (`0` = fin de `in_fd`,
/// transfert possiblement partiel — l'appelant boucle).
///
/// [ADR-085]: ../../../docs/adrs/ADR-085-descellement-couche0-cumule-libc-std-fr.md
pub fn sendfile(
    out_fd: BorrowedFd<'_>,
    in_fd: BorrowedFd<'_>,
    offset: Option<&mut u64>,
    count: usize,
) -> Result<usize, Errno> {
    // `Some` ⇒ pointeur vers l'offset (le kernel le lit **et** y réécrit la nouvelle
    // position) ; `None` ⇒ `NULL` (le kernel utilise/avance la position de `in_fd`).
    let offset_ptr = match offset {
        Some(value) => core::ptr::from_mut(value) as u64,
        None => 0,
    };
    // SAFETY:
    // - `out_fd`/`in_fd` sont des `BorrowedFd` valides le temps de l'appel.
    // - `offset_ptr` est nul, **ou** pointe un `u64` valide lu/écrit par le kernel.
    // - `sendfile(2)` ne touche aucune autre mémoire utilisateur.
    let ret = unsafe {
        syscall4(
            nr::SENDFILE,
            fd_to_u64(out_fd.as_raw_fd()),
            fd_to_u64(in_fd.as_raw_fd()),
            offset_ptr,
            count as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // `ret >= 0` : octets transférés (au plus `count <= usize::MAX`).
    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

fn utimevalue_to_kernel(v: UtimeValue) -> [i64; 2] {
    match v {
        UtimeValue::Now => [0, UTIME_NOW],
        UtimeValue::Omit => [0, UTIME_OMIT],
        UtimeValue::Time(ts) => [ts.seconds, i64::from(ts.nanoseconds)],
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Opérations spéciales
// ─────────────────────────────────────────────────────────────────────────

/// Tronque un fichier à une longueur donnée via un FD.
///
/// # Errors
///
/// - `EINVAL` : longueur négative.
/// - `EBADF` : FD invalide ou non ouvert en écriture.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::ftruncate;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// ftruncate(fd, 4096).expect("ftruncate");
/// # }
/// ```
pub fn ftruncate(fd: BorrowedFd<'_>, length: i64) -> Result<(), Errno> {
    // SAFETY: ftruncate(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall2(nr::FTRUNCATE, fd_to_u64(fd.as_raw_fd()), i64_to_u64(length)) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Tronque un fichier via son chemin.
///
/// Note: utilise `openat` + `ftruncate` car `truncate(2)` est un syscall
/// legacy non exposé directement (chemin basé). Préférer `ftruncate`.
pub fn truncate(dirfd: DirFd<'_>, path: &CStr, length: i64) -> Result<(), Errno> {
    use air_sys_types::fs::OpenFlags;
    let fd = openat(dirfd, path, OpenFlags::WRONLY, 0)?;
    // SAFETY: fd vient d'être ouvert avec succès, BorrowedFd depuis OwnedFd.
    let borrowed = unsafe { BorrowedFd::borrow_raw(fd.as_raw_fd()) };
    let result = ftruncate(borrowed, length);
    drop(fd);
    result
}

/// Force l'écriture des données et métadonnées d'un FD sur le support.
///
/// # Errors
///
/// - `EIO` : erreur d'E/S lors de la synchronisation.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::fsync;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// fsync(fd).expect("fsync");
/// # }
/// ```
pub fn fsync(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: fsync(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall1(nr::FSYNC, fd_to_u64(fd.as_raw_fd())) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Force l'écriture des données d'un FD (sans les métadonnées non essentielles).
pub fn fdatasync(fd: BorrowedFd<'_>) -> Result<(), Errno> {
    // SAFETY: fdatasync(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall1(nr::FDATASYNC, fd_to_u64(fd.as_raw_fd())) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Pré-alloue ou manipule l'espace d'un fichier.
///
/// # Errors
///
/// - `EOPNOTSUPP` : opération non supportée par le filesystem.
/// - `ENOSPC` : espace insuffisant.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::fallocate;
/// use air_sys_types::fs::FallocateMode;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// // Pré-allouer 1 Mo sans modifier la taille visible
/// fallocate(fd, FallocateMode::KEEP_SIZE, 0, 1_048_576).expect("fallocate");
/// # }
/// ```
pub fn fallocate(
    fd: BorrowedFd<'_>,
    mode: FallocateMode,
    offset: i64,
    length: i64,
) -> Result<(), Errno> {
    // SAFETY: fallocate(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall4(
            nr::FALLOCATE,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(mode.bits()),
            i64_to_u64(offset),
            i64_to_u64(length),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Copie zero-copy entre deux fichiers (même FS si possible).
///
/// Wrappeur de `copy_file_range(2)` (Linux 4.5+).
///
/// # Errors
///
/// - `EINVAL` : paramètres invalides.
/// - `EXDEV` : FS différents et copy_file_range inter-FS non supporté.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::copy_file_range;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(src: BorrowedFd<'_>, dst: BorrowedFd<'_>) {
/// let n = copy_file_range(src, None, dst, None, 4096, 0)
///     .expect("copy_file_range");
/// # }
/// ```
pub fn copy_file_range(
    fd_in: BorrowedFd<'_>,
    offset_in: Option<&mut u64>,
    fd_out: BorrowedFd<'_>,
    offset_out: Option<&mut u64>,
    length: usize,
    flags: u32,
) -> Result<usize, Errno> {
    let off_in_ptr: u64 = match offset_in {
        Some(p) => p as *mut u64 as u64,
        None => 0,
    };
    let off_out_ptr: u64 = match offset_out {
        Some(p) => p as *mut u64 as u64,
        None => 0,
    };

    // SAFETY:
    // - off_in_ptr et off_out_ptr sont soit NULL (0) soit des pointeurs sur u64 valides.
    // - copy_file_range lit/écrit éventuellement les offsets pointés.
    // - fd_in et fd_out sont des BorrowedFd valides.
    let ret = unsafe {
        syscall6(
            nr::COPY_FILE_RANGE,
            fd_to_u64(fd_in.as_raw_fd()),
            off_in_ptr,
            fd_to_u64(fd_out.as_raw_fd()),
            off_out_ptr,
            length as u64,
            u64::from(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Pose ou lève un verrou BSD sur un fichier (`flock(2)`).
pub fn flock(fd: BorrowedFd<'_>, operation: i32) -> Result<(), Errno> {
    // SAFETY: flock(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall2(nr::FLOCK, fd_to_u64(fd.as_raw_fd()), i32_to_u64(operation)) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit les statistiques du filesystem identifié par un chemin.
pub fn statfs(path: &CStr) -> Result<StatFsResult, Errno> {
    let mut kfs = KernelStatfs {
        f_type: 0,
        f_bsize: 0,
        f_blocks: 0,
        f_bfree: 0,
        f_bavail: 0,
        f_files: 0,
        f_ffree: 0,
        f_fsid: [0; 2],
        f_namelen: 0,
        f_frsize: 0,
        f_flags: 0,
        f_spare: [0; 4],
    };

    // SAFETY:
    // - path est un CStr nul-terminé valide.
    // - &mut kfs pointe sur KernelStatfs local (120 octets), correctement aligné.
    let ret = unsafe {
        syscall2(
            nr::STATFS,
            path.as_ptr() as u64,
            &mut kfs as *mut KernelStatfs as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    Ok(kernel_statfs_to_result(&kfs))
}

/// Lit les statistiques du filesystem contenant un FD.
pub fn fstatfs(fd: BorrowedFd<'_>) -> Result<StatFsResult, Errno> {
    let mut kfs = KernelStatfs {
        f_type: 0,
        f_bsize: 0,
        f_blocks: 0,
        f_bfree: 0,
        f_bavail: 0,
        f_files: 0,
        f_ffree: 0,
        f_fsid: [0; 2],
        f_namelen: 0,
        f_frsize: 0,
        f_flags: 0,
        f_spare: [0; 4],
    };

    // SAFETY:
    // - fd est un BorrowedFd valide.
    // - &mut kfs pointe sur KernelStatfs local (120 octets), correctement aligné.
    let ret = unsafe {
        syscall2(
            nr::FSTATFS,
            fd_to_u64(fd.as_raw_fd()),
            &mut kfs as *mut KernelStatfs as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    Ok(kernel_statfs_to_result(&kfs))
}

fn kernel_statfs_to_result(kfs: &KernelStatfs) -> StatFsResult {
    StatFsResult {
        f_type: FsType(kfs.f_type),
        f_bsize: kfs.f_bsize,
        f_frsize: kfs.f_frsize,
        f_blocks: kfs.f_blocks,
        f_bfree: kfs.f_bfree,
        f_bavail: kfs.f_bavail,
        f_files: kfs.f_files,
        f_ffree: kfs.f_ffree,
        f_fsid: kfs.f_fsid,
        f_namelen: kfs.f_namelen,
        f_flags: kfs.f_flags,
    }
}

/// Synchronise une plage d'un fichier sur le disque.
///
/// Wrappeur de `sync_file_range(2)` (Linux 2.6.17+).
///
/// # Errors
///
/// - `EBADF` : FD invalide.
/// - `EINVAL` : paramètres invalides.
pub fn sync_file_range(
    fd: BorrowedFd<'_>,
    offset: i64,
    nbytes: u64,
    flags: u32,
) -> Result<(), Errno> {
    // SAFETY: sync_file_range(2) ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall4(
            nr::SYNC_FILE_RANGE,
            fd_to_u64(fd.as_raw_fd()),
            i64_to_u64(offset),
            nbytes,
            u64::from(flags),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// fcntl (opérations individuelles — ADR-021 convention 3)
// ─────────────────────────────────────────────────────────────────────────

/// Duplique un FD en allouant le plus petit numéro ≥ `min_fd` (`F_DUPFD_CLOEXEC`).
///
/// # Errors
///
/// - `EMFILE` : quota FD du processus atteint.
/// - `EBADF` : FD invalide.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::dup_fd;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let new_fd = dup_fd(fd, 0).expect("dup_fd");
/// # }
/// ```
pub fn dup_fd(fd: BorrowedFd<'_>, min_fd: RawFd) -> Result<OwnedFd, Errno> {
    // SAFETY: fcntl F_DUPFD_CLOEXEC ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_DUPFD_CLOEXEC),
            fd_to_u64(min_fd),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // SAFETY: ret est un fd valide retourné par le kernel.
    #[allow(clippy::cast_possible_truncation)]
    Ok(unsafe { OwnedFd::from_raw_fd(ret as i32) })
}

/// Lit les flags du descripteur (`F_GETFD`).
pub fn get_fd_flags(fd: BorrowedFd<'_>) -> Result<FdFlags, Errno> {
    // SAFETY: F_GETFD ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall3(nr::FCNTL, fd_to_u64(fd.as_raw_fd()), i32_to_u64(F_GETFD), 0) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_possible_truncation)]
    Ok(FdFlags::from_bits_truncate(ret as i32))
}

/// Modifie les flags du descripteur (`F_SETFD`).
pub fn set_fd_flags(fd: BorrowedFd<'_>, flags: FdFlags) -> Result<(), Errno> {
    // SAFETY: F_SETFD ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_SETFD),
            i32_to_u64(flags.bits()),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit les flags de statut du fichier (`F_GETFL`).
pub fn get_status_flags(fd: BorrowedFd<'_>) -> Result<StatusFlags, Errno> {
    // SAFETY: F_GETFL ne touche aucune mémoire utilisateur.
    let ret = unsafe { syscall3(nr::FCNTL, fd_to_u64(fd.as_raw_fd()), i32_to_u64(F_GETFL), 0) };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_possible_truncation)]
    Ok(StatusFlags::from_bits_truncate(ret as i32))
}

/// Modifie les flags de statut du fichier (`F_SETFL`).
pub fn set_status_flags(fd: BorrowedFd<'_>, flags: StatusFlags) -> Result<(), Errno> {
    // SAFETY: F_SETFL ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_SETFL),
            i32_to_u64(flags.bits()),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Modifie la capacité d'un pipe (`F_SETPIPE_SZ`).
///
/// Retourne la nouvelle taille effective (peut être supérieure à `size`).
pub fn set_pipe_size(fd: BorrowedFd<'_>, size: usize) -> Result<usize, Errno> {
    // SAFETY: F_SETPIPE_SZ ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_SETPIPE_SZ),
            size as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Lit la capacité d'un pipe (`F_GETPIPE_SZ`).
pub fn get_pipe_size(fd: BorrowedFd<'_>) -> Result<usize, Errno> {
    // SAFETY: F_GETPIPE_SZ ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_GETPIPE_SZ),
            0,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_sign_loss)]
    ret_to_usize_ok(ret)
}

/// Tente d'acquérir un verrou POSIX non-bloquant (`F_SETLK`).
///
/// Retourne `true` si le verrou a été acquis, `false` si bloqué.
pub fn try_lock(fd: BorrowedFd<'_>, lock: &FileLock) -> Result<bool, Errno> {
    let kflock = file_lock_to_kernel(lock);

    // SAFETY:
    // - kflock est une struct KernelFlock valide sur la pile.
    // - fcntl F_SETLK lit la struct à l'adresse fournie.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_SETLK),
            &kflock as *const KernelFlock as u64,
        )
    };

    if ret < 0 {
        let err = errno_from_negative_syscall_ret(ret);
        // EACCES ou EAGAIN signifient que le verrou est tenu par un autre.
        if err == Errno::EACCES || err == Errno::EAGAIN {
            return Ok(false);
        }
        return Err(err);
    }
    Ok(true)
}

/// Acquiert un verrou POSIX en mode bloquant (`F_SETLKW`).
///
/// # Errors
///
/// - `EINTR` : interrompu par un signal (pas de retry automatique).
/// - `EDEADLK` : deadlock détecté.
pub fn lock(fd: BorrowedFd<'_>, lock: &FileLock) -> Result<(), Errno> {
    let kflock = file_lock_to_kernel(lock);

    // SAFETY:
    // - kflock est une struct KernelFlock valide sur la pile.
    // - fcntl F_SETLKW lit la struct à l'adresse fournie.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_SETLKW),
            &kflock as *const KernelFlock as u64,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

fn file_lock_to_kernel(lock: &FileLock) -> KernelFlock {
    KernelFlock {
        l_type: lock.lock_type as i16,
        l_whence: lock.whence as i16,
        _pad: 0,
        l_start: lock.start,
        l_len: lock.length,
        l_pid: lock.pid,
        _pad2: 0,
    }
}

/// Ajoute des scellements à un `memfd` (`F_ADD_SEALS`).
pub fn add_seals(fd: BorrowedFd<'_>, seals: Seals) -> Result<(), Errno> {
    // SAFETY: F_ADD_SEALS ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_ADD_SEALS),
            u64::from(seals.bits()),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit les scellements actifs d'un `memfd` (`F_GET_SEALS`).
pub fn get_seals(fd: BorrowedFd<'_>) -> Result<Seals, Errno> {
    // SAFETY: F_GET_SEALS ne touche aucune mémoire utilisateur.
    let ret = unsafe {
        syscall3(
            nr::FCNTL,
            fd_to_u64(fd.as_raw_fd()),
            i32_to_u64(F_GET_SEALS),
            0,
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(Seals::from_bits_truncate(ret as u32))
}

// ─────────────────────────────────────────────────────────────────────────
// Handles persistants
// ─────────────────────────────────────────────────────────────────────────

/// Obtient un handle persistant pour un fichier.
///
/// Wrappeur de `name_to_handle_at(2)` (Linux 2.6.39+). Le handle
/// retourné identifie le fichier même après renommage.
///
/// # Errors
///
/// - `EOPNOTSUPP` : filesystem ne supporte pas les handles.
/// - `ENOENT` : fichier inexistant.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::name_to_handle_at;
/// use air_sys_types::fs::{DirFd, NameToHandleFlags};
///
/// let handle = name_to_handle_at(DirFd::Cwd, c"./data.bin", NameToHandleFlags::empty())
///     .expect("name_to_handle_at");
/// ```
pub fn name_to_handle_at(
    dirfd: DirFd<'_>,
    path: &CStr,
    flags: NameToHandleFlags,
) -> Result<FileHandle, Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);
    let mut khandle = KernelFileHandle {
        handle_bytes: 128,
        handle_type: 0,
        f_handle: [0u8; 128],
    };
    let mut mount_id: i32 = 0;

    // SAFETY:
    // - path est un CStr nul-terminé valide.
    // - khandle est initialisé avec handle_bytes=128 (capacité maximale).
    // - &mut mount_id est un i32 local valide.
    // - Le kernel écrit le type et les octets du handle si handle_bytes suffit.
    let ret = unsafe {
        syscall5(
            nr::NAME_TO_HANDLE_AT,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            &mut khandle as *mut KernelFileHandle as u64,
            &mut mount_id as *mut i32 as u64,
            i32_to_u64(flags.bits()),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // handle_bytes est u32, la conversion en usize est exacte sur les cibles 64 bits Air.
    #[allow(clippy::cast_lossless)]
    let nbytes = khandle.handle_bytes as usize;
    let data = khandle
        .f_handle
        .get(..nbytes.min(128))
        .unwrap_or(&khandle.f_handle[..])
        .to_vec();

    Ok(FileHandle {
        handle_type: khandle.handle_type,
        handle_bytes: data,
        mount_id,
    })
}

/// Ouvre un fichier depuis un handle persistant.
///
/// # Parameters
///
/// - `mount_fd` : FD d'un fichier sur le même système de fichiers.
/// - `handle` : handle retourné par [`name_to_handle_at`].
/// - `flags` : flags d'ouverture.
///
/// # Errors
///
/// - `ESTALE` : handle invalide (fichier supprimé ou FS remonté).
/// - `EPERM` : `CAP_DAC_READ_SEARCH` requis.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::open_by_handle_at;
/// use air_sys_types::fs::{FileHandle, OpenFlags};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(mount_fd: BorrowedFd<'_>, handle: &FileHandle) {
/// let fd = open_by_handle_at(mount_fd, handle, OpenFlags::RDONLY)
///     .expect("open_by_handle_at");
/// # }
/// ```
pub fn open_by_handle_at(
    mount_fd: BorrowedFd<'_>,
    handle: &FileHandle,
    flags: OpenFlags,
) -> Result<OwnedFd, Errno> {
    // Reconstruit une KernelFileHandle depuis le FileHandle Air.
    let nbytes = handle.handle_bytes.len().min(128);
    // nbytes <= 128, donc la troncature usize → u32 est exacte.
    #[allow(clippy::cast_possible_truncation)]
    let nbytes_u32 = nbytes as u32;
    let mut khandle = KernelFileHandle {
        handle_bytes: nbytes_u32,
        handle_type: handle.handle_type,
        f_handle: [0u8; 128],
    };
    // SAFETY: nbytes <= 128, donc la copie ne déborde pas.
    khandle.f_handle[..nbytes].copy_from_slice(&handle.handle_bytes[..nbytes]);

    let raw_flags = flags.bits() | O_CLOEXEC;
    #[allow(clippy::cast_possible_truncation)]
    let raw_flags_i32 = raw_flags as i32;

    // SAFETY:
    // - khandle est un KernelFileHandle valide sur la pile.
    // - mount_fd est un BorrowedFd valide.
    // - Le kernel lit les handle_bytes octets de f_handle.
    let ret = unsafe {
        syscall3(
            nr::OPEN_BY_HANDLE_AT,
            fd_to_u64(mount_fd.as_raw_fd()),
            &khandle as *const KernelFileHandle as u64,
            i32_to_u64(raw_flags_i32),
        )
    };

    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // SAFETY: ret est un fd valide retourné par le kernel après succès.
    #[allow(clippy::cast_possible_truncation)]
    Ok(unsafe { OwnedFd::from_raw_fd(ret as i32) })
}

// ─────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────

#[cfg(all(test, target_os = "linux"))]
mod tests {
    use super::*;
    use air_sys_types::fs::{
        AccessFlags, AccessMode, DirFd, FallocateMode, FdFlags, FileLock, FsType, LockType,
        NameToHandleFlags, OpenFlags, RenameFlags, Seals, SeekWhence, StatusFlags, StatxFlags,
        StatxMask, StatxTimestamp, UtimeValue,
    };

    // errno standard non exposés par l'API publique (gelée). Valeurs
    // asm-generic/errno.h, identiques sur x86_64 et aarch64.
    const ENOTDIR: Errno = Errno::try_from_raw(20).unwrap();
    const EOPNOTSUPP: Errno = Errno::try_from_raw(95).unwrap();

    /// Un `BorrowedFd` jamais valide, pour provoquer `EBADF` de façon
    /// déterministe. `i32::MAX` dépasse toute limite de fd ouvrable : le
    /// kernel rejette systématiquement, sans course de réutilisation
    /// (contrairement à un fd réel fermé). `-1` est exclu car c'est la
    /// valeur-niche de `BorrowedFd` (`borrow_raw(-1)` panique `fd != -1`).
    fn invalid_fd() -> BorrowedFd<'static> {
        // SAFETY: aucune ressource n'est lue/écrite via ce fd ; il n'est
        // transmis au kernel que pour être rejeté avec `EBADF`.
        unsafe { BorrowedFd::borrow_raw(i32::MAX) }
    }
    use air_sys_types::fd::AsFd;

    // ── Helpers ──────────────────────────────────────────────────────────

    /// Ouvre un memfd anonyme pour les tests.
    fn open_memfd() -> OwnedFd {
        // memfd_create = x86_64:319, aarch64:279
        #[cfg(target_arch = "x86_64")]
        let nr_memfd: i64 = 319;
        #[cfg(target_arch = "aarch64")]
        let nr_memfd: i64 = 279;

        let name = c"test";
        // MFD_CLOEXEC = 1
        // SAFETY: memfd_create ne touche que le pointeur nom nul-terminé.
        let ret = unsafe { syscall2(nr_memfd, name.as_ptr() as u64, 1) };
        assert!(ret >= 0, "memfd_create failed: {ret}");
        #[allow(clippy::cast_possible_truncation)]
        unsafe {
            OwnedFd::from_raw_fd(ret as i32)
        }
    }

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

    #[test]
    fn openat_opens_existing_file() {
        let fd = openat(DirFd::Cwd, c"/proc/self/status", OpenFlags::RDONLY, 0);
        assert!(fd.is_ok(), "openat /proc/self/status: {:?}", fd);
    }

    #[test]
    fn openat_enoent_on_missing() {
        let result = openat(
            DirFd::Cwd,
            c"/nonexistent_air_test_file",
            OpenFlags::RDONLY,
            0,
        );
        assert_eq!(result.unwrap_err(), Errno::ENOENT);
    }

    #[test]
    fn openat2_opens_existing_file() {
        use air_sys_types::fs::{OpenHow, ResolveFlags};
        let how = OpenHow {
            flags: OpenFlags::RDONLY,
            mode: 0,
            resolve: ResolveFlags::empty(),
        };
        let fd = openat2(DirFd::Cwd, c"/proc/self/status", how);
        assert!(fd.is_ok(), "openat2: {:?}", fd);
    }

    // ── read / write ─────────────────────────────────────────────────────

    #[test]
    fn read_write_roundtrip() {
        let fd = open_memfd();
        let data = b"hello air";
        let n = write(fd.as_fd(), data).expect("write");
        assert_eq!(n, data.len());

        lseek(fd.as_fd(), 0, SeekWhence::Set).expect("lseek");

        let mut buffer = [0u8; 64];
        let n2 = read(fd.as_fd(), &mut buffer).expect("read");
        assert_eq!(n2, data.len());
        assert_eq!(&buffer[..n2], data);
    }

    // ── pread / pwrite ───────────────────────────────────────────────────

    #[test]
    fn pread_pwrite_roundtrip() {
        let fd = open_memfd();
        ftruncate(fd.as_fd(), 32).expect("ftruncate");

        let n = pwrite(fd.as_fd(), b"abcd", 4).expect("pwrite");
        assert_eq!(n, 4);

        let mut buffer = [0u8; 4];
        let n2 = pread(fd.as_fd(), &mut buffer, 4).expect("pread");
        assert_eq!(n2, 4);
        assert_eq!(&buffer, b"abcd");
    }

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

    #[test]
    fn lseek_set_and_end() {
        let fd = open_memfd();
        write(fd.as_fd(), b"0123456789").expect("write");

        let pos = lseek(fd.as_fd(), 0, SeekWhence::End).expect("lseek end");
        assert_eq!(pos, 10);

        let pos2 = lseek(fd.as_fd(), 3, SeekWhence::Set).expect("lseek set");
        assert_eq!(pos2, 3);
    }

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

    #[test]
    fn statx_on_tmp() {
        let result =
            statx(DirFd::Cwd, c"/tmp", StatxFlags::empty(), StatxMask::ALL).expect("statx /tmp");
        assert!(result.mask.contains(StatxMask::TYPE));
    }

    // ── mkdirat / unlinkat ───────────────────────────────────────────────

    #[test]
    fn mkdirat_unlinkat_roundtrip() {
        // AT_REMOVEDIR = 0x200
        const AT_REMOVEDIR: i32 = 0x200;
        let dir = c"/tmp/air_fs_test_dir_mkdirat";
        let _ = unlinkat(DirFd::Cwd, dir, AT_REMOVEDIR); // cleanup préventif
        mkdirat(DirFd::Cwd, dir, 0o700).expect("mkdirat");
        unlinkat(DirFd::Cwd, dir, AT_REMOVEDIR).expect("unlinkat rmdir");
    }

    // ── getdents64 ───────────────────────────────────────────────────────

    #[test]
    fn getdents64_lists_entries() {
        let fd = openat(
            DirFd::Cwd,
            c"/tmp",
            OpenFlags::RDONLY | OpenFlags::DIRECTORY,
            0,
        )
        .expect("openat /tmp");

        let mut buffer = vec![0u8; 4096];
        let n = getdents64(fd.as_fd(), &mut buffer).expect("getdents64");
        assert!(n > 0, "getdents64 returned 0 bytes");

        let entries: Vec<_> = parse_dirents(&buffer[..n]).collect();
        assert!(!entries.is_empty(), "pas d'entrées dans /tmp");

        // Vérifie que "." et ".." sont présents (noms = octets bruts).
        let has_dot = entries.iter().any(|e| e.name == b".");
        let has_dotdot = entries.iter().any(|e| e.name == b"..");
        assert!(has_dot, ". absent");
        assert!(has_dotdot, ".. absent");
    }

    // ── ftruncate ────────────────────────────────────────────────────────

    #[test]
    fn ftruncate_sets_size() {
        let fd = open_memfd();
        ftruncate(fd.as_fd(), 1024).expect("ftruncate");

        let pos = lseek(fd.as_fd(), 0, SeekWhence::End).expect("lseek end");
        assert_eq!(pos, 1024);
    }

    // ── fsync ────────────────────────────────────────────────────────────

    #[test]
    fn fsync_on_memfd() {
        let fd = open_memfd();
        write(fd.as_fd(), b"data").expect("write");
        // Sur memfd fsync est un no-op mais ne doit pas échouer.
        fsync(fd.as_fd()).expect("fsync");
    }

    // ── statfs ───────────────────────────────────────────────────────────

    #[test]
    fn statfs_root() {
        let result = statfs(c"/").expect("statfs /");
        assert!(result.f_bsize > 0, "f_bsize nul");
        assert!(result.f_blocks > 0, "f_blocks nul");
    }

    // ── fstatfs ──────────────────────────────────────────────────────────

    #[test]
    fn fstatfs_on_proc_fd() {
        let fd = openat(DirFd::Cwd, c"/proc/self/status", OpenFlags::RDONLY, 0).expect("openat");
        let result = fstatfs(fd.as_fd()).expect("fstatfs");
        // /proc est monté en procfs (0x9FA0)
        assert_eq!(result.f_type, FsType::PROC);
    }

    // ── copy_file_range ──────────────────────────────────────────────────

    #[test]
    fn copy_file_range_between_memfds() {
        let src = open_memfd();
        write(src.as_fd(), b"hello world").expect("write src");
        lseek(src.as_fd(), 0, SeekWhence::Set).expect("lseek src");

        let dst = open_memfd();

        let n =
            copy_file_range(src.as_fd(), None, dst.as_fd(), None, 11, 0).expect("copy_file_range");
        assert_eq!(n, 11);

        lseek(dst.as_fd(), 0, SeekWhence::Set).expect("lseek dst");
        let mut buffer = [0u8; 16];
        let n2 = read(dst.as_fd(), &mut buffer).expect("read dst");
        assert_eq!(&buffer[..n2], b"hello world");
    }

    // ── dup_fd ───────────────────────────────────────────────────────────

    #[test]
    fn dup_fd_creates_new_fd() {
        let fd = open_memfd();
        let fd2 = dup_fd(fd.as_fd(), 0).expect("dup_fd");
        // Les deux descripteurs sont distincts mais pointent sur le même fichier.
        assert_ne!(fd.as_raw_fd(), fd2.as_raw_fd());
        write(fd.as_fd(), b"dup").expect("write original");
        lseek(fd2.as_fd(), 0, SeekWhence::Set).expect("lseek dup");
        let mut buffer = [0u8; 8];
        let n = read(fd2.as_fd(), &mut buffer).expect("read dup");
        assert_eq!(&buffer[..n], b"dup");
    }

    // ── Helper : pipe anonyme ────────────────────────────────────────────

    fn make_pipe() -> (OwnedFd, OwnedFd) {
        let mut fds = [0i32; 2];
        #[cfg(target_arch = "x86_64")]
        let nr_pipe2: i64 = 293;
        #[cfg(target_arch = "aarch64")]
        let nr_pipe2: i64 = 59;
        // SAFETY: pipe2 avec O_CLOEXEC = 0o2_000_000.
        let ret = unsafe { syscall2(nr_pipe2, fds.as_mut_ptr() as u64, 0o2_000_000) };
        assert!(ret >= 0, "pipe2 failed: {ret}");
        // SAFETY: les fds ont été remplis par pipe2.
        let r = unsafe { OwnedFd::from_raw_fd(fds[0]) };
        let w = unsafe { OwnedFd::from_raw_fd(fds[1]) };
        (r, w)
    }

    // ── DirFd::Fd branch ─────────────────────────────────────────────────

    #[test]
    fn dirfd_fd_branch_enoent() {
        let dir = openat(
            DirFd::Cwd,
            c"/tmp",
            OpenFlags::RDONLY | OpenFlags::DIRECTORY,
            0,
        )
        .expect("openat /tmp");
        let result = openat(
            DirFd::Fd(dir.as_fd()),
            c"air_test_no_such_file_dir_fd_42xy",
            OpenFlags::RDONLY,
            0,
        );
        assert_eq!(result.unwrap_err(), Errno::ENOENT);
    }

    // ── close ────────────────────────────────────────────────────────────

    #[test]
    fn close_valid_fd_succeeds() {
        let fd = open_memfd();
        close(fd).expect("close");
    }

    // ── read / write error paths ─────────────────────────────────────────

    #[test]
    fn read_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        let mut buffer = [0u8; 4];
        assert_eq!(read(invalid, &mut buffer).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn write_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        assert_eq!(write(invalid, b"data").unwrap_err(), Errno::EBADF);
    }

    // ── pread / pwrite error paths ───────────────────────────────────────

    #[test]
    fn pread_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        let mut buffer = [0u8; 4];
        assert_eq!(pread(invalid, &mut buffer, 0).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn pwrite_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        assert_eq!(pwrite(invalid, b"data", 0).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn preadv_ebadf_on_invalid_fd() {
        use air_sys_types::net::IoSliceMut;
        let invalid = invalid_fd();
        let mut buffer = [0u8; 4];
        let mut iov = [IoSliceMut::new(&mut buffer)];
        assert_eq!(preadv(invalid, &mut iov, 0).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn pwritev_ebadf_on_invalid_fd() {
        use air_sys_types::net::IoSlice;
        let invalid = invalid_fd();
        let data = *b"data";
        let iov = [IoSlice::new(&data)];
        assert_eq!(pwritev(invalid, &iov, 0).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn fallocate_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        let err = fallocate(invalid, FallocateMode::empty(), 0, 4).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn copy_file_range_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        let err = copy_file_range(invalid, None, invalid, None, 4, 0).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn sync_file_range_ebadf_on_invalid_fd() {
        let invalid = invalid_fd();
        let err = sync_file_range(invalid, 0, 0, 0).unwrap_err();
        assert_eq!(err, Errno::EBADF);
    }

    #[test]
    fn symlinkat_eexist_when_link_path_already_exists() {
        // Couvre la branche d'erreur (`ret < 0`) de `symlinkat` : créer un
        // lien dont le `link_path` existe déjà (ici `.` dans le cwd) → EEXIST.
        let err = symlinkat(c"target", DirFd::Cwd, c".").unwrap_err();
        assert_eq!(err, Errno::EEXIST);
    }

    // ── readv / writev ───────────────────────────────────────────────────

    #[test]
    fn readv_writev_roundtrip() {
        use air_sys_types::net::{IoSlice, IoSliceMut};
        let fd = open_memfd();
        let a = b"hello";
        let b_data = b" world";
        let iov_w = [IoSlice::new(a), IoSlice::new(b_data)];
        let n = writev(fd.as_fd(), &iov_w).expect("writev");
        assert_eq!(n, 11);
        lseek(fd.as_fd(), 0, SeekWhence::Set).expect("lseek");
        let mut buf1 = [0u8; 5];
        let mut buf2 = [0u8; 6];
        let mut iov_r = [IoSliceMut::new(&mut buf1), IoSliceMut::new(&mut buf2)];
        let n2 = readv(fd.as_fd(), &mut iov_r).expect("readv");
        assert_eq!(n2, 11);
        assert_eq!(&buf1, b"hello");
        assert_eq!(&buf2, b" world");
    }

    #[test]
    fn readv_ebadf() {
        use air_sys_types::net::IoSliceMut;
        let invalid = invalid_fd();
        let mut buffer = [0u8; 4];
        let mut iov = [IoSliceMut::new(&mut buffer)];
        assert_eq!(readv(invalid, &mut iov).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn writev_ebadf() {
        use air_sys_types::net::IoSlice;
        let invalid = invalid_fd();
        let iov = [IoSlice::new(b"data")];
        assert_eq!(writev(invalid, &iov).unwrap_err(), Errno::EBADF);
    }

    // ── preadv / pwritev ─────────────────────────────────────────────────

    #[test]
    fn preadv_pwritev_roundtrip() {
        use air_sys_types::net::{IoSlice, IoSliceMut};
        let fd = open_memfd();
        ftruncate(fd.as_fd(), 16).expect("ftruncate");
        let data = b"abcdef";
        let iov_w = [IoSlice::new(data)];
        let n = pwritev(fd.as_fd(), &iov_w, 2).expect("pwritev");
        assert_eq!(n, 6);
        let mut out = [0u8; 6];
        let mut iov_r = [IoSliceMut::new(&mut out)];
        let n2 = preadv(fd.as_fd(), &mut iov_r, 2).expect("preadv");
        assert_eq!(n2, 6);
        assert_eq!(&out, b"abcdef");
    }

    // ── lseek error path ─────────────────────────────────────────────────

    #[test]
    fn lseek_espipe_on_pipe() {
        let (r, _w) = make_pipe();
        let err = lseek(r.as_fd(), 0, SeekWhence::Set).unwrap_err();
        assert_eq!(err, Errno::ESPIPE);
    }

    // ── statx error path ─────────────────────────────────────────────────

    #[test]
    fn statx_enoent_on_missing_file() {
        let err = statx(
            DirFd::Cwd,
            c"/air_no_such_file_statx_42",
            StatxFlags::empty(),
            StatxMask::ALL,
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

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

    #[test]
    fn faccessat_existing_file_ok() {
        faccessat(
            DirFd::Cwd,
            c"/proc/self/status",
            AccessMode::F_OK,
            AccessFlags::empty(),
        )
        .expect("faccessat /proc/self/status");
    }

    #[test]
    fn faccessat_missing_file_enoent() {
        let err = faccessat(
            DirFd::Cwd,
            c"/air_no_such_file_faccessat_42",
            AccessMode::F_OK,
            AccessFlags::empty(),
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    fn faccessat_symlink_nofollow_effective() {
        // Lien symbolique pendouillant : la cible n'existe pas, mais le lien
        // lui-même existe. C'est LE test qui distingue le comportement corrigé
        // (route vers faccessat2, 4-arg, qui HONORE le flag) de l'ancien (buggé,
        // qui passait le flag à faccessat 3-arg → silencieusement ignoré). Avant
        // le fix, l'assertion `Ok` ci-dessous échouait avec ENOENT.
        let link = c"/tmp/air_fs_faccessat_dangling_42";
        let target = c"/air_no_such_target_for_dangling_symlink_42";
        let _ = unlinkat(DirFd::Cwd, link, 0);
        symlinkat(target, DirFd::Cwd, link).expect("crée le lien pendouillant");

        // Avec SYMLINK_NOFOLLOW → on teste le lien lui-même, qui existe → Ok.
        faccessat(
            DirFd::Cwd,
            link,
            AccessMode::F_OK,
            AccessFlags::SYMLINK_NOFOLLOW,
        )
        .expect("le lien lui-même existe : F_OK doit réussir avec NOFOLLOW");

        // Sans flag → on suit le lien vers une cible absente → ENOENT.
        let err = faccessat(DirFd::Cwd, link, AccessMode::F_OK, AccessFlags::empty()).unwrap_err();
        assert_eq!(
            err,
            Errno::ENOENT,
            "sans NOFOLLOW, on suit vers la cible absente"
        );

        let _ = unlinkat(DirFd::Cwd, link, 0);
    }

    #[test]
    fn faccessat_eaccess_flag_routes_and_succeeds() {
        // AT_EACCESS force l'usage des UID/GID effectifs. Sur un fichier
        // lisible (`/proc/self/status`), R_OK doit réussir — et l'appel emprunte
        // la branche faccessat2 (flags non vide), exerçant le routage 4-arg.
        faccessat(
            DirFd::Cwd,
            c"/proc/self/status",
            AccessMode::R_OK,
            AccessFlags::EACCESS,
        )
        .expect("R_OK avec EACCESS sur un fichier lisible");
    }

    // ── mkdirat error path ────────────────────────────────────────────────

    #[test]
    fn mkdirat_eexist_on_second_call() {
        const AT_REMOVEDIR: i32 = 0x200;
        let dir = c"/tmp/air_fs_test_dir_eexist_42";
        let _ = unlinkat(DirFd::Cwd, dir, AT_REMOVEDIR);
        mkdirat(DirFd::Cwd, dir, 0o700).expect("mkdirat première fois");
        let err = mkdirat(DirFd::Cwd, dir, 0o700).unwrap_err();
        assert_eq!(err, Errno::EEXIST);
        unlinkat(DirFd::Cwd, dir, AT_REMOVEDIR).expect("cleanup");
    }

    // ── getdents64 error path ─────────────────────────────────────────────

    #[test]
    fn getdents64_enotdir_on_regular_file() {
        let fd = open_memfd();
        let mut buffer = vec![0u8; 4096];
        let err = getdents64(fd.as_fd(), &mut buffer).unwrap_err();
        assert_eq!(err, ENOTDIR);
    }

    // ── renameat2 ─────────────────────────────────────────────────────────

    #[test]
    fn renameat2_renames_file() {
        let src = c"/tmp/air_fs_rename_src_42";
        let dst = c"/tmp/air_fs_rename_dst_42";
        let _ = unlinkat(DirFd::Cwd, src, 0);
        let _ = unlinkat(DirFd::Cwd, dst, 0);
        let fd = openat(
            DirFd::Cwd,
            src,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o600,
        )
        .expect("crée src");
        drop(fd);
        renameat2(DirFd::Cwd, src, DirFd::Cwd, dst, RenameFlags::empty()).expect("renameat2");
        // dst existe maintenant, src non.
        faccessat(DirFd::Cwd, dst, AccessMode::F_OK, AccessFlags::empty())
            .expect("dst doit exister");
        let _ = unlinkat(DirFd::Cwd, dst, 0);
    }

    #[test]
    fn renameat2_noreplace_eexist() {
        let src = c"/tmp/air_fs_noreplace_src_42";
        let dst = c"/tmp/air_fs_noreplace_dst_42";
        let _ = unlinkat(DirFd::Cwd, src, 0);
        let _ = unlinkat(DirFd::Cwd, dst, 0);
        for p in [src, dst] {
            let fd = openat(
                DirFd::Cwd,
                p,
                OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
                0o600,
            )
            .expect("crée fichier");
            drop(fd);
        }
        let err = renameat2(DirFd::Cwd, src, DirFd::Cwd, dst, RenameFlags::NOREPLACE).unwrap_err();
        assert_eq!(err, Errno::EEXIST);
        let _ = unlinkat(DirFd::Cwd, src, 0);
        let _ = unlinkat(DirFd::Cwd, dst, 0);
    }

    // ── linkat / symlinkat / readlinkat ───────────────────────────────────

    #[test]
    fn linkat_creates_hard_link() {
        let src = c"/tmp/air_fs_linkat_src_42";
        let lnk = c"/tmp/air_fs_linkat_lnk_42";
        let _ = unlinkat(DirFd::Cwd, src, 0);
        let _ = unlinkat(DirFd::Cwd, lnk, 0);
        let fd = openat(
            DirFd::Cwd,
            src,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o600,
        )
        .expect("crée src");
        drop(fd);
        linkat(DirFd::Cwd, src, DirFd::Cwd, lnk, 0).expect("linkat");
        let _ = unlinkat(DirFd::Cwd, src, 0);
        let _ = unlinkat(DirFd::Cwd, lnk, 0);
    }

    #[test]
    fn linkat_enoent_on_missing_source() {
        let err = linkat(
            DirFd::Cwd,
            c"/air_no_such_linkat_src",
            DirFd::Cwd,
            c"/tmp/air_no_such_linkat_dst",
            0,
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    #[test]
    fn symlinkat_readlinkat_roundtrip() {
        let target = c"/proc/self/status";
        let link = c"/tmp/air_fs_symlink_42";
        let _ = unlinkat(DirFd::Cwd, link, 0);
        symlinkat(target, DirFd::Cwd, link).expect("symlinkat");
        let read_back = readlinkat(DirFd::Cwd, link).expect("readlinkat");
        assert_eq!(read_back.as_slice(), b"/proc/self/status");
        let _ = unlinkat(DirFd::Cwd, link, 0);
    }

    #[test]
    fn readlinkat_einval_on_non_symlink() {
        let err = readlinkat(DirFd::Cwd, c"/proc/self/status").unwrap_err();
        assert_eq!(err, Errno::EINVAL);
    }

    #[test]
    fn readlinkat_enoent_on_missing() {
        let err = readlinkat(DirFd::Cwd, c"/air_no_such_symlink_42").unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    /// `libc_enomem` est la constante `ENOMEM` (12) du chemin de croissance de
    /// buffer de `readlinkat`. Ce chemin est **structurellement inatteignable**
    /// sur les FS cibles (cible de symlink ≤ `PATH_MAX-1` < buffer initial — cf.
    /// registre `readlinkat`), donc le helper n'est jamais appelé en production ;
    /// il reste néanmoins déterministe et testable directement.
    #[test]
    fn libc_enomem_is_twelve() {
        assert_eq!(libc_enomem(), 12, "ENOMEM (asm-generic/errno.h)");
    }

    // ── mknodat ──────────────────────────────────────────────────────────

    #[test]
    fn mknodat_creates_fifo() {
        let path = c"/tmp/air_fs_mknodat_fifo_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        // S_IFIFO | 0o600 = 0o10600
        mknodat(DirFd::Cwd, path, 0o10_600, 0).expect("mknodat FIFO");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn mknodat_eexist_on_second_call() {
        let path = c"/tmp/air_fs_mknodat_eexist_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        mknodat(DirFd::Cwd, path, 0o10_600, 0).expect("mknodat première fois");
        let err = mknodat(DirFd::Cwd, path, 0o10_600, 0).unwrap_err();
        assert_eq!(err, Errno::EEXIST);
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    // ── fchmodat ─────────────────────────────────────────────────────────

    #[test]
    fn fchmodat_changes_mode() {
        let path = c"/tmp/air_fs_fchmodat_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        drop(fd);
        fchmodat(DirFd::Cwd, path, 0o600, 0).expect("fchmodat");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn fchmodat_enoent_on_missing() {
        let err = fchmodat(DirFd::Cwd, c"/air_no_such_file_fchmodat_42", 0o644, 0).unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── fchownat ─────────────────────────────────────────────────────────

    #[test]
    fn fchownat_no_change_succeeds() {
        // uid=-1/gid=-1 signifie "ne pas changer" sur Linux (4294967295 en u32).
        let path = c"/tmp/air_fs_fchownat_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        drop(fd);
        fchownat(DirFd::Cwd, path, u32::MAX, u32::MAX, 0).expect("fchownat no-op");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn fchownat_enoent_on_missing() {
        let err = fchownat(
            DirFd::Cwd,
            c"/air_no_such_file_fchownat_42",
            u32::MAX,
            u32::MAX,
            0,
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── fchmod / fchown / futimens (par fd, additif ADR-085) ──────────────

    #[test]
    fn fchmod_changes_mode_by_fd() {
        let fd = open_memfd();
        fchmod(fd.as_fd(), 0o600).expect("fchmod par fd");
        // fd invalide ⇒ `EBADF`.
        assert_eq!(fchmod(invalid_fd(), 0o600).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn fchown_noop_by_fd() {
        let fd = open_memfd();
        // `(uid, gid) = (-1, -1)` ⇒ « ne rien changer » : succès **sans privilège**.
        fchown(fd.as_fd(), u32::MAX, u32::MAX).expect("fchown no-op par fd");
        // fd invalide ⇒ `EBADF`.
        assert_eq!(
            fchown(invalid_fd(), u32::MAX, u32::MAX).unwrap_err(),
            Errno::EBADF
        );
    }

    #[test]
    fn futimens_sets_times_by_fd() {
        let fd = open_memfd();
        futimens(fd.as_fd(), UtimeValue::Now, UtimeValue::Omit).expect("futimens par fd");
        // fd invalide ⇒ `EBADF`.
        assert_eq!(
            futimens(invalid_fd(), UtimeValue::Now, UtimeValue::Now).unwrap_err(),
            Errno::EBADF
        );
    }

    #[test]
    fn sendfile_transfers_with_and_without_offset() {
        let source = open_memfd();
        let data = b"SENDFILE";
        assert_eq!(write(source.as_fd(), data).expect("write source"), 8);

        // Avec `offset` explicite : départ à 0, l'offset est **avancé** ; la position de
        // `source` reste inchangée.
        let sink = open_memfd();
        let mut offset = 0_u64;
        let sent = sendfile(sink.as_fd(), source.as_fd(), Some(&mut offset), 8).expect("sendfile");
        assert_eq!(sent, 8);
        assert_eq!(offset, 8, "l'offset explicite est avancé");
        // Relit le puits pour vérifier le contenu.
        lseek(sink.as_fd(), 0, SeekWhence::Set).expect("lseek sink");
        let mut buffer = [0_u8; 8];
        assert_eq!(read(sink.as_fd(), &mut buffer).expect("read sink"), 8);
        assert_eq!(&buffer, b"SENDFILE");

        // Sans `offset` (`None`) : le kernel part de la position **courante** de `source`
        // (remise à 0) et l'avance.
        lseek(source.as_fd(), 0, SeekWhence::Set).expect("lseek source");
        let sink2 = open_memfd();
        assert_eq!(
            sendfile(sink2.as_fd(), source.as_fd(), None, 8).expect("sendfile sans offset"),
            8
        );

        // fd invalide ⇒ `EBADF`.
        assert_eq!(
            sendfile(invalid_fd(), source.as_fd(), None, 8).unwrap_err(),
            Errno::EBADF
        );
    }

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

    #[test]
    fn utimensat_now_and_omit() {
        let path = c"/tmp/air_fs_utimensat_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        drop(fd);
        utimensat(DirFd::Cwd, path, UtimeValue::Now, UtimeValue::Omit, 0)
            .expect("utimensat Now/Omit");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn utimensat_specific_time() {
        let path = c"/tmp/air_fs_utimensat_time_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        drop(fd);
        let ts = StatxTimestamp {
            seconds: 1_000_000,
            nanoseconds: 123_456_789,
        };
        utimensat(DirFd::Cwd, path, UtimeValue::Time(ts), UtimeValue::Omit, 0)
            .expect("utimensat Time");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn utimensat_enoent_on_missing() {
        let err = utimensat(
            DirFd::Cwd,
            c"/air_no_such_utimensat_42",
            UtimeValue::Now,
            UtimeValue::Now,
            0,
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── truncate ─────────────────────────────────────────────────────────

    #[test]
    fn truncate_via_path_sets_size() {
        let path = c"/tmp/air_fs_truncate_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::WRONLY | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        write(fd.as_fd(), b"hello world 12345").expect("write");
        drop(fd);
        truncate(DirFd::Cwd, path, 5).expect("truncate");
        let fd2 = openat(DirFd::Cwd, path, OpenFlags::RDONLY, 0).expect("reopen");
        let pos = lseek(fd2.as_fd(), 0, SeekWhence::End).expect("lseek end");
        assert_eq!(pos, 5);
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn truncate_enoent_on_missing() {
        let err = truncate(DirFd::Cwd, c"/air_no_such_truncate_42", 0).unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── fdatasync ────────────────────────────────────────────────────────

    #[test]
    fn fdatasync_on_memfd() {
        let fd = open_memfd();
        write(fd.as_fd(), b"data").expect("write");
        fdatasync(fd.as_fd()).expect("fdatasync");
    }

    #[test]
    fn fdatasync_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(fdatasync(invalid).unwrap_err(), Errno::EBADF);
    }

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

    #[test]
    fn fallocate_preallocates_space() {
        let fd = open_memfd();
        fallocate(fd.as_fd(), FallocateMode::empty(), 0, 4096).expect("fallocate");
        let pos = lseek(fd.as_fd(), 0, SeekWhence::End).expect("lseek");
        assert_eq!(pos, 4096);
    }

    #[test]
    fn fallocate_keep_size_does_not_extend() {
        let fd = open_memfd();
        fallocate(fd.as_fd(), FallocateMode::KEEP_SIZE, 0, 4096).expect("fallocate KEEP_SIZE");
        // La taille visible reste 0 avec KEEP_SIZE.
        let pos = lseek(fd.as_fd(), 0, SeekWhence::End).expect("lseek");
        assert_eq!(pos, 0);
    }

    // ── flock ────────────────────────────────────────────────────────────

    #[test]
    fn flock_lock_and_unlock() {
        let fd = open_memfd();
        // LOCK_EX = 2 ; LOCK_UN = 8
        flock(fd.as_fd(), 2).expect("flock LOCK_EX");
        flock(fd.as_fd(), 8).expect("flock LOCK_UN");
    }

    #[test]
    fn flock_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(flock(invalid, 2).unwrap_err(), Errno::EBADF);
    }

    // ── sync_file_range ──────────────────────────────────────────────────

    #[test]
    fn sync_file_range_on_memfd() {
        let fd = open_memfd();
        write(fd.as_fd(), b"sync data").expect("write");
        // SYNC_FILE_RANGE_WRITE = 2
        sync_file_range(fd.as_fd(), 0, 0, 2).expect("sync_file_range");
    }

    // ── get_fd_flags / set_fd_flags ───────────────────────────────────────

    #[test]
    fn fd_flags_get_set_roundtrip() {
        let fd = open_memfd();
        // Les memfds sont créés avec FD_CLOEXEC.
        let flags = get_fd_flags(fd.as_fd()).expect("get_fd_flags");
        // FD_CLOEXEC = 1
        assert!(flags.contains(FdFlags::CLOEXEC));
        // Retire FD_CLOEXEC et vérifie.
        set_fd_flags(fd.as_fd(), FdFlags::empty()).expect("set_fd_flags");
        let flags2 = get_fd_flags(fd.as_fd()).expect("get_fd_flags après set");
        assert!(!flags2.contains(FdFlags::CLOEXEC));
    }

    #[test]
    fn get_fd_flags_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(get_fd_flags(invalid).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn set_fd_flags_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(
            set_fd_flags(invalid, FdFlags::empty()).unwrap_err(),
            Errno::EBADF
        );
    }

    // ── get_status_flags / set_status_flags ───────────────────────────────

    #[test]
    fn status_flags_get_set_roundtrip() {
        let fd = open_memfd();
        let flags = get_status_flags(fd.as_fd()).expect("get_status_flags");
        // RDWR = O_RDWR ; on vérifie juste que l'appel réussit.
        set_status_flags(fd.as_fd(), flags).expect("set_status_flags");
    }

    #[test]
    fn get_status_flags_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(get_status_flags(invalid).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn set_status_flags_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(
            set_status_flags(invalid, StatusFlags::empty()).unwrap_err(),
            Errno::EBADF
        );
    }

    // ── set_pipe_size / get_pipe_size ─────────────────────────────────────

    #[test]
    fn pipe_size_set_get_roundtrip() {
        let (r, _w) = make_pipe();
        let new_size = set_pipe_size(r.as_fd(), 65536).expect("set_pipe_size");
        assert!(new_size >= 65536);
        let got = get_pipe_size(r.as_fd()).expect("get_pipe_size");
        assert_eq!(got, new_size);
    }

    #[test]
    fn set_pipe_size_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(set_pipe_size(invalid, 4096).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn get_pipe_size_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(get_pipe_size(invalid).unwrap_err(), Errno::EBADF);
    }

    // ── try_lock / lock ──────────────────────────────────────────────────

    #[test]
    fn try_lock_and_unlock() {
        let path = c"/tmp/air_fs_try_lock_42";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::RDWR | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        let lock_w = FileLock {
            lock_type: LockType::Write,
            whence: SeekWhence::Set,
            start: 0,
            length: 0,
            pid: 0,
        };
        let locked = try_lock(fd.as_fd(), &lock_w).expect("try_lock Write");
        assert!(locked, "devrait acquérir le verrou write");
        let unlock = FileLock {
            lock_type: LockType::Unlock,
            whence: SeekWhence::Set,
            start: 0,
            length: 0,
            pid: 0,
        };
        lock(fd.as_fd(), &unlock).expect("lock Unlock");
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    /// Contention **réelle** : les verrous POSIX `fcntl` sont **per-process**. Un
    /// enfant forké prend le verrou exclusif et le tient ; le parent `try_lock` →
    /// **`Ok(false)`** (couvre le chemin de contention `EACCES`/`EAGAIN`, jadis
    /// exempté faute de harnais multi-processus). Synchronisé par pipes (pas de
    /// sleep), récolté via `waitid`.
    #[test]
    #[cfg_attr(miri, ignore = "fork/verrous fcntl non supportés par Miri")]
    fn try_lock_returns_ok_false_when_held_by_another_process() {
        use crate::ipc::pipe2;
        use crate::process::{clone3, exit_group, waitid};
        use air_sys_types::{
            CloneArgs, CloneFlags, CloneResult, PipeFlags, Signal, WaitEvent, WaitOptions,
            WaitTarget,
        };

        let path = c"/tmp/air_fs_try_lock_contention_55";
        let _ = unlinkat(DirFd::Cwd, path, 0);
        let fd = openat(
            DirFd::Cwd,
            path,
            OpenFlags::RDWR | OpenFlags::CREAT | OpenFlags::EXCL,
            0o644,
        )
        .expect("crée fichier");
        // `locked` : enfant→parent (« j'ai le verrou ») ; `release` : parent→enfant.
        let (locked_r, locked_w) = pipe2(PipeFlags::empty()).expect("pipe locked");
        let (release_r, release_w) = pipe2(PipeFlags::empty()).expect("pipe release");

        let write_lock = FileLock {
            lock_type: LockType::Write,
            whence: SeekWhence::Set,
            start: 0,
            length: 0,
            pid: 0,
        };

        let args = CloneArgs {
            flags: CloneFlags::empty(),
            exit_signal: Some(Signal::SIGCHLD),
            stack: None,
            child_tid: None,
            parent_tid: None,
            tls: None,
        };
        // SAFETY: fork simple (pas de `CLONE_VM`/namespace, pas de pile partagée) ;
        // aucune capability requise pour le fork lui-même.
        match unsafe { clone3(&args) }.expect("clone3 doit réussir") {
            CloneResult::Child => {
                // L'enfant acquiert le verrou exclusif (réussit : aucune contention
                // initiale), signale le parent, attend le feu vert, puis sort SANS
                // flush (sa couverture n'est pas requise ici — `exit_group` = `_exit`).
                let acquired = lock(fd.as_fd(), &write_lock).is_ok();
                let _ = write(locked_w.as_fd(), &[u8::from(acquired)]);
                let mut go = [0_u8; 1];
                let _ = read(release_r.as_fd(), &mut go);
                exit_group(i32::from(!acquired));
            }
            CloneResult::Parent { child_pid, .. } => {
                // Attend que l'enfant détienne le verrou.
                let mut signal = [0_u8; 1];
                assert_eq!(
                    read(locked_r.as_fd(), &mut signal).expect("signal locked"),
                    1
                );
                assert_eq!(signal[0], 1, "l'enfant a bien acquis le verrou exclusif");
                // ── CIBLE : contention → `Ok(false)` ──
                assert_eq!(
                    try_lock(fd.as_fd(), &write_lock),
                    Ok(false),
                    "verrou tenu par un autre processus → Ok(false)"
                );
                // Libère l'enfant et le récolte.
                let _ = write(release_w.as_fd(), &[1_u8]);
                let status = waitid(WaitTarget::Pid(child_pid), WaitOptions::EXITED)
                    .expect("waitid")
                    .expect("événement EXITED");
                assert!(
                    matches!(status.event, WaitEvent::Exited { code: 0 }),
                    "enfant sorti proprement : {:?}",
                    status.event
                );
            }
        }
        let _ = unlinkat(DirFd::Cwd, path, 0);
    }

    #[test]
    fn try_lock_ebadf() {
        let invalid = invalid_fd();
        let lock = FileLock {
            lock_type: LockType::Write,
            whence: SeekWhence::Set,
            start: 0,
            length: 0,
            pid: 0,
        };
        assert_eq!(try_lock(invalid, &lock).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn lock_ebadf() {
        let invalid = invalid_fd();
        let unlock = FileLock {
            lock_type: LockType::Unlock,
            whence: SeekWhence::Set,
            start: 0,
            length: 0,
            pid: 0,
        };
        assert_eq!(lock(invalid, &unlock).unwrap_err(), Errno::EBADF);
    }

    // ── add_seals / get_seals ─────────────────────────────────────────────

    #[test]
    fn seals_add_and_get_roundtrip() {
        // memfd_create with ALLOW_SEALING (memfd_create = x86_64:319, aarch64:279)
        #[cfg(target_arch = "x86_64")]
        let nr_memfd: i64 = 319;
        #[cfg(target_arch = "aarch64")]
        let nr_memfd: i64 = 279;
        let name = c"test-seals";
        // MFD_CLOEXEC | MFD_ALLOW_SEALING = 1 | 2 = 3
        // SAFETY: memfd_create via `syscall2`. `name` est une chaîne C statique
        // valide et NUL-terminée (lue par le kernel) ; retourne un FD ≥ 0 ou un errno.
        let ret = unsafe { syscall2(nr_memfd, name.as_ptr() as u64, 3) };
        if ret < 0 {
            return; // ENOSYS si indisponible
        }
        #[allow(clippy::cast_possible_truncation)]
        // SAFETY: `ret >= 0` ici, donc c'est un FD fraîchement créé par memfd_create,
        // non possédé ailleurs : on en prend la propriété exclusive.
        let fd = unsafe { OwnedFd::from_raw_fd(ret as i32) };

        // Au départ, aucun sceau.
        let initial = get_seals(fd.as_fd()).expect("get_seals initial");
        assert!(initial.is_empty());

        // Ajoute SEAL_SHRINK + SEAL_GROW.
        add_seals(fd.as_fd(), Seals::SHRINK | Seals::GROW).expect("add_seals");
        let after = get_seals(fd.as_fd()).expect("get_seals après");
        assert!(after.contains(Seals::SHRINK));
        assert!(after.contains(Seals::GROW));
    }

    #[test]
    fn add_seals_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(add_seals(invalid, Seals::SHRINK).unwrap_err(), Errno::EBADF);
    }

    #[test]
    fn get_seals_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(get_seals(invalid).unwrap_err(), Errno::EBADF);
    }

    // ── name_to_handle_at ─────────────────────────────────────────────────

    #[test]
    fn name_to_handle_at_ok_or_eopnotsupp() {
        // Sur la plupart des FS, name_to_handle_at réussit avec CAP_DAC_READ_SEARCH
        // OU retourne EOPNOTSUPP si le FS ne le supporte pas.
        // /tmp est souvent sur tmpfs qui le supporte.
        match name_to_handle_at(DirFd::Cwd, c"/tmp", NameToHandleFlags::empty()) {
            Ok(h) => {
                // Le handle est valide ; handle_type doit être un entier connu.
                assert!(!h.handle_bytes.is_empty() || h.handle_type != 0 || h.mount_id != 0);
            }
            Err(EOPNOTSUPP) => {
                // FS ne supporte pas les handles : acceptable.
                // (ENOTSUP == EOPNOTSUPP == 95 sur Linux : un seul bras suffit.)
            }
            Err(e) => panic!("name_to_handle_at inattendu : {e:?}"),
        }
    }

    #[test]
    fn name_to_handle_at_enoent() {
        let err = name_to_handle_at(
            DirFd::Cwd,
            c"/air_no_such_handle_42",
            NameToHandleFlags::empty(),
        )
        .unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── copy_file_range avec Some offsets ─────────────────────────────────

    #[test]
    fn copy_file_range_with_explicit_offsets() {
        let src = open_memfd();
        write(src.as_fd(), b"abcdefgh").expect("write src");

        let dst = open_memfd();
        ftruncate(dst.as_fd(), 16).expect("ftruncate dst");

        let mut offset_in: u64 = 2;
        let mut offset_out: u64 = 4;
        let n = copy_file_range(
            src.as_fd(),
            Some(&mut offset_in),
            dst.as_fd(),
            Some(&mut offset_out),
            4,
            0,
        )
        .expect("copy_file_range avec offsets");
        assert_eq!(n, 4);
        // offset_in avancé de 4, offset_out avancé de 4.
        assert_eq!(offset_in, 6);
        assert_eq!(offset_out, 8);
        // Vérifie que "cdef" est à la position 4 dans dst.
        lseek(dst.as_fd(), 4, SeekWhence::Set).expect("lseek dst");
        let mut buffer = [0u8; 4];
        let n2 = read(dst.as_fd(), &mut buffer).expect("read dst");
        assert_eq!(n2, 4);
        assert_eq!(&buffer, b"cdef");
    }

    // ── unlinkat error path ───────────────────────────────────────────────

    #[test]
    fn unlinkat_enoent_on_missing() {
        let err = unlinkat(DirFd::Cwd, c"/air_no_such_unlinkat_42", 0).unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── openat2 error path ───────────────────────────────────────────────

    #[test]
    fn openat2_enoent_on_missing() {
        use air_sys_types::fs::{OpenHow, ResolveFlags};
        let how = OpenHow {
            flags: OpenFlags::RDONLY,
            mode: 0,
            resolve: ResolveFlags::empty(),
        };
        let err = openat2(DirFd::Cwd, c"/air_no_such_openat2_42", how).unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── ftruncate error path ──────────────────────────────────────────────

    #[test]
    fn ftruncate_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(ftruncate(invalid, 0).unwrap_err(), Errno::EBADF);
    }

    // ── fsync error path ──────────────────────────────────────────────────

    #[test]
    fn fsync_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(fsync(invalid).unwrap_err(), Errno::EBADF);
    }

    // ── statfs error path ─────────────────────────────────────────────────

    #[test]
    fn statfs_enoent_on_missing() {
        let err = statfs(c"/air_no_such_path_statfs_42").unwrap_err();
        assert_eq!(err, Errno::ENOENT);
    }

    // ── fstatfs error path ────────────────────────────────────────────────

    #[test]
    fn fstatfs_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(fstatfs(invalid).unwrap_err(), Errno::EBADF);
    }

    // ── dup_fd error path ─────────────────────────────────────────────────

    #[test]
    fn dup_fd_ebadf() {
        let invalid = invalid_fd();
        assert_eq!(dup_fd(invalid, 0).unwrap_err(), Errno::EBADF);
    }

    // ── parse_dirents : couverture de tous les DirEntryType ───────────────

    /// Construit un buffer `linux_dirent64` minimal pour le type donné.
    fn make_dirent_buf(file_type_byte: u8) -> Vec<u8> {
        // struct linux_dirent64 :
        //   ino:    u64 (8 bytes)  [0..8]
        //   off:    i64 (8 bytes)  [8..16]
        //   reclen: u16 (2 bytes)  [16..18]
        //   type:   u8  (1 byte)   [18]
        //   name:   b"x\0" (2 bytes) [19..21]
        // Total reclen = 21, padded to 24 for alignment.
        let reclen: u16 = 24;
        let mut buffer = vec![0u8; 24];
        buffer[0..8].copy_from_slice(&1u64.to_ne_bytes()); // ino = 1
        buffer[8..16].copy_from_slice(&1i64.to_ne_bytes()); // offset = 1
        buffer[16..18].copy_from_slice(&reclen.to_ne_bytes()); // reclen
        buffer[18] = file_type_byte; // type
        buffer[19] = b'x'; // name
        buffer[20] = 0; // NUL
        buffer
    }

    #[test]
    fn parse_dirents_all_types() {
        // Type bytes: Fifo=1, Char=2, Dir=4, Block=6, Reg=8, Symlink=10, Socket=12, Unknown=0
        for (byte, expected) in [
            (1u8, DirEntryType::Fifo),
            (2, DirEntryType::Character),
            (4, DirEntryType::Directory),
            (6, DirEntryType::Block),
            (8, DirEntryType::Regular),
            (10, DirEntryType::Symlink),
            (12, DirEntryType::Socket),
            (0, DirEntryType::Unknown),
            (255, DirEntryType::Unknown), // autre valeur inconnue
        ] {
            let buffer = make_dirent_buf(byte);
            let entries: Vec<_> = parse_dirents(&buffer).collect();
            assert_eq!(entries.len(), 1, "type_byte={byte}");
            assert_eq!(entries[0].file_type, expected, "type_byte={byte}");
        }
    }

    #[test]
    fn parse_dirents_empty_buf() {
        let entries: Vec<_> = parse_dirents(&[]).collect();
        assert!(entries.is_empty());
    }

    #[test]
    fn parse_dirents_truncated_header() {
        // Buffer de moins de 19 octets : retourne None.
        let buffer = vec![0u8; 10];
        let entries: Vec<_> = parse_dirents(&buffer).collect();
        assert!(entries.is_empty());
    }

    #[test]
    fn parse_dirents_reclen_zero() {
        // reclen=0 doit stopper l'itération sans paniquer.
        let mut buffer = vec![0u8; 24];
        buffer[0..8].copy_from_slice(&1u64.to_ne_bytes());
        buffer[8..16].copy_from_slice(&1i64.to_ne_bytes());
        buffer[16..18].copy_from_slice(&0u16.to_ne_bytes()); // reclen = 0
        buffer[18] = 8;
        buffer[19] = b'x';
        buffer[20] = 0;
        let entries: Vec<_> = parse_dirents(&buffer).collect();
        assert!(entries.is_empty());
    }

    #[test]
    fn parse_dirents_name_without_nul() {
        // Nom sans NUL terminal : unwrap_or(name_region.len()) couvre ce cas.
        let reclen: u16 = 24;
        let mut buffer = vec![0u8; 24];
        buffer[0..8].copy_from_slice(&1u64.to_ne_bytes());
        buffer[8..16].copy_from_slice(&1i64.to_ne_bytes());
        buffer[16..18].copy_from_slice(&reclen.to_ne_bytes());
        buffer[18] = 8; // Regular
        // Remplir le nom avec des octets non-NUL.
        for b in buffer[19..24].iter_mut() {
            *b = b'a';
        }
        let entries: Vec<_> = parse_dirents(&buffer).collect();
        assert_eq!(entries.len(), 1);
    }
}