cloudfox-coreshift-core 2.27.0

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

//! `fork`/`execve` backend.
//!
//! Owns the child setup protocol (`ChildSetupOp`, the error pipe handshake),
//! fd-policy handling in the child, and the `fork` launch path used when
//! [`SpawnBackend::Fork`](crate::spawn::SpawnBackend::Fork) is selected.

use std::ffi::CString;
use std::os::unix::io::RawFd;

use crate::CoreError;
use crate::error::syscall_ret;
use crate::signal::SignalRuntime;
use libc::{c_char, pid_t};

use super::exec::{ExecArgv, ExecContext};
use super::{
    Pipes, Process, ProcessGroup, SpawnDrain, SpawnFdPolicy, SpawnOptions, environ, errno,
    make_cloexec_pipe,
};

#[repr(u8)]
#[derive(Clone, Copy)]
enum ChildSetupOp {
    DupStdin = 1,
    DupStdout = 2,
    DupStderr = 3,
    Setsid = 4,
    Chdir = 5,
    Setpgid = 6,
    SignalMask = 7,
    Execve = 8,
    CloseFds = 9,
    Seccomp = 10,
    /// `TIOCSCTTY` (pty mode) — claiming the slave as the child's controlling
    /// terminal. Added after the initial protocol shipped; numeric value 11 is
    /// stable and only affects the error message text.
    TtyCtl = 11,
    /// `PR_SET_PDEATHSIG` (opt-in `pdeath_signal`) — arming the parent-death
    /// signal in the child. Value 12 is stable and only affects the error text.
    Pdeathsig = 12,
}

impl ChildSetupOp {
    fn as_str(self) -> &'static str {
        match self {
            Self::DupStdin => "spawn child dup2 stdin",
            Self::DupStdout => "spawn child dup2 stdout",
            Self::DupStderr => "spawn child dup2 stderr",
            Self::Setsid => "spawn child setsid",
            Self::Chdir => "spawn child chdir",
            Self::Setpgid => "spawn child setpgid",
            Self::SignalMask => "spawn child signal setup",
            Self::Execve => "spawn child execve",
            Self::CloseFds => "spawn child fd policy scan",
            Self::Seccomp => "spawn child seccomp",
            Self::TtyCtl => "spawn child ttyctl",
            Self::Pdeathsig => "spawn child pdeathsig",
        }
    }

    fn from_u8(value: u8) -> Self {
        match value {
            1 => Self::DupStdin,
            2 => Self::DupStdout,
            3 => Self::DupStderr,
            4 => Self::Setsid,
            5 => Self::Chdir,
            6 => Self::Setpgid,
            7 => Self::SignalMask,
            8 => Self::Execve,
            9 => Self::CloseFds,
            10 => Self::Seccomp,
            11 => Self::TtyCtl,
            12 => Self::Pdeathsig,
            _ => Self::Execve,
        }
    }
}

unsafe fn report_child_setup_error(fd: RawFd, op: ChildSetupOp, code: i32) -> ! {
    let mut msg = [0u8; 5];
    msg[..4].copy_from_slice(&code.to_ne_bytes());
    msg[4] = op as u8;
    let mut written = 0;
    while written < msg.len() {
        let n = unsafe {
            libc::write(
                fd,
                msg[written..].as_ptr().cast::<libc::c_void>(),
                msg.len() - written,
            )
        };
        if n < 0 {
            let e = errno();
            // A signal can interrupt the write; retry rather than exiting
            // with a partial message, which the parent would misread as EOF
            // (i.e. a successful spawn) after the child exits.
            if e == libc::EINTR {
                continue;
            }
            break;
        }
        if n == 0 {
            break;
        }
        written += n as usize;
    }
    unsafe {
        libc::_exit(127);
    }
}

fn read_child_setup_error(fd: RawFd) -> Result<Option<CoreError>, CoreError> {
    let mut msg = [0u8; 5];
    let mut read_len = 0;
    loop {
        let n = unsafe {
            libc::read(
                fd,
                msg[read_len..].as_mut_ptr().cast::<libc::c_void>(),
                msg.len() - read_len,
            )
        };
        if n == 0 {
            if read_len == 0 {
                return Ok(None);
            }
            // EOF in the middle of a message: the child died (or closed the
            // pipe) before writing the complete error. Treat as a failure
            // rather than silently succeeding with a garbage message.
            return Err(CoreError::sys(
                libc::EIO,
                "fork child setup error: truncated message",
            ));
        }
        if n < 0 {
            let code = errno();
            if code == libc::EINTR {
                continue;
            }
            return Err(CoreError::sys(code, "read fork child setup error"));
        }
        read_len += n as usize;
        if read_len == msg.len() {
            let code = i32::from_ne_bytes([msg[0], msg[1], msg[2], msg[3]]);
            return Ok(Some(CoreError::sys(
                code,
                ChildSetupOp::from_u8(msg[4]).as_str(),
            )));
        }
    }
}

pub(super) fn collect_required_pipe_fds(pipes: &Pipes) -> Vec<RawFd> {
    let mut fds = Vec::new();
    if let Some(fd) = &pipes.stdin_r {
        fds.push(fd.raw());
    }
    if let Some(fd) = &pipes.stdin_w {
        fds.push(fd.raw());
    }
    if let Some(fd) = &pipes.stdout_r {
        fds.push(fd.raw());
    }
    if let Some(fd) = &pipes.stdout_w {
        fds.push(fd.raw());
    }
    if let Some(fd) = &pipes.stderr_r {
        fds.push(fd.raw());
    }
    if let Some(fd) = &pipes.stderr_w {
        fds.push(fd.raw());
    }
    fds
}

/// Close inherited descriptors in the child according to the fd policy.
///
/// The scan runs in the child *after* `fork()`, so it reflects the child's own
/// descriptor table and cannot be raced by other threads in the parent — a
/// parent-side snapshot would leak any fd opened between the snapshot and
/// `fork()`. `getdents64` into a fixed stack buffer keeps this
/// async-signal-safe (no allocation, no libc directory cursors). A scan
/// failure aborts the spawn through the setup-error pipe rather than silently
/// leaving every inherited fd open (a fail-open that would defeat the policy).
fn close_child_fds_for_policy(
    policy: &SpawnFdPolicy,
    required_fds: &[RawFd],
    child_error_w: RawFd,
) {
    match policy {
        SpawnFdPolicy::CloexecOnly => {}
        SpawnFdPolicy::CloseFrom3 | SpawnFdPolicy::Allowlist(_) => {
            let dir_fd = unsafe {
                libc::open(
                    c"/proc/self/fd".as_ptr(),
                    libc::O_RDONLY | libc::O_DIRECTORY | libc::O_CLOEXEC,
                )
            };
            if dir_fd < 0 {
                unsafe {
                    report_child_setup_error(child_error_w, ChildSetupOp::CloseFds, errno());
                }
            }

            let mut buf = [0u8; 4096];
            loop {
                let n = unsafe {
                    libc::syscall(
                        libc::SYS_getdents64,
                        dir_fd,
                        buf.as_mut_ptr().cast::<libc::c_void>(),
                        buf.len(),
                    )
                };
                if n < 0 {
                    let e = errno();
                    // A signal can interrupt the scan; retry rather than
                    // aborting it, which would silently fail the policy open.
                    if e == libc::EINTR {
                        continue;
                    }
                    unsafe {
                        report_child_setup_error(child_error_w, ChildSetupOp::CloseFds, e);
                    }
                }
                if n == 0 {
                    break;
                }
                let mut off = 0usize;
                while off + 19 <= n as usize {
                    // linux_dirent64 layout: d_ino(8) d_off(8) d_reclen(2)
                    // d_type(1) d_name[].
                    let reclen = u16::from_ne_bytes([buf[off + 16], buf[off + 17]]) as usize;
                    if reclen < 19 || off + reclen > n as usize {
                        break;
                    }
                    let name = &buf[off + 19..off + reclen];
                    let name_end = name.iter().position(|&b| b == 0).unwrap_or(name.len());
                    if let Some(fd) = std::str::from_utf8(&name[..name_end])
                        .ok()
                        .and_then(|s| s.parse::<RawFd>().ok())
                        && fd > 2
                        && fd != dir_fd
                        && !required_fds.contains(&fd)
                        && !matches!(
                            policy,
                            SpawnFdPolicy::Allowlist(allowlist) if allowlist.contains(&fd)
                        )
                    {
                        unsafe {
                            libc::close(fd);
                        }
                    }
                    off += reclen;
                }
            }
            unsafe {
                libc::close(dir_fd);
            }
        }
    }
}

/// Parent-side state captured before the spawn syscall and handed read-only to
/// the child. The pointer vectors must be built in the parent: under `vfork`
/// the child shares the parent's heap, so any allocation there would corrupt
/// the parent's allocator state.
pub(super) struct ChildContext<'a> {
    pub exe_ptr: *const c_char,
    pub argv: Vec<*mut c_char>,
    pub envp: Option<Vec<*mut c_char>>,
    pub cwd: Option<&'a CString>,
}

pub(super) fn prepare_child_context(ctx: &ExecContext) -> ChildContext<'_> {
    let exe_ptr = match &ctx.argv {
        ExecArgv::Dynamic(v) => v[0].as_ptr(),
    };
    ChildContext {
        exe_ptr,
        argv: ctx.get_argv_ptrs(),
        envp: ctx.get_envp_ptrs(),
        cwd: ctx.cwd.as_ref(),
    }
}

// Classic BPF instruction encodings (linux/bpf_common.h + linux/filter.h).
// Only the encodings needed by the session-containment program are defined.
const BPF_LD: u16 = 0x00; // load-class: LD
const BPF_W: u16 = 0x00; // load size: word (4 bytes)
const BPF_ABS: u16 = 0x20; // load mode: absolute offset
const BPF_JMP: u16 = 0x05; // class: JMP
const BPF_JEQ: u16 = 0x10; // jmp op: jump if equal
const BPF_K: u16 = 0x00; // src: 32-bit immediate
const BPF_RET: u16 = 0x06; // class: RET

const fn bpf_stmt(code: u16, k: u32) -> libc::sock_filter {
    libc::sock_filter {
        code,
        jt: 0,
        jf: 0,
        k,
    }
}

const fn bpf_jump(code: u16, k: u32, jt: u8, jf: u8) -> libc::sock_filter {
    libc::sock_filter { code, jt, jf, k }
}

/// `seccomp_data.arch` value (`AUDIT_ARCH_*`) for the native target. The
/// filter kills on an arch mismatch so a 32-bit (or otherwise unexpected)
/// personality cannot reinterpret the syscall numbers below.
#[cfg(target_arch = "aarch64")]
const AUDIT_ARCH_NATIVE: u32 = 0xC000_00B7; // EM_AARCH64 | 64-bit | little-endian
#[cfg(target_arch = "x86_64")]
const AUDIT_ARCH_NATIVE: u32 = 0xC000_003E; // EM_X86_64 | 64-bit | little-endian
#[cfg(target_arch = "arm")]
const AUDIT_ARCH_NATIVE: u32 = 0x4000_0028; // EM_ARM | 32-bit | little-endian
#[cfg(not(any(target_arch = "aarch64", target_arch = "x86_64", target_arch = "arm")))]
const AUDIT_ARCH_NATIVE: u32 = 0;

/// Seccomp program that locks a child — and, because filters are inherited
/// across `fork` and `execve` and can only be tightened, never loosened, by
/// the process itself — into the process group/session it was placed into by
/// [`child_entry`].
///
/// It denies the process-group/session escape syscalls:
/// - `setsid` — abandon the session and group `kill_group` targets;
/// - `setpgid` — move a process to a different group (this also covers
///   `setpgrp`, which on Linux is a libc alias for `setpgid(0, 0)`);
/// - `unshare` — create a new namespace (e.g. PID/USER) a descendant could
///   hide in;
/// - `setns` — join an attacker-selected namespace.
///
/// Everything else is allowed, so ordinary child behavior (`fork`, `exec`,
/// I/O, signals) is unaffected. Returns `EPERM` to the denied syscall.
///
/// The program is a static `[u8]`-free const array so the child installs it
/// without any allocation (async-signal-safe). Architecture mismatch is
/// answered with `SECCOMP_RET_KILL_PROCESS` so a wrong-arch personality
/// cannot even execute the denied syscall numbers.
#[cfg(any(target_arch = "aarch64", target_arch = "x86_64", target_arch = "arm"))]
static SESSION_CONTAINMENT_FILTER: [libc::sock_filter; 13] = [
    // offset 4 = seccomp_data.arch
    bpf_stmt(BPF_LD | BPF_W | BPF_ABS, 4),
    // if arch == native, skip the KILL (jt=1); else KILL (jf=0)
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_NATIVE, 1, 0),
    bpf_stmt(BPF_RET | BPF_K, libc::SECCOMP_RET_KILL_PROCESS),
    // offset 0 = seccomp_data.nr
    bpf_stmt(BPF_LD | BPF_W | BPF_ABS, 0),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_setsid as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_setpgid as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_unshare as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_setns as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_stmt(BPF_RET | BPF_K, libc::SECCOMP_RET_ALLOW),
];

/// Seccomp program for **pty** spawns under session containment: identical to
/// [`SESSION_CONTAINMENT_FILTER`] except that `setpgid` is **allowed**.
///
/// A pty child needs working job control: the interactive shell (mksh) puts
/// every foreground/background job into its own process group with `setpgid`,
/// and makes the tty's foreground group the current job via `tcsetpgrp`.
/// `setsid`/`unshare`/`setns` remain denied, so a job can fragment into any
/// number of groups *within* the session but can never leave it — the session
/// stays the daemon's kill boundary, and the kill machinery enumerates the
/// session's PGIDs at termination (see the pty job-control dilemma doc §5b)
/// instead of relying on the leader's group alone.
#[cfg(any(target_arch = "aarch64", target_arch = "x86_64", target_arch = "arm"))]
static PTY_SESSION_CONTAINMENT_FILTER: [libc::sock_filter; 11] = [
    // offset 4 = seccomp_data.arch
    bpf_stmt(BPF_LD | BPF_W | BPF_ABS, 4),
    // if arch == native, skip the KILL (jt=1); else KILL (jf=0)
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_NATIVE, 1, 0),
    bpf_stmt(BPF_RET | BPF_K, libc::SECCOMP_RET_KILL_PROCESS),
    // offset 0 = seccomp_data.nr
    bpf_stmt(BPF_LD | BPF_W | BPF_ABS, 0),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_setsid as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_unshare as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_jump(BPF_JMP | BPF_JEQ | BPF_K, libc::SYS_setns as u32, 0, 1),
    bpf_stmt(
        BPF_RET | BPF_K,
        libc::SECCOMP_RET_ERRNO | libc::EPERM as u32,
    ),
    bpf_stmt(BPF_RET | BPF_K, libc::SECCOMP_RET_ALLOW),
];

/// Install the session-containment filter in the child. Runs after the
/// daemon's own `setsid`/`setpgid` placement but before `execve`, so the
/// exec'd program and every descendant inherit the filter. Fail-closed: any
/// install error reports `ChildSetupOp::Seccomp` on the error pipe and the
/// parent aborts the spawn rather than running an uncon contained child.
///
/// `pty` selects the [`PTY_SESSION_CONTAINMENT_FILTER`] variant (which allows
/// `setpgid` so the shell's job control works) over the strict
/// [`SESSION_CONTAINMENT_FILTER`] (which denies it).
///
/// # Safety
/// Called only in the child after `fork`/`vfork`/`clone3`; async-signal-safe
/// (pure syscalls, no allocation).
unsafe fn install_session_containment(child_error_w: RawFd, pty: bool) {
    unsafe {
        let filter: &[libc::sock_filter] = if pty {
            &PTY_SESSION_CONTAINMENT_FILTER
        } else {
            &SESSION_CONTAINMENT_FILTER
        };
        let prog = libc::sock_fprog {
            len: filter.len() as u16,
            filter: filter.as_ptr().cast_mut(),
        };
        // no_new_privs must be set before the filter so the filter survives exec
        // of setuid binaries; it also forbids the child from gaining privileges.
        if libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) < 0 {
            report_child_setup_error(child_error_w, ChildSetupOp::Seccomp, errno());
        }
        if libc::prctl(
            libc::PR_SET_SECCOMP,
            libc::SECCOMP_MODE_FILTER,
            &prog as *const libc::sock_fprog as libc::c_ulong,
            0,
            0,
        ) < 0
        {
            report_child_setup_error(child_error_w, ChildSetupOp::Seccomp, errno());
        }
    }
}

/// Child-side setup shared by every exec-style backend (`fork`, `vfork`,
/// `clone3`).
///
/// The child runs only async-signal-safe operations — raw syscalls into a
/// stack-local buffer, no allocation, no locks — and either `execve`s or
/// reports the failure on `child_error_w` and `_exit`s. It never returns.
///
/// # Safety
/// This must be called only in the child after `fork`/`vfork`/`clone3`.
/// Under `vfork` the address space is shared with the suspended parent, so the
/// caller must not mutate any parent-owned state (the pipe descriptors are
/// left open — they are `O_CLOEXEC` and closed by `execve`).
#[allow(clippy::too_many_arguments)] // async-signal-safe child path; a context struct would allocate
pub(super) unsafe fn child_entry(
    pipes: &Pipes,
    fd_policy: &SpawnFdPolicy,
    pgroup: ProcessGroup,
    session_containment: bool,
    ctx: &ChildContext<'_>,
    required_fds: &[RawFd],
    child_error_r: RawFd,
    child_error_w: RawFd,
    pdeath_signal: Option<i32>,
    expected_parent_pid: libc::pid_t,
) -> ! {
    unsafe {
        // PR_SET_PDEATHSIG FIRST (opt-in `SpawnOptions::pdeath_signal`), before
        // any other setup: the signal fires when the parent *thread* that
        // created this task exits, so it must be armed while that thread is
        // still alive. Then re-check getppid: if the parent died between the
        // fork and this prctl, the child was reparented and the signal would
        // never be delivered — exit rather than leave an un-watched child.
        // `syscall(SYS_getppid)` (not the libc wrapper) avoids bionic's cached
        // getppid, which can be stale.
        if let Some(sig) = pdeath_signal {
            if libc::prctl(libc::PR_SET_PDEATHSIG, sig as libc::c_ulong, 0, 0, 0) < 0 {
                report_child_setup_error(child_error_w, ChildSetupOp::Pdeathsig, errno());
            }
            let ppid = libc::syscall(libc::SYS_getppid) as libc::pid_t;
            if ppid != expected_parent_pid {
                // The parent is gone; no one will reap or supervise us. The
                // error pipe write would also fail (the parent's read end is
                // closed), so exit directly.
                libc::_exit(127);
            }
        }

        libc::close(child_error_r);

        // Pty mode: the slave becomes stdio 0/1/2 and the controlling
        // terminal. `setsid` must happen before `TIOCSCTTY` and before the
        // fd-policy scan (which closes the original slave and master); the
        // later setsid block below is skipped so it does not double-setsid.
        if let Some(slave) = &pipes.pty_slave {
            if libc::setsid() < 0 {
                report_child_setup_error(child_error_w, ChildSetupOp::Setsid, errno());
            }
            for fd in 0..3 {
                if libc::dup2(slave.raw(), fd) < 0 {
                    report_child_setup_error(child_error_w, ChildSetupOp::TtyCtl, errno());
                }
            }
            if libc::ioctl(slave.raw(), libc::TIOCSCTTY as libc::Ioctl, 0) < 0 {
                report_child_setup_error(child_error_w, ChildSetupOp::TtyCtl, errno());
            }
        } else {
            // dup stdin
            if let (Some(r), Some(_)) = (&pipes.stdin_r, &pipes.stdin_w)
                && libc::dup2(r.raw(), 0) < 0
            {
                report_child_setup_error(child_error_w, ChildSetupOp::DupStdin, errno());
            }

            // dup stdout
            if let (Some(_), Some(w)) = (&pipes.stdout_r, &pipes.stdout_w)
                && libc::dup2(w.raw(), 1) < 0
            {
                report_child_setup_error(child_error_w, ChildSetupOp::DupStdout, errno());
            }

            // dup stderr
            if let (Some(_), Some(w)) = (&pipes.stderr_r, &pipes.stderr_w)
                && libc::dup2(w.raw(), 2) < 0
            {
                report_child_setup_error(child_error_w, ChildSetupOp::DupStderr, errno());
            }
        }

        close_child_fds_for_policy(fd_policy, required_fds, child_error_w);

        // setsid (skipped in pty mode: the pty branch already made the child a
        // session leader for TIOCSCTTY, and a second setsid fails with EPERM).
        if pgroup.isolated && pipes.pty_slave.is_none() && libc::setsid() < 0 {
            report_child_setup_error(child_error_w, ChildSetupOp::Setsid, errno());
        }

        // chdir
        if let Some(cwd) = ctx.cwd
            && libc::chdir(cwd.as_ptr()) != 0
        {
            report_child_setup_error(child_error_w, ChildSetupOp::Chdir, errno());
        }

        // setpgid
        if let Some(pg) = pgroup.leader
            && libc::setpgid(0, pg) < 0
        {
            report_child_setup_error(child_error_w, ChildSetupOp::Setpgid, errno());
        }

        // session containment: lock the child into the group/session the
        // daemon just placed it in, before it can exec into hostile code.
        // Pty mode uses the variant that allows `setpgid` (job control) while
        // still denying the session-escape syscalls.
        if session_containment {
            install_session_containment(child_error_w, pipes.pty_slave.is_some());
        }

        let envp_ptr = ctx.envp.as_ref().map_or_else(
            || environ as *const *mut c_char,
            |e: &Vec<*mut c_char>| e.as_ptr(),
        );

        // unblock signals and reset SIGPIPE
        if let Err(err) = SignalRuntime::unblock_all() {
            report_child_setup_error(
                child_error_w,
                ChildSetupOp::SignalMask,
                err.raw_os_error().unwrap_or(libc::EIO),
            );
        }
        if let Err(err) = SignalRuntime::reset_default(libc::SIGPIPE) {
            report_child_setup_error(
                child_error_w,
                ChildSetupOp::SignalMask,
                err.raw_os_error().unwrap_or(libc::EIO),
            );
        }
        // A backgrounded/inherited `SIG_IGN` (SIGHUP/SIGINT/SIGQUIT) survives
        // execve and poisons the shell and its foreground jobs (Ctrl-C cannot
        // interrupt them). Give the child a normal execution environment.
        SignalRuntime::reset_ignored_to_default();

        // exec
        libc::execve(
            ctx.exe_ptr,
            ctx.argv.as_ptr() as *const *const _,
            envp_ptr as *const *const _,
        );
        report_child_setup_error(child_error_w, ChildSetupOp::Execve, errno());
    }
}

/// Parent-side post-spawn handshake shared by every exec-style backend: close
/// the write end, read the child setup error (empty ⇒ success), reap a failed
/// child, then build the stdio drain from the surviving pipe ends.
#[allow(clippy::too_many_arguments)] // internal handshake; params mirror child_entry, no public API
pub(super) fn reap_and_drain(
    pid: pid_t,
    mut pipes: Pipes,
    child_error_r: RawFd,
    child_error_w: RawFd,
    stdin: Option<Box<[u8]>>,
    max_output: usize,
    early_exit: Option<fn(&[u8]) -> bool>,
    chunk_sink: Option<crate::io::ChunkSink>,
    pty: bool,
) -> Result<SpawnDrain, CoreError> {
    unsafe {
        libc::close(child_error_w);
    }
    match read_child_setup_error(child_error_r) {
        Ok(Some(err)) => {
            unsafe {
                libc::close(child_error_r);
                let mut status = 0;
                let _ = libc::waitpid(pid, &mut status, 0);
            }
            pipes.close_all();
            return Err(err);
        }
        Ok(None) => {}
        Err(err) => {
            unsafe {
                libc::close(child_error_r);
            }
            // The child is still live but its setup-error handshake failed;
            // nobody will `waitpid` it now. Hand it to the reaper so it does
            // not accumulate as a zombie when it exits.
            super::orphan_child(pid);
            pipes.close_all();
            return Err(err);
        }
    }
    unsafe {
        libc::close(child_error_r);
    }
    drop(pipes.stdin_r.take());
    drop(pipes.stdout_w.take());
    drop(pipes.stderr_w.take());

    // Pty mode: the master is the child's single merged stdout stream; there
    // is no stderr pipe and no stdin pipe. `pty_master` is derived here so the
    // drain maps the master's `EIO` EOF (what a pty master returns when the
    // session leader and all slave holders have closed) to a clean EOF.
    let drain = crate::io::DrainState::new(
        pipes.stdin_w.take().filter(|_| stdin.is_some()),
        stdin,
        pipes.pty_master.take().or_else(|| pipes.stdout_r.take()),
        pipes.stderr_r.take(),
        max_output,
        early_exit,
        chunk_sink,
        pty,
    )?;

    Ok(drain)
}

pub(super) fn spawn_fork_internal(opts: SpawnOptions) -> Result<(Process, SpawnDrain), CoreError> {
    let ctx = prepare_child_context(&opts.ctx);
    let mut pipes = Pipes::new(
        opts.stdin.as_deref(),
        opts.capture_stdout,
        opts.capture_stderr,
        opts.pty,
        opts.pty_fds,
    )?;

    let (child_error_r, child_error_w) = make_cloexec_pipe()?;
    let mut required_fds = collect_required_pipe_fds(&pipes);
    required_fds.push(child_error_w);

    let expected_parent_pid = unsafe { libc::getpid() };
    let pid = unsafe { libc::fork() };

    if pid < 0 {
        unsafe {
            libc::close(child_error_r);
            libc::close(child_error_w);
        }
        pipes.close_all();
        syscall_ret(-1, "fork")?;
    }

    if pid == 0 {
        // Child
        // SAFETY: child-only setup; never returns.
        unsafe {
            child_entry(
                &pipes,
                &opts.fd_policy,
                opts.pgroup,
                opts.session_containment,
                &ctx,
                &required_fds,
                child_error_r,
                child_error_w,
                opts.pdeath_signal,
                expected_parent_pid,
            );
        }
    }

    let drain = reap_and_drain(
        pid,
        pipes,
        child_error_r,
        child_error_w,
        opts.stdin,
        opts.max_output,
        opts.early_exit,
        opts.chunk_sink,
        opts.pty,
    )?;

    Ok((Process::new(pid), drain))
}

pub(super) fn spawn_vfork_internal(opts: SpawnOptions) -> Result<(Process, SpawnDrain), CoreError> {
    let ctx = prepare_child_context(&opts.ctx);
    let mut pipes = Pipes::new(
        opts.stdin.as_deref(),
        opts.capture_stdout,
        opts.capture_stderr,
        opts.pty,
        opts.pty_fds,
    )?;

    let (child_error_r, child_error_w) = make_cloexec_pipe()?;
    let mut required_fds = collect_required_pipe_fds(&pipes);
    required_fds.push(child_error_w);

    // `vfork(2)`: the child shares the parent's address space and the parent is
    // suspended until the child execs or `_exit`s. The `libc` wrapper is marked
    // deprecated because vfork is dangerous — not because it is broken — and we
    // rely on it exactly for the dangerous part it gets right: glibc/bionic
    // implement the arch-specific `clone(CLONE_VM|CLONE_VFORK|SIGCHLD)`
    // invocation (aarch64 has no `vfork` syscall and requires a valid stack).
    // Our child runs only async-signal-safe setup and never returns.
    #[allow(deprecated)]
    let expected_parent_pid = unsafe { libc::getpid() };
    let pid = unsafe { libc::vfork() };

    if pid < 0 {
        unsafe {
            libc::close(child_error_r);
            libc::close(child_error_w);
        }
        pipes.close_all();
        syscall_ret(-1, "vfork")?;
    }

    if pid == 0 {
        // SAFETY: the vfork child shares the parent's address space, but
        // `child_entry` runs only async-signal-safe operations and never
        // returns, and the parent thread is suspended by the kernel until the
        // child execs or `_exit`s.
        unsafe {
            child_entry(
                &pipes,
                &opts.fd_policy,
                opts.pgroup,
                opts.session_containment,
                &ctx,
                &required_fds,
                child_error_r,
                child_error_w,
                opts.pdeath_signal,
                expected_parent_pid,
            );
        }
    }

    let drain = reap_and_drain(
        pid,
        pipes,
        child_error_r,
        child_error_w,
        opts.stdin,
        opts.max_output,
        opts.early_exit,
        opts.chunk_sink,
        opts.pty,
    )?;

    Ok((Process::new(pid), drain))
}