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, ChmodFlags, CloseRangeFlags, 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 CLOSE_RANGE: i64 = 436;
    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 FCHMODAT2: i64 = 452;
    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 CLOSE_RANGE: i64 = 436;
    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 FCHMODAT2: i64 = 452;
    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(())
}

/// `close_range(first, last, flags)` (Linux 5.9+) — ferme **tous** les descripteurs
/// de l'intervalle **inclusif** `[first, last]`. `last == u32::MAX` ferme tout à
/// partir de `first`.
///
/// Confinement (ADR-122) : un enfant forké ferme en un appel tous les fd hérités
/// hormis un keep-set (ring io_uring, sockets d'écoute, autres connexions), **avant**
/// de poser sa cage — évite un balayage `/proc/self/fd` (openat/getdents) qui, lui,
/// serait interdit par le profil confiné.
///
/// Contrairement à [`close`], cette fonction **ne consomme pas** d'`OwnedFd` : elle
/// opère sur des **numéros bruts** (l'appelant garantit qu'aucun `OwnedFd` vivant ne
/// couvre l'intervalle, sous peine de double-fermeture au `Drop`).
///
/// # Errors
///
/// - [`Errno::EINVAL`] : `first > last`, ou `flags` non reconnus.
/// - [`Errno::EMFILE`] / [`Errno::ENOMEM`] : avec [`CloseRangeFlags::UNSHARE`], échec
///   du dédoublement de la table de descripteurs.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::close_range;
/// use air_sys_types::fs::CloseRangeFlags;
///
/// // Ferme tout à partir du fd 3 (garde stdin/stdout/stderr).
/// close_range(3, u32::MAX, CloseRangeFlags::empty()).expect("close_range");
/// ```
pub fn close_range(first: u32, last: u32, flags: CloseRangeFlags) -> Result<(), Errno> {
    // SAFETY:
    // - close_range(2) ne lit ni n'écrit de mémoire utilisateur.
    // - Ferme des descripteurs par numéro ; l'invariant « aucun OwnedFd vivant dans
    //   l'intervalle » est une précondition documentée de l'appelant.
    let ret = unsafe {
        syscall3(
            nr::CLOSE_RANGE,
            u64::from(first),
            u64::from(last),
            u64::from(flags.bits()),
        )
    };

    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 les permissions d'un fichier **en honorant les drapeaux `AT_*`**.
///
/// Wrappeur de `fchmodat2(2)` (numéro 452 sur x86_64 **et** aarch64, Linux ≥ 6.6).
///
/// # Pourquoi un second wrapper de `chmod` par chemin
///
/// Le syscall noyau `fchmodat` historique ne prend que **3 arguments**
/// (`dirfd`, `path`, `mode`) : la couche C ajoute bien un paramètre `flags` dans
/// sa signature, mais le noyau ne le reçoit jamais — `AT_SYMLINK_NOFOLLOW` y est
/// donc **silencieusement ignoré**, et le chemin est toujours re-résolu en
/// **suivant** le lien symbolique final. C'est le même piège que
/// `faccessat` / [`faccessat2`], résolu de la même façon : un syscall à 4
/// arguments qui, lui, **applique** les drapeaux.
///
/// [`ChmodFlags::SYMLINK_NOFOLLOW`] ferme donc une fenêtre TOCTOU : entre le
/// moment où l'on crée un nœud (un socket Unix, par exemple) et celui où l'on
/// restreint ses permissions, un tiers ayant droit d'écriture sur le répertoire
/// conteneur peut substituer un lien symbolique et détourner le `chmod` vers un
/// fichier tiers. Avec ce drapeau, la substitution ne réussit pas : Linux ne sait
/// pas changer les permissions d'un lien symbolique et rend `EOPNOTSUPP`.
/// L'appelant obtient donc, en plus du `chmod`, la preuve que le chemin
/// désignait bien le nœud attendu — ou une erreur qu'il peut traiter.
///
/// `EINTR` est remonté tel quel : aucun retry automatique en couche 0 (ADR-021).
///
/// # Errors
///
/// - `EOPNOTSUPP` : `SYMLINK_NOFOLLOW` demandé et le chemin final est un lien
///   symbolique (Linux ne modifie pas les permissions d'un lien).
/// - `ENOENT` : chemin inexistant.
/// - `EPERM` / `EACCES` : pas le droit de modifier ce nœud.
/// - `ENOSYS` : noyau < 6.6 (Air cible 6.12+, cf. ADR-004).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::fs::fchmodat2;
/// use air_sys_types::fs::{ChmodFlags, DirFd};
///
/// // Restreint le socket que nous venons de lier — sans jamais suivre un lien.
/// let result = fchmodat2(DirFd::Cwd, c"/run/air/forward.sock", 0o600, ChmodFlags::SYMLINK_NOFOLLOW);
/// ```
pub fn fchmodat2(
    dirfd: DirFd<'_>,
    path: &CStr,
    mode: Mode,
    flags: ChmodFlags,
) -> Result<(), Errno> {
    let raw_dirfd = dirfd_to_raw(dirfd);

    // SAFETY: SYS_fchmodat2 (x86_64 = 452) / SYS_fchmodat2 (aarch64 = 452).
    // 4 arguments : (dirfd, path, mode, flags). path est un CStr nul-terminé valide
    // pour la durée du syscall. C'est le seul syscall de chmod par chemin qui
    // HONORE réellement AT_SYMLINK_NOFOLLOW — le 3-arg fchmodat l'ignore.
    let ret = unsafe {
        syscall4(
            nr::FCHMODAT2,
            fd_to_u64(raw_dirfd),
            path.as_ptr() as u64,
            u64::from(mode),
            i32_to_u64(flags.bits()),
        )
    };

    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;