air_sys_syscall/

net.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 `net` — sockets synchrones.
//!
//! Cf. `docs/specs/layer-0/family-net.md`.
//!
//! Toutes les opérations de cette famille sont synchrones. Les variantes
//! io_uring seront ajoutées au Temps 2b (ADR-022), en réutilisant les
//! mêmes types.

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

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

use air_sys_types::net::{
    AcceptFlags, AcceptResult, IoSlice, IoSliceMut, IpMembershipV4, IpMembershipV6, Ipv4SocketAddr,
    Ipv6SocketAddr, LingerOption, MessageFlags, ReceiveMessageRequest, ReceiveMessageResult,
    SendMessageRequest, SendMessageResult, ShutdownMode, SocketAddr, SocketDomain, SocketType,
    UnixCredentials, UnixSocketAddr,
};
use air_sys_types::process::Pid;
use air_sys_types::{Errno, OwnedFd as AirOwnedFd, Timeval};

// ─────────────────────────────────────────────────────────────────────────
// Helper commun : conversion d'une valeur de retour syscall négative en Errno.
// ─────────────────────────────────────────────────────────────────────────

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

// ─────────────────────────────────────────────────────────────────────────
// Constantes socket
// ─────────────────────────────────────────────────────────────────────────

/// `SOCK_CLOEXEC` : ajouté systématiquement par les wrappers socket/socketpair/accept4.
const SOCK_CLOEXEC: i32 = 0x0008_0000;

/// `MSG_NOSIGNAL` : activé par défaut sur send/sendmsg.
const MSG_NOSIGNAL: i32 = 0x4000;

// ─────────────────────────────────────────────────────────────────────────
// Constantes sockopt
// ─────────────────────────────────────────────────────────────────────────

const SOL_SOCKET: i32 = 1;
const SO_KEEPALIVE: i32 = 9;
const SO_REUSEADDR: i32 = 2;
const SO_REUSEPORT: i32 = 15;
const SO_SNDBUF: i32 = 7;
const SO_RCVBUF: i32 = 8;
const SO_ERROR: i32 = 4;
const SO_LINGER: i32 = 13;
const SO_PEERCRED: i32 = 17;
const SO_BINDTODEVICE: i32 = 25;
// Options à `timeval` : sur LP64 (x86_64/aarch64, cibles Air), `SO_RCVTIMEO`/
// `SO_SNDTIMEO` valent les constantes « OLD » (le `time_t` y est déjà 64-bit),
// avec un `struct timeval` de 16 octets. Cf. `Timeval` (air-sys-types).
const SO_RCVTIMEO: i32 = 20;
const SO_SNDTIMEO: i32 = 21;

const IPPROTO_TCP: i32 = 6;
const TCP_NODELAY: i32 = 1;
const TCP_KEEPIDLE: i32 = 4;
const TCP_KEEPINTVL: i32 = 5;
const TCP_KEEPCNT: i32 = 6;

const IPPROTO_IP: i32 = 0;
const IP_TTL: i32 = 2;
const IP_ADD_MEMBERSHIP: i32 = 35;
const IP_DROP_MEMBERSHIP: i32 = 36;

const IPPROTO_IPV6: i32 = 41;
const IPV6_V6ONLY: i32 = 26;
// `IPV6_JOIN_GROUP` / `IPV6_LEAVE_GROUP` (alias `IPV6_ADD/DROP_MEMBERSHIP`).
const IPV6_ADD_MEMBERSHIP: i32 = 20;
const IPV6_DROP_MEMBERSHIP: i32 = 21;

/// Taille de `struct timeval` sur LP64 (deux `long` de 8 octets).
const TIMEVAL_LEN: u32 = 16;
/// Taille de `struct ip_mreq` (deux `struct in_addr`).
const IP_MREQ_LEN: u32 = 8;
/// Taille de `struct ipv6_mreq` (`in6_addr` + `int ifindex`).
const IPV6_MREQ_LEN: u32 = 20;

// Les tailles ABI ci-dessus sont **verrouillées** sur le layout `#[repr(C)]` des
// types couche 0 : un dérapage casserait la compilation (assertions const).
const _: () = assert!(core::mem::size_of::<Timeval>() == TIMEVAL_LEN as usize);
const _: () = assert!(core::mem::size_of::<IpMembershipV4>() == IP_MREQ_LEN as usize);
const _: () = assert!(core::mem::size_of::<IpMembershipV6>() == IPV6_MREQ_LEN as usize);

// ─────────────────────────────────────────────────────────────────────────
// Taille maximale de sockaddr (ss_maxsize POSIX)
// ─────────────────────────────────────────────────────────────────────────

pub(crate) const MAX_SOCKADDR_LEN: usize = 128;

/// Buffer de stockage sockaddr brut aligné sur u64.
#[repr(C, align(8))]
#[derive(Debug)]
pub(crate) struct RawSockaddrStorage {
    pub(crate) bytes: [u8; MAX_SOCKADDR_LEN],
}

/// Convertit un `SocketAddr` Air en représentation kernel brute.
/// Retourne `(buffer, longueur_effective)`.
pub(crate) fn socket_addr_to_raw(address: &SocketAddr) -> (RawSockaddrStorage, u32) {
    let mut storage = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    match address {
        SocketAddr::Unix(unix) => {
            // sa_family = AF_UNIX = 1 (LE)
            storage.bytes[0..2].copy_from_slice(&1u16.to_ne_bytes());
            match unix {
                UnixSocketAddr::Path(path) => {
                    let bytes = path.as_bytes();
                    let length = bytes.len().min(107);
                    storage.bytes[2..2_usize.saturating_add(length)]
                        .copy_from_slice(&bytes[..length]);
                    storage.bytes[2_usize.saturating_add(length)] = 0; // NUL terminateur
                    // addrlen = sizeof(sa_family) + length + NUL
                    #[allow(clippy::cast_possible_truncation)]
                    let addrlen = (2_usize.saturating_add(length).saturating_add(1)) as u32;
                    (storage, addrlen)
                }
                UnixSocketAddr::Abstract(name) => {
                    // Premier octet = '\0' (marqueur abstrait), puis le nom
                    storage.bytes[2] = 0;
                    let length = name.len().min(107);
                    storage.bytes[3..3_usize.saturating_add(length)]
                        .copy_from_slice(&name[..length]);
                    // addrlen = sizeof(sa_family) + 1 (NUL) + length
                    #[allow(clippy::cast_possible_truncation)]
                    let addrlen = (2_usize.saturating_add(1).saturating_add(length)) as u32;
                    (storage, addrlen)
                }
                UnixSocketAddr::Unnamed => (storage, 2),
            }
        }
        SocketAddr::Ipv4(ipv4) => {
            // sa_family = AF_INET = 2
            storage.bytes[0..2].copy_from_slice(&2u16.to_ne_bytes());
            // port en big-endian
            let port_be = ipv4.port.to_be();
            storage.bytes[2..4].copy_from_slice(&port_be.to_ne_bytes());
            storage.bytes[4..8].copy_from_slice(&ipv4.address);
            // sin_zero reste à 0 (déjà initialisé)
            (storage, 16)
        }
        SocketAddr::Ipv6(ipv6) => {
            // sa_family = AF_INET6 = 10
            storage.bytes[0..2].copy_from_slice(&10u16.to_ne_bytes());
            let port_be = ipv6.port.to_be();
            storage.bytes[2..4].copy_from_slice(&port_be.to_ne_bytes());
            storage.bytes[4..8].copy_from_slice(&ipv6.flowinfo.to_ne_bytes());
            storage.bytes[8..24].copy_from_slice(&ipv6.address);
            storage.bytes[24..28].copy_from_slice(&ipv6.scope_id.to_ne_bytes());
            (storage, 28)
        }
    }
}

/// Convertit un buffer sockaddr brut en `SocketAddr` Air.
/// Retourne `None` si le buffer est trop court ou la famille inconnue.
pub(crate) fn raw_to_socket_addr(buffer: &[u8], length: u32) -> Option<SocketAddr> {
    if length < 2 {
        return None;
    }
    let len_usize = length as usize;
    if buffer.len() < len_usize {
        return None;
    }
    let family = u16::from_ne_bytes([buffer[0], buffer[1]]);
    match family {
        1 => {
            // AF_UNIX
            if length == 2 {
                return Some(SocketAddr::Unix(UnixSocketAddr::Unnamed));
            }
            if length < 3 {
                return None;
            }
            let path_bytes = buffer.get(2..len_usize)?;
            if path_bytes.first() == Some(&0) {
                // Abstract : le premier octet est '\0', suivi du nom
                let name = path_bytes.get(1..).unwrap_or(&[]).to_vec();
                Some(SocketAddr::Unix(UnixSocketAddr::Abstract(name)))
            } else {
                // Path : NUL-terminé
                let nul = path_bytes
                    .iter()
                    .position(|&b| b == 0)
                    .unwrap_or(path_bytes.len());
                let cstr = CString::new(&path_bytes[..nul]).ok()?;
                Some(SocketAddr::Unix(UnixSocketAddr::Path(cstr)))
            }
        }
        2 => {
            // AF_INET
            if length < 16 {
                return None;
            }
            let port = u16::from_be_bytes([buffer[2], buffer[3]]);
            let address = [buffer[4], buffer[5], buffer[6], buffer[7]];
            Some(SocketAddr::Ipv4(Ipv4SocketAddr { address, port }))
        }
        10 => {
            // AF_INET6
            if length < 28 {
                return None;
            }
            let port = u16::from_be_bytes([buffer[2], buffer[3]]);
            let flowinfo = u32::from_ne_bytes([buffer[4], buffer[5], buffer[6], buffer[7]]);
            let mut address = [0u8; 16];
            address.copy_from_slice(buffer.get(8..24)?);
            let scope_id = u32::from_ne_bytes([buffer[24], buffer[25], buffer[26], buffer[27]]);
            Some(SocketAddr::Ipv6(Ipv6SocketAddr {
                address,
                port,
                flowinfo,
                scope_id,
            }))
        }
        _ => None,
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Codec sockaddr PUBLIC pour la face libc (ADR-070, descellement additif couche 0
// — cadre ADR-051). Fines expositions des codecs internes ci-dessus : une seule
// autorité de layout sockaddr (kernel=bible), zéro duplication côté libc.
// ─────────────────────────────────────────────────────────────────────────

/// **Décode** un `sockaddr` kernel brut (octets + `socklen_t`) en [`SocketAddr`] typé.
/// Exposition publique de [`raw_to_socket_addr`] pour la face **libc** : `bytes` est le
/// buffer présenté par le C, `length` la longueur associée. Rend `None` si la famille
/// est inconnue ou la longueur insuffisante — aucune présomption sur les octets
/// (Principe 3), aucun `unsafe`.
#[must_use]
pub fn socket_addr_from_bytes(bytes: &[u8], length: u32) -> Option<SocketAddr> {
    raw_to_socket_addr(bytes, length)
}

/// **Encode** un [`SocketAddr`] typé en `sockaddr` kernel brut dans `out`, rendant la
/// **longueur effective** (`socklen_t`) écrite, ou `None` si `out` est trop court.
/// Exposition publique de [`socket_addr_to_raw`] pour la face libc **sans** fuiter le
/// type de stockage interne (copie bornée dans le buffer de l'appelant).
#[must_use]
pub fn socket_addr_to_bytes(address: &SocketAddr, out: &mut [u8]) -> Option<u32> {
    let (storage, length) = socket_addr_to_raw(address);
    let length_usize = usize::try_from(length).ok()?;
    let source = storage.bytes.get(..length_usize)?;
    let target = out.get_mut(..length_usize)?;
    target.copy_from_slice(source);
    Some(length)
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers cmsg (ancillaires SCM_RIGHTS)
// ─────────────────────────────────────────────────────────────────────────

/// Construit un buffer `cmsghdr` + données FDs pour `SCM_RIGHTS` (LP64).
///
/// Structure `cmsghdr` sur LP64 :
/// - cmsg_len  : u64 (8 octets) — taille incluant le header
/// - cmsg_level: i32 (4 octets) = SOL_SOCKET = 1
/// - cmsg_type : i32 (4 octets) = SCM_RIGHTS = 1
/// - données   : i32 * nfds
pub(crate) fn build_scm_rights_cmsg(fds: &[BorrowedFd<'_>]) -> Vec<u8> {
    if fds.is_empty() {
        return Vec::new();
    }
    let data_len = fds.len().saturating_mul(4); // chaque fd = i32
    let cmsg_len = 16_usize.saturating_add(data_len); // header 16 + data
    let total = cmsg_len.saturating_add(7) & !7_usize; // alignement 8
    let mut buffer = vec![0u8; total];
    // cmsg_len en u64 (LP64)
    #[allow(clippy::cast_possible_truncation)]
    buffer[0..8].copy_from_slice(&(cmsg_len as u64).to_ne_bytes());
    // cmsg_level = SOL_SOCKET = 1
    buffer[8..12].copy_from_slice(&1i32.to_ne_bytes());
    // cmsg_type = SCM_RIGHTS = 1
    buffer[12..16].copy_from_slice(&1i32.to_ne_bytes());
    // FDs
    for (i, fd) in fds.iter().enumerate() {
        let raw = fd.as_raw_fd();
        let offset = 16_usize.saturating_add(i.saturating_mul(4));
        buffer[offset..offset.saturating_add(4)].copy_from_slice(&raw.to_ne_bytes());
    }
    buffer
}

/// Parse un buffer cmsg et extrait les `OwnedFd` reçus via `SCM_RIGHTS`.
pub(crate) fn parse_scm_rights(cmsg_buf: &[u8], cmsg_len: usize) -> Vec<OwnedFd> {
    let mut fds = Vec::new();
    let mut offset = 0_usize;
    while offset.saturating_add(16) <= cmsg_len && offset.saturating_add(16) <= cmsg_buf.len() {
        let len_bytes: [u8; 8] = match cmsg_buf[offset..offset.saturating_add(8)].try_into() {
            Ok(b) => b,
            Err(_) => break,
        };
        // MAX_SOCKADDR_LEN = 128 < usize::MAX sur toutes les cibles supportées (LP64).
        // La troncature de u64 à usize est intentionnelle : les tailles cmsg sont
        // bornées à quelques centaines d'octets en pratique.
        #[allow(clippy::cast_possible_truncation)]
        let length = u64::from_ne_bytes(len_bytes) as usize;
        let level_bytes: [u8; 4] =
            match cmsg_buf[offset.saturating_add(8)..offset.saturating_add(12)].try_into() {
                Ok(b) => b,
                Err(_) => break,
            };
        let level = i32::from_ne_bytes(level_bytes);
        let ty_bytes: [u8; 4] =
            match cmsg_buf[offset.saturating_add(12)..offset.saturating_add(16)].try_into() {
                Ok(b) => b,
                Err(_) => break,
            };
        let ty = i32::from_ne_bytes(ty_bytes);

        // SOL_SOCKET=1, SCM_RIGHTS=1
        if level == 1 && ty == 1 && length >= 16 {
            let mut fd_off = offset.saturating_add(16);
            let end = offset.saturating_add(length);
            while fd_off.saturating_add(4) <= end && fd_off.saturating_add(4) <= cmsg_buf.len() {
                let raw_bytes: [u8; 4] = match cmsg_buf[fd_off..fd_off.saturating_add(4)].try_into()
                {
                    Ok(b) => b,
                    Err(_) => break,
                };
                let raw = i32::from_ne_bytes(raw_bytes);
                // SAFETY: Le kernel a retourné des FDs valides dans le cmsg SCM_RIGHTS.
                // Ces FDs nous appartiennent maintenant (le kernel en transfère l'ownership).
                fds.push(unsafe { OwnedFd::from_raw_fd(raw) });
                fd_off = fd_off.saturating_add(4);
            }
        }
        let aligned = length.saturating_add(7) & !7_usize;
        if aligned == 0 {
            break;
        }
        offset = offset.saturating_add(aligned);
    }
    fds
}

// ─────────────────────────────────────────────────────────────────────────
// Structure KernelMsghdr (LP64)
// ─────────────────────────────────────────────────────────────────────────

/// Représentation kernel de `struct msghdr` en mode LP64 (Linux x86_64/aarch64).
///
/// Les champs `size_t` font 8 octets ; on insère un padding explicite entre
/// `msg_namelen` (u32) et `msg_iov` (u64) pour respecter l'alignement LP64.
#[repr(C)]
struct KernelMsghdr {
    msg_name: u64,       // *mut void = u64 (NULL si pas d'adresse)
    msg_namelen: u32,    // longueur de l'adresse
    _pad: u32,           // alignement LP64
    msg_iov: u64,        // *mut iovec
    msg_iovlen: u64,     // size_t
    msg_control: u64,    // *mut void (cmsg)
    msg_controllen: u64, // size_t
    msg_flags: i32,      // drapeaux retournés
    _pad2: u32,
}

// ─────────────────────────────────────────────────────────────────────────
// Helper getsockopt/setsockopt bas-niveau
// ─────────────────────────────────────────────────────────────────────────

/// Lit une option socket en entier (`i32`).
fn getsockopt_i32(sock: BorrowedFd<'_>, level: i32, optname: i32) -> Result<i32, Errno> {
    let mut val: i32 = 0;
    let mut length: u32 = 4;
    let val_ptr: *mut i32 = &mut val;
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit `*length` octets (au maximum `*len_ptr`) dans `*val_ptr`.
    // - val et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            level,
            optname,
            val_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(val)
}

/// Définit une option socket en entier (`i32`).
fn setsockopt_i32(sock: BorrowedFd<'_>, level: i32, optname: i32, val: i32) -> Result<(), Errno> {
    let val_ref: &i32 = &val;
    let val_ptr: *const i32 = val_ref;
    let length: u32 = 4;
    // SAFETY:
    // - setsockopt(2) lit `length` octets depuis `*val_ptr`.
    // - val est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_setsockopt(sock.as_raw_fd(), level, optname, val_ptr as u64, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// setsockopt/getsockopt PUBLICS à valeur entière pour la face libc (ADR-071,
// descellement additif couche 0 — cadre ADR-051). La quasi-totalité des options
// (SO_REUSEADDR/TCP_NODELAY/SO_KEEPALIVE/SO_ERROR/IP_TOS/…) sont des `int`.
// ─────────────────────────────────────────────────────────────────────────

/// **Définit** une option socket à valeur **entière** (`setsockopt` avec `optlen == 4`).
/// Exposition publique de [`setsockopt_i32`] pour la face libc : `level`/`optname` sont
/// les entiers bruts fournis par le C (validés par le kernel).
///
/// # Errors
/// L'`errno` de `setsockopt(2)` (`EBADF`/`ENOPROTOOPT`/`EINVAL`…), propagé.
pub fn set_socket_option_int(
    sock: BorrowedFd<'_>,
    level: i32,
    optname: i32,
    value: i32,
) -> Result<(), Errno> {
    setsockopt_i32(sock, level, optname, value)
}

/// **Lit** une option socket à valeur **entière** (`getsockopt`). Exposition publique
/// de [`getsockopt_i32`] pour la face libc.
///
/// # Errors
/// L'`errno` de `getsockopt(2)`, propagé.
pub fn get_socket_option_int(sock: BorrowedFd<'_>, level: i32, optname: i32) -> Result<i32, Errno> {
    getsockopt_i32(sock, level, optname)
}

// ─────────────────────────────────────────────────────────────────────────
// Setup des sockets
// ─────────────────────────────────────────────────────────────────────────

/// Crée un socket.
///
/// Wrappeur de `socket(2)`. `SOCK_CLOEXEC` est ajouté automatiquement
/// par le wrapper pour garantir que le FD ne fuit pas vers les processus
/// fils via `exec`.
///
/// # Parameters
///
/// - `domain` : famille de protocole ([`SocketDomain::Unix`] pour l'IPC
///   Air via Conduit).
/// - `ty` : type de socket ([`SocketType::Stream`] pour TCP/Unix stream).
/// - `protocol` : protocole (0 = défaut pour le type).
///
/// # Errors
///
/// - `EAFNOSUPPORT` : famille de protocole non supportée.
/// - `EPROTONOSUPPORT` : protocole non supporté pour ce type.
/// - `EMFILE` : quota de FD du processus atteint.
/// - `ENFILE` : quota de FD système atteint.
/// - `ENOMEM` : mémoire kernel insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::socket;
/// use air_sys_types::net::{SocketDomain, SocketType};
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// ```
pub fn socket(domain: SocketDomain, ty: SocketType, protocol: i32) -> Result<AirOwnedFd, Errno> {
    let domain_raw = domain as i32;
    let ty_raw = (ty as i32) | SOCK_CLOEXEC;
    // SAFETY:
    // - socket(2) ne touche à aucune mémoire utilisateur (args entiers).
    // - En cas de succès, retourne un FD valide >= 0 ; en cas d'erreur, ret < 0.
    // - SOCK_CLOEXEC est setté atomiquement par le kernel.
    let ret = unsafe { raw_syscall_socket(domain_raw, ty_raw, protocol) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = ret as i32;
    // SAFETY: Le kernel a retourné un FD valide >= 0.
    Ok(unsafe { AirOwnedFd::from_raw_fd(raw_fd) })
}

/// Lie un socket à une adresse locale.
///
/// Wrappeur de `bind(2)`. Pour les sockets Unix path-based, supprimer
/// le chemin existant avec `unlinkat` (en ignorant `ENOENT`) avant
/// d'appeler `bind` est la convention recommandée.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `address` : adresse locale à lier.
///
/// # Errors
///
/// - `EADDRINUSE` : adresse déjà utilisée.
/// - `EADDRNOTAVAIL` : adresse non disponible sur cet hôte.
/// - `EINVAL` : socket déjà lié ou adresse invalide.
/// - `EACCES` : permission refusée (ex. bind sur un port < 1024 sans
///   privilèges).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::{socket, bind};
/// use air_sys_types::net::{SocketAddr, SocketDomain, SocketType, UnixSocketAddr};
/// use air_sys_types::fd::AsFd;
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// bind(fd.as_fd(), &SocketAddr::Unix(UnixSocketAddr::Path(
///     std::ffi::CString::new("/tmp/air.sock").expect("cstring"),
/// ))).expect("bind");
/// ```
pub fn bind(sock: BorrowedFd<'_>, address: &SocketAddr) -> Result<(), Errno> {
    let (raw, addrlen) = socket_addr_to_raw(address);
    let addr_ptr: *const u8 = raw.bytes.as_ptr();
    // SAFETY:
    // - bind(2) lit `addrlen` octets depuis `addr_ptr` (la sockaddr).
    // - `raw` est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_bind(sock.as_raw_fd(), addr_ptr as u64, addrlen) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Met un socket en mode écoute.
///
/// Wrappeur de `listen(2)`.
///
/// # Parameters
///
/// - `sock` : FD du socket déjà lié avec [`bind`].
/// - `backlog` : taille de la file des connexions en attente d'`accept`.
///
/// # Errors
///
/// - `EADDRINUSE` : adresse déjà utilisée.
/// - `EOPNOTSUPP` : type de socket ne supporte pas `listen`.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::listen;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// listen(fd, 128).expect("listen");
/// # }
/// ```
pub fn listen(sock: BorrowedFd<'_>, backlog: u32) -> Result<(), Errno> {
    // backlog est passé comme i32 au kernel ; saturer à i32::MAX si trop grand.
    #[allow(clippy::cast_possible_truncation)]
    let backlog_i32 = if backlog > i32::MAX as u32 {
        i32::MAX
    } else {
        backlog as i32
    };
    // SAFETY:
    // - listen(2) ne touche à aucune mémoire utilisateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_listen(sock.as_raw_fd(), backlog_i32) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Opérations connectées synchrones
// ─────────────────────────────────────────────────────────────────────────

/// Initie une connexion vers un pair.
///
/// Wrappeur de `connect(2)`. Pour les sockets non-bloquants, retourne
/// immédiatement `EINPROGRESS` ; la connexion est terminée quand le
/// socket devient writable (via `poll`/`epoll`/io_uring).
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `address` : adresse du pair.
///
/// # Errors
///
/// - `ECONNREFUSED` : le pair refuse la connexion (Unix : socket absent).
/// - `EINPROGRESS` : connexion en cours (socket non-bloquant).
/// - `EALREADY` : connexion déjà en cours.
/// - `EISCONN` : socket déjà connecté.
/// - `ETIMEDOUT` : expiration du délai de connexion.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::{socket, connect};
/// use air_sys_types::net::{SocketAddr, SocketDomain, SocketType, UnixSocketAddr};
/// use air_sys_types::fd::AsFd;
///
/// let fd = socket(SocketDomain::Unix, SocketType::Stream, 0).expect("socket");
/// connect(fd.as_fd(), &SocketAddr::Unix(UnixSocketAddr::Path(
///     std::ffi::CString::new("/run/conduit.sock").expect("cstring"),
/// ))).expect("connect");
/// ```
pub fn connect(sock: BorrowedFd<'_>, address: &SocketAddr) -> Result<(), Errno> {
    let (raw, addrlen) = socket_addr_to_raw(address);
    let addr_ptr: *const u8 = raw.bytes.as_ptr();
    // SAFETY:
    // - connect(2) lit `addrlen` octets depuis `addr_ptr`.
    // - `raw` est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_connect(sock.as_raw_fd(), addr_ptr as u64, addrlen) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Accepte une connexion entrante.
///
/// Wrappeur de `accept4(2)` (préféré à `accept` car CLOEXEC atomique).
/// Le wrapper active `AcceptFlags::CLOEXEC` par défaut.
///
/// # Parameters
///
/// - `listener` : FD du socket en écoute.
/// - `flags` : [`AcceptFlags`] (CLOEXEC implicite).
///
/// # Errors
///
/// - `EAGAIN` / `EWOULDBLOCK` : pas de connexion disponible (non-bloquant).
/// - `EINTR` : interrompu par un signal (ADR-021 convention 2).
/// - `ECONNABORTED` : connexion abandonnée avant l'accept.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::accept4;
/// use air_sys_types::net::AcceptFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(listener: BorrowedFd<'_>) {
/// let result = accept4(listener, AcceptFlags::CLOEXEC).expect("accept4");
/// let _client_fd = result.fd;
/// # }
/// ```
pub fn accept4(listener: BorrowedFd<'_>, flags: AcceptFlags) -> Result<AcceptResult, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // Forcer CLOEXEC même si l'appelant l'a oublié
    let effective_flags = (flags | AcceptFlags::CLOEXEC).bits();
    // SAFETY:
    // - accept4(2) écrit l'adresse du pair dans `addr_ptr` (au plus `addrlen` octets)
    //   et met à jour `*addrlen_ptr` avec la longueur réelle.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - En cas de succès, retourne un nouveau FD valide >= 0.
    // - listener est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_accept4(
            listener.as_raw_fd(),
            addr_ptr as u64,
            addrlen_ptr as u64,
            effective_flags,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation)]
    let raw_fd = ret as i32;
    // SAFETY: Le kernel a retourné un FD valide.
    let fd = unsafe { AirOwnedFd::from_raw_fd(raw_fd) };
    let address = raw_to_socket_addr(&addr_buf.bytes, addrlen);
    Ok(AcceptResult { fd, address })
}

/// Envoie des données sur un socket connecté.
///
/// Wrappeur de `send(2)`. `MessageFlags::NOSIGNAL` est activé automatiquement
/// pour éviter `SIGPIPE` sur les connexions fermées.
///
/// # Parameters
///
/// - `sock` : FD du socket connecté.
/// - `buffer` : données à envoyer.
/// - `flags` : drapeaux [`MessageFlags`].
///
/// # Errors
///
/// - `EAGAIN` : socket non-bloquant et buffer kernel plein.
/// - `EINTR` : interrompu par un signal.
/// - `EPIPE` / `ECONNRESET` : connexion fermée par le pair.
/// - `EMSGSIZE` : message trop grand pour ce type de socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::send;
/// use air_sys_types::net::MessageFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let n = send(fd, b"hello", MessageFlags::empty()).expect("send");
/// # }
/// ```
pub fn send(sock: BorrowedFd<'_>, buffer: &[u8], flags: MessageFlags) -> Result<usize, Errno> {
    let buf_ptr: *const u8 = buffer.as_ptr();
    // MSG_NOSIGNAL ajouté automatiquement
    #[allow(clippy::cast_sign_loss)]
    let effective_flags = (flags.bits() | MSG_NOSIGNAL) as u64;
    // SAFETY:
    // - sendto(2) lit `buffer.len()` octets depuis `buf_ptr` (immutable borrow garanti).
    // - Les args address/addrlen sont NULL/0 pour un socket connecté.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_sendto(
            sock.as_raw_fd(),
            buf_ptr as u64,
            buffer.len(),
            effective_flags,
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Reçoit des données d'un socket connecté.
///
/// Wrappeur de `recv(2)`. Retourne 0 si le pair a fermé la connexion
/// proprement (EOF).
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `buffer` : buffer de destination.
/// - `flags` : drapeaux [`MessageFlags`].
///
/// # Errors
///
/// - `EAGAIN` : pas de données disponibles (non-bloquant).
/// - `EINTR` : interrompu par un signal.
/// - `ECONNRESET` : connexion réinitialisée par le pair.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::recv;
/// use air_sys_types::net::MessageFlags;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 1024];
/// let n = recv(fd, &mut buffer, MessageFlags::empty()).expect("recv");
/// # }
/// ```
pub fn recv(sock: BorrowedFd<'_>, buffer: &mut [u8], flags: MessageFlags) -> Result<usize, Errno> {
    let buf_ptr: *mut u8 = buffer.as_mut_ptr();
    #[allow(clippy::cast_sign_loss)]
    let flags_u64 = flags.bits() as u64;
    // SAFETY:
    // - recvfrom(2) écrit au plus `buffer.len()` octets dans `buf_ptr`.
    // - buffer est local (mutable borrow exclusif), valide pour la durée du syscall.
    // - Les args address/addrlen sont NULL/0 : on n'a pas besoin de l'adresse source.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_recvfrom(
            sock.as_raw_fd(),
            buf_ptr as u64,
            buffer.len(),
            flags_u64,
            0,
            0,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(ret as usize)
}

/// Envoie un message avec données de contrôle (ancillaires).
///
/// Wrappeur de `sendmsg(2)`. Supporte l'envoi multi-buffer et le
/// passage de FDs via `SCM_RIGHTS`. `NOSIGNAL` est activé par défaut.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `request` : description du message à envoyer.
///
/// # Errors
///
/// Voir [`send`]. De plus :
/// - `EINVAL` : nombre de FDs dans `request.fds` dépasse `SCM_MAX_FD`.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::sendmsg;
/// use air_sys_types::net::{IoSlice, MessageFlags, SendMessageRequest};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let data = b"hello";
/// let iov = [IoSlice::new(data)];
/// let req = SendMessageRequest {
///     iov: &iov,
///     address: None,
///     fds: &[],
///     flags: MessageFlags::empty(),
/// };
/// sendmsg(fd, &req).expect("sendmsg");
/// # }
/// ```
pub fn sendmsg(
    sock: BorrowedFd<'_>,
    request: &SendMessageRequest<'_>,
) -> Result<SendMessageResult, Errno> {
    // Convertir l'adresse optionnelle
    let (addr_storage, addr_storage_len) = if let Some(address) = request.address {
        let (s, l) = socket_addr_to_raw(address);
        (Some(s), l)
    } else {
        (None, 0u32)
    };

    // Construire le buffer cmsg (SCM_RIGHTS) si des FDs sont présents
    let cmsg_buf = build_scm_rights_cmsg(request.fds);

    let iov_ptr: *const IoSlice<'_> = request.iov.as_ptr();

    let (name_ptr, name_len) = if let Some(ref s) = addr_storage {
        (s.bytes.as_ptr() as u64, addr_storage_len)
    } else {
        (0u64, 0u32)
    };

    let (ctrl_ptr, ctrl_len) = if cmsg_buf.is_empty() {
        (0u64, 0u64)
    } else {
        (cmsg_buf.as_ptr() as u64, cmsg_buf.len() as u64)
    };

    let mut msghdr = KernelMsghdr {
        msg_name: name_ptr,
        msg_namelen: name_len,
        _pad: 0,
        msg_iov: iov_ptr as u64,
        msg_iovlen: request.iov.len() as u64,
        msg_control: ctrl_ptr,
        msg_controllen: ctrl_len,
        msg_flags: 0,
        _pad2: 0,
    };

    #[allow(clippy::cast_sign_loss)]
    let effective_flags = (request.flags.bits() | MSG_NOSIGNAL) as u64;
    let hdr_ptr: *mut KernelMsghdr = &mut msghdr;

    // SAFETY:
    // - sendmsg(2) lit la structure msghdr pointée par hdr_ptr et les buffers iov.
    // - Tous les pointeurs (iov, cmsg, address) sont valides pour la durée du syscall,
    //   garantis par les lifetimes de SendMessageRequest.
    // - IoSlice est #[repr(C)] compatible avec struct iovec.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_sendmsg(sock.as_raw_fd(), hdr_ptr as u64, effective_flags) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    Ok(SendMessageResult {
        bytes_sent: ret as usize,
    })
}

/// Reçoit un message avec données de contrôle (ancillaires).
///
/// Wrappeur de `recvmsg(2)`. Les FDs reçus via `SCM_RIGHTS` sont
/// automatiquement encapsulés dans des [`OwnedFd`] avec `CLOEXEC`
/// si [`MessageFlags::CMSG_CLOEXEC`] est dans `request.flags`.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `request` : buffers de destination et flags.
///
/// # Errors
///
/// Voir [`recv`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::recvmsg;
/// use air_sys_types::net::{IoSliceMut, MessageFlags, ReceiveMessageRequest};
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let mut buffer = [0u8; 1024];
/// let mut iov = [IoSliceMut::new(&mut buffer)];
/// let mut req = ReceiveMessageRequest {
///     iov: &mut iov,
///     flags: MessageFlags::CMSG_CLOEXEC,
/// };
/// let result = recvmsg(fd, &mut req).expect("recvmsg");
/// // result.fds contient les OwnedFd reçus via SCM_RIGHTS
/// # }
/// ```
pub fn recvmsg(
    sock: BorrowedFd<'_>,
    request: &mut ReceiveMessageRequest<'_>,
) -> Result<ReceiveMessageResult, Errno> {
    // Buffer cmsg de 1 KiO pour recevoir les données de contrôle (FDs, creds…)
    let mut cmsg_buf = [0u8; 1024];
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;

    let iov_ptr: *mut IoSliceMut<'_> = request.iov.as_mut_ptr();
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    let cmsg_ptr: *mut u8 = cmsg_buf.as_mut_ptr();

    let mut msghdr = KernelMsghdr {
        msg_name: addr_ptr as u64,
        msg_namelen: addrlen,
        _pad: 0,
        msg_iov: iov_ptr as u64,
        msg_iovlen: request.iov.len() as u64,
        msg_control: cmsg_ptr as u64,
        msg_controllen: cmsg_buf.len() as u64,
        msg_flags: 0,
        _pad2: 0,
    };

    #[allow(clippy::cast_sign_loss)]
    let flags_u64 = request.flags.bits() as u64;
    let hdr_ptr: *mut KernelMsghdr = &mut msghdr;

    // SAFETY:
    // - recvmsg(2) écrit dans les buffers iov et cmsg, et met à jour msghdr.
    // - Tous les buffers (iov, cmsg, address) sont locaux valides pour la durée du syscall.
    // - IoSliceMut est #[repr(C)] compatible avec struct iovec.
    // - Le kernel met à jour msg_namelen avec la longueur réelle de l'adresse.
    // - sock est garanti ouvert par BorrowedFd.
    // Note : on passe également addrlen_ptr mais en réalité le kernel met à jour
    // msg_namelen dans la structure msghdr ; on le récupère après l'appel.
    let ret = unsafe { raw_syscall_recvmsg(sock.as_raw_fd(), hdr_ptr as u64, flags_u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // Lire msg_namelen mis à jour par le kernel
    let returned_addrlen = msghdr.msg_namelen;
    // Lire msg_controllen mis à jour par le kernel
    #[allow(clippy::cast_possible_truncation)]
    let returned_cmsg_len = msghdr.msg_controllen as usize;
    // Lire msg_flags mis à jour par le kernel
    let returned_flags_bits = msghdr.msg_flags;

    let _ = addrlen_ptr; // addr_len mis à jour via msghdr.msg_namelen

    let address = raw_to_socket_addr(&addr_buf.bytes, returned_addrlen);
    let fds = parse_scm_rights(&cmsg_buf, returned_cmsg_len);

    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    let bytes_received = ret as usize;

    let flags = MessageFlags::from_bits_truncate(returned_flags_bits);

    Ok(ReceiveMessageResult {
        bytes_received,
        address,
        fds,
        flags,
    })
}

/// Ferme partiellement ou totalement un socket connecté.
///
/// Wrappeur de `shutdown(2)`. Différent de `close` : `shutdown` termine
/// la connexion de façon propre sans fermer le FD.
///
/// # Parameters
///
/// - `sock` : FD du socket.
/// - `mode` : direction(s) à fermer.
///
/// # Errors
///
/// - `ENOTCONN` : socket non connecté.
/// - `ENOTSOCK` : FD n'est pas un socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::shutdown;
/// use air_sys_types::net::ShutdownMode;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// shutdown(fd, ShutdownMode::Write).expect("shutdown");
/// # }
/// ```
pub fn shutdown(sock: BorrowedFd<'_>, mode: ShutdownMode) -> Result<(), Errno> {
    let how = mode as i32;
    // SAFETY:
    // - shutdown(2) ne touche à aucune mémoire utilisateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe { raw_syscall_shutdown(sock.as_raw_fd(), how) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Opérations utilitaires
// ─────────────────────────────────────────────────────────────────────────

/// Retourne l'adresse locale du socket.
///
/// # Errors
///
/// - `ENOTSOCK` : FD n'est pas un socket.
/// - `ENOBUFS` : mémoire système insuffisante.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::getsockname;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let address = getsockname(fd).expect("getsockname");
/// # }
/// ```
pub fn getsockname(sock: BorrowedFd<'_>) -> Result<SocketAddr, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // SAFETY:
    // - getsockname(2) écrit l'adresse locale dans addr_ptr (au plus *addrlen_ptr octets)
    //   et met à jour *addrlen_ptr avec la longueur réelle.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_getsockname(sock.as_raw_fd(), addr_ptr as u64, addrlen_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    raw_to_socket_addr(&addr_buf.bytes, addrlen).ok_or_else(|| {
        // Famille inconnue ou buffer trop court : errno EAFNOSUPPORT
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(97).unwrap()) // EAFNOSUPPORT = 97
    })
}

/// Retourne l'adresse du pair connecté.
///
/// # Errors
///
/// - `ENOTCONN` : socket non connecté.
/// - `ENOTSOCK` : FD n'est pas un socket.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::getpeername;
/// use air_sys_types::fd::BorrowedFd;
///
/// # fn example(fd: BorrowedFd<'_>) {
/// let address = getpeername(fd).expect("getpeername");
/// # }
/// ```
pub fn getpeername(sock: BorrowedFd<'_>) -> Result<SocketAddr, Errno> {
    let mut addr_buf = RawSockaddrStorage {
        bytes: [0u8; MAX_SOCKADDR_LEN],
    };
    // MAX_SOCKADDR_LEN = 128, valeur connue < u32::MAX : la troncature n'est pas possible.
    #[allow(clippy::cast_possible_truncation)]
    let mut addrlen: u32 = MAX_SOCKADDR_LEN as u32;
    let addr_ptr: *mut u8 = addr_buf.bytes.as_mut_ptr();
    let addrlen_ptr: *mut u32 = &mut addrlen;
    // SAFETY:
    // - getpeername(2) écrit l'adresse du pair dans addr_ptr et met à jour *addrlen_ptr.
    // - addr_buf et addrlen sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret =
        unsafe { raw_syscall_getpeername(sock.as_raw_fd(), addr_ptr as u64, addrlen_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md, section
    // `net`). La closure `None` (`EAFNOSUPPORT`) est inatteignable par
    // construction : `getpeername(2)` réussit sur un socket créé via l'API safe,
    // dont le domaine ∈ {Unix(1), Ipv4(2), Ipv6(10)} (`SocketDomain`) — les trois
    // familles que `raw_to_socket_addr` décode toujours en `Some`. Les gardes de
    // troncature internes (`len < 16`/`< 28`) sont testées séparément.
    raw_to_socket_addr(&addr_buf.bytes, addrlen).ok_or_else(|| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(97).unwrap()) // EAFNOSUPPORT
    })
}

/// Crée une paire de sockets connectés.
///
/// Wrappeur de `socketpair(2)`. Équivalent à créer un pipe mais
/// pour les sockets Unix. Les deux FDs retournés sont symétriques.
///
/// Seuls les sockets Unix (`AF_UNIX`) supportent `socketpair` sur Linux.
/// `SOCK_CLOEXEC` est ajouté automatiquement.
///
/// # Parameters
///
/// - `domain` : doit être [`SocketDomain::Unix`] sur Linux.
/// - `ty` : type de socket.
/// - `protocol` : 0 = défaut.
///
/// # Errors
///
/// - `EAFNOSUPPORT` : domaine non supporté (non-Unix).
/// - `EMFILE`/`ENFILE` : quotas FD atteints.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::net::socketpair;
/// use air_sys_types::net::{SocketDomain, SocketType};
///
/// let (fd_a, fd_b) = socketpair(SocketDomain::Unix, SocketType::Stream, 0)
///     .expect("socketpair");
/// ```
pub fn socketpair(
    domain: SocketDomain,
    ty: SocketType,
    protocol: i32,
) -> Result<(AirOwnedFd, AirOwnedFd), Errno> {
    let mut sv = [0i32; 2];
    let sv_ptr: *mut i32 = sv.as_mut_ptr();
    let domain_raw = domain as i32;
    let ty_raw = (ty as i32) | SOCK_CLOEXEC;
    // SAFETY:
    // - socketpair(2) écrit deux FDs dans sv[0..2].
    // - sv est local, valide pour la durée du syscall.
    // - En cas de succès, sv[0] et sv[1] sont des FDs valides >= 0.
    let ret = unsafe { raw_syscall_socketpair(domain_raw, ty_raw, protocol, sv_ptr as u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // SAFETY: Le kernel a retourné deux FDs valides dans sv.
    let fd_a = unsafe { AirOwnedFd::from_raw_fd(sv[0]) };
    let fd_b = unsafe { AirOwnedFd::from_raw_fd(sv[1]) };
    Ok((fd_a, fd_b))
}

// ─────────────────────────────────────────────────────────────────────────
// Options de socket (typées par option — ADR-021 convention 3)
// ─────────────────────────────────────────────────────────────────────────

/// Lit l'option `SO_KEEPALIVE`.
pub fn get_so_keepalive(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_KEEPALIVE).map(|v| v != 0)
}

/// Définit l'option `SO_KEEPALIVE`.
pub fn set_so_keepalive(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_KEEPALIVE, i32::from(enable))
}

/// Lit l'option `SO_REUSEADDR`.
pub fn get_so_reuseaddr(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_REUSEADDR).map(|v| v != 0)
}

/// Définit l'option `SO_REUSEADDR`.
pub fn set_so_reuseaddr(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_REUSEADDR, i32::from(enable))
}

/// Lit l'option `SO_REUSEPORT`.
pub fn get_so_reuseport(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_REUSEPORT).map(|v| v != 0)
}

/// Définit l'option `SO_REUSEPORT`.
pub fn set_so_reuseport(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, SOL_SOCKET, SO_REUSEPORT, i32::from(enable))
}

/// Lit l'option `TCP_NODELAY` (désactivation de l'algorithme Nagle).
pub fn get_tcp_nodelay(sock: BorrowedFd<'_>) -> Result<bool, Errno> {
    getsockopt_i32(sock, IPPROTO_TCP, TCP_NODELAY).map(|v| v != 0)
}

/// Définit l'option `TCP_NODELAY`.
pub fn set_tcp_nodelay(sock: BorrowedFd<'_>, enable: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_TCP, TCP_NODELAY, i32::from(enable))
}

/// Lit la taille du buffer de réception (`SO_RCVBUF`).
pub fn get_so_rcvbuf(sock: BorrowedFd<'_>) -> Result<u32, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_RCVBUF).map(|v| {
        // Le kernel peut retourner une valeur positive ; on la traite comme u32.
        #[allow(clippy::cast_sign_loss)]
        let u = v as u32;
        u
    })
}

/// Définit la taille du buffer de réception.
pub fn set_so_rcvbuf(sock: BorrowedFd<'_>, size: u32) -> Result<(), Errno> {
    // Le kernel interprète la valeur comme i32 ; saturer à i32::MAX si trop grand.
    #[allow(clippy::cast_possible_truncation)]
    let val = if size > i32::MAX as u32 {
        i32::MAX
    } else {
        size as i32
    };
    setsockopt_i32(sock, SOL_SOCKET, SO_RCVBUF, val)
}

/// Lit la taille du buffer d'envoi (`SO_SNDBUF`).
pub fn get_so_sndbuf(sock: BorrowedFd<'_>) -> Result<u32, Errno> {
    getsockopt_i32(sock, SOL_SOCKET, SO_SNDBUF).map(|v| {
        #[allow(clippy::cast_sign_loss)]
        let u = v as u32;
        u
    })
}

/// Définit la taille du buffer d'envoi.
pub fn set_so_sndbuf(sock: BorrowedFd<'_>, size: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if size > i32::MAX as u32 {
        i32::MAX
    } else {
        size as i32
    };
    setsockopt_i32(sock, SOL_SOCKET, SO_SNDBUF, val)
}

/// Lit l'erreur socket en attente (`SO_ERROR`) et l'efface.
///
/// Retourne `None` si aucune erreur n'est en attente.
pub fn get_so_error(sock: BorrowedFd<'_>) -> Result<Option<Errno>, Errno> {
    let val = getsockopt_i32(sock, SOL_SOCKET, SO_ERROR)?;
    if val == 0 {
        Ok(None)
    } else {
        let nz = NonZeroI32::new(val).ok_or_else(|| {
            // Ne se produit pas : val != 0 ici
            #[allow(clippy::unwrap_used)]
            Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL
        })?;
        Ok(Some(Errno::from_nonzero(nz)))
    }
}

/// Lit les credentials du pair Unix (`SO_PEERCRED`).
///
/// Uniquement sur les sockets Unix (domain `AF_UNIX`).
pub fn get_so_peercred(sock: BorrowedFd<'_>) -> Result<UnixCredentials, Errno> {
    // struct ucred { pid_t pid; uid_t uid; gid_t gid; } = 3 * i32 = 12 octets
    let mut cred = [0i32; 3];
    let mut length: u32 = 12;
    let cred_ptr: *mut i32 = cred.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit la structure ucred (12 octets) dans cred.
    // - cred et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_PEERCRED,
            cred_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // cred[0] = pid (i32), cred[1] = uid (u32), cred[2] = gid (u32)
    let pid_raw = cred[0];
    #[allow(clippy::cast_sign_loss)]
    let uid = cred[1] as u32;
    #[allow(clippy::cast_sign_loss)]
    let gid = cred[2] as u32;
    let nz = NonZeroI32::new(pid_raw).ok_or_else(|| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL : pid=0 inattendu
    })?;
    Ok(UnixCredentials {
        pid: Pid::from_nonzero(nz),
        uid,
        gid,
    })
}

/// Lit l'option `SO_LINGER`.
pub fn get_so_linger(sock: BorrowedFd<'_>) -> Result<LingerOption, Errno> {
    // struct linger { int l_onoff; int l_linger; } = 8 octets
    let mut linger = [0i32; 2];
    let mut length: u32 = 8;
    let linger_ptr: *mut i32 = linger.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit la structure linger (8 octets) dans linger.
    // - linger et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_LINGER,
            linger_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    if linger[0] == 0 {
        Ok(LingerOption::Disabled)
    } else {
        #[allow(clippy::cast_sign_loss)]
        let secs = linger[1] as u64;
        Ok(LingerOption::Enabled(core::time::Duration::from_secs(secs)))
    }
}

/// Définit l'option `SO_LINGER`.
pub fn set_so_linger(sock: BorrowedFd<'_>, linger: LingerOption) -> Result<(), Errno> {
    let (l_onoff, l_linger): (i32, i32) = match linger {
        LingerOption::Disabled => (0, 0),
        LingerOption::Enabled(d) => {
            // Saturer à i32::MAX secondes (≈ 68 ans)
            let secs = d.as_secs();
            #[allow(clippy::cast_possible_truncation)]
            let secs_i32 = if secs > i32::MAX as u64 {
                i32::MAX
            } else {
                secs as i32
            };
            (1, secs_i32)
        }
    };
    let buffer = [l_onoff, l_linger];
    let buf_ptr: *const i32 = buffer.as_ptr();
    let length: u32 = 8;
    // SAFETY:
    // - setsockopt(2) lit 8 octets depuis buf_ptr (struct linger).
    // - buffer est local, valide pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_LINGER,
            buf_ptr as u64,
            length,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lie le socket à une interface réseau (`SO_BINDTODEVICE`).
pub fn set_so_bindtodevice(sock: BorrowedFd<'_>, ifname: &CStr) -> Result<(), Errno> {
    let bytes = ifname.to_bytes_with_nul();
    let ptr: *const u8 = bytes.as_ptr();
    #[allow(clippy::cast_possible_truncation)]
    let length = bytes.len() as u32;
    // SAFETY:
    // - setsockopt(2) lit `length` octets depuis `ptr` (le nom d'interface NUL-terminé).
    // - Le CStr garantit la validité du pointeur et la présence du NUL terminateur.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_BINDTODEVICE,
            ptr as u64,
            length,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit l'interface liée au socket.
pub fn get_so_bindtodevice(sock: BorrowedFd<'_>) -> Result<CString, Errno> {
    // IFNAMSIZ = 16 octets suffisent pour un nom d'interface Linux
    let mut buffer = [0u8; 16];
    let mut length: u32 = 16;
    let buf_ptr: *mut u8 = buffer.as_mut_ptr();
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit le nom de l'interface (NUL-terminé) dans buffer.
    // - buffer et length sont locaux, valides pour la durée du syscall.
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            SO_BINDTODEVICE,
            buf_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // Trouver le NUL terminateur pour construire le CString
    let nul_pos = buffer
        .iter()
        .position(|&b| b == 0)
        .unwrap_or(length as usize);
    // COUVERTURE (ADR-035, STRUCTURAL — cf. docs/COVERAGE-EXCEPTIONS.md, section
    // `net`). La closure `map_err` (`EINVAL`) est inatteignable par construction :
    // `nul_pos` est la position du **premier** `NUL` (ou `length` à défaut), donc
    // `buffer[..nul_pos]` ne contient aucun `NUL` interne → `CString::new`
    // retourne toujours `Ok`.
    CString::new(&buffer[..nul_pos]).map_err(|_| {
        #[allow(clippy::unwrap_used)]
        Errno::from_nonzero(NonZeroI32::new(22).unwrap()) // EINVAL
    })
}

/// Définit le délai `TCP_KEEPIDLE` (secondes d'inactivité avant premier keepalive).
pub fn set_tcp_keepidle(sock: BorrowedFd<'_>, seconds: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if seconds > i32::MAX as u32 {
        i32::MAX
    } else {
        seconds as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPIDLE, val)
}

/// Définit le délai `TCP_KEEPINTVL` (secondes entre deux keepalives).
pub fn set_tcp_keepintvl(sock: BorrowedFd<'_>, seconds: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if seconds > i32::MAX as u32 {
        i32::MAX
    } else {
        seconds as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPINTVL, val)
}

/// Définit le nombre max de keepalives sans réponse (`TCP_KEEPCNT`).
pub fn set_tcp_keepcnt(sock: BorrowedFd<'_>, count: u32) -> Result<(), Errno> {
    #[allow(clippy::cast_possible_truncation)]
    let val = if count > i32::MAX as u32 {
        i32::MAX
    } else {
        count as i32
    };
    setsockopt_i32(sock, IPPROTO_TCP, TCP_KEEPCNT, val)
}

/// Définit le TTL IP (`IP_TTL`).
pub fn set_ip_ttl(sock: BorrowedFd<'_>, ttl: u8) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_IP, IP_TTL, i32::from(ttl))
}

/// Restreint les sockets IPv6 aux connexions IPv6-only (`IPV6_V6ONLY`).
pub fn set_ipv6_v6only(sock: BorrowedFd<'_>, v6only: bool) -> Result<(), Errno> {
    setsockopt_i32(sock, IPPROTO_IPV6, IPV6_V6ONLY, i32::from(v6only))
}

// ─────────────────────────────────────────────────────────────────────────
// Options à structure `timeval` — délais de réception / d'envoi
// (`SO_RCVTIMEO` / `SO_SNDTIMEO`). Options **structurées** (16 octets) : la
// couche 0 pose/lit un `Timeval` typé (jamais un `setsockopt` générique).
// ─────────────────────────────────────────────────────────────────────────

/// Décode un `timeval` **rendu par `getsockopt`** en délai optionnel.
///
/// Fonction **pure** (aucun syscall) : le kernel écrit une structure `timeval`
/// que NOUS relisons ensuite. Un `timeval` nul (`{0, 0}`) signifie « aucun délai
/// armé » (le socket bloque indéfiniment) → `None` ; toute autre valeur →
/// `Some(timeval)`. Isolé pour être **property-testé** (cf. exigence fuzz du
/// décodage `getsockopt`).
fn decode_timeout(tv: Timeval) -> Option<Timeval> {
    if tv.tv_sec == 0 && tv.tv_usec == 0 {
        None
    } else {
        Some(tv)
    }
}

/// Pose un délai (`SO_RCVTIMEO` / `SO_SNDTIMEO`) via un `timeval` de 16 octets.
///
/// `None` ⇒ `timeval` nul = « pas de délai » (sémantique kernel : blocage sans
/// limite). Helper **interne** paramétré par `optname` (les points d'entrée
/// publics restent dédiés, ADR-021 conv. 3).
fn set_socket_timeout(
    sock: BorrowedFd<'_>,
    optname: i32,
    timeout: Option<Timeval>,
) -> Result<(), Errno> {
    let tv = timeout.unwrap_or(Timeval {
        tv_sec: 0,
        tv_usec: 0,
    });
    let tv_ptr: *const Timeval = &tv;
    // SAFETY:
    // - setsockopt(2) lit `TIMEVAL_LEN` (16) octets depuis tv_ptr (struct timeval).
    // - tv est local, valide pour la durée du syscall ; layout #[repr(C)] fidèle
    //   (assertion const `size_of::<Timeval>() == 16`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            optname,
            tv_ptr as u64,
            TIMEVAL_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Lit un délai (`SO_RCVTIMEO` / `SO_SNDTIMEO`). Helper **interne** paramétré par
/// `optname`.
fn get_socket_timeout(sock: BorrowedFd<'_>, optname: i32) -> Result<Option<Timeval>, Errno> {
    let mut tv = Timeval {
        tv_sec: 0,
        tv_usec: 0,
    };
    let mut length: u32 = TIMEVAL_LEN;
    let tv_ptr: *mut Timeval = &mut tv;
    let len_ptr: *mut u32 = &mut length;
    // SAFETY:
    // - getsockopt(2) écrit au plus `length` (16) octets dans tv (struct timeval).
    // - tv et length sont locaux, valides pour la durée du syscall ; layout
    //   #[repr(C)] fidèle (assertion const `size_of::<Timeval>() == 16`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_getsockopt(
            sock.as_raw_fd(),
            SOL_SOCKET,
            optname,
            tv_ptr as u64,
            len_ptr as u64,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(decode_timeout(tv))
}

/// Définit le délai de **réception** (`SO_RCVTIMEO`). `None` désarme le délai.
pub fn set_receive_timeout(sock: BorrowedFd<'_>, timeout: Option<Timeval>) -> Result<(), Errno> {
    set_socket_timeout(sock, SO_RCVTIMEO, timeout)
}

/// Lit le délai de **réception** (`SO_RCVTIMEO`). `None` = aucun délai armé.
pub fn receive_timeout(sock: BorrowedFd<'_>) -> Result<Option<Timeval>, Errno> {
    get_socket_timeout(sock, SO_RCVTIMEO)
}

/// Définit le délai d'**envoi** (`SO_SNDTIMEO`). `None` désarme le délai.
pub fn set_send_timeout(sock: BorrowedFd<'_>, timeout: Option<Timeval>) -> Result<(), Errno> {
    set_socket_timeout(sock, SO_SNDTIMEO, timeout)
}

/// Lit le délai d'**envoi** (`SO_SNDTIMEO`). `None` = aucun délai armé.
pub fn send_timeout(sock: BorrowedFd<'_>) -> Result<Option<Timeval>, Errno> {
    get_socket_timeout(sock, SO_SNDTIMEO)
}

// ─────────────────────────────────────────────────────────────────────────
// Appartenance à un groupe multicast — options **structurées**
// `ip_mreq` (v4) / `ipv6_mreq` (v6). Fonctions dédiées typées (ADR-021).
// ─────────────────────────────────────────────────────────────────────────

/// Pose une option d'appartenance multicast **IPv4** (`ip_mreq`, 8 octets).
/// Helper **interne** paramétré par `optname` (`IP_ADD`/`IP_DROP_MEMBERSHIP`).
fn set_ip_membership_v4(
    sock: BorrowedFd<'_>,
    optname: i32,
    membership: &IpMembershipV4,
) -> Result<(), Errno> {
    let ptr: *const IpMembershipV4 = membership;
    // SAFETY:
    // - setsockopt(2) lit `IP_MREQ_LEN` (8) octets depuis ptr (struct ip_mreq).
    // - `membership` est valide pour la durée de l'appel (référence empruntée) ;
    //   layout #[repr(C)] fidèle (assertion const `size_of == 8`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            IPPROTO_IP,
            optname,
            ptr as u64,
            IP_MREQ_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// Pose une option d'appartenance multicast **IPv6** (`ipv6_mreq`, 20 octets).
/// Helper **interne** paramétré par `optname` (`IPV6_ADD`/`IPV6_DROP_MEMBERSHIP`).
fn set_ip_membership_v6(
    sock: BorrowedFd<'_>,
    optname: i32,
    membership: &IpMembershipV6,
) -> Result<(), Errno> {
    let ptr: *const IpMembershipV6 = membership;
    // SAFETY:
    // - setsockopt(2) lit `IPV6_MREQ_LEN` (20) octets depuis ptr (struct ipv6_mreq).
    // - `membership` est valide pour la durée de l'appel (référence empruntée) ;
    //   layout #[repr(C)] fidèle (assertion const `size_of == 20`).
    // - sock est garanti ouvert par BorrowedFd.
    let ret = unsafe {
        raw_syscall_setsockopt(
            sock.as_raw_fd(),
            IPPROTO_IPV6,
            optname,
            ptr as u64,
            IPV6_MREQ_LEN,
        )
    };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

/// **Rejoint** un groupe multicast IPv4 (`IP_ADD_MEMBERSHIP`, `struct ip_mreq`).
pub fn join_multicast_v4(sock: BorrowedFd<'_>, membership: &IpMembershipV4) -> Result<(), Errno> {
    set_ip_membership_v4(sock, IP_ADD_MEMBERSHIP, membership)
}

/// **Quitte** un groupe multicast IPv4 (`IP_DROP_MEMBERSHIP`, `struct ip_mreq`).
pub fn leave_multicast_v4(sock: BorrowedFd<'_>, membership: &IpMembershipV4) -> Result<(), Errno> {
    set_ip_membership_v4(sock, IP_DROP_MEMBERSHIP, membership)
}

/// **Rejoint** un groupe multicast IPv6 (`IPV6_ADD_MEMBERSHIP`, `struct ipv6_mreq`).
pub fn join_multicast_v6(sock: BorrowedFd<'_>, membership: &IpMembershipV6) -> Result<(), Errno> {
    set_ip_membership_v6(sock, IPV6_ADD_MEMBERSHIP, membership)
}

/// **Quitte** un groupe multicast IPv6 (`IPV6_DROP_MEMBERSHIP`, `struct ipv6_mreq`).
pub fn leave_multicast_v6(sock: BorrowedFd<'_>, membership: &IpMembershipV6) -> Result<(), Errno> {
    set_ip_membership_v6(sock, IPV6_DROP_MEMBERSHIP, membership)
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — x86_64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_socket(domain: i32, ty: i32, protocol: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socket (x86_64 = 41). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 41_i64,
            in("rdi") i64::from(domain),
            in("rsi") i64::from(ty),
            in("rdx") i64::from(protocol),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_bind(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_bind (x86_64 = 49). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 49_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_listen(fd: i32, backlog: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_listen (x86_64 = 50). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 50_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(backlog),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_connect(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_connect (x86_64 = 42). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 42_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_accept4(fd: i32, address: u64, addrlen: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_accept4 (x86_64 = 288). Le kernel écrit l'adresse du pair dans address.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 288_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            in("r10") i64::from(flags),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sendto(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendto (x86_64 = 44). Le kernel lit `length` octets depuis `buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 44_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") length,
            in("r10") flags,
            in("r8") address,
            in("r9") i64::from(addrlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_recvfrom(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvfrom (x86_64 = 45). Le kernel écrit au plus `length` octets dans `buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 45_i64,
            in("rdi") i64::from(fd),
            in("rsi") buffer,
            in("rdx") length,
            in("r10") flags,
            in("r8") address,
            in("r9") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sendmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendmsg (x86_64 = 46). Le kernel lit la msghdr et les buffers associés.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 46_i64,
            in("rdi") i64::from(fd),
            in("rsi") msghdr,
            in("rdx") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_recvmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvmsg (x86_64 = 47). Le kernel écrit dans les buffers iov et cmsg.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 47_i64,
            in("rdi") i64::from(fd),
            in("rsi") msghdr,
            in("rdx") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_shutdown(fd: i32, how: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_shutdown (x86_64 = 48). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 48_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(how),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getsockname(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockname (x86_64 = 51). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 51_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getpeername(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getpeername (x86_64 = 52). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 52_i64,
            in("rdi") i64::from(fd),
            in("rsi") address,
            in("rdx") addrlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_socketpair(domain: i32, ty: i32, protocol: i32, sv: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socketpair (x86_64 = 53). Le kernel écrit deux FDs dans sv[0..2].
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 53_i64,
            in("rdi") i64::from(domain),
            in("rsi") i64::from(ty),
            in("rdx") i64::from(protocol),
            in("r10") sv,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockopt (x86_64 = 55). Le kernel écrit *optlen octets dans optval.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 55_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(level),
            in("rdx") i64::from(optname),
            in("r10") optval,
            in("r8") optlen,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_setsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsockopt (x86_64 = 54). Le kernel lit optlen octets depuis optval.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 54_i64,
            in("rdi") i64::from(fd),
            in("rsi") i64::from(level),
            in("rdx") i64::from(optname),
            in("r10") optval,
            in("r8") i64::from(optlen),
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Helpers syscall bruts — aarch64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_socket(domain: i32, ty: i32, protocol: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socket (aarch64 = 198). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 198_i64,
            inout("x0") i64::from(domain) => ret,
            in("x1") i64::from(ty),
            in("x2") i64::from(protocol),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_bind(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_bind (aarch64 = 200). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 200_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_listen(fd: i32, backlog: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_listen (aarch64 = 201). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 201_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(backlog),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_connect(fd: i32, address: u64, addrlen: u32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_connect (aarch64 = 203). Le kernel lit `addrlen` octets depuis `address`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 203_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_accept4(fd: i32, address: u64, addrlen: u64, flags: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_accept4 (aarch64 = 242). Le kernel écrit l'adresse du pair dans address.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 242_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            in("x3") i64::from(flags),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sendto(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendto (aarch64 = 206). Le kernel lit `length` octets depuis `buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 206_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") length,
            in("x3") flags,
            in("x4") address,
            in("x5") i64::from(addrlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_recvfrom(
    fd: i32,
    buffer: u64,
    length: usize,
    flags: u64,
    address: u64,
    addrlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvfrom (aarch64 = 207). Le kernel écrit au plus `length` octets dans `buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 207_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") buffer,
            in("x2") length,
            in("x3") flags,
            in("x4") address,
            in("x5") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sendmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_sendmsg (aarch64 = 211). Le kernel lit la msghdr et les buffers associés.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 211_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") msghdr,
            in("x2") flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_recvmsg(fd: i32, msghdr: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_recvmsg (aarch64 = 212). Le kernel écrit dans les buffers iov et cmsg.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 212_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") msghdr,
            in("x2") flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_shutdown(fd: i32, how: i32) -> i64 {
    let ret: i64;
    // SAFETY: SYS_shutdown (aarch64 = 210). Pas d'accès mémoire utilisateur.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 210_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(how),
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getsockname(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockname (aarch64 = 204). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 204_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getpeername(fd: i32, address: u64, addrlen: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getpeername (aarch64 = 205). Le kernel écrit l'adresse et met à jour addrlen.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 205_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") address,
            in("x2") addrlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_socketpair(domain: i32, ty: i32, protocol: i32, sv: u64) -> i64 {
    let ret: i64;
    // SAFETY: SYS_socketpair (aarch64 = 199). Le kernel écrit deux FDs dans sv[0..2].
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 199_i64,
            inout("x0") i64::from(domain) => ret,
            in("x1") i64::from(ty),
            in("x2") i64::from(protocol),
            in("x3") sv,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u64,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_getsockopt (aarch64 = 209). Le kernel écrit *optlen octets dans optval.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 209_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(level),
            in("x2") i64::from(optname),
            in("x3") optval,
            in("x4") optlen,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_setsockopt(
    fd: i32,
    level: i32,
    optname: i32,
    optval: u64,
    optlen: u32,
) -> i64 {
    let ret: i64;
    // SAFETY: SYS_setsockopt (aarch64 = 208). Le kernel lit optlen octets depuis optval.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 208_i64,
            inout("x0") i64::from(fd) => ret,
            in("x1") i64::from(level),
            in("x2") i64::from(optname),
            in("x3") optval,
            in("x4") i64::from(optlen),
            options(nostack, preserves_flags),
        );
    }
    ret
}

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

#[cfg(all(test, target_os = "linux"))]
mod tests;