Skip to main content

detcore/syscalls/
files.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! System calls for dealing with the file system.
10
11use std::collections::BTreeMap;
12use std::collections::BTreeSet;
13use std::net::Ipv4Addr;
14use std::net::Ipv6Addr;
15use std::os::unix::fs::FileTypeExt;
16use std::os::unix::fs::MetadataExt;
17use std::path::Path;
18use std::path::PathBuf;
19use std::sync::atomic::AtomicBool;
20use std::sync::atomic::Ordering;
21
22use detcore_model::bundled_signal_facts;
23use nix::fcntl::AtFlags;
24use nix::fcntl::OFlag;
25use rand::RngExt as _;
26use reverie::Error;
27use reverie::Guest;
28use reverie::Stack;
29use reverie::syscalls;
30use reverie::syscalls::Addr;
31use reverie::syscalls::AddrMut;
32use reverie::syscalls::AddrSlice;
33use reverie::syscalls::AddrSliceMut;
34use reverie::syscalls::Errno;
35use reverie::syscalls::FcntlCmd::*;
36use reverie::syscalls::MapFlags;
37use reverie::syscalls::MemoryAccess;
38use reverie::syscalls::PathPtr;
39use reverie::syscalls::ProtFlags;
40use reverie::syscalls::ReadAddr;
41use reverie::syscalls::SockFlag;
42use reverie::syscalls::StatPtr;
43use reverie::syscalls::StatxMask;
44use reverie::syscalls::Syscall;
45use reverie::syscalls::SyscallInfo;
46use reverie::syscalls::Sysno;
47use reverie::syscalls::Timespec;
48use reverie::syscalls::Whence;
49use reverie::syscalls::family::StatFamily;
50use tracing::error;
51use tracing::info;
52use tracing::trace;
53use tracing::warn;
54
55use super::deterministic_stdio_inode_for_resource;
56use crate::config::SchedHeuristic;
57use crate::dirents::*;
58use crate::fd::*;
59use crate::fifo_peer::FifoPeer;
60use crate::procfs::MountInfoSnapshot;
61use crate::procfs::ProcfsFile;
62use crate::procfs::ProcfsSnapshotContext;
63use crate::procfs::is_absent_cpu_entry;
64use crate::procfs::levels;
65use crate::procfs_inode;
66use crate::procfs_inode::DirectoryInodes;
67use crate::procfs_inode::ProcfsDirectory;
68use crate::procfs_inode::ProcfsName;
69use crate::record_or_replay::RecordOrReplay;
70use crate::resources::Device;
71use crate::resources::HOST_TIMED_INTERNAL_PIPE_IO_FYI;
72use crate::resources::Permission;
73use crate::resources::ResourceID;
74use crate::resources::Resources;
75use crate::scheduler::HostTimedSignalScope;
76use crate::scheduler::runqueue::LAST_PRIORITY;
77use crate::scheduler::terminal_signals;
78use crate::stat::*;
79use crate::syscalls::threads::kernel_sigset_bit;
80use crate::tool_global::*;
81use crate::tool_local::CapturedDetFdInstallError;
82use crate::tool_local::Detcore;
83use crate::tool_local::finish_partial_record_or_replay_write;
84use crate::types::*;
85
86pub(crate) mod procfs_levels;
87pub(crate) mod procfs_numbers;
88pub(crate) mod rendered_procfs;
89
90/// A conversion from SOCK_* flags to O_* flags which makes unsafe (but checked during testing) assumptions.
91fn oflag_from_sock_bits(s_bits: i32) -> OFlag {
92    // An otherwise unsafe "cast" which leans on the `linux_flags_assumptions` below.
93    OFlag::from_bits_truncate(s_bits & (libc::SOCK_CLOEXEC | libc::SOCK_NONBLOCK))
94}
95
96const UNIX_AUTOBIND_NAME_LEN: usize = 6;
97// AUTONOMOUS-BOT-IMPLEMENTED
98// TODO-HUMAN-REVIEW(PR-2150): Review timer-slack procfs parsing,
99// per-operation target checks, and scalar/vector I/O emulation.
100const TIMER_SLACK_PARSE_BYTES: usize = 66;
101#[derive(Clone, Copy)]
102struct TimerSlackIovec {
103    base: usize,
104    len: usize,
105}
106
107#[derive(Clone, Copy, Debug, PartialEq, Eq)]
108struct TimerSlackBinding {
109    target: i32,
110    device: u64,
111    inode: u64,
112}
113
114fn classify_timer_slack_binding(
115    binding: TimerSlackBinding,
116    observed_identity: Option<(u64, u64)>,
117    current_tid: i32,
118) -> Result<(), Errno> {
119    if observed_identity != Some((binding.device, binding.inode)) {
120        // The bound task exited. A missing path and a new task that recycled
121        // the same numeric TID are both ESRCH for the old open inode.
122        return Err(Errno::ESRCH);
123    }
124    if current_tid != binding.target {
125        // Cross-task CAP_SYS_NICE access is intentionally not exposed.
126        return Err(Errno::EPERM);
127    }
128    Ok(())
129}
130
131fn parse_timer_slack_write(bytes: &[u8]) -> Result<u64, Errno> {
132    // `kstrtoull_from_user` copies at most sign + 64 binary digits + newline,
133    // then accepts decimal digits with one optional leading '+' and one
134    // optional trailing newline. An embedded NUL terminates the C string.
135    let bytes = &bytes[..bytes.len().min(TIMER_SLACK_PARSE_BYTES)];
136    let end = bytes
137        .iter()
138        .position(|byte| *byte == 0)
139        .unwrap_or(bytes.len());
140    let mut value = &bytes[..end];
141    if value.first() == Some(&b'+') {
142        value = &value[1..];
143    }
144    if value.last() == Some(&b'\n') {
145        value = &value[..value.len() - 1];
146    }
147    if value.is_empty() || !value.iter().all(u8::is_ascii_digit) {
148        return Err(Errno::EINVAL);
149    }
150    value.iter().try_fold(0_u64, |parsed, digit| {
151        parsed
152            .checked_mul(10)
153            .and_then(|parsed| parsed.checked_add(u64::from(digit - b'0')))
154            .ok_or(Errno::ERANGE)
155    })
156}
157
158fn vectored_offset(low: u64, high: u64) -> i64 {
159    if std::mem::size_of::<usize>() == 8 {
160        low as i64
161    } else {
162        ((high << 32) | (low & u32::MAX as u64)) as i64
163    }
164}
165
166/// RNG vectors use either the shared stream or an independent explicit offset.
167struct RandomVectoredRead {
168    address: usize,
169    count: usize,
170    offset: Option<u64>,
171    flags: i32,
172}
173
174/// Apply Linux's checks after complete iovec import, before touching output.
175fn validate_random_vector_read(offset: Option<u64>, total: usize, flags: i32) -> Result<(), Errno> {
176    if total == 0 {
177        return Ok(());
178    }
179    if let Some(offset) = offset
180        && offset
181            .checked_add(total as u64)
182            .is_none_or(|end| end > i64::MAX as u64)
183    {
184        return Err(Errno::EINVAL);
185    }
186    // Linux 7.1's RWF_NOSIGNAL is newer than the pinned libc crate. Native
187    // random-device controls accept it, including with RWF_NOWAIT.
188    const RWF_NOSIGNAL: i32 = 0x100;
189    const KNOWN: i32 = libc::RWF_HIPRI
190        | libc::RWF_DSYNC
191        | libc::RWF_SYNC
192        | libc::RWF_NOWAIT
193        | libc::RWF_APPEND
194        | libc::RWF_NOAPPEND
195        | libc::RWF_ATOMIC
196        | libc::RWF_DONTCACHE
197        | RWF_NOSIGNAL;
198    // Unknown flags win over conflicting recognized flags, while recognized
199    // but unsupported ATOMIC/DONTCACHE are rejected after APPEND/NOAPPEND.
200    if flags & !KNOWN != 0 {
201        return Err(Errno::EOPNOTSUPP);
202    }
203    if flags & libc::RWF_APPEND != 0 && flags & libc::RWF_NOAPPEND != 0 {
204        return Err(Errno::EINVAL);
205    }
206    if flags & (libc::RWF_ATOMIC | libc::RWF_DONTCACHE) != 0 {
207        return Err(Errno::EOPNOTSUPP);
208    }
209    Ok(())
210}
211
212fn read_iovecs<M: MemoryAccess>(
213    memory: &M,
214    address: Option<Addr<libc::iovec>>,
215    count: usize,
216) -> Result<Vec<TimerSlackIovec>, Errno> {
217    if count > libc::UIO_MAXIOV as usize {
218        return Err(Errno::EINVAL);
219    }
220    if count == 0 {
221        return Ok(Vec::new());
222    }
223    let address = address.ok_or(Errno::EFAULT)?;
224    let mut iovecs = vec![
225        libc::iovec {
226            iov_base: std::ptr::null_mut(),
227            iov_len: 0,
228        };
229        count
230    ];
231    memory.read_values(address, &mut iovecs)?;
232    let total = iovecs.iter().try_fold(0_usize, |total, iovec| {
233        total.checked_add(iovec.iov_len).ok_or(Errno::EINVAL)
234    })?;
235    if total > isize::MAX as usize {
236        return Err(Errno::EINVAL);
237    }
238    Ok(iovecs
239        .into_iter()
240        .map(|iovec| TimerSlackIovec {
241            base: iovec.iov_base as usize,
242            len: iovec.iov_len,
243        })
244        .collect())
245}
246
247fn copy_timer_slack_output<M: MemoryAccess>(
248    memory: &mut M,
249    destination: Option<AddrMut<'_, u8>>,
250    bytes: &[u8],
251) -> Result<usize, Errno> {
252    if bytes.is_empty() {
253        return Ok(0);
254    }
255    let copied = memory.write(destination.ok_or(Errno::EFAULT)?, bytes)?;
256    if copied == 0 {
257        Err(Errno::EFAULT)
258    } else {
259        Ok(copied)
260    }
261}
262
263/// Copy sanitized procfs bytes to the caller's buffer as the kernel's
264/// `copy_to_user` does: through the guest's page protections, stopping at the
265/// first byte that cannot be written. Returns the bytes copied, or `EFAULT`
266/// when none could be. A debugger write is not equivalent: the ptrace
267/// backend writes exactly eight bytes with `PTRACE_POKEDATA`, which ignores
268/// `PROT_READ` and `PROT_NONE`.
269fn copy_procfs_output<M: MemoryAccess>(
270    memory: &mut M,
271    destination: Option<AddrMut<'_, u8>>,
272    bytes: &[u8],
273) -> Result<usize, Error> {
274    if bytes.is_empty() {
275        return Ok(0);
276    }
277    let destination = destination.ok_or(Errno::EFAULT)?;
278    let mut copied = 0;
279    while copied < bytes.len() {
280        let Some(address) = destination
281            .as_raw()
282            .checked_add(copied)
283            .and_then(AddrMut::<u8>::from_raw)
284        else {
285            break;
286        };
287        match memory.write_with_user_access(address, &bytes[copied..]) {
288            Ok(0) | Err(Errno::EFAULT) => break,
289            Ok(n) => copied += n,
290            // Any other failure is the backend's, not a guest fault: report it
291            // as a tool error and commit nothing.
292            Err(errno) => {
293                return Err(Error::Tool(anyhow::anyhow!(
294                    "procfs read publication failed after {copied} bytes: {errno}"
295                )));
296            }
297        }
298    }
299    if copied == 0 {
300        Err(Errno::EFAULT.into())
301    } else {
302        Ok(copied)
303    }
304}
305
306/// Whether a descriptor with status flags `status` can read: not `O_PATH`,
307/// and opened for reading (`O_RDONLY` or `O_RDWR`; not `O_WRONLY`, nor access
308/// mode 3, which grants neither).
309fn can_read(status: i32) -> bool {
310    status & libc::O_PATH == 0 && matches!(status & libc::O_ACCMODE, libc::O_RDONLY | libc::O_RDWR)
311}
312
313/// Copy the bytes of a read of a procfs file as its read handler does: a
314/// `seq_file` copies up to the first byte it cannot write, and a sysctl
315/// (`faults_on_a_short_copy`) copies all of them or fails with `EFAULT`, so
316/// that the caller commits nothing.
317fn copy_procfs_read<M: MemoryAccess>(
318    memory: &mut M,
319    destination: Option<AddrMut<'_, u8>>,
320    bytes: &[u8],
321    faults_on_a_short_copy: bool,
322) -> Result<usize, Error> {
323    let copied = copy_procfs_output(memory, destination, bytes)?;
324    if faults_on_a_short_copy && copied < bytes.len() {
325        return Err(Errno::EFAULT.into());
326    }
327    Ok(copied)
328}
329
330/// The `RWF_*` flags of a vectored read of a procfs file Detcore renders, as
331/// `kiocb_set_rw_flags` checks them for a file with `read_iter` and without
332/// `FMODE_NOWAIT` or `FOP_DONTCACHE`: an unknown flag, then `RWF_APPEND` with
333/// `RWF_NOAPPEND` (`EINVAL`), then `RWF_NOWAIT`, `RWF_ATOMIC` (a read) and
334/// `RWF_DONTCACHE` (`EOPNOTSUPP`). Measured on Linux 7.1 for `/proc/version`
335/// and the sysctls, which also accept `RWF_NOSIGNAL`. A file without
336/// `read_iter` (`/proc/modules`, `/proc/swaps`) is read by
337/// `do_loop_readv_writev`, which refuses every flag but `RWF_HIPRI`.
338fn validate_procfs_vector_flags(flags: i32, read_iter: bool) -> Result<(), Errno> {
339    if !read_iter {
340        return if flags & !libc::RWF_HIPRI != 0 {
341            Err(Errno::EOPNOTSUPP)
342        } else {
343            Ok(())
344        };
345    }
346    // Linux 7.1's RWF_NOSIGNAL is newer than the pinned libc crate.
347    const RWF_NOSIGNAL: i32 = 0x100;
348    const KNOWN: i32 = libc::RWF_HIPRI
349        | libc::RWF_DSYNC
350        | libc::RWF_SYNC
351        | libc::RWF_NOWAIT
352        | libc::RWF_APPEND
353        | libc::RWF_NOAPPEND
354        | libc::RWF_ATOMIC
355        | libc::RWF_DONTCACHE
356        | RWF_NOSIGNAL;
357    if flags & !KNOWN != 0 {
358        return Err(Errno::EOPNOTSUPP);
359    }
360    if flags & libc::RWF_APPEND != 0 && flags & libc::RWF_NOAPPEND != 0 {
361        return Err(Errno::EINVAL);
362    }
363    if flags & (libc::RWF_NOWAIT | libc::RWF_ATOMIC | libc::RWF_DONTCACHE) != 0 {
364        return Err(Errno::EOPNOTSUPP);
365    }
366    Ok(())
367}
368
369/// Check the caller's whole requested range as `vfs_read`'s `access_ok` does
370/// before the file is read, so an address range beyond the user address limit
371/// is `EFAULT` even at EOF, when nothing would be copied. A procfs snapshot read
372/// never hands that range to the kernel.
373///
374/// `limit` is asked for the guest's user address limit only when the answer
375/// can matter, so a count that no limit admits is `EFAULT` before any query
376/// can fail.
377fn validate_procfs_destination(
378    limit: impl FnOnce() -> Result<crate::iovecs::UserAddressLimit, Error>,
379    destination: Option<AddrMut<'_, u8>>,
380    len: usize,
381) -> Result<(), Error> {
382    // No count past isize::MAX fits below a user address limit, so `read`'s
383    // `access_ok` refuses it, whatever the limit.
384    if isize::try_from(len).is_err() {
385        return Err(Errno::EFAULT.into());
386    }
387    // Two descriptors keep the range uncapped, as `access_ok` sees it; a
388    // single one may be capped at MAX_RW_COUNT first (`import_ubuf`).
389    limit()?.validate(&[
390        crate::iovecs::ImportedIovec {
391            base: destination.map_or(0, |address| address.as_raw()),
392            len,
393        },
394        crate::iovecs::ImportedIovec { base: 0, len: 0 },
395    ])
396}
397
398/// Save the bytes at `scratch` into `original` if the guest's own protections
399/// let the capture read land there: the range is readable, and writing the
400/// same bytes back through the guest's protections copies all of them.
401fn save_procfs_scratch<M: MemoryAccess>(
402    memory: &mut M,
403    scratch: AddrMut<'_, u8>,
404    original: &mut [u8],
405) -> bool {
406    read_guest_exact(memory, scratch, original).is_ok()
407        && memory
408            .write_with_user_access(scratch, original)
409            .is_ok_and(|written| written == original.len())
410}
411
412/// Read exactly `buf.len()` bytes at `addr`, in one `read_vectored` of that
413/// length, or fail `EFAULT` if not all of them can be read. `read` and
414/// `read_exact` may widen a short read (ptrace turns up to eight bytes into one
415/// eight-byte `PTRACE_PEEKDATA`), which fails when a valid extent ends less
416/// than eight bytes before an unmapped page.
417pub(crate) fn read_guest_exact<M: MemoryAccess>(
418    memory: &M,
419    addr: AddrMut<'_, u8>,
420    buf: &mut [u8],
421) -> Result<(), Errno> {
422    let len = buf.len();
423    let remote = unsafe { AddrSlice::from_raw_parts(addr.into(), len) };
424    let remote = [unsafe { remote.as_ioslice() }];
425    let mut local = [std::io::IoSliceMut::new(buf)];
426    match memory.read_vectored(&remote, &mut local) {
427        Ok(copied) if copied == len => Ok(()),
428        Ok(_) => Err(Errno::EFAULT),
429        Err(errno) => Err(errno),
430    }
431}
432
433/// Capacity used for pipes that Detcore makes physically nonblocking.
434///
435/// Linux normally creates 64-KiB pipes on this platform, but silently falls back to two pages
436/// once the creating UID crosses `pipe-user-pages-soft`. That host-global accounting can change
437/// between the two executions of `hermit run --verify`, changing whether the same write succeeds
438/// immediately or enters the scheduler's `InternalIOPolling` retry path. Two pages is the
439/// pressure-mode capacity on supported x86-64 Linux hosts and, unlike 64 KiB, never requires an
440/// unprivileged capacity increase while the soft limit is active.
441///
442/// This is also the ceiling the guest is allowed to raise a pipe to, and the
443/// value `/proc/sys/fs/pipe-max-size` reports. Those three must be ONE constant:
444/// a pinned capacity, an advertised maximum and an enforced maximum that can
445/// drift apart are three copies of one rule, and a duplicated rule drifts in
446/// N-1 places while each copy looks right on its own.
447pub(crate) const DETERMINISTIC_PIPE_CAPACITY_BYTES: i32 = 8 * 1024;
448
449/// Whether a guest's `F_SETPIPE_SZ` request must be refused as a growth past
450/// the deterministic ceiling.
451///
452/// Separated from the handler so the BOUNDARY is testable without a guest. The
453/// boundary is the whole content of this rule: a request for exactly the pinned
454/// capacity must be allowed, or hermit's own pin value becomes unreachable to a
455/// guest that reads `/proc/sys/fs/pipe-max-size` and asks for precisely what it
456/// was told.
457pub(crate) fn pipe_capacity_request_exceeds_ceiling(requested: i32) -> bool {
458    requested > DETERMINISTIC_PIPE_CAPACITY_BYTES
459}
460
461/// The capacity a guest's `F_GETPIPE_SZ` reports for a pipe or FIFO whose
462/// host capacity is `host`: never more than the deterministic ceiling.
463///
464/// A pipe Hermit did not create (an inherited stdout, a FIFO whose other end
465/// is on the host) keeps the capacity the host gave it: 64 KiB normally, but
466/// two pages (8192) once the user crosses `pipe-user-pages-soft`, which host
467/// load decides. Passed through, that made the same guest read 65536 in one
468/// run of `--verify` and 8192 in the other (`/bin/cat` on DBT, the validate of
469/// hermit 2cd56771). A pipe can never hold more than the ceiling a guest can
470/// raise it to, so above it the ceiling is reported, as `pipe-max-size` is. A
471/// capacity at or below it is the one a pipe Hermit created was pinned to, or
472/// one the guest set itself, and is reported as it is. Host load cannot make
473/// a pipe smaller than the ceiling on Linux 5.14 and later: the quota fallback
474/// is exactly two pages, and past the hard limit Linux refuses the pipe
475/// instead. So an inherited pipe below it is one its creator sized on purpose,
476/// the same in every run. Before 5.14 the fallback was one page; the creation
477/// pin already needs 5.14 there, since under the same quota its growth of a
478/// one-page pipe to the ceiling is refused and the run stops
479/// (`pipe_capacity_failure`).
480///
481/// Only the reported value is made deterministic. A write to a pipe drained on
482/// the host still completes as far as its real capacity and that reader allow.
483pub(crate) fn reported_pipe_capacity(host: i64) -> i64 {
484    host.min(i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES))
485}
486
487/// SIGIO and SIGURG, the signals Linux sends to a descriptor's owner when
488/// data, out-of-band data, a lease break, or a directory change arrives.
489fn async_io_signals() -> u64 {
490    kernel_sigset_bit(libc::SIGIO) | kernel_sigset_bit(libc::SIGURG)
491}
492
493/// The signals an `fcntl` command lets Linux send at a moment set by host
494/// timing, as a kernel sigset; 0 for every other command. `F_SETOWN` and
495/// `F_SETOWN_EX` name the owner, `F_SETLEASE` and `F_NOTIFY` make the caller
496/// the owner, `O_ASYNC` enables SIGIO, and `F_SETSIG` replaces SIGIO with
497/// another signal.
498fn fcntl_host_timed_signals(cmd: syscalls::FcntlCmd<'_>) -> u64 {
499    match cmd {
500        F_SETFL(flags) if flags & libc::O_ASYNC != 0 => async_io_signals(),
501        F_SETOWN | F_SETOWN_EX(_) | F_SETLEASE(_) | F_NOTIFY(_) => async_io_signals(),
502        F_SETSIG(signal) => async_io_signals() | kernel_sigset_bit(signal),
503        _ => 0,
504    }
505}
506
507/// The signals an `ioctl` request lets Linux send at a moment set by host
508/// timing, as a kernel sigset; 0 for every other request. `FIOASYNC` enables
509/// SIGIO, and `FIOSETOWN` and `SIOCSPGRP` name the owner. `TIOCSCTTY` makes
510/// the terminal the caller's controlling terminal, `TIOCGPTPEER` without
511/// `O_NOCTTY` opens a pseudoterminal's other end as `open` does and so can
512/// make it one (`open_can_acquire_controlling_terminal`), and `TIOCSPGRP`
513/// names the terminal's foreground process group, so the terminal can then
514/// signal the session and that group (`terminal_signals`). `TIOCNOTTY` and
515/// `TIOCSWINSZ` are not among them: the signals they send, they send inside
516/// the caller's call, in the caller's turn.
517fn ioctl_host_timed_signals(request: syscalls::ioctl::Request<'_>) -> u64 {
518    match request {
519        syscalls::ioctl::Request::FIOASYNC(_)
520        | syscalls::ioctl::Request::FIOSETOWN(_)
521        | syscalls::ioctl::Request::SIOCSPGRP(_) => async_io_signals(),
522        syscalls::ioctl::Request::TIOCSCTTY(_) | syscalls::ioctl::Request::TIOCSPGRP(_) => {
523            terminal_signals()
524        }
525        syscalls::ioctl::Request::TIOCGPTPEER(flags)
526            if open_can_acquire_controlling_terminal(OFlag::from_bits_truncate(flags)) =>
527        {
528            terminal_signals()
529        }
530        _ => 0,
531    }
532}
533
534/// Whether an `open` with these flags can make the terminal it opens the
535/// caller's controlling terminal. Linux's `tty_open` does that for a session
536/// leader that has none, unless `O_NOCTTY` is given; an `O_PATH` open never
537/// reaches `tty_open`.
538fn open_can_acquire_controlling_terminal(flags: OFlag) -> bool {
539    !flags.intersects(OFlag::O_NOCTTY | OFlag::O_PATH)
540}
541
542/// Whether the character device `rdev` is a terminal that an `open` can make
543/// its caller's controlling terminal. `tty_drivers` is the text of
544/// `/proc/tty/drivers`, one line per range of device numbers a terminal
545/// driver serves, ending in the major number, the minor number or range, and
546/// the driver's type. A device no line names is not a terminal. Linux's
547/// `tty_open` never makes `/dev/console` (5:1), `/dev/vc/0` (4:0) or a
548/// pseudoterminal master controlling, and `/dev/ptmx` (5:2) opens a master
549/// without reaching `tty_open`. `/dev/tty` (5:0) stays in: it reopens the
550/// caller's controlling terminal, and if a hangup clears that terminal during
551/// the `open`, the `open` can make it controlling again. A table that could
552/// not be read (`None`), or a line that does not parse when no other line
553/// names the device, answers true.
554fn terminal_can_become_controlling(rdev: libc::dev_t, tty_drivers: Option<&str>) -> bool {
555    let (major, minor) = (libc::major(rdev), libc::minor(rdev));
556    if matches!((major, minor), (5, 1) | (5, 2) | (4, 0)) {
557        return false;
558    }
559    let Some(table) = tty_drivers else {
560        return true;
561    };
562    let mut unparsed = false;
563    for line in table.lines().filter(|line| !line.trim().is_empty()) {
564        let fields: Vec<&str> = line.split_whitespace().collect();
565        let range = match fields[..] {
566            [.., line_major, minors, kind] => {
567                line_major.parse::<u32>().ok().and_then(|line_major| {
568                    let (first, last) = minors.split_once('-').unwrap_or((minors, minors));
569                    Some((
570                        line_major,
571                        first.parse::<u32>().ok()?,
572                        last.parse::<u32>().ok()?,
573                        kind,
574                    ))
575                })
576            }
577            _ => None,
578        };
579        match range {
580            Some((line_major, first, last, kind))
581                if line_major == major && (first..=last).contains(&minor) =>
582            {
583                return kind != "pty:master";
584            }
585            Some(_) => {}
586            None => unparsed = true,
587        }
588    }
589    unparsed
590}
591
592/// Whether an `open` in process `pid`, whose `/proc/<pid>/stat` lists
593/// `session`, of the character device `rdev` may have made that device
594/// `pid`'s controlling terminal: `pid` leads its session and the device is a
595/// terminal that can become controlling (`terminal_can_become_controlling`).
596/// Neither fact is the controlling terminal procfs lists, which a hangup of
597/// the terminal clears at any moment, so the answer does not depend on
598/// whether a hangup came before or after the read. A session leader that
599/// reopens the terminal it already controls, or opens a terminal while it
600/// controls another, also answers true.
601fn may_have_acquired_controlling_terminal(
602    pid: i32,
603    session: i32,
604    rdev: libc::dev_t,
605    tty_drivers: Option<&str>,
606) -> bool {
607    session == pid && terminal_can_become_controlling(rdev, tty_drivers)
608}
609
610/// Whether the `open` in process `pid` that returned `fd` may have made the
611/// opened terminal `pid`'s controlling terminal
612/// (`may_have_acquired_controlling_terminal`). `host_stat` is the
613/// descriptor's stat when the caller already read it. Every host read that
614/// fails answers true: a needless record only holds the terminal's signals
615/// (`terminal_signals`) to the end of the gated waits that follow, while a
616/// missed one lets the terminal interrupt one at a turn the host chose.
617fn opened_controlling_terminal(pid: i32, fd: RawFd, host_stat: Option<&libc::stat>) -> bool {
618    let rdev = match host_stat {
619        Some(stat) if stat.st_mode & libc::S_IFMT == libc::S_IFCHR => stat.st_rdev,
620        Some(_) => return false,
621        None => match std::fs::metadata(format!("/proc/{pid}/fd/{fd}")) {
622            Ok(metadata) if metadata.file_type().is_char_device() => metadata.rdev(),
623            Ok(_) => return false,
624            Err(_) => return true,
625        },
626    };
627    let session = match procfs::process::Process::new(pid).and_then(|process| process.stat()) {
628        Ok(stat) => stat.session,
629        Err(_) => return true,
630    };
631    let tty_drivers = std::fs::read_to_string("/proc/tty/drivers").ok();
632    may_have_acquired_controlling_terminal(pid, session, rdev, tty_drivers.as_deref())
633}
634
635/// Why the pin failed, and which descriptors Linux had already created when it did.
636///
637/// `pipe2` has already SUCCEEDED by the time the capacity is pinned, so the two descriptors
638/// exist in the guest whatever happens next. Carrying them alongside the errno is what makes
639/// releasing them possible; classifying separately from acting on it is what makes the
640/// classification unit-testable without a guest.
641#[derive(Debug, PartialEq, Eq)]
642struct PipeCapacityFailure {
643    created_fds: [i32; 2],
644    error: Errno,
645}
646
647impl PipeCapacityFailure {
648    fn close_syscalls(&self) -> [syscalls::Close; 2] {
649        self.created_fds
650            .map(|fd| syscalls::Close::new().with_fd(fd))
651    }
652}
653
654/// Classify the result of pinning a pipe's capacity.
655///
656/// The ONLY success shape is Linux returning exactly the requested capacity. `F_SETPIPE_SZ`
657/// returns the capacity it actually applied, and it may round; a rounded value is a pipe whose
658/// size we did not choose, which is the host-dependent capacity this path exists to remove. It
659/// is not a kernel errno, so it is reported as `EIO` rather than dressed up as one.
660fn pipe_capacity_failure(
661    created_fds: [i32; 2],
662    capacity_result: Result<i64, Errno>,
663) -> Option<PipeCapacityFailure> {
664    let error = match capacity_result {
665        Ok(applied) if applied == i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES) => return None,
666        Ok(_) => Errno::EIO,
667        Err(error) => error,
668    };
669    Some(PipeCapacityFailure { created_fds, error })
670}
671
672fn should_tag_host_timed_internal_pipe_io(
673    internal_pipe_turns_are_host_timed: bool,
674    fd_type: FdType,
675    physically_nonblocking: bool,
676    logically_nonblocking: bool,
677) -> bool {
678    internal_pipe_turns_are_host_timed
679        && fd_type == FdType::Pipe
680        && physically_nonblocking
681        && !logically_nonblocking
682}
683
684fn random_device_lseek_result(status_flags: i32, whence: Whence) -> Result<i64, Errno> {
685    if status_flags & OFlag::O_PATH.bits() != 0 {
686        return Err(Errno::EBADF);
687    }
688    match whence {
689        Whence::SEEK_SET
690        | Whence::SEEK_CUR
691        | Whence::SEEK_END
692        | Whence::SEEK_DATA
693        | Whence::SEEK_HOLE => Ok(0),
694        _ => Err(Errno::EINVAL),
695    }
696}
697
698fn require_random_device_read_access(status_flags: i32) -> Result<(), Errno> {
699    if status_flags & libc::O_PATH != 0
700        || !matches!(
701            status_flags & libc::O_ACCMODE,
702            libc::O_RDONLY | libc::O_RDWR
703        )
704    {
705        Err(Errno::EBADF)
706    } else {
707        Ok(())
708    }
709}
710
711/// Inherited container output is a stream even when an outer runner stores it
712/// in a seekable file.  The backing file also carries Hermit's own diagnostics,
713/// so exposing its live offset makes tool logging guest-visible.  Preserve real
714/// file semantics after a guest replaces stdout/stderr: `dup2(file, 1)` copies
715/// the file's resource rather than this container-output resource.
716fn is_inherited_container_output(resource: Option<ResourceID>) -> bool {
717    matches!(
718        resource,
719        Some(ResourceID::Device(
720            Device::ContainerStdout | Device::ContainerStderr
721        ))
722    )
723}
724
725fn unix_autobind_addrlen() -> i32 {
726    (std::mem::offset_of!(libc::sockaddr_un, sun_path) + UNIX_AUTOBIND_NAME_LEN) as i32
727}
728
729fn unix_autobind_address(port: u16) -> libc::sockaddr_un {
730    // Linux autobind names are a leading NUL followed by five lowercase hex digits.
731    let mut address: libc::sockaddr_un = unsafe { std::mem::zeroed() };
732    address.sun_family = libc::AF_UNIX as libc::sa_family_t;
733    for (destination, source) in address.sun_path[1..UNIX_AUTOBIND_NAME_LEN]
734        .iter_mut()
735        .zip(format!("{port:05x}").bytes())
736    {
737        *destination = source as libc::c_char;
738    }
739    address
740}
741
742// TODO-HUMAN-REVIEW(PR-904): Review the TCP_INFO compatibility boundary.
743/// Retain the logical TCP state and negotiated option header while hiding all
744/// host timing, rate, packet, and byte counters.
745fn canonicalize_tcp_info(info: &mut [u8]) {
746    for (offset, byte) in info.iter_mut().enumerate() {
747        if !matches!(offset, 0 | 1 | 5 | 6) {
748            *byte = 0;
749        }
750    }
751}
752
753// Hermit exposes exactly one isolated guest network namespace.
754const DETERMINISTIC_NETNS_COOKIE: u64 = 1;
755
756// Above Linux's PID range and below the high-bit IDs used by kernel autobind.
757const DETERMINISTIC_NETLINK_PORT_ID_BASE: u32 = 0x4000_0000;
758
759/// Does the new guest descriptor `fd` reopen an anonymous pipe that the same
760/// process already holds as a scheduler-managed pipe (`managed_pipe_fds`)?
761///
762/// Both `/proc/<pid>/fd/<fd>` links read `pipe:[<inode>]` for the same pipe.
763/// A named FIFO links to its path, and on ptrace a host pipe is never in
764/// `managed_pipe_fds` (see `scheduler_managed_pipe_fds` for SaBRe), so neither
765/// matches: a host writer is outside the scheduler and must not be polled as if
766/// it were a guest
767/// (<https://github.com/rrnewton/hermit/pull/3534#issuecomment-5962369261>).
768fn reopens_scheduler_managed_pipe(
769    backend: &reverie::BackendCapabilities,
770    pid: i32,
771    fd: RawFd,
772    managed_pipe_fds: &[RawFd],
773) -> bool {
774    // Under KVM `/proc/<pid>` is an unrelated host task, if any, and its
775    // links say nothing about this guest's pipes.
776    if !crate::procfs_inode::tool_can_name_guest_descriptors(backend) {
777        return false;
778    }
779    let link = |fd: RawFd| std::fs::read_link(format!("/proc/{pid}/fd/{fd}")).ok();
780    let Some(opened) = link(fd) else {
781        return false;
782    };
783    if !opened
784        .to_str()
785        .is_some_and(|name| name.starts_with("pipe:["))
786    {
787        return false;
788    }
789    managed_pipe_fds
790        .iter()
791        .any(|&held| held != fd && link(held).as_ref() == Some(&opened))
792}
793
794/// The path the kernel resolved an open descriptor to, read from the guest's
795/// own `/proc/<pid>/fd/<fd>` link. This is the evidence authority for "which
796/// object was opened": it is produced by the kernel from the descriptor itself,
797/// so it is independent of the pathname spelling the guest used.
798///
799/// Used ONLY as a fallback for a pathname that does not classify on its own
800/// (see the call site): a spelling that already classifies must keep its own
801/// classification, because `/proc/self/...` and `/proc/thread-self/...` are
802/// defined by the spelling and resolve to a different numeric path.
803///
804/// `None` when the link cannot be read (the descriptor is gone, or procfs is
805/// unavailable), in which case the lexical result stands unchanged. Also
806/// `None` under KVM, where `/proc/<pid>` does not name the guest (see
807/// [`crate::procfs_inode::tool_can_name_guest_descriptors`]).
808fn resolved_open_path(
809    backend: &reverie::BackendCapabilities,
810    pid: i32,
811    fd: RawFd,
812) -> Option<PathBuf> {
813    if !crate::procfs_inode::tool_can_name_guest_descriptors(backend) {
814        return None;
815    }
816    let link = std::fs::read_link(format!("/proc/{pid}/fd/{fd}")).ok()?;
817    // A deleted or anonymous target is not a stable object name.
818    link.is_absolute().then_some(link)
819}
820
821/// The scope `pidfd_send_signal`'s flags select (Linux's `pidfd_send_signal`
822/// since 6.9; <https://github.com/rrnewton/hermit/issues/4108>).
823#[derive(Clone, Copy, Debug, PartialEq, Eq)]
824pub(crate) enum PidfdSignalScope {
825    /// No flag, or `PIDFD_SIGNAL_THREAD_GROUP`: the process (Detcore's
826    /// `pidfd_open` makes no thread pidfds).
827    Process,
828    /// `PIDFD_SIGNAL_THREAD`: the thread whose id is the pid.
829    Thread,
830    /// `PIDFD_SIGNAL_PROCESS_GROUP`: the process's process group.
831    ProcessGroup,
832}
833
834const PIDFD_SIGNAL_THREAD: u32 = 1 << 0;
835const PIDFD_SIGNAL_THREAD_GROUP: u32 = 1 << 1;
836const PIDFD_SIGNAL_PROCESS_GROUP: u32 = 1 << 2;
837
838/// `flags`' scope, or EINVAL as Linux answers: for a bit outside the three
839/// scope flags, or for more than one of them.
840pub(crate) fn pidfd_signal_scope(flags: u32) -> Result<PidfdSignalScope, Errno> {
841    match flags {
842        0 | PIDFD_SIGNAL_THREAD_GROUP => Ok(PidfdSignalScope::Process),
843        PIDFD_SIGNAL_THREAD => Ok(PidfdSignalScope::Thread),
844        PIDFD_SIGNAL_PROCESS_GROUP => Ok(PidfdSignalScope::ProcessGroup),
845        _ => Err(Errno::EINVAL),
846    }
847}
848
849/// `pidfd_send_signal`'s sentinel for the calling thread (Linux 6.15 and later).
850const PIDFD_SELF_THREAD: RawFd = -10000;
851/// `pidfd_send_signal`'s sentinel for the calling thread's thread group.
852const PIDFD_SELF_THREAD_GROUP: RawFd = -10001;
853
854/// The task a `PIDFD_SELF_*` sentinel names, and the scope Linux gives it when
855/// no flag is set: the calling thread (thread-directed) or its thread group
856/// (process-directed); `None` for any other descriptor
857/// (https://github.com/rrnewton/hermit/issues/4147).
858fn pidfd_self_target<T, G: Guest<Detcore<T>>>(
859    guest: &mut G,
860    pidfd: RawFd,
861) -> Option<(DetPid, PidfdSignalScope)>
862where
863    T: RecordOrReplay,
864{
865    let state = guest.thread_state();
866    match pidfd {
867        PIDFD_SELF_THREAD => Some((
868            DetPid::from_raw(state.dettid.as_raw()),
869            PidfdSignalScope::Thread,
870        )),
871        PIDFD_SELF_THREAD_GROUP => Some((state.detpid?, PidfdSignalScope::Process)),
872        _ => None,
873    }
874}
875
876/// What a descriptor that is not a modeled pidfd names for `pidfd_send_signal`.
877#[derive(Clone, Debug, PartialEq, Eq)]
878pub(crate) enum ProcessDirectoryDescriptor {
879    /// A `/proc/<pid>` directory of the guest's procfs: Linux takes it as the
880    /// process `<pid>`.
881    Process(DetPid),
882    /// Any other file, which Linux answers EBADF.
883    NotAProcess,
884    /// Detcore cannot tell; the reason names why.
885    Unknown(&'static str),
886}
887
888/// Facts the tracer reads about a guest descriptor (`process_directory_descriptor`).
889#[derive(Clone, Debug, Default)]
890pub(crate) struct DescriptorFacts {
891    /// The descriptor's `/proc/<tid>/fd/<fd>` link, as the kernel spells it.
892    pub(crate) link: PathBuf,
893    /// Whether the file is on procfs.
894    pub(crate) on_procfs: bool,
895    /// Whether the file is a directory.
896    pub(crate) is_dir: bool,
897    /// The file's device, and its parent directory's device and inode.
898    pub(crate) dev: u64,
899    pub(crate) parent: Option<(u64, u64)>,
900    /// The device of the procfs mounted at the guest's `/proc`.
901    pub(crate) guest_proc_dev: Option<u64>,
902}
903
904/// The inode of a procfs root directory (Linux's `PROC_ROOT_INO`).
905const PROC_ROOT_INO: u64 = 1;
906
907/// Classify a descriptor from `facts` (`None`: unreadable). Linux's
908/// `tgid_pidfd_to_pid` accepts exactly a procfs process directory, whose name
909/// is its pid in the procfs instance's pid namespace and whose parent is the
910/// procfs root. That instance must be the guest's own, at its `/proc`, so the
911/// pid is a guest pid. A pidfd Detcore did not open cannot be classified.
912pub(crate) fn classify_process_directory(
913    facts: Option<&DescriptorFacts>,
914) -> ProcessDirectoryDescriptor {
915    use ProcessDirectoryDescriptor as D;
916    let Some(facts) = facts else {
917        return D::Unknown("Hermit cannot read what the descriptor names");
918    };
919    let link = facts.link.to_string_lossy();
920    if link == "anon_inode:[pidfd]" || link.starts_with("pidfd:") {
921        return D::Unknown("it is a pidfd that Detcore did not open with pidfd_open");
922    }
923    if !facts.on_procfs {
924        return D::NotAProcess;
925    }
926    if !facts.is_dir {
927        return D::NotAProcess;
928    }
929    let name = facts
930        .link
931        .file_name()
932        .map(|name| name.to_string_lossy().into_owned())
933        .unwrap_or_default();
934    // A reaped task's directory is spelled with " (deleted)", and its ".."
935    // cannot be read (ESRCH); Linux still takes it as the task, and answers
936    // ESRCH for it. The spelling is then the only evidence, so it must be a
937    // top-level entry of the guest's /proc.
938    let name = match name.strip_suffix(" (deleted)") {
939        Some(name) if facts.parent.is_none() => {
940            if facts.link.parent() != Some(Path::new("/proc")) {
941                return if facts.link.starts_with("/proc/") {
942                    D::NotAProcess
943                } else {
944                    D::Unknown("it names a reaped task outside the guest's /proc")
945                };
946            }
947            name.to_owned()
948        }
949        _ if facts.parent != Some((facts.dev, PROC_ROOT_INO)) => return D::NotAProcess,
950        _ => name,
951    };
952    let Ok(pid) = name.parse::<i32>() else {
953        return D::NotAProcess;
954    };
955    if pid <= 0 || name.starts_with(['+', '0']) {
956        return D::NotAProcess;
957    }
958    if facts.guest_proc_dev != Some(facts.dev) {
959        return D::Unknown("it is a procfs that is not the guest's /proc");
960    }
961    D::Process(DetPid::from_raw(pid))
962}
963
964/// Read the facts for the guest descriptor `fd` of thread `tid` through
965/// `/proc/<tid>/fd/<fd>` and classify it (`classify_process_directory`).
966fn process_directory_descriptor(tid: i32, fd: RawFd) -> ProcessDirectoryDescriptor {
967    let facts = (|| {
968        let (link, on_procfs) = descriptor_identity(tid, fd)?;
969        let target = std::fs::metadata(format!("/proc/{tid}/fd/{fd}")).ok()?;
970        let parent = std::fs::metadata(format!("/proc/{tid}/fd/{fd}/.."))
971            .ok()
972            .map(|parent| (parent.dev(), parent.ino()));
973        let guest_proc_dev = std::fs::metadata(format!("/proc/{tid}/root/proc"))
974            .ok()
975            .filter(|proc| proc.ino() == PROC_ROOT_INO)
976            .map(|proc| proc.dev());
977        Some(DescriptorFacts {
978            link,
979            on_procfs,
980            is_dir: target.is_dir(),
981            dev: target.dev(),
982            parent: if target.is_dir() { parent } else { None },
983            guest_proc_dev,
984        })
985    })();
986    classify_process_directory(facts.as_ref())
987}
988
989/// The host's default huge page size (`Hugepagesize` in /proc/meminfo), the
990/// size of a MAP_HUGETLB mapping that names none, or 2 MiB, the x86_64
991/// default, when it cannot be read (see [`may_change_untraced_code`]).
992fn default_huge_page_size() -> u64 {
993    static SIZE: std::sync::OnceLock<u64> = std::sync::OnceLock::new();
994    *SIZE.get_or_init(|| {
995        std::fs::read_to_string("/proc/meminfo")
996            .ok()
997            .and_then(|meminfo| {
998                let line = meminfo
999                    .lines()
1000                    .find(|line| line.starts_with("Hugepagesize:"))?;
1001                let kib: u64 = line.split_whitespace().nth(1)?.parse().ok()?;
1002                kib.checked_mul(1024)
1003            })
1004            .unwrap_or(2 << 20)
1005    })
1006}
1007
1008/// What a guest descriptor is, read through the opening thread's
1009/// `/proc/<tid>/fd/<fd>`: its link as the kernel spells it, and whether the
1010/// file is on procfs (see [`may_write_process_memory`]). Read through the
1011/// thread because its descriptor table may not be its leader's (a thread
1012/// cloned without CLONE_FILES). `None` when either cannot be read.
1013fn descriptor_identity(tid: i32, fd: RawFd) -> Option<(PathBuf, bool)> {
1014    let path = format!("/proc/{tid}/fd/{fd}");
1015    let link = std::fs::read_link(&path).ok()?;
1016    let path = std::ffi::CString::new(path).ok()?;
1017    let mut buf = std::mem::MaybeUninit::<libc::statfs>::uninit();
1018    // SAFETY: `path` is NUL-terminated and `buf` is large enough for statfs.
1019    if unsafe { libc::statfs(path.as_ptr(), buf.as_mut_ptr()) } != 0 {
1020        return None;
1021    }
1022    // SAFETY: statfs succeeded, so it filled `buf`.
1023    let on_procfs = unsafe { buf.assume_init() }.f_type == libc::PROC_SUPER_MAGIC;
1024    Some((link, on_procfs))
1025}
1026
1027/// Resolve an `AT_FDCWD`-relative spelling in the guest's filesystem view.
1028///
1029/// Replayer chroots the guest, so the tracer-visible cwd includes the replay
1030/// root. Stripping `/proc/<pid>/root` produces the same guest-absolute path in
1031/// record and replay without depending on the opened descriptor (which is an
1032/// eventfd placeholder during replay).
1033fn resolved_at_fdcwd_path(pid: i32, path: &Path) -> Option<PathBuf> {
1034    debug_assert!(!path.is_absolute());
1035    let root = std::fs::read_link(format!("/proc/{pid}/root")).ok()?;
1036    let cwd = std::fs::read_link(format!("/proc/{pid}/cwd")).ok()?;
1037    let guest_cwd = cwd.strip_prefix(root).ok()?;
1038    Some(Path::new("/").join(guest_cwd).join(path))
1039}
1040
1041/// Whether removing a name of the file `stat` describes leaves it with no
1042/// name: a directory has only one, and a non-directory with one link loses
1043/// its last. A host may then give its inode to another file
1044/// (<https://github.com/rrnewton/hermit/issues/3840>).
1045fn retires_on_removal(stat: &libc::stat) -> bool {
1046    stat.st_mode & libc::S_IFMT == libc::S_IFDIR || stat.st_nlink == 1
1047}
1048
1049/// The path to report for one operand of a successful namespace change (see
1050/// `Detcore::record_host_namespace_change`): the operand made absolute, or
1051/// `/` when it could not be read or made absolute. A tracer that may not read
1052/// a non-dumpable guest's memory, for one, cannot read it while the change
1053/// itself succeeds. `/` is an ancestor of every path, so no host input change
1054/// is named in that run, rather than one the guest may have made.
1055fn rebound_path(observed: Option<PathBuf>) -> String {
1056    match observed {
1057        Some(path) if path.is_absolute() => path.to_string_lossy().into_owned(),
1058        _ => String::from("/"),
1059    }
1060}
1061
1062/// Whether the raw call `number(args)` may change the guest memory in
1063/// `range`, `[start, end)` (see `Config::untraced_code_range`):
1064/// - a fixed mapping over any part of it: `mmap` with MAP_FIXED, `mremap`
1065///   with MREMAP_FIXED, `shmat` with SHM_REMAP;
1066/// - a protection, advice or unmapping over any part of it: `mprotect`,
1067///   `pkey_mprotect`, `madvise`, `munmap`, the old range of `mremap`.
1068///
1069/// Linux takes page-aligned addresses for these calls and rounds a length up
1070/// to whole pages, and `range` is whole pages, so the unrounded interval
1071/// overlaps it exactly when the rounded one does. A MAP_HUGETLB `mmap` rounds
1072/// to its own page size on both ends, so it is widened to the size its
1073/// MAP_HUGE_* bits name, or else to `default_huge_page` (the host's
1074/// `Hugepagesize`). A zero length counts as its first byte, and a `shmat` as
1075/// reaching the end of the address space, since its size is the segment's.
1076/// A mapping without a fixed address never lands on an existing one, and the
1077/// guest's `process_vm_writev`, `ptrace` and `remap_file_pages` are refused.
1078/// Scalar arguments are never read as addresses, so an ordinary call is
1079/// never counted.
1080pub(crate) fn may_change_untraced_code(
1081    number: Sysno,
1082    args: &syscalls::SyscallArgs,
1083    (start, end): (u64, u64),
1084    default_huge_page: u64,
1085) -> bool {
1086    let [arg0, arg1, arg2, arg3, arg4] =
1087        [args.arg0, args.arg1, args.arg2, args.arg3, args.arg4].map(|arg| arg as u64);
1088    let overlaps = |addr: u64, len: u64| addr < end && addr.saturating_add(len.max(1)) > start;
1089    let overlaps_huge = |addr: u64, len: u64, page: u64| {
1090        let page = page.max(1);
1091        let first = addr - addr % page;
1092        let last = addr
1093            .saturating_add(len.max(1))
1094            .div_ceil(page)
1095            .saturating_mul(page);
1096        overlaps(first, last.saturating_sub(first).max(1))
1097    };
1098    let huge_page = |flags: u64| match (flags >> libc::MAP_HUGE_SHIFT) & libc::MAP_HUGE_MASK as u64
1099    {
1100        0 => default_huge_page,
1101        shift => 1u64.checked_shl(shift as u32).unwrap_or(u64::MAX),
1102    };
1103    match number {
1104        Sysno::mmap if arg3 & libc::MAP_FIXED as u64 == 0 => false,
1105        Sysno::mmap if arg3 & libc::MAP_HUGETLB as u64 != 0 => {
1106            overlaps_huge(arg0, arg1, huge_page(arg3))
1107        }
1108        Sysno::mmap => overlaps(arg0, arg1),
1109        Sysno::mprotect | Sysno::pkey_mprotect | Sysno::madvise | Sysno::munmap => {
1110            overlaps(arg0, arg1)
1111        }
1112        Sysno::mremap => {
1113            overlaps(arg0, arg1) || (arg3 & libc::MREMAP_FIXED as u64 != 0 && overlaps(arg4, arg2))
1114        }
1115        Sysno::shmat => arg1 != 0 && arg2 & libc::SHM_REMAP as u64 != 0 && overlaps(arg1, u64::MAX),
1116        _ => false,
1117    }
1118}
1119
1120/// Whether an open with `flags` that returned a descriptor may write a
1121/// process's memory: `/proc/<pid>/mem` and `/proc/<pid>/task/<tid>/mem`
1122/// write through page protections. `descriptor` is what the descriptor is,
1123/// read through the opening thread's `/proc/<tid>/fd/<fd>` (see
1124/// [`descriptor_identity`]): its link, which names the file however the guest
1125/// reached it (a symlink, a `/proc/self/fd` reopen), and whether it is on
1126/// procfs. It counts only when it is a procfs file named `mem`, so an
1127/// ordinary file of that name, or a name that leads to a pipe, does not. A
1128/// descriptor that cannot be read at all counts, since Detcore cannot
1129/// establish what it is.
1130pub(crate) fn may_write_process_memory(flags: OFlag, descriptor: Option<(&Path, bool)>) -> bool {
1131    let writes = !flags.contains(OFlag::O_PATH) && flags & OFlag::O_ACCMODE != OFlag::O_RDONLY;
1132    writes
1133        && descriptor.is_none_or(|(link, on_procfs)| {
1134            on_procfs && link.file_name() == Some(std::ffi::OsStr::new("mem"))
1135        })
1136}
1137
1138/// The guest call after which [`Detcore::refresh_description_locks`] reads a
1139/// descriptor's locks.
1140#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1141pub(crate) enum LockCall {
1142    /// `F_OFD_SETLK` or `F_OFD_SETLKW`.
1143    Fcntl,
1144    /// `flock`.
1145    Flock,
1146    /// `pidfd_getfd`, which adds a slot.
1147    PidfdGetfd,
1148    /// `recvmsg` with `SCM_RIGHTS`, which adds a slot.
1149    Recvmsg,
1150}
1151
1152impl LockCall {
1153    /// The call's name, as a refusal names it.
1154    fn name(self) -> &'static str {
1155        match self {
1156            Self::Fcntl => "fcntl",
1157            Self::Flock => "flock",
1158            Self::PidfdGetfd => "pidfd_getfd",
1159            Self::Recvmsg => "recvmsg",
1160        }
1161    }
1162
1163    /// Whether the call can take or release a lock.
1164    fn changes_locks(self) -> bool {
1165        matches!(self, Self::Fcntl | Self::Flock)
1166    }
1167}
1168
1169/// The inode number an fdinfo names (its `ino:` line), as `/proc/locks`
1170/// prints the last field of a lock's object.
1171fn fdinfo_inode(fdinfo: &[u8]) -> Option<String> {
1172    String::from_utf8_lossy(fdinfo)
1173        .lines()
1174        .find_map(|line| line.strip_prefix("ino:"))
1175        .map(|inode| inode.trim().to_string())
1176        .filter(|inode| !inode.is_empty() && inode.bytes().all(|byte| byte.is_ascii_digit()))
1177}
1178
1179/// The fdinfo page [`Detcore::read_own_fdinfo`] stages its calls in, and its
1180/// layout: the path, `openat2`'s `struct open_how`, the `fstatfs`/`fstat`
1181/// buffer, then the read buffer.
1182const FDINFO_PAGE: usize = 4096;
1183const FDINFO_PATH: usize = 0;
1184const FDINFO_HOW: usize = 64;
1185const FDINFO_HOW_SIZE: usize = 24;
1186const FDINFO_STAT: usize = 128;
1187const FDINFO_READ: usize = 512;
1188const _: () = assert!(FDINFO_HOW + FDINFO_HOW_SIZE <= FDINFO_STAT);
1189const _: () = assert!(FDINFO_STAT + std::mem::size_of::<libc::stat>() <= FDINFO_READ);
1190const _: () = assert!(FDINFO_STAT + std::mem::size_of::<libc::statfs>() <= FDINFO_READ);
1191/// `openat2`'s resolution for the fdinfo entry: no step out of the anchor
1192/// and no mount crossed.
1193const FDINFO_RESOLVE: u64 = libc::RESOLVE_NO_XDEV | libc::RESOLVE_BENEATH;
1194
1195/// What [`Detcore::read_own_fdinfo`] found.
1196pub(crate) enum FdinfoRead {
1197    /// The fdinfo's text, from an entry proved to be on the guest's procfs.
1198    Contents(Vec<u8>),
1199    /// A step failed for a reason that says nothing about the description's
1200    /// locks: they are unknown (`procfs::locks::LockLedger::note_unknown`).
1201    Unknown(String),
1202    /// The guest's `/proc` could not be proved to be procfs, or a step failed
1203    /// for a cause the guest's own view or the backend decides
1204    /// ([`fdinfo_failure_hides`]): the description contributes no lock, which
1205    /// can hide the guest's row but never admits a host's.
1206    Untrackable(String),
1207}
1208
1209impl FdinfoRead {
1210    /// The inode number the fdinfo names, if it was read.
1211    fn inode(&self) -> Option<String> {
1212        match self {
1213            Self::Contents(contents) => fdinfo_inode(contents),
1214            Self::Unknown(_) | Self::Untrackable(_) => None,
1215        }
1216    }
1217}
1218
1219/// Why [`Detcore::read_staged_fdinfo`] did not read an fdinfo.
1220enum FdinfoFailure {
1221    /// A step (`open`, `fstatfs`, `fstat`, `read`) failed with an errno.
1222    Failed(&'static str, Errno),
1223    /// The guest's `/proc` was shown not to be procfs, for this reason.
1224    NotProcfs(&'static str),
1225}
1226
1227/// Whether an fdinfo step that failed with `errno` shows the description
1228/// is untrackable: a cause the guest's own filesystem view or the backend
1229/// decides, the same in every run of the same program (no `/proc` or an
1230/// entry missing, ENOENT or ENOTDIR; a symlink loop, ELOOP; an entry outside
1231/// the anchor or across a mount, EXDEV; a backend that refuses the call,
1232/// EINVAL, as KVM refuses an `O_PATH` open of its `/proc`). Every other
1233/// errno, ambient or resource state that can differ between runs, leaves the
1234/// locks unknown, so a later `/proc/locks` read refuses rather than shows a
1235/// row that depends on host state: a full descriptor table, EMFILE; a full
1236/// host file table, ENFILE; no memory, ENOMEM; an interruption, EINTR; an I/O
1237/// error, EIO; EAGAIN; a kernel without `openat2`, ENOSYS; a permission
1238/// refusal, EACCES or EPERM, which a host security module keyed by the host
1239/// process can give as well as the guest's own seccomp filter; anything
1240/// unlisted.
1241fn fdinfo_failure_hides(errno: Errno) -> bool {
1242    matches!(
1243        errno,
1244        Errno::ENOENT | Errno::ENOTDIR | Errno::ELOOP | Errno::EXDEV | Errno::EINVAL
1245    )
1246}
1247
1248/// Why Detcore does not know which locks the description descriptor `fd`
1249/// names holds after the guest's `call` through it: `step` (the open or a
1250/// read of its fdinfo) failed with `errno`. A failure says nothing about
1251/// which locks it holds (`Detcore::read_own_fdinfo`); a later `/proc/locks`
1252/// read refuses with this reason (`procfs::locks::LockLedger::unknown`).
1253fn fdinfo_refusal(call: &str, fd: RawFd, step: &str, errno: Errno) -> String {
1254    format!(
1255        "after {call} on fd {fd}, Detcore could not {step} that descriptor's fdinfo \
1256         ({errno}), so it does not know which locks the description holds"
1257    )
1258}
1259
1260#[cfg(test)]
1261mod fdinfo_refusal_tests {
1262    use super::*;
1263
1264    /// A guest at its descriptor limit gets EMFILE from Detcore's fdinfo
1265    /// open after a lock call that needed no new descriptor; a later
1266    /// `/proc/locks` read stops the run with that named, naming the call,
1267    /// rather than taking the description to hold nothing. hermit-cli's
1268    /// `a_full_descriptor_table_refuses_the_next_proc_locks_read` runs that
1269    /// end to end; this pins the reason's wording.
1270    #[test]
1271    fn a_failed_fdinfo_read_is_a_named_refusal_not_an_empty_one() {
1272        let reason = fdinfo_refusal("recvmsg", 7, "open", Errno::EMFILE);
1273        assert!(reason.contains("after recvmsg on fd 7"), "{reason}");
1274        assert!(
1275            reason.contains("could not open that descriptor's fdinfo"),
1276            "{reason}"
1277        );
1278        assert!(reason.contains("EMFILE"), "{reason}");
1279        assert!(fdinfo_refusal("flock", 7, "read", Errno::EIO).contains("could not read that"));
1280    }
1281
1282    /// A failure the guest's filesystem view or the backend decides hides
1283    /// the description; ambient or resource state, and anything unlisted,
1284    /// leaves its locks unknown (and a later `/proc/locks` read refused).
1285    #[test]
1286    fn only_a_guest_or_backend_decided_failure_hides_the_description() {
1287        for errno in [
1288            Errno::ENOENT,
1289            Errno::ENOTDIR,
1290            Errno::ELOOP,
1291            Errno::EXDEV,
1292            Errno::EINVAL,
1293        ] {
1294            assert!(fdinfo_failure_hides(errno), "{errno}");
1295        }
1296        for errno in [
1297            Errno::EACCES,
1298            Errno::EPERM,
1299            Errno::EMFILE,
1300            Errno::ENFILE,
1301            Errno::ENOMEM,
1302            Errno::EINTR,
1303            Errno::EIO,
1304            Errno::EAGAIN,
1305            Errno::ENOSYS,
1306            Errno::EBADF,
1307        ] {
1308            assert!(!fdinfo_failure_hides(errno), "{errno}");
1309        }
1310    }
1311
1312    #[test]
1313    fn an_fdinfo_names_its_inode_as_proc_locks_prints_it() {
1314        let fdinfo = b"pos:\t0\nflags:\t0100002\nmnt_id:\t31\nino:\t1234\n\
1315            lock:\t1: OFDLCK ADVISORY READ -1 00:18:1234 0 0\n";
1316        assert_eq!(fdinfo_inode(fdinfo).as_deref(), Some("1234"));
1317        assert_eq!(fdinfo_inode(b"pos:\t0\n"), None);
1318        assert_eq!(fdinfo_inode(b"ino:\tx\n"), None);
1319    }
1320}
1321
1322/// Writes back the guest bytes that a pre-call lookup buffer (utimensat's, or
1323/// the removal lookup's) covered.
1324fn restore_lookup_buffer<M: MemoryAccess>(memory: &mut M, buffer: StatPtr, saved: &[u8]) {
1325    if memory.write_exact(buffer.0.cast(), saved).is_err() {
1326        info!("Could not restore the guest bytes under a pre-call lookup buffer.");
1327    }
1328}
1329
1330/// Whether a lookup `buffer` overlaps `path` through its NUL, which a guest
1331/// call still has to read. A path that cannot be read counts as overlapping,
1332/// so that the kernel, not a lookup, reports the fault.
1333fn path_overlaps_buffer<M: MemoryAccess>(
1334    memory: &M,
1335    path: Option<syscalls::PathPtr<'_>>,
1336    buffer: StatPtr,
1337) -> bool {
1338    path_overlaps_bytes(
1339        memory,
1340        path,
1341        buffer.0.as_raw(),
1342        std::mem::size_of::<libc::stat>(),
1343    )
1344}
1345
1346/// Whether the `len` bytes at `start` overlap `path` through its NUL. A path
1347/// that cannot be read counts as overlapping.
1348fn path_overlaps_bytes<M: MemoryAccess>(
1349    memory: &M,
1350    path: Option<syscalls::PathPtr<'_>>,
1351    start: usize,
1352    len: usize,
1353) -> bool {
1354    use reverie::syscalls::FromToRaw;
1355
1356    let end = start.saturating_add(len);
1357    path.is_some_and(|ptr| match ptr.read(memory) {
1358        Ok(read) => {
1359            let addr = Some(ptr).into_raw();
1360            let read: PathBuf = read;
1361            addr < end && start < addr.saturating_add(read.as_os_str().len() + 1)
1362        }
1363        Err(_) => true,
1364    })
1365}
1366
1367/// Whether the utimensat lookup buffer overlaps the guest memory Linux reads
1368/// for `call`: the path through its NUL and, with `guest_times`, the two
1369/// timespecs. A path that cannot be read counts as overlapping, so that the
1370/// kernel, not a lookup, reports the fault.
1371fn utimensat_input_overlaps<M: MemoryAccess>(
1372    memory: &M,
1373    call: &syscalls::Utimensat,
1374    guest_times: bool,
1375    buffer: StatPtr,
1376) -> bool {
1377    let start = buffer.0.as_raw();
1378    let end = start + std::mem::size_of::<libc::stat>();
1379    let overlaps = |addr: usize, len: usize| addr < end && start < addr.saturating_add(len);
1380    let path = path_overlaps_buffer(memory, call.path(), buffer);
1381    let times = guest_times
1382        && call
1383            .times()
1384            .is_some_and(|times| overlaps(times.as_raw(), std::mem::size_of::<[Timespec; 2]>()));
1385    path || times
1386}
1387
1388/// Whether a `*at` stat call names no path: it passes `AT_EMPTY_PATH` with an
1389/// empty or NULL path (Linux 6.11 accepts NULL), and so describes `dirfd`
1390/// itself, or the working directory for `AT_FDCWD`. A path that cannot be
1391/// read counts as nonempty, so the call keeps the path-based numbering and
1392/// the kernel reports the fault. The path is read only after the flag check,
1393/// so an ordinary `stat()` reads no guest memory here.
1394fn names_no_path<M: MemoryAccess>(memory: &M, path: Option<PathPtr>, flags: AtFlags) -> bool {
1395    flags.contains(AtFlags::AT_EMPTY_PATH)
1396        && match path {
1397            None => true,
1398            Some(path) => path
1399                .read(memory)
1400                .is_ok_and(|path| path.as_os_str().is_empty()),
1401        }
1402}
1403
1404/// The fixed inode that `fd` reports when it is still the container's
1405/// inherited stdin, stdout or stderr, as fdinfo and `/proc/self/fd/N` report
1406/// it. Every stat call that describes the descriptor itself must use it, or
1407/// the guest's libc decides which number `fstat()` sees.
1408fn stdio_inode_override<T: RecordOrReplay, G: Guest<Detcore<T>>>(
1409    guest: &G,
1410    fd: i32,
1411) -> Option<DetInode> {
1412    guest
1413        .thread_state()
1414        .with_detfd(fd, |detfd| {
1415            deterministic_stdio_inode_for_resource(fd, detfd.resource())
1416        })
1417        .ok()
1418        .flatten()
1419}
1420
1421/// The file a stat call describes, as Detcore finds it again to learn the
1422/// canonical path of a procfs file (see [`procfs_inode`]).
1423#[derive(Clone, Copy)]
1424enum StatTarget<'a> {
1425    /// The file open as this descriptor.
1426    Descriptor(RawFd),
1427    /// The calling thread's working directory.
1428    Cwd,
1429    /// The file `path` names relative to `dirfd`, or the symbolic link itself
1430    /// when `follow` is false.
1431    Path {
1432        dirfd: i32,
1433        path: Option<PathPtr<'a>>,
1434        follow: bool,
1435    },
1436    /// A file named by a path that the call's result overwrote, which Detcore
1437    /// cannot look up again.
1438    Overwritten,
1439}
1440
1441impl<'a> StatTarget<'a> {
1442    /// The target of an `fstatat` or `statx` call with these operands.
1443    fn at<M: MemoryAccess>(
1444        memory: &M,
1445        dirfd: i32,
1446        path: Option<PathPtr<'a>>,
1447        flags: AtFlags,
1448    ) -> Self {
1449        if names_no_path(memory, path, flags) {
1450            if dirfd == libc::AT_FDCWD {
1451                return StatTarget::Cwd;
1452            }
1453            if dirfd >= 0 {
1454                return StatTarget::Descriptor(dirfd);
1455            }
1456        }
1457        StatTarget::Path {
1458            dirfd,
1459            path,
1460            follow: !flags.contains(AtFlags::AT_SYMLINK_NOFOLLOW),
1461        }
1462    }
1463
1464    /// This target, or [`StatTarget::Overwritten`] if it is a path that the
1465    /// `len` bytes of the call's result at `result` overlap. Linux reads the
1466    /// path before it writes the result, so the call succeeds, but the path
1467    /// the guest named is gone once it returns. Found before the call.
1468    fn unless_overwritten<M: MemoryAccess>(self, memory: &M, result: usize, len: usize) -> Self {
1469        match self {
1470            StatTarget::Path { path, .. } if path_overlaps_bytes(memory, path, result, len) => {
1471                StatTarget::Overwritten
1472            }
1473            target => target,
1474        }
1475    }
1476
1477    /// The descriptor the call describes itself, if it names no path.
1478    fn descriptor(&self) -> Option<RawFd> {
1479        match self {
1480            StatTarget::Descriptor(fd) => Some(*fd),
1481            StatTarget::Cwd | StatTarget::Path { .. } | StatTarget::Overwritten => None,
1482        }
1483    }
1484}
1485
1486/// The rendered procfs file that a stat result describes, if it is one: by
1487/// the name Detcore gave it, or by its kernel identity where Detcore names no
1488/// procfs files. Never a per-process file, whose kernel-reached instances
1489/// keep the kernel's identity. `files` are the files the session renders
1490/// (`Detcore::rendered_files`).
1491fn rendered_entry(
1492    procfs: &ProcfsEntry,
1493    stat: &DetStat,
1494    cfg: &crate::config::Config,
1495    files: crate::procfs::RenderedFiles,
1496) -> Option<&'static Path> {
1497    if cfg.recordreplay_modes {
1498        return None;
1499    }
1500    let found = match procfs {
1501        ProcfsEntry::At(within) => rendered_procfs::rendered_path_within(within, files),
1502        ProcfsEntry::NotProcfs | ProcfsEntry::Unknown => {
1503            rendered_procfs::rendered_path_of_raw(stat, files)
1504        }
1505        ProcfsEntry::Unnamed => None,
1506    };
1507    // A per-process file the kernel reached (through `..`, after `chroot`,
1508    // in a nested PID namespace) is served from the kernel's bytes
1509    // (`ProcfsFile::served_rendered_path`), so it keeps the kernel's metadata
1510    // too: its identity is the kernel's file's, not the rendered file's.
1511    found.filter(|path| !crate::procfs::rendered_path_is_per_process(path))
1512}
1513
1514/// `STATX_MNT_ID_UNIQUE` (include/uapi/linux/stat.h, since Linux 6.8). Reverie's
1515/// `StatxMask` does not name it and drops it from a mask read through it, so
1516/// Detcore reads a call's raw mask ([`statx_requested_mask`]).
1517const STATX_MNT_ID_UNIQUE: u32 = 0x4000;
1518
1519/// What Linux adds to every unique mount ID so that none equals a classic
1520/// 32-bit one: `MNT_UNIQUE_ID_OFFSET` (v6.12 fs/namespace.c:73). Linux counts
1521/// up from it and never reuses an ID, so the first mount's is the offset plus
1522/// one (fs/namespace.c:74 and 244).
1523const MNT_UNIQUE_ID_OFFSET: u64 = 1 << 31;
1524
1525/// The mask a `statx` call asks for, every bit kept.
1526fn statx_requested_mask(call: syscalls::Statx) -> u32 {
1527    syscalls::SyscallArgs::from(call).arg3 as u32
1528}
1529
1530/// `call` asking the kernel for the classic mount ID (`STATX_MNT_ID`) where
1531/// it asked for the unique one, and otherwise the same call.
1532fn statx_asking_classic_mount_id(call: syscalls::Statx) -> syscalls::Statx {
1533    let mut args = syscalls::SyscallArgs::from(call);
1534    let mask = args.arg3 as u32;
1535    if mask & STATX_MNT_ID_UNIQUE != 0 {
1536        args.arg3 = ((mask & !STATX_MNT_ID_UNIQUE) | libc::STATX_MNT_ID) as usize;
1537    }
1538    syscalls::Statx::from(args)
1539}
1540
1541/// Whether `statx` accepts these `flags` and `mask` (`vfs_statx`'s and the
1542/// syscall's own checks): no reserved mask bit, known flags only (unless the
1543/// call names no path), and not both synchronization types at once.
1544fn statx_arguments_valid(flags: i32, mask: u32, names_no_path: bool) -> bool {
1545    let known = libc::AT_SYMLINK_NOFOLLOW
1546        | libc::AT_EMPTY_PATH
1547        | libc::AT_NO_AUTOMOUNT
1548        | libc::AT_STATX_SYNC_TYPE;
1549    // A call on the descriptor itself (`AT_EMPTY_PATH` with an empty or
1550    // NULL path) does not look at the other flags (measured on Linux 7.1).
1551    mask & 0x8000_0000 == 0
1552        && (names_no_path || flags & !known == 0)
1553        && flags & libc::AT_STATX_SYNC_TYPE != libc::AT_STATX_SYNC_TYPE
1554}
1555
1556/// Whether `path` spells a descriptor link: `/dev/fd/N`, `/proc/*/fd/N` or
1557/// `/proc/*/task/*/fd/N`.
1558fn names_descriptor_link(path: &Path) -> bool {
1559    let parts = path
1560        .components()
1561        .filter_map(|component| match component {
1562            std::path::Component::Normal(part) => {
1563                Some(std::os::unix::ffi::OsStrExt::as_bytes(part))
1564            }
1565            _ => None,
1566        })
1567        .collect::<Vec<_>>();
1568    let number = |part: &[u8]| !part.is_empty() && part.iter().all(u8::is_ascii_digit);
1569    match parts.as_slice() {
1570        [b"dev", b"fd", fd] | [b"proc", _, b"fd", fd] | [b"proc", _, b"task", _, b"fd", fd] => {
1571            number(fd)
1572        }
1573        _ => false,
1574    }
1575}
1576
1577/// Who opens a path that may be one of its descriptor links, for
1578/// [`path_to_record_for_open`].
1579#[derive(Debug, Clone, Copy)]
1580struct DescriptorLinkOpener {
1581    /// The caller's pid and tid as the guest's `/proc/<pid>` and
1582    /// `.../task/<tid>` spellings name them on every backend, or `None`
1583    /// where Detcore does not know those names (a nested PID namespace).
1584    /// See [`Detcore::procfs_caller_ids`].
1585    own: Option<(i32, i32)>,
1586    /// Whether the descriptor table procfs reads for a process-level link
1587    /// (`/proc/self/fd/N`, `/dev/fd/N`), the thread-group leader's, is
1588    /// provably the caller's own: the caller leads its group, or holds the
1589    /// table the leader holds now (`ThreadState::process_files`). A thread
1590    /// cloned without `CLONE_FILES` holds a table of its own.
1591    holds_process_table: bool,
1592}
1593
1594/// The descriptor `N` that a descriptor link in an open's spelling names,
1595/// as it stood when the open looked the link up: in the open's own turn,
1596/// before the call, which may block and leave the turn (a FIFO waiting for
1597/// its other end) while a thread sharing the table replaces `N`. The kernel
1598/// follows the link at that lookup, so the file it opens is the one `N` was
1599/// then, whatever `N` is when the open completes.
1600#[derive(Debug, Clone, PartialEq, Eq)]
1601struct LinkSource {
1602    fd: RawFd,
1603    /// The path Detcore had recorded for `N`.
1604    path: Option<PathBuf>,
1605    /// `N`'s open file description.
1606    open_file: OpenFileId,
1607    /// Where `N`'s `/proc/self` or `/proc/thread-self` spelling led, and the
1608    /// identity of the task it led to (`DetFd::procfs_reached`).
1609    reached: Option<(PathBuf, Option<crate::procfs::TaskIncarnation>)>,
1610}
1611
1612impl LinkSource {
1613    /// The path to record, for [`path_to_record_for_open`], for descriptor
1614    /// `fd` of the caller's table, whose open file description is `current`
1615    /// when the open completes: `N`'s path as the lookup saw it, only if
1616    /// `fd` is `N` and `N` still holds that description. Where `N` was
1617    /// replaced meanwhile, nothing, and the open keeps its spelling, as
1618    /// before this change.
1619    fn path_if_unchanged(&self, fd: RawFd, current: Option<OpenFileId>) -> Option<PathBuf> {
1620        (fd == self.fd && current == Some(self.open_file))
1621            .then(|| self.path.clone())
1622            .flatten()
1623    }
1624
1625    /// Where `N`'s selector spelling led, for a new descriptor opened through
1626    /// the link to `N` (`fd`), only if `fd` is `N` and `N` still holds its
1627    /// description: the new open file is that task's directory too.
1628    fn reached_if_unchanged(
1629        &self,
1630        fd: RawFd,
1631        current: Option<OpenFileId>,
1632    ) -> Option<(PathBuf, Option<crate::procfs::TaskIncarnation>)> {
1633        (fd == self.fd && current == Some(self.open_file))
1634            .then(|| self.reached.clone())
1635            .flatten()
1636    }
1637}
1638
1639/// Where the spelling `recorded` led, if it names a task's directory: through
1640/// a `/proc` selector, `/proc/self`, `/proc/self/task`,
1641/// `/proc/self/task/<tid>` or `/proc/thread-self`, with the selector replaced
1642/// by the opener's numbers (`own`, its pid and tid as `/proc` spells them), as
1643/// Linux resolved it at the open; or by number, `/proc/<pid>`,
1644/// `/proc/<pid>/task` or `/proc/<pid>/task/<tid>`, itself
1645/// (`DetFd::procfs_reached`). Linux binds the directory to the task it named
1646/// at the open, not to the number, so either is that task while it lives.
1647/// Nothing for any other path, such as a descriptor link (`fd/N`), which
1648/// leads to another file, and nothing where Detcore does not know the
1649/// caller's numbers (`own` is `None` in a nested PID namespace).
1650fn procfs_selector_reached(recorded: &Path, own: Option<(i32, i32)>) -> Option<PathBuf> {
1651    let (pid, tid) = own?;
1652    let below = recorded.strip_prefix("/proc").ok()?;
1653    let names = below
1654        .components()
1655        .map(|component| match component {
1656            std::path::Component::Normal(name) => name.to_str(),
1657            _ => None,
1658        })
1659        .collect::<Option<Vec<_>>>()?;
1660    let number = |name: &str| {
1661        (!name.starts_with('0') && !name.is_empty() && name.bytes().all(|b| b.is_ascii_digit()))
1662            .then(|| name.parse::<i32>().ok())
1663            .flatten()
1664    };
1665    Some(PathBuf::from(match names.as_slice() {
1666        ["self"] => format!("/proc/{pid}"),
1667        ["self", "task"] => format!("/proc/{pid}/task"),
1668        ["self", "task", thread] => format!("/proc/{pid}/task/{}", number(thread)?),
1669        ["thread-self"] => format!("/proc/{pid}/task/{tid}"),
1670        [process] => format!("/proc/{}", number(process)?),
1671        [process, "task"] => format!("/proc/{}/task", number(process)?),
1672        [process, "task", thread] => {
1673            format!("/proc/{}/task/{}", number(process)?, number(thread)?)
1674        }
1675        _ => return None,
1676    }))
1677}
1678
1679/// The task whose directory `reached` (where a `/proc` selector led,
1680/// `procfs_selector_reached`) is or is below: `/proc/<pid>`, and the thread of
1681/// `/proc/<pid>/task/<tid>`.
1682fn procfs_reached_task(reached: &Path) -> Option<crate::procfs::BoundTask> {
1683    let names = reached
1684        .strip_prefix("/proc")
1685        .ok()?
1686        .components()
1687        .map(|component| component.as_os_str().to_str())
1688        .collect::<Option<Vec<_>>>()?;
1689    let number = |name: &str| name.parse::<i32>().ok().filter(|number| *number > 0);
1690    let process = number(names.first()?)?;
1691    let thread = match names.as_slice() {
1692        [_, "task", thread, ..] => Some(number(thread)?),
1693        _ => None,
1694    };
1695    Some(crate::procfs::BoundTask { process, thread })
1696}
1697
1698/// Whether `spelling` names a `/proc` selector link itself: `/proc/self` or
1699/// `/proc/thread-self`, which are symbolic links to a task's directory.
1700fn names_a_selector_link(spelling: &Path) -> bool {
1701    spelling.parent() == Some(Path::new("/proc"))
1702        && spelling
1703            .file_name()
1704            .is_some_and(|name| name == "self" || name == "thread-self")
1705}
1706
1707/// Whether an open of the absolute spelling `observed` with `flags` opens a
1708/// descriptor link itself rather than the file it reaches: `O_NOFOLLOW`
1709/// does not follow the last component (with `O_PATH` the link is opened,
1710/// without it the open fails with `ELOOP`), unless the spelling follows it
1711/// anyway with a trailing slash or `/.`.
1712fn opens_the_link_itself(observed: &Path, flags: OFlag) -> bool {
1713    let bytes = std::os::unix::ffi::OsStrExt::as_bytes(observed.as_os_str());
1714    flags.contains(OFlag::O_NOFOLLOW) && !(bytes.ends_with(b"/") || bytes.ends_with(b"/."))
1715}
1716
1717/// The path Detcore records for a descriptor the guest opened at the absolute
1718/// spelling `observed` with `flags`. Opened through one of the caller's own
1719/// descriptor links (`/proc/self/fd/N`, `/dev/fd/N`, ... see
1720/// [`crate::syscalls::namespace::own_descriptor_link`]), the new descriptor
1721/// is the file that descriptor `N` is, so it takes the path recorded for `N`
1722/// (by `recorded`): a name relative to the new descriptor is then looked up
1723/// below that file, as Linux looks it up, and not below the link's spelling,
1724/// which names no procfs file of its own.
1725///
1726/// It keeps the spelling, as every other open does, wherever the recorded
1727/// path could name another file than the one the kernel opened:
1728/// - the open does not follow the link (`O_NOFOLLOW` without a trailing
1729///   slash or `/.`), so it opened the link itself;
1730/// - the link names the process's table, which is the thread-group
1731///   leader's, and the caller is not proven to hold that table
1732///   (`opener.holds_process_table`); `recorded` reads the caller's;
1733/// - descriptor `N` has no recorded path, or a relative one;
1734/// - `N`'s recorded path is resolved per caller (`/proc/self`,
1735///   `/proc/thread-self`, `/dev/fd`, ... see
1736///   [`crate::syscalls::namespace::names_through_caller_selector`]): `N` is
1737///   the file its opener reached, which another process or thread that
1738///   inherited or shares it would not reach by that path.
1739///
1740/// Where the link names the caller's own table and `N` has no recorded path
1741/// at all, as for a descriptor received through `SCM_RIGHTS`, `identity` is
1742/// recorded instead if given: the procfs directory that the kernel names for
1743/// the opened descriptor (see `Detcore::procfs_directory_named_for`). Not
1744/// where `N`'s recorded path is refused above, nor where the link names a
1745/// table the caller is not proven to hold, whose `N` is not the one
1746/// `recorded` describes.
1747fn path_to_record_for_open(
1748    observed: &Path,
1749    flags: OFlag,
1750    opener: DescriptorLinkOpener,
1751    recorded: impl FnOnce(RawFd) -> Option<PathBuf>,
1752    identity: Option<PathBuf>,
1753) -> PathBuf {
1754    use crate::syscalls::namespace::DescriptorTable;
1755    if opens_the_link_itself(observed, flags) {
1756        return observed.to_path_buf();
1757    }
1758    let Some(link) = crate::syscalls::namespace::own_descriptor_link(observed, opener.own) else {
1759        return observed.to_path_buf();
1760    };
1761    if !(link.table == DescriptorTable::Thread || opener.holds_process_table) {
1762        return observed.to_path_buf();
1763    }
1764    match recorded(link.fd) {
1765        Some(path) => {
1766            (!crate::syscalls::namespace::names_through_caller_selector(&path)).then_some(path)
1767        }
1768        None => identity,
1769    }
1770    .unwrap_or_else(|| observed.to_path_buf())
1771}
1772
1773/// The components below `/proc` of the kernel's name for a procfs directory
1774/// (a descriptor link), and the positions among them of the task numbers it
1775/// names: `/proc/<pid>` and its `task/<tid>`. `None` for a name outside
1776/// `/proc`, a deleted or anonymous object, a relative name, or a task number
1777/// procfs would not have (a leading zero).
1778fn procfs_directory_task_positions(link: &str) -> Option<(Vec<String>, Vec<usize>)> {
1779    if link.ends_with(" (deleted)") {
1780        return None;
1781    }
1782    let below = link.strip_prefix("/proc")?;
1783    if !(below.is_empty() || below.starts_with('/')) {
1784        return None;
1785    }
1786    let names = below
1787        .split('/')
1788        .filter(|name| !name.is_empty())
1789        .map(str::to_owned)
1790        .collect::<Vec<_>>();
1791    if names.iter().any(|name| name == "." || name == "..") {
1792        return None;
1793    }
1794    let number = |name: &str| {
1795        !name.is_empty() && !name.starts_with('0') && name.bytes().all(|byte| byte.is_ascii_digit())
1796    };
1797    let mut positions = Vec::new();
1798    if let Some(first) = names.first()
1799        && first.bytes().all(|byte| byte.is_ascii_digit())
1800    {
1801        if !number(first) {
1802            return None;
1803        }
1804        positions.push(0);
1805        if names.get(1).map(String::as_str) == Some("task")
1806            && let Some(thread) = names.get(2)
1807        {
1808            if !number(thread) {
1809                return None;
1810            }
1811            positions.push(2);
1812        }
1813    }
1814    Some((names, positions))
1815}
1816
1817/// Whether `link`, the kernel's name for a descriptor (its
1818/// `/proc/thread-self/fd/N` link), names a procfs directory path Detcore
1819/// may record for it: `/proc`, or a path below it that names no process or
1820/// thread (`procfs::ids::named_ids`, and no numeric component at all),
1821/// whose numbers are the kernel's and need not be the guest's, nor a
1822/// selector procfs resolves per caller. Not a deleted directory
1823/// (`" (deleted)"`), an anonymous object or a relative target, nor any other
1824/// directory.
1825fn procfs_directory_link(link: &Path) -> bool {
1826    use std::os::unix::ffi::OsStrExt;
1827    let bytes = link.as_os_str().as_bytes();
1828    link.starts_with("/proc")
1829        && !bytes.ends_with(b" (deleted)")
1830        && link.components().all(|component| match component {
1831            std::path::Component::RootDir => true,
1832            std::path::Component::Normal(name) => !name.as_bytes().iter().all(u8::is_ascii_digit),
1833            _ => false,
1834        })
1835        && crate::procfs::ids::named_ids(link).is_empty()
1836        && !crate::syscalls::namespace::names_through_caller_selector(link)
1837}
1838
1839/// Whether a stat call's own arguments are ones Linux accepts before it looks
1840/// up any file: `newfstatat` refuses unknown flags (`vfs_fstatat`), except on
1841/// the descriptor itself (`AT_EMPTY_PATH` with an empty path), which it
1842/// stats without looking at them (measured on Linux 7.1).
1843fn stat_family_arguments_valid<M: MemoryAccess>(memory: &M, call: &StatFamily) -> bool {
1844    match call {
1845        StatFamily::Fstatat(call) => {
1846            let known = libc::AT_SYMLINK_NOFOLLOW
1847                | libc::AT_NO_AUTOMOUNT
1848                | libc::AT_EMPTY_PATH
1849                | libc::AT_STATX_SYNC_TYPE;
1850            names_no_path(memory, call.path(), call.flags()) || call.flags().bits() & !known == 0
1851        }
1852        _ => true,
1853    }
1854}
1855
1856/// The file a call of the stat family describes.
1857fn stat_family_target<'a, M: MemoryAccess>(memory: &M, call: &'a StatFamily) -> StatTarget<'a> {
1858    match call {
1859        StatFamily::Fstat(call) => StatTarget::Descriptor(call.fd()),
1860        StatFamily::Fstatat(call) => {
1861            StatTarget::at(memory, call.dirfd(), call.path(), call.flags())
1862        }
1863        #[cfg(not(target_arch = "aarch64"))]
1864        StatFamily::Stat(call) => StatTarget::Path {
1865            dirfd: libc::AT_FDCWD,
1866            path: call.path(),
1867            follow: true,
1868        },
1869        #[cfg(not(target_arch = "aarch64"))]
1870        StatFamily::Lstat(call) => StatTarget::Path {
1871            dirfd: libc::AT_FDCWD,
1872            path: call.path(),
1873            follow: false,
1874        },
1875    }
1876}
1877
1878/// How many times Detcore injects the `openat` or the `close` of the
1879/// `O_PATH` descriptor it opens in the guest to name a procfs entry when the
1880/// call had no effect, before it records a determinism loss instead.
1881const OBJECT_DESCRIPTOR_ATTEMPTS: usize = 8;
1882
1883/// What Detcore learned of a stat result that may describe a procfs file
1884/// (see [`procfs_inode`]).
1885#[derive(Debug, Clone, PartialEq, Eq)]
1886enum ProcfsEntry {
1887    /// Not a file on a procfs mount, or a mode in which Detcore does not name
1888    /// procfs files.
1889    NotProcfs,
1890    /// A procfs file at this path within procfs.
1891    At(PathBuf),
1892    /// A procfs file that Detcore could not name. It recorded a determinism
1893    /// loss.
1894    Unnamed,
1895    /// A file Detcore could not tell from a procfs file, as it could not read
1896    /// the guest's mount table or the file's filesystem type, or did not look,
1897    /// as the guest's threads are not sequentialized. It recorded a
1898    /// determinism loss.
1899    Unknown,
1900}
1901
1902impl ProcfsEntry {
1903    /// Whether the file is known to be on a procfs mount.
1904    fn is_procfs(&self) -> bool {
1905        matches!(self, ProcfsEntry::At(_) | ProcfsEntry::Unnamed)
1906    }
1907
1908    /// The name of the file, which is on `device`.
1909    fn name(&self, device: u64) -> Option<ProcfsName> {
1910        match self {
1911            ProcfsEntry::At(within) => Some(ProcfsName::new(device, within)),
1912            ProcfsEntry::NotProcfs | ProcfsEntry::Unnamed | ProcfsEntry::Unknown => None,
1913        }
1914    }
1915}
1916
1917impl<T: RecordOrReplay> Detcore<T> {
1918    async fn observe_timer_slack_identity<G: Guest<Self>>(
1919        &self,
1920        guest: &mut G,
1921        target: i32,
1922    ) -> Result<Option<(u64, u64)>, Error> {
1923        // Re-resolve the numeric proc path on every operation. Linux gives a
1924        // recycled TID a different proc inode, while the original open file
1925        // description remains bound to the exited task's inode.
1926        // The kernel's number for the guest's (DBT; `procfs_numbers`): one
1927        // `/proc` does not list has no file to bind.
1928        let Some(target) = Self::kernel_procfs_number(guest, target).await else {
1929            return Ok(None);
1930        };
1931        let path = format!("/proc/{target}/timerslack_ns");
1932        let path_bytes = path.as_bytes();
1933        let mut path_buffer = [0_u8; 64];
1934        assert!(path_bytes.len() < path_buffer.len());
1935        path_buffer[..path_bytes.len()].copy_from_slice(path_bytes);
1936
1937        let mut stack = guest.stack().await;
1938        let path_address = stack.push(path_buffer).cast::<libc::c_char>();
1939        let statptr = StatPtr(stack.reserve());
1940        let stack_guard = stack.commit()?;
1941        let call = syscalls::Fstatat::new()
1942            .with_dirfd(libc::AT_FDCWD)
1943            .with_path(PathPtr::from_ptr(
1944                path_address.as_raw() as *const libc::c_char
1945            ))
1946            .with_stat(Some(statptr))
1947            .with_flags(AtFlags::empty());
1948        let mut identity = match guest.inject_with_retry(call).await {
1949            Ok(_) => {
1950                let stat = statptr.read(&guest.memory())?;
1951                Some((stat.st_dev, stat.st_ino))
1952            }
1953            Err(Errno::ENOENT) | Err(Errno::ESRCH) => None,
1954            Err(error) => return Err(error.into()),
1955        };
1956        drop(stack_guard);
1957        // Replayer runs the guest in a filesystem chroot whose `/proc` path is
1958        // intentionally absent, while the tracing process remains in the same
1959        // PID namespace and can resolve the task through its own proc mount.
1960        // Use that equivalent view only for record/replay; other backends keep
1961        // the guest-path result above as their sole authority.
1962        if identity.is_none()
1963            && guest.config().recordreplay_modes
1964            && let Ok(metadata) = std::fs::metadata(path)
1965        {
1966            identity = Some((metadata.dev(), metadata.ino()));
1967        }
1968        Ok(identity)
1969    }
1970
1971    async fn require_current_timer_slack_target<G: Guest<Self>>(
1972        &self,
1973        guest: &mut G,
1974        binding: TimerSlackBinding,
1975    ) -> Result<(), Error> {
1976        let observed_identity = self
1977            .observe_timer_slack_identity(guest, binding.target)
1978            .await?;
1979        let current = guest.inject(syscalls::Gettid::new()).await? as i32;
1980        classify_timer_slack_binding(binding, observed_identity, current).map_err(Into::into)
1981    }
1982
1983    fn timer_slack_binding<G: Guest<Self>>(
1984        &self,
1985        guest: &G,
1986        fd: RawFd,
1987    ) -> Result<Option<TimerSlackBinding>, Errno> {
1988        guest.thread_state().with_detfd(fd, |detfd| {
1989            detfd
1990                .procfs_timer_slack_binding()
1991                .map(|(target, device, inode)| TimerSlackBinding {
1992                    target,
1993                    device,
1994                    inode,
1995                })
1996        })
1997    }
1998
1999    fn require_timer_slack_access<G: Guest<Self>>(
2000        &self,
2001        guest: &G,
2002        fd: RawFd,
2003        write: bool,
2004    ) -> Result<(), Errno> {
2005        guest.thread_state().with_detfd(fd, |detfd| {
2006            let flags = detfd.status_flags();
2007            let mode = flags & libc::O_ACCMODE;
2008            let denied = flags & libc::O_PATH != 0
2009                || if write {
2010                    mode == libc::O_RDONLY
2011                } else {
2012                    mode == libc::O_WRONLY
2013                };
2014            (!denied).then_some(()).ok_or(Errno::EBADF)
2015        })?
2016    }
2017
2018    fn read_timer_slack_input<G: Guest<Self>>(
2019        &self,
2020        guest: &G,
2021        buffer: Option<Addr<u8>>,
2022        count: usize,
2023    ) -> Result<u64, Errno> {
2024        let mut bytes = vec![0_u8; count.min(TIMER_SLACK_PARSE_BYTES)];
2025        if !bytes.is_empty() {
2026            guest
2027                .memory()
2028                .read_exact(buffer.ok_or(Errno::EFAULT)?, &mut bytes)?;
2029        }
2030        parse_timer_slack_write(&bytes)
2031    }
2032
2033    async fn read_timer_slack<G: Guest<Self>>(
2034        &self,
2035        guest: &mut G,
2036        fd: RawFd,
2037        buffer: Option<AddrMut<'_, u8>>,
2038        maximum: usize,
2039    ) -> Result<i64, Error> {
2040        self.require_timer_slack_access(guest, fd, false)?;
2041        if maximum == 0 {
2042            return Ok(0);
2043        }
2044        let binding = self
2045            .timer_slack_binding(guest, fd)?
2046            .expect("timer-slack read lost its procfs classification");
2047        self.require_current_timer_slack_target(guest, binding)
2048            .await?;
2049        let value = guest.thread_state().timer_slack_ns;
2050        let preview = guest
2051            .thread_state()
2052            .with_detfd(fd, |detfd| detfd.preview_procfs_timer_slack(value, maximum))?
2053            .expect("timer-slack procfs state disappeared");
2054        let copied = copy_timer_slack_output(&mut guest.memory(), buffer, &preview.bytes)?;
2055        if copied != 0 {
2056            guest.thread_state().with_detfd(fd, |detfd| {
2057                detfd.commit_procfs_timer_slack_read(&preview, copied);
2058            })?;
2059        }
2060        Ok(copied as i64)
2061    }
2062
2063    async fn pread_timer_slack<G: Guest<Self>>(
2064        &self,
2065        guest: &mut G,
2066        fd: RawFd,
2067        buffer: Option<AddrMut<'_, u8>>,
2068        maximum: usize,
2069        offset: i64,
2070    ) -> Result<i64, Error> {
2071        if offset < 0 {
2072            return Err(Errno::EINVAL.into());
2073        }
2074        self.require_timer_slack_access(guest, fd, false)?;
2075        if maximum == 0 {
2076            return Ok(0);
2077        }
2078        let binding = self
2079            .timer_slack_binding(guest, fd)?
2080            .expect("timer-slack pread lost its procfs classification");
2081        self.require_current_timer_slack_target(guest, binding)
2082            .await?;
2083        let value = guest.thread_state().timer_slack_ns;
2084        let bytes = guest
2085            .thread_state()
2086            .with_detfd(fd, |detfd| {
2087                detfd.take_procfs_timer_slack_at(value, offset as usize, maximum)
2088            })?
2089            .expect("timer-slack procfs state disappeared");
2090        Ok(copy_timer_slack_output(&mut guest.memory(), buffer, &bytes)? as i64)
2091    }
2092
2093    /// A vectored read of a procfs file Detcore renders: one read of its
2094    /// snapshot, as Linux's `read_iter` serves the whole vector at once,
2095    /// scattered over the `count` vectors at `address`, at `offset` or at
2096    /// (and advancing) the shared cursor. The order is `vfs_readv`'s: the
2097    /// descriptor's access mode, then the vectors' import (`EFAULT` for any
2098    /// destination outside the user address range, even at end of file), an
2099    /// empty vector (0), the range (`rw_verify_area`), and the flags.
2100    async fn readv_rendered_procfs<G: Guest<Self>>(
2101        &self,
2102        guest: &mut G,
2103        fd: RawFd,
2104        address: usize,
2105        count: usize,
2106        offset: Option<i64>,
2107        flags: i32,
2108    ) -> Result<i64, Error> {
2109        let status = guest
2110            .thread_state()
2111            .with_detfd(fd, |detfd| detfd.status_flags())?;
2112        if !can_read(status) {
2113            return Err(Errno::EBADF.into());
2114        }
2115        let iovecs = crate::iovecs::import_read_iovecs(&guest.memory(), address, count, || {
2116            crate::iovecs::UserAddressLimit::from_query(guest.user_address_limit())
2117        })?;
2118        let maximum = iovecs.iter().map(|iovec| iovec.len).sum::<usize>();
2119        if maximum == 0 {
2120            return Ok(0);
2121        }
2122        if let Some(offset) = offset
2123            && offset.checked_add(maximum as i64).is_none()
2124        {
2125            return Err(Errno::EINVAL.into());
2126        }
2127        let read_iter = guest
2128            .thread_state()
2129            .with_detfd(fd, |detfd| detfd.procfs_has_read_iter())?;
2130        validate_procfs_vector_flags(flags, read_iter)?;
2131        // A file the kernel opened takes its snapshot at its first read.
2132        if guest
2133            .thread_state()
2134            .with_detfd(fd, |detfd| detfd.procfs_needs_snapshot())?
2135        {
2136            self.initialize_procfs_snapshot(guest, syscalls::Read::new().with_fd(fd))
2137                .await?;
2138        } else if let Some(offset) = offset
2139            && guest.thread_state().with_detfd(fd, |detfd| {
2140                detfd
2141                    .procfs_position()
2142                    .is_some_and(|(position, _)| position as i64 != offset)
2143            })?
2144        {
2145            // A read at a position the buffered snapshot does not start at
2146            // runs a per-process file's `show` again (`traverse`).
2147            self.require_rendered_task(guest, fd).await?;
2148        }
2149        let start = match offset {
2150            Some(offset) => offset as usize,
2151            None => {
2152                self.adopt_rendered_procfs_position(guest, fd).await?;
2153                guest
2154                    .thread_state()
2155                    .with_detfd(fd, |detfd| detfd.procfs_position())?
2156                    .map_or(0, |(offset, _)| offset)
2157            }
2158        };
2159        let (bytes, faults_on_a_short_copy) = guest.thread_state().with_detfd(fd, |detfd| {
2160            (
2161                detfd.take_procfs_at(start, maximum).unwrap_or_default(),
2162                detfd.procfs_faults_on_a_short_copy(),
2163            )
2164        })?;
2165        // Like `copy_to_iter`, stop at the first byte that cannot be written,
2166        // leaving later vectors untouched.
2167        let mut copied = 0;
2168        for iovec in iovecs {
2169            if copied == bytes.len() {
2170                break;
2171            }
2172            if iovec.len == 0 {
2173                continue;
2174            }
2175            let end = (copied + iovec.len).min(bytes.len());
2176            let written = match copy_procfs_output(
2177                &mut guest.memory(),
2178                AddrMut::from_raw(iovec.base),
2179                &bytes[copied..end],
2180            ) {
2181                Ok(written) => written,
2182                Err(Error::Errno(Errno::EFAULT)) => 0,
2183                Err(error) => return Err(error),
2184            };
2185            copied += written;
2186            if copied < end {
2187                break;
2188            }
2189        }
2190        if copied < bytes.len() && (faults_on_a_short_copy || copied == 0) {
2191            return Err(Errno::EFAULT.into());
2192        }
2193        if offset.is_none() {
2194            guest
2195                .thread_state()
2196                .with_detfd(fd, |detfd| detfd.commit_procfs_read(start, copied))?;
2197            self.sync_rendered_procfs_position(guest, fd).await?;
2198        }
2199        Ok(copied as i64)
2200    }
2201
2202    async fn readv_timer_slack<G: Guest<Self>>(
2203        &self,
2204        guest: &mut G,
2205        fd: RawFd,
2206        iovecs: Vec<TimerSlackIovec>,
2207        offset: Option<i64>,
2208        flags: i32,
2209    ) -> Result<i64, Error> {
2210        self.require_timer_slack_access(guest, fd, false)?;
2211        let maximum = iovecs.iter().map(|iovec| iovec.len).sum::<usize>();
2212        if maximum == 0 {
2213            return Ok(0);
2214        }
2215        if flags & !libc::RWF_HIPRI != 0 {
2216            return Err(Errno::EOPNOTSUPP.into());
2217        }
2218        let binding = self
2219            .timer_slack_binding(guest, fd)?
2220            .expect("timer-slack readv lost its procfs classification");
2221        self.require_current_timer_slack_target(guest, binding)
2222            .await?;
2223        let value = guest.thread_state().timer_slack_ns;
2224        let mut positioned_offset = offset.map(|offset| offset as usize);
2225        let mut total = 0_usize;
2226        for iovec in iovecs {
2227            if iovec.len == 0 {
2228                continue;
2229            }
2230            let sequential_preview = if positioned_offset.is_none() {
2231                guest.thread_state().with_detfd(fd, |detfd| {
2232                    detfd.preview_procfs_timer_slack(value, iovec.len)
2233                })?
2234            } else {
2235                None
2236            };
2237            let bytes = match (&sequential_preview, positioned_offset) {
2238                (Some(preview), None) => preview.bytes.clone(),
2239                (None, Some(offset)) => guest
2240                    .thread_state()
2241                    .with_detfd(fd, |detfd| {
2242                        detfd.take_procfs_timer_slack_at(value, offset, iovec.len)
2243                    })?
2244                    .expect("timer-slack procfs state disappeared"),
2245                _ => unreachable!("timer-slack read mode changed while reading"),
2246            };
2247            if bytes.is_empty() {
2248                break;
2249            }
2250            let copied = match copy_timer_slack_output(
2251                &mut guest.memory(),
2252                AddrMut::from_raw(iovec.base),
2253                &bytes,
2254            ) {
2255                Ok(copied) => copied,
2256                Err(_) if total > 0 => return Ok(total as i64),
2257                Err(error) => return Err(error.into()),
2258            };
2259            if let Some(preview) = &sequential_preview {
2260                guest.thread_state().with_detfd(fd, |detfd| {
2261                    detfd.commit_procfs_timer_slack_read(preview, copied);
2262                })?;
2263            }
2264            total += copied;
2265            if let Some(offset) = positioned_offset.as_mut() {
2266                *offset += copied;
2267            }
2268            if copied != bytes.len() {
2269                return Ok(total as i64);
2270            }
2271            if bytes.len() != iovec.len {
2272                break;
2273            }
2274        }
2275        Ok(total as i64)
2276    }
2277
2278    async fn write_timer_slack<G: Guest<Self>>(
2279        &self,
2280        guest: &mut G,
2281        fd: RawFd,
2282        buffer: Option<Addr<'_, u8>>,
2283        count: usize,
2284    ) -> Result<i64, Error> {
2285        self.require_timer_slack_access(guest, fd, true)?;
2286        let requested = self.read_timer_slack_input(guest, buffer, count)?;
2287        let binding = self
2288            .timer_slack_binding(guest, fd)?
2289            .expect("timer-slack write lost its procfs classification");
2290        self.require_current_timer_slack_target(guest, binding)
2291            .await?;
2292        let state = guest.thread_state_mut();
2293        state.timer_slack_ns = if requested == 0 {
2294            state.default_timer_slack_ns
2295        } else {
2296            requested
2297        };
2298        i64::try_from(count).map_err(|_| Errno::EINVAL.into())
2299    }
2300
2301    async fn writev_timer_slack<G: Guest<Self>>(
2302        &self,
2303        guest: &mut G,
2304        fd: RawFd,
2305        iovecs: Vec<TimerSlackIovec>,
2306        flags: i32,
2307    ) -> Result<i64, Error> {
2308        self.require_timer_slack_access(guest, fd, true)?;
2309        if iovecs.iter().all(|iovec| iovec.len == 0) {
2310            return Ok(0);
2311        }
2312        if flags & !libc::RWF_HIPRI != 0 {
2313            return Err(Errno::EOPNOTSUPP.into());
2314        }
2315        // Procfs supplies only `.write`, so Linux's writev fallback invokes it
2316        // once per nonempty iovec. Preserve its partial-success behavior and
2317        // let the last successful segment determine the current slack.
2318        let mut total = 0_i64;
2319        for iovec in iovecs {
2320            if iovec.len == 0 {
2321                continue;
2322            }
2323            let buffer = Addr::from_raw(iovec.base).ok_or(Errno::EFAULT);
2324            let requested = match buffer
2325                .and_then(|buffer| self.read_timer_slack_input(guest, Some(buffer), iovec.len))
2326            {
2327                Ok(requested) => requested,
2328                Err(_error) if total > 0 => return Ok(total),
2329                Err(error) => return Err(error.into()),
2330            };
2331            let binding = self
2332                .timer_slack_binding(guest, fd)?
2333                .expect("timer-slack writev lost its procfs classification");
2334            if let Err(error) = self
2335                .require_current_timer_slack_target(guest, binding)
2336                .await
2337            {
2338                return if total > 0 { Ok(total) } else { Err(error) };
2339            }
2340            let state = guest.thread_state_mut();
2341            state.timer_slack_ns = if requested == 0 {
2342                state.default_timer_slack_ns
2343            } else {
2344                requested
2345            };
2346            total = total
2347                .checked_add(i64::try_from(iovec.len).map_err(|_| Errno::EINVAL)?)
2348                .ok_or(Errno::EINVAL)?;
2349        }
2350        Ok(total)
2351    }
2352    /// Set the kernel's O_NONBLOCK on `fd`'s open file description, keeping its
2353    /// other status flags. The caller records the change with
2354    /// `maybe_set_nonblocking_fd`; the guest-visible flags are unchanged.
2355    async fn inject_physical_nonblocking<G: Guest<Self>>(
2356        &self,
2357        guest: &mut G,
2358        fd: RawFd,
2359    ) -> Result<(), Errno> {
2360        let flags = guest
2361            .inject(syscalls::Fcntl::new().with_fd(fd).with_cmd(F_GETFL))
2362            .await?;
2363        guest
2364            .inject(
2365                syscalls::Fcntl::new()
2366                    .with_fd(fd)
2367                    .with_cmd(F_SETFL(flags as i32 | OFlag::O_NONBLOCK.bits())),
2368            )
2369            .await?;
2370        Ok(())
2371    }
2372
2373    /// A blocking `openat` of the FIFO `fifo` (found by the tracer at `path`),
2374    /// which a guest made in this run (`crate::fifo_peer::is_guest_made`), for
2375    /// reading or for writing. On Linux it waits in the kernel until the other
2376    /// end is open; injected as is, it would wait while it holds the scheduler
2377    /// turn, and a guest that opens the other end could never run
2378    /// (<https://github.com/rrnewton/hermit/issues/2203>).
2379    ///
2380    /// First the open is tried nonblocking. Any error other than "no reader
2381    /// yet" (`ENXIO`, for a writer) is the open's own, returned at once, as
2382    /// Linux returns it before waiting (`EEXIST`, `ENOENT`, `EACCES`, ...), and
2383    /// nothing else is opened. A writer that finds a reader completes then, as
2384    /// does a reader whose writer a guest holds or waits to open. Otherwise the
2385    /// open waits in polling turns ([`crate::fifo_peer::PendingOpen`]), and the
2386    /// guest's try is closed in the same turn, so no sibling sees a descriptor
2387    /// for it. It waits until a guest holds the other end, is waiting to open
2388    /// it, or has opened it since, then opens nonblocking and is made
2389    /// blocking, as the guest asked.
2390    ///
2391    /// A signal ends the wait as Linux's: `ERESTARTSYS`, which the kernel turns
2392    /// into `EINTR` or a restart by the guest's disposition.
2393    ///
2394    /// When the scheduler answers that nothing else can run
2395    /// (`ResumeStatus::NothingElseCanRun`), no guest can open the other end,
2396    /// so the open is made as the guest asked, waiting in the kernel while it
2397    /// holds the turn, as without the poll: only a host could complete it.
2398    ///
2399    /// Either way the open completes on the FIFO it waited on
2400    /// ([`Self::open_fifo_waited_on`]).
2401    async fn open_fifo_once_a_guest_holds_its_peer<G: Guest<Self>>(
2402        &self,
2403        guest: &mut G,
2404        call: syscalls::Openat,
2405        fifo: (u64, u64),
2406        path: &std::ffi::OsStr,
2407    ) -> Result<i64, Error> {
2408        let reading = call.flags().bits() & libc::O_ACCMODE == libc::O_RDONLY;
2409        let peer = if reading {
2410            FifoPeer::Writer
2411        } else {
2412            FifoPeer::Reader
2413        };
2414        let nonblocking = call.with_flags(call.flags() | OFlag::O_NONBLOCK);
2415        let opens_before = crate::fifo_peer::guest_opens(fifo);
2416        // Guest state only, which changes in guest turns: the answer at each
2417        // polling turn is deterministic.
2418        let guest_peer_ready = || {
2419            crate::fifo_peer::guest_holds_peer_of(fifo, peer)
2420                || crate::fifo_peer::pending_opens(fifo).of(peer) > 0
2421                || crate::fifo_peer::guest_opens(fifo).of(peer) > opens_before.of(peer)
2422        };
2423        // A nonblocking FIFO open never waits, so an injection a signal
2424        // interrupts did not run, and is made again; the signal is delivered
2425        // as the guest resumes.
2426        let pending = match guest.inject_with_retry(nonblocking).await {
2427            // A writer found a reader: Linux's open completes at once.
2428            Ok(fd) if !reading => return Ok(self.make_blocking(guest, fd as RawFd).await?),
2429            Ok(fd) if guest_peer_ready() => {
2430                crate::fifo_peer::stand_in_for_waiting_writers(fifo, path);
2431                return Ok(self.make_blocking(guest, fd as RawFd).await?);
2432            }
2433            Ok(fd) => {
2434                // The tracer's reader opens before the guest's try closes, so
2435                // the FIFO keeps a reader throughout.
2436                let pending = crate::fifo_peer::PendingOpen::begin(fifo, path, call.flags().bits());
2437                guest
2438                    .inject_with_retry(syscalls::Close::new().with_fd(fd as RawFd))
2439                    .await?;
2440                pending
2441            }
2442            Err(Errno::ENXIO) if !reading => {
2443                crate::fifo_peer::PendingOpen::begin(fifo, path, call.flags().bits())
2444            }
2445            Err(errno) => return Err(errno.into()),
2446        };
2447        info!("[detcore] the FIFO open polls for a guest peer");
2448        // A waiting open is an end on Linux: it readies the opens waiting for
2449        // this end (`--pipe-wake-latency`).
2450        let in_effect = self.cfg.pipe_wake_latency_in_effect().is_some();
2451        let channel = crate::pipe_wake::ChannelId::Fifo(if in_effect {
2452            crate::fifo_peer::fifo_channel(fifo)
2453        } else {
2454            0
2455        });
2456        let (readies, waits_for) = if reading {
2457            (
2458                crate::pipe_wake::Wants::PeerReader,
2459                crate::pipe_wake::Wants::PeerWriter,
2460            )
2461        } else {
2462            (
2463                crate::pipe_wake::Wants::PeerWriter,
2464                crate::pipe_wake::Wants::PeerReader,
2465            )
2466        };
2467        self.note_pipe_readied(guest, channel, readies).await;
2468
2469        let mut resources = Resources::new(guest.thread_state().dettid);
2470        resources.insert(ResourceID::InternalIOPolling, Permission::W);
2471        resources.fyi(call.name());
2472        resources.polls_guest_state_only = true;
2473        resources.waits_until_nothing_else_can_run = true;
2474        if in_effect {
2475            resources.polls_channel = Some(Box::new((channel, waits_for)));
2476        }
2477        // As a polled pipe read: a signal another task sends ends the wait.
2478        resources.set_signal_interrupt_errno(Errno::ERESTARTSYS);
2479        resources.signal_state_task = crate::syscalls::helpers::guest_signal_state_task(guest);
2480        // The peer is checked again after every answer, the last one included:
2481        // a guest may have opened (and closed) the other end in the turns
2482        // before it.
2483        loop {
2484            let status = resource_request(guest, resources.clone()).await;
2485            resources.poll_attempt += 1;
2486            if guest_peer_ready() {
2487                break;
2488            }
2489            match status {
2490                ResumeStatus::Signaled(_) => return Err(Errno::ERESTARTSYS.into()),
2491                ResumeStatus::NothingElseCanRun => {
2492                    info!(
2493                        "[detcore] nothing else can run; the FIFO open waits in the kernel, as without the poll"
2494                    );
2495                    let waited_on = pending.guest_path();
2496                    return self
2497                        .open_fifo_waited_on(
2498                            guest,
2499                            call,
2500                            fifo,
2501                            waited_on.as_deref(),
2502                            call.flags(),
2503                            false,
2504                        )
2505                        .await;
2506                }
2507                _ => {}
2508            }
2509        }
2510        let waited_on = pending.guest_path();
2511        let open = async |guest: &mut G| {
2512            self.open_fifo_waited_on(
2513                guest,
2514                call,
2515                fifo,
2516                waited_on.as_deref(),
2517                nonblocking.flags(),
2518                true,
2519            )
2520            .await
2521        };
2522        let mut opened = open(guest).await;
2523        if matches!(opened, Err(Error::Errno(Errno::ENXIO))) {
2524            // A writer whose only reader has come and gone opens as Linux's did
2525            // when the reader opened; the tracer stands in for that reader while
2526            // the guest opens, so the guest's writes then fail with `EPIPE`, as
2527            // on Linux.
2528            let _stand_in = pending.open_in_tracer(libc::O_RDONLY);
2529            opened = open(guest).await;
2530        }
2531        if reading && opened.is_ok() {
2532            pending.stand_in_for_waiting_writers();
2533        }
2534        drop(pending);
2535        Ok(self.make_blocking(guest, opened? as RawFd).await?)
2536    }
2537
2538    /// Open, in the guest, the FIFO `fifo` a blocking open waited on, with
2539    /// the guest's `flags`, whatever its name is now: through the tracer's
2540    /// descriptor for it, `waited_on` ([`Self::open_waited_on_fifo`]).
2541    ///
2542    /// The kernel lets a guest into the tracer's descriptors only if it holds
2543    /// `CAP_SYS_PTRACE` or every capability the tracer has
2544    /// (`proc_fd_access_allowed`), and only if the tracer's `/proc` is under
2545    /// its root; and a root whose `/proc` is not the tracer's may name another
2546    /// file at that path, so what it opened is checked to be the FIFO, and
2547    /// closed if not. A guest that cannot reach the descriptor (`EACCES`,
2548    /// `ENOENT`, another file), or whose open waited without one (`waited_on`
2549    /// is `None`),
2550    /// opens the FIFO by the name it gave, as its first try did, provided the
2551    /// name still reaches that FIFO: looked up first, so that no other file
2552    /// is opened, and checked again once open. If the name reaches another
2553    /// file or none, the open cannot complete on its FIFO, as Linux's does,
2554    /// and is refused (Claude re-check of
2555    /// <https://github.com/rrnewton/hermit/pull/4329> at revision 4,
2556    /// MEDIUM-A).
2557    ///
2558    /// Either way this is a new open, so the FIFO's mode is checked again
2559    /// against the guest's credentials when it completes: a FIFO whose mode
2560    /// the guest may no longer open (a `chmod` during the wait) gives
2561    /// `EACCES`, where Linux checked only at the start.
2562    ///
2563    /// `retry`: an open that cannot wait (nonblocking), which a signal stops
2564    /// only before it runs. `ENXIO` (a writer whose reader is gone) and
2565    /// `ERESTARTSYS` (a signal ended a blocking open) are the caller's.
2566    async fn open_fifo_waited_on<G: Guest<Self>>(
2567        &self,
2568        guest: &mut G,
2569        call: syscalls::Openat,
2570        fifo: (u64, u64),
2571        waited_on: Option<&str>,
2572        flags: OFlag,
2573        retry: bool,
2574    ) -> Result<i64, Error> {
2575        let is_the_fifo = |stat: &libc::stat| (stat.st_dev, stat.st_ino) == fifo;
2576        let unreachable = match waited_on {
2577            Some(waited_on) => {
2578                match Self::open_waited_on_fifo(guest, fifo, waited_on, flags, retry).await {
2579                    Err(errno) if !matches!(errno, Errno::ENXIO | Errno::ERESTARTSYS) => {
2580                        Some(errno)
2581                    }
2582                    // A root whose `/proc` is not the tracer's can name
2583                    // another file at that path (Claude re-check at
2584                    // revision 5, LOW-C).
2585                    Ok(fd)
2586                        if !self
2587                            .inject_fstat(guest, fd as RawFd)
2588                            .await
2589                            .is_ok_and(|stat| is_the_fifo(&stat)) =>
2590                    {
2591                        info!(
2592                            "[detcore] the tracer's descriptor path reached another file in the guest's root"
2593                        );
2594                        guest
2595                            .inject_with_retry(syscalls::Close::new().with_fd(fd as RawFd))
2596                            .await?;
2597                        Some(Errno::ENOENT)
2598                    }
2599                    opened => return Ok(opened?),
2600                }
2601            }
2602            None => None,
2603        };
2604        if let Some(errno) = unreachable {
2605            info!(
2606                "[detcore] the guest cannot reach the tracer's descriptor for the FIFO ({}); it opens the FIFO by its name",
2607                errno
2608            );
2609        }
2610        let path = call.path().ok_or(Errno::EFAULT)?;
2611        let lookup = if flags.contains(OFlag::O_NOFOLLOW) {
2612            AtFlags::AT_SYMLINK_NOFOLLOW
2613        } else {
2614            AtFlags::empty()
2615        };
2616        if Self::inject_statat(guest, call.dirfd(), path, [Some(path), None], lookup)
2617            .await
2618            .is_ok_and(|stat| is_the_fifo(&stat))
2619        {
2620            // The name was checked by the first try, and reaches the FIFO:
2621            // nothing is created.
2622            let open = call.with_flags(flags - (OFlag::O_CREAT | OFlag::O_EXCL));
2623            let fd = if retry {
2624                guest.inject_with_retry(open).await?
2625            } else {
2626                guest.inject(open).await?
2627            };
2628            if self
2629                .inject_fstat(guest, fd as RawFd)
2630                .await
2631                .is_ok_and(|stat| is_the_fifo(&stat))
2632            {
2633                return Ok(fd);
2634            }
2635            guest
2636                .inject_with_retry(syscalls::Close::new().with_fd(fd as RawFd))
2637                .await?;
2638        }
2639        error!(
2640            "[detcore] a blocking open of a FIFO a guest made waited for its peer, and cannot complete \
2641             on that FIFO: the guest cannot reach the tracer's descriptor for it, and its name no \
2642             longer reaches it (a guest without CAP_SYS_PTRACE, or without the tracer's /proc, whose \
2643             FIFO was renamed or unlinked during the wait); refused \
2644             (https://github.com/rrnewton/hermit/pull/4329)"
2645        );
2646        self.refuse_unserviceable_operation(
2647            guest,
2648            Sysno::openat,
2649            unreachable.unwrap_or(Errno::ENOENT),
2650        )
2651        .await
2652    }
2653
2654    /// Open, in the guest, the FIFO a waiting open waited on, at `waited_on`
2655    /// (`fifo_peer::PendingOpen::guest_path`), with the guest's `flags`: the
2656    /// checks of its name were made by the first try, so `O_CREAT`, `O_EXCL`
2657    /// and `O_NOFOLLOW` go (the path is the tracer's descriptor link).
2658    /// `retry`: an open that cannot wait (nonblocking), which a signal stops
2659    /// only before it runs.
2660    ///
2661    /// The path is staged in a private page mapped for this open only, not
2662    /// in the guest stack scratch, so that an open needs no spare stack
2663    /// below the guest's stack pointer, which Linux's does not (Codex
2664    /// re-check of <https://github.com/rrnewton/hermit/pull/4329> at revision
2665    /// 4, P2). The page is unmapped before the guest resumes, so the guest's
2666    /// memory keeps no tracer descriptor number (Claude's LOW-B there). An
2667    /// error mapping or writing the page is returned, and the caller opens
2668    /// the FIFO by its name instead.
2669    ///
2670    /// A task killed while the open waits in the kernel drops this call
2671    /// before its unmap; the page is then unmapped by the next task of the
2672    /// same address space to reach Detcore
2673    /// ([`crate::fifo_peer::StagedPage`], [`Self::unmap_orphaned_staging_pages`]).
2674    ///
2675    /// What the path names is looked up first, and must be the FIFO `fifo`:
2676    /// a root whose `/proc` is not the tracer's can name another file there,
2677    /// which is not opened (`ESTALE`; Claude re-check at revision 6, LOW-H).
2678    async fn open_waited_on_fifo<G: Guest<Self>>(
2679        guest: &mut G,
2680        fifo: (u64, u64),
2681        waited_on: &str,
2682        flags: OFlag,
2683        retry: bool,
2684    ) -> Result<i64, Errno> {
2685        let mut path_buffer = [0_u8; crate::fifo_peer::STAGED_PAGE_LENGTH];
2686        let bytes = waited_on.as_bytes();
2687        if bytes.len() >= path_buffer.len() {
2688            return Err(Errno::ENAMETOOLONG);
2689        }
2690        path_buffer[..bytes.len()].copy_from_slice(bytes);
2691        // The page's owner exists before its `mmap` runs, at an address
2692        // chosen first: a task killed during the `mmap` leaves its address
2693        // space's next task an address to check.
2694        let address =
2695            crate::fifo_peer::free_staging_address(guest.tid().as_raw()).ok_or(Errno::ENOMEM)?;
2696        let page = AddrMut::<u8>::from_raw(address).ok_or(Errno::ENOMEM)?;
2697        let staged =
2698            crate::fifo_peer::StagedPage::new(guest.thread_state().mm_id, address, path_buffer);
2699        match guest
2700            .inject_with_retry(Syscall::Mmap(
2701                syscalls::Mmap::new()
2702                    .with_addr(Some(page.cast::<libc::c_void>().into()))
2703                    .with_len(path_buffer.len())
2704                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
2705                    .with_flags(
2706                        MapFlags::MAP_PRIVATE
2707                            | MapFlags::MAP_ANONYMOUS
2708                            | MapFlags::MAP_FIXED_NOREPLACE,
2709                    )
2710                    .with_fd(-1)
2711                    .with_offset(0),
2712            ))
2713            .await
2714        {
2715            Ok(mapped) if mapped as usize == address => {
2716                crate::race_probe::delay(crate::race_probe::FIFO_STAGING_MAPPED).await;
2717            }
2718            // Nothing was mapped at the address (`EEXIST`: something is
2719            // there): this route is not taken.
2720            Err(errno) => {
2721                staged.unmapped();
2722                return Err(errno);
2723            }
2724            // A kernel without MAP_FIXED_NOREPLACE takes the address as a
2725            // hint and maps elsewhere.
2726            Ok(mapped) => {
2727                staged.unmapped();
2728                if let Some(elsewhere) = Addr::<libc::c_void>::from_raw(mapped as usize) {
2729                    let _ = guest
2730                        .inject_with_retry(Syscall::Munmap(
2731                            syscalls::Munmap::new()
2732                                .with_addr(Some(elsewhere))
2733                                .with_len(path_buffer.len()),
2734                        ))
2735                        .await;
2736                }
2737                return Err(Errno::ENOMEM);
2738            }
2739        }
2740        let path = PathPtr::from_ptr(page.as_raw() as *const libc::c_char)
2741            .expect("a mapped page is not null");
2742        let opened = match guest.memory().write_exact(page, &path_buffer) {
2743            Ok(()) => match Self::inject_statat(
2744                guest,
2745                libc::AT_FDCWD,
2746                path,
2747                [Some(path), None],
2748                AtFlags::empty(),
2749            )
2750            .await
2751            {
2752                Ok(stat) if (stat.st_dev, stat.st_ino) == fifo => {
2753                    let open = syscalls::Openat::new()
2754                        .with_dirfd(libc::AT_FDCWD)
2755                        .with_path(Some(path))
2756                        .with_flags(flags - (OFlag::O_CREAT | OFlag::O_EXCL | OFlag::O_NOFOLLOW))
2757                        .with_mode(None);
2758                    if retry {
2759                        guest.inject_with_retry(open).await
2760                    } else {
2761                        guest.inject(open).await
2762                    }
2763                }
2764                Ok(_) => {
2765                    info!(
2766                        "[detcore] the tracer's descriptor path names another file in the guest's root"
2767                    );
2768                    Err(Errno::ESTALE)
2769                }
2770                Err(errno) => Err(errno),
2771            },
2772            Err(error) => Err(error),
2773        };
2774        match guest
2775            .inject_with_retry(Syscall::Munmap(
2776                syscalls::Munmap::new()
2777                    .with_addr(Some(page.cast::<libc::c_void>().into()))
2778                    .with_len(path_buffer.len()),
2779            ))
2780            .await
2781        {
2782            Ok(_) => staged.unmapped(),
2783            // An unmap that did not run (stopped before it ran) is left, with
2784            // the guard, to this address space's next task.
2785            Err(errno) => info!(
2786                "[detcore] the transient FIFO path page is left to the next task: {}",
2787                errno
2788            ),
2789        }
2790        opened
2791    }
2792
2793    /// Unmap the pages a completing FIFO open staged in this task's address
2794    /// space and could not unmap, because its task went away while the open
2795    /// waited ([`crate::fifo_peer::StagedPage`]). Called as a task reaches
2796    /// Detcore, before it runs guest code again; costs one load while no page
2797    /// is left.
2798    pub(crate) async fn unmap_orphaned_staging_pages<G: Guest<Self>>(guest: &mut G) {
2799        // Each taken page is owned by its guard until it is unmapped: one this
2800        // task does not get to (its unmap does not run, or the task exits
2801        // while it waits) is left again.
2802        for page in crate::fifo_peer::take_orphaned_pages(guest.thread_state().mm_id) {
2803            // Only a page that still holds what was staged: the guest may have
2804            // unmapped it and mapped something else there.
2805            let mut contents = [0_u8; crate::fifo_peer::STAGED_PAGE_LENGTH];
2806            let Some(address) = Addr::<u8>::from_raw(page.address()) else {
2807                page.unmapped();
2808                continue;
2809            };
2810            let readable = guest.memory().read_exact(address, &mut contents).is_ok();
2811            // A task killed during the `mmap` may have left the page before
2812            // anything was written to it: a page of zeros is the staging page
2813            // only where it is a lone one-page anonymous mapping.
2814            if !readable
2815                || (contents != *page.contents()
2816                    && !(contents == [0; crate::fifo_peer::STAGED_PAGE_LENGTH]
2817                        && crate::fifo_peer::is_lone_staging_mapping(
2818                            guest.tid().as_raw(),
2819                            page.address(),
2820                        )))
2821            {
2822                info!("[detcore] a FIFO open's path page that a killed task left is gone");
2823                page.unmapped();
2824                continue;
2825            }
2826            info!("[detcore] unmapping a FIFO open's path page that a killed task left");
2827            crate::race_probe::delay(crate::race_probe::FIFO_STAGING_RECLAIM).await;
2828            let unmapped = guest
2829                .inject_with_retry(Syscall::Munmap(
2830                    syscalls::Munmap::new()
2831                        .with_addr(Addr::<libc::c_void>::from_raw(page.address()))
2832                        .with_len(contents.len()),
2833                ))
2834                .await;
2835            match unmapped {
2836                Ok(_) => page.unmapped(),
2837                Err(Errno::EINVAL) => {
2838                    warn!(
2839                        "[detcore] could not unmap the transient FIFO path page: {}",
2840                        Errno::EINVAL
2841                    );
2842                    page.unmapped();
2843                }
2844                // Stopped before it ran: the guard leaves it to the next task
2845                // (Claude re-check at revision 6, MEDIUM-G).
2846                Err(errno) => info!(
2847                    "[detcore] the transient FIFO path page is left to the next task: {}",
2848                    errno
2849                ),
2850            }
2851        }
2852    }
2853
2854    /// Clear `O_NONBLOCK` on the guest's FIFO descriptor `fd`, which was opened
2855    /// nonblocking in place of a blocking open, and return it.
2856    async fn make_blocking<G: Guest<Self>>(&self, guest: &mut G, fd: RawFd) -> Result<i64, Errno> {
2857        let flags = guest
2858            .inject_with_retry(syscalls::Fcntl::new().with_fd(fd).with_cmd(F_GETFL))
2859            .await?;
2860        guest
2861            .inject_with_retry(
2862                syscalls::Fcntl::new()
2863                    .with_fd(fd)
2864                    .with_cmd(F_SETFL(flags as i32 & !OFlag::O_NONBLOCK.bits())),
2865            )
2866            .await?;
2867        Ok(fd as i64)
2868    }
2869
2870    /// Before a logically blocking read (`peer` is `Writer`) or write
2871    /// (`Reader`) on a FIFO that `handle_openat` marked: if a guest holds the
2872    /// other end (`crate::fifo_peer`), shrink the FIFO's capacity to the one
2873    /// `handle_pipe2` pins a pipe to (never growing one the guest shrank), make
2874    /// it physically nonblocking, and treat it from then on as a
2875    /// scheduler-managed pipe. The call then polls in
2876    /// turns instead of blocking in the kernel while it holds the turn, where
2877    /// the guest at the other end could never run
2878    /// (<https://github.com/rrnewton/hermit/issues/4200>). A FIFO whose other
2879    /// ends are all on the host is left blocking, as before.
2880    ///
2881    /// The open file description may be shared with another process that
2882    /// already made this change: the kernel then reports it nonblocking while
2883    /// this process still sees it blocking, and this process follows. On
2884    /// ptrace a forked child shares the parent's model (`fork_for` clones the
2885    /// `Arc`), so it sees the change at once; this branch is for a backend
2886    /// whose fork copies the model into the child's address space (DBT), and
2887    /// the ptrace tests do not reach it.
2888    /// Shrink a FIFO that is about to be polled as a pipe to the capacity
2889    /// `handle_pipe2` pins a pipe to, if it is larger, so that its partial
2890    /// writes do not depend on the host's pipe defaults. A capacity the guest
2891    /// set smaller is kept, as Linux keeps it. The kernel refuses (`EBUSY`)
2892    /// while more is buffered than the new capacity holds; the FIFO is then
2893    /// polled at its current capacity, which only that buffered amount
2894    /// decides.
2895    async fn shrink_fifo_capacity<G: Guest<Self>>(&self, guest: &mut G, fd: RawFd) {
2896        let Ok(capacity) = guest
2897            .inject(syscalls::Fcntl::new().with_fd(fd).with_cmd(F_GETPIPE_SZ))
2898            .await
2899        else {
2900            return;
2901        };
2902        if capacity > i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES)
2903            && let Err(errno) = guest
2904                .inject(
2905                    syscalls::Fcntl::new()
2906                        .with_fd(fd)
2907                        .with_cmd(F_SETPIPE_SZ(DETERMINISTIC_PIPE_CAPACITY_BYTES)),
2908                )
2909                .await
2910        {
2911            info!(
2912                "[detcore] FIFO fd {} keeps its {}-byte capacity: shrinking it failed with {}",
2913                fd, capacity, errno
2914            );
2915        }
2916    }
2917
2918    async fn fifo_polls_if_a_guest_holds_its_peer<G: Guest<Self>>(
2919        &self,
2920        guest: &mut G,
2921        fd: RawFd,
2922        peer: FifoPeer,
2923    ) {
2924        let Ok((awaiting, logically_nonblocking)) = guest.thread_state().with_detfd(fd, |detfd| {
2925            (detfd.fifo_awaiting_guest_peer(), detfd.is_nonblocking())
2926        }) else {
2927            return;
2928        };
2929        if !awaiting || logically_nonblocking {
2930            return;
2931        }
2932        // The calling thread's own table: it may not be its leader's (a thread
2933        // cloned without CLONE_FILES), and `fd` is changed in this one.
2934        let tid = guest.tid().as_raw();
2935        let joins = match crate::fifo_peer::kernel_nonblocking(tid, fd) {
2936            Some(true) => true,
2937            Some(false) => {
2938                crate::fifo_peer::guest_holds_peer(tid, fd, peer) && {
2939                    self.shrink_fifo_capacity(guest, fd).await;
2940                    self.inject_physical_nonblocking(guest, fd).await.is_ok()
2941                }
2942            }
2943            None => false,
2944        };
2945        if joins {
2946            info!(
2947                "[detcore] fd {} is a FIFO with a guest at its other end; polling it as a pipe",
2948                fd
2949            );
2950            let _ = guest
2951                .thread_state()
2952                .with_detfd(fd, |detfd| detfd.fifo_joins_internal_polling());
2953        }
2954    }
2955
2956    /// Inject an extra fstat to retrieve file metadata.
2957    ///
2958    /// The kernel needs a writable `struct stat` in the guest. It is staged
2959    /// first in the guest stack scratch, which on the ptrace backend lies just
2960    /// below the red zone under the guest's stack pointer and costs nothing
2961    /// when the stack has room. That memory is not guaranteed to be writable:
2962    /// the guest may run with its stack pointer just above a guard page (a
2963    /// thread, fiber or alternate signal stack), or within a few hundred bytes
2964    /// of the lowest page of the main-thread stack, which a tracer's write does
2965    /// not grow. The fault then belongs to Detcore's bookkeeping, not to the
2966    /// guest, so the same fstat is repeated with its buffer in a transient
2967    /// private page that is unmapped before the guest resumes
2968    /// (<https://github.com/rrnewton/hermit/issues/3328>).
2969    pub(crate) async fn inject_fstat<G: Guest<Self>>(
2970        &self,
2971        guest: &mut G,
2972        raw_fd: RawFd,
2973    ) -> Result<libc::stat, Errno> {
2974        info!(
2975            "Injecting additional fstat to retrieve file metadata on fd {}.",
2976            raw_fd
2977        );
2978        let fstat = move |statptr: StatPtr<'_>| {
2979            Syscall::Fstat(
2980                syscalls::Fstat::new()
2981                    .with_fd(raw_fd)
2982                    .with_stat(Some(statptr)),
2983            )
2984        };
2985        let copied = match Self::inject_stat_on_stack(guest, fstat).await {
2986            Err(Errno::EFAULT) => {
2987                info!(
2988                    "Guest stack scratch cannot hold the fstat buffer for fd {}; \
2989                     using a transient page instead.",
2990                    raw_fd
2991                );
2992                Self::inject_stat_in_transient_page(guest, fstat).await?
2993            }
2994            result => result?,
2995        };
2996        trace!("extra fstat returned inode {}", copied.st_ino);
2997        Ok(copied)
2998    }
2999
3000    /// `fstatat(dirfd, path, AT_SYMLINK_NOFOLLOW)` for a path the guest named
3001    /// in a call that has not run yet and must still read `inputs`, its paths
3002    /// ([`Detcore::inject_statat`]).
3003    async fn inject_lstatat<G: Guest<Self>>(
3004        guest: &mut G,
3005        dirfd: RawFd,
3006        path: syscalls::PathPtr<'_>,
3007        inputs: [Option<syscalls::PathPtr<'_>>; 2],
3008    ) -> Result<libc::stat, Errno> {
3009        Self::inject_statat(guest, dirfd, path, inputs, AtFlags::AT_SYMLINK_NOFOLLOW).await
3010    }
3011
3012    /// `fstatat(dirfd, path, flags)` for a path the guest named in a call that
3013    /// has not run yet and must still read `inputs`, its paths.
3014    ///
3015    /// The buffer is staged as the utimensat target lookup stages its own: in
3016    /// the guest stack scratch, below the red zone, where a raw syscall may
3017    /// keep its own path, so only when it overlaps none of `inputs`, and with
3018    /// the bytes under it saved and put back after the commit and after the
3019    /// lookup, so that the call reads its inputs unchanged (claude review of
3020    /// <https://github.com/rrnewton/hermit/pull/3849>, P3-2). Otherwise it is
3021    /// a transient private page, unmapped before the guest resumes.
3022    pub(crate) async fn inject_statat<G: Guest<Self>>(
3023        guest: &mut G,
3024        dirfd: RawFd,
3025        path: syscalls::PathPtr<'_>,
3026        inputs: [Option<syscalls::PathPtr<'_>>; 2],
3027        flags: AtFlags,
3028    ) -> Result<libc::stat, Errno> {
3029        // A `/proc` path naming a process or thread by the guest's number
3030        // is looked up by the kernel's (DBT), as the guest's own call is
3031        // (`procfs_numbers`).
3032        let probe = Syscall::Newfstatat(
3033            syscalls::Newfstatat::new()
3034                .with_dirfd(dirfd)
3035                .with_path(Some(path))
3036                .with_flags(flags),
3037        );
3038        let Some(translated) = Self::procfs_translated_call(guest, &probe).await? else {
3039            return Self::inject_statat_as_spelled(guest, dirfd, path, inputs, flags).await;
3040        };
3041        // The one path is staged at the start of the transient page.
3042        let respelled = PathPtr::from_ptr(translated.page.as_raw() as *const libc::c_char);
3043        let looked_up = match respelled {
3044            Some(respelled) => {
3045                Self::inject_statat_as_spelled(
3046                    guest,
3047                    dirfd,
3048                    respelled,
3049                    [Some(respelled), None],
3050                    flags,
3051                )
3052                .await
3053            }
3054            None => Err(Errno::ENOMEM),
3055        };
3056        Self::finish_translated_call(guest, translated).await;
3057        looked_up
3058    }
3059
3060    /// [`Self::inject_statat`] of `path` as it is spelled.
3061    async fn inject_statat_as_spelled<G: Guest<Self>>(
3062        guest: &mut G,
3063        dirfd: RawFd,
3064        path: syscalls::PathPtr<'_>,
3065        inputs: [Option<syscalls::PathPtr<'_>>; 2],
3066        flags: AtFlags,
3067    ) -> Result<libc::stat, Errno> {
3068        let lstatat = move |statptr: StatPtr<'_>| {
3069            Syscall::Newfstatat(
3070                syscalls::Newfstatat::new()
3071                    .with_dirfd(dirfd)
3072                    .with_path(Some(path))
3073                    .with_stat(Some(statptr))
3074                    .with_flags(flags),
3075            )
3076        };
3077        // The scratch starts 128 bytes below the stack pointer, at addresses
3078        // computed by subtraction.
3079        let scratch = 128 + std::mem::size_of::<libc::stat>();
3080        if usize::try_from(guest.regs().await.rsp).map_or(true, |rsp| rsp <= scratch) {
3081            return Self::inject_stat_in_transient_page(guest, lstatat).await;
3082        }
3083        let mut stack = guest.stack().await;
3084        let statptr: StatPtr = StatPtr(stack.reserve());
3085        let mut saved = [0u8; std::mem::size_of::<libc::stat>()];
3086        let staged_on_stack = !inputs
3087            .iter()
3088            .any(|input| path_overlaps_buffer(&guest.memory(), *input, statptr))
3089            && guest
3090                .memory()
3091                .read_exact(statptr.0.cast(), &mut saved)
3092                .is_ok();
3093        if !staged_on_stack {
3094            drop(stack);
3095            return Self::inject_stat_in_transient_page(guest, lstatat).await;
3096        }
3097        let guard = match stack.commit() {
3098            Ok(guard) => guard,
3099            Err(_) => {
3100                restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
3101                return Self::inject_stat_in_transient_page(guest, lstatat).await;
3102            }
3103        };
3104        restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
3105        let looked_up = Self::inject_stat_into(guest, lstatat(statptr), statptr).await;
3106        restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
3107        drop(guard);
3108        looked_up
3109    }
3110
3111    /// The fast path of [`Self::inject_fstat`]: the buffer lives in the guest
3112    /// stack scratch. Returns `EFAULT` when that scratch is not writable.
3113    async fn inject_stat_on_stack<G: Guest<Self>>(
3114        guest: &mut G,
3115        stat_call: impl Fn(StatPtr<'_>) -> Syscall,
3116    ) -> Result<libc::stat, Errno> {
3117        let mut stack = guest.stack().await;
3118        let statptr: StatPtr = StatPtr(stack.reserve());
3119        // Keep the guard until the buffer is no longer used. Backends whose
3120        // scratch is a Tool-owned arena (DBT, SaBRe) free it when the guard
3121        // drops, so dropping it before the injected fstat would let the kernel
3122        // write into freed memory.
3123        let _stack_guard = stack.commit()?;
3124        let copied = Self::inject_stat_into(guest, stat_call(statptr), statptr).await?;
3125        // clear stack memory used for fstat allocation
3126        guest
3127            .memory()
3128            .write_exact(statptr.0.cast(), &[0; std::mem::size_of::<libc::stat>()])?;
3129        Ok(copied)
3130    }
3131
3132    /// The fallback of [`Self::inject_fstat`] and [`Self::inject_lstatat`]:
3133    /// the buffer lives in a private
3134    /// anonymous page mapped for this call only. The guest never learns its
3135    /// address, and it is unmapped before the guest resumes, so the guest's
3136    /// address space is the same as before the call.
3137    async fn inject_stat_in_transient_page<G: Guest<Self>>(
3138        guest: &mut G,
3139        stat_call: impl Fn(StatPtr<'_>) -> Syscall,
3140    ) -> Result<libc::stat, Errno> {
3141        let len = std::mem::size_of::<libc::stat>();
3142        let mapped = guest
3143            .inject_with_retry(Syscall::Mmap(
3144                syscalls::Mmap::new()
3145                    .with_addr(None)
3146                    .with_len(len)
3147                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
3148                    .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
3149                    .with_fd(-1)
3150                    .with_offset(0),
3151            ))
3152            .await?;
3153        let page = usize::try_from(mapped)
3154            .ok()
3155            .and_then(AddrMut::<libc::stat>::from_raw)
3156            .unwrap_or_else(|| panic!("transient fstat page mmap returned {mapped}"));
3157        let copied = Self::inject_stat_into(guest, stat_call(StatPtr(page)), StatPtr(page)).await;
3158        if let Err(errno) = guest
3159            .inject_with_retry(Syscall::Munmap(
3160                syscalls::Munmap::new()
3161                    .with_addr(Some(page.cast::<libc::c_void>().into()))
3162                    .with_len(len),
3163            ))
3164            .await
3165        {
3166            // Not expected: the page was mapped by this call and its address
3167            // never reached the guest. The metadata is still valid, so a
3168            // leftover page is no reason to fail the guest's syscall.
3169            warn!(
3170                "[detcore] could not unmap the transient stat page: {}",
3171                errno
3172            );
3173        }
3174        copied
3175    }
3176
3177    /// Inject `stat_call`, which writes a `struct stat` at `statptr`, and read
3178    /// back what the kernel wrote.
3179    async fn inject_stat_into<G: Guest<Self>>(
3180        guest: &mut G,
3181        stat_call: Syscall,
3182        statptr: StatPtr<'_>,
3183    ) -> Result<libc::stat, Errno> {
3184        // NOTE: Must retry the injection here. This could get interrupted and
3185        // we don't want to rerun the entire syscall handler twice.
3186        guest.inject_with_retry(stat_call).await?;
3187        statptr.read(&guest.memory())
3188    }
3189
3190    // helper function to track a new file descriptor.
3191    pub(crate) async fn add_fd<G: Guest<Self>>(
3192        &self,
3193        guest: &mut G,
3194        fd: RawFd,
3195        flags: OFlag,
3196        ty: FdType,
3197    ) -> Result<(), Errno> {
3198        self.add_fd_with_stat(guest, fd, flags, ty).await.map(drop)
3199    }
3200
3201    /// Track `fd`, which the guest already holds from a call that has
3202    /// succeeded whatever happens here (a clone's pidfd), as [`Self::add_fd`]
3203    /// does, except that a failure leaves the descriptor open and untracked
3204    /// rather than closing it: the guest keeps what Linux gave it.
3205    pub(crate) async fn track_held_fd<G: Guest<Self>>(
3206        &self,
3207        guest: &mut G,
3208        fd: RawFd,
3209        flags: OFlag,
3210        ty: FdType,
3211    ) -> Result<(), Errno> {
3212        let host_stat = if guest.config().virtualize_metadata {
3213            Some(self.inject_fstat(guest, fd).await?)
3214        } else {
3215            None
3216        };
3217        guest
3218            .thread_state()
3219            .add_fd(fd, flags, ty, host_stat.map(Into::into))
3220    }
3221
3222    /// [`Self::add_fd`], also returning the host `fstat` it took of `fd`, which
3223    /// it takes only when metadata is virtualized.
3224    async fn add_fd_with_stat<G: Guest<Self>>(
3225        &self,
3226        guest: &mut G,
3227        fd: RawFd,
3228        flags: OFlag,
3229        ty: FdType,
3230    ) -> Result<Option<libc::stat>, Errno> {
3231        let host_stat = if guest.config().virtualize_metadata {
3232            match self.inject_fstat(guest, fd).await {
3233                Ok(stat) => Some(stat),
3234                Err(errno) => {
3235                    // `fd` is already open in the guest, but Detcore cannot
3236                    // model it: with metadata virtualization on, a descriptor
3237                    // without its stat is an invariant violation. The caller
3238                    // reports this error as the syscall's result, so close
3239                    // the descriptor rather than leave an untracked one open
3240                    // behind that error. Not retried on EINTR: Linux releases
3241                    // the descriptor even then, and a retry could close a
3242                    // reused number.
3243                    if let Err(close_errno) = guest.inject(syscalls::Close::new().with_fd(fd)).await
3244                    {
3245                        warn!(
3246                            "[detcore] could not close fd {} after failing to record its \
3247                             metadata ({}): {}",
3248                            fd, errno, close_errno
3249                        );
3250                    }
3251                    return Err(errno);
3252                }
3253            }
3254        } else {
3255            None
3256        };
3257        guest
3258            .thread_state()
3259            .add_fd(fd, flags, ty, host_stat.map(Into::into))?;
3260        Ok(host_stat)
3261    }
3262
3263    pub(crate) async fn release_port_for_open_file<G: Guest<Self>>(
3264        &self,
3265        guest: &mut G,
3266        open_file_id: OpenFileId,
3267    ) -> Option<u16> {
3268        let response = send_and_update_time(guest, GlobalRequest::ReleasePort(open_file_id)).await;
3269        match response.1 {
3270            GlobalResponse::ReleasePort(port) => port,
3271            other => panic!("unexpected release-port response: {other:?}"),
3272        }
3273    }
3274
3275    pub(crate) async fn restore_port_for_open_file<G: Guest<Self>>(
3276        &self,
3277        guest: &mut G,
3278        open_file_id: OpenFileId,
3279        port: u16,
3280    ) {
3281        let response =
3282            send_and_update_time(guest, GlobalRequest::AddUsedPort(port, open_file_id)).await;
3283        match response.1 {
3284            GlobalResponse::AddUsedPort => {}
3285            other => panic!("unexpected restore-port response: {other:?}"),
3286        }
3287    }
3288
3289    /// [`Self::observed_path`], with a `/proc` directory that `dirfd` names
3290    /// taken as the directory it is open on, as Linux looks a relative name up
3291    /// below that directory whoever holds the descriptor: a `/proc/self` or
3292    /// `/proc/thread-self` directory is the task the selector reached when it
3293    /// was opened (`DetFd::procfs_reached`), and a descriptor Detcore has no
3294    /// record of (one received over `SCM_RIGHTS`, which a fresh discovery
3295    /// leaves without one) is named as the kernel names the directory it is
3296    /// open on, where that is on procfs ([`Self::unrecorded_procfs_directory`]).
3297    /// Detcore's own decisions about procfs names (the files it renders, the
3298    /// `--proc` level, the links it canonicalizes) use this spelling. A name
3299    /// below the recorded directory of a task that is gone is ESRCH, and one
3300    /// below a selector link opened as the link itself ENOTDIR, as Linux
3301    /// answers them.
3302    pub(crate) async fn procfs_spelling_at<G: Guest<Self>>(
3303        &self,
3304        guest: &mut G,
3305        dirfd: i32,
3306        path: &Path,
3307    ) -> Result<PathBuf, Error> {
3308        if !path.is_absolute() && !path.as_os_str().is_empty() && dirfd != libc::AT_FDCWD {
3309            let (reached, link_itself) = guest
3310                .thread_state()
3311                .with_detfd(dirfd, |detfd| {
3312                    (detfd.procfs_reached(), detfd.procfs_link_itself())
3313                })
3314                .unwrap_or((None, false));
3315            // A selector link itself is no directory.
3316            if link_itself {
3317                return Err(Errno::ENOTDIR.into());
3318            }
3319            if let Some((reached, incarnation)) = reached {
3320                // The directory's task, while it lives: Linux checks the
3321                // task a pid directory was opened on at every lookup below it
3322                // (`proc_pid_permission`), and a task that is gone, whose
3323                // number another task may hold by now, fails every name with
3324                // ESRCH (measured on Linux 7.1: `cgroup`, `status`, `exe` and
3325                // a name no task has alike).
3326                // TODO-HUMAN-REVIEW(#4213): Review the stale task-directory
3327                // decision: a directory bound to a task identity at its open
3328                // answers ESRCH for every name once that identity no longer
3329                // holds its numbers (`ProcfsTaskAnswer::still_names`).
3330                if let Some(incarnation) = incarnation
3331                    && let Some(task) = procfs_reached_task(&reached)
3332                {
3333                    let answer = crate::tool_global::procfs_task(guest, task).await;
3334                    if !answer.still_names(incarnation) {
3335                        return Err(Errno::ESRCH.into());
3336                    }
3337                }
3338                return Ok(reached.join(path));
3339            }
3340            if let Some(directory) = self.unrecorded_procfs_directory(guest, dirfd).await {
3341                return Ok(directory.join(path));
3342            }
3343        }
3344        Self::observed_path(guest, dirfd, path)
3345    }
3346
3347    /// The procfs directory descriptor `dirfd` is open on, where Detcore has
3348    /// no record of the descriptor, as the guest names it: the kernel's name
3349    /// for it (its `/proc/thread-self/fd/N` link, one injected `readlinkat`),
3350    /// if that is `/proc` or a path below it, with the kernel's numbers of
3351    /// the task it names taken back to the guest's where the two differ (DBT,
3352    /// `Self::translates_procfs_numbers`). Every backend's kernel beneath
3353    /// answers that link for the calling thread's own table: the host kernel
3354    /// on ptrace and DBT, KVM's provider (`guest_fd_path`), which has one
3355    /// table per process. `None` for a descriptor Detcore has a record of, any
3356    /// other object, a task number no task of the guest's holds, and where
3357    /// Detcore does not render procfs files (record and replay, after
3358    /// `chroot`).
3359    ///
3360    /// In every threading mode, `--no-sequentialize-threads` included. For a
3361    /// file Detcore renders, the link is the only observation of the
3362    /// descriptor, read once inside the guest's own call, and the answer comes
3363    /// from that name alone: another thread that replaces the descriptor
3364    /// concurrently is ordered before that read (the call looks below the new
3365    /// directory) or after it (below the old one), and Linux takes the
3366    /// descriptor at one point inside the call too (`path_init`), so each
3367    /// answer is one Linux can give. Without this a relaxed run's received
3368    /// `/proc` would leave its mount tables to the backend, which keeps no copy
3369    /// (KVM).
3370    ///
3371    /// Where the name only guides a call the kernel then resolves through the
3372    /// same descriptor, there are two observations, and without
3373    /// sequentialized threads another thread can replace the descriptor
3374    /// between them. A directory opened below it gets procfs provenance only
3375    /// if the descriptor the kernel returned holds a directory below `/proc`
3376    /// (`handle_openat`). The `--proc` level's refusal of an omitted name below
3377    /// it is best-effort there for `stat`, `access` and `readlink`, which have
3378    /// no check after the kernel's lookup: a residual of the relaxed mode,
3379    /// narrower than before, when no level applied below a received descriptor
3380    /// in that mode at all.
3381    pub(crate) async fn unrecorded_procfs_directory<G: Guest<Self>>(
3382        &self,
3383        guest: &mut G,
3384        dirfd: i32,
3385    ) -> Option<PathBuf> {
3386        if dirfd < 0 || !self.renders_procfs(guest) {
3387            return None;
3388        }
3389        let recorded = guest
3390            .thread_state()
3391            .with_detfd(dirfd, |detfd| detfd.path())
3392            .unwrap_or(None);
3393        if recorded.is_some() {
3394            return None;
3395        }
3396        const LINK_CAPACITY: usize = 40;
3397        const TARGET_CAPACITY: usize = 256;
3398        let mut stack = guest.stack().await;
3399        let link = stack.push(rendered_procfs::c_string::<LINK_CAPACITY>(
3400            format!("/proc/thread-self/fd/{dirfd}").as_bytes(),
3401        ));
3402        let target = stack.reserve::<[u8; TARGET_CAPACITY]>();
3403        let stack_guard = stack.commit().ok()?;
3404        let length = guest
3405            .inject(
3406                syscalls::Readlinkat::new()
3407                    .with_dirfd(libc::AT_FDCWD)
3408                    .with_path(PathPtr::from_ptr(link.as_raw() as *const libc::c_char))
3409                    .with_buf(Some(target.cast::<libc::c_char>()))
3410                    .with_buf_len(TARGET_CAPACITY),
3411            )
3412            .await;
3413        let bytes = match length.map(|length| length as usize) {
3414            Ok(length) if length < TARGET_CAPACITY => {
3415                let mut bytes = vec![0; length];
3416                guest
3417                    .memory()
3418                    .read_exact(target.cast::<u8>(), &mut bytes)
3419                    .ok()
3420                    .map(|()| bytes)
3421            }
3422            _ => None,
3423        };
3424        drop(stack_guard);
3425        let text = String::from_utf8(bytes?).ok()?;
3426        let (mut names, positions) = procfs_directory_task_positions(&text)?;
3427        if Self::translates_procfs_numbers(guest) && !positions.is_empty() {
3428            let kernel = positions
3429                .iter()
3430                .map(|position| names[*position].parse::<i32>().ok())
3431                .collect::<Option<Vec<_>>>()?;
3432            let translated = crate::tool_global::procfs_ids(guest, false, kernel).await;
3433            for (position, number) in positions.iter().zip(translated) {
3434                names[*position] = number?.to_string();
3435            }
3436        }
3437        let mut directory = PathBuf::from("/proc");
3438        directory.extend(names);
3439        Some(directory)
3440    }
3441
3442    /// `path`, as a guest syscall named it relative to `dirfd`, made
3443    /// absolute in the guest's view. A relative spelling is not the object:
3444    /// absolute paths are already bound, a dirfd supplies its own prefix, and
3445    /// AT_FDCWD-relative spellings are resolved through the guest's root and
3446    /// cwd, so the result does not depend on Replayer's placeholder
3447    /// descriptor. A spelling that cannot be resolved is kept as given.
3448    fn observed_path<G: Guest<Self>>(guest: &G, dirfd: i32, path: &Path) -> Result<PathBuf, Error> {
3449        Ok(if path.is_absolute() {
3450            path.to_path_buf()
3451        } else if dirfd == libc::AT_FDCWD {
3452            resolved_at_fdcwd_path(guest.pid().as_raw(), path).unwrap_or_else(|| path.to_path_buf())
3453        } else {
3454            // A descriptor Detcore has no state for (one received over
3455            // `SCM_RIGHTS` under a backend whose tool does not discover
3456            // descriptors as they are used) keeps the relative spelling, which
3457            // the kernel looks up from it; the kernel, not this lookup,
3458            // decides whether the descriptor is open. Before, such an `openat`
3459            // failed with EBADF though the descriptor was open.
3460            guest
3461                .thread_state()
3462                .with_detfd(dirfd, |detfd| detfd.path())
3463                .unwrap_or(None)
3464                .map_or_else(|| path.to_path_buf(), |directory| directory.join(path))
3465        })
3466    }
3467
3468    /// For `hermit run --verify`, report each path `call` may rebind in the
3469    /// guest's file namespace: both names of a rename, the new name of a link
3470    /// or symlink, an unlinked name, and a node, directory or file it makes
3471    /// or removes (see `detcore_model::host_input::HostMutationRecord`). A
3472    /// host file whose path the guest rebinds may have been replaced by the
3473    /// guest itself. Called before the call runs, whatever its outcome.
3474    pub(crate) async fn record_host_namespace_change<G: Guest<Self>>(
3475        &self,
3476        guest: &mut G,
3477        call: &Syscall,
3478    ) {
3479        let at = libc::AT_FDCWD;
3480        let changed: Vec<(i32, Option<syscalls::PathPtr>)> = match call {
3481            #[cfg(not(target_arch = "aarch64"))]
3482            Syscall::Rename(c) => vec![(at, c.oldpath()), (at, c.newpath())],
3483            Syscall::Renameat(c) => vec![(c.olddirfd(), c.oldpath()), (c.newdirfd(), c.newpath())],
3484            Syscall::Renameat2(c) => {
3485                vec![(c.olddirfd(), c.oldpath()), (c.newdirfd(), c.newpath())]
3486            }
3487            #[cfg(not(target_arch = "aarch64"))]
3488            Syscall::Link(c) => vec![(at, c.newpath())],
3489            Syscall::Linkat(c) => vec![(c.newdirfd(), c.newpath())],
3490            #[cfg(not(target_arch = "aarch64"))]
3491            Syscall::Unlink(c) => vec![(at, c.path())],
3492            Syscall::Unlinkat(c) => vec![(c.dirfd(), c.path())],
3493            #[cfg(not(target_arch = "aarch64"))]
3494            Syscall::Symlink(c) => vec![(at, c.linkpath())],
3495            Syscall::Symlinkat(c) => vec![(c.newdirfd(), c.linkpath())],
3496            #[cfg(not(target_arch = "aarch64"))]
3497            Syscall::Mknod(c) => vec![(at, c.path())],
3498            Syscall::Mknodat(c) => vec![(c.dirfd(), c.path())],
3499            #[cfg(not(target_arch = "aarch64"))]
3500            Syscall::Mkdir(c) => vec![(at, c.path())],
3501            Syscall::Mkdirat(c) => vec![(c.dirfd(), c.path())],
3502            #[cfg(not(target_arch = "aarch64"))]
3503            Syscall::Rmdir(c) => vec![(at, c.path())],
3504            #[cfg(not(target_arch = "aarch64"))]
3505            Syscall::Creat(c) => vec![(at, c.path())],
3506            _ => return,
3507        };
3508        for (dirfd, path) in changed {
3509            let observed = match path.map(|path| path.read(&guest.memory())) {
3510                Some(Ok(path)) => {
3511                    let path: PathBuf = path;
3512                    Self::observed_path(guest, dirfd, &path).ok()
3513                }
3514                _ => None,
3515            };
3516            crate::tool_global::record_host_mutation(guest, rebound_path(observed)).await;
3517        }
3518    }
3519
3520    /// The host inodes whose last name `call` would remove: the name an
3521    /// `unlink`, `unlinkat` or `rmdir` removes, or the target a `rename`,
3522    /// `renameat` or `renameat2` replaces (not with `RENAME_EXCHANGE`), when
3523    /// it is a directory or a file with one link (see [`retires_on_removal`]).
3524    /// Each name is stat'ed with an injected `fstatat(AT_SYMLINK_NOFOLLOW)`
3525    /// before the call runs; a name that does not resolve removes nothing.
3526    /// Pass the result to [`Self::retire_removed_inodes`] if the call
3527    /// succeeds. Only with virtualized metadata, the only mode that numbers
3528    /// inodes.
3529    ///
3530    /// Nothing is retired without sequentialized threads. Only then do the
3531    /// lookups, the call and the retirement run in one turn; otherwise another
3532    /// thread can link, unlink or rename the file in between, and a file that
3533    /// keeps a name could be retired and renumbered (codex review of
3534    /// <https://github.com/rrnewton/hermit/pull/3849>, P2). Without them inode
3535    /// numbers behave as before retirement existed.
3536    pub(crate) async fn last_names_removed_by<G: Guest<Self>>(
3537        &self,
3538        guest: &mut G,
3539        call: &Syscall,
3540    ) -> Vec<RawInode> {
3541        if !guest.config().virtualize_metadata || !guest.config().sequentialize_threads {
3542            return Vec::new();
3543        }
3544        let at = libc::AT_FDCWD;
3545        // The name removed, and for a rename the source, which replaces
3546        // nothing when it is the target's own file (`rename(a, a)`, or two
3547        // links of one file).
3548        let (removed, source) = match call {
3549            #[cfg(not(target_arch = "aarch64"))]
3550            Syscall::Unlink(c) => ((at, c.path()), None),
3551            Syscall::Unlinkat(c) => ((c.dirfd(), c.path()), None),
3552            #[cfg(not(target_arch = "aarch64"))]
3553            Syscall::Rmdir(c) => ((at, c.path()), None),
3554            #[cfg(not(target_arch = "aarch64"))]
3555            Syscall::Rename(c) => ((at, c.newpath()), Some((at, c.oldpath()))),
3556            Syscall::Renameat(c) => (
3557                (c.newdirfd(), c.newpath()),
3558                Some((c.olddirfd(), c.oldpath())),
3559            ),
3560            Syscall::Renameat2(c) if c.flags() & libc::RENAME_EXCHANGE == 0 => (
3561                (c.newdirfd(), c.newpath()),
3562                Some((c.olddirfd(), c.oldpath())),
3563            ),
3564            _ => return Vec::new(),
3565        };
3566        // Every path the call reads, which the lookups must leave unchanged.
3567        let inputs = [removed.1, source.and_then(|source| source.1)];
3568        let Some(path) = removed.1 else {
3569            return Vec::new();
3570        };
3571        let Ok(stat) = Self::inject_lstatat(guest, removed.0, path, inputs).await else {
3572            return Vec::new();
3573        };
3574        let inode = RawInode::new(stat.st_dev, stat.st_ino);
3575        if let Some((dirfd, Some(path))) = source
3576            && Self::inject_lstatat(guest, dirfd, path, inputs)
3577                .await
3578                .is_ok_and(|source| RawInode::new(source.st_dev, source.st_ino) == inode)
3579        {
3580            return Vec::new();
3581        }
3582        if retires_on_removal(&stat) {
3583            vec![inode]
3584        } else {
3585            Vec::new()
3586        }
3587    }
3588
3589    /// The guest-made FIFO (`crate::fifo_peer::is_guest_made`) whose last
3590    /// name `call` removes: the name an `unlink` or `unlinkat` removes, or the
3591    /// target a `rename`, `renameat` or `renameat2` replaces (not with
3592    /// `RENAME_EXCHANGE`), when it is that FIFO's only link
3593    /// ([`retires_on_removal`]) and not the rename's own source (another link
3594    /// of the same FIFO, or `rename(a, a)`). Stat'ed before the call runs; pass
3595    /// the result to `crate::fifo_peer::forget_guest_made` if the call
3596    /// succeeds, so that a FIFO that later reuses the number is not taken for
3597    /// a guest's, while a FIFO that keeps a name stays a guest's. Only where
3598    /// the set is shared by every guest (`fifo_peer::guest_descriptors_are_visible`).
3599    pub(crate) async fn guest_made_fifos_removed_by<G: Guest<Self>>(
3600        &self,
3601        guest: &mut G,
3602        call: &Syscall,
3603    ) -> Vec<(u64, u64)> {
3604        if !crate::fifo_peer::any_guest_made()
3605            || !crate::fifo_peer::guest_descriptors_are_visible(
3606                &self.cfg.backend,
3607                guest.thread_state().physical_tid,
3608            )
3609        {
3610            return Vec::new();
3611        }
3612        let at = libc::AT_FDCWD;
3613        let (removed, source) = match call {
3614            #[cfg(not(target_arch = "aarch64"))]
3615            Syscall::Unlink(c) => ((at, c.path()), None),
3616            Syscall::Unlinkat(c) => ((c.dirfd(), c.path()), None),
3617            #[cfg(not(target_arch = "aarch64"))]
3618            Syscall::Rename(c) => ((at, c.newpath()), Some((at, c.oldpath()))),
3619            Syscall::Renameat(c) => (
3620                (c.newdirfd(), c.newpath()),
3621                Some((c.olddirfd(), c.oldpath())),
3622            ),
3623            Syscall::Renameat2(c) if c.flags() & libc::RENAME_EXCHANGE == 0 => (
3624                (c.newdirfd(), c.newpath()),
3625                Some((c.olddirfd(), c.oldpath())),
3626            ),
3627            _ => return Vec::new(),
3628        };
3629        let inputs = [removed.1, source.and_then(|source| source.1)];
3630        let Some(path) = removed.1 else {
3631            return Vec::new();
3632        };
3633        let Ok(stat) = Self::inject_lstatat(guest, removed.0, path, inputs).await else {
3634            return Vec::new();
3635        };
3636        let fifo = (stat.st_dev, stat.st_ino);
3637        if stat.st_mode & libc::S_IFMT != libc::S_IFIFO
3638            || !crate::fifo_peer::is_guest_made(fifo)
3639            || !retires_on_removal(&stat)
3640        {
3641            return Vec::new();
3642        }
3643        if let Some((dirfd, Some(path))) = source
3644            && Self::inject_lstatat(guest, dirfd, path, inputs)
3645                .await
3646                .is_ok_and(|source| (source.st_dev, source.st_ino) == fifo)
3647        {
3648            return Vec::new();
3649        }
3650        vec![fifo]
3651    }
3652
3653    /// After a successful `mknod` or `mknodat` that made a FIFO, record it as
3654    /// a guest's (`crate::fifo_peer::note_guest_made`), stat'ed at the name the
3655    /// call made, in the same turn. Only where a blocking open of it can wait
3656    /// in polling turns (sequentialized `hermit run` under a separate tracer
3657    /// whose guest thread IDs are host tasks).
3658    pub(crate) async fn note_guest_made_fifo<G: Guest<Self>>(&self, guest: &mut G, call: &Syscall) {
3659        // Only where one set serves every guest, as `fifo_at` requires.
3660        if !self.cfg.use_nonblocking_sockets()
3661            || self.cfg.recordreplay_modes
3662            || !crate::fifo_peer::guest_descriptors_are_visible(
3663                &self.cfg.backend,
3664                guest.thread_state().physical_tid,
3665            )
3666        {
3667            return;
3668        }
3669        let (dirfd, path, mode) = match call {
3670            #[cfg(not(target_arch = "aarch64"))]
3671            Syscall::Mknod(c) => (libc::AT_FDCWD, c.path(), c.mode().bits()),
3672            Syscall::Mknodat(c) => (c.dirfd(), c.path(), c.mode().bits()),
3673            _ => return,
3674        };
3675        if mode & libc::S_IFMT != libc::S_IFIFO {
3676            return;
3677        }
3678        let Some(path) = path else {
3679            return;
3680        };
3681        if let Ok(stat) = Self::inject_lstatat(guest, dirfd, path, [Some(path), None]).await
3682            && stat.st_mode & libc::S_IFMT == libc::S_IFIFO
3683        {
3684            crate::fifo_peer::note_guest_made((stat.st_dev, stat.st_ino));
3685        }
3686    }
3687
3688    /// Retire the mappings of `inodes`, whose last names a successful call
3689    /// removed (see [`Self::last_names_removed_by`] and `InodePool::retire`).
3690    pub(crate) async fn retire_removed_inodes<G: Guest<Self>>(
3691        &self,
3692        guest: &mut G,
3693        inodes: Vec<RawInode>,
3694    ) {
3695        for inode in inodes {
3696            retire_inode(guest, inode).await;
3697        }
3698    }
3699
3700    /// For `hermit run --verify` on a backend whose guest holds code that
3701    /// makes untraced syscalls (`Config::untraced_code_range`): report `/`
3702    /// when `call` may change the memory holding it (see
3703    /// [`may_change_untraced_code`]). Intact, that code faults right after
3704    /// its syscall, and the fault is reported (`handle_signal_event`); a
3705    /// guest that rewrote or replaced it could use it without faulting, so
3706    /// Detcore could not establish what the guest changed, and `/`, the
3707    /// ancestor of every path, keeps a host input change from being named
3708    /// in that run. Called before the call runs, whatever its outcome.
3709    pub(crate) async fn record_untraced_code_change<G: Guest<Self>>(
3710        &self,
3711        guest: &mut G,
3712        call: &Syscall,
3713    ) {
3714        let Some(range) = guest.config().untraced_code_range else {
3715            return;
3716        };
3717        let (number, args) = call.into_parts();
3718        if may_change_untraced_code(number, &args, range, default_huge_page_size()) {
3719            crate::tool_global::record_host_mutation(guest, String::from("/")).await;
3720        }
3721    }
3722
3723    /// Open an `exe` link, by `call`, as the image Detcore recorded for the
3724    /// process it reaches, `exe` (`Detcore::launched_exe`): Linux opens the
3725    /// image the link names, which the kernel's link here does not (it names
3726    /// the launcher). The kernel first opens the guest's spelling itself as
3727    /// a path (`O_PATH`), so whether the link is there and every error stay
3728    /// its own (an exited thread-group leader's `ENOENT`). Without a record,
3729    /// or for an image no longer at its path, which only the kernel's link to
3730    /// the image could still open, the run is refused by name.
3731    async fn open_launched_exe<G: Guest<Self>>(
3732        &self,
3733        guest: &mut G,
3734        call: syscalls::Openat,
3735        exe: Option<&crate::exec_record::ExecRecord>,
3736    ) -> Result<i64, Error> {
3737        // The longest path Linux opens, NUL included.
3738        const CAPACITY: usize = libc::PATH_MAX as usize;
3739        let probe = syscalls::Openat::new()
3740            .with_dirfd(call.dirfd())
3741            .with_path(call.path())
3742            .with_flags(OFlag::O_PATH | OFlag::O_CLOEXEC);
3743        let probed = guest.inject(probe).await?;
3744        let _ = guest
3745            .inject(syscalls::Close::new().with_fd(probed as RawFd))
3746            .await;
3747        let present = exe.filter(|exe| {
3748            self.guest_root(guest)
3749                .is_some_and(|root| exe.is_present(&root))
3750        });
3751        let Some(exe) = present else {
3752            return self.refuse_launched_exe(guest, Sysno::openat, exe).await;
3753        };
3754        let bytes = std::os::unix::ffi::OsStrExt::as_bytes(exe.exe.as_os_str());
3755        let mut stack = guest.stack().await;
3756        if bytes.len() >= CAPACITY || stack.capacity() < CAPACITY {
3757            drop(stack);
3758            let reason = format!(
3759                "unsupported: opening the /proc/<pid>/exe link of {:?}, whose path does not \
3760                 fit the guest stack, where the kernel's link names the launcher",
3761                exe.exe
3762            );
3763            return self
3764                .refuse_launched_exe_because(guest, Sysno::openat, reason)
3765                .await;
3766        }
3767        let mut buffer = [0_u8; CAPACITY];
3768        buffer[..bytes.len()].copy_from_slice(bytes);
3769        let address = stack.push(buffer).cast::<libc::c_char>();
3770        let stack_guard = stack.commit()?;
3771        let call = call.with_path(PathPtr::from_ptr(address.as_raw() as *const libc::c_char));
3772        let result = self.record_or_replay(guest, Syscall::Openat(call)).await;
3773        drop(stack_guard);
3774        Ok(result?)
3775    }
3776
3777    /// Whether guest descriptor `fd` is open on the launcher a launched run
3778    /// declared (`Detcore::launched_exe`), read where the tool shares the
3779    /// guest's descriptor table, as a launcher's tool does. Asked only for an
3780    /// open of a possible `exe` link
3781    /// (`crate::syscalls::namespace::exe_link_candidate`).
3782    fn opened_the_launcher(&self, fd: RawFd) -> bool {
3783        use std::os::unix::fs::MetadataExt;
3784        let Some(launcher) = self.declared_launcher() else {
3785            return false;
3786        };
3787        if !self.cfg.backend.tool_shares_guest_descriptor_table {
3788            return false;
3789        }
3790        let mut opened: libc::stat = unsafe { std::mem::zeroed() };
3791        // Runtime-owned read-only inspection of the shared descriptor table.
3792        let result = unsafe {
3793            crate::util::raw_syscall(
3794                libc::SYS_fstat,
3795                [fd as u64, (&raw mut opened) as u64, 0, 0, 0, 0],
3796            )
3797        };
3798        result == 0
3799            && std::fs::metadata(launcher)
3800                .is_ok_and(|meta| (meta.dev(), meta.ino()) == (opened.st_dev, opened.st_ino))
3801    }
3802
3803    /// Openat system call.
3804    pub async fn handle_openat<G: Guest<Self>>(
3805        &self,
3806        guest: &mut G,
3807        call: syscalls::Openat,
3808    ) -> Result<i64, Error> {
3809        let path = call.path().ok_or(Errno::EFAULT)?;
3810        let path: PathBuf = path.read(&guest.memory())?;
3811        // A relative spelling is not the object. `chdir("/sys/module/kvm");
3812        // open("refcnt")` and an absolute open name the SAME kernel object, so
3813        // classifying the unresolved lexical pathname lets one spelling bypass
3814        // normalization and expose the host value. Absolute paths are already
3815        // bound; a dirfd supplies its own prefix; AT_FDCWD-relative spellings
3816        // are resolved through the guest's root and cwd before the open so the
3817        // result does not depend on Replayer's placeholder descriptor.
3818        let observed_path = Self::observed_path(guest, call.dirfd(), &path)?;
3819        // The spelling Detcore's own lookups of the files it renders see.
3820        let procfs_spelling = self.procfs_spelling_at(guest, call.dirfd(), &path).await?;
3821        crate::race_probe::delay(crate::race_probe::PROCFS_SPELLING_RESOLVED).await;
3822        if guest.config().record_host_inputs && call.flags().contains(OFlag::O_CREAT) {
3823            // It may create the file it opens. Reported before the open runs,
3824            // as `record_host_namespace_change` reports the other changes.
3825            crate::tool_global::record_host_mutation(
3826                guest,
3827                rebound_path(Some(observed_path.clone())),
3828            )
3829            .await;
3830        }
3831
3832        let resource = ResourceID::Path(path.clone());
3833        // Ask for permission to resolve this path into a file:
3834        let request = guest.thread_state().mk_request(resource, Permission::R);
3835        resource_request(guest, request).await;
3836        // An empty path names nothing to `openat`, which has no
3837        // `AT_EMPTY_PATH`: the kernel's ENOENT.
3838        let rendered = match if path.as_os_str().is_empty() {
3839            Ok(None)
3840        } else {
3841            self.rendered_procfs_at(guest, &procfs_spelling).await
3842        } {
3843            Ok(rendered) => rendered,
3844            Err(error) => {
3845                resource_release_all(guest).await;
3846                // Flags `build_open_flags` refuses fail before the lookup.
3847                return Err(
3848                    rendered_procfs::open_flags_refused(call.flags()).map_or(error, Into::into)
3849                );
3850            }
3851        };
3852        // `O_PATH|O_NOFOLLOW` opens a descriptor link itself, which the
3853        // kernel has.
3854        if let Some(target) = rendered.filter(|target| {
3855            !(target.via_link && call.flags().contains(OFlag::O_PATH | OFlag::O_NOFOLLOW))
3856        }) {
3857            let result = self.open_rendered_procfs(guest, call.flags(), target).await;
3858            resource_release_all(guest).await;
3859            return result;
3860        }
3861        // An `exe` link Detcore answers from its record (`Detcore::launched_exe`)
3862        // opens that image, for reading only: a write open of a running image
3863        // is the kernel's `ETXTBSY`, `O_NOFOLLOW` its `ELOOP`, and `O_PATH`
3864        // with it the link itself.
3865        let launched_exe = if call.flags().bits() & libc::O_ACCMODE == libc::O_RDONLY
3866            && !call
3867                .flags()
3868                .intersects(OFlag::O_NOFOLLOW | OFlag::O_TRUNC | OFlag::O_CREAT)
3869        {
3870            self.launched_exe(guest, (call.dirfd(), &path), true).await
3871        } else {
3872            None
3873        };
3874        // Signal phase 1 (`sigalrm_phase1`): in a process that handles SIGALRM,
3875        // an open that may wait (a FIFO, a character or block device) is
3876        // refused. Checked after the grant: no other guest runs before the open.
3877        if guest.thread_state().sigalrm_handled
3878            && !call.flags().intersects(OFlag::O_DIRECTORY | OFlag::O_PATH)
3879            && let Some(path) = call.path()
3880            && crate::sigalrm_phase1::open_refused(
3881                Self::inject_statat(
3882                    guest,
3883                    call.dirfd(),
3884                    path,
3885                    [Some(path), None],
3886                    AtFlags::empty(),
3887                )
3888                .await,
3889                call.flags().contains(OFlag::O_NONBLOCK),
3890            )
3891        {
3892            return Err(Errno::EOPNOTSUPP.into());
3893        }
3894        // The descriptor a descriptor link in the spelling names, as the open
3895        // finds it now, in its own turn, where the kernel looks the link up
3896        // (`LinkSource`). The open below may block and leave the turn.
3897        let link_source = crate::syscalls::namespace::own_descriptor_link(
3898            &observed_path,
3899            self.procfs_caller_ids(guest),
3900        )
3901        .and_then(|link| {
3902            guest
3903                .thread_state()
3904                .with_detfd(link.fd, |detfd| LinkSource {
3905                    fd: link.fd,
3906                    path: detfd.path(),
3907                    open_file: detfd.open_file_id(),
3908                    reached: detfd.procfs_reached(),
3909                })
3910                .ok()
3911        });
3912        // A blocking open, for reading or for writing, of a FIFO a guest made
3913        // waits in polling turns for a guest at the other end
3914        // (https://github.com/rrnewton/hermit/issues/2203).
3915        let fifo = (self.cfg.use_nonblocking_sockets()
3916            && !self.cfg.recordreplay_modes
3917            && !call.flags().intersects(OFlag::O_NONBLOCK | OFlag::O_PATH)
3918            && call.flags().bits() & libc::O_ACCMODE != libc::O_RDWR)
3919            .then(|| {
3920                crate::fifo_peer::fifo_at(
3921                    &self.cfg.backend,
3922                    guest.thread_state().physical_tid,
3923                    guest.tid().as_raw(),
3924                    call.dirfd(),
3925                    &path,
3926                )
3927            })
3928            .flatten()
3929            // Only a FIFO a guest made; every other one is opened as before.
3930            .filter(|(fifo, _)| crate::fifo_peer::is_guest_made(*fifo));
3931        // A later descriptor lookup proves the object, while this observation
3932        // brackets its kernel open against target exec/PID replacement.
3933        let maps_before = if guest.runtime_private_memory_regions().is_some() {
3934            if let Some((pid, tid)) = self.procfs_caller_ids(guest)
3935                && let Some(task) = crate::procfs::maps_task_at(&procfs_spelling, pid, tid)
3936            {
3937                Some((task, crate::tool_global::procfs_task(guest, task).await))
3938            } else {
3939                None
3940            }
3941        } else {
3942            None
3943        };
3944        let res: Result<i64, Error> = match fifo {
3945            Some((fifo, fifo_path)) => {
3946                self.open_fifo_once_a_guest_holds_its_peer(guest, call, fifo, &fifo_path)
3947                    .await
3948            }
3949            None => match launched_exe {
3950                Some(exe) => self.open_launched_exe(guest, call, exe.as_deref()).await,
3951                None => self
3952                    .record_or_replay(guest, Syscall::Openat(call))
3953                    .await
3954                    .map_err(Error::from),
3955            },
3956        };
3957
3958        match res {
3959            Ok(fd) => {
3960                let fd = fd as RawFd;
3961                // A link Detcore could not resolve whose kernel open reached
3962                // the launcher, in the guest's image's place.
3963                if crate::syscalls::namespace::exe_link_candidate(&path)
3964                    && self.opened_the_launcher(fd)
3965                {
3966                    let _ = guest.inject(syscalls::Close::new().with_fd(fd)).await;
3967                    resource_release_all(guest).await;
3968                    return self.refuse_launched_exe(guest, Sysno::openat, None).await;
3969                }
3970                // Another process's descriptor link, or another spelling of
3971                // this one's, to a placeholder: the guest opened the rendered
3972                // file again, as Linux opens the procfs file again.
3973                // (Where one tool process serves every guest, it knows every
3974                // placeholder, and a run that made none pays nothing.)
3975                if names_descriptor_link(&observed_path)
3976                    && !call.flags().contains(OFlag::O_PATH | OFlag::O_NOFOLLOW)
3977                    && (rendered_procfs::placeholders_exist()
3978                        || guest.config().backend.tool_shares_guest_descriptor_table)
3979                {
3980                    let behind = self.rendered_procfs_behind(guest, fd).await;
3981                    if !matches!(behind, Ok(None)) {
3982                        let _ = guest.inject(syscalls::Close::new().with_fd(fd)).await;
3983                    }
3984                    let result = match behind {
3985                        Ok(None) => None,
3986                        Ok(Some(path)) => {
3987                            let target = rendered_procfs::RenderedTarget {
3988                                procfs: ProcfsFile::from_rendered_path(path)
3989                                    .expect("a rendered path is a procfs file"),
3990                                via_link: true,
3991                            };
3992                            Some(self.open_rendered_procfs(guest, call.flags(), target).await)
3993                        }
3994                        Err(error) => Some(Err(error)),
3995                    };
3996                    if let Some(result) = result {
3997                        resource_release_all(guest).await;
3998                        return result;
3999                    }
4000                }
4001                // Under a network trace mode only; the run ends before the
4002                // guest sees the descriptor.
4003                let pid = guest.pid().as_raw();
4004                let backend = self.cfg.backend;
4005                self.network_check_open(guest, &observed_path, || {
4006                    resolved_open_path(&backend, pid, fd)
4007                })
4008                .await;
4009                let fd_type = path.to_str().map_or(FdType::Regular, |fname| {
4010                    if fname == "/dev/random" || fname == "/dev/urandom" {
4011                        FdType::Rng
4012                    } else {
4013                        FdType::Regular
4014                    }
4015                });
4016                // A guest-created pipe reopened by path (`/dev/stdin`,
4017                // `/proc/self/fd/N`, bash's `< <(cmd)` as `/dev/fd/63`) is a NEW open
4018                // file description, so it carries neither the Pipe type nor the
4019                // physical O_NONBLOCK that `handle_pipe2` gave the original. Left as a
4020                // physically blocking Regular fd, a read that waits for a writer blocks
4021                // in the kernel while holding the scheduler turn, and the writer never
4022                // runs (https://github.com/rrnewton/hermit/issues/1850). Give it the
4023                // same treatment as `handle_pipe2`: Pipe type plus a Detcore-internal
4024                // physical O_NONBLOCK, which F_GETFL hides from the guest. Only a pipe
4025                // this process already holds as scheduler-managed qualifies; a host
4026                // pipe or a named FIFO keeps `deterministic_read`'s Regular handling.
4027                // Gated like the forced O_NONBLOCK in F_SETFL: Replayer's descriptor
4028                // is an eventfd placeholder, so record and replay would not classify
4029                // alike.
4030                let fd_type = if fd_type == FdType::Regular
4031                    && self.cfg.use_nonblocking_sockets()
4032                    && !self.cfg.recordreplay_modes
4033                    && !call.flags().contains(OFlag::O_PATH)
4034                    && reopens_scheduler_managed_pipe(
4035                        &self.cfg.backend,
4036                        guest.pid().as_raw(),
4037                        fd,
4038                        &guest.thread_state().scheduler_managed_pipe_fds(),
4039                    )
4040                    && (call.flags().contains(OFlag::O_NONBLOCK)
4041                        || self.inject_physical_nonblocking(guest, fd).await.is_ok())
4042                {
4043                    FdType::Pipe
4044                } else {
4045                    fd_type
4046                };
4047                let host_stat = self
4048                    .add_fd_with_stat(guest, fd, call.flags(), fd_type)
4049                    .await?;
4050                // A placeholder reached through any other spelling (a symbolic
4051                // link to a descriptor link, `/dev/stdin`): the kernel opened
4052                // the placeholder, which is the rendered file again, also for
4053                // `O_PATH`. The kernel already followed every link, so none
4054                // remains for `O_NOFOLLOW` to refuse (an `O_PATH|O_NOFOLLOW`
4055                // descriptor for a link is the link, no placeholder).
4056                // Without virtualized metadata no stat was taken; take one
4057                // while a placeholder may be about.
4058                let identity = match &host_stat {
4059                    Some(stat) => Some(*stat),
4060                    None if self.renders_procfs(guest)
4061                        && (guest.thread_state().holds_a_rendered_procfs_file()
4062                            || rendered_procfs::placeholders_exist()) =>
4063                    {
4064                        self.inject_fstat(guest, fd).await.ok()
4065                    }
4066                    None => None,
4067                };
4068                let reached = match &identity {
4069                    Some(stat) if self.renders_procfs(guest) => {
4070                        self.recognize_placeholder(
4071                            guest,
4072                            &DetStat::from(*stat),
4073                            StatTarget::Descriptor(fd),
4074                        )
4075                        .await
4076                    }
4077                    _ => None,
4078                };
4079                if let Some(path) = reached {
4080                    guest.thread_state().remove_fd(fd);
4081                    let _ = guest.inject(syscalls::Close::new().with_fd(fd)).await;
4082                    let target = rendered_procfs::RenderedTarget {
4083                        procfs: ProcfsFile::from_rendered_path(path)
4084                            .expect("a rendered path is a procfs file"),
4085                        via_link: false,
4086                    };
4087                    let result = self.open_rendered_procfs(guest, call.flags(), target).await;
4088                    resource_release_all(guest).await;
4089                    return result;
4090                }
4091                // A `/proc` name outside the run's level that the kernel
4092                // reached through a spelling the lookup check does not
4093                // resolve (a symbolic link, `..`), named by the kernel's path
4094                // for the descriptor (see `refuse_procfs_name_outside_level`).
4095                if self
4096                    .opened_procfs_name_outside_level(
4097                        guest,
4098                        fd,
4099                        identity.as_ref().map(|stat| (stat.st_dev, stat.st_ino)),
4100                    )
4101                    .await
4102                {
4103                    guest.thread_state().remove_fd(fd);
4104                    let _ = guest.inject(syscalls::Close::new().with_fd(fd)).await;
4105                    resource_release_all(guest).await;
4106                    return Err(Errno::ENOENT.into());
4107                }
4108                // A FIFO (a named one, or a pipe reached by path that the
4109                // check above left `Regular`) stays `Regular` and physically
4110                // blocking, so a FIFO whose other end is on the host blocks as
4111                // before. Its first blocking read or write that finds a guest
4112                // holding the other end makes it an internally polled pipe
4113                // (`fifo_polls_if_a_guest_holds_its_peer`). Run mode only, as
4114                // for a reopened pipe: Replayer's descriptor is a placeholder.
4115                // `fifo_of` finds a FIFO only where it can read the guest's
4116                // descriptors through `/proc/<tid>`: under a separate tracer
4117                // (not DBT, in its PID container) whose guest thread IDs are
4118                // host tasks (not KVM). Elsewhere a FIFO blocks as before.
4119                if fd_type == FdType::Regular
4120                    && self.cfg.use_nonblocking_sockets()
4121                    && !self.cfg.recordreplay_modes
4122                    && !call.flags().contains(OFlag::O_PATH)
4123                    && let Some(fifo) = crate::fifo_peer::fifo_of(
4124                        &self.cfg.backend,
4125                        guest.thread_state().physical_tid,
4126                        guest.tid().as_raw(),
4127                        fd,
4128                    )
4129                {
4130                    guest
4131                        .thread_state()
4132                        .with_detfd(fd, |detfd| detfd.mark_fifo_awaiting_guest_peer())?;
4133                    crate::fifo_peer::note_guest_open(fifo, call.flags().bits());
4134                    // Name the FIFO for `--pipe-wake-latency`, and ready the
4135                    // opens waiting for the end this one opened.
4136                    if self.cfg.pipe_wake_latency_in_effect().is_some() {
4137                        let accmode = call.flags().bits() & libc::O_ACCMODE;
4138                        let end = crate::pipe_wake::ChannelEnd {
4139                            channel: crate::pipe_wake::ChannelId::Fifo(
4140                                crate::fifo_peer::fifo_channel(fifo),
4141                            ),
4142                            reads: accmode != libc::O_WRONLY,
4143                            writes: accmode != libc::O_RDONLY,
4144                        };
4145                        guest
4146                            .thread_state()
4147                            .with_detfd(fd, |detfd| detfd.set_channel(end))?;
4148                        for (applies, readies) in [
4149                            (end.reads, crate::pipe_wake::Wants::PeerReader),
4150                            (end.writes, crate::pipe_wake::Wants::PeerWriter),
4151                        ] {
4152                            if applies {
4153                                self.note_pipe_readied(guest, end.channel, readies).await;
4154                            }
4155                        }
4156                    }
4157                }
4158                if let (true, Some(stat)) = (guest.config().record_host_inputs, &host_stat) {
4159                    crate::tool_global::record_host_input(
4160                        guest,
4161                        observed_path.to_string_lossy().into_owned(),
4162                        detcore_model::host_input::HostFileIdentity::from_stat(stat),
4163                    )
4164                    .await;
4165                }
4166                // An open that finds its file linked, or creates it
4167                // (`O_TMPFILE`), reaches a file that has a name or never had
4168                // one, so a retired mapping of its inode described a file the
4169                // host has freed (https://github.com/rrnewton/hermit/issues/3840).
4170                // Reopening an unlinked file through `/proc/self/fd/N` finds no
4171                // link and keeps it.
4172                if let Some(stat) = &host_stat
4173                    && (stat.st_nlink > 0 || call.flags().contains(OFlag::O_TMPFILE))
4174                {
4175                    // A procfs entry the host rebuilt keeps its number when it is
4176                    // next written or read through this descriptor.
4177                    let procfs =
4178                        Self::procfs_entry(guest, &DetStat::from(stat), StatTarget::Descriptor(fd))
4179                            .await;
4180                    forget_retired_inode(
4181                        guest,
4182                        RawInode::new(stat.st_dev, stat.st_ino),
4183                        procfs.name(stat.st_dev),
4184                    )
4185                    .await;
4186                }
4187                // A descriptor that writes process memory can rewrite the
4188                // untraced code (see `record_untraced_code_change`). Reported
4189                // once the open returns, before the guest has the descriptor;
4190                // the record has no position in the run, so it covers every
4191                // write through it.
4192                if guest.config().record_host_inputs
4193                    && guest.config().untraced_code_range.is_some()
4194                    && may_write_process_memory(
4195                        call.flags(),
4196                        descriptor_identity(guest.tid().as_raw(), fd)
4197                            .as_ref()
4198                            .map(|(link, on_procfs)| (link.as_path(), *on_procfs)),
4199                    )
4200                {
4201                    crate::tool_global::record_host_mutation(guest, String::from("/")).await;
4202                }
4203                // A session leader with no controlling terminal that opens a
4204                // terminal without O_NOCTTY gains it as one, and the terminal
4205                // can then signal the session and its foreground process group
4206                // at moments set by host timing (`terminal_signals`). Hold
4207                // those signals in every process, as `handle_ioctl` does for
4208                // TIOCSCTTY and TIOCGPTPEER. Only the kernel knows whether this
4209                // open made the terminal controlling, so the record is made
4210                // after the call; it is still this thread's turn, and no other
4211                // thread's gated wait reads the record before the turn ends.
4212                // Skipped under record and replay: Replayer's descriptor is a
4213                // placeholder that never becomes a terminal, so the two runs
4214                // would not record alike.
4215                if bundled_signal_facts::host_timed_signal_sources_are_physical(
4216                    &guest.config().backend,
4217                ) && !self.cfg.recordreplay_modes
4218                    && open_can_acquire_controlling_terminal(call.flags())
4219                    && opened_controlling_terminal(guest.pid().as_raw(), fd, host_stat.as_ref())
4220                {
4221                    record_host_timed_signals(
4222                        guest,
4223                        HostTimedSignalScope::Container,
4224                        terminal_signals(),
4225                    )
4226                    .await;
4227                }
4228                if fd_type == FdType::Pipe {
4229                    self.maybe_set_nonblocking_fd(guest, fd);
4230                }
4231                // Classify the spelling the guest used FIRST. Several kinds are
4232                // defined by that spelling and MUST keep it: `/proc/self/...`,
4233                // `/proc/thread-self/...` and the mountinfo aliases all resolve
4234                // through `/proc/<pid>/fd/<fd>` to a numeric `/proc/<pid>/...`
4235                // path, which is a DIFFERENT (or absent) classification. So
4236                // resolution must never overwrite a spelling that already
4237                // classifies.
4238                //
4239                // Only when the spelling yields nothing do we ask the kernel
4240                // what the descriptor actually names. That is exactly the
4241                // AT_FDCWD/alias gap -- `chdir("/sys/module/kvm"); open("refcnt")`
4242                // classifies as nothing lexically -- and scoping it this way
4243                // makes the fallback MONOTONE: it can only add a classification
4244                // where there was none, never change one that already existed.
4245                //
4246                // Under record and replay the descriptor's link is read through
4247                // the recording: replay holds the descriptor's number with an
4248                // eventfd, which resolves to no procfs file, so both runs must
4249                // classify the open by the link the recording read
4250                // (`recorded_open_path`).
4251                // A process's `auxv` the kernel opened keeps the kernel's
4252                // bytes, unclassified, as before Detcore rendered the file
4253                // (`ProcfsFile::kernel_served`): by its spelling here, and by
4254                // its link below.
4255                let mut procfs =
4256                    ProcfsFile::from_path(&observed_path).filter(ProcfsFile::kernel_served);
4257                // Under record and replay the link is read for every open,
4258                // also one whose spelling classifies: a spelling through `..`
4259                // (`/proc/self/../self/io`) classifies as the file it reaches,
4260                // which may be outside the level.
4261                if procfs.is_none() || self.cfg.recordreplay_modes {
4262                    let resolved = if self.cfg.recordreplay_modes {
4263                        self.recorded_open_path(guest, fd).await?
4264                    } else {
4265                        resolved_open_path(&self.cfg.backend, guest.pid().as_raw(), fd)
4266                    };
4267                    // Under record and replay, a `/proc` name outside the
4268                    // run's level that a spelling the lookup check does not
4269                    // resolve reached, named by the link the recording read
4270                    // (in the guest's view, also after a `chroot`), so both
4271                    // runs refuse it alike (outside record and replay the
4272                    // check after the open above does it). Only where the
4273                    // recording saw that the descriptor is procfs: after a
4274                    // `chroot`, or under a user bind, `/proc` need not be.
4275                    if self.cfg.recordreplay_modes
4276                        && resolved.as_deref().is_some_and(|resolved| {
4277                            levels::procfs_name(resolved)
4278                                .is_some_and(|name| name.absent_at(self.cfg.proc_level))
4279                        })
4280                        // And the descriptor is procfs, not a user bind over
4281                        // part of `/proc`, as the recording saw it.
4282                        && self.recorded_descriptor_is_on_procfs(guest, fd).await
4283                    {
4284                        guest.thread_state().remove_fd(fd);
4285                        let _ = self
4286                            .record_or_replay(guest, syscalls::Close::new().with_fd(fd))
4287                            .await;
4288                        resource_release_all(guest).await;
4289                        return Err(Errno::ENOENT.into());
4290                    }
4291                    if procfs.is_none() {
4292                        procfs = resolved
4293                            .filter(|resolved| resolved != &observed_path)
4294                            .and_then(|resolved| ProcfsFile::from_path(&resolved))
4295                            .filter(ProcfsFile::kernel_served);
4296                    }
4297                }
4298                // A process's cgroup file bind-mounted at another path, or
4299                // reached through another procfs mount, classifies by neither
4300                // its spelling nor its link, which names the bind's mount
4301                // point, and would read as the host's bytes. Name the procfs
4302                // entry the descriptor reaches, as a stat does, and classify
4303                // that name, so the alias is the file it is (Codex review of
4304                // https://github.com/rrnewton/hermit/pull/4386). Only that
4305                // kind (`ProcfsFile::may_be_named_by_provenance`): a mountinfo
4306                // file of another procfs mount failed its identity check and
4307                // stopped the run (Claude re-check). Like the link above, this
4308                // only adds a classification. Record and replay name no
4309                // entries, and without sequentialized threads naming records a
4310                // determinism loss for any file that may be procfs, so neither
4311                // looks.
4312                if procfs.is_none()
4313                    && guest.config().sequentialize_threads
4314                    && let Some(stat) = host_stat
4315                    && let ProcfsEntry::At(within) =
4316                        Self::procfs_entry(guest, &DetStat::from(stat), StatTarget::Descriptor(fd))
4317                            .await
4318                {
4319                    procfs = ProcfsFile::from_path(
4320                        &Path::new("/proc").join(within.strip_prefix("/").unwrap_or(&within)),
4321                    )
4322                    .filter(ProcfsFile::may_be_named_by_provenance);
4323                }
4324                if guest.runtime_private_memory_regions().is_some()
4325                    && procfs.as_ref().is_some_and(ProcfsFile::is_maps)
4326                    && let Some(stat) = host_stat
4327                {
4328                    match self
4329                        .maps_descriptor_entry(guest, &DetStat::from(stat), fd)
4330                        .await
4331                    {
4332                        ProcfsEntry::At(within) => {
4333                            let actual = Path::new("/proc")
4334                                .join(within.strip_prefix("/").unwrap_or(&within));
4335                            if let Some(task) = self.maps_guest_target(guest, &actual).await
4336                                && let Some((before_task, before)) = maps_before.as_ref()
4337                                && *before_task == task
4338                            {
4339                                let after = crate::tool_global::procfs_task(guest, task).await;
4340                                if let Some(target) =
4341                                    crate::procfs::MapsTarget::from_open(task, before, &after)
4342                                    && guest.runtime_private_memory_is_current(&target.private)
4343                                {
4344                                    procfs.as_mut().unwrap().bind_maps_target(target);
4345                                }
4346                            }
4347                        }
4348                        // A shadowed proc spelling is an ordinary file. Its
4349                        // contents must not receive procfs projection at all.
4350                        ProcfsEntry::NotProcfs => procfs = None,
4351                        ProcfsEntry::Unnamed | ProcfsEntry::Unknown => {}
4352                    }
4353                }
4354                // A process's `mountinfo` or `mounts` the kernel opened reads
4355                // the view its task's root gives it, decided now, at the open,
4356                // as Linux takes the root at the open.
4357                if let Some(file) = procfs.as_ref()
4358                    && file.mount_table_rendering().is_some()
4359                {
4360                    let kernel = self.mount_view_is_kernel(guest, file).await;
4361                    procfs
4362                        .as_mut()
4363                        .expect("a classified procfs file disappeared")
4364                        .pin_mount_view(kernel);
4365                }
4366                if procfs
4367                    .as_ref()
4368                    .is_some_and(ProcfsFile::needs_bound_thread_identity)
4369                {
4370                    // TODO-HUMAN-REVIEW(PR-964): Bind thread-self at open time,
4371                    // matching procfs inode resolution even if another thread or
4372                    // a forked process later reads the shared descriptor.
4373                    let tgid = guest.inject(syscalls::Getpid::new()).await? as i32;
4374                    let tid = guest.inject(syscalls::Gettid::new()).await? as i32;
4375                    let ppid = guest.inject(syscalls::Getppid::new()).await? as i32;
4376                    procfs
4377                        .as_mut()
4378                        .expect("thread identity request lost its procfs file")
4379                        .bind_thread_identity(tgid, tid, ppid);
4380                }
4381                if procfs
4382                    .as_ref()
4383                    .and_then(ProcfsFile::timer_slack_target)
4384                    .is_some()
4385                {
4386                    let target = procfs
4387                        .as_ref()
4388                        .and_then(ProcfsFile::timer_slack_target)
4389                        .expect("timer-slack target disappeared");
4390                    let stat = match guest.thread_state().with_detfd(fd, |detfd| detfd.stat())? {
4391                        Some(stat) => libc::stat::from(&stat),
4392                        None => self.inject_fstat(guest, fd).await?,
4393                    };
4394                    // Recorder opens a real proc inode, while Replayer reserves
4395                    // the recorded descriptor number with an anonymous eventfd.
4396                    // A real proc descriptor is the strongest open-time task
4397                    // incarnation witness. For a virtual replay descriptor,
4398                    // bind the live numeric proc path instead; every operation
4399                    // re-resolves that same path, so exit or TID reuse still
4400                    // changes the inode and returns ESRCH.
4401                    let identity = if stat.st_mode & libc::S_IFMT == libc::S_IFREG {
4402                        (stat.st_dev, stat.st_ino)
4403                    } else {
4404                        self.observe_timer_slack_identity(guest, target)
4405                            .await?
4406                            .unwrap_or((stat.st_dev, stat.st_ino))
4407                    };
4408                    procfs
4409                        .as_mut()
4410                        .expect("timer-slack classification disappeared")
4411                        .bind_timer_slack_identity(identity.0, identity.1);
4412                }
4413                // Signal phase 1: what the kernel says this file is, for the
4414                // table's descriptor rules (`sigalrm_phase1`).
4415                let provenance = guest
4416                    .thread_state()
4417                    .sigalrm_handled
4418                    .then(|| crate::sigalrm_phase1::kernel_provenance(guest.pid().as_raw(), fd));
4419                // An open through one of the caller's descriptor links
4420                // records the path of the descriptor it reopens, so that a
4421                // name relative to it (`openat(fd, "stat")` with `fd` from
4422                // `open("/proc/self/fd/<a /proc descriptor>")`) is the file
4423                // Linux finds there (see `path_to_record_for_open`, which
4424                // also keeps the spelling wherever the link may reach
4425                // another file). Not after a `chroot`, where `/proc` and
4426                // `/dev/fd` need not be what they are outside it.
4427                //
4428                // The leader holds the table procfs reads for
4429                // `/proc/self/fd`, and so does every thread that holds the
4430                // same table: the process's, which the group shares
4431                // (`process_files`). Not known only for a state restored
4432                // from before that was kept, where only the leader is shown
4433                // to hold it.
4434                let opener = {
4435                    let detpid = self.own_detpid(guest);
4436                    let state = guest.thread_state();
4437                    DescriptorLinkOpener {
4438                        own: self.procfs_caller_ids(guest),
4439                        holds_process_table: state.dettid == detpid || state.holds_process_files(),
4440                    }
4441                };
4442                // Where `N`, in the caller's own table, has no recorded path
4443                // at all (a descriptor received through SCM_RIGHTS, which
4444                // Detcore does not track, or one discovered without one), a
4445                // procfs directory is named as the kernel beneath the backend
4446                // names the opened descriptor (`procfs_directory_named_for`,
4447                // one injected `readlinkat`). Only where Detcore renders
4448                // procfs files (not under record and replay, which does not
4449                // record that call, nor after a `chroot`), and with
4450                // sequentialized threads, so that no other guest thread can
4451                // replace the descriptor before the link is read.
4452                let unrecorded_link_identity = if self.renders_procfs(guest)
4453                    && guest.config().sequentialize_threads
4454                    && !opens_the_link_itself(&observed_path, call.flags())
4455                    && host_stat.is_none_or(|stat| stat.st_mode & libc::S_IFMT == libc::S_IFDIR)
4456                    && link_source
4457                        .as_ref()
4458                        .is_none_or(|source| source.path.is_none())
4459                    && crate::syscalls::namespace::own_descriptor_link(&observed_path, opener.own)
4460                        .is_some_and(|link| {
4461                            link.table == crate::syscalls::namespace::DescriptorTable::Thread
4462                                || opener.holds_process_table
4463                        }) {
4464                    Self::procfs_directory_named_for(guest, fd).await
4465                } else {
4466                    None
4467                };
4468                let recorded_path = {
4469                    let state = guest.thread_state();
4470                    if state.changed_root.load(Ordering::SeqCst) {
4471                        observed_path.clone()
4472                    } else {
4473                        // `N` as the lookup saw it, and only if `N` still holds
4474                        // the same open file description: a thread sharing
4475                        // the table may have replaced it while the open
4476                        // waited (`LinkSource`).
4477                        path_to_record_for_open(
4478                            &observed_path,
4479                            call.flags(),
4480                            opener,
4481                            |target| {
4482                                link_source.as_ref().and_then(|source| {
4483                                    source.path_if_unchanged(
4484                                        target,
4485                                        state.with_detfd(target, |detfd| detfd.open_file_id()).ok(),
4486                                    )
4487                                })
4488                            },
4489                            unrecorded_link_identity,
4490                        )
4491                    }
4492                };
4493                // A `/proc/self` or `/proc/thread-self` directory, opened by
4494                // that spelling or through a descriptor link to one, is the
4495                // task the selector reached at its first open; a name below it
4496                // is that task's file whoever looks it up (a fork's child, a
4497                // thread). Recorded only where Detcore renders per-process
4498                // files, which read it.
4499                let link_itself = self.renders_procfs(guest)
4500                    && opens_the_link_itself(&procfs_spelling, call.flags())
4501                    && names_a_selector_link(&procfs_spelling);
4502                let reached = if self.renders_procfs(guest) {
4503                    let linked = {
4504                        let state = guest.thread_state();
4505                        crate::syscalls::namespace::own_descriptor_link(&observed_path, opener.own)
4506                            .filter(|link| {
4507                                !opens_the_link_itself(&observed_path, call.flags())
4508                                    && (link.table
4509                                        == crate::syscalls::namespace::DescriptorTable::Thread
4510                                        || opener.holds_process_table)
4511                            })
4512                            .and_then(|link| {
4513                                link_source.as_ref().and_then(|source| {
4514                                    source.reached_if_unchanged(
4515                                        link.fd,
4516                                        state
4517                                            .with_detfd(link.fd, |detfd| detfd.open_file_id())
4518                                            .ok(),
4519                                    )
4520                                })
4521                            })
4522                    };
4523                    match linked {
4524                        Some(reached) => Some(reached),
4525                        // An `O_PATH | O_NOFOLLOW` open of `/proc/self` or
4526                        // `/proc/thread-self` is the link itself, no
4527                        // directory: nothing is below it (ENOTDIR,
4528                        // `procfs_link_itself` below).
4529                        None if link_itself => None,
4530                        None => match procfs_selector_reached(&procfs_spelling, opener.own) {
4531                            // The caller's own task, as the process table
4532                            // identifies it now.
4533                            Some(selected) => {
4534                                let incarnation = match procfs_reached_task(&selected) {
4535                                    Some(task) => {
4536                                        let answer =
4537                                            crate::tool_global::procfs_task(guest, task).await;
4538                                        answer.exists.then(|| answer.incarnation())
4539                                    }
4540                                    None => None,
4541                                };
4542                                Some((selected, incarnation))
4543                            }
4544                            // Below a directory Detcore named: a selector's
4545                            // keeps its task's identity, and one the kernel
4546                            // named (received over SCM_RIGHTS) is named again
4547                            // at each use.
4548                            None if procfs_spelling != observed_path => {
4549                                let inherited = (!path.is_absolute()
4550                                    && call.dirfd() != libc::AT_FDCWD)
4551                                    .then(|| {
4552                                        guest
4553                                            .thread_state()
4554                                            .with_detfd(call.dirfd(), |detfd| {
4555                                                detfd.procfs_reached()
4556                                            })
4557                                            .ok()
4558                                            .flatten()
4559                                    })
4560                                    .flatten()
4561                                    .and_then(|(_, incarnation)| incarnation);
4562                                Some((procfs_spelling.clone(), inherited))
4563                            }
4564                            None => None,
4565                        },
4566                    }
4567                } else {
4568                    None
4569                };
4570                // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/issues/4213):
4571                // Review binding procfs directory provenance to the object the
4572                // kernel opened, without sequentialized threads.
4573                // Without sequentialized threads another guest thread can
4574                // replace the descriptor (or move the working directory) that
4575                // a relative lookup starts from, between Detcore naming it and
4576                // the kernel's open. Provenance taken from the spelling then
4577                // describes an object the new descriptor may not hold: a
4578                // `/proc/self` mark on an ordinary directory would make a
4579                // later relative `mountinfo` render a file Linux has no way to
4580                // open there. So it is installed only if the descriptor the
4581                // kernel returned holds a directory below `/proc`, as its own
4582                // link names it (`descriptor_kernel_link`, one more injected
4583                // `readlinkat`); for `O_PATH | O_NOFOLLOW` of a selector, only
4584                // if it holds that selector link. With sequentialized threads
4585                // no other thread runs in between, and nothing is checked.
4586                let (reached, link_itself) = if (reached.is_some() || link_itself)
4587                    && !path.is_absolute()
4588                    && !guest.config().sequentialize_threads
4589                {
4590                    let held = Self::descriptor_kernel_link(guest, fd).await;
4591                    let below_proc = |name: &Path| {
4592                        use std::os::unix::ffi::OsStrExt;
4593                        name.starts_with("/proc")
4594                            && !name.as_os_str().as_bytes().ends_with(b" (deleted)")
4595                    };
4596                    let reached = reached.filter(|_| held.as_deref().is_some_and(below_proc));
4597                    let link_itself = link_itself
4598                        && held.as_deref().is_some_and(|name| {
4599                            name == Path::new("/proc/self")
4600                                || name == Path::new("/proc/thread-self")
4601                        });
4602                    (reached, link_itself)
4603                } else {
4604                    (reached, link_itself)
4605                };
4606                guest.thread_state().with_detfd(fd, |detfd| {
4607                    detfd.set_path(&recorded_path);
4608                    if let Some((reached, incarnation)) = reached.clone() {
4609                        detfd.set_procfs_reached(reached, incarnation);
4610                    }
4611                    if link_itself {
4612                        detfd.set_procfs_link_itself();
4613                    }
4614                    if let Some(procfs) = procfs.clone() {
4615                        detfd.set_procfs(procfs);
4616                    }
4617                    if let Some(provenance) = provenance {
4618                        detfd.set_sigalrm_phase1_provenance(provenance);
4619                    }
4620                })?;
4621                resource_release_all(guest).await;
4622                Ok(fd as i64)
4623            }
4624            // TODO: audit for error-nondeterminism:
4625            Err(e) => {
4626                // A root-only `/proc` name outside the run's level, reached
4627                // through a spelling the lookup check does not resolve,
4628                // refuses the open before its descriptor can be named; and
4629                // the KVM executor refuses whatever reaches procfs.
4630                let e = if matches!(e, Error::Errno(Errno::EACCES | Errno::EPERM))
4631                    && self
4632                        .refused_open_reaches_procfs_name_outside_level(guest, &call)
4633                        .await
4634                {
4635                    Errno::ENOENT.into()
4636                } else {
4637                    e
4638                };
4639                resource_release_all(guest).await;
4640                Err(e)
4641            }
4642        }
4643    }
4644
4645    /// SYS_close system call.
4646    pub async fn handle_close<G: Guest<Self>>(
4647        &self,
4648        guest: &mut G,
4649        call: syscalls::Close,
4650    ) -> Result<i64, Error> {
4651        let fd = call.fd();
4652        if let Ok(waited) = u32::try_from(fd)
4653            && let Some(refusal) = self
4654                .refuse_close_of_waited_listener(guest, Sysno::close, waited..=waited)
4655                .await
4656        {
4657            return refusal;
4658        }
4659        let channel_end = self.pipe_channel_end(guest, fd);
4660        let lock_tracked = self.lock_tracked_descriptions(guest, fd..=fd);
4661        let res = self.record_or_replay(guest, call).await;
4662        let fd_was_released = !matches!(res, Err(Errno::EBADF) | Err(Errno::ERESTARTSYS));
4663        if fd_was_released {
4664            if let Some(open_file_id) = guest.thread_state_mut().remove_fd(fd) {
4665                self.release_port_for_open_file(guest, open_file_id).await;
4666            }
4667            self.report_lock_references(guest, lock_tracked).await;
4668            if let Ok(fd) = u32::try_from(fd) {
4669                crate::tool_global::descriptors_replaced(guest, fd, fd).await;
4670            }
4671            trace!("Closed {}", fd);
4672            self.note_channel_end_closed(guest, channel_end).await;
4673        }
4674        res.map_err(Error::from)
4675    }
4676
4677    // AUTONOMOUS-BOT-IMPLEMENTED
4678    // TODO-HUMAN-REVIEW(PR-838): Review close_range descriptor-table synchronization.
4679    /// Close a contiguous descriptor range and mirror successful closes in Detcore.
4680    ///
4681    /// The pinned Reverie revision exposes close_range as `Syscall::Other`. The
4682    /// common flags=0 operation cannot block and is deterministic for the
4683    /// process-local descriptor table. CLOSE_RANGE_UNSHARE and
4684    /// CLOSE_RANGE_CLOEXEC need separate shared-table modeling, so return ENOSYS
4685    /// for nonzero flags rather than letting strict execution silently diverge.
4686    pub async fn handle_close_range<G: Guest<Self>>(
4687        &self,
4688        guest: &mut G,
4689        call: Syscall,
4690    ) -> Result<i64, Error> {
4691        let Syscall::Other(_, args) = call else {
4692            unreachable!("close_range unexpectedly gained a typed variant")
4693        };
4694        let first = args.arg0 as u32;
4695        let last = args.arg1 as u32;
4696        let flags = args.arg2 as u32;
4697        if flags != 0 {
4698            return Err(Errno::ENOSYS.into());
4699        }
4700        if first <= last
4701            && let Some(refusal) = self
4702                .refuse_close_of_waited_listener(guest, Sysno::close_range, first..=last)
4703                .await
4704        {
4705            return refusal;
4706        }
4707
4708        let channel_ends = self.pipe_channel_ends_in(guest, first, last);
4709        let lock_tracked = match (i32::try_from(first), i32::try_from(last)) {
4710            (Ok(first), Ok(last)) => self.lock_tracked_descriptions(guest, first..=last),
4711            (Ok(first), Err(_)) => self.lock_tracked_descriptions(guest, first..=RawFd::MAX),
4712            _ => Vec::new(),
4713        };
4714        let result = self.record_or_replay(guest, call).await;
4715        if result.is_ok() {
4716            let released = guest.thread_state_mut().remove_fd_range(first, last);
4717            for open_file_id in released {
4718                self.release_port_for_open_file(guest, open_file_id).await;
4719            }
4720            self.report_lock_references(guest, lock_tracked).await;
4721            crate::tool_global::descriptors_replaced(guest, first, last).await;
4722            for end in channel_ends {
4723                self.note_channel_end_closed(guest, Some(end)).await;
4724            }
4725        }
4726        result.map_err(Error::from)
4727    }
4728
4729    // AUTONOMOUS-BOT-IMPLEMENTED
4730    // TODO-HUMAN-REVIEW(#2373)
4731    /// Advisory whole-file locks, forwarded to the kernel.
4732    ///
4733    /// This was previously an unconditional no-op success, justified by the
4734    /// claim that "an advisory whole-file lock is never contended within the
4735    /// serialized container". That is false: serializing guest threads stops
4736    /// them EXECUTING simultaneously, it does not stop their lock HOLD
4737    /// INTERVALS from overlapping. A holder that is descheduled -- because it
4738    /// blocked, forked, or simply used up its timeslice -- keeps holding while
4739    /// another process runs and observes the lock. Measured before this change,
4740    /// on both ptrace and DBI, two processes held the same `LOCK_EX`
4741    /// simultaneously while native correctly returned `EWOULDBLOCK`.
4742    ///
4743    /// A no-op is the wrong failure direction for a determinism tool. It is
4744    /// deterministically wrong, so double-run verification cannot see it, and it
4745    /// silently removes mutual exclusion from every guest that uses a lockfile.
4746    ///
4747    /// Forwarding is what `fcntl` already does for POSIX record locks, which is
4748    /// why those work. The guest's descriptor is a real host descriptor, so the
4749    /// kernel supplies the whole contract for free and consistently with itself:
4750    /// shared vs exclusive, `LOCK_NB`, upgrade/downgrade (which Linux performs
4751    /// non-atomically -- see below, this handler compensates), release on
4752    /// `LOCK_UN`, release when the last descriptor for the open file
4753    /// description is closed, and release on process exit.
4754    ///
4755    /// Determinism, scoped to what is actually true. When every contender is
4756    /// inside the container the outcome is a function of which guest holds the
4757    /// lock, and that is fixed by Detcore's deterministic schedule, so a given
4758    /// program and seed produce the same acquisition outcome every run.
4759    ///
4760    /// The scope is not decoration. Because this forwards to the kernel, a
4761    /// process OUTSIDE the container holding a lock on a guest-visible file
4762    /// does change the guest's result -- measured: with a host `flock -x`
4763    /// holder, a guest `LOCK_EX|LOCK_NB` returns `EWOULDBLOCK`, and acquires
4764    /// without one. That is a host-state leak, it is faithful to Linux, and it
4765    /// is the same leak `fcntl` record locks have always had here. Hermit
4766    /// already declines to make a mutating external filesystem deterministic,
4767    /// and lock state on a shared file is part of that state. Do not restate
4768    /// this as "no host state enters the decision": it does, and the previous
4769    /// bug in this very function came from writing down a determinism argument
4770    /// that was broader than the truth.
4771    ///
4772    /// Note that the no-op this replaced was not host-independent in any useful
4773    /// sense either -- it was host-independent by being wrong in all cases.
4774    ///
4775    /// # Why a blocking request is probed non-blockingly, and what that costs
4776    ///
4777    /// A guest thread parked inside a kernel `flock` is not visible to the
4778    /// deterministic scheduler as blocked, so nothing runs to release the lock
4779    /// and the whole container wedges -- measured: a four-way contention guest
4780    /// that completes natively hung indefinitely under a plain forwarding
4781    /// implementation. So a blocking operation is rewritten to `LOCK_NB` and,
4782    /// if it turns out to be contended, refused rather than hung.
4783    ///
4784    /// That rewrite is not free, and the cost is a *lock the guest already
4785    /// owns*. Linux converts an `flock` lock in place and the conversion is not
4786    /// atomic: `flock_lock_inode` deletes this open file description's existing
4787    /// lock **before** it scans for a conflict, so a contended `LOCK_SH` ->
4788    /// `LOCK_EX` conversion leaves the caller holding nothing and then reports
4789    /// `EWOULDBLOCK`. Natively the guest never observes that intermediate
4790    /// state, because a *blocking* request would sleep and eventually acquire.
4791    /// Under the rewrite it would: the guest asked to wait, got told "no", and
4792    /// silently lost the shared lock it was already relying on.
4793    ///
4794    /// So this handler restores the prior mode before refusing a *blocking*
4795    /// conversion, making the refusal side-effect-free. It deliberately does
4796    /// **not** restore when the guest itself passed `LOCK_NB`: there the drop is
4797    /// exactly what Linux does, and re-acquiring would be a divergence in the
4798    /// other direction. `DetFd::flock_mode` is what makes the two cases
4799    /// distinguishable -- it records the mode Detcore last saw the kernel grant
4800    /// for this open file description, so a first acquisition (nothing to lose)
4801    /// is not confused with a conversion (something to lose).
4802    ///
4803    /// That cache covers locks Detcore granted while it had sole knowledge of
4804    /// the open file description. State becomes permanently unknown when the
4805    /// descriptor is inherited across a process fork, discovered after tracing
4806    /// begins, or received through `SCM_RIGHTS`, because another process can
4807    /// change that shared kernel lock without updating this cache. A blocking
4808    /// conversion in unknown state is refused before the nonblocking probe, so
4809    /// the refusal cannot destroy a lock Detcore cannot restore.
4810    pub async fn handle_flock<G: Guest<Self>>(
4811        &self,
4812        guest: &mut G,
4813        call: syscalls::Flock,
4814    ) -> Result<i64, Error> {
4815        // A flock belongs to its open file description. Whatever the call
4816        // did (took, converted, released, or, refused, dropped a lock in a
4817        // non-atomic conversion), the description's own fdinfo now says which
4818        // locks it holds (`procfs::locks`).
4819        let fd = call.fd();
4820        let result = self.flock_through_the_kernel(guest, call).await;
4821        self.refresh_description_locks(guest, fd, LockCall::Flock)
4822            .await?;
4823        result
4824    }
4825
4826    /// [`Self::handle_flock`]'s call itself.
4827    async fn flock_through_the_kernel<G: Guest<Self>>(
4828        &self,
4829        guest: &mut G,
4830        call: syscalls::Flock,
4831    ) -> Result<i64, Error> {
4832        const LOCK_NB: i32 = libc::LOCK_NB;
4833        /// `LOCK_SH`/`LOCK_EX`/`LOCK_UN` with `LOCK_NB` (and any padding) masked off.
4834        const MODE_MASK: i32 = libc::LOCK_SH | libc::LOCK_EX | libc::LOCK_UN;
4835
4836        let (fd, operation) = (call.fd(), call.operation());
4837        let requested = operation & MODE_MASK;
4838        let caller_wants_nonblocking = operation & LOCK_NB != 0;
4839        let releasing = requested == libc::LOCK_UN;
4840        let valid_operation = operation & !(MODE_MASK | LOCK_NB) == 0
4841            && matches!(requested, libc::LOCK_SH | libc::LOCK_EX | libc::LOCK_UN);
4842        let dettid = guest.thread_state().dettid;
4843
4844        // Preserve kernel validation for malformed operations. In particular,
4845        // an unknown descriptor with an invalid mode must report EINVAL rather
4846        // than being mistaken for a valid blocking request and refused with
4847        // ENOLCK.
4848        if !valid_operation {
4849            return self
4850                .record_or_replay(guest, call)
4851                .await
4852                .map_err(Error::from);
4853        }
4854
4855        // The mode Detcore last saw the kernel grant this open file description.
4856        let known_held = guest
4857            .thread_state()
4858            .with_detfd(fd, |detfd| detfd.known_flock_mode())
4859            .unwrap_or(None);
4860
4861        // A nonblocking conversion is allowed to have Linux's documented
4862        // non-atomic side effect. A blocking conversion is not: if this open
4863        // file description was inherited or received and its prior mode is
4864        // unknown, probing could silently drop a lock we cannot restore.
4865        // Validate the descriptor without changing lock state, then refuse the
4866        // uncertain blocking operation before issuing flock at all.
4867        if !caller_wants_nonblocking && !releasing && known_held.is_none() {
4868            guest
4869                .inject_with_retry(Syscall::Fcntl(
4870                    syscalls::Fcntl::new().with_fd(fd).with_cmd(F_GETFD),
4871                ))
4872                .await?;
4873            report_flock_refusal(&format!(
4874                "[dtid {dettid}] blocking flock(fd={fd}, operation={operation:#x}) refused: \
4875                 this open file description existed before Detcore observed its lock state, \
4876                 so a nonblocking probe could destroy a lock that cannot be restored. \
4877                 {FLOCK_REFUSAL_ADVICE}"
4878            ));
4879            return self
4880                .refuse_unserviceable_operation(guest, Sysno::flock, Errno::ENOLCK)
4881                .await;
4882        }
4883        let held = known_held.flatten();
4884
4885        // LOCK_UN cannot block, so it is forwarded exactly as the guest wrote it.
4886        let probe_operation = if releasing {
4887            operation
4888        } else {
4889            operation | LOCK_NB
4890        };
4891        let result = self
4892            .record_or_replay(guest, call.with_operation(probe_operation))
4893            .await;
4894        // A backend that cannot apply flock faithfully refuses it with a typed
4895        // refusal and no lock effect (the KVM backend refuses every lock
4896        // operation: https://github.com/rrnewton/reverie/issues/1069). Ask
4897        // before anything else is injected, since the next injection replaces
4898        // the backend's record. The refusal is reported as a refusal, never
4899        // handed to the guest as the backend's raw ENOSYS.
4900        let refusal = if result.is_err() {
4901            guest.take_unsupported_refusal()
4902        } else {
4903            None
4904        };
4905        if let Some(refusal) = refusal {
4906            let message = format!(
4907                "[dtid {dettid}] flock(fd={fd}, operation={operation:#x}) refused by the backend: {}. \
4908                 No lock was taken or released.",
4909                refusal.diagnostic
4910            );
4911            report_flock_refusal(&message);
4912            if !self.cfg.panic_on_unsupported_syscalls {
4913                crate::tool_global::report_unsupported_syscall(guest, Sysno::flock).await;
4914            }
4915            return self
4916                .refuse_unserviceable_operation_because(
4917                    guest,
4918                    Sysno::flock,
4919                    Errno::ENOLCK,
4920                    refusal.diagnostic,
4921                )
4922                .await;
4923        }
4924
4925        match result {
4926            Ok(value) => {
4927                let granted = if releasing { None } else { Some(requested) };
4928                let _ = guest
4929                    .thread_state()
4930                    .with_detfd(fd, |detfd| detfd.set_flock_mode(granted));
4931                trace!(
4932                    "flock(fd={}, operation={:#x}) served, open file now holds {:?}",
4933                    fd, operation, granted
4934                );
4935                Ok(value)
4936            }
4937            Err(Errno::EWOULDBLOCK) if caller_wants_nonblocking => {
4938                // Exactly what the guest asked for, including Linux's own
4939                // non-atomic conversion behavior: if this was a conversion, the
4940                // kernel really did drop the prior lock on the way to failing,
4941                // so the cache must forget it rather than claim a lock the
4942                // guest no longer holds.
4943                if held.is_some_and(|held| held != requested) {
4944                    let _ = guest
4945                        .thread_state()
4946                        .with_detfd(fd, |detfd| detfd.set_flock_mode(None));
4947                }
4948                trace!("flock(fd={}, operation={:#x}) would block", fd, operation);
4949                Err(Errno::EWOULDBLOCK.into())
4950            }
4951            Err(Errno::EWOULDBLOCK) => {
4952                // The guest asked to wait, and Detcore substituted a probe.
4953                // Undo the probe's collateral damage before refusing.
4954                if let Some(previous) = held.filter(|previous| *previous != requested) {
4955                    let restore = call.with_operation(previous | LOCK_NB);
4956                    match self.record_or_replay(guest, restore).await {
4957                        Ok(_) => {
4958                            warn!(
4959                                "[dtid {dettid}] contended blocking flock(fd={fd}, \
4960                                 operation={operation:#x}) refused; restored this open file's \
4961                                 prior {previous:#x} lock, which Linux's non-atomic conversion \
4962                                 had dropped. The guest holds exactly what it held before the \
4963                                 call."
4964                            );
4965                        }
4966                        Err(err) => {
4967                            let _ = guest
4968                                .thread_state()
4969                                .with_detfd(fd, |detfd| detfd.set_flock_mode(None));
4970                            error!(
4971                                "[dtid {dettid}] contended blocking flock(fd={fd}, \
4972                                 operation={operation:#x}) refused, AND this open file's prior \
4973                                 {previous:#x} lock could not be restored ({err}). Linux's \
4974                                 non-atomic conversion dropped it and something outside this \
4975                                 container took it in the interval. The guest has lost a lock \
4976                                 it held; treat any mutual exclusion it was protecting as \
4977                                 broken."
4978                            );
4979                        }
4980                    }
4981                }
4982                // Waiting faithfully needs a wait queue owned by the
4983                // deterministic scheduler, the way futexes are handled; until
4984                // that exists, refuse loudly. Returning success would recreate
4985                // the mutual-exclusion bug this handler was written to fix, and
4986                // blocking in the kernel would deadlock the container.
4987                report_flock_refusal(&format!(
4988                    "[dtid {dettid}] blocking flock(fd={fd}, operation={operation:#x}) is \
4989                     contended, and Detcore cannot yet park a thread on a file lock \
4990                     deterministically. Refusing rather than granting a lock another guest \
4991                     holds. {FLOCK_REFUSAL_ADVICE}"
4992                ));
4993                self.refuse_unserviceable_operation(guest, Sysno::flock, Errno::ENOLCK)
4994                    .await
4995            }
4996            Err(err) => {
4997                trace!(
4998                    "flock(fd={}, operation={:#x}) refused: {}",
4999                    fd, operation, err
5000                );
5001                Err(err.into())
5002            }
5003        }
5004    }
5005
5006    async fn snapshot_procfs<G: Guest<Self>>(
5007        &self,
5008        guest: &mut G,
5009        call: syscalls::Read,
5010    ) -> Result<Vec<u8>, Error> {
5011        // A backend-owned read may have advanced the kernel cursor without
5012        // passing through Detcore's logical procfs cursor (KVM does this for
5013        // worker-shared descriptors). Rewind before taking the initial snapshot
5014        // so a later intercepted pread cannot snapshot from EOF.
5015        //
5016        // AUTONOMOUS-BOT-IMPLEMENTED
5017        // TODO-HUMAN-REVIEW(#1903): ESPIPE is not a failure here. Several procfs
5018        // files are legitimately non-seekable -- `/proc/net/*` single-release
5019        // seq_files return ESPIPE from `llseek` on the host, verified natively:
5020        // `lseek(fd, 0, SEEK_SET)` on `/proc/net/sockstat` gives ESPIPE while the
5021        // subsequent `read(2)` returns data. Propagating that ESPIPE made the
5022        // GUEST's `read` fail on a file Linux reads fine (`cat
5023        // /proc/net/sockstat` -> "Illegal seek"), which is a deviation from Linux
5024        // semantics, not a determinism requirement: the rewind is an internal
5025        // correction Detcore performs for its own benefit and the guest never
5026        // asked for it. A non-seekable fd also cannot have been advanced behind
5027        // our back by a seek, and a freshly opened one is already at offset 0, so
5028        // skipping the rewind loses nothing the rewind was protecting.
5029        match guest
5030            .inject_with_retry(Syscall::Lseek(
5031                syscalls::Lseek::new()
5032                    .with_fd(call.fd())
5033                    .with_offset(0)
5034                    .with_whence(Whence::SEEK_SET),
5035            ))
5036            .await
5037        {
5038            Ok(_) => {}
5039            Err(Errno::ESPIPE) => {}
5040            Err(err) => return Err(err.into()),
5041        }
5042
5043        // Capture into scratch memory, never into the caller's buffer. The
5044        // caller receives only the sanitized bytes, so every host byte a
5045        // capture read left in its buffer past that length would stay visible
5046        // after the read returns: all of a host `/proc/modules` chunk behind
5047        // its empty sanitized view
5048        // (https://github.com/rrnewton/hermit/issues/3815). Saving and
5049        // restoring the caller's buffer cannot cover every destination the
5050        // kernel may write, such as a PROT_WRITE-only page that the save
5051        // cannot read. The caller's buffer sees only the sanitized
5052        // publication, which checks its protection as the kernel's copy does.
5053        let (lists_address_space, lists_locks) =
5054            guest.thread_state().with_detfd(call.fd(), |detfd| {
5055                (
5056                    detfd.procfs_lists_address_space(),
5057                    detfd.procfs_lists_locks(),
5058                )
5059            })?;
5060        if lists_address_space {
5061            self.capture_procfs_on_stack(guest, call, lists_locks).await
5062        } else {
5063            self.capture_procfs_in_mapping(guest, call, lists_locks)
5064                .await
5065        }
5066    }
5067
5068    /// Capture through a private anonymous mapping that is unmapped before
5069    /// returning, so no host byte stays in guest memory.
5070    async fn capture_procfs_in_mapping<G: Guest<Self>>(
5071        &self,
5072        guest: &mut G,
5073        call: syscalls::Read,
5074        lists_locks: bool,
5075    ) -> Result<Vec<u8>, Error> {
5076        const CAPTURE_CHUNK_BYTES: usize = 64 * 1024;
5077
5078        let mapped = guest
5079            .inject_with_retry(Syscall::Mmap(
5080                syscalls::Mmap::new()
5081                    .with_addr(None)
5082                    .with_len(CAPTURE_CHUNK_BYTES)
5083                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
5084                    .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
5085                    .with_fd(-1)
5086                    .with_offset(0),
5087            ))
5088            .await?;
5089        let mapping = usize::try_from(mapped)
5090            .ok()
5091            .and_then(AddrMut::<u8>::from_raw)
5092            .ok_or(Errno::EFAULT)?;
5093        let result = self
5094            .drain_procfs(guest, call, mapping, CAPTURE_CHUNK_BYTES, lists_locks)
5095            .await;
5096        guest
5097            .inject_with_retry(Syscall::Munmap(
5098                syscalls::Munmap::new()
5099                    .with_addr(Some(Addr::from(mapping).cast()))
5100                    .with_len(CAPTURE_CHUNK_BYTES),
5101            ))
5102            .await?;
5103        result
5104    }
5105
5106    /// Capture a file that lists the address space (`maps`, `smaps`,
5107    /// `numa_maps`, `smaps_rollup`) through the guest stack scratch. A
5108    /// capture mapping would be listed in the snapshot, or merged into a
5109    /// neighbouring row, and then be unmapped before the guest sees it. The
5110    /// stack scratch changes no mapping; its original bytes are put back, so
5111    /// no host byte stays below the stack pointer either.
5112    ///
5113    /// The scratch below the red zone is not always there: a thread, fiber or
5114    /// alternate signal stack may put the stack pointer just above a guard page
5115    /// or the end of its mapping (compare [`Self::inject_fstat`]). The read
5116    /// needs no stack, so that must not fail it. The capture then goes through
5117    /// the caller's buffer, which this read writes anyway, with the same save
5118    /// and restore before the output is copied. If not even its first byte can
5119    /// be read and written, Linux copies nothing and the read fails `EFAULT`;
5120    /// it does so here without taking the snapshot.
5121    async fn capture_procfs_on_stack<G: Guest<Self>>(
5122        &self,
5123        guest: &mut G,
5124        call: syscalls::Read,
5125        lists_locks: bool,
5126    ) -> Result<Vec<u8>, Error> {
5127        const CAPTURE_CHUNK_BYTES: usize = 512;
5128
5129        let mut original = [0_u8; CAPTURE_CHUNK_BYTES];
5130        {
5131            let mut stack = guest.stack().await;
5132            let scratch = stack.reserve::<[u8; CAPTURE_CHUNK_BYTES]>().cast::<u8>();
5133            // `commit` writes the reserved bytes, so save them before it.
5134            if save_procfs_scratch(&mut guest.memory(), scratch, &mut original)
5135                && let Ok(guard) = stack.commit()
5136            {
5137                let result = self
5138                    .drain_procfs(guest, call, scratch, CAPTURE_CHUNK_BYTES, lists_locks)
5139                    .await;
5140                guest.memory().write_exact(scratch, &original)?;
5141                drop(guard);
5142                return result;
5143            }
5144        }
5145
5146        let buffer = call.buf().ok_or(Errno::EFAULT)?;
5147        for chunk in [call.len().min(CAPTURE_CHUNK_BYTES), 1] {
5148            let original = &mut original[..chunk];
5149            if save_procfs_scratch(&mut guest.memory(), buffer, original) {
5150                let result = self
5151                    .drain_procfs(guest, call, buffer, chunk, lists_locks)
5152                    .await;
5153                guest.memory().write_exact(buffer, original)?;
5154                return result;
5155            }
5156        }
5157        Err(Errno::EFAULT.into())
5158    }
5159
5160    /// Read the host file to EOF through `scratch`, `chunk` bytes at a time.
5161    ///
5162    /// For `/proc/locks` (`lists_locks`), the bytes that reads after the one
5163    /// that provably reached the end of the kernel's lock list return are
5164    /// dropped (`procfs::locks::locks_capture_kept_bytes`): they are rows the
5165    /// kernel repeats when the host adds a lock between two reads, at moments
5166    /// the host decides. Those reads are still made, through the recorder,
5167    /// until one returns 0, so the recorded calls are the same as before and a
5168    /// replay drops the same bytes.
5169    async fn drain_procfs<G: Guest<Self>>(
5170        &self,
5171        guest: &mut G,
5172        call: syscalls::Read,
5173        scratch: AddrMut<'_, u8>,
5174        chunk: usize,
5175        lists_locks: bool,
5176    ) -> Result<Vec<u8>, Error> {
5177        const MAX_SNAPSHOT_BYTES: usize = 16 * 1024 * 1024;
5178
5179        let capture = call.with_buf(Some(scratch)).with_len(chunk);
5180        let mut contents = Vec::new();
5181        let mut reads = Vec::new();
5182        loop {
5183            let bytes_read = self.record_or_replay(guest, capture).await? as usize;
5184            if bytes_read == 0 {
5185                break;
5186            }
5187            if contents.len() + bytes_read > MAX_SNAPSHOT_BYTES {
5188                return Err(Errno::EFBIG.into());
5189            }
5190            let start = contents.len();
5191            contents.resize(start + bytes_read, 0);
5192            read_guest_exact(&guest.memory(), scratch, &mut contents[start..])?;
5193            reads.push(bytes_read);
5194        }
5195        if lists_locks {
5196            let kept = crate::procfs::locks::locks_capture_kept_bytes(&reads, chunk);
5197            if kept < contents.len() {
5198                // Not INFO: whether the host moved a lock between the reads is
5199                // host-timed, and INFO is compared between verified runs.
5200                tracing::debug!(
5201                    "[detcore] /proc/locks capture: dropped {} bytes that reads after the end \
5202                     of the kernel's list returned (reads {:?})",
5203                    contents.len() - kept,
5204                    reads
5205                );
5206                contents.truncate(kept);
5207            }
5208        }
5209        Ok(contents)
5210    }
5211
5212    /// The procfs directory that the kernel beneath the backend names for
5213    /// descriptor `fd`, which this guest thread just opened: its
5214    /// `/proc/thread-self/fd/<fd>` link, read by a `readlinkat` injected in
5215    /// the guest thread, which the host kernel answers under ptrace and DBT
5216    /// and the KVM executor answers for its own `/proc`, if that names a
5217    /// directory Detcore may record (`procfs_directory_link`). `None`
5218    /// otherwise, and where the guest stack scratch cannot hold the call's
5219    /// buffers, the call fails, or the link does not fit in 256 bytes: every
5220    /// path accepted is far shorter, and a truncated one must not match.
5221    async fn procfs_directory_named_for<G: Guest<Self>>(
5222        guest: &mut G,
5223        fd: RawFd,
5224    ) -> Option<PathBuf> {
5225        let named = Self::descriptor_kernel_link(guest, fd).await?;
5226        procfs_directory_link(&named).then_some(named)
5227    }
5228
5229    /// The `/proc/thread-self/fd/<fd>` link of descriptor `fd`, which this
5230    /// guest thread holds, as the kernel beneath the backend reads it (one
5231    /// `readlinkat` injected in the guest thread; the host kernel under ptrace
5232    /// and DBT, the KVM executor for its own `/proc`). `None` where the guest
5233    /// stack scratch cannot hold the call's buffers, the call fails, or the
5234    /// link does not fit in 256 bytes.
5235    async fn descriptor_kernel_link<G: Guest<Self>>(guest: &mut G, fd: RawFd) -> Option<PathBuf> {
5236        const LINK_CAPACITY: usize = 40;
5237        const TARGET_CAPACITY: usize = 256;
5238        let mut stack = guest.stack().await;
5239        let link = stack.push(rendered_procfs::c_string::<LINK_CAPACITY>(
5240            format!("/proc/thread-self/fd/{fd}").as_bytes(),
5241        ));
5242        let target = stack.reserve::<[u8; TARGET_CAPACITY]>();
5243        let stack_guard = stack.commit().ok()?;
5244        let length = guest
5245            .inject(
5246                syscalls::Readlinkat::new()
5247                    .with_dirfd(libc::AT_FDCWD)
5248                    .with_path(PathPtr::from_ptr(link.as_raw() as *const libc::c_char))
5249                    .with_buf(Some(target.cast::<libc::c_char>()))
5250                    .with_buf_len(TARGET_CAPACITY),
5251            )
5252            .await;
5253        let bytes = match length.map(|length| length as usize) {
5254            Ok(length) if length < TARGET_CAPACITY => {
5255                let mut bytes = vec![0; length];
5256                guest
5257                    .memory()
5258                    .read_exact(target.cast::<u8>(), &mut bytes)
5259                    .ok()
5260                    .map(|()| bytes)
5261            }
5262            _ => None,
5263        };
5264        drop(stack_guard);
5265        Some(PathBuf::from(
5266            <std::ffi::OsString as std::os::unix::ffi::OsStringExt>::from_vec(bytes?),
5267        ))
5268    }
5269
5270    /// What descriptor `fd` of the calling process names, as its
5271    /// `/proc/self/fd` link reads, through the recording: the recording reads
5272    /// the kernel's link and keeps its bytes, and replay, whose descriptor is
5273    /// an eventfd, returns the same bytes. `None` for a deleted or anonymous
5274    /// target, a link that cannot be read, or one too long for the 256 bytes
5275    /// read: every path Detcore classifies is far shorter, and a truncated
5276    /// one must not match.
5277    ///
5278    /// The link's name and the buffer go in the guest stack scratch, below the
5279    /// red zone, or, where that memory is not writable (a stack pointer just
5280    /// above a guard page or the lowest page of the main-thread stack), in a
5281    /// transient private page, as `inject_fstat` does
5282    /// (<https://github.com/rrnewton/hermit/issues/3328>): Detcore's
5283    /// bookkeeping must never fail the guest's open.
5284    async fn recorded_open_path<G: Guest<Self>>(
5285        &self,
5286        guest: &mut G,
5287        fd: RawFd,
5288    ) -> Result<Option<PathBuf>, Error> {
5289        const LINK_CAPACITY: usize = 32;
5290        const TARGET_CAPACITY: usize = 256;
5291        let link_name = rendered_procfs::c_string::<LINK_CAPACITY>(
5292            format!("/proc/thread-self/fd/{fd}").as_bytes(),
5293        );
5294        let mut stack = guest.stack().await;
5295        let link = stack.push(link_name);
5296        let target = stack.reserve::<[u8; TARGET_CAPACITY]>();
5297        let bytes = match stack.commit() {
5298            Ok(stack_guard) => {
5299                let bytes = self
5300                    .recorded_readlink(guest, link.as_raw(), target.as_raw(), TARGET_CAPACITY)
5301                    .await;
5302                drop(stack_guard);
5303                bytes
5304            }
5305            Err(_) => {
5306                info!(
5307                    "Guest stack scratch cannot hold the link of fd {}; using a transient page \
5308                     instead.",
5309                    fd
5310                );
5311                let len = LINK_CAPACITY + TARGET_CAPACITY;
5312                let mapped = guest
5313                    .inject_with_retry(Syscall::Mmap(
5314                        syscalls::Mmap::new()
5315                            .with_addr(None)
5316                            .with_len(len)
5317                            .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
5318                            .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
5319                            .with_fd(-1)
5320                            .with_offset(0),
5321                    ))
5322                    .await;
5323                let Some(page) = mapped
5324                    .ok()
5325                    .and_then(|mapped| usize::try_from(mapped).ok())
5326                    .and_then(AddrMut::<u8>::from_raw)
5327                else {
5328                    return Ok(None);
5329                };
5330                let bytes = if guest.memory().write_exact(page, &link_name).is_ok() {
5331                    self.recorded_readlink(
5332                        guest,
5333                        page.as_raw(),
5334                        page.as_raw() + LINK_CAPACITY,
5335                        TARGET_CAPACITY,
5336                    )
5337                    .await
5338                } else {
5339                    None
5340                };
5341                if let Err(errno) = guest
5342                    .inject_with_retry(Syscall::Munmap(
5343                        syscalls::Munmap::new()
5344                            .with_addr(Some(page.cast::<libc::c_void>().into()))
5345                            .with_len(len),
5346                    ))
5347                    .await
5348                {
5349                    warn!(
5350                        "[detcore] could not unmap the transient link page: {}",
5351                        errno
5352                    );
5353                }
5354                bytes
5355            }
5356        };
5357        Ok(bytes.and_then(|bytes| {
5358            let path = PathBuf::from(
5359                <std::ffi::OsString as std::os::unix::ffi::OsStringExt>::from_vec(bytes),
5360            );
5361            path.is_absolute().then_some(path)
5362        }))
5363    }
5364
5365    /// `readlink(link, target, capacity)` through the recording, both at guest
5366    /// addresses: the bytes it read, or `None` if it failed or filled the
5367    /// buffer (a link that may be truncated).
5368    async fn recorded_readlink<G: Guest<Self>>(
5369        &self,
5370        guest: &mut G,
5371        link: usize,
5372        target: usize,
5373        capacity: usize,
5374    ) -> Option<Vec<u8>> {
5375        let target = AddrMut::<u8>::from_raw(target)?;
5376        let length = self
5377            .record_or_replay(
5378                guest,
5379                syscalls::Readlink::new()
5380                    .with_path(PathPtr::from_ptr(link as *const libc::c_char))
5381                    .with_buf(Some(target.cast::<libc::c_char>()))
5382                    .with_bufsize(capacity),
5383            )
5384            .await
5385            .ok()?;
5386        let length = usize::try_from(length)
5387            .ok()
5388            .filter(|length| *length < capacity)?;
5389        let mut bytes = vec![0; length];
5390        guest.memory().read_exact(target, &mut bytes).ok()?;
5391        Some(bytes)
5392    }
5393
5394    async fn initialize_procfs_snapshot<G: Guest<Self>>(
5395        &self,
5396        guest: &mut G,
5397        call: syscalls::Read,
5398    ) -> Result<(), Error> {
5399        let maps_target = if guest.runtime_private_memory_regions().is_some()
5400            && guest
5401                .thread_state()
5402                .with_detfd(call.fd(), |fd| fd.procfs_is_maps())?
5403        {
5404            if !guest.config().sequentialize_threads {
5405                return Err(Error::Tool(anyhow::anyhow!(
5406                    "runtime-private maps view unavailable: capture is not sequentialized"
5407                )));
5408            }
5409            let target = guest
5410                .thread_state()
5411                .with_detfd(call.fd(), |fd| fd.procfs_maps_target())?
5412                .ok_or_else(|| {
5413                    Error::Tool(anyhow::anyhow!(
5414                        "runtime-private maps view unavailable: opened target image is unbound"
5415                    ))
5416                })?;
5417            if !guest.runtime_private_memory_is_current(&target.private) {
5418                return Err(Error::Tool(anyhow::anyhow!(
5419                    "runtime-private maps view unavailable: target ownership retired"
5420                )));
5421            }
5422            Some(target)
5423        } else {
5424            None
5425        };
5426        let template = guest
5427            .thread_state()
5428            .with_detfd(call.fd(), |detfd| detfd.procfs_rendering_template())?;
5429        // A process's `mountinfo` or `mounts`, in a run with a container
5430        // mount table: the table's bytes, whoever opened the file.
5431        let mount_table = self.mount_table_snapshot(guest, call.fd())?;
5432        let raw_contents = match template {
5433            // A descriptor that cannot read (`O_PATH`, write-only, or access
5434            // mode 3) reads nothing (EBADF), as the kernel's read of it,
5435            // which a rendered snapshot does not make, would answer.
5436            Some(_)
5437                if !can_read(
5438                    guest
5439                        .thread_state()
5440                        .with_detfd(call.fd(), |detfd| detfd.status_flags())?,
5441                ) =>
5442            {
5443                return Err(Errno::EBADF.into());
5444            }
5445            Some(template) => {
5446                // A per-process file's `show` finds its task again: a task
5447                // that is gone, or whose pid another task now holds, is ESRCH.
5448                // At position 0 only: a description that has no snapshot at
5449                // another position is one rebuilt from a placeholder whose
5450                // first read happened in another process
5451                // (`adopt_received_placeholder`, `adopt_placeholder`), where
5452                // Linux reads on from the buffer that read filled, without
5453                // looking for the task.
5454                let position = guest
5455                    .thread_state()
5456                    .with_detfd(call.fd(), |detfd| detfd.procfs_position())?
5457                    .map_or(0, |(offset, _)| offset);
5458                if position == 0 {
5459                    self.require_rendered_task(guest, call.fd()).await?;
5460                }
5461                mount_table.unwrap_or_else(|| template.to_vec())
5462            }
5463            // A mount table file the kernel opened takes no capture of the
5464            // kernel's bytes, which the table replaces; a descriptor that
5465            // cannot read reads nothing (EBADF), as the kernel's read of it
5466            // would answer.
5467            None if let Some(table) = mount_table => {
5468                if !can_read(
5469                    guest
5470                        .thread_state()
5471                        .with_detfd(call.fd(), |detfd| detfd.status_flags())?,
5472                ) {
5473                    return Err(Errno::EBADF.into());
5474                }
5475                table
5476            }
5477            None => self.snapshot_procfs(guest, call).await?,
5478        };
5479        let raw_contents = if let Some(target) = maps_target {
5480            if !guest.runtime_private_memory_is_current(&target.private) {
5481                return Err(Error::Tool(anyhow::anyhow!(
5482                    "runtime-private maps view unavailable: target ownership changed during capture"
5483                )));
5484            }
5485            crate::procfs::private_maps::project(&raw_contents, &target.private.regions).map_err(
5486                |reason| {
5487                    Error::Tool(anyhow::anyhow!(
5488                        "runtime-private maps view unavailable: {reason}"
5489                    ))
5490                },
5491            )?
5492        } else {
5493            raw_contents
5494        };
5495        // The guest mount view is the launch namespace (guest mount/unshare/
5496        // setns are refused under Detcore). Ephemeral host FUSE seed rows
5497        // (per-process and named-tool seeds) are other tenants' propagated
5498        // runtime state, not part of that namespace; exclude the class at
5499        // capture so snapshot identity assignment and every later read agree
5500        // on the same membership.
5501        let contents = if guest
5502            .thread_state()
5503            .with_detfd(call.fd(), |detfd| detfd.procfs_needs_mountinfo_identities())?
5504        {
5505            crate::procfs::exclude_ephemeral_host_seed_mounts(&raw_contents)
5506        } else {
5507            raw_contents
5508        };
5509        // Another process's `stat` or `status`, where the kernel numbers
5510        // processes otherwise than Detcore (DBT), is renumbered to the
5511        // guest's numbers (slice B3a-4 of
5512        // https://github.com/rrnewton/hermit/issues/4266).
5513        let held = guest.thread_state().with_detfd(call.fd(), |detfd| {
5514            detfd.procfs_kernel_numbers_held(&contents)
5515        })?;
5516        // The init's files (`/proc/1/...`, Hermit's own process and threads)
5517        // keep the numbers the kernel gives them, as their paths do. Which
5518        // process's file it is, the kernel's name for the descriptor says
5519        // where the tool shares the guest's descriptors (DBT), whatever path
5520        // reached it.
5521        let path = if guest.config().backend.tool_shares_guest_descriptor_table {
5522            std::fs::read_link(format!("/proc/thread-self/fd/{}", call.fd())).ok()
5523        } else {
5524            guest
5525                .thread_state()
5526                .with_detfd(call.fd(), |detfd| detfd.path())?
5527        };
5528        let init = path.is_some_and(|path| crate::procfs::ids::names_init(&path));
5529        let held = if init { Vec::new() } else { held };
5530        if let Some(numbers) = Self::guest_procfs_numbers(guest, &held).await {
5531            guest.thread_state().with_detfd(call.fd(), |detfd| {
5532                detfd.set_procfs_guest_numbers(numbers.clone())
5533            })?;
5534        }
5535        let virtual_uptime_seconds = self.calculate_procfs_uptime(guest).await?;
5536        // A file Detcore renders at its first read: at the uptime an earlier
5537        // read of the same open file took its snapshot at, which a process
5538        // without Detcore's state of it (after `exec` or `fork` where the
5539        // tool runs in each guest process) finds on the placeholder.
5540        let virtual_uptime_seconds = match guest.thread_state().with_detfd(call.fd(), |detfd| {
5541            detfd
5542                .procfs_rendered_at_first_read()
5543                .then(|| detfd.procfs_rendered_path())
5544                .flatten()
5545        })? {
5546            Some(path) => {
5547                self.first_read_uptime(guest, call.fd(), path, virtual_uptime_seconds)
5548                    .await
5549            }
5550            None => virtual_uptime_seconds,
5551        };
5552        // Only `/proc/stat` renders btime. Computing it for every snapshot let
5553        // an unrepresentable boot instant refuse unrelated files such as
5554        // `/proc/uptime`.
5555        let needs_boot_time = guest
5556            .thread_state()
5557            .with_detfd(call.fd(), |detfd| detfd.procfs_needs_boot_time())?;
5558        let virtual_boot_time_seconds = needs_boot_time
5559            .then(|| self.calculate_procfs_boot_time())
5560            .transpose()?;
5561        let virtual_realtime_seconds = i64::try_from(thread_observe_time(guest).await.as_secs())
5562            .map_err(|_| Errno::EOVERFLOW)?;
5563        // TODO-HUMAN-REVIEW(PR-723): Review injected identity snapshot reads.
5564        let virtual_pid = guest.inject(syscalls::Getpid::new()).await? as i32;
5565        let virtual_ppid = guest.inject(syscalls::Getppid::new()).await? as i32;
5566        let virtual_pty_count = guest.thread_state().count_open_files_at_paths(&[
5567            std::path::Path::new("/dev/ptmx"),
5568            std::path::Path::new("/dev/pts/ptmx"),
5569        ]);
5570        let target_fd = guest
5571            .thread_state()
5572            .with_detfd(call.fd(), |detfd| detfd.procfs_target_fd())?;
5573        // The kernel's fdinfo for a procfs file Detcore renders describes the
5574        // memfd standing in for it. Linux's names the file: Detcore's cursor,
5575        // the guest's procfs mount and the file's inode. The cursor is the one
5576        // processes sharing the open file share.
5577        if let Some(target_fd) = target_fd {
5578            self.adopt_rendered_procfs_position(guest, target_fd)
5579                .await?;
5580        }
5581        let rendered_target = match target_fd {
5582            Some(target_fd) => guest
5583                .thread_state()
5584                .with_detfd(target_fd, |detfd| {
5585                    detfd.procfs_rendered_path().map(|path| {
5586                        (
5587                            path,
5588                            detfd.procfs_position().map_or(0, |(offset, _)| offset),
5589                        )
5590                    })
5591                })
5592                .ok()
5593                .flatten(),
5594            None => None,
5595        };
5596        let contents = match rendered_target {
5597            Some((_, offset)) => format!(
5598                "pos:\t{offset}\nflags:\t0\nmnt_id:\t{}\nino:\t0\n",
5599                rendered_procfs::guest_procfs_mount_id()?
5600            )
5601            .into_bytes(),
5602            None => contents,
5603        };
5604        let fdinfo_identity = if let Some(target_fd) = target_fd {
5605            let (cached_stat, logical_flags, open_file_id, fd_type, inode_override) =
5606                guest.thread_state().with_detfd(target_fd, |detfd| {
5607                    (
5608                        detfd.stat(),
5609                        detfd.status_flags(),
5610                        detfd.open_file_id(),
5611                        detfd.ty(),
5612                        deterministic_stdio_inode_for_resource(target_fd, detfd.resource()),
5613                    )
5614                })?;
5615            let stat = match cached_stat {
5616                Some(stat) => stat,
5617                None => DetStat::from(self.inject_fstat(guest, target_fd).await?),
5618            };
5619            // Keyed as `fstat` keys the descriptor, so the two numbers agree.
5620            let virtual_inode = match inode_override {
5621                Some(inode) => inode,
5622                // Detcore numbered it when it rendered the file.
5623                None if let Some((path, _)) = rendered_target => {
5624                    DetInode::mint(procfs_inode::rendered_inode(path))
5625                }
5626                None => {
5627                    let procfs =
5628                        Self::procfs_entry(guest, &stat, StatTarget::Descriptor(target_fd)).await;
5629                    let files = self.rendered_files(guest);
5630                    if let Some(path) = rendered_entry(&procfs, &stat, guest.config(), files) {
5631                        DetInode::mint(procfs_inode::rendered_inode(path))
5632                    } else {
5633                        determinize_inode_observing_mtime(
5634                            guest,
5635                            stat.raw_inode(),
5636                            procfs.name(stat.dev),
5637                            ObservedMtime::Unobserved,
5638                            InodeSighting::Descriptor,
5639                        )
5640                        .await
5641                        .0
5642                    }
5643                }
5644            };
5645            let raw_mount_id =
5646                detcore_model::procfs::parse_fdinfo_mount_id(&contents).ok_or_else(|| {
5647                    Error::Tool(anyhow::anyhow!(
5648                        "kernel returned malformed /proc/*/fdinfo without one numeric mnt_id"
5649                    ))
5650                })?;
5651            // CLI container and recording paths provide the exact namespace's
5652            // row order. Replay intentionally retains the recording-time raw
5653            // IDs because ReadV2 supplies recording-time fdinfo bytes.
5654            let has_configured_mount_ids = guest.config().mountinfo_mount_ids_captured;
5655            let virtual_mount_id = if raw_mount_id == 0 {
5656                // Linux uses zero for anonymous objects such as memfd. Key the
5657                // equivalence on the observed value, not our descriptor type.
5658                0
5659            } else if !has_configured_mount_ids {
5660                // Public non-container callers have no pre-captured provenance.
5661                // Mount/unshare/setns are refused once Detcore starts, so a
5662                // tracer-side snapshot of this task's namespace is immutable.
5663                let mountinfo_path = format!("/proc/{}/mountinfo", guest.pid().as_raw());
5664                let mountinfo_contents = std::fs::read(&mountinfo_path).map_err(|error| {
5665                    Error::Tool(anyhow::anyhow!(
5666                        "failed to read {mountinfo_path} while validating fdinfo mnt_id: {error}"
5667                    ))
5668                })?;
5669                // Same guest mount model as the mountinfo capture path:
5670                // ephemeral host seed rows are not guest namespace members
5671                // and must not shift run-global mount-ID assignment.
5672                let mountinfo_contents =
5673                    crate::procfs::exclude_ephemeral_host_seed_mounts(&mountinfo_contents);
5674                let mountinfo_rows =
5675                    crate::procfs::parse_mountinfo(&mountinfo_contents).ok_or_else(|| {
5676                        Error::Tool(anyhow::anyhow!(
5677                            "kernel returned malformed {mountinfo_path} while validating fdinfo mnt_id"
5678                        ))
5679                    })?;
5680                let snapshot = MountInfoSnapshot::new(
5681                    mountinfo_rows,
5682                    &[],
5683                    false,
5684                    BTreeMap::new(),
5685                    BTreeMap::new(),
5686                )
5687                .ok_or_else(|| {
5688                    Error::Tool(anyhow::anyhow!(
5689                        "{mountinfo_path} failed strict identity validation for fdinfo"
5690                    ))
5691                })?;
5692                determinize_mount_id(guest, raw_mount_id, Some(snapshot.raw_mount_id_order()))
5693                    .await
5694                    .ok_or_else(|| {
5695                        Error::Tool(anyhow::anyhow!(
5696                            "mountinfo mount-ID order changed after the identity snapshot while resolving fdinfo mnt_id {raw_mount_id} for {fd_type:?} from {mountinfo_path}"
5697                        ))
5698                    })?
5699            } else {
5700                // A file on a mount the container mount table hides reports
5701                // its nearest shown ancestor (`ContainerMountTable::select`).
5702                let raw_mount_id = self.shown_mount_id(guest, raw_mount_id);
5703                determinize_mount_id(guest, raw_mount_id, None)
5704                    .await
5705                    .ok_or_else(|| {
5706                        Error::Tool(anyhow::anyhow!(
5707                            "recorded mount identity provenance was invalid while resolving fdinfo mnt_id {raw_mount_id} for {fd_type:?}"
5708                        ))
5709                    })?
5710            };
5711            Some((
5712                // Determinized immediately above (stdio-special or
5713                // `determinize_inode`); lowered to an integer only here, at the
5714                // point it is rendered into guest-visible fdinfo text.
5715                virtual_inode.as_raw(),
5716                logical_flags,
5717                open_file_id.deterministic_socket_cookie(),
5718                virtual_mount_id,
5719            ))
5720        } else {
5721            None
5722        };
5723        // The guest's CPUID instruction is answered from Detcore's table
5724        // exactly when CPUID is virtualized and the backend delivers the
5725        // instruction to Detcore (`handle_cpuid_event`), on ptrace and KVM
5726        // alike; without CPUID interception the guest sees the host's CPU,
5727        // and so does this file. There Detcore renders the file itself
5728        // (`ProcfsFile::rendered_path`); this is for a /proc/cpuinfo the
5729        // kernel opened: through a symbolic link, after `chroot`, or under
5730        // record and replay.
5731        // A placeholder (`procfs_rendered_path`), which exists only where the
5732        // session renders the file, is rendered from the table: it holds no
5733        // other bytes.
5734        let (is_cpuinfo, placeholder) = guest.thread_state().with_detfd(call.fd(), |detfd| {
5735            (
5736                detfd.procfs_is_cpuinfo(),
5737                detfd.procfs_rendered_path().is_some(),
5738            )
5739        })?;
5740        let virtual_cpuinfo = (is_cpuinfo && (placeholder || self.rendered_files(guest).cpuinfo))
5741            .then(|| self.virtual_cpuid().cpuinfo());
5742        let needs_random_uuid = guest
5743            .thread_state()
5744            .with_detfd(call.fd(), |detfd| detfd.procfs_needs_random_uuid())?;
5745        // AUTONOMOUS-BOT-IMPLEMENTED
5746        // TODO-HUMAN-REVIEW(PR-955): Review deterministic kernel UUID generation.
5747        let random_uuid =
5748            needs_random_uuid.then(|| guest.thread_state_mut().thread_prng().random::<[u8; 16]>());
5749        // ⚠️ DETERMINIZE HERE, IN THE CALLER, THROUGH THE SAME POOLS `stat` USES.
5750        //
5751        // The sanitizers in `crate::procfs` are pure functions of content and
5752        // hold no guest handle, so they cannot reach `InodePool`/`DevicePool`.
5753        // Minting an identity down there would make the maps column stable and
5754        // STILL DISAGREE with `stat` -- deterministic, reproducible and wrong.
5755        // This mirrors how `fdinfo_identity` is built a few lines above:
5756        // determinize with `determinize_inode`/`determinize_device`, then hand
5757        // the finished values down purely to be rendered.
5758        //
5759        // BOTH COLUMNS, not just the inode. `determinize_stat` sanitizes
5760        // `st_dev` as well, so rewriting only the inode would leave the device
5761        // disagreeing -- the same defect with the reported symptom removed.
5762        let needs_mapping_identities = guest
5763            .thread_state()
5764            .with_detfd(call.fd(), |detfd| detfd.procfs_needs_mapping_identities())?;
5765        let mut mapping_identities: BTreeMap<(u64, u64), (u64, u64)> = BTreeMap::new();
5766        if needs_mapping_identities {
5767            // A mapping backed by stdio must report the SAME inode fdinfo
5768            // reports for that fd, which is the fixed `deterministic_stdio_inode`
5769            // value rather than a pooled one. Matching is by raw inode, read
5770            // from the cached stat only: injecting an fstat here would add
5771            // syscalls to every maps read and perturb the very traces this
5772            // change is meant to keep consistent.
5773            //
5774            // The lowest descriptor wins a shared identity, as in
5775            // `deterministic_stdio_inode_for_raw`. Detcore gives all three
5776            // inherited descriptors the stat of its own stdin (`setup_stdio`),
5777            // so they share one until the guest replaces them; a mapping of
5778            // that file is a mapping of fd 0, and must report the 1000 that
5779            // fd 0's fdinfo reports, not stderr's 1002.
5780            let mut stdio_by_raw_inode: BTreeMap<RawInode, DetInode> = BTreeMap::new();
5781            for fd in libc::STDIN_FILENO..=libc::STDERR_FILENO {
5782                let cached = guest
5783                    .thread_state()
5784                    .with_detfd(fd, |detfd| {
5785                        let inode = deterministic_stdio_inode_for_resource(fd, detfd.resource())?;
5786                        detfd.stat().map(|stat| (stat.raw_inode(), inode))
5787                    })
5788                    .ok()
5789                    .flatten();
5790                if let Some((raw, det)) = cached {
5791                    stdio_by_raw_inode.entry(raw).or_insert(det);
5792                }
5793            }
5794            // One numbering request per file-backed line, in line order
5795            // (address order, which the guest's own mmaps decide), repeats and
5796            // stdio-backed lines included. The pool numbers files in request
5797            // order and every request consumes a number, so sorting by raw
5798            // `(dev, ino)` would let a host inode decide which file gets which
5799            // number, and skipping lines whose host pair repeats (hard-linked
5800            // libraries) or matches stdio would let host identity decide how
5801            // many numbers a read consumes
5802            // (https://github.com/rrnewton/hermit/issues/2897).
5803            //
5804            // The device a mapping names is the filesystem's own, which on
5805            // btrfs is not the per-subvolume device `stat` reports; the pair is
5806            // the identity either way, as it is for the device determinized
5807            // below.
5808            let raw_pairs: Vec<(u64, u64)> = String::from_utf8_lossy(&contents)
5809                .lines()
5810                .filter_map(crate::procfs::mapping_header_identity)
5811                .collect();
5812            let pooled = determinize_mapping_inodes(
5813                guest,
5814                raw_pairs
5815                    .iter()
5816                    .map(|&(raw_dev, raw_inode)| RawInode::new(raw_dev, raw_inode))
5817                    .collect(),
5818            )
5819            .await;
5820            for (&(raw_dev, raw_inode), pooled) in raw_pairs.iter().zip(pooled) {
5821                if mapping_identities.contains_key(&(raw_dev, raw_inode)) {
5822                    continue;
5823                }
5824                let det_inode = stdio_by_raw_inode
5825                    .get(&RawInode::new(raw_dev, raw_inode))
5826                    .copied()
5827                    .unwrap_or(pooled);
5828                // The device pool numbers first sightings only, so a repeated
5829                // device request changes nothing.
5830                let det_dev = determinize_device(guest, raw_dev).await;
5831                mapping_identities.insert((raw_dev, raw_inode), (det_dev, det_inode.as_raw()));
5832            }
5833        }
5834        let mountinfo = if guest
5835            .thread_state()
5836            .with_detfd(call.fd(), |detfd| detfd.procfs_needs_mountinfo_identities())?
5837        {
5838            let mut rows = crate::procfs::parse_mountinfo(&contents).ok_or_else(|| {
5839                Error::Tool(anyhow::anyhow!(
5840                    "kernel returned malformed /proc/*/mountinfo"
5841                ))
5842            })?;
5843            let mut device_rewrites = BTreeMap::new();
5844            for &(mountinfo_device, metadata_device) in &guest.config().mountinfo_device_rewrites {
5845                if device_rewrites
5846                    .insert(mountinfo_device, metadata_device)
5847                    .is_some()
5848                {
5849                    return Err(Error::Tool(anyhow::anyhow!(
5850                        "duplicate proven mountinfo device rewrite for raw device {mountinfo_device}"
5851                    )));
5852                }
5853            }
5854            for row in &mut rows {
5855                if let Some(metadata_device) = device_rewrites.get(&row.raw_device) {
5856                    row.raw_device = *metadata_device;
5857                }
5858            }
5859            let mut raw_devices = Vec::new();
5860            let mut seen_devices = BTreeSet::new();
5861            for row in &rows {
5862                if seen_devices.insert(row.raw_device) {
5863                    raw_devices.push(row.raw_device);
5864                }
5865            }
5866            let mut devices = BTreeMap::new();
5867            let virtualize_metadata = guest.config().virtualize_metadata;
5868            if virtualize_metadata {
5869                // Intentionally use snapshot row order to pre-populate the
5870                // same run-global DevicePool used by stat/statx. This makes
5871                // every later observation of a device agree within the run.
5872                // It does not promise that unlike host filesystem layouts
5873                // expose the same device equivalence classes or order.
5874                for raw in raw_devices {
5875                    devices.insert(raw, determinize_device(guest, raw).await);
5876                }
5877            }
5878            let mut root_rewrites = BTreeMap::new();
5879            for rewrite in &guest.config().mountinfo_root_rewrites {
5880                if root_rewrites
5881                    .insert(rewrite.raw_mount_id, rewrite.clone())
5882                    .is_some()
5883                {
5884                    return Err(Error::Tool(anyhow::anyhow!(
5885                        "duplicate proven mountinfo root rewrite for mount ID {}",
5886                        rewrite.raw_mount_id
5887                    )));
5888                }
5889            }
5890            let mut snapshot = MountInfoSnapshot::new(
5891                rows,
5892                if guest.config().mountinfo_mount_ids_captured {
5893                    &guest.config().mountinfo_mount_ids
5894                } else {
5895                    &[]
5896                },
5897                virtualize_metadata,
5898                devices,
5899                root_rewrites,
5900            )
5901            .ok_or_else(|| {
5902                Error::Tool(anyhow::anyhow!(
5903                    "mountinfo snapshot failed strict identity validation"
5904                ))
5905            })?;
5906            // Number this view's mount IDs through the same run-global pool
5907            // as fdinfo. IDs the run has already shown keep their numbers;
5908            // the rest are numbered in the order this view presents them
5909            // (rows, then parent-only IDs). The canonical order, which may
5910            // follow the captured namespace, only validates the view.
5911            let observation_order = snapshot.raw_mount_id_observation_order();
5912            let Some(virtual_ids) = resolve_mountinfo_identities(
5913                guest,
5914                snapshot.raw_mount_id_order(),
5915                observation_order.clone(),
5916            )
5917            .await
5918            else {
5919                return Err(Error::Tool(anyhow::anyhow!(
5920                    "mountinfo mount-ID order changed after the run-global identity snapshot"
5921                )));
5922            };
5923            if !snapshot.use_run_mount_ids(&observation_order, &virtual_ids) {
5924                return Err(Error::Tool(anyhow::anyhow!(
5925                    "run-global mount identities do not cover this mountinfo snapshot"
5926                )));
5927            }
5928            Some(snapshot)
5929        } else {
5930            None
5931        };
5932        // `/proc/locks` keeps the guest's own rows only: an OFD lock has no
5933        // owning task, so Linux shows every process's OFD locks from every
5934        // PID namespace (`procfs::locks`). Decided before the sanitizer
5935        // numbers identities, so a dropped row shifts no remaining id. The
5936        // capture above and this decision are two steps of one turn: with
5937        // sequentialized threads no other guest thread's lock call (and its
5938        // fdinfo record) runs between them. Parallel execution would need
5939        // them taken as one.
5940        let lock_rows_kept = if guest
5941            .thread_state()
5942            .with_detfd(call.fd(), |detfd| detfd.procfs_lists_locks())?
5943        {
5944            match crate::procfs::locks::lock_rows(&contents) {
5945                Some(rows) => match crate::tool_global::guest_lock_rows(guest, rows).await {
5946                    Ok(kept) => Some(kept),
5947                    Err(reason) => {
5948                        let reason = format!(
5949                            "/proc/locks: {reason}; that description's rows cannot be told \
5950                             from another process's"
5951                        );
5952                        self.refuse_lock_bookkeeping(guest, reason).await
5953                    }
5954                },
5955                // Rows that do not parse: the sanitizer refuses the snapshot.
5956                None => None,
5957            }
5958        } else {
5959            None
5960        };
5961        let machine = crate::machine::MachineDescription::of(guest.config());
5962        // A status reports the guest's own mask of a thread Detcore holds
5963        // under a private blocking mask, which that thread published to the
5964        // scheduler; the kernel's `SigBlk` is Detcore's mask (Codex review of
5965        // R2b-2 stage 2, P2; https://github.com/rrnewton/hermit/issues/4273).
5966        // Masks are published only where the scheduler models signal targets.
5967        let mask_thread = guest.thread_state().with_detfd(call.fd(), |detfd| {
5968            detfd.procfs_status_mask_thread(&contents)
5969        })?;
5970        let published_sigblk = match mask_thread {
5971            Some(thread) if crate::scheduler::discarded_at_send::records(guest.config()) => {
5972                crate::tool_global::published_guest_sigmask(guest, DetTid::from_raw(thread)).await
5973            }
5974            _ => None,
5975        };
5976        guest.thread_state().with_detfd(call.fd(), |detfd| {
5977            detfd.initialize_procfs(
5978                contents.clone(),
5979                ProcfsSnapshotContext {
5980                    mapping_identities: mapping_identities.clone(),
5981                    mountinfo: mountinfo.clone(),
5982                    virtual_uptime_seconds,
5983                    virtual_boot_time_seconds,
5984                    virtual_realtime_seconds,
5985                    virtual_pid,
5986                    virtual_ppid,
5987                    virtual_pty_count,
5988                    fdinfo_identity,
5989                    random_uuid,
5990                    virtual_cpuinfo: virtual_cpuinfo.clone(),
5991                    machine: machine.clone(),
5992                    published_sigblk,
5993                    lock_rows_kept: lock_rows_kept.clone(),
5994                },
5995            );
5996        })?;
5997        Ok(())
5998    }
5999
6000    /// The bytes of the procfs file open as `fd`, if it is a process's
6001    /// `mountinfo` or `mounts` and the run has a container mount table
6002    /// (`Config::container_mount_table`): the table's `mountinfo`, with raw
6003    /// identities that the snapshot then numbers as it numbers the kernel's,
6004    /// or its `mounts`. Wherever the file was opened from: rendered by Detcore,
6005    /// or opened by the kernel (under record and replay, through a spelling
6006    /// Detcore does not resolve, on a backend's own procfs), except one the
6007    /// kernel opened after the process it names changed its root, whose view
6008    /// the kernel decides (`chroot` keeps the kernel's path, as for every
6009    /// rendered file). `None` for every other file.
6010    fn mount_table_snapshot<G: Guest<Self>>(
6011        &self,
6012        guest: &G,
6013        fd: RawFd,
6014    ) -> Result<Option<Vec<u8>>, Errno> {
6015        let Some(table) = guest.config().container_mount_table.as_ref() else {
6016            return Ok(None);
6017        };
6018        let (rendering, rendered, pinned) = guest.thread_state().with_detfd(fd, |detfd| {
6019            (
6020                detfd.procfs_mount_table_rendering(),
6021                detfd.procfs_rendered_path().is_some(),
6022                detfd.procfs_pinned_mount_view(),
6023            )
6024        })?;
6025        let Some(rendering) = rendering else {
6026            return Ok(None);
6027        };
6028        // A rendered file is the table, as its open decided. A file the kernel
6029        // opened reads the view its open pinned; one nothing pinned (a
6030        // descriptor Detcore learned of otherwise), the reader's.
6031        let kernel_view = !rendered
6032            && pinned.unwrap_or_else(|| {
6033                guest
6034                    .thread_state()
6035                    .changed_root
6036                    .load(std::sync::atomic::Ordering::SeqCst)
6037            });
6038        if kernel_view {
6039            return Ok(None);
6040        }
6041        Ok(Some(match rendering {
6042            crate::procfs::MountTableRendering::Mountinfo => table.mountinfo(),
6043            crate::procfs::MountTableRendering::Mounts => {
6044                table.mounts(&guest.config().mountinfo_root_rewrites)
6045            }
6046        }))
6047    }
6048
6049    /// Whether the process's `mountinfo` or `mounts` the kernel opened as
6050    /// `file` reads the kernel's view: the task the path names has a changed
6051    /// root (`tool_global::root_changed`, which follows filesystem groups
6052    /// shared through CLONE_FS), or Detcore cannot tell which task it names.
6053    /// As on Linux, where `mounts_open_common` takes the target task's root,
6054    /// the reader's own root does not decide it. The kernel's view is
6055    /// Linux's own answer for whatever task the path names, so it is the
6056    /// answer whenever the task is unknown: never the launch table.
6057    async fn mount_view_is_kernel<G: Guest<Self>>(&self, guest: &mut G, file: &ProcfsFile) -> bool {
6058        // In a nested PID namespace the path's numbers are that namespace's
6059        // (a child that kept a `/proc` directory descriptor across
6060        // CLONE_NEWPID and opens `self/mountinfo` through it, for one), and
6061        // Detcore does not map them here.
6062        let Some((pid, tid)) = self.procfs_caller_ids(guest) else {
6063            return true;
6064        };
6065        let mut bound = file.clone();
6066        bound.bind_task(pid, tid);
6067        match bound.bound_task() {
6068            Some(task) => {
6069                crate::tool_global::root_changed(
6070                    guest,
6071                    detcore_model::pid::DetPid::from_raw(task.thread.unwrap_or(task.process)),
6072                )
6073                .await
6074            }
6075            None => true,
6076        }
6077    }
6078
6079    /// The raw mount ID a file on mount `raw_mount_id` reports to the guest:
6080    /// with a container mount table, and until the process changes its root,
6081    /// a hidden mount's nearest shown ancestor
6082    /// (`ContainerMountTable::shown_mount_id`); otherwise the mount itself.
6083    pub(crate) fn shown_mount_id<G: Guest<Self>>(&self, guest: &G, raw_mount_id: u64) -> u64 {
6084        match guest.config().container_mount_table.as_ref() {
6085            Some(table)
6086                if !guest
6087                    .thread_state()
6088                    .changed_root
6089                    .load(std::sync::atomic::Ordering::SeqCst) =>
6090            {
6091                table.shown_mount_id(raw_mount_id)
6092            }
6093            _ => raw_mount_id,
6094        }
6095    }
6096
6097    /// Write `stat`, a procfs file Detcore renders, as `statx`'s result, with
6098    /// the guest's procfs mount's ID, as its fdinfo `mnt_id` shows it.
6099    async fn write_rendered_statx<G: Guest<Self>>(
6100        &self,
6101        guest: &mut G,
6102        call: syscalls::Statx,
6103        stat: DetStat,
6104    ) -> Result<i64, Error> {
6105        let statptr = call.statx().ok_or(Errno::EFAULT)?;
6106        let mut statx: libc::statx = stat.into();
6107        let raw_mount_id = rendered_procfs::guest_procfs_mount_id().ok();
6108        let unique = statx_requested_mask(call) & STATX_MNT_ID_UNIQUE != 0;
6109        self.fill_statx_mount_id(guest, &mut statx, raw_mount_id, unique)
6110            .await;
6111        guest.memory().write_value(statptr.0, &statx)?;
6112        Ok(0)
6113    }
6114
6115    // TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/issues/4213):
6116    // Review STATX_MNT_ID numbered as fdinfo's mnt_id, a hidden mount's file
6117    // reporting its nearest shown ancestor.
6118    /// Fill `statx`'s mount ID for a file on mount `raw_mount_id` (a classic
6119    /// ID), as Linux fills it whether or not the caller asked for it
6120    /// (`vfs_statx_path`, v6.12 fs/stat.c:248-259): the number its fdinfo
6121    /// `mnt_id` and its `mountinfo` row show, through the run's mount-ID
6122    /// pool, a hidden mount's file showing its nearest shown ancestor's
6123    /// ([`Self::shown_mount_id`]), with `STATX_MNT_ID`. If the caller asked
6124    /// for `STATX_MNT_ID_UNIQUE` (`unique`), Linux reports the mount's unique
6125    /// ID and that bit instead; here that is the same number plus
6126    /// [`MNT_UNIQUE_ID_OFFSET`], which is above every classic ID, the same
6127    /// for every file of the mount, different for every other mount, and
6128    /// the first valid unique ID for the first mount numbered. Where there is
6129    /// no such number (no mount provenance to number it by, outside Hermit's
6130    /// container, or no mount ID from the kernel), the field is 0 and both
6131    /// mask bits are cleared, so no caller reads a number that names nothing.
6132    ///
6133    /// Where this differs from Linux: the pool is keyed by classic IDs, which
6134    /// Linux can give a new mount after an unmount (an IDA), while a unique
6135    /// ID is never reused. A mount made after another's unmount, on the
6136    /// freed classic ID, shows that mount's unique ID here too.
6137    async fn fill_statx_mount_id<G: Guest<Self>>(
6138        &self,
6139        guest: &mut G,
6140        statx: &mut libc::statx,
6141        raw_mount_id: Option<u64>,
6142        unique: bool,
6143    ) {
6144        let guest_mount_id = match raw_mount_id {
6145            Some(raw_mount_id) if guest.config().mountinfo_mount_ids_captured => {
6146                let raw_mount_id = self.shown_mount_id(guest, raw_mount_id);
6147                determinize_mount_id(guest, raw_mount_id, None).await
6148            }
6149            _ => None,
6150        };
6151        let reported = match guest_mount_id {
6152            Some(id) if unique => id
6153                .checked_add(MNT_UNIQUE_ID_OFFSET)
6154                .map(|id| (id, STATX_MNT_ID_UNIQUE)),
6155            Some(id) => Some((id, libc::STATX_MNT_ID)),
6156            None => None,
6157        };
6158        statx.stx_mask &= !(libc::STATX_MNT_ID | STATX_MNT_ID_UNIQUE);
6159        match reported {
6160            Some((id, bit)) => {
6161                statx.stx_mnt_id = id;
6162                statx.stx_mask |= bit;
6163            }
6164            None => statx.stx_mnt_id = 0,
6165        }
6166    }
6167
6168    /// SYS_read system call (MAYHANG).
6169    pub async fn handle_read<G: Guest<Self>>(
6170        &self,
6171        guest: &mut G,
6172        call: syscalls::Read,
6173    ) -> Result<i64, Error> {
6174        if self.timer_slack_binding(guest, call.fd())?.is_some() {
6175            return self
6176                .read_timer_slack(guest, call.fd(), call.buf(), call.len())
6177                .await;
6178        }
6179
6180        if call.len() == 0 {
6181            if let Ok(Some(status_flags)) = guest.thread_state().with_detfd(call.fd(), |detfd| {
6182                (detfd.ty() == FdType::Rng).then(|| detfd.status_flags())
6183            }) {
6184                // Replay reserves random-device fd slots with eventfds. A
6185                // physical zero-length read of that placeholder returns EINVAL
6186                // even though the logical random-device read must return zero.
6187                require_random_device_read_access(status_flags)?;
6188                let limit =
6189                    crate::iovecs::UserAddressLimit::from_query(guest.user_address_limit())?;
6190                // vfs_read still checks access_ok for a zero-length buffer:
6191                // NULL is valid, but an address beyond TASK_SIZE is EFAULT.
6192                limit.validate(&[crate::iovecs::ImportedIovec {
6193                    base: call.buf().map_or(0, |address| address.as_raw()),
6194                    len: 0,
6195                }])?;
6196                return Ok(0);
6197            }
6198            // A zero-count read transfers nothing on a file or stream, but on a
6199            // datagram or SEQPACKET socket it consumes a pending message. Its
6200            // result goes through record/replay: a replayed descriptor may be
6201            // a placeholder whose own zero-count read fails differently.
6202            // AUTONOMOUS-BOT-IMPLEMENTED
6203            // TODO-HUMAN-REVIEW(PR-3601)
6204            return self
6205                .record_or_replay_preserving_tool_errors(guest, call)
6206                .await;
6207        }
6208
6209        let (needs_procfs_snapshot, serves_procfs_snapshot, cannot_read) =
6210            guest.thread_state().with_detfd(call.fd(), |detfd| {
6211                (
6212                    detfd.procfs_needs_snapshot(),
6213                    detfd.procfs_serves_snapshot(),
6214                    !can_read(detfd.status_flags()),
6215                )
6216            })?;
6217        // A descriptor that cannot read (`O_PATH`, write-only, access mode 3)
6218        // reads nothing (EBADF), before its buffer is looked at, as Linux's
6219        // `vfs_read` checks, whether or not a rendered file's snapshot is
6220        // taken yet (`/proc/uptime`'s is taken at its first read).
6221        if serves_procfs_snapshot && cannot_read {
6222            return Err(Errno::EBADF.into());
6223        }
6224        if serves_procfs_snapshot {
6225            validate_procfs_destination(
6226                || crate::iovecs::UserAddressLimit::from_query(guest.user_address_limit()),
6227                call.buf(),
6228                call.len(),
6229            )?;
6230        }
6231        if needs_procfs_snapshot {
6232            self.initialize_procfs_snapshot(guest, call).await?;
6233        }
6234
6235        self.adopt_rendered_procfs_position(guest, call.fd())
6236            .await?;
6237        // Like a seq_file read, advance the shared cursor only by the bytes
6238        // actually copied: a read that faults before copying anything leaves
6239        // it where it was.
6240        let procfs_preview = guest
6241            .thread_state()
6242            .with_detfd(call.fd(), |detfd| detfd.preview_procfs(call.len()))?;
6243        if let Some((offset, bytes)) = procfs_preview {
6244            let faults_on_a_short_copy = guest
6245                .thread_state()
6246                .with_detfd(call.fd(), |detfd| detfd.procfs_faults_on_a_short_copy())?;
6247            let copied = copy_procfs_read(
6248                &mut guest.memory(),
6249                call.buf(),
6250                &bytes,
6251                faults_on_a_short_copy,
6252            )?;
6253            guest.thread_state().with_detfd(call.fd(), |detfd| {
6254                detfd.commit_procfs_read(offset, copied);
6255            })?;
6256            self.sync_rendered_procfs_position(guest, call.fd()).await?;
6257            return Ok(copied as i64);
6258        }
6259
6260        self.fifo_polls_if_a_guest_holds_its_peer(guest, call.fd(), FifoPeer::Writer)
6261            .await;
6262        let (fd_type, physically_nonblocking, logically_nonblocking, resource, descriptor) =
6263            guest.thread_state_mut().with_detfd(call.fd(), |detfd| {
6264                (
6265                    detfd.ty(),
6266                    detfd.physically_nonblocking(),
6267                    detfd.is_nonblocking(),
6268                    detfd.resource(),
6269                    detfd.clone(),
6270                )
6271            })?;
6272
6273        if let Some(resource) = resource {
6274            let mut request = guest.thread_state().mk_request(resource, Permission::R);
6275            if should_tag_host_timed_internal_pipe_io(
6276                guest.config().backend.internal_pipe_turns_are_host_timed,
6277                fd_type,
6278                physically_nonblocking,
6279                logically_nonblocking,
6280            ) {
6281                request.fyi(HOST_TIMED_INTERNAL_PIPE_IO_FYI);
6282            }
6283            resource_request(guest, request).await;
6284        }
6285
6286        let res = match fd_type {
6287            FdType::Rng => {
6288                trace!("Read call RNG fd {}, simulating...", call.fd());
6289                let status_flags = descriptor.status_flags();
6290                descriptor
6291                    .with_random_device_stream(|offset| {
6292                        require_random_device_read_access(status_flags)?;
6293                        let remote_buf = call.buf().ok_or(Errno::EFAULT)?;
6294                        self.fill_random_device_bytes(guest, remote_buf, call.len(), offset)
6295                    })
6296                    .map(|n| n as i64)
6297            }
6298            FdType::Regular | FdType::Pipe if descriptor.inherited_external_read().is_some() => {
6299                // An authenticated controller input or terminal can block
6300                // after this Device grant.
6301                // Announce one external kernel read even when our cached flags
6302                // say nonblocking: a fork/exec peer can change the shared OFD's
6303                // flags while the process-local model remains stale (the
6304                // pre-existing https://github.com/rrnewton/hermit/issues/3520).
6305                // The kernel keeps its actual O_NONBLOCK semantics, including
6306                // immediate EAGAIN. Never fill an external short read to len.
6307                self.record_or_replay_blocking(guest, call.into()).await
6308            }
6309            FdType::Regular => {
6310                if guest.config().deterministic_io {
6311                    self.deterministic_read(guest, call).await
6312                } else {
6313                    Ok(self.record_or_replay(guest, call).await?)
6314                }
6315            }
6316            FdType::Signalfd
6317                if call.len() >= 2 * crate::syscalls::signal::SIGNALFD_RECORD
6318                    && self.signalfd_reads_per_record(guest, call.fd()).await =>
6319            {
6320                self.read_signalfd_per_record(guest, call).await
6321            }
6322            FdType::Signalfd => self.read_signalfd(guest, call, true).await,
6323            FdType::Timerfd => {
6324                trace!("Possibly blocking read call on timerfd {}", call.fd());
6325                // Expirations up to this thread's virtual now make the host
6326                // descriptor readable before a nonblocking read's one attempt;
6327                // a blocking read's retries publish again at each turn.
6328                crate::syscalls::timerfd::publish_expired(guest).await;
6329                let result = self.execute_nonblockable_fd_syscall(guest, call).await;
6330                crate::syscalls::timerfd::finish_read(guest, call.fd(), call.buf(), result)
6331            }
6332            FdType::Eventfd | FdType::Inotify => {
6333                trace!(
6334                    "Possibly blocking read call on notification fd {}, type {:?}",
6335                    call.fd(),
6336                    fd_type
6337                );
6338                self.execute_nonblockable_fd_syscall(guest, call).await
6339            }
6340            FdType::Memfd | FdType::Pidfd | FdType::Userfaultfd | FdType::Epoll => {
6341                trace!("Read call on unusual fd {}, type {:?}", call.fd(), fd_type);
6342                Ok(self.record_or_replay(guest, call).await?)
6343            }
6344
6345            FdType::Socket | FdType::Pipe => {
6346                trace!(
6347                    "Possibly blocking read call on {:?} fd {}",
6348                    fd_type,
6349                    call.fd()
6350                );
6351                self.execute_nonblockable_fd_syscall(guest, call).await
6352            }
6353        };
6354        // O2: a signalfd read (even one that faulted copying out a record
6355        // it had already dequeued) may have taken the process's ITIMER_REAL
6356        // copy (https://github.com/rrnewton/hermit/issues/4139).
6357        if fd_type == FdType::Signalfd {
6358            crate::tool_global::reconcile_alarm(guest).await;
6359        }
6360        resource_release_all(guest).await;
6361        res
6362    }
6363
6364    /// One read of signalfd `call`, as the kernel answers it, with each
6365    /// record put through the child-exit ledger and the discarded-at-send
6366    /// record (`reconcile_signalfd_records`). A read whose every record was
6367    /// dropped reads again if `may_read_again`, as if those copies had never
6368    /// been queued; otherwise it answers 0.
6369    async fn read_signalfd<G: Guest<Self>>(
6370        &self,
6371        guest: &mut G,
6372        call: syscalls::Read,
6373        may_read_again: bool,
6374    ) -> Result<i64, Error> {
6375        loop {
6376            trace!("Possibly blocking read call on signalfd {}", call.fd());
6377            let extents = [(call.buf().map_or(0, |buf| buf.as_raw()), call.len())];
6378            let before =
6379                crate::syscalls::signal::capture_signalfd_buffer(guest, &extents, call.len());
6380            let result = self.execute_nonblockable_fd_syscall(guest, call).await;
6381            // A SIGCHLD read here goes through the child-exit ledger as
6382            // one delivered to a handler does. A read whose every record
6383            // was a dropped duplicate reads again, as if those copies had
6384            // never been queued.
6385            match (result, call.buf()) {
6386                (Ok(read), Some(buf))
6387                    if read > 0 && self.cfg.backend.reports_child_exit_publication =>
6388                {
6389                    let Some(kept) = self
6390                        .reconcile_signalfd_records(guest, buf, read as usize, &before)
6391                        .await
6392                    else {
6393                        break self
6394                            .refuse_unrestorable_signalfd_record(guest, Sysno::read)
6395                            .await;
6396                    };
6397                    if self
6398                        .settle_faulted_signalfd_record(
6399                            guest,
6400                            call.fd(),
6401                            &extents,
6402                            Some(read as usize),
6403                        )
6404                        .await
6405                    {
6406                        break self
6407                            .refuse_faulted_signalfd_discard(guest, Sysno::read)
6408                            .await;
6409                    }
6410                    if kept > 0 {
6411                        break Ok(kept as i64);
6412                    }
6413                    if !may_read_again {
6414                        break Ok(0);
6415                    }
6416                }
6417                (Err(Error::Errno(Errno::EFAULT)), _) => {
6418                    if self
6419                        .settle_faulted_signalfd_record(guest, call.fd(), &extents, None)
6420                        .await
6421                    {
6422                        break self
6423                            .refuse_faulted_signalfd_discard(guest, Sysno::read)
6424                            .await;
6425                    }
6426                    break Err(Errno::EFAULT.into());
6427                }
6428                (result, _) => break result,
6429            }
6430        }
6431    }
6432
6433    /// Whether a signalfd read of `fd` takes one record per kernel read
6434    /// (4262 design §4.4): some signal it covers has an entry behind the
6435    /// front of its list, or a stale timer entry, in the calling thread's or
6436    /// its process's queue. A read must then dequeue one record at a time:
6437    /// sending a list's next entry before the next record, as Linux's
6438    /// `signalfd_dequeue` loop takes them in its order, and refilling the slot
6439    /// of a stale record it drops, as Linux skips such an entry inside the
6440    /// dequeue. With only single valid entries, every entry is physically
6441    /// queued and none is dropped, so one kernel read returns what Linux
6442    /// returns, in count and in order.
6443    async fn signalfd_reads_per_record<G: Guest<Self>>(&self, guest: &mut G, fd: i32) -> bool {
6444        use crate::scheduler::discarded_at_send::DiscardedSignalAnswer;
6445        use crate::scheduler::discarded_at_send::DiscardedSignalControl;
6446        if !crate::scheduler::discarded_at_send::records(guest.config()) {
6447            return false;
6448        }
6449        let Some(mask) = crate::syscalls::signal::signalfd_mask(guest.pid().as_raw(), fd) else {
6450            return false;
6451        };
6452        matches!(
6453            crate::tool_global::discarded_signal(guest, DiscardedSignalControl::Queued).await,
6454            DiscardedSignalAnswer::Bits { thread, process } if (thread | process) & mask != 0
6455        )
6456    }
6457
6458    /// A signalfd read taken one record at a time
6459    /// (`signalfd_reads_per_record`): the first record's read may block, as
6460    /// the call would; each later one is read only while a signal the
6461    /// descriptor covers is pending, so it never blocks (fs/signalfd.c reads
6462    /// later records without waiting). A fault after k records returns
6463    /// k records, as the kernel's copy-out does.
6464    async fn read_signalfd_per_record<G: Guest<Self>>(
6465        &self,
6466        guest: &mut G,
6467        call: syscalls::Read,
6468    ) -> Result<i64, Error> {
6469        const RECORD: usize = crate::syscalls::signal::SIGNALFD_RECORD;
6470        let Some(buf) = call.buf() else {
6471            return self.read_signalfd(guest, call, true).await;
6472        };
6473        let mask = crate::syscalls::signal::signalfd_mask(guest.pid().as_raw(), call.fd());
6474        let mut done = 0usize;
6475        // A read whose records were all dropped (stale timer entries) frees
6476        // its slot. Each such read dequeued a physical record and popped its
6477        // entry, and the lists are finite, so the refills end without a cap
6478        // (the Codex re-review of
6479        // https://github.com/rrnewton/hermit/pull/4491, P2: 80 stale entries).
6480        while done + RECORD <= call.len() {
6481            if done > 0 {
6482                let pending =
6483                    crate::syscalls::threads::read_kernel_signal_state(guest.pid(), guest.tid())
6484                        .map(|state| state.thread_pending | state.shared_pending)
6485                        .unwrap_or(0);
6486                if mask.is_none_or(|mask| pending & mask == 0) {
6487                    break;
6488                }
6489            }
6490            // A guest address, never dereferenced here.
6491            let at = AddrMut::<u8>::from_raw(buf.as_raw() + done);
6492            let record = syscalls::Read::new()
6493                .with_fd(call.fd())
6494                .with_buf(at)
6495                .with_len(RECORD);
6496            match self.read_signalfd(guest, record, done == 0).await {
6497                Ok(read) if read > 0 => done += read as usize,
6498                Ok(read) if done == 0 => return Ok(read),
6499                // Linux skips a stale entry inside the dequeue and fills the
6500                // slot with the next pending signal (the Claude review of
6501                // https://github.com/rrnewton/hermit/pull/4491, P2-1).
6502                Ok(_) => {}
6503                Err(error) if done == 0 => return Err(error),
6504                Err(_) => break,
6505            }
6506        }
6507        Ok(done as i64)
6508    }
6509
6510    /// SYS_pread64 system call.
6511    pub async fn handle_pread64<G: Guest<Self>>(
6512        &self,
6513        guest: &mut G,
6514        call: syscalls::Pread64,
6515    ) -> Result<i64, Error> {
6516        if self.timer_slack_binding(guest, call.fd())?.is_some() {
6517            return self
6518                .pread_timer_slack(guest, call.fd(), call.buf(), call.len(), call.offset())
6519                .await;
6520        }
6521
6522        if call.len() == 0 {
6523            // As for read, a zero-count pread's result goes through
6524            // record/replay.
6525            // AUTONOMOUS-BOT-IMPLEMENTED
6526            // TODO-HUMAN-REVIEW(PR-3601)
6527            return self
6528                .record_or_replay_preserving_tool_errors(guest, call)
6529                .await;
6530        }
6531
6532        let offset = usize::try_from(call.offset()).map_err(|_| Errno::EINVAL)?;
6533        let (needs_procfs_snapshot, serves_procfs_snapshot, cannot_read) =
6534            guest.thread_state().with_detfd(call.fd(), |detfd| {
6535                (
6536                    detfd.procfs_needs_snapshot(),
6537                    detfd.procfs_serves_snapshot(),
6538                    !can_read(detfd.status_flags()),
6539                )
6540            })?;
6541        // A descriptor that cannot read (`O_PATH`, write-only, access mode 3)
6542        // reads nothing (EBADF), before its buffer is looked at, as Linux's
6543        // `vfs_read` checks, whether or not a rendered file's snapshot is
6544        // taken yet (`/proc/uptime`'s is taken at its first read).
6545        if serves_procfs_snapshot && cannot_read {
6546            return Err(Errno::EBADF.into());
6547        }
6548        if serves_procfs_snapshot {
6549            validate_procfs_destination(
6550                || crate::iovecs::UserAddressLimit::from_query(guest.user_address_limit()),
6551                call.buf(),
6552                call.len(),
6553            )?;
6554        }
6555        if needs_procfs_snapshot {
6556            let read = syscalls::Read::new()
6557                .with_fd(call.fd())
6558                .with_buf(call.buf())
6559                .with_len(call.len());
6560            self.initialize_procfs_snapshot(guest, read).await?;
6561        } else if serves_procfs_snapshot
6562            && guest.thread_state().with_detfd(call.fd(), |detfd| {
6563                detfd
6564                    .procfs_position()
6565                    .is_some_and(|(position, _)| position != offset)
6566            })?
6567        {
6568            // A read at a position the buffered snapshot does not start at
6569            // runs a per-process file's `show` again (`traverse`).
6570            self.require_rendered_task(guest, call.fd()).await?;
6571        }
6572
6573        let procfs_bytes = guest
6574            .thread_state()
6575            .with_detfd(call.fd(), |detfd| detfd.take_procfs_at(offset, call.len()))?;
6576        if let Some(bytes) = procfs_bytes {
6577            let faults_on_a_short_copy = guest
6578                .thread_state()
6579                .with_detfd(call.fd(), |detfd| detfd.procfs_faults_on_a_short_copy())?;
6580            let copied = copy_procfs_read(
6581                &mut guest.memory(),
6582                call.buf(),
6583                &bytes,
6584                faults_on_a_short_copy,
6585            )?;
6586            return Ok(copied as i64);
6587        }
6588
6589        let (fd_type, resource) = guest
6590            .thread_state_mut()
6591            .with_detfd(call.fd(), |detfd| (detfd.ty(), detfd.resource()))?;
6592
6593        if let Some(resource) = resource {
6594            let request = guest.thread_state().mk_request(resource, Permission::R);
6595            resource_request(guest, request).await;
6596        }
6597
6598        let res = match fd_type {
6599            FdType::Rng => (|| -> Result<i64, Error> {
6600                trace!("Pread64 call RNG fd {}, simulating...", call.fd());
6601                let remote_buf = call.buf().ok_or(Errno::EFAULT)?;
6602                let n =
6603                    self.fill_random_device_bytes(guest, remote_buf, call.len(), offset as u64)?;
6604                Ok(n as i64)
6605            })(),
6606            FdType::Regular if guest.config().deterministic_io => {
6607                self.deterministic_pread64(guest, call).await
6608            }
6609            _ => match self.record_or_replay(guest, call).await {
6610                Ok(value) => Ok(value),
6611                Err(error) => Err(error.into()),
6612            },
6613        };
6614
6615        resource_release_all(guest).await;
6616        res
6617    }
6618
6619    /// Whether `fd`, whose open recorded the host stat `cached`, is a
6620    /// directory that is not on procfs (see [`Self::handle_lseek`]). procfs
6621    /// keeps the host's seek behavior, as it keeps the host's sizes. A
6622    /// descriptor's type and device never change, so the stat its open took
6623    /// answers without another `fstat` (Claude re-check of
6624    /// https://github.com/rrnewton/hermit/pull/4369). Its block size can (a
6625    /// FUSE server reports it), so it only rules procfs out: the kernel's
6626    /// procfs always has 1024-byte blocks, and a directory that may be procfs
6627    /// is proved so by naming its entry, as a stat does, and KVM's by its
6628    /// device ([`procfs_inode::is_backend_procfs_device`]). Under DBT, where
6629    /// Detcore names no entries, one with procfs's stat fields keeps the
6630    /// host's seek unproved ([`procfs_inode::unprovable_procfs_signature`]).
6631    /// With metadata virtualized every descriptor the guest opened has a stat;
6632    /// those without are Detcore's own pipes and sockets.
6633    async fn is_seekable_directory<G: Guest<Self>>(
6634        guest: &mut G,
6635        fd: RawFd,
6636        cached: Option<DetStat>,
6637    ) -> bool {
6638        let Some(stat) = cached.filter(|stat| stat.mode & libc::S_IFMT == libc::S_IFDIR) else {
6639            return false;
6640        };
6641        if procfs_inode::is_backend_procfs_device(&guest.config().backend, stat.dev, stat.blksize)
6642            || procfs_inode::unprovable_procfs_signature(
6643                &guest.config().backend,
6644                guest.thread_state().physical_tid,
6645                stat.dev,
6646                stat.blksize,
6647            )
6648        {
6649            return false;
6650        }
6651        !Self::procfs_entry(guest, &stat, StatTarget::Descriptor(fd))
6652            .await
6653            .is_procfs()
6654    }
6655
6656    /// SYS_lseek system call.
6657    pub async fn handle_lseek<G: Guest<Self>>(
6658        &self,
6659        guest: &mut G,
6660        call: syscalls::Lseek,
6661    ) -> Result<i64, Error> {
6662        let timer_slack_binding = self.timer_slack_binding(guest, call.fd())?;
6663        // A seek must not move the position under a `getdents` that is
6664        // reading or serving this open file's directory.
6665        let directory_lock = guest
6666            .thread_state()
6667            .with_detfd(call.fd(), |detfd| detfd.directory_lock())?;
6668        let _seeking = directory_lock.lock().await;
6669        self.adopt_rendered_procfs_position(guest, call.fd())
6670            .await?;
6671        let (fd_type, status_flags, procfs_position, resource, directory_stream, host_order) =
6672            guest.thread_state().with_detfd(call.fd(), |detfd| {
6673                (
6674                    detfd.ty(),
6675                    detfd.status_flags(),
6676                    detfd.procfs_position(),
6677                    detfd.resource(),
6678                    detfd.has_directory_stream(),
6679                    detfd.directory_in_host_order(),
6680                )
6681            })?;
6682        if fd_type == FdType::Rng {
6683            return random_device_lseek_result(status_flags, call.whence()).map_err(Into::into);
6684        }
6685        if is_inherited_container_output(resource) {
6686            return Err(Errno::ESPIPE.into());
6687        }
6688        if timer_slack_binding.is_some() && status_flags & libc::O_PATH != 0 {
6689            return Err(Errno::EBADF.into());
6690        }
6691        if directory_stream {
6692            // Positions in a sorted directory stream are entry indices (see
6693            // `DirectoryStream`), not host cookies. The kernel position only
6694            // follows the stream, for descriptors Detcore does not track. Like
6695            // tmpfs's `dcache_dir_lseek`, only SEEK_SET and SEEK_CUR are
6696            // accepted; SEEK_END, SEEK_DATA and SEEK_HOLE get `EINVAL`, where
6697            // ext4 and btrfs accept SEEK_END
6698            // (https://github.com/rrnewton/hermit/issues/3724).
6699            let current = guest.thread_state().with_detfd(call.fd(), |detfd| {
6700                detfd.with_directory_stream(|stream| stream.position())
6701            })??;
6702            let requested = i128::from(call.offset());
6703            let position = match call.whence() {
6704                Whence::SEEK_SET => requested,
6705                Whence::SEEK_CUR => i128::from(current) + requested,
6706                _ => return Err(Errno::EINVAL.into()),
6707            };
6708            let result = i64::try_from(position)
6709                .ok()
6710                .filter(|position| *position >= 0)
6711                .ok_or(Errno::EINVAL)?;
6712            let target = guest.thread_state().with_detfd(call.fd(), |detfd| {
6713                detfd.with_directory_stream(|stream| {
6714                    stream.seek(result as u64);
6715                    stream.kernel_target()
6716                })
6717            })??;
6718            self.move_directory_kernel_position(guest, call.fd() as RawFd, target)
6719                .await;
6720            return Ok(result);
6721        }
6722        let Some((current, snapshot_len)) = procfs_position else {
6723            // A directory without a stream yet: SEEK_END would return the
6724            // host directory's size, which st_size no longer reports and
6725            // which changes as anything outside the run adds or removes an
6726            // entry (https://github.com/rrnewton/hermit/issues/4372). Answer
6727            // as a stream does (above, tmpfs's `dcache_dir_lseek`), from the
6728            // descriptor's first use. An `O_PATH` descriptor goes on to the
6729            // kernel, which refuses its seek with EBADF whatever the whence.
6730            if guest.config().virtualize_metadata
6731                && status_flags & libc::O_PATH == 0
6732                && matches!(
6733                    call.whence(),
6734                    Whence::SEEK_END | Whence::SEEK_DATA | Whence::SEEK_HOLE
6735                )
6736            {
6737                let cached = guest
6738                    .thread_state()
6739                    .with_detfd(call.fd(), |detfd| detfd.stat())?;
6740                if Self::is_seekable_directory(guest, call.fd(), cached).await {
6741                    return Err(Errno::EINVAL.into());
6742                }
6743            }
6744            // AUTONOMOUS-BOT-IMPLEMENTED
6745            // TODO-HUMAN-REVIEW(#1044): Regular-file lseek must
6746            // flow through record_or_replay, exactly as handle_read does for
6747            // FdType::Regular. Injecting the seek live here is correct for run
6748            // and --verify (the inner NoopTool just re-injects), but under
6749            // record/replay the replay descriptor is a virtual placeholder
6750            // whose kernel position never advances (reads are served from the
6751            // log, not the file). A live SEEK_CUR then returned Ok(0) on replay
6752            // versus the recorded offset (e.g. glibc's __tzfile_read rewinds
6753            // /etc/localtime with lseek(fd, -N, SEEK_CUR)), diverging the
6754            // guest's control flow and desynchronizing the event stream. Routing
6755            // through record_or_replay records the offset once and substitutes
6756            // the recorded value on replay, keeping the two runs identical.
6757            let position = self.record_or_replay(guest, call).await?;
6758            if host_order && position == 0 {
6759                // Back at the start, the next `getdents` can read the whole
6760                // directory again and serve it as a sorted stream.
6761                guest
6762                    .thread_state()
6763                    .with_detfd(call.fd(), |detfd| detfd.use_directory_stream())?;
6764            }
6765            return Ok(position);
6766        };
6767
6768        if let Some(binding) = timer_slack_binding {
6769            // Linux exposes this file through seq_lseek, which accepts only
6770            // SEEK_SET and SEEK_CUR. Keep that position entirely in the
6771            // virtual open-file description even before the first read.
6772            let requested = i128::from(call.offset());
6773            let new_offset = match call.whence() {
6774                Whence::SEEK_SET => requested,
6775                Whence::SEEK_CUR => current as i128 + requested,
6776                _ => return Err(Errno::EINVAL.into()),
6777            };
6778            let new_offset = usize::try_from(new_offset).map_err(|_| Errno::EINVAL)?;
6779            let result = i64::try_from(new_offset).map_err(|_| Errno::EOVERFLOW)?;
6780            // seq_lseek does not call the show callback for a no-op or a reset
6781            // to zero. Only a traversal to another positive position observes
6782            // the target task and therefore performs lifetime/access checks.
6783            if new_offset != 0 && new_offset != current {
6784                self.require_current_timer_slack_target(guest, binding)
6785                    .await?;
6786            }
6787            guest
6788                .thread_state()
6789                .with_detfd(call.fd(), |detfd| detfd.set_procfs_offset(new_offset))?;
6790            return Ok(result);
6791        }
6792
6793        // A procfs file Detcore renders, whichever opened it: an `O_PATH`
6794        // descriptor has no position (EBADF), before the seek's arguments are
6795        // looked at; otherwise a sysctl file's `default_llseek` on a file of
6796        // size 0, whatever the snapshot holds, or a `seq_file`'s `seq_lseek`,
6797        // which seeks only from the start or the position.
6798        let files = self.rendered_files(guest);
6799        let rendered = guest
6800            .thread_state()
6801            .with_detfd(call.fd(), |detfd| detfd.procfs_renderable_path(files))?;
6802        if let Some(rendered) = rendered {
6803            if status_flags & libc::O_PATH != 0 {
6804                return Err(Errno::EBADF.into());
6805            }
6806            let seq_file = crate::procfs::rendered_path_is_seq_file(rendered);
6807            let requested = i128::from(call.offset());
6808            let new_offset = match call.whence() {
6809                Whence::SEEK_SET => requested,
6810                Whence::SEEK_CUR => current as i128 + requested,
6811                _ if seq_file => return Err(Errno::EINVAL.into()),
6812                Whence::SEEK_END => requested,
6813                // At or past the end, which is 0.
6814                Whence::SEEK_DATA | Whence::SEEK_HOLE if requested >= 0 => {
6815                    return Err(Errno::ENXIO.into());
6816                }
6817                Whence::SEEK_DATA | Whence::SEEK_HOLE => requested,
6818                _ => return Err(Errno::EINVAL.into()),
6819            };
6820            let new_offset = usize::try_from(new_offset).map_err(|_| Errno::EINVAL)?;
6821            let result = i64::try_from(new_offset).map_err(|_| Errno::EOVERFLOW)?;
6822            // seq_lseek to another positive position traverses the file,
6823            // which runs a per-process file's `show` (ESRCH once its task is
6824            // gone); a rewind or a no-op does not.
6825            if new_offset != 0 && new_offset != current {
6826                self.require_rendered_task(guest, call.fd()).await?;
6827            }
6828            guest
6829                .thread_state()
6830                .with_detfd(call.fd(), |detfd| detfd.seek_procfs(new_offset))?;
6831            self.sync_rendered_procfs_position(guest, call.fd()).await?;
6832            return Ok(result);
6833        }
6834
6835        let Some(snapshot_len) = snapshot_len else {
6836            let offset = guest.inject(Syscall::from(call)).await?;
6837            let offset = usize::try_from(offset).map_err(|_| Errno::EINVAL)?;
6838            guest
6839                .thread_state()
6840                .with_detfd(call.fd(), |detfd| detfd.set_procfs_offset(offset))?;
6841            return Ok(offset as i64);
6842        };
6843
6844        // A `seq_file` seeks only from the start or the position, before and
6845        // after the snapshot (`ProcfsFile::seeks_only_from_start_or_position`).
6846        let seq_file = guest.thread_state().with_detfd(call.fd(), |detfd| {
6847            detfd.procfs_seeks_only_from_start_or_position()
6848        })?;
6849        let requested = i128::from(call.offset());
6850        let new_offset = match call.whence() {
6851            Whence::SEEK_SET => requested,
6852            Whence::SEEK_CUR => current as i128 + requested,
6853            _ if seq_file => return Err(Errno::EINVAL.into()),
6854            Whence::SEEK_END => snapshot_len as i128 + requested,
6855            Whence::SEEK_DATA => {
6856                if requested < 0 || requested >= snapshot_len as i128 {
6857                    return Err(Errno::ENXIO.into());
6858                }
6859                requested
6860            }
6861            Whence::SEEK_HOLE => {
6862                if requested < 0 || requested >= snapshot_len as i128 {
6863                    return Err(Errno::ENXIO.into());
6864                }
6865                snapshot_len as i128
6866            }
6867            _ => return Err(Errno::EINVAL.into()),
6868        };
6869        let new_offset = usize::try_from(new_offset).map_err(|_| Errno::EINVAL)?;
6870        let result = i64::try_from(new_offset).map_err(|_| Errno::EOVERFLOW)?;
6871        guest
6872            .thread_state()
6873            .with_detfd(call.fd(), |detfd| detfd.set_procfs_offset(new_offset))?;
6874        self.sync_rendered_procfs_position(guest, call.fd()).await?;
6875        Ok(result)
6876    }
6877
6878    /// Helper for performing a deterministic read that retries until it gets all its
6879    /// bytes.
6880    // AUTONOMOUS-BOT-IMPLEMENTED
6881    // TODO-HUMAN-REVIEW(#689): Confirm partial reads take precedence over later errors.
6882    async fn deterministic_read<G: Guest<Self>>(
6883        &self,
6884        guest: &mut G,
6885        mut call: syscalls::Read,
6886    ) -> Result<i64, Error> {
6887        let mut total_read_bytes = 0;
6888        let mut remaining_buf = call.len();
6889
6890        trace!(
6891            "[detcore/det_io]: Requested read buffer size: {:?}",
6892            remaining_buf
6893        );
6894
6895        loop {
6896            match guest.inject_with_retry(call).await {
6897                Ok(res) => {
6898                    remaining_buf -= res as usize;
6899                    total_read_bytes += res;
6900
6901                    trace!(
6902                        "[detcore/det_io]: Remaining read buffer size: {:?}",
6903                        remaining_buf
6904                    );
6905
6906                    if res == 0 || remaining_buf == 0 {
6907                        break Ok(total_read_bytes);
6908                    }
6909
6910                    // Buf is guaranteed to exist as we already issued a syscall.
6911                    let old_ptr = call.buf().unwrap().as_raw();
6912                    call = call
6913                        .with_len(remaining_buf)
6914                        .with_buf(AddrMut::<u8>::from_raw(old_ptr + res as usize));
6915                }
6916                Err(error) if total_read_bytes > 0 => {
6917                    trace!("[detcore/det_io]: returning {total_read_bytes} bytes before {error}");
6918                    break Ok(total_read_bytes);
6919                }
6920                Err(error) => break Err(error.into()),
6921            }
6922        }
6923    }
6924
6925    /// Perform a positional read until the requested buffer is full or EOF is reached.
6926    async fn deterministic_pread64<G: Guest<Self>>(
6927        &self,
6928        guest: &mut G,
6929        mut call: syscalls::Pread64,
6930    ) -> Result<i64, Error> {
6931        let mut total_read_bytes = 0;
6932        let mut remaining_buf = call.len();
6933
6934        trace!(
6935            "[detcore/det_io]: Requested pread64 buffer size: {:?}",
6936            remaining_buf
6937        );
6938
6939        loop {
6940            match guest.inject_with_retry(call).await {
6941                Ok(res) => {
6942                    remaining_buf -= res as usize;
6943                    total_read_bytes += res;
6944
6945                    trace!(
6946                        "[detcore/det_io]: Remaining pread64 buffer size: {:?}",
6947                        remaining_buf
6948                    );
6949
6950                    if res == 0 || remaining_buf == 0 {
6951                        break Ok(total_read_bytes);
6952                    }
6953
6954                    let old_ptr = call
6955                        .buf()
6956                        .expect("successful pread64 requires a valid guest buffer")
6957                        .as_raw();
6958                    let offset = call.offset().checked_add(res).ok_or(Errno::EOVERFLOW)?;
6959                    call = call
6960                        .with_len(remaining_buf)
6961                        .with_buf(AddrMut::<u8>::from_raw(old_ptr + res as usize))
6962                        .with_offset(offset);
6963                }
6964                Err(error) => break Err(error.into()),
6965            }
6966        }
6967    }
6968
6969    // AUTONOMOUS-BOT-IMPLEMENTED
6970    // TODO-HUMAN-REVIEW(PR-838): Review regular-file sendfile mediation.
6971    /// Copy data between tracked regular files or memfds.
6972    ///
6973    /// The kernel advances the input offset (or the explicit offset pointer) and
6974    /// destination offset atomically with the copy. Detcore serializes destination
6975    /// writes while the strict scheduler orders the stable input read, and routes
6976    /// the syscall through record/replay so that the result and offset update stay
6977    /// ordered with other file operations. Socket and pipe destinations can block
6978    /// and need the nonblocking scheduler path; return ENOSYS for those endpoint
6979    /// types so libc/application fallbacks use Detcore's existing read/write
6980    /// handlers instead.
6981    pub async fn handle_sendfile<G: Guest<Self>>(
6982        &self,
6983        guest: &mut G,
6984        call: syscalls::Sendfile,
6985    ) -> Result<i64, Error> {
6986        let in_type = guest
6987            .thread_state()
6988            .with_detfd(call.in_fd(), |detfd| detfd.ty())?;
6989        let (out_type, out_resource, out_inode) =
6990            guest.thread_state().with_detfd(call.out_fd(), |detfd| {
6991                (
6992                    detfd.ty(),
6993                    detfd.resource(),
6994                    detfd.stat().map(|stat| stat.raw_inode()),
6995                )
6996            })?;
6997
6998        // AUTONOMOUS-BOT-IMPLEMENTED
6999        // TODO-HUMAN-REVIEW(PR-973): Refuse sendfile from a procfs input so it
7000        // cannot bypass the deterministic ProcfsFile snapshot. A procfs fd is
7001        // classified `FdType::Regular`, so it would otherwise pass the type
7002        // guard below and copy live kernel bytes straight to the output fd,
7003        // reintroducing the nondeterminism the mediated read()/write() path
7004        // sanitizes. Failing closed with ENOSYS makes callers fall back to
7005        // that mediated path (glibc's sendfile does exactly this).
7006        let in_is_procfs = guest
7007            .thread_state()
7008            .with_detfd(call.in_fd(), |detfd| detfd.procfs_position().is_some())?;
7009        if in_is_procfs {
7010            return Err(Errno::ENOSYS.into());
7011        }
7012
7013        if !matches!(in_type, FdType::Regular | FdType::Memfd)
7014            || !matches!(out_type, FdType::Regular | FdType::Memfd)
7015        {
7016            return Err(Errno::ENOSYS.into());
7017        }
7018
7019        let dettid = guest.thread_state().dettid;
7020        let mut resources = Resources::new(dettid);
7021        // `out_inode` is the fd's cached HOST inode, so it must be
7022        // determinized before naming a resource. It is deliberately left raw
7023        // for the `touch_file` call below, which takes a `RawInode`.
7024        let out_resource = match out_resource {
7025            Some(resource) => Some(resource),
7026            None => match out_inode {
7027                Some(raw_ino) => Some(ResourceID::FileContents(
7028                    determinize_inode(guest, raw_ino).await.0,
7029                )),
7030                None => None,
7031            },
7032        };
7033        if let Some(resource) = out_resource {
7034            resources.insert(resource, Permission::W);
7035        }
7036        resources.fyi("sendfile");
7037        resource_request(guest, resources).await;
7038
7039        let result = self
7040            .record_or_replay(guest, call)
7041            .await
7042            .map_err(Error::from);
7043        if guest.config().virtualize_metadata && matches!(&result, Ok(copied) if *copied > 0) {
7044            let inode = out_inode.expect("virtualized metadata requires stat data for sendfile");
7045            touch_file(guest, inode).await;
7046        }
7047        resource_release_all(guest).await;
7048        result
7049    }
7050
7051    /// SYS_write system call.
7052    pub async fn handle_write<G: Guest<Self>>(
7053        &self,
7054        guest: &mut G,
7055        mut call: syscalls::Write,
7056    ) -> Result<i64, Error> {
7057        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7058            return self
7059                .write_timer_slack(guest, call.fd(), call.buf(), call.len())
7060                .await;
7061        }
7062
7063        if call.len() > 0 {
7064            self.fifo_polls_if_a_guest_holds_its_peer(guest, call.fd(), FifoPeer::Reader)
7065                .await;
7066        }
7067        let (
7068            fd_type,
7069            physically_nonblocking,
7070            logically_nonblocking,
7071            open_file_id,
7072            resource,
7073            raw_ino,
7074        ) = guest.thread_state().with_detfd(call.fd(), |detfd| {
7075            (
7076                detfd.ty(),
7077                detfd.physically_nonblocking(),
7078                detfd.is_nonblocking(),
7079                detfd.open_file_id(),
7080                detfd.resource(),
7081                detfd.stat().map(|x| x.raw_inode()),
7082            )
7083        })?;
7084        // It doesn't matter much where the linearization point for this mtime bump falls:
7085        if guest.config().virtualize_metadata {
7086            let r =
7087                raw_ino.expect("Expect that when virtualize_metadata, DetFd's stat is populated!");
7088            touch_file(guest, r).await;
7089        }
7090
7091        if let Some(resource) = resource {
7092            let container_output = crate::sigalrm_phase1::is_container_output(&resource);
7093            let mut request = guest.thread_state().mk_request(resource, Permission::W);
7094            if should_tag_host_timed_internal_pipe_io(
7095                guest.config().backend.internal_pipe_turns_are_host_timed,
7096                fd_type,
7097                physically_nonblocking,
7098                logically_nonblocking,
7099            ) {
7100                request.fyi(HOST_TIMED_INTERNAL_PIPE_IO_FYI);
7101            }
7102            resource_request(guest, request).await;
7103            // Signal phase 1, design closure 1: a write to inherited stdout or
7104            // stderr may sleep with no scheduler admission. Once the grant is
7105            // taken no SIGALRM commits until this call ends, so one already due
7106            // is the only one it can strand: recorded as a determinism loss.
7107            if guest.thread_state().sigalrm_handled && container_output {
7108                sigalrm_refuses(guest, SigalrmControl::UnadmittedStdioIo).await;
7109            }
7110        }
7111
7112        // Only route writes through the nonblockable-fd path when the fd is actually
7113        // physically nonblocking. Detcore-created pipes are physically nonblocking in every
7114        // sequential mode, including record/replay, so their logically blocking writes use
7115        // the completion helper below. A physically blocking fd instead uses the original
7116        // synchronous path: treating an internal pipe as BlockingExternalIO would assume the
7117        // writer and reader were independent and could deadlock the scheduler.
7118        let res = if physically_nonblocking && fd_type == FdType::Pipe && !logically_nonblocking {
7119            self.execute_blocking_pipe_write(guest, call, open_file_id)
7120                .await
7121        } else if physically_nonblocking
7122            && matches!(fd_type, FdType::Socket | FdType::Pipe | FdType::Eventfd)
7123        {
7124            self.execute_nonblockable_fd_syscall(guest, call).await
7125        } else if guest.config().deterministic_io {
7126            let mut total_written_bytes = 0;
7127            let mut remaining_buf = call.len();
7128
7129            trace!(
7130                "[detcore/det_io]: Requested write buffer size: {:?}",
7131                remaining_buf
7132            );
7133
7134            loop {
7135                match self
7136                    .record_or_replay_preserving_tool_errors(guest, call)
7137                    .await
7138                {
7139                    Ok(res) => {
7140                        remaining_buf -= res as usize;
7141                        total_written_bytes += res;
7142
7143                        trace!(
7144                            "[detcore/det_io]: Remaining write buffer size: {:?}",
7145                            remaining_buf
7146                        );
7147
7148                        if res == 0 || remaining_buf == 0 {
7149                            break Ok(total_written_bytes);
7150                        }
7151
7152                        // Buf is guaranteed to exist as we already issued a syscall.
7153                        let old_ptr = call.buf().unwrap().as_raw();
7154                        call = call
7155                            .with_len(remaining_buf)
7156                            .with_buf(Addr::<u8>::from_raw(old_ptr + res as usize));
7157                    }
7158                    Err(error) => {
7159                        break finish_partial_record_or_replay_write(total_written_bytes, error);
7160                    }
7161                }
7162            }
7163        } else {
7164            self.record_or_replay_preserving_tool_errors(guest, call)
7165                .await
7166        };
7167
7168        resource_release_all(guest).await;
7169        res
7170    }
7171
7172    // AUTONOMOUS-BOT-IMPLEMENTED
7173    // TODO-HUMAN-REVIEW(#683): Confirm positional-write ordering and replay semantics.
7174    /// SYS_pwrite64 system call.
7175    pub async fn handle_pwrite64<G: Guest<Self>>(
7176        &self,
7177        guest: &mut G,
7178        mut call: syscalls::Pwrite64,
7179    ) -> Result<i64, Error> {
7180        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7181            return Err(if call.offset() < 0 {
7182                Errno::EINVAL.into()
7183            } else {
7184                Errno::ESPIPE.into()
7185            });
7186        }
7187
7188        let (resource, raw_ino) = guest.thread_state().with_detfd(call.fd(), |detfd| {
7189            (detfd.resource(), detfd.stat().map(|stat| stat.raw_inode()))
7190        })?;
7191        // The fd's cached `DetStat` carries the HOST inode (`DetStat` is built
7192        // straight from `fstat`/`statx`), so it must be determinized before it
7193        // can name a guest-visible resource. Passing it through directly used
7194        // to type-check only because `DetInode` was an alias for `RawInode`.
7195        let resource = match resource {
7196            Some(resource) => Some(resource),
7197            None => match raw_ino {
7198                Some(raw_ino) => Some(ResourceID::FileContents(
7199                    determinize_inode(guest, raw_ino).await.0,
7200                )),
7201                None => None,
7202            },
7203        };
7204
7205        if let Some(resource) = resource {
7206            let request = guest.thread_state().mk_request(resource, Permission::W);
7207            resource_request(guest, request).await;
7208        }
7209
7210        let result = if guest.config().deterministic_io {
7211            let mut total_written = 0_i64;
7212            let mut remaining = call.len();
7213
7214            loop {
7215                match self
7216                    .record_or_replay_preserving_tool_errors(guest, call)
7217                    .await
7218                {
7219                    Ok(written) => {
7220                        let Ok(written) = usize::try_from(written) else {
7221                            break Err(Errno::EIO.into());
7222                        };
7223                        let Ok(written_i64) = i64::try_from(written) else {
7224                            break Err(Errno::EIO.into());
7225                        };
7226                        if written > remaining {
7227                            break Err(Errno::EIO.into());
7228                        }
7229                        remaining -= written;
7230                        let Some(next_total) = total_written.checked_add(written_i64) else {
7231                            break Err(Errno::EIO.into());
7232                        };
7233                        total_written = next_total;
7234
7235                        if written == 0 || remaining == 0 {
7236                            break Ok(total_written);
7237                        }
7238
7239                        let Some(old_buf) = call.buf() else {
7240                            break Err(Errno::EFAULT.into());
7241                        };
7242                        let Some(next_buf) = old_buf.as_raw().checked_add(written) else {
7243                            break Err(Errno::EFAULT.into());
7244                        };
7245                        let Some(next_offset) = call.offset().checked_add(written_i64) else {
7246                            break Err(Errno::EFBIG.into());
7247                        };
7248                        let Some(next_buf) = Addr::<u8>::from_raw(next_buf) else {
7249                            break Err(Errno::EFAULT.into());
7250                        };
7251                        call = call
7252                            .with_buf(Some(next_buf))
7253                            .with_len(remaining)
7254                            .with_offset(next_offset);
7255                    }
7256                    Err(error) => {
7257                        break finish_partial_record_or_replay_write(total_written, error);
7258                    }
7259                }
7260            }
7261        } else {
7262            self.record_or_replay_preserving_tool_errors(guest, call)
7263                .await
7264        };
7265
7266        if guest.config().virtualize_metadata && matches!(&result, Ok(written) if *written > 0) {
7267            let inode = raw_ino.expect("virtualized metadata requires stat data for tracked fds");
7268            touch_file(guest, inode).await;
7269        }
7270
7271        resource_release_all(guest).await;
7272        result
7273    }
7274
7275    // AUTONOMOUS-BOT-IMPLEMENTED
7276    // TODO-HUMAN-REVIEW(#547)
7277    /// SYS_writev system call.
7278    ///
7279    /// Preserve the initial writev as one kernel operation so its iovec order remains intact.
7280    /// Detcore adds open-file resource ordering and nonblocking scheduler integration; a
7281    /// blocking pipe short write is completed by the helper because Hermit injected O_NONBLOCK.
7282    pub async fn handle_writev<G: Guest<Self>>(
7283        &self,
7284        guest: &mut G,
7285        call: syscalls::Writev,
7286    ) -> Result<i64, Error> {
7287        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7288            self.require_timer_slack_access(guest, call.fd(), true)?;
7289            let iovecs = read_iovecs(&guest.memory(), call.iov(), call.len())?;
7290            return self.writev_timer_slack(guest, call.fd(), iovecs, 0).await;
7291        }
7292
7293        self.fifo_polls_if_a_guest_holds_its_peer(guest, call.fd(), FifoPeer::Reader)
7294            .await;
7295        let (
7296            fd_type,
7297            physically_nonblocking,
7298            logically_nonblocking,
7299            open_file_id,
7300            resource,
7301            raw_ino,
7302        ) = guest.thread_state().with_detfd(call.fd(), |detfd| {
7303            (
7304                detfd.ty(),
7305                detfd.physically_nonblocking(),
7306                detfd.is_nonblocking(),
7307                detfd.open_file_id(),
7308                detfd.resource(),
7309                detfd.stat().map(|x| x.raw_inode()),
7310            )
7311        })?;
7312
7313        if let Some(resource) = resource {
7314            let mut request = guest.thread_state().mk_request(resource, Permission::W);
7315            if should_tag_host_timed_internal_pipe_io(
7316                guest.config().backend.internal_pipe_turns_are_host_timed,
7317                fd_type,
7318                physically_nonblocking,
7319                logically_nonblocking,
7320            ) {
7321                request.fyi(HOST_TIMED_INTERNAL_PIPE_IO_FYI);
7322            }
7323            resource_request(guest, request).await;
7324        }
7325
7326        let result = if physically_nonblocking && fd_type == FdType::Pipe && !logically_nonblocking
7327        {
7328            self.execute_blocking_pipe_writev(guest, call, open_file_id)
7329                .await
7330        } else if physically_nonblocking
7331            && matches!(fd_type, FdType::Socket | FdType::Pipe | FdType::Eventfd)
7332        {
7333            self.execute_nonblockable_fd_syscall(guest, call).await
7334        } else {
7335            self.record_or_replay_preserving_tool_errors(guest, call)
7336                .await
7337        };
7338
7339        if guest.config().virtualize_metadata && matches!(&result, Ok(written) if *written > 0) {
7340            let inode =
7341                raw_ino.expect("virtualized metadata requires stat data for every tracked fd");
7342            touch_file(guest, inode).await;
7343        }
7344
7345        resource_release_all(guest).await;
7346        result
7347    }
7348
7349    // AUTONOMOUS-BOT-IMPLEMENTED
7350    // TODO-HUMAN-REVIEW(#794)
7351    /// A vectored read (`readv`, or `preadv2` at the current offset) of a
7352    /// signalfd, whose
7353    /// SIGCHLD records go through the child-exit ledger as `read`'s do
7354    /// (`reconcile_signalfd_extents`).
7355    ///
7356    /// Linux imports the `count` iovecs at `address` before it writes any record,
7357    /// and the records can overwrite the array itself, so the geometry is
7358    /// captured here, before the read, and used for the reconciliation and
7359    /// for the output observation (`observed`) alike (Codex re-check #6 of
7360    /// https://github.com/rrnewton/hermit/pull/4031). A read whose every
7361    /// record is dropped reads again, with the array's bytes put back first.
7362    /// An array the tracer cannot read is a proven kernel failure (EINVAL, or
7363    /// EFAULT with some byte outside every mapping: the kernel copies the whole
7364    /// array), forwarded unchanged; a wholly mapped one it cannot read, or one
7365    /// whose mappings cannot be listed, is refused by name, so no record is
7366    /// returned unreconciled.
7367    async fn vectored_signalfd_read<G: Guest<Self>, C>(
7368        &self,
7369        guest: &mut G,
7370        sysno: Sysno,
7371        call: C,
7372        address: usize,
7373        count: usize,
7374        observed: &mut Option<Vec<crate::io_buffers::BufferExtent>>,
7375    ) -> Result<i64, Error>
7376    where
7377        C: Into<Syscall> + Copy,
7378    {
7379        const IOVEC: usize = std::mem::size_of::<libc::iovec>();
7380        let fd = match call.into() {
7381            Syscall::Readv(call) => call.fd(),
7382            Syscall::Preadv2(call) => call.fd(),
7383            _ => -1,
7384        };
7385        // Linux passes the count on as an `unsigned int` (Codex re-check #7).
7386        let count = crate::io_buffers::linux_iovec_count(count as u64);
7387        if count > libc::UIO_MAXIOV as usize {
7388            return self
7389                .record_or_replay_preserving_tool_errors(guest, call)
7390                .await;
7391        }
7392        let mut raw = vec![0u8; count * IOVEC];
7393        if count > 0 {
7394            let read = AddrMut::<u8>::from_raw(address)
7395                .is_some_and(|at| guest.memory().read_exact(at, &mut raw).is_ok())
7396                || {
7397                    use std::os::unix::fs::FileExt;
7398                    std::fs::File::open(format!("/proc/{}/mem", guest.tid().as_raw()))
7399                        .and_then(|mem| mem.read_exact_at(&mut raw, address as u64))
7400                        .is_ok()
7401                };
7402            if !read {
7403                // A maps listing that cannot be read decides nothing: refuse.
7404                let maps = std::fs::read_to_string(format!("/proc/{}/maps", guest.tid().as_raw()));
7405                if let Ok(maps) = &maps
7406                    && !signalfd_range_is_mapped(maps, address, raw.len())
7407                {
7408                    return self
7409                        .record_or_replay_preserving_tool_errors(guest, call)
7410                        .await;
7411                }
7412                tracing::error!(
7413                    "[detcore, dtid {}] {} of a signalfd with its iovec array at {:#x} is not \
7414                     supported: the memory is mapped, but Hermit cannot read it to reconcile \
7415                     the SIGCHLD records (https://github.com/rrnewton/hermit/issues/3994)",
7416                    guest.thread_state().dettid,
7417                    sysno,
7418                    address,
7419                );
7420                return self
7421                    .refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
7422                    .await;
7423            }
7424        }
7425        let extents: Vec<(usize, usize)> = raw
7426            .chunks(IOVEC)
7427            .map(|iovec| {
7428                let word = |at: usize| {
7429                    usize::from_ne_bytes(iovec[at..at + 8].try_into().expect("eight bytes"))
7430                };
7431                (word(0), word(8))
7432            })
7433            .collect();
7434        // A vectored read of a signalfd covering a signal with an entry behind
7435        // its list's front would need one record per kernel read, each into
7436        // its own sub-extents (`read_signalfd_per_record`), which Detcore does
7437        // not do for a vector; refused by name rather than return records out
7438        // of Linux's order (<https://github.com/rrnewton/hermit/issues/4262>).
7439        let total: usize = extents.iter().map(|(_, len)| *len).sum();
7440        if total >= 2 * crate::syscalls::signal::SIGNALFD_RECORD
7441            && self.signalfd_reads_per_record(guest, fd).await
7442        {
7443            tracing::error!(
7444                "[detcore, dtid {}] {} of a signalfd while a signal it covers has a POSIX timer's entry queued behind another is not supported: Linux returns them one by one in its dequeue order, which Detcore produces only for read (https://github.com/rrnewton/hermit/issues/4262)",
7445                guest.thread_state().dettid,
7446                sysno,
7447            );
7448            return self
7449                .refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
7450                .await;
7451        }
7452        loop {
7453            let before =
7454                crate::syscalls::signal::capture_signalfd_buffer(guest, &extents, usize::MAX);
7455            let result = self
7456                .record_or_replay_preserving_tool_errors(guest, call)
7457                .await;
7458            match result {
7459                Ok(read) if read > 0 => {
7460                    let Some(kept) = self
7461                        .reconcile_signalfd_extents(guest, &extents, read as usize, &before)
7462                        .await
7463                    else {
7464                        break self.refuse_unrestorable_signalfd_record(guest, sysno).await;
7465                    };
7466                    if self
7467                        .settle_faulted_signalfd_record(guest, fd, &extents, Some(read as usize))
7468                        .await
7469                    {
7470                        break self.refuse_faulted_signalfd_discard(guest, sysno).await;
7471                    }
7472                    if kept > 0 {
7473                        *observed = Some(
7474                            crate::syscalls::signal::signalfd_extent_pieces(&extents, kept)
7475                                .into_iter()
7476                                .map(|(addr, len)| crate::io_buffers::BufferExtent {
7477                                    addr: addr as u64,
7478                                    len: len as u64,
7479                                })
7480                                .collect(),
7481                        );
7482                        break Ok(kept as i64);
7483                    }
7484                    if let Some(at) = AddrMut::<u8>::from_raw(address)
7485                        && guest.memory().write_exact(at, &raw).is_err()
7486                    {
7487                        break Err(Errno::EFAULT.into());
7488                    }
7489                }
7490                Err(Error::Errno(Errno::EFAULT)) => {
7491                    if self
7492                        .settle_faulted_signalfd_record(guest, fd, &extents, None)
7493                        .await
7494                    {
7495                        break self.refuse_faulted_signalfd_discard(guest, sysno).await;
7496                    }
7497                    break Err(Errno::EFAULT.into());
7498                }
7499                result => break result,
7500            }
7501        }
7502    }
7503
7504    /// Linux's signalfd read dequeues each signal before it copies its record
7505    /// out, and stops at the first copy that faults, so that signal is lost:
7506    /// the read fails with EFAULT if it was the first record, or returns the
7507    /// records before it. The SIGCHLD such a record may have held is settled
7508    /// with the child-exit ledger as a faulted `rt_sigtimedwait`'s is
7509    /// (`WaitFaulted`; the Codex re-check of
7510    /// https://github.com/rrnewton/hermit/pull/4131 at 8692836e). `extents`
7511    /// are the read's buffers and `read` the bytes it returned, or `None` for
7512    /// an EFAULT.
7513    ///
7514    /// An EFAULT dequeued nothing when a buffer is not a user address at all
7515    /// (`access_ok`, checked before any dequeue). After a positive read, a
7516    /// record was lost only if the buffers had room for another and some
7517    /// byte of it is not writable; even then no signal may have been left to
7518    /// take, so the shared queue's pending bit decides that case.
7519    ///
7520    /// Returns whether a record may have been lost that way, and its copy may
7521    /// have been one Linux discarded when it was sent, which it would never
7522    /// have dequeued: the caller refuses the call by name
7523    /// (`refuse_faulted_signalfd_discard`), since the copy cannot be told
7524    /// (<https://github.com/rrnewton/hermit/issues/4293>).
7525    async fn settle_faulted_signalfd_record<G: Guest<Self>>(
7526        &self,
7527        guest: &mut G,
7528        fd: i32,
7529        extents: &[(usize, usize)],
7530        read: Option<usize>,
7531    ) -> bool {
7532        if !self.cfg.backend.reports_child_exit_publication || !guest.config().sequentialize_threads
7533        {
7534            return false;
7535        }
7536        match read {
7537            None => {
7538                let user_end = user_address_end();
7539                if extents.iter().any(|(address, len)| {
7540                    address.checked_add(*len).is_none_or(|end| end > user_end)
7541                }) {
7542                    return false;
7543                }
7544            }
7545            Some(read) => {
7546                let Some(next) = signalfd_next_record(extents, read) else {
7547                    return false;
7548                };
7549                let Ok(maps) =
7550                    std::fs::read_to_string(format!("/proc/{}/maps", guest.tid().as_raw()))
7551                else {
7552                    return false;
7553                };
7554                if next
7555                    .iter()
7556                    .all(|(address, len)| signalfd_range_is_writable(&maps, *address, *len))
7557                {
7558                    return false;
7559                }
7560            }
7561        }
7562        let mask = signalfd_sigmask(guest.pid().as_raw(), fd);
7563        let lost_a_discarded_copy = {
7564            use crate::scheduler::discarded_at_send::DiscardedSignalAnswer;
7565            use crate::scheduler::discarded_at_send::DiscardedSignalControl;
7566            use crate::scheduler::discarded_at_send::STANDARD_SIGNALS;
7567            matches!(
7568                crate::tool_global::discarded_signal(guest, DiscardedSignalControl::Bits).await,
7569                DiscardedSignalAnswer::Bits { thread, process }
7570                    if (thread | process) & mask.unwrap_or(!0) & STANDARD_SIGNALS != 0
7571            )
7572        };
7573        let sigchld = crate::syscalls::threads::kernel_sigset_bit(libc::SIGCHLD);
7574        if mask.is_some_and(|mask| mask & sigchld == 0) {
7575            return lost_a_discarded_copy;
7576        }
7577        let Ok(state) =
7578            crate::syscalls::threads::read_thread_wait_signal_state(guest.pid(), guest.tid())
7579        else {
7580            return lost_a_discarded_copy;
7581        };
7582        // A failed read of a descriptor for SIGCHLD alone took a SIGCHLD.
7583        let shared_pending = if read.is_none() && mask == Some(sigchld) {
7584            false
7585        } else {
7586            state.shared_pending & sigchld != 0
7587        };
7588        crate::tool_global::child_exit_sigchld(
7589            guest,
7590            crate::scheduler::child_exit_sigchld::ChildExitSigchldControl::WaitFaulted {
7591                private_pending: state.thread_pending & sigchld != 0,
7592                shared_pending,
7593            },
7594        )
7595        .await;
7596        lost_a_discarded_copy
7597    }
7598
7599    /// Refuse by name a signalfd `sysno` whose copy-out faulted after a
7600    /// dequeue that may have taken a copy Linux discarded when it was sent
7601    /// (`settle_faulted_signalfd_record`): Linux would not have taken it, and
7602    /// which copy the lost record held cannot be told.
7603    async fn refuse_faulted_signalfd_discard<G: Guest<Self>>(
7604        &self,
7605        guest: &mut G,
7606        sysno: Sysno,
7607    ) -> Result<i64, Error> {
7608        tracing::error!(
7609            "[detcore, dtid {}] {} of a signalfd faulted copying out a record that may hold a \
7610             signal Linux discarded when it was sent, which Linux would never have dequeued; \
7611             Hermit cannot tell which copy was lost \
7612             (https://github.com/rrnewton/hermit/issues/4293)",
7613            guest.thread_state().dettid,
7614            sysno,
7615        );
7616        self.refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
7617            .await
7618    }
7619
7620    /// Refuse by name a signalfd `sysno` that read a record to drop (a copy
7621    /// Linux discarded at send, or a duplicate child-exit copy) whose bytes
7622    /// the capture before the read does not reach: more records than
7623    /// `SIGNALFD_CAPTURED` holds, which only real-time signals can make.
7624    /// Linux would leave those bytes as they were, and Hermit does not invent
7625    /// them (the Codex re-check of https://github.com/rrnewton/hermit/pull/4351,
7626    /// P2-2).
7627    async fn refuse_unrestorable_signalfd_record<G: Guest<Self>>(
7628        &self,
7629        guest: &mut G,
7630        sysno: Sysno,
7631    ) -> Result<i64, Error> {
7632        tracing::error!(
7633            "[detcore, dtid {}] {} of a signalfd read a record Hermit drops, beyond the bytes \
7634             captured before the read, so it cannot leave the caller's buffer as Linux would \
7635             (https://github.com/rrnewton/hermit/issues/4293)",
7636            guest.thread_state().dettid,
7637            sysno,
7638        );
7639        self.refuse_unserviceable_operation(guest, sysno, Errno::ENOSYS)
7640            .await
7641    }
7642
7643    /// SYS_readv system call: the vectored form of `read`.
7644    ///
7645    /// Mirrors [`Self::handle_writev`] for the read direction. Detcore adds
7646    /// open-file resource ordering and, for physically nonblocking pipe/socket
7647    /// fds, the nonblocking scheduler integration. Random devices use the shared
7648    /// canonical cursor; other descriptors retain their recorded kernel operation.
7649    pub async fn handle_readv<G: Guest<Self>>(
7650        &self,
7651        guest: &mut G,
7652        call: syscalls::Readv,
7653    ) -> Result<i64, Error> {
7654        self.handle_readv_with_output(guest, call, &mut None).await
7655    }
7656
7657    /// Import after the resource wait and retain that geometry through copyout.
7658    /// The shared-cursor closure is synchronous and takes no metadata locks.
7659    fn read_random_vectors<G: Guest<Self>>(
7660        &self,
7661        guest: &mut G,
7662        detfd: &DetFd,
7663        request: RandomVectoredRead,
7664        rng_output: &mut Option<Vec<crate::io_buffers::BufferExtent>>,
7665    ) -> Result<i64, Error> {
7666        require_random_device_read_access(detfd.status_flags())?;
7667        let iovecs = crate::iovecs::import_read_iovecs(
7668            &guest.memory(),
7669            request.address,
7670            request.count,
7671            || crate::iovecs::UserAddressLimit::from_query(guest.user_address_limit()),
7672        )?;
7673        let total = iovecs.iter().map(|iov| iov.len).sum();
7674        validate_random_vector_read(request.offset, total, request.flags)?;
7675        let written = if let Some(offset) = request.offset {
7676            self.fill_random_device_iovecs(guest, &iovecs, offset)?
7677        } else {
7678            detfd.with_random_device_stream(|offset| {
7679                self.fill_random_device_iovecs(guest, &iovecs, offset)
7680            })?
7681        };
7682        if written > 0 && self.cfg.detlog_io_buffers && crate::detlog_observed!() {
7683            *rng_output = Some(crate::io_buffers::rng_readv_extents(&iovecs, written)?);
7684        }
7685        Ok(written as i64)
7686    }
7687
7688    pub(crate) async fn handle_readv_with_output<G: Guest<Self>>(
7689        &self,
7690        guest: &mut G,
7691        call: syscalls::Readv,
7692        rng_output: &mut Option<Vec<crate::io_buffers::BufferExtent>>,
7693    ) -> Result<i64, Error> {
7694        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7695            self.require_timer_slack_access(guest, call.fd(), false)?;
7696            let iovecs = read_iovecs(&guest.memory(), call.iov(), call.len())?;
7697            return self
7698                .readv_timer_slack(guest, call.fd(), iovecs, None, 0)
7699                .await;
7700        }
7701        let files = self.rendered_files(guest);
7702        if guest.thread_state().with_detfd(call.fd(), |detfd| {
7703            detfd.procfs_renderable_path(files).is_some()
7704        })? {
7705            let address = call.iov().map_or(0, |address| address.as_raw());
7706            return self
7707                .readv_rendered_procfs(guest, call.fd(), address, call.len(), None, 0)
7708                .await;
7709        }
7710
7711        let is_procfs = guest
7712            .thread_state()
7713            .with_detfd(call.fd(), |detfd| detfd.procfs_position().is_some())?;
7714        if is_procfs {
7715            return Err(Errno::ENOSYS.into());
7716        }
7717
7718        self.fifo_polls_if_a_guest_holds_its_peer(guest, call.fd(), FifoPeer::Writer)
7719            .await;
7720        let (fd_type, physically_nonblocking, logically_nonblocking, resource, detfd) =
7721            guest.thread_state().with_detfd(call.fd(), |detfd| {
7722                (
7723                    detfd.ty(),
7724                    detfd.physically_nonblocking(),
7725                    detfd.is_nonblocking(),
7726                    detfd.resource(),
7727                    detfd.clone(),
7728                )
7729            })?;
7730
7731        if let Some(resource) = resource {
7732            let mut request = guest.thread_state().mk_request(resource, Permission::R);
7733            if should_tag_host_timed_internal_pipe_io(
7734                guest.config().backend.internal_pipe_turns_are_host_timed,
7735                fd_type,
7736                physically_nonblocking,
7737                logically_nonblocking,
7738            ) {
7739                request.fyi(HOST_TIMED_INTERNAL_PIPE_IO_FYI);
7740            }
7741            resource_request(guest, request).await;
7742        }
7743
7744        let res = if fd_type == FdType::Rng {
7745            self.read_random_vectors(
7746                guest,
7747                &detfd,
7748                RandomVectoredRead {
7749                    address: call.iov().map_or(0, |addr| addr.as_raw()),
7750                    count: call.len(),
7751                    offset: None,
7752                    flags: 0,
7753                },
7754                rng_output,
7755            )
7756        } else if detfd.inherited_external_read().is_some() {
7757            // The same one-kernel-read rule as scalar input: preserve the
7758            // kernel's iovec/short-read/error semantics and announce blocking.
7759            self.record_or_replay_blocking(guest, call.into()).await
7760        } else if fd_type == FdType::Timerfd && crate::syscalls::timerfd::enabled(guest) {
7761            // As `read` of a timerfd on virtual time: publish its expirations,
7762            // retry a logically blocking read in turns, and return the
7763            // virtual count (`crate::syscalls::timerfd`).
7764            crate::syscalls::timerfd::publish_expired(guest).await;
7765            let result = self.execute_nonblockable_fd_syscall(guest, call).await;
7766            crate::syscalls::timerfd::finish_readv(guest, call.fd(), call.iov(), call.len(), result)
7767        } else if physically_nonblocking
7768            && matches!(fd_type, FdType::Socket | FdType::Pipe | FdType::Eventfd)
7769        {
7770            self.execute_nonblockable_fd_syscall(guest, call).await
7771        } else if fd_type == FdType::Signalfd && self.cfg.backend.reports_child_exit_publication {
7772            // The SIGCHLD records a vectored read scatters go through the
7773            // child-exit ledger as `read`'s do (`reconcile_signalfd_extents`).
7774            self.vectored_signalfd_read(
7775                guest,
7776                Sysno::readv,
7777                call,
7778                call.iov().map_or(0, |iov| iov.as_raw()),
7779                call.len(),
7780                rng_output,
7781            )
7782            .await
7783        } else {
7784            self.record_or_replay_preserving_tool_errors(guest, call)
7785                .await
7786        };
7787
7788        // O2: a signalfd read (even one that faulted copying out a record
7789        // it had already dequeued) may have taken the process's ITIMER_REAL
7790        // copy (https://github.com/rrnewton/hermit/issues/4139).
7791        if fd_type == FdType::Signalfd {
7792            crate::tool_global::reconcile_alarm(guest).await;
7793        }
7794        resource_release_all(guest).await;
7795        res
7796    }
7797
7798    // AUTONOMOUS-BOT-IMPLEMENTED
7799    // TODO-HUMAN-REVIEW(#794)
7800    /// SYS_preadv system call: the vectored form of `pread64`.
7801    ///
7802    /// RNG reads use the canonical stream at the explicit offset without
7803    /// advancing its shared cursor. Other files retain their kernel operation.
7804    pub async fn handle_preadv<G: Guest<Self>>(
7805        &self,
7806        guest: &mut G,
7807        call: syscalls::Preadv,
7808    ) -> Result<i64, Error> {
7809        self.handle_preadv_with_output(guest, call, &mut None).await
7810    }
7811
7812    pub(crate) async fn handle_preadv_with_output<G: Guest<Self>>(
7813        &self,
7814        guest: &mut G,
7815        call: syscalls::Preadv,
7816        rng_output: &mut Option<Vec<crate::io_buffers::BufferExtent>>,
7817    ) -> Result<i64, Error> {
7818        // Linux rejects negative offsets before descriptor lookup or import.
7819        let offset = vectored_offset(call.pos_l(), call.pos_h());
7820        if offset < 0 {
7821            return Err(Errno::EINVAL.into());
7822        }
7823        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7824            self.require_timer_slack_access(guest, call.fd(), false)?;
7825            let iovecs = read_iovecs(&guest.memory(), call.iov(), call.iov_len())?;
7826            return self
7827                .readv_timer_slack(guest, call.fd(), iovecs, Some(offset), 0)
7828                .await;
7829        }
7830        let files = self.rendered_files(guest);
7831        if guest.thread_state().with_detfd(call.fd(), |detfd| {
7832            detfd.procfs_renderable_path(files).is_some()
7833        })? {
7834            let address = call.iov().map_or(0, |address| address.as_raw());
7835            return self
7836                .readv_rendered_procfs(guest, call.fd(), address, call.iov_len(), Some(offset), 0)
7837                .await;
7838        }
7839
7840        let is_procfs = guest
7841            .thread_state()
7842            .with_detfd(call.fd(), |detfd| detfd.procfs_position().is_some())?;
7843        if is_procfs {
7844            return Err(Errno::ENOSYS.into());
7845        }
7846
7847        let detfd = guest
7848            .thread_state()
7849            .with_detfd(call.fd(), |detfd| detfd.clone())?;
7850
7851        if let Some(resource) = detfd.resource() {
7852            let request = guest.thread_state().mk_request(resource, Permission::R);
7853            resource_request(guest, request).await;
7854        }
7855
7856        let res = if detfd.ty() == FdType::Rng {
7857            self.read_random_vectors(
7858                guest,
7859                &detfd,
7860                RandomVectoredRead {
7861                    address: call.iov().map_or(0, |addr| addr.as_raw()),
7862                    count: call.iov_len(),
7863                    offset: Some(offset as u64),
7864                    flags: 0,
7865                },
7866                rng_output,
7867            )
7868        } else {
7869            self.record_or_replay_preserving_tool_errors(guest, call)
7870                .await
7871        };
7872        resource_release_all(guest).await;
7873        res
7874    }
7875
7876    // AUTONOMOUS-BOT-IMPLEMENTED
7877    // TODO-HUMAN-REVIEW(#794)
7878    /// SYS_preadv2 system call: positioned vectors, or the shared stream when
7879    /// offset is -1. RNG flag validation precedes output copying.
7880    pub async fn handle_preadv2<G: Guest<Self>>(
7881        &self,
7882        guest: &mut G,
7883        call: syscalls::Preadv2,
7884    ) -> Result<i64, Error> {
7885        self.handle_preadv2_with_output(guest, call, &mut None)
7886            .await
7887    }
7888
7889    pub(crate) async fn handle_preadv2_with_output<G: Guest<Self>>(
7890        &self,
7891        guest: &mut G,
7892        call: syscalls::Preadv2,
7893        rng_output: &mut Option<Vec<crate::io_buffers::BufferExtent>>,
7894    ) -> Result<i64, Error> {
7895        let offset = vectored_offset(call.pos_l(), call.pos_h());
7896        if offset < -1 {
7897            return Err(Errno::EINVAL.into());
7898        }
7899        if self.timer_slack_binding(guest, call.fd())?.is_some() {
7900            self.require_timer_slack_access(guest, call.fd(), false)?;
7901            let count = usize::try_from(call.iov_len()).map_err(|_| Errno::EINVAL)?;
7902            let iovecs = read_iovecs(&guest.memory(), call.iov(), count)?;
7903            return if offset == -1 {
7904                self.readv_timer_slack(guest, call.fd(), iovecs, None, call.flags())
7905                    .await
7906            } else {
7907                self.readv_timer_slack(guest, call.fd(), iovecs, Some(offset), call.flags())
7908                    .await
7909            };
7910        }
7911        let files = self.rendered_files(guest);
7912        if guest.thread_state().with_detfd(call.fd(), |detfd| {
7913            detfd.procfs_renderable_path(files).is_some()
7914        })? {
7915            let address = call.iov().map_or(0, |address| address.as_raw());
7916            let offset = (offset != -1).then_some(offset);
7917            return self
7918                .readv_rendered_procfs(
7919                    guest,
7920                    call.fd(),
7921                    address,
7922                    call.iov_len() as usize,
7923                    offset,
7924                    call.flags(),
7925                )
7926                .await;
7927        }
7928
7929        let is_procfs = guest
7930            .thread_state()
7931            .with_detfd(call.fd(), |detfd| detfd.procfs_position().is_some())?;
7932        if is_procfs {
7933            return Err(Errno::ENOSYS.into());
7934        }
7935
7936        let detfd = guest
7937            .thread_state()
7938            .with_detfd(call.fd(), |detfd| detfd.clone())?;
7939
7940        if let Some(resource) = detfd.resource() {
7941            let request = guest.thread_state().mk_request(resource, Permission::R);
7942            resource_request(guest, request).await;
7943        }
7944
7945        let res = if detfd.ty() == FdType::Rng {
7946            self.read_random_vectors(
7947                guest,
7948                &detfd,
7949                RandomVectoredRead {
7950                    address: call.iov().map_or(0, |addr| addr.as_raw()),
7951                    count: call.iov_len() as usize,
7952                    offset: (offset != -1).then_some(offset as u64),
7953                    flags: call.flags(),
7954                },
7955                rng_output,
7956            )
7957        } else if detfd.ty() == FdType::Signalfd
7958            && offset == -1
7959            && self.cfg.backend.reports_child_exit_publication
7960        {
7961            // At the current offset (-1) a signalfd reads as `readv` does,
7962            // and its records go through the child-exit ledger
7963            // (`reconcile_signalfd_extents`). At any other offset, as with
7964            // `preadv`, the kernel fails with ESPIPE before it imports the
7965            // array, so that call goes to it unchanged below.
7966            self.vectored_signalfd_read(
7967                guest,
7968                Sysno::preadv2,
7969                call,
7970                call.iov().map_or(0, |iov| iov.as_raw()),
7971                usize::try_from(call.iov_len()).unwrap_or(0),
7972                rng_output,
7973            )
7974            .await
7975        } else {
7976            self.record_or_replay_preserving_tool_errors(guest, call)
7977                .await
7978        };
7979        // O2: a signalfd read (even one that faulted copying out a record
7980        // it had already dequeued) may have taken the process's ITIMER_REAL
7981        // copy (https://github.com/rrnewton/hermit/issues/4139).
7982        if detfd.ty() == FdType::Signalfd {
7983            crate::tool_global::reconcile_alarm(guest).await;
7984        }
7985        resource_release_all(guest).await;
7986        res
7987    }
7988
7989    // AUTONOMOUS-BOT-IMPLEMENTED
7990    // TODO-HUMAN-REVIEW(#794)
7991    /// SYS_pwritev system call: the vectored form of `pwrite64`.
7992    ///
7993    /// Positioned writes target seekable files and do not block, so this mirrors
7994    /// [`Self::handle_pwrite64`]'s ordering, records/replays the single kernel
7995    /// operation, and bumps the virtual mtime on a successful write.
7996    pub async fn handle_pwritev<G: Guest<Self>>(
7997        &self,
7998        guest: &mut G,
7999        call: syscalls::Pwritev,
8000    ) -> Result<i64, Error> {
8001        if self.timer_slack_binding(guest, call.fd())?.is_some() {
8002            let offset = vectored_offset(call.pos_l(), call.pos_h());
8003            return if offset < 0 {
8004                Err(Errno::EINVAL.into())
8005            } else {
8006                Err(Errno::ESPIPE.into())
8007            };
8008        }
8009
8010        let (resource, raw_ino) = guest.thread_state().with_detfd(call.fd(), |detfd| {
8011            (detfd.resource(), detfd.stat().map(|stat| stat.raw_inode()))
8012        })?;
8013        // The fd's cached `DetStat` carries the HOST inode (`DetStat` is built
8014        // straight from `fstat`/`statx`), so it must be determinized before it
8015        // can name a guest-visible resource. Passing it through directly used
8016        // to type-check only because `DetInode` was an alias for `RawInode`.
8017        let resource = match resource {
8018            Some(resource) => Some(resource),
8019            None => match raw_ino {
8020                Some(raw_ino) => Some(ResourceID::FileContents(
8021                    determinize_inode(guest, raw_ino).await.0,
8022                )),
8023                None => None,
8024            },
8025        };
8026
8027        if let Some(resource) = resource {
8028            let request = guest.thread_state().mk_request(resource, Permission::W);
8029            resource_request(guest, request).await;
8030        }
8031
8032        let result = self
8033            .record_or_replay_preserving_tool_errors(guest, call)
8034            .await;
8035
8036        if guest.config().virtualize_metadata && matches!(&result, Ok(written) if *written > 0) {
8037            let inode = raw_ino.expect("virtualized metadata requires stat data for tracked fds");
8038            touch_file(guest, inode).await;
8039        }
8040
8041        resource_release_all(guest).await;
8042        result
8043    }
8044
8045    // AUTONOMOUS-BOT-IMPLEMENTED
8046    // TODO-HUMAN-REVIEW(#794)
8047    /// SYS_pwritev2 system call: `pwritev` with a trailing per-call flags
8048    /// argument, which record/replay forwards unchanged.
8049    pub async fn handle_pwritev2<G: Guest<Self>>(
8050        &self,
8051        guest: &mut G,
8052        call: syscalls::Pwritev2,
8053    ) -> Result<i64, Error> {
8054        if self.timer_slack_binding(guest, call.fd())?.is_some() {
8055            let offset = vectored_offset(call.pos_l(), call.pos_h());
8056            if offset < -1 {
8057                return Err(Errno::EINVAL.into());
8058            }
8059            if offset >= 0 {
8060                return Err(Errno::ESPIPE.into());
8061            }
8062            self.require_timer_slack_access(guest, call.fd(), true)?;
8063            let count = usize::try_from(call.iov_len()).map_err(|_| Errno::EINVAL)?;
8064            let iovecs = read_iovecs(&guest.memory(), call.iov(), count)?;
8065            return self
8066                .writev_timer_slack(guest, call.fd(), iovecs, call.flags())
8067                .await;
8068        }
8069
8070        let (resource, raw_ino) = guest.thread_state().with_detfd(call.fd(), |detfd| {
8071            (detfd.resource(), detfd.stat().map(|stat| stat.raw_inode()))
8072        })?;
8073        // The fd's cached `DetStat` carries the HOST inode (`DetStat` is built
8074        // straight from `fstat`/`statx`), so it must be determinized before it
8075        // can name a guest-visible resource. Passing it through directly used
8076        // to type-check only because `DetInode` was an alias for `RawInode`.
8077        let resource = match resource {
8078            Some(resource) => Some(resource),
8079            None => match raw_ino {
8080                Some(raw_ino) => Some(ResourceID::FileContents(
8081                    determinize_inode(guest, raw_ino).await.0,
8082                )),
8083                None => None,
8084            },
8085        };
8086
8087        if let Some(resource) = resource {
8088            let request = guest.thread_state().mk_request(resource, Permission::W);
8089            resource_request(guest, request).await;
8090        }
8091
8092        let result = self
8093            .record_or_replay_preserving_tool_errors(guest, call)
8094            .await;
8095
8096        if guest.config().virtualize_metadata && matches!(&result, Ok(written) if *written > 0) {
8097            let inode = raw_ino.expect("virtualized metadata requires stat data for tracked fds");
8098            touch_file(guest, inode).await;
8099        }
8100
8101        resource_release_all(guest).await;
8102        result
8103    }
8104
8105    /// SYS_mmap system call.
8106    pub async fn handle_mmap<G: Guest<Self>>(
8107        &self,
8108        guest: &mut G,
8109        call: syscalls::Mmap,
8110    ) -> Result<i64, Error> {
8111        enum SharedBacking {
8112            Anonymous,
8113            File {
8114                object: SharedMemoryObjectId,
8115                offset: u64,
8116            },
8117        }
8118
8119        let backing = if call.flags().contains(MapFlags::MAP_SHARED) {
8120            if call.fd() == -1 {
8121                Some(SharedBacking::Anonymous)
8122            } else {
8123                let offset = u64::try_from(call.offset()).map_err(|_| Errno::EINVAL)?;
8124                guest
8125                    .thread_state()
8126                    .with_detfd(call.fd(), |fd| {
8127                        let object = fd.stat().map_or_else(
8128                            || SharedMemoryObjectId::OpenFile {
8129                                id: fd.open_file_id(),
8130                            },
8131                            |stat| SharedMemoryObjectId::File {
8132                                device: stat.dev,
8133                                inode: stat.inode,
8134                            },
8135                        );
8136                        SharedBacking::File { object, offset }
8137                    })
8138                    .ok()
8139            }
8140        } else {
8141            None
8142        };
8143        let len = call.len();
8144        let result = self.record_or_replay(guest, call).await?;
8145        let start = usize::try_from(result).expect("a successful mmap must return an address");
8146
8147        guest.thread_state().unmap_memory(start, len);
8148        match backing {
8149            Some(SharedBacking::Anonymous) => {
8150                guest.thread_state().map_shared_anonymous(start, len);
8151            }
8152            Some(SharedBacking::File { object, offset }) => {
8153                guest
8154                    .thread_state()
8155                    .map_shared_object(start, len, object, offset);
8156            }
8157            None => {}
8158        }
8159        Ok(result)
8160    }
8161
8162    /// SYS_munmap system call.
8163    pub async fn handle_munmap<G: Guest<Self>>(
8164        &self,
8165        guest: &mut G,
8166        call: syscalls::Munmap,
8167    ) -> Result<i64, Error> {
8168        let start = call.addr().map(Addr::as_raw).unwrap_or(0);
8169        let len = call.len();
8170        let result = self.record_or_replay(guest, call).await?;
8171        guest.thread_state().unmap_memory(start, len);
8172        Ok(result)
8173    }
8174
8175    /// SYS_mremap system call.
8176    pub async fn handle_mremap<G: Guest<Self>>(
8177        &self,
8178        guest: &mut G,
8179        call: syscalls::Mremap,
8180    ) -> Result<i64, Error> {
8181        let old_start = call.addr().map(AddrMut::as_raw).unwrap_or(0);
8182        let old_len = call.old_len();
8183        let new_len = call.new_len();
8184        // MREMAP_DONTUNMAP (Linux 5.7): the old mapping stays in place.
8185        let keep_source = call.flags() & 4 != 0;
8186        let result = self.record_or_replay(guest, call).await?;
8187        let new_start =
8188            usize::try_from(result).expect("a successful mremap must return an address");
8189        guest
8190            .thread_state()
8191            .remap_memory(old_start, old_len, new_start, new_len, keep_source);
8192        Ok(result)
8193    }
8194
8195    /// What Detcore learns of the file `stat` describes, which the guest
8196    /// named as `target`, as a procfs entry: its path within procfs when its
8197    /// device is a procfs mount in the guest's mount table (see
8198    /// [`procfs_inode`]). A failure to tell or to name a procfs entry records
8199    /// a determinism loss, as the entry's number then depends on whether the
8200    /// host rebuilt it.
8201    ///
8202    /// Never under record and replay, which reproduces the recorded host
8203    /// numbers instead: Replayer's descriptor is a placeholder, and its guest
8204    /// has no `/proc`. Nor when the guest's thread IDs do not name host tasks
8205    /// (see [`procfs_inode::guest_tids_name_host_tasks`]), as there is then no
8206    /// `/proc/<tid>` to read.
8207    ///
8208    /// Nor without sequentialized threads (see [`Self::name_procfs_entry`]).
8209    ///
8210    /// Naming a path injects an `openat` and a `close` into the guest (see
8211    /// [`Self::with_object_link`]), and Detcore trusts the host kernel to run
8212    /// them as Linux defines them. A
8213    /// seccomp filter the guest inherited from whatever started it (which
8214    /// `Config::inherited_seccomp` records) may refuse them with an error,
8215    /// such as `EPERM`, and Detcore then names nothing and records a
8216    /// determinism loss. A filter, or a user-space supervisor
8217    /// (`SECCOMP_RET_USER_NOTIF`), that returns a result without running the
8218    /// call stands in for the kernel, which Detcore does not support.
8219    ///
8220    /// The `O_PATH` descriptor that names a path is open in the guest for one
8221    /// turn. A call the scheduler runs in the background meanwhile, such as
8222    /// an `accept` on a descriptor Detcore does not track, can allocate a
8223    /// descriptor in the same table at a moment the host chooses, and so take
8224    /// another number than without the stat, as it can beside any other
8225    /// descriptor allocation (https://github.com/rrnewton/hermit/issues/3988).
8226    ///
8227    /// The guest's `errno` is what it was: under SaBRe, Detcore shares libc,
8228    /// and so `errno`, with the guest thread it handles (see
8229    /// [`procfs_inode::preserving_errno`]).
8230    async fn procfs_entry<G: Guest<Self>>(
8231        guest: &mut G,
8232        stat: &DetStat,
8233        target: StatTarget<'_>,
8234    ) -> ProcfsEntry {
8235        procfs_inode::preserving_errno(Self::name_procfs_entry(guest, stat, target)).await
8236    }
8237
8238    /// Maps ownership needs the actual opened object even where scheduler
8239    /// IDs are virtual. Use the existing same-view task directory capability;
8240    /// never pass a virtual TID to the host-only procfs naming path.
8241    async fn maps_descriptor_entry<G: Guest<Self>>(
8242        &self,
8243        guest: &G,
8244        stat: &DetStat,
8245        fd: RawFd,
8246    ) -> ProcfsEntry {
8247        procfs_inode::preserving_errno(async {
8248            if guest.config().recordreplay_modes || !guest.config().sequentialize_threads {
8249                return ProcfsEntry::Unknown;
8250            }
8251            let Some(task) = self.guest_task_directory(guest) else {
8252                return ProcfsEntry::Unknown;
8253            };
8254            match procfs_inode::descriptor_procfs_path(&task, fd, stat.dev, stat.inode) {
8255                Ok(Some(within)) => ProcfsEntry::At(within),
8256                Ok(None) => ProcfsEntry::NotProcfs,
8257                Err(_) => ProcfsEntry::Unknown,
8258            }
8259        })
8260        .await
8261    }
8262
8263    async fn maps_guest_target<G: Guest<Self>>(
8264        &self,
8265        guest: &mut G,
8266        actual: &Path,
8267    ) -> Option<crate::procfs::BoundTask> {
8268        let numbers = if Self::translates_procfs_numbers(guest) {
8269            let ids = crate::procfs::ids::named_ids(actual);
8270            Some(Self::guest_procfs_numbers(guest, &ids).await?)
8271        } else {
8272            None
8273        };
8274        let (pid, tid) = self.procfs_caller_ids(guest)?;
8275        Self::maps_target_with_numbers(actual, numbers.as_ref(), pid, tid)
8276    }
8277
8278    /// Preserve an authenticated spelling when its complete numeric mapping
8279    /// is the identity. Missing target components cannot authorize a binding.
8280    fn maps_target_with_numbers(
8281        actual: &Path,
8282        numbers: Option<&BTreeMap<i32, i32>>,
8283        pid: i32,
8284        tid: i32,
8285    ) -> Option<crate::procfs::BoundTask> {
8286        let translated;
8287        let actual = if let Some(numbers) = numbers {
8288            if crate::procfs::ids::named_ids(actual)
8289                .iter()
8290                .any(|id| !numbers.contains_key(id))
8291            {
8292                return None;
8293            }
8294            translated = crate::procfs::ids::translate(actual, |id| numbers.get(&id).copied());
8295            translated.as_deref().unwrap_or(actual)
8296        } else {
8297            actual
8298        };
8299        crate::procfs::maps_task_at(actual, pid, tid)
8300    }
8301
8302    /// [`Self::procfs_entry`], which restores the guest's `errno` afterwards.
8303    ///
8304    /// Without sequentialized threads, another guest thread can change what a
8305    /// descriptor, the working directory or a path leads to between any two
8306    /// of the steps that name an entry, and under SaBRe it shares the
8307    /// descriptor table Detcore reads the mount table through. So Detcore
8308    /// names nothing then, before any of those steps, and records a
8309    /// determinism loss for any file that may be on procfs (see
8310    /// [`procfs_inode::may_be_procfs`]), devpts files among them.
8311    async fn name_procfs_entry<G: Guest<Self>>(
8312        guest: &mut G,
8313        stat: &DetStat,
8314        target: StatTarget<'_>,
8315    ) -> ProcfsEntry {
8316        if guest.config().recordreplay_modes
8317            || !procfs_inode::guest_tids_name_host_tasks(
8318                &guest.config().backend,
8319                guest.thread_state().physical_tid,
8320            )
8321            || !procfs_inode::may_be_procfs(stat.dev, stat.blksize)
8322        {
8323            return ProcfsEntry::NotProcfs;
8324        }
8325        if !guest.config().sequentialize_threads {
8326            Self::record_procfs_loss(
8327                guest,
8328                "the guest's threads are not sequentialized, so Detcore does not name procfs files"
8329                    .into(),
8330            )
8331            .await;
8332            return ProcfsEntry::Unknown;
8333        }
8334        let tid = guest.tid().as_raw();
8335        let mounts = match procfs_inode::procfs_mounts(tid, stat.dev, false) {
8336            Ok(Some(mounts)) => mounts,
8337            // No procfs mount in the guest's mount table is on the device, but
8338            // a procfs file can be, opened outside the guest's mounts: one
8339            // inherited from Hermit's own `/proc`, or received through
8340            // SCM_RIGHTS. It has no path within the guest's procfs, so it goes
8341            // unnamed. Its filesystem type tells.
8342            Ok(None) => {
8343                let on_procfs = Self::with_object_link(guest, target, |link| {
8344                    procfs_inode::is_on_procfs(link, stat.dev, stat.inode)
8345                })
8346                .await;
8347                return match on_procfs {
8348                    Ok(false) => ProcfsEntry::NotProcfs,
8349                    Ok(true) => {
8350                        Self::record_procfs_loss(
8351                            guest,
8352                            "a procfs file outside the guest's procfs mounts".into(),
8353                        )
8354                        .await;
8355                        ProcfsEntry::Unnamed
8356                    }
8357                    Err(reason) => {
8358                        Self::record_procfs_loss(guest, reason).await;
8359                        ProcfsEntry::Unknown
8360                    }
8361                };
8362            }
8363            Err(error) => {
8364                Self::record_procfs_loss(
8365                    guest,
8366                    format!(
8367                        "cannot read the guest's mount table: {}",
8368                        crate::util::describe_io_error(&error)
8369                    ),
8370                )
8371                .await;
8372                return ProcfsEntry::Unknown;
8373            }
8374        };
8375        let (canonical, mount_id) = match Self::procfs_canonical_path(guest, stat, target).await {
8376            Ok(found) => found,
8377            Err(reason) => {
8378                Self::record_procfs_loss(guest, reason).await;
8379                return ProcfsEntry::Unnamed;
8380            }
8381        };
8382        let reread = || procfs_inode::procfs_mounts(tid, stat.dev, true);
8383        match procfs_inode::path_within(
8384            &mounts,
8385            mount_id,
8386            &canonical,
8387            reread,
8388            procfs_inode::mount_root,
8389        ) {
8390            Ok(within) => ProcfsEntry::At(within),
8391            // The guest reached the file through a mount that its mount
8392            // table, read again, does not list at a mount point where Detcore
8393            // finds the mount: one outside the guest's root, or one whose
8394            // mount point reads in another frame than the file's path.
8395            Err(reason) => {
8396                Self::record_procfs_loss(guest, reason).await;
8397                ProcfsEntry::Unnamed
8398            }
8399        }
8400    }
8401
8402    /// The canonical path of the procfs file `stat` describes, which the
8403    /// guest named as `target`, from a magic link to it (see
8404    /// [`Self::with_object_link`]), if that is still the file `stat`
8405    /// describes, and the ID of the mount it was reached through. An entry
8406    /// the host rebuilt between the guest's stat and an `O_PATH` open, a
8407    /// window of one injected call, is not, and goes unnamed.
8408    async fn procfs_canonical_path<G: Guest<Self>>(
8409        guest: &mut G,
8410        stat: &DetStat,
8411        target: StatTarget<'_>,
8412    ) -> Result<(PathBuf, u64), String> {
8413        Self::with_object_link(guest, target, |link| {
8414            procfs_inode::inspect_link(link, stat.dev, stat.inode)
8415        })
8416        .await
8417    }
8418
8419    /// Run `inspect` on a magic link to the file the guest named as
8420    /// `target`: that of the descriptor or working directory in the guest
8421    /// thread's `/proc/<tid>`. For a path, Detcore opens an `O_PATH`
8422    /// descriptor in the guest with the guest's own path, directory and
8423    /// flags, which resolves `self` and `thread-self` to the guest, and
8424    /// closes it again (see [`Self::open_object_descriptor`] and
8425    /// [`Self::close_object_descriptor`]). An error is the reason Detcore
8426    /// learned nothing, or that the guest's descriptors may have changed.
8427    ///
8428    /// It runs only with sequentialized threads (see
8429    /// [`Self::name_procfs_entry`]). Only then do the open, the look at the
8430    /// link and the close run in one turn, and does the guest's descriptor or
8431    /// working directory lead to one file throughout; otherwise another guest
8432    /// thread can close the descriptor Detcore opened and take its number for
8433    /// one of its own in between, which Detcore would then read, and close.
8434    async fn with_object_link<G: Guest<Self>, R>(
8435        guest: &mut G,
8436        target: StatTarget<'_>,
8437        inspect: impl FnOnce(&Path) -> Result<R, String>,
8438    ) -> Result<R, String> {
8439        let tid = guest.tid().as_raw();
8440        match target {
8441            StatTarget::Descriptor(fd) => inspect(Path::new(&format!("/proc/{tid}/fd/{fd}"))),
8442            StatTarget::Cwd => inspect(Path::new(&format!("/proc/{tid}/cwd"))),
8443            StatTarget::Overwritten => Err("the call's result overwrote the guest's path".into()),
8444            StatTarget::Path {
8445                dirfd,
8446                path,
8447                follow,
8448            } => {
8449                let mut flags = OFlag::O_PATH | OFlag::O_CLOEXEC;
8450                if !follow {
8451                    flags |= OFlag::O_NOFOLLOW;
8452                }
8453                let open = syscalls::Openat::new()
8454                    .with_dirfd(dirfd)
8455                    .with_path(path)
8456                    .with_flags(flags);
8457                let fd = Self::open_object_descriptor(guest, open).await?;
8458                let found = inspect(Path::new(&format!("/proc/{tid}/fd/{fd}")));
8459                Self::close_object_descriptor(guest, fd).await?;
8460                found
8461            }
8462        }
8463    }
8464
8465    /// Open the `O_PATH` descriptor `open` describes in the guest. An open
8466    /// that opened no descriptor and reported a restart or `EINTR` (see
8467    /// [`procfs_inode::read_open`]) is tried again, but only
8468    /// `OBJECT_DESCRIPTOR_ATTEMPTS` times, as a seccomp filter the guest
8469    /// inherited can return a restart every time without running the call.
8470    async fn open_object_descriptor<G: Guest<Self>>(
8471        guest: &mut G,
8472        open: syscalls::Openat,
8473    ) -> Result<RawFd, String> {
8474        let mut last = Errno::EINTR.to_string();
8475        for _ in 0..OBJECT_DESCRIPTOR_ATTEMPTS {
8476            match procfs_inode::read_open(guest.inject(open).await) {
8477                procfs_inode::Injected::Ran(fd) => return Ok(fd),
8478                procfs_inode::Injected::NotRun(reported) => last = reported,
8479                procfs_inode::Injected::Failed(reason) => return Err(reason),
8480            }
8481        }
8482        Err(format!(
8483            "cannot open the guest's path again: {last} in each of {OBJECT_DESCRIPTOR_ATTEMPTS} attempts"
8484        ))
8485    }
8486
8487    /// Close the `O_PATH` descriptor `fd` that Detcore opened in the guest. A
8488    /// close that did not run (see [`procfs_inode::read_close`]) is tried
8489    /// again, but only `OBJECT_DESCRIPTOR_ATTEMPTS` times. One that failed
8490    /// leaves the descriptor open, where it changes the numbers the guest's
8491    /// later descriptors take, so it is an error.
8492    async fn close_object_descriptor<G: Guest<Self>>(
8493        guest: &mut G,
8494        fd: RawFd,
8495    ) -> Result<(), String> {
8496        let close = syscalls::Close::new().with_fd(fd);
8497        for _ in 0..OBJECT_DESCRIPTOR_ATTEMPTS {
8498            match procfs_inode::read_close(guest.inject(close).await) {
8499                procfs_inode::Injected::Ran(()) => return Ok(()),
8500                procfs_inode::Injected::NotRun(_) => {}
8501                procfs_inode::Injected::Failed(reason) => return Err(reason),
8502            }
8503        }
8504        Err(format!(
8505            "close of the guest's O_PATH descriptor did not run in {OBJECT_DESCRIPTOR_ATTEMPTS} attempts"
8506        ))
8507    }
8508
8509    /// Records the determinism loss of a procfs entry Detcore could not name,
8510    /// once per process, through the global tool, whose process is the one
8511    /// whose losses verification reads under every backend.
8512    async fn record_procfs_loss<G: Guest<Self>>(guest: &mut G, reason: String) {
8513        static RECORDED: AtomicBool = AtomicBool::new(false);
8514        if !RECORDED.swap(true, Ordering::Relaxed) {
8515            report_determinism_loss(guest, format!("procfs inode numbers: {reason}")).await;
8516        }
8517    }
8518
8519    // Determinize stat by doing:
8520    //   - using virtual inode instead of real inodes. The virtual inodes
8521    //     increase monolitically and won't be re-used (like ext4)
8522    //   - use logical modtime which could be used by program like GNU make
8523    //     to determine file changes. A file first seen with a canonical host
8524    //     mtime (`CANONICAL_FILE_MTIME_SECONDS`, e.g. the Nix store's 1) keeps
8525    //     it; any other first-seen file reports the epoch.
8526    //   - atime, ctime and btime always report the epoch: the kernel sets ctime
8527    //     and btime itself, so even for a Nix store file they are real
8528    //     timestamps, and Hermit keeps no per-file atime.
8529    async fn determinize_stat<G, S>(
8530        &self,
8531        guest: &mut G,
8532        stat: S,
8533        inode_override: Option<DetInode>,
8534        procfs: ProcfsEntry,
8535    ) -> Result<DetStat, Error>
8536    where
8537        G: Guest<Self>,
8538        S: Into<DetStat>,
8539    {
8540        let cfg = guest.config().clone();
8541
8542        let mut stat: DetStat = stat.into();
8543        // Detcore's placeholder, however the guest reached it: the rendered
8544        // file it stands in for.
8545        if inode_override.is_none()
8546            && !cfg.recordreplay_modes
8547            && let Some(path) = rendered_procfs::placeholder_identity(stat.dev, stat.inode)
8548        {
8549            return self.rendered_metadata(guest, path).await;
8550        }
8551        let (d_ino, global_mtime) = match inode_override {
8552            // The container's stdio streams have fixed inodes and always
8553            // report the epoch: whatever backs them on the host (a pipe, a
8554            // terminal, a redirected file) is not part of the guest's view.
8555            Some(inode) => {
8556                let nanos = cfg
8557                    .epoch
8558                    .timestamp_nanos_opt()
8559                    .expect("epoch cannot be represented in nanoseconds")
8560                    as u64;
8561                (inode, LogicalTime::from_nanos(nanos))
8562            }
8563            None => {
8564                // statx fills stx_mtime only when it reports STATX_MTIME.
8565                let observed = if stat.mask.contains(StatxMask::STATX_MTIME) {
8566                    ObservedMtime::from_host_mtime(stat.mtime.tv_sec, stat.mtime.tv_nsec)
8567                } else {
8568                    ObservedMtime::Unobserved
8569                };
8570                // A file with a link cannot be one a retired mapping describes:
8571                // Linux refuses to link an unlinked file again (only an
8572                // `O_TMPFILE` file, which is never retired, may get a name).
8573                // So a nonzero link count is a name sighting however the file
8574                // was reached, by path, descriptor or working directory, and a
8575                // zero count (`fstat` after `unlink`, `/proc/self/fd/N`) is not.
8576                let sighting = if stat.mask.contains(StatxMask::STATX_NLINK) && stat.nlink > 0 {
8577                    InodeSighting::Name
8578                } else {
8579                    InodeSighting::Descriptor
8580                };
8581                // A procfs root counts the host's processes as its links.
8582                // Report 1, which file systems that do not count a
8583                // directory's links report, so that a walker such as `find`
8584                // infers nothing from it.
8585                if procfs.is_procfs()
8586                    && stat.inode == procfs_inode::PROC_ROOT_INO
8587                    && stat.mode & libc::S_IFMT == libc::S_IFDIR
8588                    && stat.mask.contains(StatxMask::STATX_NLINK)
8589                {
8590                    stat.nlink = 1;
8591                }
8592                match rendered_entry(&procfs, &stat, &cfg, self.rendered_files(guest)) {
8593                    // A file Detcore renders, reached through a spelling the
8594                    // kernel resolved (a symbolic link): the number its path
8595                    // names, and the epoch.
8596                    Some(path) => {
8597                        let nanos = cfg
8598                            .epoch
8599                            .timestamp_nanos_opt()
8600                            .expect("epoch cannot be represented in nanoseconds")
8601                            as u64;
8602                        (
8603                            DetInode::mint(procfs_inode::rendered_inode(path)),
8604                            LogicalTime::from_nanos(nanos),
8605                        )
8606                    }
8607                    None => {
8608                        determinize_inode_observing_mtime(
8609                            guest,
8610                            stat.raw_inode(),
8611                            procfs.name(stat.dev),
8612                            observed,
8613                            sighting,
8614                        )
8615                        .await
8616                    }
8617                }
8618            }
8619        };
8620        stat.inode = d_ino.as_raw(); // Reveal only the deterministic inode.
8621
8622        // AUTONOMOUS-BOT-IMPLEMENTED
8623        // TODO-HUMAN-REVIEW(PR-1056): Deterministic st_dev remapping.
8624        // The raw st_dev leaks the kernel's host-wide anonymous block-device
8625        // number for procfs/sysfs/tmpfs mounts, which drifts between runs (and
8626        // between the two runs of `--verify`). Reveal only a deterministic
8627        // device id.
8628        let host_device = stat.dev;
8629        stat.dev = determinize_device(guest, stat.dev).await;
8630
8631        // A directory's size is whatever its file system makes of its
8632        // entries: btrfs sums the names' lengths, tmpfs counts entries, ext4
8633        // rounds up to its blocks. So it changes whenever any process adds or
8634        // removes an entry, and differs between file systems. Builds stat
8635        // every ancestor of their working directory (kbuild, configure,
8636        // cargo, CMake's look at $HOME), so the host's value broke
8637        // `--verify --verify-strict` of ordinary builds on a shared machine
8638        // and reproducibility across hosts
8639        // (https://github.com/rrnewton/hermit/issues/4162). Report one
8640        // 4096-byte block, as ext4 does for a small directory, whatever the
8641        // directory holds; btrfs reports an empty directory as 0, so even
8642        // an empty one is set. A procfs directory keeps the host's value
8643        // (0, or a descriptor count for /proc/<pid>/fd), which Detcore
8644        // already virtualizes there. Only a proved procfs directory keeps
8645        // it: one whose entry Detcore names (`ProcfsEntry`, on the backends
8646        // whose guest threads are host tasks) or KVM's synthetic procfs
8647        // (`procfs_inode::is_backend_procfs_device`). Its stat fields alone
8648        // prove nothing: an anonymous device with 1024-byte blocks is also
8649        // devpts, autofs or a FUSE mount reporting those blocks (Codex
8650        // re-check of https://github.com/rrnewton/hermit/pull/4369). Under
8651        // DBT, where Detcore names no procfs entries, such a directory keeps
8652        // the host's value unproved
8653        // (`procfs_inode::unprovable_procfs_signature`). sysfs and cgroup
8654        // directories, which Linux also reports as 0, report 4096.
8655        if stat.mode & libc::S_IFMT == libc::S_IFDIR
8656            && stat.mask.contains(StatxMask::STATX_SIZE)
8657            && !procfs.is_procfs()
8658            && !procfs_inode::is_backend_procfs_device(
8659                &guest.config().backend,
8660                host_device,
8661                stat.blksize,
8662            )
8663            && !procfs_inode::unprovable_procfs_signature(
8664                &guest.config().backend,
8665                guest.thread_state().physical_tid,
8666                host_device,
8667                stat.blksize,
8668            )
8669        {
8670            stat.size = 4096;
8671            if stat.mask.contains(StatxMask::STATX_BLOCKS) {
8672                stat.blocks = 8;
8673            }
8674        }
8675
8676        let epoch_tp = Timespec {
8677            tv_sec: cfg.epoch.timestamp(),
8678            tv_nsec: cfg.epoch.timestamp_subsec_nanos() as i64,
8679        };
8680
8681        let mtime: Timespec = global_mtime.into();
8682        stat.atime = epoch_tp;
8683        stat.ctime = epoch_tp;
8684        stat.btime = epoch_tp;
8685
8686        stat.mtime = mtime;
8687
8688        Ok(stat)
8689    }
8690
8691    /// Handles all stat syscalls.
8692    pub async fn handle_stat_family<G: Guest<Self>>(
8693        &self,
8694        guest: &mut G,
8695        call: StatFamily,
8696    ) -> Result<i64, Error> {
8697        if guest.config().virtualize_metadata {
8698            // NB: let kernel handle error codes, it's not easy to do so without
8699            // kernel because there're many corner cases. i.e.: even access
8700            // filepath from tracer may cause tracer to hang under certain fuse
8701            // filesystem (squashfs_ll).
8702            // The target is found before the call, which can overwrite its path.
8703            // A procfs file Detcore renders is answered from the path as named,
8704            // as Linux reads the path before it writes the result, once the
8705            // call's own arguments passed.
8706            let target = stat_family_target(&guest.memory(), &call);
8707            if !stat_family_arguments_valid(&guest.memory(), &call) {
8708                if !matches!(self.rendered_procfs_stat(guest, target).await, Ok(None)) {
8709                    return Err(Errno::EINVAL.into());
8710                }
8711            } else if let Some(stat) = self.rendered_procfs_stat(guest, target).await? {
8712                let statptr = call.stat().ok_or(Errno::EFAULT)?;
8713                guest.memory().write_value(statptr.0, &stat.into())?;
8714                return Ok(0);
8715            }
8716            let target = match call.stat() {
8717                Some(result) => target.unless_overwritten(
8718                    &guest.memory(),
8719                    result.0.as_raw(),
8720                    std::mem::size_of::<libc::stat>(),
8721                ),
8722                None => target,
8723            };
8724            Self::inject_translated(guest, Syscall::from(call)).await?;
8725            let statptr = call.stat().ok_or(Errno::EFAULT)?;
8726            let inode_override = target
8727                .descriptor()
8728                .and_then(|fd| stdio_inode_override(guest, fd));
8729            let mut memory = guest.memory();
8730            let stat: libc::stat = memory.read_value(statptr.0)?;
8731            // A placeholder another process made, or an earlier image of this
8732            // one, becomes known by its identity (`determinize_stat`).
8733            if inode_override.is_none() {
8734                let _ = self
8735                    .recognize_placeholder(guest, &DetStat::from(&stat), target)
8736                    .await;
8737            }
8738            let procfs = match inode_override {
8739                Some(_) => ProcfsEntry::NotProcfs,
8740                None => Self::procfs_entry(guest, &DetStat::from(&stat), target).await,
8741            };
8742            let stat = self
8743                .determinize_stat(guest, stat, inode_override, procfs)
8744                .await?;
8745            memory.write_value(statptr.0, &stat.into())?;
8746            Ok(0)
8747        } else {
8748            // A procfs file Detcore renders has no kernel object to ask.
8749            let target = stat_family_target(&guest.memory(), &call);
8750            if !stat_family_arguments_valid(&guest.memory(), &call) {
8751                if !matches!(self.rendered_procfs_stat(guest, target).await, Ok(None)) {
8752                    return Err(Errno::EINVAL.into());
8753                }
8754            } else if let Some(stat) = self.rendered_procfs_stat(guest, target).await? {
8755                let statptr = call.stat().ok_or(Errno::EFAULT)?;
8756                guest.memory().write_value(statptr.0, &stat.into())?;
8757                return Ok(0);
8758            }
8759            Ok(self.record_or_replay(guest, call).await?)
8760        }
8761    }
8762
8763    /// statx system call
8764    pub async fn handle_statx<G: Guest<Self>>(
8765        &self,
8766        guest: &mut G,
8767        call: syscalls::Statx,
8768    ) -> Result<i64, Error> {
8769        // Whether `statx` accepts its arguments, which it checks before it
8770        // looks at any file.
8771        let renderable = statx_arguments_valid(
8772            call.flags().bits(),
8773            call.mask().bits(),
8774            names_no_path(&guest.memory(), call.path(), call.flags()),
8775        );
8776        if guest.config().virtualize_metadata {
8777            // NB: let kernel handle error codes, it's not easy to do so without kernel
8778            // because there're many corner cases. i.e.: even access filepath from tracer
8779            // may cause tracer to hang under certain fuse filesystem (squashfs_ll).
8780            // The target is found before the call, which can overwrite its path.
8781            // A procfs file Detcore renders is answered from the path as named,
8782            // as Linux reads the path before it writes the result, once the
8783            // call's own arguments passed (which `statx` checks before it
8784            // looks up any file).
8785            let target = StatTarget::at(&guest.memory(), call.dirfd(), call.path(), call.flags());
8786            if !renderable {
8787                if !matches!(self.rendered_procfs_stat(guest, target).await, Ok(None)) {
8788                    return Err(Errno::EINVAL.into());
8789                }
8790            } else if let Some(stat) = self.rendered_procfs_stat(guest, target).await? {
8791                return self.write_rendered_statx(guest, call, stat).await;
8792            }
8793            let target = match call.statx() {
8794                Some(result) => target.unless_overwritten(
8795                    &guest.memory(),
8796                    result.0.as_raw(),
8797                    std::mem::size_of::<libc::statx>(),
8798                ),
8799                None => target,
8800            };
8801            // A call that asks for the unique mount ID asks the kernel for the
8802            // classic one: the run's mount-ID pool numbers classic IDs, the
8803            // ones mountinfo and fdinfo show, and the guest's unique ID is
8804            // derived from that number (`fill_statx_mount_id`). Linux fills
8805            // both mount-ID fields in `vfs_statx_path` (v6.12
8806            // fs/stat.c:248-259) after the filesystem's getattr, which sees
8807            // `STATX_MNT_ID` in place of `STATX_MNT_ID_UNIQUE`.
8808            let unique = statx_requested_mask(call) & STATX_MNT_ID_UNIQUE != 0;
8809            Self::inject_translated(guest, Syscall::from(statx_asking_classic_mount_id(call)))
8810                .await?;
8811            let statptr = call.statx().ok_or(Errno::EFAULT)?;
8812            let inode_override = target
8813                .descriptor()
8814                .and_then(|fd| stdio_inode_override(guest, fd));
8815            let mut memory = guest.memory();
8816            let stat: libc::statx = memory.read_value(statptr.0)?;
8817            // A placeholder another process made, or an earlier image of this
8818            // one, becomes known by its identity (`determinize_stat`).
8819            let placeholder = match inode_override {
8820                None => {
8821                    self.recognize_placeholder(guest, &DetStat::from(stat), target)
8822                        .await
8823                }
8824                Some(_) => None,
8825            };
8826            let procfs = match inode_override {
8827                Some(_) => ProcfsEntry::NotProcfs,
8828                None => Self::procfs_entry(guest, &DetStat::from(stat), target).await,
8829            };
8830            // A rendered file reached through any spelling (a symbolic link to
8831            // its descriptor link) is on the guest's procfs mount, not on the
8832            // placeholder's memfd's.
8833            let raw_mount_id = match placeholder {
8834                Some(_) => rendered_procfs::guest_procfs_mount_id().ok(),
8835                None => (stat.stx_mask & libc::STATX_MNT_ID != 0).then_some(stat.stx_mnt_id),
8836            };
8837            let stat = self
8838                .determinize_stat(guest, stat, inode_override, procfs)
8839                .await?;
8840            let mut statx: libc::statx = stat.into();
8841            self.fill_statx_mount_id(guest, &mut statx, raw_mount_id, unique)
8842                .await;
8843            memory.write_value(statptr.0, &statx)?;
8844            Ok(0)
8845        } else {
8846            // A procfs file Detcore renders has no kernel object to ask.
8847            let target = StatTarget::at(&guest.memory(), call.dirfd(), call.path(), call.flags());
8848            // Arguments `statx` refuses before it looks up any file, here a
8849            // file Detcore renders.
8850            if !renderable {
8851                if !matches!(self.rendered_procfs_stat(guest, target).await, Ok(None)) {
8852                    return Err(Errno::EINVAL.into());
8853                }
8854            } else if let Some(stat) = self.rendered_procfs_stat(guest, target).await? {
8855                return self.write_rendered_statx(guest, call, stat).await;
8856            }
8857            Ok(self.record_or_replay(guest, call).await?)
8858        }
8859    }
8860
8861    /// Whether a guest's F_SETFL or FIONBIO on this descriptor changes only its
8862    /// logical (guest-visible) O_NONBLOCK, leaving it physically nonblocking for
8863    /// the scheduler's nonblockize-and-retry.
8864    ///
8865    /// Outside record/replay that holds for every scheduler-managed type. In
8866    /// record/replay it holds only for a container-internal channel that is
8867    /// already physically nonblocking: a pipe, which is how `handle_pipe2`
8868    /// leaves every guest-created pipe in both phases, or a socketpair endpoint,
8869    /// which is how `handle_socketpair` leaves both ends. Forwarding the guest's
8870    /// clear would make the recording's next read on that channel a blocking
8871    /// read on an fd that `syscall_targets_internal_fd` calls internal, which
8872    /// deadlocks the sequentialized scheduler while the writer waits for its
8873    /// turn. Both phases take the same branch, because `fd_type`,
8874    /// `socketpair_endpoint` and `physically_nonblocking` are Detcore
8875    /// bookkeeping that record and replay evolve identically: an F_SETFL is
8876    /// still recorded and replayed, with the kernel given `flags | O_NONBLOCK`
8877    /// in record and the recorded result returned in replay; a FIONBIO returns
8878    /// before `record_or_replay`, so neither phase records or applies it. Other
8879    /// sockets and eventfds stay external in record/replay. A pipe whose
8880    /// physical O_NONBLOCK came from the guest rather than from Detcore is also
8881    /// kept nonblocking; in record/replay the only such pipes are `pipe2` pipes,
8882    /// which Detcore has already made nonblocking.
8883    fn keeps_physically_nonblocking(
8884        &self,
8885        fd_type: FdType,
8886        socketpair_endpoint: bool,
8887        physically_nonblocking: bool,
8888        inherited_external_read: bool,
8889    ) -> bool {
8890        self.cfg.use_nonblocking_sockets()
8891            && !inherited_external_read
8892            && match fd_type {
8893                FdType::Pipe => !self.cfg.recordreplay_modes || physically_nonblocking,
8894                FdType::Socket if socketpair_endpoint => {
8895                    !self.cfg.recordreplay_modes || physically_nonblocking
8896                }
8897                FdType::Socket | FdType::Eventfd => !self.cfg.recordreplay_modes,
8898                _ => false,
8899            }
8900    }
8901
8902    /// fcntl system call
8903    pub async fn handle_fcntl<G: Guest<Self>>(
8904        &self,
8905        guest: &mut G,
8906        call: syscalls::Fcntl,
8907    ) -> Result<i64, Error> {
8908        let fd = call.fd();
8909        // Before anything else, so a refused call has no other effect.
8910        let (call, _owner_copy) = self.screen_fcntl_owner(guest, call).await?;
8911        // The owner of an asynchronous-I/O descriptor may be any process or
8912        // process group, and Linux signals it when data arrives, at a moment
8913        // set by host timing. Record the signals in this turn, before the call
8914        // reaches the kernel, for every process of the container, and never
8915        // forget them (`Scheduler::record_host_timed_signals`).
8916        let signals = fcntl_host_timed_signals(call.cmd());
8917        if signals & kernel_sigset_bit(libc::SIGALRM) != 0 {
8918            refuse_sigalrm(guest, SigalrmControl::ArmProducer).await?;
8919        }
8920        // A lease makes another process's open of the file wait for the
8921        // lease break, interruptibly, with no scheduler admission.
8922        if matches!(call.cmd(), F_SETLEASE(lease) if lease != libc::F_UNLCK) {
8923            refuse_sigalrm(guest, SigalrmControl::ArmProducer).await?;
8924        }
8925        if signals != 0
8926            && bundled_signal_facts::host_timed_signal_sources_are_physical(&guest.config().backend)
8927        {
8928            record_host_timed_signals(guest, HostTimedSignalScope::Container, signals).await;
8929        }
8930        let o_cloexec = match call.cmd() {
8931            F_DUPFD_CLOEXEC(_) => OFlag::O_CLOEXEC,
8932            _ => OFlag::empty(),
8933        };
8934        match call.cmd() {
8935            F_GETFL => {
8936                let physical_flags = self.record_or_replay(guest, call).await?;
8937                let (logical_nonblocking, rendered_nofollow) =
8938                    guest.thread_state().with_detfd(fd, |detfd| {
8939                        (
8940                            detfd.is_nonblocking(),
8941                            detfd.procfs_rendered_path().is_some()
8942                                && detfd.status_flags() & libc::O_NOFOLLOW != 0,
8943                        )
8944                    })?;
8945                // A rendered procfs file's placeholder was reopened without
8946                // the guest's `O_NOFOLLOW`, which Linux keeps.
8947                let physical_flags = if rendered_nofollow {
8948                    physical_flags | i64::from(libc::O_NOFOLLOW)
8949                } else {
8950                    physical_flags
8951                };
8952                let nonblocking = i64::from(OFlag::O_NONBLOCK.bits());
8953                if logical_nonblocking {
8954                    Ok(physical_flags | nonblocking)
8955                } else {
8956                    Ok(physical_flags & !nonblocking)
8957                }
8958            }
8959            F_SETFL(flags) => {
8960                let (fd_type, socketpair_endpoint, physically_nonblocking, inherited_external_read) =
8961                    guest.thread_state().with_detfd(fd, |detfd| {
8962                        (
8963                            detfd.ty(),
8964                            detfd.is_socketpair_endpoint(),
8965                            detfd.physically_nonblocking(),
8966                            detfd.inherited_external_read().is_some(),
8967                        )
8968                    })?;
8969                let force_nonblocking = self.keeps_physically_nonblocking(
8970                    fd_type,
8971                    socketpair_endpoint,
8972                    physically_nonblocking,
8973                    inherited_external_read,
8974                );
8975                let physical_flags = if force_nonblocking {
8976                    flags | OFlag::O_NONBLOCK.bits()
8977                } else {
8978                    flags
8979                };
8980                let result = self
8981                    .record_or_replay(guest, call.with_cmd(F_SETFL(physical_flags)))
8982                    .await?;
8983                guest.thread_state().with_detfd(fd, |detfd| {
8984                    // Record the guest's *logical* status flags (derives logical
8985                    // nonblocking); when we forced O_NONBLOCK physically without the
8986                    // guest asking, mark the description physically nonblocking too.
8987                    detfd.set_status_flags(flags);
8988                    if force_nonblocking {
8989                        detfd.set_physically_nonblocking();
8990                    }
8991                })?;
8992                Ok(result)
8993            }
8994            F_DUPFD(_) | F_DUPFD_CLOEXEC(_) => {
8995                let newfd = self.record_or_replay(guest, call).await? as RawFd;
8996                let lock_tracked = self.lock_tracked_descriptions(guest, newfd..=newfd);
8997                let replaced = guest.thread_state_mut().dup_fd(fd, newfd, o_cloexec)?;
8998                if let Some(open_file_id) = replaced {
8999                    self.release_port_for_open_file(guest, open_file_id).await;
9000                }
9001                self.report_lock_references(guest, lock_tracked).await;
9002                Ok(newfd as i64)
9003            }
9004            F_SETFD(flags) => {
9005                let result = self.record_or_replay(guest, call).await?;
9006                guest.thread_state().with_detfd(fd, |detfd| {
9007                    detfd.set_cloexec(flags & libc::FD_CLOEXEC != 0);
9008                })?;
9009                Ok(result)
9010            }
9011            // AUTONOMOUS-BOT-IMPLEMENTED
9012            // TODO-HUMAN-REVIEW(PR-2568): Review refusing guest pipe growth.
9013            // Raising a pipe above the pinned capacity is the ONE syscall that
9014            // defeats the pin, and whether it succeeds is decided by the host's
9015            // `/proc/sys/fs/pipe-max-size`. On a default host (1 MiB ceiling)
9016            // the guest gets a 1048576-byte pipe; on a hardened host (64 KiB)
9017            // the identical guest gets EPERM and keeps 8192. Same binary, same
9018            // `--strict`, guest-visible return value and pipe capacity decided
9019            // by a host sysctl -- a determinism leak by this project's own
9020            // definition, and it survived because the capacity pin was applied
9021            // at creation and never defended afterwards.
9022            //
9023            // Refuse deterministically instead of asking Linux. EPERM is the
9024            // errno Linux itself returns when that ceiling binds, so the guest
9025            // sees a shape it must already handle rather than a novel one, and
9026            // it is the answer the hardened host would have given.
9027            //
9028            // SHRINKING IS DELIBERATELY LEFT ALONE. It is always permitted for
9029            // an unprivileged process, it is process-local with no host-derived
9030            // input, and `tests/c/pipe_capacity.c` locks
9031            // it as a guest-visible contract: that fixture shrinks to one page
9032            // and requires the value to round-trip. Clamping every
9033            // `F_SETPIPE_SZ` to the pinned capacity would break that contract
9034            // while fixing nothing that is actually nondeterministic.
9035            // A host-backed pipe's capacity is host state
9036            // (`reported_pipe_capacity`); the guest reads it no larger than
9037            // the ceiling it may raise a pipe to.
9038            F_GETPIPE_SZ => Ok(reported_pipe_capacity(
9039                self.record_or_replay(guest, call).await?,
9040            )),
9041            F_SETPIPE_SZ(requested) if pipe_capacity_request_exceeds_ceiling(requested) => {
9042                trace!(
9043                    "[detcore] refusing F_SETPIPE_SZ({}) above the deterministic pipe ceiling {}",
9044                    requested, DETERMINISTIC_PIPE_CAPACITY_BYTES
9045                );
9046                Err(Errno::EPERM.into())
9047            }
9048            // An OFD lock belongs to its open file description, and Linux
9049            // shows it in `/proc/locks` from every PID namespace, the host's
9050            // included, as owner -1. After each call, the description's own
9051            // fdinfo says which locks it holds (`procfs::locks`); the lock
9052            // itself is the kernel's, as for POSIX locks.
9053            F_OFD_SETLK(_) | F_OFD_SETLKW(_) => {
9054                let result = self.record_or_replay(guest, call).await?;
9055                self.refresh_description_locks(guest, fd, LockCall::Fcntl)
9056                    .await?;
9057                Ok(result)
9058            }
9059            _ => {
9060                trace!(
9061                    "[detcore-finishme]: fcntl unhandled cases: {:?}",
9062                    call.cmd()
9063                );
9064                Ok(self.record_or_replay(guest, call).await?)
9065            }
9066        }
9067    }
9068
9069    /// Record which OFD and flock locks the open file description `fd` names
9070    /// holds now, after a call through it that may have changed them
9071    /// (`procfs::locks`), from the `lock:` lines of its fdinfo, which name
9072    /// exactly that description's locks with the device `/proc/locks`
9073    /// prints. A descriptor Detcore keeps no model of is left out.
9074    ///
9075    /// The fdinfo is read only through an anchor proved to be procfs, by a
9076    /// sequence of calls through the recorder ([`Self::read_own_fdinfo`]):
9077    /// the `/proc/locks` rows a replay filters are the recording's, and
9078    /// replay takes no real lock, so the locks they are matched against must
9079    /// be the recording's too. A recording therefore holds, after each such
9080    /// call, the anchor's `openat`, `fstatfs` and `fstat`, the entry's
9081    /// `openat2`, `fstatfs` and `fstat`, the reads and two `close`s
9082    /// (hermit-cli's `RECORD_VERSION` names the change).
9083    ///
9084    /// The guest's `call` is never affected. A read that fails for a cause
9085    /// the guest's own filesystem view or the backend decides (no `/proc`,
9086    /// not procfs, an entry outside it or across a mount, a backend's
9087    /// refusal) makes the description untrackable: it contributes no lock. A
9088    /// read that fails for ambient or resource state (a full descriptor table
9089    /// or file table, no memory, an interruption, an I/O error, a kernel
9090    /// without `openat2`, a permission refusal) leaves its locks unknown, and
9091    /// a later `/proc/locks` read
9092    /// refuses while a guest table references the description
9093    /// (`procfs::locks::LockLedger::unknown`).
9094    ///
9095    /// A lock or unlock through a descriptor whose description the ledger
9096    /// may know under another identity (one Detcore keeps no model of, such
9097    /// as a descriptor received over `SCM_RIGHTS` on ptrace, or one an
9098    /// in-guest backend registered on reception) can leave that other
9099    /// identity's entry stale, so no lock on that file's inode number counts
9100    /// from then on (`procfs::locks::LockLedger::alias_inode`): hidden, never
9101    /// a host's row admitted. If that descriptor's fdinfo cannot be read for
9102    /// ambient or resource state, every later `/proc/locks` read refuses
9103    /// instead ([`Self::note_alias`]).
9104    pub(crate) async fn refresh_description_locks<G: Guest<Self>>(
9105        &self,
9106        guest: &mut G,
9107        fd: RawFd,
9108        call: LockCall,
9109    ) -> Result<(), Error> {
9110        let model = guest.thread_state().with_detfd(fd, |detfd| {
9111            detfd.set_lock_tracked();
9112            if call == LockCall::Recvmsg {
9113                detfd.set_received_for_locks();
9114            }
9115            if call == LockCall::Fcntl {
9116                detfd.set_may_hold_ofd_lock();
9117            }
9118            (detfd.open_file_id(), detfd.is_received_for_locks())
9119        });
9120        let Ok((open_file, received)) = model else {
9121            if call.changes_locks() {
9122                let fdinfo = self.read_own_fdinfo(guest, fd, call.name()).await?;
9123                Self::note_alias(guest, &fdinfo).await;
9124            }
9125            return Ok(());
9126        };
9127        let fdinfo = self.read_own_fdinfo(guest, fd, call.name()).await?;
9128        if received && call.changes_locks() {
9129            Self::note_alias(guest, &fdinfo).await;
9130        }
9131        let held = matches!(&fdinfo, FdinfoRead::Contents(_));
9132        let locks = match fdinfo {
9133            FdinfoRead::Contents(contents) => {
9134                Ok(crate::procfs::locks::held_locks_in_fdinfo(&contents))
9135            }
9136            FdinfoRead::Unknown(reason) => Err(reason),
9137            // Hidden, never admitted: the description contributes no lock
9138            // until a later read through a proved procfs.
9139            FdinfoRead::Untrackable(reason) => {
9140                info!("[detcore] /proc/locks: {reason}; its locks are not shown");
9141                Ok(Vec::new())
9142            }
9143        };
9144        if !held
9145            || locks
9146                .as_ref()
9147                .is_ok_and(|locks| locks.iter().any(|lock| lock.class == "OFDLCK"))
9148        {
9149            let _ = guest
9150                .thread_state()
9151                .with_detfd(fd, |detfd| detfd.set_may_hold_ofd_lock());
9152        }
9153        let slots = guest.thread_state().slots_naming(open_file);
9154        crate::tool_global::note_description_locks(guest, open_file, locks, slots).await;
9155        Ok(())
9156    }
9157
9158    /// After a lock or unlock through a descriptor whose description the
9159    /// ledger may know under another identity: no lock on its inode number
9160    /// counts from now on (`procfs::locks::LockLedger::alias_inode`). If its
9161    /// fdinfo could not be read for ambient or resource state, which
9162    /// identities it changed is unknown, and every later `/proc/locks`
9163    /// snapshot is refused by name (`procfs::locks::LockLedger::refuse`); if
9164    /// the guest's `/proc` could not be proved to be procfs, no lock counts
9165    /// at all (an inode of `None`), which only hides.
9166    async fn note_alias<G: Guest<Self>>(guest: &mut G, fdinfo: &FdinfoRead) {
9167        match fdinfo {
9168            FdinfoRead::Unknown(reason) => {
9169                crate::tool_global::note_lock_ledger_refused(guest, reason.clone()).await;
9170            }
9171            FdinfoRead::Contents(_) | FdinfoRead::Untrackable(_) => {
9172                crate::tool_global::note_aliased_inode(guest, fdinfo.inode()).await;
9173            }
9174        }
9175    }
9176
9177    /// The descriptions named by the slots `fds` of this thread's table
9178    /// whose locks `procfs::locks::LockLedger` follows, taken before a close
9179    /// or replacement of those slots.
9180    fn lock_tracked_descriptions<G: Guest<Self>>(
9181        &self,
9182        guest: &G,
9183        fds: std::ops::RangeInclusive<RawFd>,
9184    ) -> Vec<OpenFileId> {
9185        let thread = guest.thread_state();
9186        let candidates = if fds.start() == fds.end() {
9187            vec![*fds.start()]
9188        } else {
9189            thread
9190                .open_fds()
9191                .into_iter()
9192                .filter(|fd| fds.contains(fd))
9193                .collect()
9194        };
9195        let mut tracked = candidates
9196            .into_iter()
9197            .filter_map(|fd| {
9198                thread
9199                    .with_detfd(fd, |detfd| {
9200                        detfd.is_lock_tracked().then(|| detfd.open_file_id())
9201                    })
9202                    .ok()
9203                    .flatten()
9204            })
9205            .collect::<Vec<_>>();
9206        tracked.sort();
9207        tracked.dedup();
9208        tracked
9209    }
9210
9211    /// After a close or replacement of slots that named `descriptions`,
9212    /// report how many slots of this thread's table still name each
9213    /// (`procfs::locks::LockLedger::release`).
9214    async fn report_lock_references<G: Guest<Self>>(
9215        &self,
9216        guest: &mut G,
9217        descriptions: Vec<OpenFileId>,
9218    ) {
9219        for open_file in descriptions {
9220            let remaining = guest.thread_state().slots_naming(open_file);
9221            crate::tool_global::note_table_released(guest, open_file, remaining).await;
9222        }
9223    }
9224
9225    /// The text of `/proc/thread-self/fdinfo/<fd>`, read through the guest's
9226    /// procfs only, by a recorded sequence staged in a private page mapped for
9227    /// this call and unmapped before it returns ([`Self::read_staged_fdinfo`]).
9228    ///
9229    /// The guest chooses its own root, so a path alone proves nothing: under a
9230    /// `chroot` its `/proc` can be any tree, with any text where an fdinfo is
9231    /// expected, and lock lines that matched a host's lock would admit the
9232    /// host's `/proc/locks` row. So the read starts from an anchor, the
9233    /// guest's `/proc`, which must be procfs (`fstatfs`), opens the entry
9234    /// below it with `openat2`'s `RESOLVE_BENEATH | RESOLVE_NO_XDEV` (no step
9235    /// out of the anchor, no mount crossed, so nothing bound over an entry),
9236    /// and requires the entry itself on procfs and on the anchor's device
9237    /// (`fstatfs` and `fstat` of both). Every step goes through the
9238    /// recorder, so record and replay decide alike. The read holds two
9239    /// descriptors at once, the anchor and the entry. These checks rely on
9240    /// the serialized schedule, under which no other guest thread runs
9241    /// between the calls; with concurrent threads the entry check narrows a
9242    /// `dup2` race on the descriptor numbers but does not close it
9243    /// ([`Self::read_opened_entry`]).
9244    ///
9245    /// No page for a guest that mapped its whole address space away, and a
9246    /// failed step whose errno is ambient or resource state
9247    /// ([`fdinfo_failure_hides`] is false), leave the description's locks
9248    /// unknown ([`FdinfoRead::Unknown`], whose reason names the guest's
9249    /// `call`, [`fdinfo_refusal`]). Every other outcome that gives no proved
9250    /// fdinfo (no `/proc`, not procfs, an entry outside it or across a
9251    /// mount, a device mismatch, a guest-decided or backend-decided errno)
9252    /// makes the description untrackable ([`FdinfoRead::Untrackable`]).
9253    async fn read_own_fdinfo<G: Guest<Self>>(
9254        &self,
9255        guest: &mut G,
9256        fd: RawFd,
9257        call: &str,
9258    ) -> Result<FdinfoRead, Error> {
9259        let mapped = guest
9260            .inject_with_retry(Syscall::Mmap(
9261                syscalls::Mmap::new()
9262                    .with_addr(None)
9263                    .with_len(FDINFO_PAGE)
9264                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
9265                    .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
9266                    .with_fd(-1)
9267                    .with_offset(0),
9268            ))
9269            .await;
9270        let Some(page) = mapped
9271            .ok()
9272            .and_then(|mapped| usize::try_from(mapped).ok())
9273            .filter(|page| *page != 0)
9274        else {
9275            return Ok(FdinfoRead::Unknown(format!(
9276                "after {call} on fd {fd}, Detcore could not map the page it reads that \
9277                 descriptor's fdinfo through ({mapped:?}), so it does not know which locks \
9278                 the description holds"
9279            )));
9280        };
9281        let result = self.read_staged_fdinfo(guest, page, fd).await;
9282        if let Err(errno) = guest
9283            .inject_with_retry(Syscall::Munmap(
9284                syscalls::Munmap::new()
9285                    .with_addr(Addr::from_raw(page))
9286                    .with_len(FDINFO_PAGE),
9287            ))
9288            .await
9289        {
9290            warn!(
9291                "[detcore] could not unmap the transient fdinfo page: {}",
9292                errno
9293            );
9294        }
9295        Ok(match result? {
9296            Ok(contents) => FdinfoRead::Contents(contents),
9297            // Ambient or resource state says nothing about the locks.
9298            Err(FdinfoFailure::Failed(step, errno)) if !fdinfo_failure_hides(errno) => {
9299                FdinfoRead::Unknown(fdinfo_refusal(call, fd, step, errno))
9300            }
9301            Err(FdinfoFailure::Failed(step, errno)) => FdinfoRead::Untrackable(format!(
9302                "after {call} on fd {fd}, the guest's /proc did not give a procfs fdinfo \
9303                 ({step}: {errno})"
9304            )),
9305            Err(FdinfoFailure::NotProcfs(why)) => FdinfoRead::Untrackable(format!(
9306                "after {call} on fd {fd}, the guest's /proc did not give a procfs fdinfo \
9307                 ({why})"
9308            )),
9309        })
9310    }
9311
9312    /// Stop the run, by name, with the policy-refusal exit, because Detcore
9313    /// cannot tell a `/proc/locks` snapshot's guest rows from a host's while a
9314    /// description whose locks it could not read is referenced
9315    /// (`procfs::locks::LockLedger::unknown`).
9316    async fn refuse_lock_bookkeeping<G: Guest<Self>>(&self, guest: &mut G, reason: String) -> ! {
9317        error!("[detcore] {reason}");
9318        crate::tool_global::report_policy_refusal(guest, reason).await;
9319        crate::tool_global::unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT)
9320            .await
9321    }
9322
9323    /// [`Self::read_own_fdinfo`]'s recorded sequence, in the mapped `page`
9324    /// (layout: the path at [`FDINFO_PATH`], `openat2`'s `struct open_how` at
9325    /// [`FDINFO_HOW`], `fstatfs` and `fstat` buffers at [`FDINFO_STAT`], the
9326    /// read buffer from [`FDINFO_READ`]): open the anchor, prove it procfs,
9327    /// open the entry beneath it on its mount, compare devices, read, and
9328    /// close both descriptors.
9329    async fn read_staged_fdinfo<G: Guest<Self>>(
9330        &self,
9331        guest: &mut G,
9332        page: usize,
9333        fd: RawFd,
9334    ) -> Result<Result<Vec<u8>, FdinfoFailure>, Error> {
9335        let path_ptr =
9336            PathPtr::from_ptr((page + FDINFO_PATH) as *const libc::c_char).ok_or(Errno::EFAULT)?;
9337        self.write_fdinfo_path(guest, page, "/proc")?;
9338        let anchor = syscalls::Openat::new()
9339            .with_dirfd(libc::AT_FDCWD)
9340            .with_path(Some(path_ptr))
9341            .with_flags(OFlag::O_PATH | OFlag::O_DIRECTORY | OFlag::O_CLOEXEC)
9342            .with_mode(None);
9343        let anchor = match self.record_or_replay(guest, Syscall::Openat(anchor)).await {
9344            Ok(anchor) => anchor as RawFd,
9345            Err(errno) => return Ok(Err(FdinfoFailure::Failed("open", errno))),
9346        };
9347        let result = self.read_beneath_anchor(guest, page, anchor, fd).await;
9348        if let Err(errno) = self
9349            .record_or_replay(guest, syscalls::Close::new().with_fd(anchor))
9350            .await
9351        {
9352            trace!("[detcore] closing the fdinfo anchor failed: {errno}");
9353        }
9354        result
9355    }
9356
9357    /// [`Self::read_staged_fdinfo`] once its `anchor` is open.
9358    async fn read_beneath_anchor<G: Guest<Self>>(
9359        &self,
9360        guest: &mut G,
9361        page: usize,
9362        anchor: RawFd,
9363        fd: RawFd,
9364    ) -> Result<Result<Vec<u8>, FdinfoFailure>, Error> {
9365        let anchor_device = match self.recorded_procfs_device(guest, page, anchor).await? {
9366            Ok(device) => device,
9367            Err(failure) => return Ok(Err(failure)),
9368        };
9369        self.write_fdinfo_path(guest, page, &format!("thread-self/fdinfo/{fd}"))?;
9370        // struct open_how { u64 flags; u64 mode; u64 resolve; }
9371        let how = (libc::O_RDONLY | libc::O_CLOEXEC) as u64;
9372        let mut open_how = [0u8; FDINFO_HOW_SIZE];
9373        open_how[..8].copy_from_slice(&how.to_ne_bytes());
9374        open_how[16..].copy_from_slice(&FDINFO_RESOLVE.to_ne_bytes());
9375        let how_ptr = AddrMut::<u8>::from_raw(page + FDINFO_HOW).ok_or(Errno::EFAULT)?;
9376        guest.memory().write_exact(how_ptr, &open_how)?;
9377        let opened = match self
9378            .record_or_replay(
9379                guest,
9380                Syscall::from_raw(
9381                    Sysno::openat2,
9382                    procfs_levels::raw_args([
9383                        anchor as usize,
9384                        page + FDINFO_PATH,
9385                        page + FDINFO_HOW,
9386                        FDINFO_HOW_SIZE,
9387                        0,
9388                        0,
9389                    ]),
9390                ),
9391            )
9392            .await
9393        {
9394            Ok(opened) => opened as RawFd,
9395            // The entry is outside the anchor or across a mount.
9396            Err(Errno::EXDEV) => {
9397                return Ok(Err(FdinfoFailure::NotProcfs(
9398                    "the entry is outside /proc or across a mount",
9399                )));
9400            }
9401            Err(errno) => return Ok(Err(FdinfoFailure::Failed("open", errno))),
9402        };
9403        // Closed on every path, the error ones included.
9404        let result = self
9405            .read_opened_entry(guest, page, opened, anchor_device)
9406            .await;
9407        if let Err(errno) = self
9408            .record_or_replay(guest, syscalls::Close::new().with_fd(opened))
9409            .await
9410        {
9411            trace!("[detcore] closing fdinfo failed: {errno}");
9412        }
9413        result
9414    }
9415
9416    /// The text of the `opened` fdinfo entry, once it too is shown to be on
9417    /// procfs and on the anchor's device. The checks run on the entry's own
9418    /// descriptor, so a sibling thread that replaces the anchor's descriptor
9419    /// number between calls (`dup2` of a fake directory) cannot pass them.
9420    ///
9421    /// The defence relies on Detcore's serialized schedule: no other guest
9422    /// thread runs between these injected calls. Under
9423    /// `--no-sequentialize-threads` a sibling could still `dup2` onto the
9424    /// entry's own descriptor number between its checks and the read; the
9425    /// entry check narrows that race but does not close it.
9426    async fn read_opened_entry<G: Guest<Self>>(
9427        &self,
9428        guest: &mut G,
9429        page: usize,
9430        opened: RawFd,
9431        anchor_device: u64,
9432    ) -> Result<Result<Vec<u8>, FdinfoFailure>, Error> {
9433        match self.recorded_procfs_device(guest, page, opened).await? {
9434            Ok(device) if device == anchor_device => {}
9435            Ok(_) => {
9436                return Ok(Err(FdinfoFailure::NotProcfs(
9437                    "the entry is not on /proc's device",
9438                )));
9439            }
9440            Err(failure) => return Ok(Err(failure)),
9441        }
9442        let scratch = AddrMut::<u8>::from_raw(page + FDINFO_READ).ok_or(Errno::EFAULT)?;
9443        match self
9444            .drain_procfs(
9445                guest,
9446                syscalls::Read::new().with_fd(opened),
9447                scratch,
9448                FDINFO_PAGE - FDINFO_READ,
9449                false,
9450            )
9451            .await
9452        {
9453            Ok(contents) => Ok(Ok(contents)),
9454            Err(Error::Errno(errno)) => Ok(Err(FdinfoFailure::Failed("read", errno))),
9455            Err(error) => Err(error),
9456        }
9457    }
9458
9459    /// The device of the descriptor `fd`, once `fstatfs` shows it is on
9460    /// procfs, both through the recorder into the stat buffer of the fdinfo
9461    /// page. A failed call keeps its errno, for the common classification
9462    /// ([`fdinfo_failure_hides`]).
9463    async fn recorded_procfs_device<G: Guest<Self>>(
9464        &self,
9465        guest: &mut G,
9466        page: usize,
9467        fd: RawFd,
9468    ) -> Result<Result<u64, FdinfoFailure>, Error> {
9469        let stat = page + FDINFO_STAT;
9470        if let Err(errno) = self
9471            .record_or_replay(
9472                guest,
9473                Syscall::from_raw(
9474                    Sysno::fstatfs,
9475                    procfs_levels::raw_args([fd as usize, stat, 0, 0, 0, 0]),
9476                ),
9477            )
9478            .await
9479        {
9480            return Ok(Err(FdinfoFailure::Failed("fstatfs", errno)));
9481        }
9482        // `f_type` is the first field of `struct statfs`.
9483        if self.read_fdinfo_word(guest, stat)? != libc::PROC_SUPER_MAGIC as u64 {
9484            return Ok(Err(FdinfoFailure::NotProcfs("not procfs")));
9485        }
9486        if let Err(errno) = self
9487            .record_or_replay(
9488                guest,
9489                Syscall::from_raw(
9490                    Sysno::fstat,
9491                    procfs_levels::raw_args([fd as usize, stat, 0, 0, 0, 0]),
9492                ),
9493            )
9494            .await
9495        {
9496            return Ok(Err(FdinfoFailure::Failed("fstat", errno)));
9497        }
9498        // `st_dev` is the first field of `struct stat`.
9499        Ok(Ok(self.read_fdinfo_word(guest, stat)?))
9500    }
9501
9502    /// Write `path`, NUL-terminated, at the fdinfo page's path slot.
9503    fn write_fdinfo_path<G: Guest<Self>>(
9504        &self,
9505        guest: &mut G,
9506        page: usize,
9507        path: &str,
9508    ) -> Result<(), Error> {
9509        assert!(
9510            path.len() < FDINFO_HOW - FDINFO_PATH,
9511            "fdinfo path {path:?} outgrew its room"
9512        );
9513        let start = AddrMut::<u8>::from_raw(page + FDINFO_PATH).ok_or(Errno::EFAULT)?;
9514        let mut bytes = path.as_bytes().to_vec();
9515        bytes.push(0);
9516        guest.memory().write_exact(start, &bytes)?;
9517        Ok(())
9518    }
9519
9520    /// The first 8 bytes at `address`, a native-endian `u64`.
9521    fn read_fdinfo_word<G: Guest<Self>>(
9522        &self,
9523        guest: &mut G,
9524        address: usize,
9525    ) -> Result<u64, Error> {
9526        let mut word = [0u8; 8];
9527        let start = Addr::<u8>::from_raw(address).ok_or(Errno::EFAULT)?;
9528        guest.memory().read_exact(start, &mut word)?;
9529        Ok(u64::from_ne_bytes(word))
9530    }
9531
9532    /// Refuse with EPERM a call that would make one of Hermit's tasks the
9533    /// owner of a descriptor's signals (https://github.com/rrnewton/hermit/issues/4083).
9534    /// Linux would accept it and later signal Hermit whenever the descriptor is
9535    /// ready; with `F_SETSIG(SIGTERM)` that ended Hermit's run. Refusing is a
9536    /// policy, the answer `pidfd_open` of Hermit's process gets.
9537    async fn refuse_hermit_owner<G: Guest<Self>>(
9538        &self,
9539        guest: &mut G,
9540        fd: RawFd,
9541        command: &str,
9542        owner: libc::c_int,
9543    ) -> Result<(), Error> {
9544        if owner <= 0 || !crate::tool_global::names_hermit_task(guest, None, owner).await {
9545            return Ok(());
9546        }
9547        tracing::info!(
9548            "[detcore, dtid {}] {command} on fd {fd} names task {owner}, one of Hermit's own, \
9549             as the owner of its signals: refused with EPERM \
9550             (https://github.com/rrnewton/hermit/issues/4083)",
9551            guest.thread_state().dettid,
9552        );
9553        Err(Errno::EPERM.into())
9554    }
9555
9556    /// `call`, unless it is an `fcntl` that sets a descriptor's signal owner
9557    /// to one of Hermit's tasks ([`Self::refuse_hermit_owner`]): `F_SETOWN`
9558    /// with a positive pid, or `F_SETOWN_EX` naming a thread (`F_OWNER_TID`)
9559    /// or a process (`F_OWNER_PID`).
9560    ///
9561    /// `F_SETOWN` passes the owner by value; it is read from the raw argument,
9562    /// because the pinned Reverie's typed `FcntlCmd::F_SETOWN` carries none.
9563    /// `F_SETOWN_EX` passes it through guest memory, which another guest
9564    /// thread could change between this check and the kernel's own read, so
9565    /// the `f_owner_ex` is read once and the kernel is handed Detcore's copy,
9566    /// on this thread's scratch stack. An `f_owner_ex` that cannot be read is
9567    /// EFAULT here, as the kernel would answer, rather than a pointer passed
9568    /// on for the kernel to read later. The returned guard keeps the copy
9569    /// alive (SaBRe's scratch stack is an arena it owns) and must be held
9570    /// until the call has run.
9571    async fn screen_fcntl_owner<G: Guest<Self>>(
9572        &self,
9573        guest: &mut G,
9574        call: syscalls::Fcntl,
9575    ) -> Result<(syscalls::Fcntl, Option<<G::Stack as Stack>::StackGuard>), Error> {
9576        // Linux's include/uapi/asm-generic/fcntl.h; the pinned libc lacks them.
9577        const F_OWNER_TID: libc::c_int = 0;
9578        const F_OWNER_PID: libc::c_int = 1;
9579        match call.cmd() {
9580            F_SETOWN => {
9581                let (_, args) = call.into_parts();
9582                self.refuse_hermit_owner(guest, call.fd(), "F_SETOWN", args.arg2 as libc::c_int)
9583                    .await?;
9584                Ok((call, None))
9585            }
9586            F_SETOWN_EX(owner) => {
9587                let owner: Addr<[libc::c_int; 2]> = owner.ok_or(Errno::EFAULT)?.cast();
9588                let copy = guest.memory().read_value(owner)?;
9589                if matches!(copy[0], F_OWNER_TID | F_OWNER_PID) {
9590                    self.refuse_hermit_owner(guest, call.fd(), "F_SETOWN_EX", copy[1])
9591                        .await?;
9592                }
9593                let mut stack = guest.stack().await;
9594                let copied: Addr<[libc::c_int; 2]> = stack.push(copy);
9595                let guard = stack.commit()?;
9596                Ok((call.with_cmd(F_SETOWN_EX(Some(copied.cast()))), Some(guard)))
9597            }
9598            _ => Ok((call, None)),
9599        }
9600    }
9601
9602    /// `call`, unless it is an `ioctl` that sets a descriptor's signal owner
9603    /// to one of Hermit's tasks ([`Self::refuse_hermit_owner`]): `FIOSETOWN`
9604    /// or `SIOCSPGRP` with a positive pid, which set the owner as `F_SETOWN`
9605    /// does. The owner is passed through guest memory, so, as for
9606    /// `F_SETOWN_EX` ([`Self::screen_fcntl_owner`]), it is read once and the
9607    /// kernel is handed Detcore's copy, kept alive by the returned guard;
9608    /// an unreadable one is EFAULT.
9609    async fn screen_ioctl_owner<G: Guest<Self>>(
9610        &self,
9611        guest: &mut G,
9612        call: syscalls::Ioctl,
9613    ) -> Result<(syscalls::Ioctl, Option<<G::Stack as Stack>::StackGuard>), Error> {
9614        let (command, owner) = match call.request() {
9615            syscalls::ioctl::Request::FIOSETOWN(owner) => ("FIOSETOWN", owner),
9616            syscalls::ioctl::Request::SIOCSPGRP(owner) => ("SIOCSPGRP", owner),
9617            _ => return Ok((call, None)),
9618        };
9619        let copy: libc::c_int = guest.memory().read_value(owner.ok_or(Errno::EFAULT)?)?;
9620        self.refuse_hermit_owner(guest, call.fd(), command, copy)
9621            .await?;
9622        let mut stack = guest.stack().await;
9623        let copied = stack.push(copy);
9624        let guard = stack.commit()?;
9625        let request = match call.request() {
9626            syscalls::ioctl::Request::FIOSETOWN(_) => {
9627                syscalls::ioctl::Request::FIOSETOWN(Some(copied))
9628            }
9629            _ => syscalls::ioctl::Request::SIOCSPGRP(Some(copied)),
9630        };
9631        Ok((call.with_request(request), Some(guard)))
9632    }
9633
9634    /// ioctl system call
9635    pub async fn handle_ioctl<G: Guest<Self>>(
9636        &self,
9637        guest: &mut G,
9638        call: syscalls::Ioctl,
9639    ) -> Result<i64, Error> {
9640        let fd = call.fd();
9641        // Setting a virtual timerfd's host tick count would make the host
9642        // disagree with Detcore's count (`crate::syscalls::timerfd`).
9643        if Syscall::Ioctl(call).into_parts().1.arg1 as u64
9644            == crate::syscalls::timerfd::TFD_IOC_SET_TICKS
9645            && crate::syscalls::timerfd::enabled(guest)
9646            && crate::syscalls::timerfd::is_timerfd(guest, fd)
9647        {
9648            crate::syscalls::timerfd::refuse(format_args!(
9649                "ioctl(TFD_IOC_SET_TICKS) on timerfd {fd} would set the host's tick count"
9650            ));
9651        }
9652        // Before anything else, so a refused call has no other effect.
9653        let (call, _owner_copy) = self.screen_ioctl_owner(guest, call).await?;
9654        // As in `handle_fcntl`: an asynchronous-I/O owner, and a session whose
9655        // controlling terminal hangs up, are signalled at a moment set by host
9656        // timing, so hold their signals in every process.
9657        let signals = ioctl_host_timed_signals(call.request());
9658        if signals != 0
9659            && bundled_signal_facts::host_timed_signal_sources_are_physical(&guest.config().backend)
9660        {
9661            record_host_timed_signals(guest, HostTimedSignalScope::Container, signals).await;
9662        }
9663        let (cloexec, nonblocking) = match call.request() {
9664            // AUTONOMOUS-BOT-IMPLEMENTED
9665            // TODO-HUMAN-REVIEW(PR-1142): Review deterministic SIOCETHTOOL rejection.
9666            // Ethernet link state belongs to the host network namespace and can change between
9667            // runs. Match record/replay's established policy instead of exposing that state.
9668            syscalls::ioctl::Request::SIOCETHTOOL(_) => return Err(Errno::ENODEV.into()),
9669            syscalls::ioctl::Request::FIOCLEX => (Some(true), None),
9670            syscalls::ioctl::Request::FIONCLEX => (Some(false), None),
9671            syscalls::ioctl::Request::FIONBIO(value) => {
9672                let enabled = guest.memory().read_value(value.ok_or(Errno::EFAULT)?)? != 0;
9673                (None, Some(enabled))
9674            }
9675            _ => (None, None),
9676        };
9677
9678        // AUTONOMOUS-BOT-IMPLEMENTED
9679        // TODO-HUMAN-REVIEW(PR-1013): Review logical FIONBIO handling for forced fds.
9680        // Detcore already keeps scheduler-managed fds physically nonblocking. Satisfy
9681        // FIONBIO logically instead of forwarding it: some backends cannot apply the
9682        // ioctl to their proxied pipe fd, and clearing it would violate the scheduler's
9683        // nonblockize-and-retry invariant. This mirrors F_SETFL's forced state split.
9684        if let Some(enabled) = nonblocking {
9685            let (fd_type, socketpair_endpoint, physically_nonblocking, inherited_external_read) =
9686                guest.thread_state().with_detfd(fd, |detfd| {
9687                    (
9688                        detfd.ty(),
9689                        detfd.is_socketpair_endpoint(),
9690                        detfd.physically_nonblocking(),
9691                        detfd.inherited_external_read().is_some(),
9692                    )
9693                })?;
9694            if self.keeps_physically_nonblocking(
9695                fd_type,
9696                socketpair_endpoint,
9697                physically_nonblocking,
9698                inherited_external_read,
9699            ) && physically_nonblocking
9700            {
9701                guest.thread_state().with_detfd(fd, |detfd| {
9702                    detfd.set_logical_nonblocking(enabled);
9703                })?;
9704                return Ok(0);
9705            }
9706        }
9707
9708        let result = self.record_or_replay(guest, call).await?;
9709        if cloexec.is_some() || nonblocking.is_some() {
9710            guest.thread_state().with_detfd(fd, |detfd| {
9711                if let Some(enabled) = cloexec {
9712                    detfd.set_cloexec(enabled);
9713                }
9714                if let Some(enabled) = nonblocking {
9715                    detfd.set_nonblocking(enabled);
9716                }
9717            })?;
9718        }
9719        Ok(result)
9720    }
9721
9722    /// statfs: report deterministic filesystem statistics.
9723    ///
9724    /// The kernel's `statfs` reflects live host state: the free-block counts
9725    /// (`f_bfree`, `f_bavail`), the free-inode count (`f_ffree`) and the device
9726    /// id (`f_fsid`) all vary between runs as the underlying host filesystem
9727    /// fills and drains, which makes a bare passthrough diverge under `--verify`
9728    /// (e.g. `tar` calls statfs on its target filesystem). The static geometry
9729    /// of the mount (`f_type`, `f_bsize`, `f_blocks`, `f_namelen`, ...) is
9730    /// reproducible, so we run the real syscall and then canonicalize only the
9731    /// volatile fields.
9732    pub async fn handle_statfs<G: Guest<Self>>(
9733        &self,
9734        guest: &mut G,
9735        call: syscalls::Statfs,
9736    ) -> Result<i64, Error> {
9737        if let Some(pointer) = call.path() {
9738            let path: PathBuf = pointer.read(&guest.memory())?;
9739            let observed = Self::observed_path(guest, libc::AT_FDCWD, &path)?;
9740            if self.rendered_procfs_at(guest, &observed).await?.is_some()
9741                || self
9742                    .placeholder_reached(guest, libc::AT_FDCWD, Some(pointer), true)
9743                    .await
9744                    .is_some()
9745            {
9746                self.write_procfs_statfs(guest, call.buf())?;
9747                return Ok(0);
9748            }
9749        }
9750        let ret = self.record_or_replay(guest, call).await?;
9751        self.canonicalize_statfs_buf(guest, call.buf())?;
9752        Ok(ret)
9753    }
9754
9755    /// fstatfs: same determinization as [`Self::handle_statfs`], keyed on an fd.
9756    pub async fn handle_fstatfs<G: Guest<Self>>(
9757        &self,
9758        guest: &mut G,
9759        call: syscalls::Fstatfs,
9760    ) -> Result<i64, Error> {
9761        let rendered = guest
9762            .thread_state()
9763            .with_detfd(call.fd(), |detfd| detfd.procfs_rendered_path().is_some())
9764            .unwrap_or(false);
9765        if rendered {
9766            self.write_procfs_statfs(guest, call.buf())?;
9767            return Ok(0);
9768        }
9769        let ret = self.record_or_replay(guest, call).await?;
9770        self.canonicalize_statfs_buf(guest, call.buf())?;
9771        Ok(ret)
9772    }
9773
9774    // AUTONOMOUS-BOT-IMPLEMENTED
9775    // TODO-HUMAN-REVIEW(#1851): Determinized ownership mutation. Emulate the
9776    // IDENTITY half of the call and let Linux answer the ARGUMENT half.
9777    /// The `chown` family (`chown`, `fchown`, `fchownat`, `lchown`).
9778    ///
9779    /// Detcore presents a fixed virtual-root identity, so the *permission*
9780    /// answer must be the one a real root gets: success, for any uid. But root
9781    /// privilege affects only the ownership permission check — it does not
9782    /// waive pathname, descriptor, or flag errors. A real root's
9783    /// `chown("/does/not/exist", 0, 0)` still fails with `ENOENT`.
9784    ///
9785    /// So this does not fabricate a bare `Ok(0)`. It translates the mutation
9786    /// into a side-effect-free metadata lookup with the same target-selection
9787    /// arguments, and reports success only if that lookup succeeds:
9788    ///
9789    /// * `F_GETFL` validates `fchown`'s descriptor and distinguishes an
9790    ///   `O_PATH` descriptor (valid for `fstat`, invalid for `fchown`);
9791    ///   `newfstatat` performs the corresponding path walk for the three
9792    ///   pathname variants, preserving `ENOENT`, `ENOTDIR`, `ELOOP`,
9793    ///   `ENAMETOOLONG`, `EFAULT`, and `EBADF`;
9794    /// * `fchownat` flags are checked explicitly before the lookup, so an
9795    ///   unsupported flag still returns `EINVAL` rather than being accepted by
9796    ///   a metadata syscall with a wider flag vocabulary;
9797    /// * the ownership assignment itself is not performed, but the *other*
9798    ///   consequences of a successful chown are, because Linux applies them
9799    ///   even when ownership does not change. Measured on this host with
9800    ///   `chown(path, -1, -1)`: mode `06755`, `04755` and `02755` all become
9801    ///   `0755`; `02644` keeps `S_ISGID` because the file is not
9802    ///   group-executable; a directory at `06755` keeps both bits; and ctime
9803    ///   moves in every one of those cases, including the plain `0644` file
9804    ///   with nothing to clear. Skipping that is a privilege-containment
9805    ///   regression, not a bookkeeping one: a guest that builds a setuid
9806    ///   binary and chowns it would see the setuid bit survive under hermit
9807    ///   and be cleared on the kernel.
9808    ///
9809    /// Rather than reimplement that rule, the consequence is delegated to the
9810    /// kernel by reissuing the *same* call from the same family with the
9811    /// `(-1, -1)` sentinel, which is precisely the operation whose only effects
9812    /// are `ATTR_CTIME | ATTR_KILL_SUID | ATTR_KILL_SGID`. Delegation gets the
9813    /// directory exemption, the group-executable condition on `S_ISGID`, and
9814    /// symlink handling right for free, and cannot drift from the kernel the
9815    /// way a transcribed rule would.
9816    ///
9817    /// Routed through `record_or_replay` rather than `inject`, so a replay does
9818    /// not need the guest's filesystem to still exist.
9819    ///
9820    /// **Semantic boundary, stated explicitly.** Detcore does not model
9821    /// per-file ownership, so the success is not observable through a later
9822    /// `stat`. A guest that chowns to a foreign uid and reads the owner back
9823    /// sees the unchanged owner — a divergence a single-uid container cannot
9824    /// avoid, and strictly smaller than the status quo in which the guest
9825    /// believes it is root and cannot chown at all.
9826    ///
9827    /// **Residual, also stated.** This emulates ownership permission and target
9828    /// validation, not every write-time filesystem policy. In particular a
9829    /// target on a read-only mount can pass the metadata lookup where a real
9830    /// chown would return `EROFS`. Path resolution also still requires search
9831    /// permission on the parent directories, so `EACCES` remains a function of
9832    /// the host identity under `--no-namespace`. That exposure is shared with
9833    /// every pass-through filesystem syscall (`open`, `stat`, `chmod`) and is
9834    /// not introduced here; it is recorded so the boundary is not overstated.
9835    ///
9836    /// **Residual introduced by the delegation, stated too.** The sentinel call
9837    /// needs the same `inode_owner_or_capable` permission the mode change does,
9838    /// so on a target the guest does not own it returns `EPERM` and that errno
9839    /// is propagated. Reporting a successful chown while silently failing to
9840    /// apply the consequence the kernel guarantees would be the same defect in
9841    /// a narrower form, so this fails closed instead. It is not a regression:
9842    /// that is exactly the case in which the pass-through implementation also
9843    /// returned `EPERM`. The case this change exists to fix — a guest chowning
9844    /// a file it created — is the owning case, and it succeeds.
9845    ///
9846    /// The behavioural contract is bracketed end to end by
9847    /// `hermit-cli/tests/chown_virtual_root_identity.rs`; the unit tests in
9848    /// `syscall_classification` pin membership only and cannot see this
9849    /// function's result.
9850    pub async fn handle_ownership_change_noop<G: Guest<Self>>(
9851        &self,
9852        guest: &mut G,
9853        call: Syscall,
9854    ) -> Result<i64, Error> {
9855        // Unreachable while `is_ownership_change_noop_syscall` and the matches
9856        // below name the same four syscalls. Fail closed if they drift: "not
9857        // attempted" must never be observationally identical to a validated
9858        // emulated success.
9859        if !matches!(
9860            call,
9861            Syscall::Chown(_) | Syscall::Fchown(_) | Syscall::Fchownat(_) | Syscall::Lchown(_)
9862        ) {
9863            warn!(
9864                "ownership-change no-op reached with an unexpected syscall {:?}; \
9865                 refusing unvalidated success",
9866                call.number()
9867            );
9868            return Err(Error::Errno(Errno::ENOSYS));
9869        }
9870
9871        // Flag errors precede path resolution in the kernel, so check first.
9872        if let Syscall::Fchownat(c) = &call {
9873            let allowed = AtFlags::AT_EMPTY_PATH | AtFlags::AT_SYMLINK_NOFOLLOW;
9874            if c.flags().bits() & !allowed.bits() != 0 {
9875                return Err(Error::Errno(Errno::EINVAL));
9876            }
9877        }
9878
9879        // Argument half. `F_GETFL` answers it for `fchown`: it validates the
9880        // descriptor and distinguishes an `O_PATH` descriptor, which `fstat`
9881        // accepts and `fchown` rejects. For the three pathname variants a
9882        // `newfstatat` with the same target-selection arguments performs the
9883        // corresponding path walk.
9884        if let Syscall::Fchown(c) = &call {
9885            let flags = self
9886                .record_or_replay(
9887                    guest,
9888                    syscalls::Fcntl::new().with_fd(c.fd()).with_cmd(F_GETFL),
9889                )
9890                .await?;
9891            if flags & i64::from(OFlag::O_PATH.bits()) != 0 {
9892                return Err(Error::Errno(Errno::EBADF));
9893            }
9894        } else {
9895            let mut stack = guest.stack().await;
9896            let statptr: StatPtr = StatPtr(stack.reserve());
9897            stack.commit()?;
9898
9899            let validate = match &call {
9900                Syscall::Chown(c) => Syscall::Newfstatat(
9901                    syscalls::Newfstatat::new()
9902                        .with_dirfd(libc::AT_FDCWD)
9903                        .with_path(c.path())
9904                        .with_stat(Some(statptr))
9905                        .with_flags(AtFlags::empty()),
9906                ),
9907                Syscall::Lchown(c) => Syscall::Newfstatat(
9908                    syscalls::Newfstatat::new()
9909                        .with_dirfd(libc::AT_FDCWD)
9910                        .with_path(c.path())
9911                        .with_stat(Some(statptr))
9912                        .with_flags(AtFlags::AT_SYMLINK_NOFOLLOW),
9913                ),
9914                Syscall::Fchownat(c) => Syscall::Newfstatat(
9915                    syscalls::Newfstatat::new()
9916                        .with_dirfd(c.dirfd())
9917                        .with_path(c.path())
9918                        .with_stat(Some(statptr))
9919                        .with_flags(c.flags()),
9920                ),
9921                _ => return Err(Error::Errno(Errno::ENOSYS)),
9922            };
9923
9924            // The errno of the side-effect-free validating call is the guest's
9925            // answer; only an actually executed successful validation becomes the
9926            // emulated success. Clear the scratch output on both paths.
9927            let result = self.record_or_replay(guest, validate).await;
9928            guest
9929                .memory()
9930                .write_exact(statptr.0.cast(), &[0; std::mem::size_of::<libc::stat>()])?;
9931            result?;
9932        }
9933
9934        // Metadata half, delegated to the kernel. The identity assignment is
9935        // deliberately not performed, but everything else a successful chown
9936        // does is, by reissuing the same call with the `(-1, -1)` sentinel:
9937        // clear `S_ISUID`, clear `S_ISGID` on a group-executable file, exempt
9938        // directories, and move ctime unconditionally. Letting Linux apply its
9939        // own rule keeps it from drifting here.
9940        const KEEP_ID: libc::uid_t = libc::uid_t::MAX;
9941        let consequence = match &call {
9942            Syscall::Fchown(c) => Syscall::Fchown(
9943                syscalls::Fchown::new()
9944                    .with_fd(c.fd())
9945                    .with_owner(KEEP_ID)
9946                    .with_group(KEEP_ID),
9947            ),
9948            Syscall::Chown(c) => Syscall::Chown(
9949                syscalls::Chown::new()
9950                    .with_path(c.path())
9951                    .with_owner(KEEP_ID)
9952                    .with_group(KEEP_ID),
9953            ),
9954            Syscall::Lchown(c) => Syscall::Lchown(
9955                syscalls::Lchown::new()
9956                    .with_path(c.path())
9957                    .with_owner(KEEP_ID)
9958                    .with_group(KEEP_ID),
9959            ),
9960            Syscall::Fchownat(c) => Syscall::Fchownat(
9961                syscalls::Fchownat::new()
9962                    .with_dirfd(c.dirfd())
9963                    .with_path(c.path())
9964                    .with_owner(KEEP_ID)
9965                    .with_group(KEEP_ID)
9966                    .with_flags(c.flags()),
9967            ),
9968            _ => return Err(Error::Errno(Errno::ENOSYS)),
9969        };
9970        self.record_or_replay(guest, consequence).await?;
9971        Ok(0)
9972    }
9973
9974    /// Overwrite the host-varying fields of a `statfs` result buffer with fixed
9975    /// values, leaving the static per-mount geometry intact. Shared by statfs
9976    /// and fstatfs. A null buffer (only possible on an error return, which the
9977    /// caller has already propagated) is a no-op.
9978    fn canonicalize_statfs_buf<G: Guest<Self>>(
9979        &self,
9980        guest: &mut G,
9981        buf: Option<AddrMut<libc::statfs>>,
9982    ) -> Result<(), Error> {
9983        // Fixed *caps* for the volatile counters. The exact values are
9984        // arbitrary; they only need to be constant so repeated runs agree. We
9985        // clamp each free count to the mount's (static) total so we never report
9986        // the impossible "free > total": a filesystem may be smaller than the
9987        // cap, and some (e.g. overlayfs) report no inode accounting at all
9988        // (`f_files == 0`).
9989        const FREE_BLOCKS_CAP: libc::fsblkcnt_t = 1_000_000;
9990        const FREE_INODES_CAP: libc::fsfilcnt_t = 500_000;
9991
9992        if let Some(buf) = buf {
9993            let mut sf = guest.memory().read_value(buf)?;
9994            let free_blocks = FREE_BLOCKS_CAP.min(sf.f_blocks);
9995            sf.f_bfree = free_blocks;
9996            sf.f_bavail = free_blocks;
9997            // `f_files == 0` means the filesystem does not track inodes; keep the
9998            // free count at 0 rather than inventing free inodes on a mount that
9999            // reports none.
10000            sf.f_ffree = if sf.f_files == 0 {
10001                0
10002            } else {
10003                FREE_INODES_CAP.min(sf.f_files)
10004            };
10005            // f_fsid is a device-dependent filesystem identifier; zero it. An
10006            // all-zero bit pattern is a valid `fsid_t` (a POD id pair).
10007            sf.f_fsid = unsafe { std::mem::zeroed() };
10008            guest.memory().write_value(buf, &sf)?;
10009        }
10010        Ok(())
10011    }
10012
10013    /// dup system call.
10014    pub async fn handle_dup<G: Guest<Self>>(
10015        &self,
10016        guest: &mut G,
10017        call: syscalls::Dup,
10018    ) -> Result<i64, Errno> {
10019        let old_fd = call.oldfd();
10020        let new_fd = self.record_or_replay(guest, call).await? as RawFd;
10021        let lock_tracked = self.lock_tracked_descriptions(guest, new_fd..=new_fd);
10022        let replaced = guest
10023            .thread_state_mut()
10024            .dup_fd(old_fd, new_fd, OFlag::empty())?;
10025        if let Some(open_file_id) = replaced {
10026            self.release_port_for_open_file(guest, open_file_id).await;
10027        }
10028        self.report_lock_references(guest, lock_tracked).await;
10029        Ok(new_fd as i64)
10030    }
10031
10032    /// dup2 system call.
10033    pub async fn handle_dup2<G: Guest<Self>>(
10034        &self,
10035        guest: &mut G,
10036        call: syscalls::Dup2,
10037    ) -> Result<i64, Error> {
10038        let old_fd = call.oldfd();
10039        let new_fd = call.newfd();
10040        if let Some(refusal) = self
10041            .refuse_dup_over_waited_listener(guest, Sysno::dup2, old_fd, new_fd)
10042            .await
10043        {
10044            return refusal;
10045        }
10046        // `dup2` over another open descriptor closes it.
10047        let closed_end = (old_fd != new_fd)
10048            .then(|| self.pipe_channel_end(guest, new_fd))
10049            .flatten();
10050        let res = self.record_or_replay(guest, call).await?;
10051        // Reported as soon as the kernel replaced `new_fd`, before Detcore's
10052        // own table update, which can still fail for a descriptor it does not
10053        // track (`Scheduler::note_descriptors_replaced`).
10054        if old_fd != new_fd
10055            && let Ok(new_fd) = u32::try_from(new_fd)
10056        {
10057            crate::tool_global::descriptors_replaced(guest, new_fd, new_fd).await;
10058        }
10059        let lock_tracked = if old_fd == new_fd {
10060            Vec::new()
10061        } else {
10062            self.lock_tracked_descriptions(guest, new_fd..=new_fd)
10063        };
10064        let replaced = self
10065            .dup_fd_after_replacement(guest, old_fd, new_fd, OFlag::empty(), lock_tracked.clone())
10066            .await?;
10067        if let Some(open_file_id) = replaced {
10068            self.release_port_for_open_file(guest, open_file_id).await;
10069        }
10070        self.report_lock_references(guest, lock_tracked).await;
10071        self.note_channel_end_closed(guest, closed_end).await;
10072        Ok(res)
10073    }
10074
10075    /// Detcore's table update after the kernel's `dup2` or `dup3` put
10076    /// `old_fd`'s description in slot `new_fd`. If Detcore keeps no model of
10077    /// `old_fd` (one received over `SCM_RIGHTS` on ptrace), the update fails,
10078    /// but the kernel replaced the slot all the same: its old description is
10079    /// dropped from the model and `lock_tracked` (what the slot named) is
10080    /// reported to `procfs::locks::LockLedger`, so no stale entry can admit
10081    /// a host's identical `/proc/locks` row. The error is returned as before.
10082    async fn dup_fd_after_replacement<G: Guest<Self>>(
10083        &self,
10084        guest: &mut G,
10085        old_fd: RawFd,
10086        new_fd: RawFd,
10087        flags: OFlag,
10088        lock_tracked: Vec<OpenFileId>,
10089    ) -> Result<Option<OpenFileId>, Error> {
10090        match guest.thread_state_mut().dup_fd(old_fd, new_fd, flags) {
10091            Ok(replaced) => Ok(replaced),
10092            Err(errno) => {
10093                if old_fd != new_fd {
10094                    let displaced = guest.thread_state().remove_fd(new_fd);
10095                    if let Some(open_file_id) = displaced {
10096                        self.release_port_for_open_file(guest, open_file_id).await;
10097                    }
10098                    self.report_lock_references(guest, lock_tracked).await;
10099                }
10100                Err(errno.into())
10101            }
10102        }
10103    }
10104
10105    /// Refuse a `dup2` or `dup3` that would close `new_fd` while a blocking
10106    /// accept waits on it. With `old_fd == new_fd` neither call closes
10107    /// anything. The check comes before the call, so a call that would fail
10108    /// for another reason (a bad `old_fd`) is refused as well.
10109    async fn refuse_dup_over_waited_listener<G: Guest<Self>>(
10110        &self,
10111        guest: &mut G,
10112        sysno: Sysno,
10113        old_fd: RawFd,
10114        new_fd: RawFd,
10115    ) -> Option<Result<i64, Error>> {
10116        if old_fd == new_fd {
10117            return None;
10118        }
10119        let new_fd = u32::try_from(new_fd).ok()?;
10120        self.refuse_close_of_waited_listener(guest, sysno, new_fd..=new_fd)
10121            .await
10122    }
10123
10124    /// dup3 system call.
10125    pub async fn handle_dup3<G: Guest<Self>>(
10126        &self,
10127        guest: &mut G,
10128        call: syscalls::Dup3,
10129    ) -> Result<i64, Error> {
10130        let old_fd = call.oldfd();
10131        let new_fd = call.newfd();
10132        let flags = call.flags();
10133        if let Some(refusal) = self
10134            .refuse_dup_over_waited_listener(guest, Sysno::dup3, old_fd, new_fd)
10135            .await
10136        {
10137            return refusal;
10138        }
10139        // `dup3` over another open descriptor closes it.
10140        let closed_end = (old_fd != new_fd)
10141            .then(|| self.pipe_channel_end(guest, new_fd))
10142            .flatten();
10143        let res = self.record_or_replay(guest, call).await?;
10144        // Reported before Detcore's own table update, as for `dup2`.
10145        if let Ok(new_fd) = u32::try_from(new_fd) {
10146            crate::tool_global::descriptors_replaced(guest, new_fd, new_fd).await;
10147        }
10148        let lock_tracked = self.lock_tracked_descriptions(guest, new_fd..=new_fd);
10149        let replaced = self
10150            .dup_fd_after_replacement(guest, old_fd, new_fd, flags, lock_tracked.clone())
10151            .await?;
10152        if let Some(open_file_id) = replaced {
10153            self.release_port_for_open_file(guest, open_file_id).await;
10154        }
10155        self.report_lock_references(guest, lock_tracked).await;
10156        self.note_channel_end_closed(guest, closed_end).await;
10157        Ok(res)
10158    }
10159
10160    /// pipe2 system call.
10161    pub async fn handle_pipe2<G: Guest<Self>>(
10162        &self,
10163        guest: &mut G,
10164        call: syscalls::Pipe2,
10165    ) -> Result<i64, Error> {
10166        // Pipes are unambiguously container-internal: both endpoints are owned by
10167        // guest processes. Make them physically nonblocking whenever we sequentialize
10168        // threads -- INCLUDING record/replay modes. This lets a potentially-blocking
10169        // pipe read follow the deterministic nonblockize-and-retry (InternalIOPolling)
10170        // path instead of being descheduled as BlockingExternalIO. A pipe reader and
10171        // its paired writer are NOT independent, so treating an internal pipe as
10172        // "external blocking IO" (safe to run in the background and rejoin whenever)
10173        // deadlocks the sequentialized scheduler in R/R (the documented pipe hang). The
10174        // physical O_NONBLOCK is Detcore-internal and invisible to the guest (F_GETFL is
10175        // virtualized), and mirrors what `hermit run --strict` already does for pipes.
10176        let internally_nonblocking = self.cfg.use_nonblocking_sockets();
10177        let injected = if internally_nonblocking {
10178            call.with_flags(call.flags() | OFlag::O_NONBLOCK)
10179        } else {
10180            call
10181        };
10182        // NO PRE-CALL READ OF `pipefd`. This is load-bearing on three backends, not a style
10183        // choice. `record_or_replay` below returns early on failure, so every guest memory
10184        // access AFTER it runs only when pipe2 SUCCEEDED -- and a successful pipe2 means the
10185        // kernel itself wrote two ints there, which proves the address valid. A pre-call
10186        // snapshot would be the only access to a kernel-UNVALIDATED address, and `LocalMemory`
10187        // (reverie-dbt, reverie-e9patch, reverie-liteinst) implements reads as an unsafe
10188        // `copy_nonoverlapping` that always returns `Ok`: a bad pointer is a hardware fault
10189        // that `Result::ok` cannot catch, so the guest would die with SIGSEGV before Linux
10190        // could report EFAULT. Letting the kernel touch `pipefd` first is also what keeps its
10191        // argument-validation precedence intact -- flags are checked before the pointer, so a
10192        // bad pointer with bad flags is EINVAL and with good flags EFAULT.
10193        // A C guest asserting that precedence directly is being added separately.
10194        let res = self.record_or_replay(guest, injected).await?;
10195        let memory = guest.memory();
10196
10197        if let Some(pipefd) = call.pipefd() {
10198            let fds: [i32; 2] = memory.read_value(pipefd)?;
10199            if internally_nonblocking {
10200                let capacity_result = guest
10201                    .inject(
10202                        syscalls::Fcntl::new()
10203                            .with_fd(fds[0])
10204                            .with_cmd(F_SETPIPE_SZ(DETERMINISTIC_PIPE_CAPACITY_BYTES)),
10205                    )
10206                    .await;
10207                if let Some(failure) = pipe_capacity_failure(fds, capacity_result) {
10208                    // Release the descriptors Linux already created, THEN stop the run.
10209                    //
10210                    // Returning `Err` here -- what this code did before -- unwinds without
10211                    // closing them. `pipe2` has already succeeded, so both descriptors are
10212                    // live in the guest and are not yet registered with `add_fd`, which means
10213                    // Detcore's own bookkeeping never learns they exist. Closing them is the
10214                    // only way the guest's descriptor table matches Detcore's model.
10215                    //
10216                    // We do NOT fabricate a `pipe2` errno. Linux leaves `pipefd` untouched
10217                    // when `pipe2` fails, so inventing a failure would oblige us to restore
10218                    // the caller's buffer, which needs the pre-call snapshot the comment above
10219                    // explains we must never take. And returning success with an unpinned pipe
10220                    // silently restores exactly the host-dependent capacity this path exists
10221                    // to remove. An unpinnable pipe means determinism is unavailable for this
10222                    // run, so fail closed and loudly rather than quietly.
10223                    //
10224                    // Defensive, not expected: pinning on a freshly created EMPTY pipe is a
10225                    // shrink or a no-op. EBUSY needs buffered data and EPERM needs to exceed
10226                    // `pipe-max-size`; neither can hold here.
10227                    for close in failure.close_syscalls() {
10228                        let _ = guest.inject(close).await;
10229                    }
10230                    error!(
10231                        "[detcore] cannot pin scheduler-managed pipe to {} bytes (fds {:?}): {}. \
10232                         Determinism is unavailable for this run.",
10233                        DETERMINISTIC_PIPE_CAPACITY_BYTES, failure.created_fds, failure.error,
10234                    );
10235                    // Fail-closed policy: determinism is unavailable for this run.
10236                    unrecoverable_shutdown(guest, detcore_model::HERMIT_POLICY_REFUSAL_EXIT).await;
10237                }
10238            }
10239            self.add_fd(guest, fds[0], call.flags(), FdType::Pipe)
10240                .await?;
10241            self.add_fd(guest, fds[1], call.flags(), FdType::Pipe)
10242                .await?;
10243            if internally_nonblocking {
10244                self.maybe_set_nonblocking_fd(guest, fds[0]);
10245                self.maybe_set_nonblocking_fd(guest, fds[1]);
10246            }
10247            // Both ends name the pipe by the read end's open file description,
10248            // for `--pipe-wake-latency` only (`crate::pipe_wake`).
10249            if self.cfg.pipe_wake_latency_in_effect().is_some() {
10250                let read_end = guest
10251                    .thread_state()
10252                    .with_detfd(fds[0], |detfd| detfd.open_file_id())?;
10253                let channel = crate::pipe_wake::ChannelId::Pipe(read_end);
10254                for (fd, reads) in [(fds[0], true), (fds[1], false)] {
10255                    let end = crate::pipe_wake::ChannelEnd {
10256                        channel,
10257                        reads,
10258                        writes: !reads,
10259                    };
10260                    guest
10261                        .thread_state()
10262                        .with_detfd(fd, |detfd| detfd.set_channel(end))?;
10263                }
10264            }
10265        }
10266
10267        Ok(res)
10268    }
10269
10270    /// utime syscall: update access/modification time on a file
10271    pub async fn handle_utime<G: Guest<Self>>(
10272        &self,
10273        guest: &mut G,
10274        call: syscalls::Utime,
10275    ) -> Result<i64, Errno> {
10276        let times = match call.times() {
10277            None => {
10278                let now: Timespec = thread_observe_time(guest).await.into();
10279                [now, now]
10280            }
10281            Some(times) => {
10282                let utimbuf = guest.memory().read_value(times)?;
10283                [
10284                    Timespec {
10285                        tv_sec: utimbuf.actime,
10286                        tv_nsec: 0,
10287                    },
10288                    Timespec {
10289                        tv_sec: utimbuf.modtime,
10290                        tv_nsec: 0,
10291                    },
10292                ]
10293            }
10294        };
10295
10296        let utimensat = syscalls::Utimensat::new()
10297            .with_dirfd(libc::AT_FDCWD)
10298            .with_path(call.path());
10299
10300        self.set_file_times(guest, utimensat, Some(times)).await
10301    }
10302
10303    /// utimes syscall
10304    pub async fn handle_utimes<G: Guest<Self>>(
10305        &self,
10306        guest: &mut G,
10307        call: syscalls::Utimes,
10308    ) -> Result<i64, Errno> {
10309        let utimensat = syscalls::Utimensat::new()
10310            .with_dirfd(libc::AT_FDCWD)
10311            .with_path(call.filename());
10312
10313        match call.times() {
10314            None => {
10315                let now: Timespec = thread_observe_time(guest).await.into();
10316                self.set_file_times(guest, utimensat, Some([now, now]))
10317                    .await
10318            }
10319            Some(times) => {
10320                // Convert the timeval array to a timespec array.
10321                let mut memory = guest.memory();
10322                let tvs = memory.read_value(times)?;
10323                let tp: Addr<[Timespec; 2]> = times.cast();
10324
10325                // Safety: The address could point to read-only memory and the
10326                // write below could fail.
10327                let tp = unsafe { tp.into_mut() };
10328
10329                memory.write_value(tp, &[tvs[0].into(), tvs[1].into()])?;
10330                self.set_file_times(guest, utimensat.with_times(Some(tp.into())), None)
10331                    .await
10332            }
10333        }
10334    }
10335
10336    /// ustimensat syscall
10337    pub async fn handle_utimensat<G: Guest<Self>>(
10338        &self,
10339        guest: &mut G,
10340        call: syscalls::Utimensat,
10341    ) -> Result<i64, Errno> {
10342        self.set_file_times(guest, call, None).await
10343    }
10344
10345    /// Performs a utimensat call and copies the mtime it sets into the virtual
10346    /// mtime. With `staged` the times are first pushed onto the guest's scratch
10347    /// stack and replace the call's `times` pointer; utime and utimes(NULL)
10348    /// build their times that way.
10349    async fn set_file_times<G: Guest<Self>>(
10350        &self,
10351        guest: &mut G,
10352        call: syscalls::Utimensat,
10353        staged: Option<[Timespec; 2]>,
10354    ) -> Result<i64, Errno> {
10355        if !guest.config().virtualize_metadata {
10356            return self.utimensat_without_lookup(guest, call, staged).await;
10357        }
10358        // Without thread sequentialization another guest thread can swap the
10359        // target away and back around the call, so that both lookups name a
10360        // file the kernel did not update. No lookup can tell the two apart,
10361        // so the virtual mtime is left alone.
10362        if !guest.config().sequentialize_threads {
10363            return self.utimensat_without_lookup(guest, call, staged).await;
10364        }
10365        // The scratch stack starts 128 bytes below the stack pointer and its
10366        // addresses are computed by subtraction, so a stack pointer too close
10367        // to zero to hold the staged times and the lookup buffer would stop
10368        // Hermit rather than reach Linux.
10369        let scratch = 128
10370            + staged.map_or(0, |_| std::mem::size_of::<[Timespec; 2]>())
10371            + std::mem::size_of::<libc::stat>();
10372        if usize::try_from(guest.regs().await.rsp).map_or(true, |rsp| rsp <= scratch) {
10373            info!(
10374                "Guest stack pointer cannot hold the utimensat target lookup; \
10375                 leaving the virtual mtime unchanged."
10376            );
10377            return self.utimensat_without_lookup(guest, call, staged).await;
10378        }
10379
10380        // The staged times and the buffer for the target lookups share one
10381        // scratch stack, and its guard is held until the last injected syscall
10382        // has run, so that neither the kernel's read of the times nor a lookup
10383        // finds the other's bytes, or a restored stack, at its address.
10384        let mut stack = guest.stack().await;
10385        let staged_call = match staged {
10386            Some(times) => call.with_times(Some(stack.push(times))),
10387            None => call,
10388        };
10389        let statptr: StatPtr = StatPtr(stack.reserve());
10390        // The scratch stack lies below the guest's red zone, where a raw
10391        // syscall may keep its own path or times. Writing the lookup buffer
10392        // over either would change the call before Linux reads it.
10393        if utimensat_input_overlaps(&guest.memory(), &call, staged.is_none(), statptr) {
10394            info!(
10395                "utimensat inputs overlap the target lookup buffer; \
10396                 leaving the virtual mtime unchanged."
10397            );
10398            drop(stack);
10399            return self.utimensat_without_lookup(guest, call, staged).await;
10400        }
10401        // The buffer's address range can still share its pages with guest data
10402        // through a second shared mapping, which no address comparison sees.
10403        // Its bytes are saved here and put back after the commit and after
10404        // each lookup, so the lookups and the call read their inputs unchanged
10405        // and the guest keeps its memory.
10406        let mut saved = [0u8; std::mem::size_of::<libc::stat>()];
10407        if guest
10408            .memory()
10409            .read_exact(statptr.0.cast(), &mut saved)
10410            .is_err()
10411        {
10412            info!(
10413                "Guest stack scratch cannot hold the utimensat target lookup; \
10414                 leaving the virtual mtime unchanged."
10415            );
10416            drop(stack);
10417            return self.utimensat_without_lookup(guest, call, staged).await;
10418        }
10419        let _guard = match stack.commit() {
10420            Ok(guard) => guard,
10421            // The lookup buffer only serves the virtual update, so a scratch
10422            // stack that cannot hold it, for example one next to the guard
10423            // page, must not keep the guest's own call from reaching Linux.
10424            // The commit writes page by page, so it can fail after writing a
10425            // lower writable page; those bytes are put back first.
10426            Err(_) => {
10427                info!(
10428                    "Guest stack scratch cannot hold the utimensat target lookup; \
10429                     leaving the virtual mtime unchanged."
10430                );
10431                restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
10432                return self.utimensat_without_lookup(guest, call, staged).await;
10433            }
10434        };
10435        restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
10436        let call = staged_call;
10437
10438        // The kernel applies the new times to the real file, but the guest
10439        // observes the virtual mtime, which otherwise only moves on writes. Copy
10440        // the requested mtime into it so that `tar` extraction, `cp -p` and
10441        // `touch -r` restore a file's mtime and `make` compares the times the
10442        // build asked for rather than the order in which files were unpacked.
10443        //
10444        // Nothing below may change the syscall's result: an unreadable `times`
10445        // or a failed lookup only skips the virtual update, and the kernel
10446        // reports its own error for the call itself.
10447        let mtime = match (staged, call.times()) {
10448            (Some([_, mtime]), _) => Some(mtime),
10449            (None, None) => Some(Timespec {
10450                tv_sec: 0,
10451                tv_nsec: libc::UTIME_NOW,
10452            }),
10453            (None, Some(times)) => guest
10454                .memory()
10455                .read_value(times)
10456                .ok()
10457                .map(|[_, mtime]| mtime),
10458        }
10459        .filter(|mtime| mtime.tv_nsec != libc::UTIME_OMIT);
10460        let before = match mtime {
10461            Some(_) => self.utimensat_target(guest, &call, statptr).await,
10462            None => None,
10463        };
10464        restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
10465
10466        let res = self.record_or_replay(guest, call).await?;
10467
10468        // Update only the inode the kernel modified. No other guest thread
10469        // runs during the call, but a process outside the container can still
10470        // rename, unlink or replace the target; the target is resolved before
10471        // and after the call, and the update is skipped unless both name the
10472        // same file. Equal lookups alone do not show that the kernel updated
10473        // that file: the name may have been swapped away and back during the
10474        // call, or an inode number reused. So an explicit mtime is copied only
10475        // when the file holds it, truncated to the filesystem's granularity,
10476        // and the virtual mtime takes the value the kernel stored, which is
10477        // what stat reports on Linux. `UTIME_NOW` has no such witness.
10478        let (Some(mtime), Some(before)) = (mtime, before) else {
10479            return Ok(res);
10480        };
10481        let after = self.utimensat_target(guest, &call, statptr).await;
10482        restore_lookup_buffer(&mut guest.memory(), statptr, &saved);
10483        let Some(after) = after else {
10484            return Ok(res);
10485        };
10486        if (after.st_dev, after.st_ino) != (before.st_dev, before.st_ino) {
10487            return Ok(res);
10488        }
10489        if mtime.tv_nsec == libc::UTIME_NOW {
10490            touch_file(guest, RawInode::new(after.st_dev, after.st_ino)).await;
10491            return Ok(res);
10492        }
10493        const NANOS_PER_SEC: i128 = 1_000_000_000;
10494        let requested = i128::from(mtime.tv_sec) * NANOS_PER_SEC + i128::from(mtime.tv_nsec);
10495        let stored = i128::from(after.st_mtime) * NANOS_PER_SEC + i128::from(after.st_mtime_nsec);
10496        // Linux truncates the requested time down to the filesystem's
10497        // granularity, at most a second on the filesystems builds use.
10498        if (0..NANOS_PER_SEC).contains(&(requested - stored)) {
10499            let nanos = u64::try_from(stored.max(0)).unwrap_or(u64::MAX);
10500            set_file_mtime(
10501                guest,
10502                RawInode::new(after.st_dev, after.st_ino),
10503                LogicalTime::from_nanos(nanos),
10504            )
10505            .await;
10506        }
10507        Ok(res)
10508    }
10509
10510    /// Performs a utimensat call without the virtual mtime update. Staged
10511    /// times are then the only scratch-stack allocation, as they were before
10512    /// the update existed.
10513    async fn utimensat_without_lookup<G: Guest<Self>>(
10514        &self,
10515        guest: &mut G,
10516        call: syscalls::Utimensat,
10517        staged: Option<[Timespec; 2]>,
10518    ) -> Result<i64, Errno> {
10519        let Some(times) = staged else {
10520            return self.record_or_replay(guest, call).await;
10521        };
10522        let mut stack = guest.stack().await;
10523        let call = call.with_times(Some(stack.push(times)));
10524        let _guard = stack.commit()?;
10525        self.record_or_replay(guest, call).await
10526    }
10527
10528    /// The metadata of the file a utimensat call targets, with the same target
10529    /// selection: the descriptor itself for `futimens` (a NULL path), else a
10530    /// path walk honoring the flags utimensat accepts. `None` if the lookup
10531    /// fails.
10532    async fn utimensat_target<G: Guest<Self>>(
10533        &self,
10534        guest: &mut G,
10535        call: &syscalls::Utimensat,
10536        statptr: StatPtr<'_>,
10537    ) -> Option<libc::stat> {
10538        let lookup = match call.path() {
10539            None => Syscall::Fstat(
10540                syscalls::Fstat::new()
10541                    .with_fd(call.dirfd())
10542                    .with_stat(Some(statptr)),
10543            ),
10544            Some(path) => {
10545                let allowed = libc::AT_SYMLINK_NOFOLLOW | libc::AT_EMPTY_PATH;
10546                Syscall::Newfstatat(
10547                    syscalls::Newfstatat::new()
10548                        .with_dirfd(call.dirfd())
10549                        .with_path(Some(path))
10550                        .with_stat(Some(statptr))
10551                        .with_flags(AtFlags::from_bits_truncate(call.flags() & allowed)),
10552                )
10553            }
10554        };
10555        self.record_or_replay(guest, lookup).await.ok()?;
10556        statptr.read(&guest.memory()).ok()
10557    }
10558
10559    /// socket system call.
10560    pub async fn handle_socket<G: Guest<Self>>(
10561        &self,
10562        guest: &mut G,
10563        call: syscalls::Socket,
10564    ) -> Result<i64, Error> {
10565        // The socket syscall itself is not blocking, but we must decide whether to make the socket
10566        // returned physically nonblocking.
10567        if !self.cfg.sequentialize_threads || self.cfg.recordreplay_modes {
10568            // Allow possibly blocking syscall in record mode
10569            let fd = self.record_or_replay(guest, call).await? as RawFd;
10570            self.add_fd(
10571                guest,
10572                fd,
10573                OFlag::from_bits_truncate(call.r#type()),
10574                FdType::Socket,
10575            )
10576            .await?;
10577            self.mark_sock_diag_fd(guest, fd, &call);
10578            // Linux's SOCK_TYPE_MASK: the type without SOCK_NONBLOCK and SOCK_CLOEXEC.
10579            const SOCK_TYPE_MASK: i32 = 0xf;
10580            if self.accept_in_turn_enabled() && call.r#type() & SOCK_TYPE_MASK == libc::SOCK_STREAM
10581            {
10582                guest
10583                    .thread_state()
10584                    .with_detfd(fd, |detfd| detfd.set_accept_in_turn_eligible())?;
10585            }
10586            Ok(fd as i64)
10587        } else {
10588            // Under run mode, force all sockets to be registered to be nonblocking in the OS:
10589            let call2 = if self.cfg.use_nonblocking_sockets() {
10590                call.with_type(call.r#type() | libc::SOCK_NONBLOCK)
10591            } else {
10592                call
10593            };
10594            let fd = self.record_or_replay(guest, call2).await? as RawFd; // Cannot hang.
10595            self.add_fd(
10596                guest,
10597                fd,
10598                OFlag::from_bits_truncate(
10599                    call.r#type() & (libc::SOCK_NONBLOCK | libc::SOCK_CLOEXEC),
10600                ),
10601                FdType::Socket,
10602            )
10603            .await?;
10604            self.maybe_set_nonblocking_fd(guest, fd);
10605            self.mark_sock_diag_fd(guest, fd, &call);
10606
10607            Ok(fd as i64)
10608        }
10609    }
10610
10611    // TODO-HUMAN-REVIEW(PR-3908)
10612    /// Whether record/replay runs a blocking `accept(2)` on a stream socket
10613    /// the container created in the caller's turn
10614    /// (https://github.com/rrnewton/hermit/issues/3880). The temporary
10615    /// `O_NONBLOCK` around each attempt goes through Detcore's own copy of the
10616    /// listener (`AcceptBracket`), which needs a tool outside the guest's
10617    /// descriptor table, as under ptrace.
10618    pub(crate) fn accept_in_turn_enabled(&self) -> bool {
10619        self.cfg.recordreplay_modes
10620            && self.cfg.use_nonblocking_sockets()
10621            && !self.cfg.backend.tool_shares_guest_descriptor_table
10622    }
10623
10624    // AUTONOMOUS-BOT-IMPLEMENTED
10625    // TODO-HUMAN-REVIEW(PR-1064)
10626    /// Flag `AF_NETLINK`/`NETLINK_SOCK_DIAG` sockets so `handle_recvmsg`
10627    /// determinizes the socket inode numbers carried by their binary dump
10628    /// replies (see `crate::sock_diag`). Best-effort: if the descriptor lookup
10629    /// fails the reply is simply left unsanitized.
10630    fn mark_sock_diag_fd<G: Guest<Self>>(&self, guest: &mut G, fd: RawFd, call: &syscalls::Socket) {
10631        if call.family() != libc::AF_NETLINK {
10632            return;
10633        }
10634        if call.protocol() == libc::NETLINK_SOCK_DIAG {
10635            let _ = guest
10636                .thread_state()
10637                .with_detfd(fd, |detfd| detfd.set_sock_diag());
10638        }
10639        // TODO-HUMAN-REVIEW(PR-2478)
10640        // NETLINK_ROUTE link dumps carry live interface counters. They were
10641        // invisible until IO-buffer hashing went on by default, because the
10642        // reply's LENGTH and return value are identical between runs and only
10643        // the payload bytes move.
10644        if call.protocol() == libc::NETLINK_ROUTE {
10645            let _ = guest
10646                .thread_state()
10647                .with_detfd(fd, |detfd| detfd.set_netlink_route());
10648        }
10649    }
10650
10651    /// socketpair system call.
10652    pub async fn handle_socketpair<G: Guest<Self>>(
10653        &self,
10654        guest: &mut G,
10655        call: syscalls::Socketpair,
10656    ) -> Result<i64, Error> {
10657        let call2 = if self.cfg.sequentialize_threads && !self.cfg.debug_externalize_sockets {
10658            call.with_type(call.r#type() | libc::SOCK_NONBLOCK)
10659        } else {
10660            call
10661        };
10662        let res = self.record_or_replay(guest, call2).await?;
10663        if let Some(usockvec) = call.usockvec() {
10664            let memory = guest.memory();
10665            let fds: [i32; 2] = memory.read_value(usockvec)?;
10666
10667            // Logical flags are as requested:
10668            self.add_fd(
10669                guest,
10670                fds[0],
10671                OFlag::from_bits_truncate(
10672                    call.r#type() & (libc::SOCK_NONBLOCK | libc::SOCK_CLOEXEC),
10673                ),
10674                FdType::Socket,
10675            )
10676            .await?;
10677            self.add_fd(
10678                guest,
10679                fds[1],
10680                OFlag::from_bits_truncate(
10681                    call.r#type() & (libc::SOCK_NONBLOCK | libc::SOCK_CLOEXEC),
10682                ),
10683                FdType::Socket,
10684            )
10685            .await?;
10686
10687            // Both endpoints are container-internal by construction: socketpair(2)
10688            // creates the pair itself, so no peer outside the container can ever
10689            // hold one. Record that here, at the only point where it is known,
10690            // so potentially-blocking I/O on them takes the same
10691            // nonblockize-and-retry path as a pipe rather than being treated as
10692            // external blocking I/O against an fd Detcore just made SOCK_NONBLOCK.
10693            // See `syscall_targets_internal_fd`. Only when the endpoints really
10694            // are physically nonblocking, which is the same condition as `call2`
10695            // above: under `debug_externalize_sockets` they stay external.
10696            if self.cfg.use_nonblocking_sockets() {
10697                for fd in fds {
10698                    let _ = guest
10699                        .thread_state()
10700                        .with_detfd(fd, |detfd| detfd.set_socketpair_endpoint());
10701                }
10702            }
10703
10704            self.maybe_set_nonblocking_fd(guest, fds[0]);
10705            self.maybe_set_nonblocking_fd(guest, fds[1]);
10706        }
10707        Ok(res)
10708    }
10709
10710    // AUTONOMOUS-BOT-IMPLEMENTED
10711    // TODO-HUMAN-REVIEW(#663)
10712    /// Apply a socket option to an already tracked socket. Record mode captures
10713    /// the result; replay re-applies a successful option before later socket I/O,
10714    /// which remains mediated by Detcore's nonblocking scheduler paths.
10715    ///
10716    /// Under record and replay a successful `SO_RCVTIMEO` also sets the
10717    /// socket's modeled receive timeout (`DetFd::receive_timeout`), which a
10718    /// blocking accept in turn waits by. The value is read before the call,
10719    /// from the same guest memory in both phases.
10720    pub async fn handle_setsockopt<G: Guest<Self>>(
10721        &self,
10722        guest: &mut G,
10723        call: syscalls::Setsockopt,
10724    ) -> Result<i64, Error> {
10725        // TODO-HUMAN-REVIEW(PR-3908)
10726        const SO_RCVTIMEO_NEW: i32 = 66;
10727        let receive_timeout = (self.accept_in_turn_enabled()
10728            && call.level() == libc::SOL_SOCKET
10729            && matches!(call.optname(), libc::SO_RCVTIMEO | SO_RCVTIMEO_NEW))
10730        .then(|| {
10731            // On x86_64 both forms take 16 bytes: seconds, then microseconds.
10732            call.optval()
10733                .and_then(|value| {
10734                    guest
10735                        .memory()
10736                        .read_value::<_, libc::timeval>(value.cast())
10737                        .ok()
10738                })
10739                .map_or(ReceiveTimeout::Unknown, ReceiveTimeout::set_by)
10740        });
10741        let result = self.record_or_replay(guest, call).await?;
10742        if let Some(timeout) = receive_timeout {
10743            let _ = guest
10744                .thread_state()
10745                .with_detfd(call.fd(), |detfd| detfd.set_receive_timeout(timeout));
10746        }
10747        Ok(result)
10748    }
10749
10750    // AUTONOMOUS-BOT-IMPLEMENTED
10751    // TODO-HUMAN-REVIEW(#663)
10752    /// Transition an already tracked socket into listening state.
10753    pub async fn handle_listen<G: Guest<Self>>(
10754        &self,
10755        guest: &mut G,
10756        call: syscalls::Listen,
10757    ) -> Result<i64, Error> {
10758        Ok(self.record_or_replay(guest, call).await?)
10759    }
10760
10761    // AUTONOMOUS-BOT-IMPLEMENTED
10762    // TODO-HUMAN-REVIEW(#663)
10763    /// Return the local address of a tracked socket.
10764    pub async fn handle_getsockname<G: Guest<Self>>(
10765        &self,
10766        guest: &mut G,
10767        call: syscalls::Getsockname,
10768    ) -> Result<i64, Error> {
10769        Ok(self.record_or_replay(guest, call).await?)
10770    }
10771
10772    // AUTONOMOUS-BOT-IMPLEMENTED
10773    // TODO-HUMAN-REVIEW(#663)
10774    /// Return the peer address of a tracked socket.
10775    pub async fn handle_getpeername<G: Guest<Self>>(
10776        &self,
10777        guest: &mut G,
10778        call: syscalls::Getpeername,
10779    ) -> Result<i64, Error> {
10780        Ok(self.record_or_replay(guest, call).await?)
10781    }
10782
10783    // AUTONOMOUS-BOT-IMPLEMENTED
10784    // TODO-HUMAN-REVIEW(#663)
10785    /// Return an option value from a tracked socket. Hermit only promises normal
10786    /// run determinism for isolated guest networking; record/replay captures the
10787    /// result when external socket state is part of the recording boundary.
10788    pub async fn handle_getsockopt<G: Guest<Self>>(
10789        &self,
10790        guest: &mut G,
10791        call: syscalls::Getsockopt,
10792    ) -> Result<i64, Error> {
10793        // TODO-HUMAN-REVIEW(PR-894): Review deterministic network-namespace identity.
10794        let requested_length =
10795            if call.level() == libc::SOL_SOCKET && call.optname() == libc::SO_NETNS_COOKIE {
10796                let fd_type = guest
10797                    .thread_state()
10798                    .with_detfd(call.fd(), |detfd| detfd.ty())?;
10799                if fd_type == FdType::Socket {
10800                    call.optlen()
10801                        .map(|length| guest.memory().read_value(length))
10802                        .transpose()?
10803                } else {
10804                    None
10805                }
10806            } else {
10807                None
10808            };
10809
10810        // TODO-HUMAN-REVIEW(PR-886): Review deterministic SO_COOKIE identities.
10811        let deterministic_cookie =
10812            if call.level() == libc::SOL_SOCKET && call.optname() == libc::SO_COOKIE {
10813                let requested_length = call
10814                    .optlen()
10815                    .map(|length| guest.memory().read_value(length))
10816                    .transpose()?;
10817                let open_file_id = guest
10818                    .thread_state()
10819                    .with_detfd(call.fd(), |detfd| detfd.open_file_id())?;
10820                Some((open_file_id.deterministic_socket_cookie(), requested_length))
10821            } else {
10822                None
10823            };
10824
10825        let result = self.record_or_replay(guest, call).await?;
10826
10827        // TODO-HUMAN-REVIEW(PR-898): Hermit exposes one virtual CPU, so do not
10828        // leak the host CPU that processed a socket's most recent packet.
10829        if result == 0
10830            && call.level() == libc::SOL_SOCKET
10831            && call.optname() == libc::SO_INCOMING_CPU
10832            && let (Some(optval), Some(optlen)) = (call.optval(), call.optlen())
10833        {
10834            let returned_len: libc::socklen_t = guest.memory().read_value(optlen)?;
10835            let zero_cpu = 0_i32.to_ne_bytes();
10836            let returned_len = (returned_len as usize).min(zero_cpu.len());
10837            guest
10838                .memory()
10839                .write_exact(optval.cast::<u8>(), &zero_cpu[..returned_len])?;
10840        }
10841        if result == 0
10842            && call.level() == libc::IPPROTO_TCP
10843            && call.optname() == libc::TCP_INFO
10844            && let (Some(optval), Some(optlen)) = (call.optval(), call.optlen())
10845        {
10846            let returned_len: libc::socklen_t = guest.memory().read_value(optlen)?;
10847            let mut info = vec![0; returned_len as usize];
10848            let optval = optval.cast::<u8>();
10849            guest.memory().read_exact(optval, info.as_mut_slice())?;
10850            canonicalize_tcp_info(&mut info);
10851            guest.memory().write_exact(optval, info.as_slice())?;
10852        }
10853        if let Some(requested_length) = requested_length
10854            && let Some(value) = call.optval()
10855        {
10856            let bytes = DETERMINISTIC_NETNS_COOKIE.to_ne_bytes();
10857            let write_length = (requested_length as usize).min(bytes.len());
10858            guest
10859                .memory()
10860                .write_exact(value.cast(), &bytes[..write_length])?;
10861        }
10862        if let Some((cookie, Some(requested_length))) = deterministic_cookie
10863            && let Some(value) = call.optval()
10864        {
10865            let bytes = cookie.to_ne_bytes();
10866            let write_length = (requested_length as usize).min(bytes.len());
10867            guest
10868                .memory()
10869                .write_exact(value.cast(), &bytes[..write_length])?;
10870        }
10871        Ok(result)
10872    }
10873    // AUTONOMOUS-BOT-IMPLEMENTED
10874    // TODO-HUMAN-REVIEW(#818)
10875    /// Half-close the read and/or write direction of an already tracked socket.
10876    /// shutdown never blocks and returns no data; its effect is deterministic
10877    /// given the container's socket state, so it forwards via record_or_replay
10878    /// exactly like the rest of the socket family (KVM ratchet round 12).
10879    pub async fn handle_shutdown<G: Guest<Self>>(
10880        &self,
10881        guest: &mut G,
10882        call: syscalls::Shutdown,
10883    ) -> Result<i64, Error> {
10884        Ok(self.record_or_replay(guest, call).await?)
10885    }
10886
10887    /// bind system call.
10888    pub async fn handle_bind<G: Guest<Self>>(
10889        &self,
10890        guest: &mut G,
10891        call: syscalls::Bind,
10892    ) -> Result<i64, Error> {
10893        // WIP!
10894        if guest.config().sched_heuristic == SchedHeuristic::ConnectBind {
10895            trace!("Scheduling heuristic: reprioritizing bind");
10896            let resource = ResourceID::PriorityChangePoint(
10897                LAST_PRIORITY,
10898                guest.thread_state().thread_logical_time.as_nanos(),
10899                guest.thread_state().committed_clock_value,
10900                Vec::new(),
10901            );
10902            let req = guest.thread_state().mk_request(resource, Permission::W);
10903            resource_request(guest, req).await;
10904        }
10905        let addr = call.umyaddr().ok_or(Errno::EFAULT)?;
10906        let sock_fd = call.fd();
10907        let open_file_id = guest
10908            .thread_state()
10909            .with_detfd(sock_fd, |detfd| detfd.open_file_id())?;
10910
10911        let sockaddr_family = guest.memory().read_value(addr.cast::<u16>())?;
10912        // AUTONOMOUS-BOT-IMPLEMENTED
10913        // TODO-HUMAN-REVIEW(PR-872): Review deterministic AF_UNIX autobind identity.
10914        if sockaddr_family == libc::AF_UNIX as u16
10915            && call.addrlen() == std::mem::offset_of!(libc::sockaddr_un, sun_path) as i32
10916        {
10917            let resp = send_and_update_time(guest, GlobalRequest::RequestPort(open_file_id)).await;
10918            let port = match resp.1 {
10919                GlobalResponse::RequestPort(port) => port,
10920                GlobalResponse::PortFull => {
10921                    return Err(reverie::Error::from(nix::errno::Errno::EADDRINUSE));
10922                }
10923                _ => unreachable!(),
10924            };
10925
10926            let mut stack = guest.stack().await;
10927            let autobind_addr: AddrMut<libc::sockaddr_un> = stack.reserve();
10928            let _stack_guard = stack.commit()?;
10929            guest
10930                .memory()
10931                .write_value(autobind_addr, &unix_autobind_address(port))?;
10932            let deterministic_bind = call
10933                .with_umyaddr(Some(autobind_addr.cast()))
10934                .with_addrlen(unix_autobind_addrlen());
10935            return Ok(self.record_or_replay(guest, deterministic_bind).await?);
10936        // AUTONOMOUS-BOT-IMPLEMENTED
10937        // TODO-HUMAN-REVIEW(PR-880): Review deterministic Netlink autobind identities.
10938        } else if sockaddr_family == libc::AF_NETLINK as u16
10939            && call.addrlen() >= std::mem::size_of::<libc::sockaddr_nl>() as i32
10940        {
10941            let mut sockaddr_nl: libc::sockaddr_nl = guest
10942                .memory()
10943                .read_value(addr.cast::<libc::sockaddr_nl>())?;
10944            if sockaddr_nl.nl_pid == 0 {
10945                let resp =
10946                    send_and_update_time(guest, GlobalRequest::RequestPort(open_file_id)).await;
10947                match resp.1 {
10948                    GlobalResponse::RequestPort(port) => {
10949                        sockaddr_nl.nl_pid = DETERMINISTIC_NETLINK_PORT_ID_BASE | u32::from(port);
10950                        let mut stack = guest.stack().await;
10951                        let deterministic_addr: AddrMut<libc::sockaddr_nl> = stack.reserve();
10952                        let _stack_guard = stack.commit()?;
10953                        guest
10954                            .memory()
10955                            .write_value(deterministic_addr, &sockaddr_nl)?;
10956                        let deterministic_bind = call.with_umyaddr(Some(deterministic_addr.cast()));
10957                        return Ok(self.record_or_replay(guest, deterministic_bind).await?);
10958                    }
10959                    GlobalResponse::PortFull => {
10960                        return Err(reverie::Error::from(nix::errno::Errno::EADDRINUSE));
10961                    }
10962                    _ => unreachable!(),
10963                }
10964            }
10965        } else if sockaddr_family == libc::AF_INET as u16 {
10966            // For IPv4
10967            let mut sockaddr_in: libc::sockaddr_in = guest
10968                .memory()
10969                .read_value(addr.cast::<libc::sockaddr_in>())?;
10970
10971            let port = sockaddr_in.sin_port.to_be();
10972            let ipaddr = Ipv4Addr::from(sockaddr_in.sin_addr.s_addr);
10973            if port != 0 {
10974                if guest.config().warn_non_zero_binds {
10975                    warn!(
10976                        "Analyze Networking: Non-zero port detected: {:?}:{:?}",
10977                        ipaddr, port
10978                    );
10979                }
10980                // Send RPC to make sure already used ports are not used.
10981                let resp =
10982                    send_and_update_time(guest, GlobalRequest::AddUsedPort(port, open_file_id))
10983                        .await;
10984                match resp.1 {
10985                    GlobalResponse::AddUsedPort => {
10986                        trace!("Added to used port {}", port);
10987                    }
10988                    _ => unreachable!(),
10989                }
10990            } else {
10991                // Request a determinzed port
10992                let resp =
10993                    send_and_update_time(guest, GlobalRequest::RequestPort(open_file_id)).await;
10994                match resp.1 {
10995                    GlobalResponse::RequestPort(port_assigned) => {
10996                        sockaddr_in.sin_port = port_assigned.to_be();
10997                        guest
10998                            .memory()
10999                            .write_value(addr.cast::<libc::sockaddr_in>(), &sockaddr_in)?;
11000                    }
11001                    GlobalResponse::PortFull => {
11002                        return Err(reverie::Error::from(nix::errno::Errno::EADDRINUSE));
11003                    }
11004                    _ => unreachable!(),
11005                }
11006            }
11007        } else if sockaddr_family == libc::AF_INET6 as u16 {
11008            // For IPv6
11009            let mut sockfaddr_in: libc::sockaddr_in6 = guest
11010                .memory()
11011                .read_value(addr.cast::<libc::sockaddr_in6>())?;
11012            let port = sockfaddr_in.sin6_port.to_be();
11013            let ipaddr = Ipv6Addr::from(sockfaddr_in.sin6_addr.s6_addr);
11014            if port != 0 {
11015                if guest.config().warn_non_zero_binds {
11016                    warn!(
11017                        "Analyze Networking: Non-zero port detected: {:?}:{:?}",
11018                        ipaddr, port
11019                    );
11020                }
11021                let resp =
11022                    send_and_update_time(guest, GlobalRequest::AddUsedPort(port, open_file_id))
11023                        .await;
11024                match resp.1 {
11025                    GlobalResponse::AddUsedPort => {
11026                        trace!("Added to used port {}", port);
11027                    }
11028                    _ => unreachable!(),
11029                }
11030            } else {
11031                let resp =
11032                    send_and_update_time(guest, GlobalRequest::RequestPort(open_file_id)).await;
11033                match resp.1 {
11034                    GlobalResponse::RequestPort(port_assigned) => {
11035                        sockfaddr_in.sin6_port = port_assigned.to_be();
11036                        guest
11037                            .memory()
11038                            .write_value(addr.cast::<libc::sockaddr_in6>(), &sockfaddr_in)?;
11039                        trace!("Port assigned {}", port_assigned)
11040                    }
11041                    GlobalResponse::PortFull => {
11042                        return Err(reverie::Error::from(nix::errno::Errno::EADDRINUSE));
11043                    }
11044                    _ => unreachable!(),
11045                }
11046            }
11047        }
11048        let res = self.record_or_replay(guest, call).await?;
11049
11050        Ok(res)
11051    }
11052
11053    /// Create and register an event notification counter.
11054    ///
11055    /// Determinism: strict execution serializes creation, so the initial counter, guest-visible
11056    /// flags, and descriptor number depend only on syscall arguments and the reconstructed file
11057    /// table. Any internally added nonblocking flag remains hidden from the guest.
11058    pub async fn handle_eventfd2<G: Guest<Self>>(
11059        &self,
11060        guest: &mut G,
11061        call: syscalls::Eventfd2,
11062    ) -> Result<i64, Error> {
11063        let internally_nonblocking =
11064            self.cfg.use_nonblocking_sockets() && !self.cfg.recordreplay_modes;
11065        let injected = if internally_nonblocking {
11066            call.with_flags(call.flags() | syscalls::EfdFlags::EFD_NONBLOCK)
11067        } else {
11068            call
11069        };
11070        let fd = self.record_or_replay(guest, injected).await? as RawFd;
11071        self.add_fd(
11072            guest,
11073            fd,
11074            OFlag::from_bits_truncate(
11075                call.flags().bits() & (libc::EFD_CLOEXEC | libc::EFD_NONBLOCK),
11076            ),
11077            FdType::Eventfd,
11078        )
11079        .await?;
11080        if internally_nonblocking {
11081            self.maybe_set_nonblocking_fd(guest, fd);
11082        }
11083        Ok(fd as i64)
11084    }
11085
11086    /// signalfd4 system call.
11087    pub async fn handle_signalfd4<G: Guest<Self>>(
11088        &self,
11089        guest: &mut G,
11090        call: syscalls::Signalfd4,
11091    ) -> Result<i64, Error> {
11092        // A signalfd of a pending real-time timer expiration that every thread
11093        // blocked when it expired would be readable at once
11094        // (https://github.com/rrnewton/hermit/issues/4089). A mask the kernel
11095        // cannot read fails the call below.
11096        let mask = match call.mask().and_then(|mask| Addr::from_raw(mask.as_raw())) {
11097            Some(mask) => {
11098                // The call's first injection (`restart_if_first_probe_not_run`).
11099                match crate::syscalls::signal::restart_if_first_probe_not_run(
11100                    crate::syscalls::signal::read_kernel_sigset(guest, mask).await,
11101                ) {
11102                    Err(Error::Errno(Errno::ERESTARTNOINTR)) => {
11103                        return Err(Errno::ERESTARTNOINTR.into());
11104                    }
11105                    read => read.ok(),
11106                }
11107            }
11108            None => None,
11109        };
11110        if let Some(mask) = mask {
11111            let pending = crate::syscalls::helpers::pending_real_time_among(guest, mask).await;
11112            crate::syscalls::helpers::act_on_pending_real_time(guest, pending, mask, 0).await;
11113        }
11114        let signalfd = self.record_or_replay(guest, call).await? as RawFd;
11115        // A real-time timer expiration this descriptor, or a copy a fork
11116        // inherits, could read is never kept pending
11117        // (`Scheduler::real_time_expiration_fate`), a `SIGEV_THREAD_ID`
11118        // timer's copy of a signal it covers may be taken unobserved
11119        // (`Scheduler::thread_timer_copy_is_observable`), and a process one
11120        // of whose threads blocks in an I/O call while it holds one for
11121        // SIGCHLD does not attribute SIGCHLD through the send window
11122        // (`Scheduler::note_outside_blocker`), since that call may read it
11123        // outside the schedule.
11124        if let Some(mask) = mask
11125            && mask != 0
11126            && let Some(detpid) = guest.thread_state().detpid
11127        {
11128            crate::tool_global::register_signalfd(guest, detpid, mask).await;
11129        }
11130        self.add_fd(
11131            guest,
11132            signalfd,
11133            OFlag::from_bits_truncate(
11134                call.flags().bits() & (libc::SFD_CLOEXEC | libc::SFD_NONBLOCK),
11135            ),
11136            FdType::Signalfd,
11137        )
11138        .await?;
11139        Ok(signalfd as i64)
11140    }
11141
11142    /// Create and register a timer notification descriptor.
11143    ///
11144    /// Determinism: strict execution serializes creation, which exposes only kernel validation,
11145    /// guest-visible flags, and a descriptor number; this operation does not read the clock.
11146    pub async fn handle_timerfd_create<G: Guest<Self>>(
11147        &self,
11148        guest: &mut G,
11149        call: syscalls::TimerfdCreate,
11150    ) -> Result<i64, Error> {
11151        // A timerfd on virtual time is physically nonblocking, as an eventfd
11152        // is, so a logically blocking read retries in scheduler turns
11153        // (internal IO polling) instead of blocking in the host until a
11154        // host-timed moment (`crate::syscalls::timerfd`).
11155        crate::syscalls::timerfd::refuse_unshared_model(guest);
11156        let internally_nonblocking = crate::syscalls::timerfd::enabled(guest);
11157        let injected = if internally_nonblocking {
11158            call.with_flags(call.flags() | syscalls::TimerFlags::TFD_NONBLOCK)
11159        } else {
11160            call
11161        };
11162        let fd = self.record_or_replay(guest, injected).await? as RawFd;
11163        self.add_fd(
11164            guest,
11165            fd,
11166            OFlag::from_bits_truncate(
11167                call.flags().bits() & (libc::TFD_CLOEXEC | libc::TFD_NONBLOCK),
11168            ),
11169            FdType::Timerfd,
11170        )
11171        .await?;
11172        if internally_nonblocking {
11173            self.maybe_set_nonblocking_fd(guest, fd);
11174        }
11175        Ok(fd as i64)
11176    }
11177
11178    /// Serialize a notification descriptor control operation.
11179    async fn notification_fd_control<G: Guest<Self>>(
11180        &self,
11181        guest: &mut G,
11182        call: Syscall,
11183    ) -> Result<i64, Error> {
11184        let dettid = guest.thread_state().dettid;
11185        resource_request(guest, Resources::new(dettid)).await;
11186        Ok(self.record_or_replay(guest, call).await?)
11187    }
11188
11189    /// timerfd_settime system call. Under virtual time the setting is kept on
11190    /// Detcore's clock and the host timerfd stays disarmed
11191    /// (`crate::syscalls::timerfd`).
11192    pub async fn handle_timerfd_settime<G: Guest<Self>>(
11193        &self,
11194        guest: &mut G,
11195        call: syscalls::TimerfdSettime,
11196    ) -> Result<i64, Error> {
11197        let dettid = guest.thread_state().dettid;
11198        resource_request(guest, Resources::new(dettid)).await;
11199        if let Some(result) = crate::syscalls::timerfd::settime(guest, call).await? {
11200            return Ok(result);
11201        }
11202        Ok(self.record_or_replay(guest, call).await?)
11203    }
11204
11205    /// timerfd_gettime system call, answered from the virtual clock for a
11206    /// timerfd Detcore keeps there.
11207    pub async fn handle_timerfd_gettime<G: Guest<Self>>(
11208        &self,
11209        guest: &mut G,
11210        call: syscalls::TimerfdGettime,
11211    ) -> Result<i64, Error> {
11212        let dettid = guest.thread_state().dettid;
11213        resource_request(guest, Resources::new(dettid)).await;
11214        if let Some(result) = crate::syscalls::timerfd::gettime(guest, call).await? {
11215            return Ok(result);
11216        }
11217        Ok(self.record_or_replay(guest, call).await?)
11218    }
11219
11220    /// inotify_init1 system call.
11221    pub async fn handle_inotify_init1<G: Guest<Self>>(
11222        &self,
11223        guest: &mut G,
11224        call: syscalls::InotifyInit1,
11225    ) -> Result<i64, Error> {
11226        let fd = self.record_or_replay(guest, call).await? as RawFd;
11227        self.add_fd(
11228            guest,
11229            fd,
11230            OFlag::from_bits_truncate(call.flags().bits() & (libc::IN_CLOEXEC | libc::IN_NONBLOCK)),
11231            FdType::Inotify,
11232        )
11233        .await?;
11234        Ok(fd as i64)
11235    }
11236
11237    /// inotify_add_watch system call.
11238    pub async fn handle_inotify_add_watch<G: Guest<Self>>(
11239        &self,
11240        guest: &mut G,
11241        call: syscalls::InotifyAddWatch,
11242    ) -> Result<i64, Error> {
11243        self.notification_fd_control(guest, call.into()).await
11244    }
11245
11246    /// inotify_rm_watch system call.
11247    pub async fn handle_inotify_rm_watch<G: Guest<Self>>(
11248        &self,
11249        guest: &mut G,
11250        call: syscalls::InotifyRmWatch,
11251    ) -> Result<i64, Error> {
11252        self.notification_fd_control(guest, call.into()).await
11253    }
11254
11255    /// memfd_create system call.
11256    pub async fn handle_memfd_create<G: Guest<Self>>(
11257        &self,
11258        guest: &mut G,
11259        call: syscalls::MemfdCreate,
11260    ) -> Result<i64, Error> {
11261        let fd = self.record_or_replay(guest, call).await? as RawFd;
11262        self.add_fd(
11263            guest,
11264            fd,
11265            OFlag::from_bits_truncate((call.flags() & libc::MFD_CLOEXEC) as i32),
11266            FdType::Memfd,
11267        )
11268        .await?;
11269        Ok(fd as i64)
11270    }
11271
11272    // AUTONOMOUS-BOT-IMPLEMENTED
11273    // TODO-HUMAN-REVIEW(PR-862): pidfd creation and Detcore FD registration.
11274    /// Create a pidfd through record/replay and synchronize the descriptor with
11275    /// Detcore's metadata before fcntl, poll, close, or waitid can observe it.
11276    pub async fn handle_pidfd_open<G: Guest<Self>>(
11277        &self,
11278        guest: &mut G,
11279        call: syscalls::PidfdOpen,
11280    ) -> Result<i64, Error> {
11281        let allowed_flags = libc::O_NONBLOCK as u32;
11282        if call.flags() & !allowed_flags != 0 {
11283            return Err(Errno::EINVAL.into());
11284        }
11285        // A pidfd for Hermit's own process, PID 1 of the guest's namespace,
11286        // would let `pidfd_send_signal` signal it and `pidfd_getfd` take its
11287        // descriptors (https://github.com/rrnewton/hermit/issues/4066). Linux
11288        // would open it; refusing it with EPERM is a policy, the answer the
11289        // guest already gets for `ptrace` and `process_vm_readv` on that process.
11290        let pid = call.pid() as i32;
11291        // A nested caller names its own namespace's pid, where none of
11292        // Hermit's tasks is visible; the pidfd records the task it names
11293        // (https://github.com/rrnewton/hermit/issues/4155). A pid no task of
11294        // that namespace has goes to the kernel, which answers ESRCH.
11295        if pid > 0 && guest.thread_state().nested_pid_namespace {
11296            let target = match crate::tool_global::guest_pid(guest, pid).await {
11297                crate::scheduler::pid_namespaces::GuestPidAnswer::Task { task, .. } => Some(task),
11298                crate::scheduler::pid_namespaces::GuestPidAnswer::NoSuchPid => None,
11299                crate::scheduler::pid_namespaces::GuestPidAnswer::Untranslatable(reason) => {
11300                    tracing::error!(
11301                        "[detcore, dtid {}] pidfd_open of pid {} from a nested PID namespace is not supported: {} (https://github.com/rrnewton/hermit/issues/4155)",
11302                        guest.thread_state().dettid,
11303                        pid,
11304                        reason,
11305                    );
11306                    return self
11307                        .refuse_unserviceable_operation(guest, Sysno::pidfd_open, Errno::ENOSYS)
11308                        .await;
11309                }
11310            };
11311            let fd = self.record_or_replay(guest, call).await? as RawFd;
11312            let flags = OFlag::O_CLOEXEC | OFlag::from_bits_truncate(call.flags() as libc::c_int);
11313            self.add_fd(guest, fd, flags, FdType::Pidfd).await?;
11314            if let Some(target) = target {
11315                guest
11316                    .thread_state()
11317                    .with_detfd(fd, |detfd| detfd.set_pidfd_target(target))?;
11318            }
11319            return Ok(fd as i64);
11320        }
11321        if pid > 0 && crate::tool_global::names_hermit_task(guest, Some(pid), pid).await {
11322            tracing::info!(
11323                "[detcore, dtid {}] pidfd_open of {}, Hermit's own process: refused with EPERM \
11324                 (https://github.com/rrnewton/hermit/issues/4066)",
11325                guest.thread_state().dettid,
11326                pid,
11327            );
11328            return Err(Errno::EPERM.into());
11329        }
11330
11331        let fd = self.record_or_replay(guest, call).await? as RawFd;
11332        let flags = OFlag::O_CLOEXEC | OFlag::from_bits_truncate(call.flags() as libc::c_int);
11333        self.add_fd(guest, fd, flags, FdType::Pidfd).await?;
11334        let target = DetPid::from_raw(call.pid() as i32);
11335        guest
11336            .thread_state()
11337            .with_detfd(fd, |detfd| detfd.set_pidfd_target(target))?;
11338        Ok(fd as i64)
11339    }
11340
11341    // AUTONOMOUS-BOT-IMPLEMENTED
11342    // TODO-HUMAN-REVIEW(PR-1175): pidfd_send_signal(2) determinization.
11343    /// Deliver a signal to the process referred to by a pidfd.
11344    ///
11345    /// `pidfd_send_signal(pidfd, sig, info, flags)` names its target by an open
11346    /// kernel descriptor rather than a numeric PID. Unlike `kill(2)`, there is
11347    /// therefore no host-PID/virtual-PID ambiguity for Detcore to resolve: the
11348    /// pidfd was bound to one specific process at `pidfd_open` time. Signal
11349    /// generation runs inside this thread's serialized scheduler turn, as for
11350    /// `tgkill`/`tkill`/`rt_tgsigqueueinfo`, which forward through record/replay
11351    /// and then tell the scheduler that the signal is pending for its receiver
11352    /// (`notify_cross_task_signal`), so that a receiver parked in a blocking call
11353    /// is woken. This handler does the same for a process with one live thread
11354    /// (<https://github.com/rrnewton/hermit/issues/4099>).
11355    ///
11356    /// The flags and the descriptor are decided as Linux decides them, ahead of
11357    /// the forward (<https://github.com/rrnewton/hermit/issues/4108>):
11358    /// - an unknown flag bit, or more than one of the three scope flags, is
11359    ///   EINVAL; `PIDFD_SIGNAL_THREAD_GROUP` is the scope a process pidfd has
11360    ///   anyway, and `PIDFD_SIGNAL_THREAD` sends to the thread whose id is the
11361    ///   pid, as `tgkill(pid, pid)` does; `PIDFD_SIGNAL_PROCESS_GROUP` is
11362    ///   refused by name, even with signal 0, whose answer would come from the
11363    ///   process group the guest inherits from Hermit;
11364    /// - a descriptor names a process when it is a pidfd from `pidfd_open` or
11365    ///   a `/proc/<pid>` directory of the guest's procfs
11366    ///   (`process_directory_descriptor`); any other file is EBADF, and a
11367    ///   descriptor Detcore cannot classify is refused by name.
11368    ///
11369    /// A process-directed signal to a process with several live threads is
11370    /// refused by name, as `kill` refuses it (`Detcore::process_signal_target`).
11371    ///
11372    /// `call` is the raw `Syscall::Other`; `pidfd`/`flags` are pre-extracted from
11373    /// its arguments by the dispatcher.
11374    pub async fn handle_pidfd_send_signal<G: Guest<Self>>(
11375        &self,
11376        guest: &mut G,
11377        call: Syscall,
11378        pidfd: RawFd,
11379        signal: i32,
11380        flags: u32,
11381    ) -> Result<i64, Error> {
11382        // Linux checks the flags before it looks at the descriptor.
11383        let mut scope = pidfd_signal_scope(flags)?;
11384        let info = AddrMut::<libc::siginfo_t>::from_raw(call.into_parts().1.arg2);
11385        if let Some(refused) = self
11386            .refuse_forged_own_sigchld(guest, Sysno::pidfd_send_signal, signal, info)
11387            .await
11388        {
11389            return refused;
11390        }
11391        // The two sentinels name the caller without a descriptor: its thread
11392        // (`PIDFD_SELF_THREAD`, thread-directed unless a flag says otherwise)
11393        // or its thread group (`PIDFD_SELF_THREAD_GROUP`)
11394        // (https://github.com/rrnewton/hermit/issues/4147).
11395        let named = if let Some((target, default)) = pidfd_self_target(guest, pidfd) {
11396            if flags == 0 {
11397                scope = default;
11398            }
11399            Some(target)
11400        } else {
11401            // An unknown or closed descriptor is EBADF, and so is any file that is
11402            // neither a pidfd nor an opened path (a pipe, a socket, an eventfd...).
11403            // Linux's fdget skips an O_PATH descriptor, so it is EBADF too.
11404            let kind = guest
11405                .thread_state()
11406                .with_detfd(pidfd, |detfd| match detfd.ty() {
11407                    FdType::Pidfd => Some(Some(detfd.pidfd_target())),
11408                    FdType::Regular if detfd.status_flags() & libc::O_PATH == 0 => Some(None),
11409                    _ => None,
11410                })?;
11411            let Some(kind) = kind else {
11412                return Err(Errno::EBADF.into());
11413            };
11414            // `named` is the pid the descriptor names. A pidfd from `pidfd_open`
11415            // names a process leader; a `/proc/<tid>` directory may name any thread,
11416            // whose process is its leader's (https://github.com/rrnewton/hermit/issues/4094).
11417            match kind {
11418                Some(target) => target,
11419                None => {
11420                    let descriptor = if self.cfg.recordreplay_modes {
11421                        // Replay holds a placeholder for a reopened file, so the
11422                        // descriptor cannot be read the same way in both.
11423                        ProcessDirectoryDescriptor::Unknown(
11424                            "record and replay do not read what a descriptor names",
11425                        )
11426                    } else if !bundled_signal_facts::host_task_reads_enabled(
11427                        &guest.config().backend,
11428                    ) {
11429                        // Only on ptrace are the guest's thread ids the host's, so
11430                        // that its descriptors can be read through /proc/<tid>.
11431                        ProcessDirectoryDescriptor::Unknown(
11432                            "this backend's guest thread ids are not host thread ids",
11433                        )
11434                    } else {
11435                        process_directory_descriptor(guest.tid().as_raw(), pidfd)
11436                    };
11437                    match descriptor {
11438                        ProcessDirectoryDescriptor::Process(task)
11439                            if crate::tool_global::names_hermit_task(
11440                                guest,
11441                                None,
11442                                task.as_raw(),
11443                            )
11444                            .await =>
11445                        {
11446                            // Any of Hermit's threads, as a `kill` naming one is
11447                            // dropped and `pidfd_open` of Hermit's process is refused
11448                            // (https://github.com/rrnewton/hermit/issues/4066).
11449                            tracing::info!(
11450                                "[detcore, dtid {}] pidfd_send_signal through /proc/{}, one of \
11451                                 Hermit's own threads: refused with EPERM",
11452                                guest.thread_state().dettid,
11453                                task,
11454                            );
11455                            return Err(Errno::EPERM.into());
11456                        }
11457                        ProcessDirectoryDescriptor::Process(task) => Some(task),
11458                        ProcessDirectoryDescriptor::NotAProcess => return Err(Errno::EBADF.into()),
11459                        ProcessDirectoryDescriptor::Unknown(reason) => {
11460                            tracing::error!(
11461                                "[detcore, dtid {}] pidfd_send_signal through descriptor {} is not \
11462                                 supported: {} (https://github.com/rrnewton/hermit/issues/4108)",
11463                                guest.thread_state().dettid,
11464                                pidfd,
11465                                reason,
11466                            );
11467                            return self
11468                                .refuse_unserviceable_operation(
11469                                    guest,
11470                                    Sysno::pidfd_send_signal,
11471                                    Errno::ENOSYS,
11472                                )
11473                                .await;
11474                        }
11475                    }
11476                }
11477            }
11478        };
11479        if scope == PidfdSignalScope::ProcessGroup {
11480            tracing::error!(
11481                "[detcore, dtid {}] signal {} by pidfd_send_signal with PIDFD_SIGNAL_PROCESS_GROUP \
11482                 is not supported: Detcore does not model process-group membership, and the \
11483                 guest's process group is inherited from Hermit's \
11484                 (https://github.com/rrnewton/hermit/issues/4108)",
11485                guest.thread_state().dettid,
11486                signal,
11487            );
11488            return self
11489                .refuse_unserviceable_operation(guest, Sysno::pidfd_send_signal, Errno::ENOSYS)
11490                .await;
11491        }
11492        let process = match named {
11493            Some(named) => Some(signal_target_process(guest, named).await.unwrap_or(named)),
11494            None => None,
11495        };
11496        // A nested caller's signal to its own PID namespace's init is dropped
11497        // by the kernel unless the init catches it, SIGKILL always
11498        // (`Detcore::own_namespace_init_drops`): forward it unchanged, with
11499        // nothing to retire or record
11500        // (https://github.com/rrnewton/hermit/issues/4155).
11501        if guest.thread_state().nested_pid_namespace
11502            && let Some(process) = process
11503            && let Ok(Some(local)) = crate::tool_global::local_pid(guest, process).await
11504            && let crate::scheduler::pid_namespaces::GuestPidAnswer::Task {
11505                own_init_caught, ..
11506            } = crate::tool_global::guest_pid(guest, local).await
11507            && Self::own_namespace_init_drops(own_init_caught, signal)
11508        {
11509            return Ok(self.record_or_replay(guest, call).await?);
11510        }
11511        // A process Detcore saw exit and that is gone is ESRCH, as Linux
11512        // answers once it is reaped, whatever the host has reaped by now
11513        // (https://github.com/rrnewton/hermit/issues/4091).
11514        if guest.config().sequentialize_threads
11515            && let Some(process) = process
11516        {
11517            let (targets, zombie) = resolve_kill_targets_and_exit(guest, process).await;
11518            if targets.is_empty() && zombie == Some(false) {
11519                return self.gone_pidfd_signal_answer(guest, call, signal).await;
11520            }
11521        }
11522        // The thread scope sends to the thread whose id is the pid, like
11523        // `tgkill(pid, pid)`; the process scope to its process.
11524        let thread_scope = scope == PidfdSignalScope::Thread;
11525        let receiver_id = if thread_scope { named } else { process };
11526        self.record_orphaned_group_signals(guest, signal).await;
11527        if signal == libc::SIGALRM {
11528            // `pidfd_open` records the process a pidfd names; a pidfd with no
11529            // recorded target is refused while any process handles SIGALRM.
11530            let control = match receiver_id {
11531                Some(target) => SigalrmControl::SendTo(DetTid::from_raw(target.as_raw())),
11532                None => SigalrmControl::SendToUnnamed,
11533            };
11534            refuse_sigalrm(guest, control).await?;
11535        }
11536        // A thread-scoped SIGKILL to a leader that exited while its group
11537        // lives on changes nothing, as `tgkill`'s does
11538        // (https://github.com/rrnewton/hermit/issues/4445).
11539        let exited_leader = signal == libc::SIGKILL
11540            && guest.config().sequentialize_threads
11541            && thread_scope
11542            && match named {
11543                Some(thread) => {
11544                    crate::syscalls::signal::sigkill_names_an_exited_leader(
11545                        guest,
11546                        DetTid::from_raw(thread.as_raw()),
11547                    )
11548                    .await
11549                }
11550                None => false,
11551            };
11552        if signal == libc::SIGKILL
11553            && guest.config().sequentialize_threads
11554            && !exited_leader
11555            && let (Some(process), Some(receiver)) = (process, receiver_id)
11556        {
11557            // A SIGKILL ends the whole process whichever thread it names, and
11558            // is retired at this turn as `kill`'s and `tgkill`'s are
11559            // (https://github.com/rrnewton/hermit/issues/3994).
11560            if self
11561                .reserve_controlled_self_sigkill_exit(
11562                    guest,
11563                    signal,
11564                    Some(process),
11565                    thread_scope.then(|| DetTid::from_raw(receiver.as_raw())),
11566                )
11567                .await
11568            {
11569                return Ok(self.record_or_replay(guest, call).await?);
11570            }
11571            if let Some(reservation) =
11572                reserve_sigkill(guest, DetTid::from_raw(receiver.as_raw())).await
11573            {
11574                return self.send_reserved_sigkill(guest, reservation, call).await;
11575            }
11576        }
11577        if thread_scope {
11578            // A thread-scoped send queues the copy in the named thread's
11579            // private queue (the Claude re-check of
11580            // https://github.com/rrnewton/hermit/pull/4131).
11581            let value = match (named, process) {
11582                (Some(thread), Some(process)) => {
11583                    self.send_guest_signal(
11584                        guest,
11585                        call,
11586                        DetTid::from_raw(thread.as_raw()),
11587                        signal,
11588                        Some(process),
11589                        true,
11590                        DetTid::from_raw(thread.as_raw()),
11591                    )
11592                    .await?
11593                }
11594                _ => self.record_or_replay(guest, call).await?,
11595            };
11596            if exited_leader {
11597                return Ok(value);
11598            }
11599            if let (Some(thread), Some(process)) = (named, process) {
11600                let thread = DetTid::from_raw(thread.as_raw());
11601                if signal == libc::SIGKILL {
11602                    crate::tool_global::notify_signal_pending(
11603                        guest,
11604                        thread,
11605                        SigWrapper(libc::SIGKILL),
11606                        Some(process),
11607                        crate::tool_global::SignalScope::Thread,
11608                    )
11609                    .await;
11610                } else {
11611                    self.notify_cross_task_signal(
11612                        guest,
11613                        thread,
11614                        signal,
11615                        Some(process),
11616                        crate::tool_global::SignalScope::Thread,
11617                    )
11618                    .await;
11619                }
11620            }
11621            return Ok(value);
11622        }
11623        // A process-directed signal. To a process with two or more live threads
11624        // it is refused by name as `kill` refuses it: Linux's complete_signal
11625        // picks the receiving thread, which Detcore does not model
11626        // (https://github.com/rrnewton/hermit/issues/4047). Everything else is
11627        // forwarded and the kernel answers: signal 0, which only checks that
11628        // the process exists; a SIGKILL that could not be reserved, which kills
11629        // the whole group whichever thread it reaches (the scheduler is told
11630        // below); a process with one live thread, whose receiver the scheduler
11631        // is then told about, as `kill` does; and a process with none (a
11632        // zombie, which Linux still signals successfully).
11633        let mut receiver = None;
11634        if signal != 0
11635            && signal != libc::SIGKILL
11636            && guest.config().sequentialize_threads
11637            && let Some(target) = process
11638        {
11639            match resolve_kill_targets(guest, target).await.as_slice() {
11640                [] => {}
11641                [thread] => receiver = Some((*thread, target)),
11642                _ => {
11643                    self.process_signal_target(
11644                        guest,
11645                        reverie::syscalls::Sysno::pidfd_send_signal,
11646                        target,
11647                        signal,
11648                    )
11649                    .await?;
11650                }
11651            }
11652        }
11653        let value = match receiver {
11654            Some((thread, process)) => {
11655                // A process-scoped pidfd names the process's leader
11656                // (`pidfd_send_signal` with `PIDTYPE_TGID`).
11657                self.send_guest_signal(
11658                    guest,
11659                    call,
11660                    thread,
11661                    signal,
11662                    Some(process),
11663                    false,
11664                    DetTid::from_raw(process.as_raw()),
11665                )
11666                .await?
11667            }
11668            None => self.record_or_replay(guest, call).await?,
11669        };
11670        if let Some((thread, process)) = receiver {
11671            // Tell the scheduler, as `kill` does, so a receiver parked in a
11672            // blocking call (pause(), a futex wait) is woken to take it
11673            // (https://github.com/rrnewton/hermit/issues/4099).
11674            self.notify_cross_task_signal(
11675                guest,
11676                thread,
11677                signal,
11678                Some(process),
11679                crate::tool_global::SignalScope::Process,
11680            )
11681            .await;
11682        }
11683        if signal == libc::SIGKILL {
11684            // A process killed through a pidfd will die; the scheduler must
11685            // not count a wait for it as part of a deadlock
11686            // (https://github.com/rrnewton/hermit/issues/3904).
11687            match process {
11688                Some(target) => {
11689                    crate::tool_global::notify_signal_pending(
11690                        guest,
11691                        DetTid::from_raw(target.as_raw()),
11692                        SigWrapper(libc::SIGKILL),
11693                        Some(target),
11694                        crate::tool_global::SignalScope::Process,
11695                    )
11696                    .await
11697                }
11698                None => crate::tool_global::notify_unresolved_sigkill(guest, None).await,
11699            }
11700        }
11701        Ok(value)
11702    }
11703
11704    /// The answer to a `pidfd_send_signal` whose target Detcore saw exit and
11705    /// that is gone, in Linux's order: a non-NULL `info` is copied and its
11706    /// layout checked against its own `si_signo` (EFAULT, E2BIG), then that
11707    /// `si_signo` against the signal (EINVAL), then a forged `si_code`
11708    /// (EPERM), and only then is the task missing (ESRCH). The copy, the layout
11709    /// check and the `si_code` check are the kernel's: the same `info` goes to
11710    /// `rt_sigqueueinfo` naming a pid no task can have, which makes those
11711    /// checks and sends nothing (as
11712    /// <https://github.com/rrnewton/hermit/issues/4124> does for that call).
11713    /// `rt_sigqueueinfo` checks the layout against the signal it is given, so
11714    /// it is given the info's own `si_signo`.
11715    async fn gone_pidfd_signal_answer<G: Guest<Self>>(
11716        &self,
11717        guest: &mut G,
11718        call: Syscall,
11719        signal: i32,
11720    ) -> Result<i64, Error> {
11721        let info = match call {
11722            Syscall::Other(_, args) => args.arg2,
11723            _ => 0,
11724        };
11725        let Some(info) = AddrMut::<libc::siginfo_t>::from_raw(info) else {
11726            return Err(Errno::ESRCH.into());
11727        };
11728        let signo = guest.memory().read_value(info.cast::<libc::c_int>()).ok();
11729        let checked = guest
11730            .inject(
11731                syscalls::RtSigqueueinfo::new()
11732                    .with_tgid(super::signal::NO_SUCH_PID)
11733                    .with_sig(signo.unwrap_or(signal))
11734                    .with_siginfo(Some(info)),
11735            )
11736            .await;
11737        let answer = match checked {
11738            Err(errno @ (Errno::EPERM | Errno::ESRCH)) => errno,
11739            Err(errno) => return Err(errno.into()),
11740            Ok(_) => Errno::ESRCH,
11741        };
11742        // The copy succeeded, so the kernel could read `si_signo`; a page
11743        // only the kernel reaches (`[vvar]`) cannot be decided here.
11744        let Some(signo) = signo else {
11745            tracing::error!(
11746                "[detcore, dtid {}] pidfd_send_signal to a gone process with a siginfo_t at \
11747                 {:#x} is not supported: Hermit cannot read its si_signo \
11748                 (https://github.com/rrnewton/hermit/issues/4108)",
11749                guest.thread_state().dettid,
11750                info.as_raw(),
11751            );
11752            return self
11753                .refuse_unserviceable_operation(guest, Sysno::pidfd_send_signal, Errno::ENOSYS)
11754                .await;
11755        };
11756        if signo != signal {
11757            return Err(Errno::EINVAL.into());
11758        }
11759        Err(answer.into())
11760    }
11761
11762    // AUTONOMOUS-BOT-IMPLEMENTED
11763    // TODO-HUMAN-REVIEW(PR-1175): pidfd_getfd(2) determinization and the
11764    // FdType of the duplicated descriptor.
11765    /// Duplicate a descriptor from the process referred to by a pidfd.
11766    ///
11767    /// `pidfd_getfd(pidfd, targetfd, flags)` returns a fresh descriptor in the
11768    /// caller that aliases `targetfd` in the target process. The source pidfd
11769    /// names one specific process fixed at `pidfd_open` time, the returned
11770    /// descriptor number is chosen through record/replay (so it is stable across
11771    /// runs), and a successful modeled operation executes inside this thread's
11772    /// serialized turn, so the result is deterministic. For zero flags, Detcore
11773    /// fails closed with `EBADF` unless it models the descriptor as a pidfd.
11774    /// Linux checks the kernel-reserved `flags` first, however, so a nonzero
11775    /// value takes the raw record/replay path and preserves the kernel's exact
11776    /// `EINVAL` across valid and invalid descriptor combinations.
11777    ///
11778    /// The modeled path is narrower than "same process": the caller must be the
11779    /// thread-group leader named by the pidfd. `CLONE_THREAD` does not imply
11780    /// `CLONE_FILES`, so a nonleader can share the target's TGID while using a
11781    /// different descriptor table. Requiring `target == getpid() == gettid()`
11782    /// proves that `targetfd` is resolved in the caller's exact table. The
11783    /// returned descriptor is then modeled as a real alias of the source open
11784    /// file description. Broader support needs a cross-task OFD channel that
11785    /// Detcore does not have today, so every other target is refused with
11786    /// `EOPNOTSUPP`. Failed calls leave descriptor state unchanged.
11787    pub async fn handle_pidfd_getfd<G: Guest<Self>>(
11788        &self,
11789        guest: &mut G,
11790        call: Syscall,
11791        pidfd: RawFd,
11792        targetfd: RawFd,
11793        flags: u32,
11794    ) -> Result<i64, Error> {
11795        if flags != 0 {
11796            return match self.record_or_replay(guest, call).await {
11797                Err(error) => Err(error.into()),
11798                Ok(fd) => {
11799                    let fd = fd as RawFd;
11800                    let close_result = guest.inject(syscalls::Close::new().with_fd(fd)).await;
11801                    Err(Error::Tool(anyhow::anyhow!(
11802                        "pidfd_getfd unexpectedly accepted reserved flags and returned fd {fd}; cleanup close result: {close_result:?}"
11803                    )))
11804                }
11805            };
11806        }
11807
11808        if !guest.config().sequentialize_threads {
11809            return self
11810                .refuse_unserviceable_operation(guest, Sysno::pidfd_getfd, Errno::EOPNOTSUPP)
11811                .await;
11812        }
11813
11814        // A nested caller's own getpid and gettid are its namespace's ids,
11815        // while a pidfd records the task in the container's: compare the
11816        // caller's own DetPid and DetTid then
11817        // (https://github.com/rrnewton/hermit/issues/4155).
11818        let (current_tgid, current_tid) = match guest.thread_state().detpid {
11819            Some(detpid) if guest.thread_state().nested_pid_namespace => {
11820                (detpid, guest.thread_state().dettid)
11821            }
11822            _ => (
11823                DetPid::from_raw(guest.inject(syscalls::Getpid::new()).await? as i32),
11824                DetTid::from_raw(guest.inject(syscalls::Gettid::new()).await? as i32),
11825            ),
11826        };
11827        let source = guest.thread_state().capture_pidfd_getfd_source(
11828            pidfd,
11829            targetfd,
11830            current_tgid,
11831            current_tid,
11832        )?;
11833        let fd = match self.record_or_replay(guest, call).await {
11834            Ok(fd) => fd as RawFd,
11835            Err(error) => {
11836                if let Some(open_file_id) = guest.thread_state().abandon_captured_fd(source) {
11837                    self.release_port_for_open_file(guest, open_file_id).await;
11838                }
11839                return Err(error.into());
11840            }
11841        };
11842        // pidfd_getfd always sets FD_CLOEXEC on the returned descriptor.
11843        let replaced = match guest.thread_state_mut().install_captured_fd(
11844            source,
11845            fd,
11846            OFlag::O_CLOEXEC,
11847        ) {
11848            Ok(replaced) => replaced,
11849            Err(error @ CapturedDetFdInstallError { .. }) => {
11850                let expected_files_id = error.expected_files_id;
11851                let actual_files_id = error.actual_files_id;
11852                let cleanup = error.into_cleanup();
11853                let close_result = guest
11854                    .inject(syscalls::Close::new().with_fd(cleanup.close_fd))
11855                    .await;
11856                if let Some(open_file_id) = cleanup.release_open_file {
11857                    self.release_port_for_open_file(guest, open_file_id).await;
11858                }
11859                if let Err(close_error) = close_result {
11860                    return Err(Error::Tool(anyhow::anyhow!(
11861                        "pidfd_getfd returned fd {fd}, but its captured source table changed from {expected_files_id:?} to {actual_files_id:?}; cleanup close failed with {close_error}"
11862                    )));
11863                }
11864                warn!(
11865                    "pidfd_getfd returned fd {fd}, but its captured source table changed from {expected_files_id:?} to {actual_files_id:?}; closed the result and refusing with EOPNOTSUPP"
11866                );
11867                return Err(Errno::EOPNOTSUPP.into());
11868            }
11869        };
11870        if let Some(open_file_id) = replaced {
11871            self.release_port_for_open_file(guest, open_file_id).await;
11872        }
11873        // This process now holds the description too, with any OFD or flock
11874        // lock it holds (`procfs::locks`).
11875        self.refresh_description_locks(guest, fd, LockCall::PidfdGetfd)
11876            .await?;
11877        Ok(fd as i64)
11878    }
11879
11880    /// userfaultfd system call.
11881    pub async fn handle_userfaultfd<G: Guest<Self>>(
11882        &self,
11883        guest: &mut G,
11884        call: syscalls::Userfaultfd,
11885    ) -> Result<i64, Error> {
11886        let fd = self.record_or_replay(guest, call).await? as RawFd;
11887        self.add_fd(
11888            guest,
11889            fd,
11890            OFlag::from_bits_truncate(call.flags()),
11891            FdType::Userfaultfd,
11892        )
11893        .await?;
11894        Ok(fd as i64)
11895    }
11896
11897    /// accept4 system call (MAYHANG).
11898    ///
11899    /// Category: External OR Internal IO
11900    /// ---------------------------------
11901    /// When do we know?  We only know if an accept4 did an extra-container IO AFTER it returns.
11902    /// I.e. we could accept a connection from another endpoint in the container, or from the outside,
11903    /// and we don't know which at the point where `accept4` is called.
11904    pub async fn handle_accept4<G: Guest<Self>>(
11905        &self,
11906        guest: &mut G,
11907        call: syscalls::Accept4,
11908    ) -> Result<i64, Error> {
11909        // This option applies both to the socket we're doing the accept call on, and the connection
11910        // that we return. We don't have any smart detection yet to separate internal/external, so
11911        // applies to everything.
11912        //
11913        // Record and replay leave the connection as the guest asked, as `handle_socket` does.
11914        // Their reads and writes on it run as backgrounded blocking calls, and on a physically
11915        // nonblocking connection such a call returns EAGAIN to a guest that asked to block
11916        // (https://github.com/rrnewton/hermit/issues/3882). The rejoin log orders their results.
11917        // TODO-HUMAN-REVIEW(PR-3908)
11918        let physically_nonblocking =
11919            self.cfg.use_nonblocking_sockets() && !self.cfg.recordreplay_modes;
11920        let call2 = if physically_nonblocking {
11921            // Let the socket returned from accept4 be physically nonblocking:
11922            call.with_flags(call.flags() | SockFlag::SOCK_NONBLOCK)
11923        } else {
11924            call
11925        };
11926        let in_turn = self.accept_in_turn_enabled()
11927            && guest
11928                .thread_state()
11929                .with_detfd(call.sockfd(), |detfd| detfd.is_accept_in_turn_listener())
11930                .unwrap_or(false);
11931        let fd = if in_turn {
11932            // Record and replay run the accept in the caller's turn, so the new descriptor's
11933            // number is allocated deterministically (https://github.com/rrnewton/hermit/issues/3880).
11934            self.accept_in_turn(guest, call2).await? as RawFd
11935        } else {
11936            // This will do blocking/polling as appropriate based on the fd status:
11937            self.execute_nonblockable_fd_syscall(guest, call2).await? as RawFd
11938        };
11939
11940        self.add_fd(
11941            guest,
11942            fd,
11943            // This will specify whether the socket returned is logically non-blocking:
11944            oflag_from_sock_bits(call.flags().bits()),
11945            FdType::Socket,
11946        )
11947        .await?;
11948        guest
11949            .thread_state()
11950            .with_detfd(fd, |detfd| detfd.set_accepted_connection())?;
11951
11952        if physically_nonblocking {
11953            self.maybe_set_nonblocking_fd(guest, fd);
11954        }
11955
11956        Ok(fd as i64)
11957    }
11958
11959    /// getdents system call.
11960    pub async fn handle_getdents<G: Guest<Self>>(
11961        &self,
11962        guest: &mut G,
11963        call: syscalls::Getdents,
11964    ) -> Result<i64, Error> {
11965        let virtualize = guest.config().virtualize_metadata;
11966        if !virtualize
11967            && (call.dirent().is_none()
11968                || !self.is_caller_descriptor_table(guest, call.fd() as i32))
11969        {
11970            return Ok(self.record_or_replay(guest, call).await?);
11971        }
11972        let buf = call.dirent().ok_or(Errno::EFAULT)?.cast::<u8>();
11973        let call = GetdentsCall {
11974            call: Syscall::from(call),
11975            empty: Syscall::from(call.with_count(0)),
11976            fd: call.fd() as i32,
11977            buf,
11978            capacity: call.count() as usize,
11979            format: DirentFormat::Legacy,
11980        };
11981        if virtualize {
11982            self.serve_directory_stream(guest, call).await
11983        } else {
11984            self.project_one_buffer(guest, call).await
11985        }
11986    }
11987
11988    /// getdents64 system call.
11989    pub async fn handle_getdents64<G: Guest<Self>>(
11990        &self,
11991        guest: &mut G,
11992        call: syscalls::Getdents64,
11993    ) -> Result<i64, Error> {
11994        let virtualize = guest.config().virtualize_metadata;
11995        if !virtualize
11996            && (call.dirent().is_none()
11997                || !self.is_caller_descriptor_table(guest, call.fd() as i32))
11998        {
11999            return Ok(self.record_or_replay(guest, call).await?);
12000        }
12001        let buf = call.dirent().ok_or(Errno::EFAULT)?.cast::<u8>();
12002        let call = GetdentsCall {
12003            call: Syscall::from(call),
12004            empty: Syscall::from(call.with_count(0)),
12005            fd: call.fd() as i32,
12006            buf,
12007            capacity: call.count() as usize,
12008            format: DirentFormat::Dirent64,
12009        };
12010        if virtualize {
12011            self.serve_directory_stream(guest, call).await
12012        } else {
12013            self.project_one_buffer(guest, call).await
12014        }
12015    }
12016
12017    /// Answer a `getdents` call from the open file's sorted directory stream
12018    /// (see [`DirectoryStream`]), reading the host directory first if the
12019    /// stream has no snapshot.
12020    ///
12021    /// Sorting each kernel buffer on its own is not enough: a directory larger
12022    /// than one buffer (about a thousand short names for glibc's 32KiB) would
12023    /// come back as sorted runs whose boundaries, and the host `d_off` cookies
12024    /// inside them, depend on the filesystem's on-disk layout.
12025    async fn serve_directory_stream<G: Guest<Self>>(
12026        &self,
12027        guest: &mut G,
12028        call: GetdentsCall<'_>,
12029    ) -> Result<i64, Error> {
12030        let negative = i32::try_from(call.capacity).is_err();
12031        let lock = match guest
12032            .thread_state()
12033            .with_detfd(call.fd, |detfd| detfd.directory_lock())
12034        {
12035            Ok(lock) => lock,
12036            // Detcore has no open file description for this descriptor (one
12037            // received through SCM_RIGHTS, for example), so there is nowhere
12038            // to keep a stream. Sort the one kernel buffer instead, as before
12039            // directory streams existed; the kernel reports a descriptor that
12040            // is not open at all.
12041            Err(Errno::EBADF) if negative => {
12042                return self.serve_negative_count(guest, call, None).await;
12043            }
12044            Err(Errno::EBADF) => return self.project_one_buffer(guest, call).await,
12045            Err(errno) => return Err(errno.into()),
12046        };
12047        let _serving = lock.lock().await;
12048        let (host_order, needs_snapshot, position) =
12049            guest.thread_state().with_detfd(call.fd, |detfd| {
12050                (
12051                    detfd.directory_in_host_order(),
12052                    detfd.directory_needs_snapshot(),
12053                    detfd.with_directory_stream(|stream| stream.position()).ok(),
12054                )
12055            })?;
12056        if negative {
12057            let stream = if host_order {
12058                None
12059            } else {
12060                position.map(|position| (position, needs_snapshot))
12061            };
12062            return self.serve_negative_count(guest, call, stream).await;
12063        }
12064        if host_order {
12065            return self.project_one_buffer(guest, call).await;
12066        }
12067        if !needs_snapshot {
12068            return self.serve_next_batch(guest, call).await;
12069        }
12070        let mark = directory_snapshot_mark(guest).await;
12071        if let Some((entries, inodes, order)) = self.modeled_directory_snapshot(guest, call).await?
12072        {
12073            let mut entries = Some(entries);
12074            guest.thread_state().with_detfd(call.fd, |detfd| {
12075                detfd.install_directory_snapshot(
12076                    entries.take().unwrap_or_default(),
12077                    mark,
12078                    inodes.clone(),
12079                    order,
12080                )
12081            })?;
12082            return self.serve_next_batch(guest, call).await;
12083        }
12084        // How to key the entries' numbers is decided with the snapshot, as a
12085        // procfs directory loses its name once its task exits (see
12086        // `DirectoryStream`).
12087        let inodes = self.directory_inodes(guest, call.fd).await?;
12088        match self.snapshot_directory_privately(guest, call).await {
12089            Ok(Some(entries)) => {
12090                let mut entries = Some(entries);
12091                guest.thread_state().with_detfd(call.fd, |detfd| {
12092                    detfd.install_directory_snapshot(
12093                        entries.take().unwrap_or_default(),
12094                        mark,
12095                        inodes.clone(),
12096                        DirectoryOrder::NameBytes,
12097                    )
12098                })?;
12099                self.serve_next_batch(guest, call).await
12100            }
12101            Ok(None) => {
12102                guest
12103                    .thread_state()
12104                    .with_detfd(call.fd, |detfd| detfd.use_host_directory_order())?;
12105                self.project_one_buffer(guest, call).await
12106            }
12107            Err(error) => Err(error),
12108        }
12109    }
12110
12111    /// Answer a `getdents` whose count does not fit in an `int`. Linux keeps
12112    /// the count in one, where it is negative, so no entry fits: the call
12113    /// fails with `EINVAL`, or returns 0 at the end of the directory, and
12114    /// moves nothing. It does not look at the buffer, so a count of 0 gets
12115    /// the same answer for any pointer, and the same `EBADF`, `ENOTDIR` or
12116    /// `ENOENT`; that is the call issued, since a backend that does not
12117    /// truncate the guest's count to an `int` would copy host records into
12118    /// the guest's buffer.
12119    ///
12120    /// `stream` is the directory stream's position and whether it needs a
12121    /// snapshot, or `None` when the open file has no stream (it has not been
12122    /// read, is read in host order, or is not tracked). Then the guest's
12123    /// position is the kernel's, so the kernel's answer is Linux's. So it is
12124    /// for a stream rewound to 0, whose kernel position is the start. A
12125    /// stream that has a snapshot decides between `EINVAL` and 0 itself. The
12126    /// kernel position of a stream without a snapshot is moved to the start
12127    /// first, and then to where the snapshot, if made, puts it. A descriptor
12128    /// Detcore does not track that shares the open file, and had moved that
12129    /// position, reads on from there, where on Linux the call moves nothing. A
12130    /// stream rewound and then seeked past 0 needs to know how many entries
12131    /// the directory has, so a snapshot is taken (see
12132    /// [`Self::snapshot_directory_privately`]). If the directory must be
12133    /// read in host order instead, the kernel's answer from the start is
12134    /// returned, which is `EINVAL` even at or past the end; if no mapping can
12135    /// be made for the snapshot, the call fails with `ENOMEM`
12136    /// (https://github.com/rrnewton/hermit/issues/3723).
12137    async fn serve_negative_count<G: Guest<Self>>(
12138        &self,
12139        guest: &mut G,
12140        call: GetdentsCall<'_>,
12141        stream: Option<(u64, bool)>,
12142    ) -> Result<i64, Error> {
12143        if let Some((_, true)) = stream {
12144            // Without a snapshot, the kernel position of a stream is the
12145            // start; a descriptor Detcore does not track may have moved it.
12146            self.move_directory_kernel_position(guest, call.fd, 0).await;
12147        }
12148        let kernel = self.record_or_replay(guest, call.empty).await;
12149        match kernel {
12150            Ok(_) | Err(Errno::EINVAL) => {}
12151            Err(errno) => return Err(errno.into()),
12152        }
12153        match stream {
12154            None | Some((0, true)) => return Ok(kernel.map(|_| 0)?),
12155            Some((_, true)) => {
12156                let mark = directory_snapshot_mark(guest).await;
12157                let modeled = self.modeled_directory_snapshot(guest, call).await?;
12158                let (snapshot, inodes, order) = match modeled {
12159                    Some((entries, inodes, order)) => (Ok(Some(entries)), inodes, order),
12160                    None => {
12161                        let inodes = self.directory_inodes(guest, call.fd).await?;
12162                        (
12163                            self.snapshot_directory_privately(guest, call).await,
12164                            inodes,
12165                            DirectoryOrder::NameBytes,
12166                        )
12167                    }
12168                };
12169                match snapshot {
12170                    Ok(Some(entries)) => {
12171                        let mut entries = Some(entries);
12172                        let target = guest.thread_state().with_detfd(call.fd, |detfd| {
12173                            detfd.install_directory_snapshot(
12174                                entries.take().unwrap_or_default(),
12175                                mark,
12176                                inodes.clone(),
12177                                order,
12178                            );
12179                            detfd.with_directory_stream(|stream| stream.kernel_target())
12180                        })??;
12181                        self.move_directory_kernel_position(guest, call.fd, target)
12182                            .await;
12183                    }
12184                    Ok(None) => return Ok(kernel.map(|_| 0)?),
12185                    Err(error) => return Err(error),
12186                }
12187            }
12188            Some((_, false)) => {}
12189        }
12190        let batch = guest.thread_state().with_detfd(call.fd, |detfd| {
12191            detfd.with_directory_stream(|stream| stream.next_batch(call.format, 0))
12192        })??;
12193        batch?;
12194        Ok(0)
12195    }
12196
12197    /// Return the entries at the stream's position that fit in the guest's
12198    /// buffer, with determinized inodes, keyed as decided when the snapshot
12199    /// was taken, and each `d_off` naming the position after its entry,
12200    /// counting from 1.
12201    ///
12202    /// Whatever the outcome, the kernel position then follows the stream (see
12203    /// [`DirectoryStream::kernel_target`]).
12204    async fn serve_next_batch<G: Guest<Self>>(
12205        &self,
12206        guest: &mut G,
12207        call: GetdentsCall<'_>,
12208    ) -> Result<i64, Error> {
12209        let (start, batch, mark, inodes) =
12210            guest.thread_state().with_detfd(call.fd, |detfd| {
12211                detfd.with_directory_stream(|stream| {
12212                    (
12213                        stream.position(),
12214                        stream.next_batch(call.format, call.capacity),
12215                        stream.snapshot_mark(),
12216                        stream.snapshot_inodes(),
12217                    )
12218                })
12219            })??;
12220        let (passed, copied) = match batch {
12221            Ok(batch) => {
12222                // Every snapshot is installed with its keys; a stream without
12223                // them is keyed now.
12224                let inodes = match inodes {
12225                    Some(inodes) => inodes,
12226                    None => self.directory_inodes(guest, call.fd).await?,
12227                };
12228                let mut records = Vec::new();
12229                let mut names = Vec::with_capacity(batch.len());
12230                for (index, entry) in batch.iter().enumerate() {
12231                    let (host, path) = inodes.entry_inode(&entry.name, entry.ino);
12232                    let files = self.rendered_files(guest);
12233                    let d_ino = match self
12234                        .rendered_listed_inode(guest, &inodes, &entry.name, entry.ino, files)
12235                        .await?
12236                    {
12237                        Some(inode) => DetInode::mint(inode),
12238                        None => determinize_listed_inode(guest, host, path, mark).await.0,
12239                    };
12240                    let d_off = i64::try_from(start + index as u64 + 1).unwrap_or(i64::MAX);
12241                    call.format
12242                        .encode(entry, d_ino.as_raw(), d_off, &mut records);
12243                    names.push(entry.name.len());
12244                }
12245                copy_records(
12246                    &mut guest.memory(),
12247                    call.buf,
12248                    call.format,
12249                    &records,
12250                    &names,
12251                    start,
12252                )
12253            }
12254            Err(errno) => (0, Err(errno)),
12255        };
12256        // With --no-sequentialize-threads another thread can close the
12257        // descriptor during the copy; like Linux, the call's result stands.
12258        let target = guest.thread_state().with_detfd(call.fd, |detfd| {
12259            detfd.with_directory_stream(|stream| {
12260                stream.advance(passed);
12261                stream.kernel_target()
12262            })
12263        });
12264        if let Ok(Ok(target)) = target {
12265            self.move_directory_kernel_position(guest, call.fd, target)
12266                .await;
12267        }
12268        Ok(copied.map(|len| len as i64)?)
12269    }
12270
12271    /// The entries of the `/proc` directory open as `fd`, and how to key their
12272    /// inode numbers, if Detcore lists it from its own model (see
12273    /// [`crate::procfs::listing`]): the root, the level table's other
12274    /// directories, a process's or a thread's directory, or a process's
12275    /// `task`, with processes and threads as the guest numbers them, so that
12276    /// every backend lists the same.
12277    ///
12278    /// The directory is the one the descriptor was opened on: where guest
12279    /// thread IDs name host tasks (ptrace), the kernel's canonical name for
12280    /// it (`procfs_entry`), which bound `self` and `thread-self` to the
12281    /// opener, so an inherited or passed descriptor keeps listing the
12282    /// opener's; on a backend that serves its own `/proc` (KVM), the guest's
12283    /// spelling, and only a directory with no process in its path (the root
12284    /// and the table's system directories), as its process directories cannot
12285    /// be opened yet (slice B3a-4).
12286    ///
12287    /// Each entry is looked up by its spelling below the directory, as the
12288    /// guest's own `lstat` of it would be: on the kernel's procfs an entry the
12289    /// lookup does not find (a name the level lists but this kernel lacks,
12290    /// such as `children` without `CONFIG_PROC_CHILDREN`) is left out, unless
12291    /// Detcore renders it; on a backend's own /proc (KVM), whose lookups
12292    /// follow its executor's process table at host-timed moments, a lookup
12293    /// decides no entry. One the lookup finds is
12294    /// numbered by the inode it reports, which a stat of it pools under too
12295    /// (with the entry's name and its task's incarnation), so the two agree. A
12296    /// file Detcore renders is numbered by its rendered inode
12297    /// ([`Self::serve_next_batch`]), and an entry the backend refuses to look
12298    /// up (KVM) by its path's key.
12299    ///
12300    /// The kernel's directory is still read once, as for any other directory
12301    /// ([`Self::snapshot_directory_privately`]), for its `d_off` cookies: each
12302    /// entry carries the cookie of the host entry of its name, so that the
12303    /// stream leaves the kernel position where a descriptor Detcore does not
12304    /// track reads on from (at the end, the kernel's own end). A descriptor
12305    /// whose position the guest moved before its first read is then read in
12306    /// host order, as any other is.
12307    ///
12308    /// `None`, so that the kernel's listing is served as before: for any other
12309    /// directory; an `O_PATH` descriptor, which lists nothing (the kernel's
12310    /// `EBADF`); under record and replay, where the replayer's descriptor
12311    /// does not name the recorded directory; in a nested PID namespace, whose
12312    /// numbers are not Detcore's; after a guest `chroot`, where `/proc` need
12313    /// not be procfs; for a descriptor not on the guest's procfs (a user bind
12314    /// over part of it); on the in-guest backends whose kernel numbers
12315    /// processes otherwise than Detcore (DBT,
12316    /// <https://github.com/rrnewton/hermit/issues/4009>), where a listed guest
12317    /// pid would open the kernel's process of that number until `/proc/<pid>`
12318    /// is translated (slice B3a-4); and for a process or thread the scheduler
12319    /// does not list, which the kernel's directory then answers for.
12320    async fn modeled_directory_snapshot<G: Guest<Self>>(
12321        &self,
12322        guest: &mut G,
12323        call: GetdentsCall<'_>,
12324    ) -> Result<Option<(Vec<DirEntry>, DirectoryInodes, DirectoryOrder)>, Error> {
12325        let fd = call.fd;
12326        use std::os::unix::ffi::OsStrExt;
12327
12328        use crate::procfs::listing;
12329        use crate::procfs::listing::ModeledDirectory;
12330        let state = guest.thread_state();
12331        if self.cfg.recordreplay_modes
12332            || state.nested_pid_namespace
12333            || state.changed_root.load(Ordering::SeqCst)
12334        {
12335            return Ok(None);
12336        }
12337        let Ok((spelled, status_flags)) =
12338            state.with_detfd(fd, |detfd| (detfd.path(), detfd.status_flags()))
12339        else {
12340            return Ok(None);
12341        };
12342        // Only a descriptor the guest opened by a spelling of such a
12343        // directory is one, which spares every other directory's listing the
12344        // naming below.
12345        if status_flags & libc::O_PATH != 0 {
12346            return Ok(None);
12347        }
12348        // Where numbers are translated (DBT), the kernel's name for the
12349        // descriptor says which directory it is, whatever spelling opened it
12350        // (`/proc/self/fd/N` of a descriptor of `/proc`).
12351        let kernel_named = || {
12352            std::fs::read_link(format!("/proc/thread-self/fd/{fd}"))
12353                .is_ok_and(|kernel| listing::classify(&kernel, 0, 0).is_some())
12354        };
12355        if spelled
12356            .as_deref()
12357            .and_then(|spelled| listing::classify(spelled, 0, 0))
12358            .is_none()
12359            && !(Self::translates_procfs_numbers(guest)
12360                && guest.config().backend.tool_shares_guest_descriptor_table
12361                && kernel_named())
12362        {
12363            return Ok(None);
12364        }
12365        let state = guest.thread_state();
12366        let tid = state.dettid.as_raw();
12367        let names_tasks =
12368            procfs_inode::guest_tids_name_host_tasks(&self.cfg.backend, state.physical_tid);
12369        let pid = self.own_detpid(guest).as_raw();
12370        let cached = guest
12371            .thread_state()
12372            .with_detfd(fd, |detfd| detfd.stat())
12373            .ok()
12374            .flatten();
12375        let stat = match cached {
12376            Some(stat) => stat,
12377            None => DetStat::from(self.inject_fstat(guest, fd).await?),
12378        };
12379        if stat.mode & libc::S_IFMT != libc::S_IFDIR {
12380            return Ok(None);
12381        }
12382        let backend_procfs =
12383            procfs_inode::is_backend_procfs_device(&self.cfg.backend, stat.dev, stat.blksize);
12384        // Where the kernel numbers processes otherwise than Detcore (DBT),
12385        // the directory is the one the guest's spelling names, which reached
12386        // the kernel's directory of the same process (`procfs_numbers`).
12387        let translates = Self::translates_procfs_numbers(guest)
12388            && rendered_procfs::proc_device() == Some(stat.dev);
12389        let path = if names_tasks && rendered_procfs::proc_device() == Some(stat.dev) {
12390            match Self::procfs_entry(guest, &stat, StatTarget::Descriptor(fd)).await {
12391                ProcfsEntry::At(within) => {
12392                    Path::new("/proc").join(within.strip_prefix("/").unwrap_or(&within))
12393                }
12394                ProcfsEntry::NotProcfs | ProcfsEntry::Unnamed | ProcfsEntry::Unknown => {
12395                    return Ok(None);
12396                }
12397            }
12398        } else if translates {
12399            match Self::guest_procfs_spelling(guest, fd).await {
12400                Some(path) => path,
12401                None => return Ok(None),
12402            }
12403        } else if backend_procfs && let Some(spelled) = spelled {
12404            spelled
12405        } else {
12406            return Ok(None);
12407        };
12408        let Some(directory) = listing::classify(&path, pid, tid) else {
12409            return Ok(None);
12410        };
12411        if backend_procfs && !matches!(directory, ModeledDirectory::System(_)) {
12412            return Ok(None);
12413        }
12414        let process = match directory {
12415            ModeledDirectory::System(_) => None,
12416            ModeledDirectory::Process(process)
12417            | ModeledDirectory::Thread(process, _)
12418            | ModeledDirectory::Tasks(process) => Some(DetPid::from_raw(process)),
12419        };
12420        let facts = crate::tool_global::procfs_listing(guest, process).await;
12421        let listed = match directory {
12422            ModeledDirectory::System(_) => true,
12423            // The namespace's init is Hermit's own process unless a guest
12424            // holds pid 1; its threads are the kernel's to list.
12425            ModeledDirectory::Process(process) => {
12426                process == 1 || facts.processes.contains(&process)
12427            }
12428            ModeledDirectory::Thread(_, thread) => facts.threads.contains(&thread),
12429            ModeledDirectory::Tasks(_) => !facts.threads.is_empty(),
12430        };
12431        if !listed {
12432            return Ok(None);
12433        }
12434        let Some(names) = listing::entries(&directory, self.cfg.proc_level, &facts) else {
12435            return Ok(None);
12436        };
12437        // The host's cookies, where the kernel lists the directory. A
12438        // backend's own /proc (KVM) lists nothing of it and may not answer
12439        // the guest's form of the call (legacy `getdents`), so there only a
12440        // position the guest moved before its first read is the kernel's to
12441        // keep, as for any other directory.
12442        let host = if backend_procfs {
12443            let known = guest
12444                .thread_state()
12445                .with_detfd(fd, |detfd| detfd.has_directory_stream())?;
12446            let position = syscalls::Lseek::new()
12447                .with_fd(fd)
12448                .with_offset(0)
12449                .with_whence(Whence::SEEK_CUR);
12450            if !known && self.record_or_replay(guest, position).await != Ok(0) {
12451                return Ok(None);
12452            }
12453            Vec::new()
12454        } else {
12455            let Some(host) = self.snapshot_directory_privately(guest, call).await? else {
12456                return Ok(None);
12457            };
12458            host
12459        };
12460        // A process or thread number the kernel lists is the kernel's (DBT):
12461        // its cookie is the cookie of the guest's number for it.
12462        let host_numbers = if translates {
12463            let held = host
12464                .iter()
12465                .filter(|entry| {
12466                    crate::procfs::ids::names_an_id(&path, std::ffi::OsStr::from_bytes(&entry.name))
12467                })
12468                .filter_map(|entry| std::str::from_utf8(&entry.name).ok()?.parse::<i32>().ok())
12469                .collect::<Vec<_>>();
12470            Self::guest_procfs_numbers(guest, &held)
12471                .await
12472                .unwrap_or_default()
12473        } else {
12474            BTreeMap::new()
12475        };
12476        // A kernel number that is no guest's has no cookie to give: its name
12477        // may be another guest number's.
12478        let host_cookies: std::collections::HashMap<Vec<u8>, i64> = host
12479            .iter()
12480            .filter_map(|entry| {
12481                if !translates
12482                    || !crate::procfs::ids::names_an_id(
12483                        &path,
12484                        std::ffi::OsStr::from_bytes(&entry.name),
12485                    )
12486                {
12487                    return Some((entry.name.clone(), entry.off));
12488                }
12489                let kernel = std::str::from_utf8(&entry.name).ok()?.parse::<i32>().ok()?;
12490                let guest = host_numbers.get(&kernel)?;
12491                Some((guest.to_string().into_bytes(), entry.off))
12492            })
12493            .collect();
12494        let host_cookie = |name: &[u8]| host_cookies.get(name).copied().unwrap_or(0);
12495        let session_files = self.rendered_files(guest);
12496        let host_end = host.last().map_or(0, |entry| entry.off);
12497        // Looked up from the guest's own descriptor where it names the
12498        // kernel's directory, and by the guest's spelling on KVM, whose own
12499        // /proc looks up only absolute paths, and on DBT, whose lookup
12500        // translates the guest's numbers to the kernel's as the guest's own
12501        // lookup of each would be (`inject_statat`, `procfs_numbers`).
12502        let (lookup_dir, spellings): (RawFd, Vec<PathBuf>) = if backend_procfs || translates {
12503            let spellings = names
12504                .iter()
12505                .map(|(name, _)| path.join(std::ffi::OsStr::from_bytes(name)))
12506                .collect();
12507            (libc::AT_FDCWD, spellings)
12508        } else {
12509            let spellings = names
12510                .iter()
12511                .map(|(name, _)| PathBuf::from(std::ffi::OsStr::from_bytes(name)))
12512                .collect();
12513            (fd, spellings)
12514        };
12515        let looked_up = self.looked_up_inodes(guest, lookup_dir, &spellings).await?;
12516        let within = listing::within(&directory);
12517        let entries = names
12518            .into_iter()
12519            .zip(looked_up)
12520            .filter_map(|((name, ty), looked_up)| {
12521                let entry = match name.as_slice() {
12522                    b"." => within.clone(),
12523                    b".." => within.parent().unwrap_or(&within).to_path_buf(),
12524                    name => within.join(std::ffi::OsStr::from_bytes(name)),
12525                };
12526                // A file Detcore renders exists whatever the kernel has.
12527                let rendered = crate::procfs::ProcfsFile::from_path(
12528                    &Path::new("/proc").join(entry.strip_prefix("/").unwrap_or(&entry)),
12529                )
12530                .is_some_and(|file| file.rendered_path(session_files).is_some());
12531                // On a backend's own /proc (KVM), what a lookup finds is the
12532                // backend's, at a moment the host decides (a process's
12533                // directory goes when its executor learns of the exit), so
12534                // there it numbers an entry but decides none.
12535                let ino = match looked_up {
12536                    Ok(ino) => ino,
12537                    Err(Errno::ENOENT)
12538                        if name != b"." && name != b".." && !rendered && !backend_procfs =>
12539                    {
12540                        return None;
12541                    }
12542                    Err(_) => procfs_inode::path_inode(stat.dev, &entry).ino,
12543                };
12544                Some(DirEntry {
12545                    ino,
12546                    off: host_cookie(&name),
12547                    ty,
12548                    name,
12549                })
12550            })
12551            .collect::<Vec<_>>();
12552        // In host order, which `DirectoryStream::install` takes them in, and
12553        // ending where the host's listing ends, so the stream's end is the
12554        // kernel's.
12555        let mut entries = entries;
12556        entries.sort_by_key(|entry| entry.off);
12557        if let Some(last) = entries.last_mut() {
12558            last.off = last.off.max(host_end);
12559        }
12560        let inodes = DirectoryInodes::new(stat.dev, Some(ProcfsDirectory::new(within)));
12561        let order = match &directory {
12562            ModeledDirectory::System(names) if names.is_empty() => DirectoryOrder::ProcfsIds,
12563            ModeledDirectory::Tasks(_) => DirectoryOrder::ProcfsIds,
12564            _ => DirectoryOrder::NameBytes,
12565        };
12566        Ok(Some((entries, inodes, order)))
12567    }
12568
12569    /// The inode number a lookup of each of `paths` from the directory open as
12570    /// `dir` (or absolute, with `AT_FDCWD`), without following a final link,
12571    /// gives in the guest, as the guest's own `fstatat` of it would, or the
12572    /// lookup's error. The paths are staged in an
12573    /// anonymous mapping injected for the purpose and unmapped before the guest
12574    /// runs again, as a directory snapshot's reads are (see
12575    /// [`Self::snapshot_directory_privately`]); without one, every lookup is
12576    /// `ENOMEM`. A mapping that cannot be unmapped would be visible to the
12577    /// guest, so that is an error.
12578    async fn looked_up_inodes<G: Guest<Self>>(
12579        &self,
12580        guest: &mut G,
12581        dir: RawFd,
12582        paths: &[PathBuf],
12583    ) -> Result<Vec<Result<u64, Errno>>, Error> {
12584        use std::os::unix::ffi::OsStrExt;
12585
12586        let mapped = guest
12587            .inject_with_retry(Syscall::Mmap(
12588                syscalls::Mmap::new()
12589                    .with_addr(None)
12590                    .with_len(DIRECTORY_PAGE)
12591                    .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
12592                    .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
12593                    .with_fd(-1)
12594                    .with_offset(0),
12595            ))
12596            .await;
12597        let Some(page) = mapped
12598            .ok()
12599            .and_then(|addr| usize::try_from(addr).ok())
12600            .and_then(AddrMut::<u8>::from_raw)
12601        else {
12602            return Ok(vec![Err(Errno::ENOMEM); paths.len()]);
12603        };
12604        let mut inodes = Vec::with_capacity(paths.len());
12605        for path in paths {
12606            let mut bytes = path.as_os_str().as_bytes().to_vec();
12607            bytes.push(0);
12608            let staged =
12609                bytes.len() <= DIRECTORY_PAGE && guest.memory().write_exact(page, &bytes).is_ok();
12610            let staged_path = PathPtr::from_ptr(page.as_raw() as *const libc::c_char);
12611            let inode = match (staged, staged_path) {
12612                (true, Some(staged_path)) => Self::inject_statat(
12613                    guest,
12614                    dir,
12615                    staged_path,
12616                    [Some(staged_path), None],
12617                    AtFlags::AT_SYMLINK_NOFOLLOW,
12618                )
12619                .await
12620                .map(|stat| stat.st_ino),
12621                _ => Err(Errno::ENAMETOOLONG),
12622            };
12623            inodes.push(inode);
12624        }
12625        guest
12626            .inject_with_retry(Syscall::Munmap(
12627                syscalls::Munmap::new()
12628                    .with_addr(Some(Addr::from(page).cast()))
12629                    .with_len(DIRECTORY_PAGE),
12630            ))
12631            .await?;
12632        Ok(inodes)
12633    }
12634
12635    /// How to key the inode numbers of the entries of the directory open as
12636    /// `fd`. Every entry is on the directory's host device (a mount point's
12637    /// entry names the directory beneath the mount, on the same device), and
12638    /// a procfs directory's entries also name their paths beneath its
12639    /// canonical path (see [`procfs_inode`]). The directory's stat is the
12640    /// cached one when Detcore tracks `fd`, and an injected `fstat` otherwise.
12641    async fn directory_inodes<G: Guest<Self>>(
12642        &self,
12643        guest: &mut G,
12644        fd: RawFd,
12645    ) -> Result<DirectoryInodes, Errno> {
12646        let cached = guest
12647            .thread_state()
12648            .with_detfd(fd, |detfd| detfd.stat())
12649            .ok()
12650            .flatten();
12651        let stat = match cached {
12652            Some(stat) => stat,
12653            None => DetStat::from(self.inject_fstat(guest, fd).await?),
12654        };
12655        let procfs = match Self::procfs_entry(guest, &stat, StatTarget::Descriptor(fd)).await {
12656            ProcfsEntry::At(within) => Some(ProcfsDirectory::new(within)),
12657            ProcfsEntry::NotProcfs | ProcfsEntry::Unnamed | ProcfsEntry::Unknown => None,
12658        };
12659        Ok(DirectoryInodes::new(stat.dev, procfs))
12660    }
12661
12662    /// Move the kernel position of the open file behind `fd` to `target`, a
12663    /// [`DirectoryStream::kernel_target`], so that a descriptor Detcore does
12664    /// not track that aliases it reads every entry the stream has not
12665    /// returned. Without this, the snapshot leaves the kernel at the end of
12666    /// the directory, and such a descriptor would read nothing.
12667    ///
12668    /// The guest's own call has already been decided, so a failed seek is not
12669    /// reported to it; the next move of the stream seeks again.
12670    async fn move_directory_kernel_position<G: Guest<Self>>(
12671        &self,
12672        guest: &mut G,
12673        fd: RawFd,
12674        target: i64,
12675    ) {
12676        let seek = syscalls::Lseek::new()
12677            .with_fd(fd)
12678            .with_offset(target)
12679            .with_whence(Whence::SEEK_SET);
12680        let _ = self.record_or_replay(guest, seek).await;
12681    }
12682
12683    /// Drop from `entries`, read from the directory open as `fd`, the CPUs and
12684    /// nodes that Hermit's single virtual CPU and node leave out (see
12685    /// [`is_absent_cpu_entry`]), so that a guest counting
12686    /// `/sys/devices/system/cpu/cpuN` finds one CPU, as `online` and
12687    /// `sched_getaffinity` report
12688    /// (<https://github.com/rrnewton/hermit/issues/4160>); and the `/proc`
12689    /// names outside the run's `--proc` level, which lookups refuse (see
12690    /// [`levels::absent_entry`]).
12691    ///
12692    /// The directory is named by the kernel's path for the descriptor, so a
12693    /// relative or symlinked spelling is recognized too. Not under record and
12694    /// replay, where the replayer's descriptor does not name the recorded
12695    /// directory, so the two runs would not drop alike; Detcore names no
12696    /// procfs entry there either (see [`Self::procfs_entry`]).
12697    fn drop_absent_entries<G: Guest<Self>>(
12698        &self,
12699        guest: &G,
12700        fd: RawFd,
12701        entries: &mut Vec<DirEntry>,
12702    ) {
12703        if self.cfg.recordreplay_modes {
12704            return;
12705        }
12706        let link = format!("{}/fd/{fd}", self.caller_proc_directory(guest));
12707        // Names are dropped as outside the level only from a directory the
12708        // tool sees is on procfs: not from a user bind over part of `/proc`,
12709        // and not where the tool cannot tell (its `/proc` entry for the
12710        // caller is not the caller's where the guest's threads are no host
12711        // tasks, KVM, or is unreadable after a `chroot`).
12712        let tool_sees_caller =
12713            crate::procfs_inode::tool_can_name_guest_descriptors(&self.cfg.backend);
12714        let directory_metadata = tool_sees_caller
12715            .then(|| std::fs::metadata(&link).ok())
12716            .flatten();
12717        let on_procfs = match (&directory_metadata, rendered_procfs::proc_device()) {
12718            (Some(metadata), Some(device)) => metadata.dev() == device,
12719            _ => false,
12720        };
12721        if self.is_caller_descriptor_table(guest, fd) {
12722            entries.retain(|entry| {
12723                !runtime_owned_descriptor_entry(&entry.name, |fd| guest.is_runtime_owned_fd(fd))
12724            });
12725        }
12726        // The kernel's path for the descriptor; or, where the tool cannot
12727        // read it (after a `chroot` into a root without `/proc`, where the
12728        // tool runs inside the guest), the path the guest opened it by.
12729        let directory = std::fs::read_link(&link)
12730            .ok()
12731            .or_else(|| {
12732                guest
12733                    .thread_state()
12734                    .with_detfd(fd, |detfd| detfd.path())
12735                    .ok()
12736                    .flatten()
12737            })
12738            .filter(|path| path.is_absolute());
12739        // After a `chroot` into another root, the kernel names the directory
12740        // in the tool's view, below that root.
12741        let directory = match (directory, self.guest_root_in_view(guest)) {
12742            (Some(directory), Some(Some(root))) if !directory.starts_with("/proc") => directory
12743                .strip_prefix(&root)
12744                .ok()
12745                .map(|below| Path::new("/").join(below))
12746                .or(Some(directory)),
12747            (directory, _) => directory,
12748        };
12749        if let Some(directory) = directory {
12750            let level = self.cfg.proc_level;
12751            entries.retain(|entry| {
12752                !is_absent_cpu_entry(&directory, &entry.name)
12753                    && !(on_procfs && levels::absent_entry(&directory, &entry.name, level))
12754            });
12755        }
12756    }
12757
12758    /// Whether the opened procfs object names the caller's own descriptor
12759    /// table. Authenticate kernel object identity, not the guest spelling:
12760    /// an inherited directory may belong to a different process. Process and
12761    /// thread aliases have distinct inodes; the process alias requires the
12762    /// existing shared-table proof. Independent of metadata virtualization.
12763    fn is_caller_descriptor_table<G: Guest<Self>>(&self, guest: &G, fd: RawFd) -> bool {
12764        if self.cfg.recordreplay_modes
12765            || !crate::procfs_inode::tool_can_name_guest_descriptors(&self.cfg.backend)
12766        {
12767            return false;
12768        }
12769        let link = format!("{}/fd/{fd}", self.caller_proc_directory(guest));
12770        let directory_metadata = std::fs::metadata(link).ok();
12771        let on_procfs = match (&directory_metadata, rendered_procfs::proc_device()) {
12772            (Some(metadata), Some(device)) => metadata.dev() == device,
12773            _ => false,
12774        };
12775        let state = guest.thread_state();
12776        let holds_process_table =
12777            state.dettid == self.own_detpid(guest) || state.holds_process_files();
12778        let process = if self.cfg.backend.tool_shares_guest_descriptor_table {
12779            String::from("/proc/self")
12780        } else {
12781            format!("/proc/{}", guest.pid().as_raw())
12782        };
12783        on_procfs
12784            && directory_metadata.as_ref().is_some_and(|metadata| {
12785                is_caller_descriptor_directory(
12786                    metadata,
12787                    &self.caller_proc_directory(guest),
12788                    holds_process_table.then_some(process.as_str()),
12789                )
12790            })
12791    }
12792
12793    /// Answer `getdents` without a directory stream by issuing the guest's own
12794    /// call. With metadata virtualization, sort that kernel buffer and
12795    /// determinize its inodes. Without it, only omit runtime-owned entries
12796    /// from an authenticated caller descriptor table; keep host order and
12797    /// inodes. The host's `d_off` cookies are kept, so the kernel can
12798    /// still interpret them. A directory larger than one buffer comes back as
12799    /// sorted runs whose boundaries depend on the host.
12800    ///
12801    /// A buffer whose every entry is dropped (see
12802    /// [`Self::drop_absent_entries`]) is not returned empty, which would
12803    /// end the directory: the call is issued again from where the kernel
12804    /// left off. The bytes the kernel wrote past the entries returned, by this
12805    /// call or one it reissued, are zeroed, as they may name the entries
12806    /// dropped; so is a buffer every dropped entry was written to when the
12807    /// directory then ends.
12808    async fn project_one_buffer<G: Guest<Self>>(
12809        &self,
12810        guest: &mut G,
12811        call: GetdentsCall<'_>,
12812    ) -> Result<i64, Error> {
12813        // The longest any call wrote: a reissued call can write less than the
12814        // one before it, whose dropped names lie past it.
12815        let virtualize = guest.config().virtualize_metadata;
12816        let mut written = 0;
12817        let mut dropped = false;
12818        let (len, mut entries) = loop {
12819            let len = match self.record_or_replay(guest, call.call).await {
12820                Ok(len) => len as usize,
12821                Err(error) => {
12822                    if written > 0 {
12823                        guest.memory().write_exact(call.buf, &vec![0; written])?;
12824                    }
12825                    return Err(error.into());
12826                }
12827            };
12828            if len == 0 {
12829                if written > 0 {
12830                    guest.memory().write_exact(call.buf, &vec![0; written])?;
12831                }
12832                return Ok(0);
12833            }
12834            written = written.max(len);
12835            let mut entries = match read_records(&guest.memory(), call.buf, len, call.format) {
12836                Ok(entries) => entries,
12837                Err(error) => {
12838                    guest.memory().write_exact(call.buf, &vec![0; written])?;
12839                    return Err(error.into());
12840                }
12841            };
12842            if virtualize {
12843                self.drop_absent_entries(guest, call.fd, &mut entries);
12844            } else {
12845                let original = entries.len();
12846                entries.retain(|entry| {
12847                    !runtime_owned_descriptor_entry(&entry.name, |fd| guest.is_runtime_owned_fd(fd))
12848                });
12849                if entries.len() == original && !dropped {
12850                    return Ok(len as i64);
12851                }
12852                dropped = true;
12853            }
12854            if !entries.is_empty() {
12855                break (len, entries);
12856            }
12857        };
12858        let inodes = if virtualize {
12859            sort_dir_entries(&mut entries);
12860            Some(self.directory_inodes(guest, call.fd).await?)
12861        } else {
12862            None
12863        };
12864        let mut records = Vec::with_capacity(len);
12865        for entry in &entries {
12866            let Some(inodes) = &inodes else {
12867                call.format
12868                    .encode(entry, entry.ino, entry.off, &mut records);
12869                continue;
12870            };
12871            let (host, path) = inodes.entry_inode(&entry.name, entry.ino);
12872            let files = self.rendered_files(guest);
12873            let d_ino = match self
12874                .rendered_listed_inode(guest, inodes, &entry.name, entry.ino, files)
12875                .await?
12876            {
12877                Some(inode) => DetInode::mint(inode),
12878                None => determinize_named_inode(guest, host, path).await.0,
12879            };
12880            call.format
12881                .encode(entry, d_ino.as_raw(), entry.off, &mut records);
12882        }
12883        let returned = records.len();
12884        // Zero what the kernel wrote past the entries returned.
12885        records.resize(returned.max(written), 0);
12886        if guest.memory().write_exact(call.buf, &records).is_err() {
12887            // The padding after the last name may not be writable, as Linux
12888            // does not write it.
12889            let written = entries.last().map_or(0, |last| {
12890                returned - call.format.record_len(last.name.len())
12891                    + call.format.written_len(last.name.len())
12892            });
12893            guest.memory().write_exact(call.buf, &records[..written])?;
12894        }
12895        Ok(returned as i64)
12896    }
12897
12898    /// Read the whole host directory behind `call.fd` into a private mapping
12899    /// (see [`Self::snapshot_directory`]), and return its entries in host
12900    /// order, less the CPUs and nodes Hermit's single virtual CPU and node
12901    /// leave out and the `/proc` names outside the run's level (see
12902    /// [`Self::drop_absent_entries`]). Every directory
12903    /// snapshot a stream stores comes from here, so none holds them.
12904    ///
12905    /// Linux writes into guest memory only the records a call returns and the
12906    /// fields it stored of one it could not finish, so the reads do not go to
12907    /// the guest's buffer, which may be too small
12908    /// for any entry, unreadable, or partly unmapped, nor to its stack. They
12909    /// go to an anonymous mapping injected for the purpose and unmapped
12910    /// before the guest runs again, as the atomic `writev` does for its
12911    /// iovecs. The mapping is fresh, so the reads leave nothing that the
12912    /// guest could see in memory. On the kvm backend, whose guest allocator
12913    /// fills the lowest hole below a cursor first and moves the cursor past
12914    /// each mapping it makes, the mapping moves that cursor, so a later
12915    /// mapping that fits no hole below it lands elsewhere than on Linux. That
12916    /// follows from the guest's own calls, so it is the same on every run.
12917    ///
12918    /// If a mapping of [`DIRECTORY_DRAIN_COUNT`] bytes cannot be made, one
12919    /// page is used, which still holds any entry. If that cannot be made
12920    /// either (the guest's address space is at its limit), the call fails
12921    /// with `ENOMEM` before anything is read, and the stream stays without a
12922    /// snapshot, so a later call tries again. Linux's `getdents` does not
12923    /// fail so; serving the directory in host order would make the order
12924    /// depend on the host. This divergence is tracked in
12925    /// https://github.com/rrnewton/hermit/issues/3723.
12926    async fn snapshot_directory_privately<G: Guest<Self>>(
12927        &self,
12928        guest: &mut G,
12929        call: GetdentsCall<'_>,
12930    ) -> Result<Option<Vec<DirEntry>>, Error> {
12931        let mut mapping = None;
12932        for len in [DIRECTORY_DRAIN_COUNT as usize, DIRECTORY_PAGE] {
12933            let mapped = guest
12934                .inject_with_retry(Syscall::Mmap(
12935                    syscalls::Mmap::new()
12936                        .with_addr(None)
12937                        .with_len(len)
12938                        .with_prot(ProtFlags::PROT_READ | ProtFlags::PROT_WRITE)
12939                        .with_flags(MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS)
12940                        .with_fd(-1)
12941                        .with_offset(0),
12942                ))
12943                .await;
12944            if let Some(scratch) = mapped
12945                .ok()
12946                .and_then(|addr| usize::try_from(addr).ok())
12947                .and_then(AddrMut::<u8>::from_raw)
12948            {
12949                mapping = Some((scratch, len));
12950                break;
12951            }
12952        }
12953        let Some((scratch, len)) = mapping else {
12954            return Err(Errno::ENOMEM.into());
12955        };
12956        let snapshot = self
12957            .snapshot_directory(guest, call.into_scratch(scratch, len as u32))
12958            .await;
12959        let unmapped = guest
12960            .inject_with_retry(Syscall::Munmap(
12961                syscalls::Munmap::new()
12962                    .with_addr(Some(Addr::from(scratch).cast()))
12963                    .with_len(len),
12964            ))
12965            .await;
12966        // A mapping left behind would be visible to the guest.
12967        unmapped?;
12968        let mut snapshot = snapshot?;
12969        if let Some(entries) = &mut snapshot {
12970            self.drop_absent_entries(guest, call.fd, entries);
12971        }
12972        Ok(snapshot)
12973    }
12974
12975    /// Read the whole host directory by issuing `call.call` until it returns
12976    /// 0, and return its entries in host order. `call` reads into a private
12977    /// mapping that holds any entry.
12978    ///
12979    /// Every step goes through `record_or_replay`, so a replay reads the same
12980    /// entries from the log. The reads must start at the beginning of the
12981    /// directory: a known directory is rewound there, and before the first
12982    /// snapshot the kernel position must already be 0.
12983    ///
12984    /// The first read fails as the guest's call would at any position: the
12985    /// descriptor is not a directory, or the directory has been removed.
12986    ///
12987    /// Returns `None` when this open file must be read in host order instead,
12988    /// with the kernel position where the guest left it. Either the position
12989    /// was moved before the first `getdents`, to a host cookie that no entry
12990    /// index stands for, or a read after the first failed, so the directory
12991    /// cannot be read to its end. A regular file, pipe or `O_PATH` descriptor
12992    /// whose position is not 0 also lands here, and reading it in host order
12993    /// reports the kernel's error without moving its offset.
12994    async fn snapshot_directory<G: Guest<Self>>(
12995        &self,
12996        guest: &mut G,
12997        call: GetdentsCall<'_>,
12998    ) -> Result<Option<Vec<DirEntry>>, Error> {
12999        let known_directory = guest
13000            .thread_state()
13001            .with_detfd(call.fd, |detfd| detfd.has_directory_stream())?;
13002        let lseek = |offset, whence| {
13003            syscalls::Lseek::new()
13004                .with_fd(call.fd)
13005                .with_offset(offset)
13006                .with_whence(whence)
13007        };
13008        if known_directory {
13009            self.record_or_replay(guest, lseek(0, Whence::SEEK_SET))
13010                .await?;
13011        } else if self
13012            .record_or_replay(guest, lseek(0, Whence::SEEK_CUR))
13013            .await
13014            != Ok(0)
13015        {
13016            return Ok(None);
13017        }
13018
13019        let mut entries = Vec::new();
13020        let mut read_any = false;
13021        let error: Error = loop {
13022            let len = match self.record_or_replay(guest, call.call).await {
13023                Ok(0) => return Ok(Some(entries)),
13024                Ok(len) => len as usize,
13025                Err(error) => break error.into(),
13026            };
13027            read_any = true;
13028            match read_records(&guest.memory(), call.buf, len, call.format) {
13029                Ok(parsed) => entries.extend(parsed),
13030                Err(error) => break error.into(),
13031            }
13032        };
13033        if !read_any {
13034            return Err(error);
13035        }
13036        // The earlier reads moved the position, which the guest's call must
13037        // find where the guest left it: at the start.
13038        self.record_or_replay(guest, lseek(0, Whence::SEEK_SET))
13039            .await?;
13040        Ok(None)
13041    }
13042}
13043
13044/// The size of the private mapping that a snapshot reads the host directory
13045/// into, and so the most bytes one read of it asks for. It holds any entry.
13046const DIRECTORY_DRAIN_COUNT: u32 = 64 * 1024;
13047
13048/// The granularity at which the guest's buffer can stop being writable.
13049const DIRECTORY_PAGE: usize = 4096;
13050
13051/// The most pages one vectored copy names: Linux's `IOV_MAX`.
13052const PAGES_PER_COPY: usize = 1024;
13053
13054/// The pieces of the `len` bytes at guest address `addr`, split where they
13055/// cross a page: the offset and length of each.
13056fn guest_pages(addr: usize, len: usize) -> Vec<(usize, usize)> {
13057    let mut pieces = Vec::with_capacity(len / DIRECTORY_PAGE + 2);
13058    let mut at = 0;
13059    while at < len {
13060        let piece = (DIRECTORY_PAGE - (addr + at) % DIRECTORY_PAGE).min(len - at);
13061        pieces.push((at, piece));
13062        at += piece;
13063    }
13064    pieces
13065}
13066
13067/// Read and decode the `len` bytes of records a `getdents` returned in the
13068/// guest's buffer. Linux does not write the padding after the last record's
13069/// name, which can lie in a page the guest cannot read.
13070fn read_records(
13071    memory: &impl MemoryAccess,
13072    buf: AddrMut<u8>,
13073    len: usize,
13074    format: DirentFormat,
13075) -> Result<Vec<DirEntry>, Errno> {
13076    let mut bytes = vec![0; len];
13077    let readable = match memory.read_exact(buf, &mut bytes) {
13078        Ok(()) => len,
13079        Err(_) => read_guest_prefix(memory, buf, &mut bytes)?,
13080    };
13081    format.parse_written(&mut bytes, readable)
13082}
13083
13084/// Read the start of the guest's buffer into `bytes`, up to the first page the
13085/// guest cannot read, and return how many bytes were read. Only a fault
13086/// (`EFAULT`) ends the copy short; any other error of the copy, such as
13087/// `ESRCH` for a thread that is gone or `EIO` from the backend, is returned.
13088///
13089/// This and [`write_guest_pieces`] use only vectored copies, one page per
13090/// piece, which respect the guest's page protection. Reverie's `read` and
13091/// `write` do not always: on the ptrace backend, a copy of at most 8 bytes goes
13092/// through `PTRACE_PEEKDATA` or `PTRACE_POKEDATA`, which reach a page the guest
13093/// has made inaccessible.
13094pub(crate) fn read_guest_prefix(
13095    memory: &impl MemoryAccess,
13096    buf: AddrMut<u8>,
13097    bytes: &mut [u8],
13098) -> Result<usize, Errno> {
13099    let mut done = 0;
13100    for pages in guest_pages(buf.as_raw(), bytes.len()).chunks(PAGES_PER_COPY) {
13101        let from = pages[0].0;
13102        let len: usize = pages.iter().map(|&(_, len)| len).sum();
13103        let remote: Vec<AddrSlice<u8>> = pages
13104            .iter()
13105            .map(|&(at, len)| unsafe { AddrSlice::from_raw_parts(buf.add(at).into(), len) })
13106            .collect();
13107        let remote: Vec<std::io::IoSlice> = remote
13108            .iter()
13109            .map(|piece| unsafe { piece.as_ioslice() })
13110            .collect();
13111        let mut local = [std::io::IoSliceMut::new(&mut bytes[from..from + len])];
13112        let copied = match memory.read_vectored(&remote, &mut local) {
13113            Err(Errno::EFAULT) => 0,
13114            copied => copied?,
13115        };
13116        done += copied;
13117        if copied < len {
13118            break;
13119        }
13120    }
13121    Ok(done)
13122}
13123
13124/// Write each of `pieces`, an offset in the guest's buffer and the bytes to
13125/// store there, within one page, in the order given, up to the first the
13126/// guest cannot write. Return how many bytes of the pieces were written,
13127/// counted in that order. As in [`read_guest_prefix`], only a fault ends the
13128/// copy short, and any other error is returned.
13129fn write_guest_pieces(
13130    memory: &mut impl MemoryAccess,
13131    buf: AddrMut<u8>,
13132    pieces: &[(usize, &[u8])],
13133) -> Result<usize, Errno> {
13134    let mut done = 0;
13135    for pieces in pieces.chunks(PAGES_PER_COPY) {
13136        let len: usize = pieces.iter().map(|(_, bytes)| bytes.len()).sum();
13137        let mut remote: Vec<AddrSliceMut<u8>> = pieces
13138            .iter()
13139            .map(|&(at, bytes)| unsafe { AddrSliceMut::from_raw_parts(buf.add(at), bytes.len()) })
13140            .collect();
13141        let mut remote: Vec<std::io::IoSliceMut> = remote
13142            .iter_mut()
13143            .map(|piece| unsafe { piece.as_ioslice_mut() })
13144            .collect();
13145        let local: Vec<std::io::IoSlice> = pieces
13146            .iter()
13147            .map(|&(_, bytes)| std::io::IoSlice::new(bytes))
13148            .collect();
13149        let copied = match memory.write_vectored(&local, &mut remote) {
13150            Err(Errno::EFAULT) => 0,
13151            copied => copied?,
13152        };
13153        done += copied;
13154        if copied < len {
13155            break;
13156        }
13157    }
13158    Ok(done)
13159}
13160
13161/// One store that Linux makes into the guest's buffer to copy directory
13162/// records: where in the buffer, the bytes stored (a range of the records,
13163/// or of the first record's placeholder `d_off` after them), and whether the
13164/// CPU makes it as one store, which writes nothing if any byte of it faults.
13165struct DirentStore {
13166    at: usize,
13167    from: std::ops::Range<usize>,
13168    single: bool,
13169}
13170
13171/// The stores Linux makes, in its order, to copy records whose names are
13172/// `names` bytes long, and for each record, how many of the stores precede
13173/// the end of its `filldir`. `placeholder` is where the first record's
13174/// placeholder `d_off` follows the records.
13175///
13176/// For each record, `filldir` (fs/readdir.c) first stores the `d_off` of the
13177/// record before it, which is its own entry's position. The first record of
13178/// a call has none before it, so its own `d_off` gets that position, to be
13179/// overwritten. Then come `d_ino`, `d_reclen`, `d_type`, the NUL after the
13180/// name, and the name. Once no more records are copied, the call stores the
13181/// last one's `d_off`. No padding is written.
13182///
13183/// Linux copies a name in words from its start, after the NUL that follows
13184/// it. A name spans at most two pages, and the NUL's page could be written,
13185/// so if a word of the name faults, the first does, and none of the name is
13186/// written. So it is here, where the name is written page by page.
13187fn dirent_stores(
13188    format: DirentFormat,
13189    names: &[usize],
13190    placeholder: usize,
13191) -> (Vec<DirentStore>, Vec<usize>) {
13192    let field = |at: usize, len: usize| DirentStore {
13193        at,
13194        from: at..at + len,
13195        single: true,
13196    };
13197    let mut stores = Vec::with_capacity(names.len() * 6 + 1);
13198    let mut filled = Vec::with_capacity(names.len());
13199    let mut previous = None;
13200    let mut at = 0;
13201    for &name_len in names {
13202        let reclen = format.record_len(name_len);
13203        let name = at + format.name_offset();
13204        stores.push(match previous {
13205            Some(previous) => field(previous + 8, 8),
13206            None => DirentStore {
13207                at: at + 8,
13208                from: placeholder..placeholder + 8,
13209                single: true,
13210            },
13211        });
13212        stores.push(field(at, 8));
13213        stores.push(field(at + 16, 2));
13214        stores.push(field(at + format.type_offset(reclen), 1));
13215        stores.push(field(name + name_len, 1));
13216        stores.push(DirentStore {
13217            at: name,
13218            from: name..name + name_len,
13219            single: false,
13220        });
13221        filled.push(stores.len());
13222        previous = Some(at);
13223        at += reclen;
13224    }
13225    if let Some(previous) = previous {
13226        stores.push(field(previous + 8, 8));
13227    }
13228    (stores, filled)
13229}
13230
13231/// Copy directory records into the guest's buffer as Linux does: store by
13232/// store (see [`dirent_stores`]), up to the first store the guest cannot
13233/// write. `records` holds the records of entries whose names are `names`
13234/// bytes long, the first at position `start`.
13235///
13236/// Return how many entries the call passes, and its result: the bytes of the
13237/// records whose `filldir` completed. It is `EFAULT` if none did, or if the
13238/// fault hit a `d_off`, which the call's last store would then write again.
13239/// A copy that fails with any error other than a fault passes no entry and
13240/// returns that error, as the call did before directory streams.
13241///
13242/// Each store within one page is written whole or not at all, as Linux's
13243/// are. A single store that crosses into another page, a field of a buffer
13244/// not aligned to 8 bytes, the CPU writes whole or not at all, so its two
13245/// parts are written one after the other and the first is put back if the
13246/// second cannot be written. What is put back is read just before the first
13247/// part is written, after every store before it, which may have changed those
13248/// bytes through another mapping of the same memory. The part written first
13249/// is the one whose bytes Detcore can read to put back: the part in the
13250/// second page, unless only the part in the first page can be read. Where
13251/// neither can be read with a vectored copy, the part in the second page is
13252/// written first, so that a write-only buffer ending at a page the guest
13253/// cannot touch is left as Linux leaves it, and its bytes are read to put
13254/// back with Reverie's `read`, which for at most 8 bytes is `PTRACE_PEEKDATA`
13255/// on the ptrace backend and reads a write-only page. While no other thread
13256/// writes the buffer, only a store from a page the guest can neither read nor
13257/// write into a write-only page that this read cannot reach either leaves
13258/// bytes Linux does not write: up to 7, in the write-only page.
13259fn copy_records(
13260    memory: &mut impl MemoryAccess,
13261    buf: AddrMut<u8>,
13262    format: DirentFormat,
13263    records: &[u8],
13264    names: &[usize],
13265    start: u64,
13266) -> (usize, Result<usize, Errno>) {
13267    if names.is_empty() {
13268        return (0, Ok(0));
13269    }
13270    let mut source = records.to_vec();
13271    let placeholder = source.len();
13272    source.extend_from_slice(&i64::try_from(start).unwrap_or(i64::MAX).to_ne_bytes());
13273    let (stores, filled) = dirent_stores(format, names, placeholder);
13274    // Each piece, within one page: where in the buffer and its bytes, and,
13275    // in `owner`, its store.
13276    let mut pieces: Vec<(usize, &[u8])> = Vec::with_capacity(stores.len());
13277    let mut owner = Vec::with_capacity(stores.len());
13278    // For each single store that crosses pages: its part written first, as an
13279    // index into `pieces`, and whether the guest can read that part's bytes.
13280    let mut crossing = Vec::new();
13281    for (index, store) in stores.iter().enumerate() {
13282        let mut split = guest_pages(buf.as_raw() + store.at, store.from.len());
13283        if store.single && split.len() > 1 {
13284            let readable: Result<Vec<bool>, Errno> = split
13285                .iter()
13286                .map(|&(at, len)| {
13287                    let mut bytes = vec![0; len];
13288                    let addr = unsafe { buf.add(store.at + at) };
13289                    Ok(read_guest_prefix(memory, addr, &mut bytes)? == len)
13290                })
13291                .collect();
13292            let mut readable = match readable {
13293                Ok(readable) => readable,
13294                Err(errno) => return (0, Err(errno)),
13295            };
13296            if readable[1] || !readable[0] {
13297                split.reverse();
13298                readable.reverse();
13299            }
13300            crossing.push((pieces.len(), readable[0]));
13301        }
13302        for (at, len) in split {
13303            let from = store.from.start + at;
13304            pieces.push((store.at + at, &source[from..from + len]));
13305            owner.push(index);
13306        }
13307    }
13308    // Write the pieces in order, stopping before the first part of each
13309    // crossing store to save what the guest has there. The stores before it
13310    // can have changed those bytes through another mapping of the same memory,
13311    // so they are read only once those stores are made.
13312    let mut next = 0;
13313    let mut saved: Option<(usize, Vec<u8>)> = None;
13314    let mut failed = None;
13315    for &(stop, readable) in crossing.iter().chain([(pieces.len(), false)].iter()) {
13316        let segment = &pieces[next..stop];
13317        let written = match write_guest_pieces(memory, buf, segment) {
13318            Ok(written) => written,
13319            Err(errno) => return (0, Err(errno)),
13320        };
13321        let mut end = 0;
13322        if let Some(at) = segment.iter().position(|(_, bytes)| {
13323            end += bytes.len();
13324            end > written
13325        }) {
13326            failed = Some(next + at);
13327            break;
13328        }
13329        if stop == pieces.len() {
13330            break;
13331        }
13332        let (at, bytes) = pieces[stop];
13333        let addr = unsafe { buf.add(at) };
13334        let mut before = vec![0; bytes.len()];
13335        let read = if readable {
13336            match read_guest_prefix(memory, addr, &mut before) {
13337                Ok(read) => read == before.len(),
13338                Err(errno) => return (0, Err(errno)),
13339            }
13340        } else {
13341            // The part in the second page, at its start, which no vectored copy
13342            // can read. Reverie's `read` of at most 8 bytes can on the ptrace
13343            // backend, through `PTRACE_PEEKDATA`, and a read changes nothing
13344            // the guest sees.
13345            memory.read_exact(addr, &mut before).is_ok()
13346        };
13347        saved = read.then_some((stop, before));
13348        next = stop;
13349    }
13350    let Some(failed) = failed else {
13351        return (names.len(), Ok(records.len()));
13352    };
13353    let store = owner[failed];
13354    if failed > 0
13355        && owner[failed - 1] == store
13356        && let Some((first, before)) = &saved
13357        && *first == failed - 1
13358        && let Err(errno) =
13359            write_guest_pieces(memory, buf, &[(pieces[*first].0, before.as_slice())])
13360    {
13361        return (0, Err(errno));
13362    }
13363    // The entry whose `filldir` made the store, or all of them for the call's
13364    // last store, and the first store of that `filldir`.
13365    let entry = filled.partition_point(|&end| end <= store);
13366    let first = entry.checked_sub(1).map_or(0, |before| filled[before]);
13367    let result = if entry == 0 || store == first {
13368        Err(Errno::EFAULT)
13369    } else {
13370        Ok(names[..entry]
13371            .iter()
13372            .map(|&name_len| format.record_len(name_len))
13373            .sum())
13374    };
13375    (entry, result)
13376}
13377
13378/// A guest `getdents` or `getdents64` call.
13379#[derive(Clone, Copy)]
13380struct GetdentsCall<'a> {
13381    /// The call as the guest made it.
13382    call: Syscall,
13383    /// The same call asking for no bytes.
13384    empty: Syscall,
13385    fd: RawFd,
13386    buf: AddrMut<'a, u8>,
13387    /// The guest's buffer size.
13388    capacity: usize,
13389    format: DirentFormat,
13390}
13391
13392impl<'a> GetdentsCall<'a> {
13393    /// The same call reading at most `count` bytes into `buf` instead.
13394    fn into_scratch<'b>(self, buf: AddrMut<'b, u8>, count: u32) -> GetdentsCall<'b> {
13395        let call = match self.call {
13396            Syscall::Getdents(call) => {
13397                Syscall::from(call.with_dirent(Some(buf.cast())).with_count(count))
13398            }
13399            Syscall::Getdents64(call) => {
13400                Syscall::from(call.with_dirent(Some(buf.cast())).with_count(count))
13401            }
13402            other => other,
13403        };
13404        GetdentsCall {
13405            call,
13406            empty: self.empty,
13407            fd: self.fd,
13408            buf,
13409            capacity: count as usize,
13410            format: self.format,
13411        }
13412    }
13413}
13414
13415/// Whether every byte of `[address, address + len)` lies in some mapping of a
13416/// `/proc/<pid>/maps` listing (`Detcore::vectored_signalfd_read`).
13417fn signalfd_range_is_mapped(maps: &str, address: usize, len: usize) -> bool {
13418    signalfd_range_is_covered(maps, address, len, false)
13419}
13420
13421/// Whether every byte of `[address, address + len)` lies in some writable
13422/// mapping of a `/proc/<pid>/maps` listing
13423/// (`Detcore::settle_faulted_signalfd_record`).
13424fn signalfd_range_is_writable(maps: &str, address: usize, len: usize) -> bool {
13425    signalfd_range_is_covered(maps, address, len, true)
13426}
13427
13428/// The pieces of the guest buffers `extents` (address, length) that the
13429/// signalfd record after the first `read` bytes would fill, or `None` if
13430/// they have no room for a whole record there (Linux reads only whole ones).
13431fn signalfd_next_record(extents: &[(usize, usize)], read: usize) -> Option<Vec<(usize, usize)>> {
13432    const RECORD: usize = std::mem::size_of::<libc::signalfd_siginfo>();
13433    let capacity = extents
13434        .iter()
13435        .try_fold(0usize, |total, (_, len)| total.checked_add(*len))?;
13436    if capacity / RECORD <= read / RECORD {
13437        return None;
13438    }
13439    let mut skip = read - read % RECORD;
13440    let mut left = RECORD;
13441    let mut pieces = Vec::new();
13442    for (address, len) in extents {
13443        if left == 0 {
13444            break;
13445        }
13446        if skip >= *len {
13447            skip -= len;
13448            continue;
13449        }
13450        let take = (len - skip).min(left);
13451        pieces.push((address + skip, take));
13452        left -= take;
13453        skip = 0;
13454    }
13455    Some(pieces)
13456}
13457
13458/// The end of the user address space, x86-64's `TASK_SIZE_MAX`, above which
13459/// `access_ok` fails a buffer before a call does anything: 2^56 - 4096 where
13460/// the kernel runs five-level page tables, 2^47 - 4096 otherwise. Measured
13461/// once, by asking for a mapping above 2^47, which the kernel grants there
13462/// only with five-level page tables.
13463fn user_address_end() -> usize {
13464    static END: std::sync::OnceLock<usize> = std::sync::OnceLock::new();
13465    *END.get_or_init(|| {
13466        const HINT: usize = 1 << 48;
13467        // SAFETY: a fresh anonymous mapping, unmapped at once; the hint is
13468        // only a hint (no MAP_FIXED).
13469        let at = unsafe {
13470            libc::mmap(
13471                HINT as *mut libc::c_void,
13472                4096,
13473                libc::PROT_NONE,
13474                libc::MAP_PRIVATE | libc::MAP_ANONYMOUS,
13475                -1,
13476                0,
13477            )
13478        };
13479        if at == libc::MAP_FAILED {
13480            return (1 << 47) - 4096;
13481        }
13482        // SAFETY: the mapping made above.
13483        unsafe { libc::munmap(at, 4096) };
13484        if at as usize >= 1 << 47 {
13485            (1 << 56) - 4096
13486        } else {
13487            (1 << 47) - 4096
13488        }
13489    })
13490}
13491
13492/// Authenticate the current task's FD/fdinfo directory by kernel object
13493/// identity, including symlink/bind aliases, without interpreting guest PIDs.
13494fn is_caller_descriptor_directory(
13495    observed: &std::fs::Metadata,
13496    caller: &str,
13497    process: Option<&str>,
13498) -> bool {
13499    [Some(caller), process].into_iter().flatten().any(|owner| {
13500        ["fd", "fdinfo"].into_iter().any(|kind| {
13501            std::fs::metadata(format!("{owner}/{kind}")).is_ok_and(|expected| {
13502                observed.dev() == expected.dev() && observed.ino() == expected.ino()
13503            })
13504        })
13505    })
13506}
13507
13508fn runtime_owned_descriptor_entry(name: &[u8], owns: impl FnOnce(RawFd) -> bool) -> bool {
13509    !name.is_empty()
13510        && name.iter().all(u8::is_ascii_digit)
13511        && std::str::from_utf8(name)
13512            .ok()
13513            .and_then(|name| name.parse::<RawFd>().ok())
13514            .is_some_and(owns)
13515}
13516
13517/// The signals a signalfd reads, from its `/proc/<pid>/fdinfo` entry.
13518fn signalfd_sigmask(pid: i32, fd: i32) -> Option<u64> {
13519    let info = std::fs::read_to_string(format!("/proc/{pid}/fdinfo/{fd}")).ok()?;
13520    let mask = info
13521        .lines()
13522        .find_map(|line| line.strip_prefix("sigmask:"))?;
13523    u64::from_str_radix(mask.trim(), 16).ok()
13524}
13525
13526fn signalfd_range_is_covered(maps: &str, address: usize, len: usize, writable: bool) -> bool {
13527    let mut ranges: Vec<(usize, usize)> = maps
13528        .lines()
13529        .filter_map(|line| {
13530            let mut fields = line.split_whitespace();
13531            let (start, end) = fields.next()?.split_once('-')?;
13532            if writable && !fields.next()?.contains('w') {
13533                return None;
13534            }
13535            Some((
13536                usize::from_str_radix(start, 16).ok()?,
13537                usize::from_str_radix(end, 16).ok()?,
13538            ))
13539        })
13540        .collect();
13541    ranges.sort();
13542    let Some(end) = address.checked_add(len) else {
13543        return false;
13544    };
13545    let mut next = address;
13546    for (start, stop) in ranges {
13547        if start <= next && next < stop {
13548            next = stop;
13549            if next >= end {
13550                return true;
13551            }
13552        }
13553    }
13554    false
13555}
13556
13557#[cfg(test)]
13558mod guest_proc_visibility_tests {
13559    use std::os::fd::AsRawFd;
13560
13561    use reverie::BackendCapabilities;
13562
13563    use super::reopens_scheduler_managed_pipe;
13564    use super::resolved_open_path;
13565
13566    /// The open-path helpers read `/proc/<pid>/fd/<fd>` wherever guest
13567    /// threads are host tasks: ptrace (whose facts a DBT run without its
13568    /// configuration keeps), in-guest LiteInst, DBT and SaBRe.
13569    /// With this process's own pipe and file, those read the links. KVM, whose
13570    /// guest is not a host task, never consults them and gives the helpers'
13571    /// "unknown" answers.
13572    #[tokio::test]
13573    async fn host_proc_links_are_read_except_under_kvm() {
13574        let pid = std::process::id() as i32;
13575        let (reader, _writer) = nix::unistd::pipe().unwrap();
13576        let alias = nix::unistd::dup(&reader).unwrap();
13577        let file = std::fs::File::open("/proc/self/exe").unwrap();
13578        let (pipe_fd, alias_fd) = (reader.as_raw_fd(), alias.as_raw_fd());
13579        let file_fd = file.as_raw_fd();
13580
13581        for backend in [
13582            BackendCapabilities::PTRACE,
13583            BackendCapabilities::LITEINST_IN_GUEST,
13584            BackendCapabilities::DBT,
13585            BackendCapabilities::SABRE,
13586        ] {
13587            assert!(
13588                reopens_scheduler_managed_pipe(&backend, pid, alias_fd, &[pipe_fd]),
13589                "{backend:?}"
13590            );
13591            assert!(
13592                resolved_open_path(&backend, pid, file_fd).is_some(),
13593                "{backend:?}"
13594            );
13595        }
13596        let kvm = BackendCapabilities::KVM;
13597        assert!(!reopens_scheduler_managed_pipe(
13598            &kvm,
13599            pid,
13600            alias_fd,
13601            &[pipe_fd]
13602        ));
13603        assert_eq!(resolved_open_path(&kvm, pid, file_fd), None);
13604
13605        // Runtime ownership is exact: ordinary high application descriptors
13606        // remain visible, and a directory merely named "fd" is not procfs.
13607        for name in [
13608            b"1023".as_slice(),
13609            b"1025",
13610            b"4096",
13611            b".",
13612            b"..",
13613            b"+1024",
13614            b"2147483648",
13615        ] {
13616            assert!(!super::runtime_owned_descriptor_entry(name, |fd| fd == 1024));
13617        }
13618        assert!(super::runtime_owned_descriptor_entry(b"1024", |fd| fd == 1024));
13619        assert!(!super::runtime_owned_descriptor_entry(b"1024", |_| false));
13620        for kind in ["fd", "fdinfo"] {
13621            let thread = std::fs::metadata(format!("/proc/thread-self/{kind}")).unwrap();
13622            let process = std::fs::metadata(format!("/proc/self/{kind}")).unwrap();
13623            assert!(super::is_caller_descriptor_directory(
13624                &thread,
13625                "/proc/thread-self",
13626                None
13627            ));
13628            assert!(!super::is_caller_descriptor_directory(
13629                &process,
13630                "/proc/thread-self",
13631                None
13632            ));
13633            assert!(super::is_caller_descriptor_directory(
13634                &process,
13635                "/proc/thread-self",
13636                Some("/proc/self")
13637            ));
13638        }
13639        let ordinary = tempfile::tempdir().unwrap();
13640        let metadata = std::fs::metadata(ordinary.path()).unwrap();
13641        assert!(!super::is_caller_descriptor_directory(
13642            &metadata,
13643            "/proc/thread-self",
13644            Some("/proc/self")
13645        ));
13646        super::inject_fstat_scratch::raw_directory_projection().await;
13647    }
13648}
13649
13650#[cfg(test)]
13651mod signalfd_geometry_tests {
13652    use super::signalfd_next_record;
13653    use super::signalfd_range_is_mapped;
13654    use super::signalfd_range_is_writable;
13655
13656    /// A range is mapped only when contiguous mappings cover every byte.
13657    #[test]
13658    fn an_iovec_array_is_mapped_only_when_mappings_cover_every_byte() {
13659        let maps =
13660            "1000-2000 r--p 0 0:0 0\n2000-3000 ---p 0 0:0 0 [vvar]\n5000-6000 rw-p 0 0:0 0\n";
13661        assert!(signalfd_range_is_mapped(maps, 0x1ff0, 32));
13662        assert!(
13663            !signalfd_range_is_mapped(maps, 0x2ff0, 32),
13664            "runs into a hole"
13665        );
13666        assert!(!signalfd_range_is_mapped(maps, 0x4000, 16));
13667        assert!(!signalfd_range_is_mapped(maps, usize::MAX - 4, 16));
13668        assert!(!signalfd_range_is_mapped("", 0x1000, 16));
13669    }
13670
13671    /// The record a signalfd read could have lost after the bytes it
13672    /// returned: only where the buffers hold a whole further record, which
13673    /// may span iovecs, and lost only if some byte of it is not writable.
13674    #[test]
13675    fn the_record_after_a_read_is_where_the_buffers_have_room_for_it() {
13676        assert_eq!(
13677            signalfd_next_record(&[(0x1000, 256)], 128),
13678            Some(vec![(0x1080, 128)])
13679        );
13680        assert_eq!(signalfd_next_record(&[(0x1000, 255)], 128), None);
13681        assert_eq!(signalfd_next_record(&[(0x1000, 128)], 128), None);
13682        assert_eq!(
13683            signalfd_next_record(&[(0x1000, 100), (0x3000, 60), (0x5000, 300)], 128),
13684            Some(vec![(0x3000 + 28, 32), (0x5000, 96)])
13685        );
13686        assert_eq!(
13687            signalfd_next_record(&[(0x1000, usize::MAX), (0x2000, 2)], 0),
13688            None
13689        );
13690        let maps = "1000-2000 rw-p 0 0:0 0\n2000-3000 ---p 0 0:0 0\n";
13691        assert!(signalfd_range_is_writable(maps, 0x1f80, 128));
13692        assert!(!signalfd_range_is_writable(maps, 0x1fc0, 128));
13693        assert!(signalfd_range_is_mapped(maps, 0x1fc0, 128));
13694    }
13695}
13696
13697#[cfg(test)]
13698mod procfs_wiring_guard {
13699    //! The procfs snapshot WIRING, guarded where the wiring lives.
13700    //!
13701    //! WHY THIS IS A SOURCE-LEVEL GUARD AND NOT A BEHAVIOURAL TEST. The thing
13702    //! at risk is not `ProcfsFile`'s logic -- that is exercised elsewhere. It is
13703    //! the CALL from each read handler into the snapshot initialiser. Those
13704    //! handlers are `async fn`s on the `Tool` trait taking a live `Guest`, so a
13705    //! unit test cannot invoke one without standing up a traced guest process;
13706    //! that is exactly why the only thing guarding this today is one heavyweight
13707    //! integration test that compiles a C probe and runs hermit.
13708    //!
13709    //! MEASURED GAP (2026-08-07, hermit 75506005d): deleting the pread64
13710    //! snapshot-initialisation block leaves ALL 386 detcore lib tests green.
13711    //! A mechanism whose only proof of life is one fixture is one deletion away
13712    //! from vanishing unnoticed -- the positioned-read determinism bug this
13713    //! wiring fixes would silently return.
13714    //!
13715    //! These assertions are deliberately narrow: they bind to the CALL, name the
13716    //! mechanism when they fail, and cost nothing to run. They do not claim to
13717    //! verify that the snapshot is correct.
13718
13719    /// The production source only. `include_str!` pulls in THIS module too, so a
13720    /// naive scan counts the guard's own string literals and reports phantom
13721    /// duplicates -- it did exactly that on first run. Truncating at the guard's
13722    /// own header makes every assertion below immune to self-reference.
13723    fn production_source() -> &'static str {
13724        const WHOLE: &str = include_str!("files.rs");
13725        const GUARD: &str = "#[cfg(test)]\nmod procfs_wiring_guard {";
13726        match WHOLE.find(GUARD) {
13727            Some(cut) => &WHOLE[..cut],
13728            None => WHOLE,
13729        }
13730    }
13731
13732    /// The body of `fn <name>` up to the next top-level `    }` at fn indent.
13733    fn handler_body(name: &str) -> &'static str {
13734        let start = production_source()
13735            .find(&format!("fn {}<G: Guest<Self>>", name))
13736            .unwrap_or_else(|| {
13737                panic!(
13738                    "procfs wiring guard: handler `{name}` not found in files.rs.\n\
13739                     TWO VERY DIFFERENT CAUSES, and the guard cannot tell them apart:\n\
13740                       (a) the handler was RENAMED or its signature changed -- the \
13741                     mechanism is fine, update the name in this guard; or\n\
13742                       (b) the handler was DELETED -- the procfs snapshot wiring is gone.\n\
13743                     Check which before editing. This guard binds to source text on \
13744                     purpose: the handlers are async `Tool` methods taking a live Guest, \
13745                     so nothing cheaper can observe the call. It is deliberately loud \
13746                     when it cannot see the code, because silently passing is the \
13747                     failure it exists to prevent."
13748                )
13749            });
13750        let rest = &production_source()[start..];
13751        let end = rest
13752            .find(
13753                "
13754    }
13755",
13756            )
13757            .map(|e| e + 6)
13758            .unwrap_or(rest.len());
13759        &rest[..end]
13760    }
13761
13762    #[test]
13763    fn pread64_initializes_the_procfs_snapshot() {
13764        let body = handler_body("handle_pread64");
13765        assert!(
13766            body.contains("procfs_needs_snapshot") && body.contains("initialize_procfs_snapshot"),
13767            "MISSING MECHANISM: the pread64 handler no longer initialises the procfs \
13768             snapshot. Positioned reads will fall through to LIVE KERNEL BYTES instead of \
13769             the sanitized ProcfsFile snapshot, reintroducing the positioned-read \
13770             nondeterminism that hermit-cli/tests/procfs_positioned_determinism.rs exists \
13771             to catch. Restore the `procfs_needs_snapshot` -> `initialize_procfs_snapshot` \
13772             call in handle_pread64."
13773        );
13774    }
13775
13776    #[test]
13777    fn read_initializes_the_procfs_snapshot() {
13778        let body = handler_body("handle_read");
13779        assert!(
13780            body.contains("procfs_needs_snapshot") && body.contains("initialize_procfs_snapshot"),
13781            "MISSING MECHANISM: the sequential read handler no longer initialises the \
13782             procfs snapshot. Reads of /proc will observe live kernel bytes. Restore the \
13783             `procfs_needs_snapshot` -> `initialize_procfs_snapshot` call in handle_read."
13784        );
13785    }
13786
13787    #[test]
13788    fn both_read_paths_share_one_snapshot_initializer() {
13789        // The original defect was exactly this asymmetry: `read` consumed the
13790        // sanitized snapshot while `pread64` did not. Forking the logic into two
13791        // initialisers is how that asymmetry comes back.
13792        let n = production_source()
13793            .matches("async fn initialize_procfs_snapshot")
13794            .count();
13795        assert_eq!(
13796            n, 1,
13797            "MISSING MECHANISM: expected exactly ONE `initialize_procfs_snapshot` \
13798             definition so every read path shares it; found {n}. Two initialisers is how \
13799             read/pread64 drifted apart in the first place."
13800        );
13801        for handler in ["handle_read", "handle_pread64"] {
13802            assert!(
13803                handler_body(handler).contains("self.initialize_procfs_snapshot("),
13804                "MISSING MECHANISM: `{handler}` does not call the shared \
13805                 initialize_procfs_snapshot."
13806            );
13807        }
13808    }
13809
13810    /// Both mountinfo captures in the snapshot initializer must drop ephemeral
13811    /// host seed rows (https://github.com/rrnewton/hermit/pull/3219): the guest
13812    /// read's capture, for the files that carry mountinfo identities, and the
13813    /// tracer-side capture that validates fdinfo `mnt_id`. Without either, host
13814    /// seed churn reaches guest-visible mountinfo or shifts mount-ID assignment,
13815    /// and no unit test of the filter itself notices.
13816    #[test]
13817    fn snapshot_initializer_excludes_host_seed_mounts_at_both_captures() {
13818        let body = handler_body("initialize_procfs_snapshot");
13819        let calls = body.matches("exclude_ephemeral_host_seed_mounts(").count();
13820        assert_eq!(
13821            calls, 2,
13822            "MISSING MECHANISM: initialize_procfs_snapshot must call \
13823             exclude_ephemeral_host_seed_mounts exactly twice (the guest mountinfo \
13824             capture and the fdinfo mnt_id capture); found {calls}. Without it, \
13825             unrelated host squashfuse seed mounts make /proc/<pid>/mountinfo and \
13826             fdinfo mount IDs depend on host timing."
13827        );
13828        let guest_capture = body
13829            .find("exclude_ephemeral_host_seed_mounts(&raw_contents)")
13830            .expect(
13831                "MISSING MECHANISM: the guest read's procfs capture (`raw_contents`) is \
13832                 no longer filtered for host seed mounts",
13833            );
13834        let gate = body[..guest_capture]
13835            .rfind("let contents = if")
13836            .map(|start| &body[start..guest_capture])
13837            .unwrap_or_default();
13838        assert!(
13839            gate.contains("procfs_needs_mountinfo_identities()"),
13840            "MISSING MECHANISM: the guest capture's seed filter must apply exactly to \
13841             the files that carry mountinfo identities (`let contents = if ... \
13842             procfs_needs_mountinfo_identities()`); found {gate:?}"
13843        );
13844        let fdinfo_capture = body
13845            .find("exclude_ephemeral_host_seed_mounts(&mountinfo_contents)")
13846            .expect(
13847                "MISSING MECHANISM: the fdinfo mnt_id capture (`mountinfo_contents`) is \
13848                 no longer filtered for host seed mounts",
13849            );
13850        let parse = body
13851            .find("parse_mountinfo(&mountinfo_contents)")
13852            .expect("the fdinfo mnt_id capture no longer parses mountinfo_contents");
13853        assert!(
13854            fdinfo_capture < parse,
13855            "MISSING MECHANISM: the fdinfo mnt_id capture parses mountinfo before \
13856             dropping host seed rows"
13857        );
13858    }
13859
13860    #[test]
13861    fn the_guard_can_actually_see_the_handlers() {
13862        // Positive control: if the extractor silently returned empty bodies the
13863        // three assertions above would be vacuous rather than protective.
13864        for handler in ["handle_read", "handle_pread64"] {
13865            let body = handler_body(handler);
13866            assert!(
13867                body.len() > 200 && body.contains("call.fd()"),
13868                "guard extractor did not find a real body for `{handler}` \
13869                 (len {}), so the wiring assertions would be vacuous",
13870                body.len()
13871            );
13872        }
13873    }
13874}
13875
13876#[cfg(test)]
13877mod test {
13878    use nix::fcntl::OFlag;
13879    use reverie::syscalls::FromToRaw;
13880    use reverie::syscalls::LocalMemory;
13881    use reverie::syscalls::Whence;
13882
13883    use super::DETERMINISTIC_PIPE_CAPACITY_BYTES;
13884    use super::fcntl_host_timed_signals;
13885    use super::ioctl_host_timed_signals;
13886    use super::may_have_acquired_controlling_terminal;
13887    use super::open_can_acquire_controlling_terminal;
13888    use super::opened_controlling_terminal;
13889    use super::pipe_capacity_request_exceeds_ceiling;
13890    use super::terminal_can_become_controlling;
13891    use crate::test_pages::PAGE;
13892    use crate::test_pages::Pages;
13893
13894    /// A `/proc/self` or `/proc/thread-self` spelling leads to the opener's
13895    /// task, which a name relative to the descriptor is then looked up below,
13896    /// whoever looks it up.
13897    #[test]
13898    fn a_proc_selector_leads_to_the_openers_task() {
13899        use std::path::Path;
13900
13901        use super::procfs_selector_reached;
13902
13903        let own = Some((3, 5));
13904        for (spelling, reached) in [
13905            ("/proc/self", Some("/proc/3")),
13906            ("/proc/self/", Some("/proc/3")),
13907            ("/proc/self/task", Some("/proc/3/task")),
13908            ("/proc/self/task/5", Some("/proc/3/task/5")),
13909            ("/proc/thread-self", Some("/proc/3/task/5")),
13910            ("/proc/self/fd/7", None),
13911            ("/proc/self/task/05", None),
13912            ("/proc/thread-self/fd/7", None),
13913            ("/proc/self/cwd", None),
13914            ("/proc/3", Some("/proc/3")),
13915            ("/proc/7/", Some("/proc/7")),
13916            ("/proc/7/task", Some("/proc/7/task")),
13917            ("/proc/7/task/9", Some("/proc/7/task/9")),
13918            ("/proc/07", None),
13919            ("/proc/7/task/09", None),
13920            ("/proc/7/fd", None),
13921            ("/proc/7/task/9/fd/1", None),
13922            ("/proc/sys", None),
13923            ("/proc", None),
13924            ("/proc/selfish", None),
13925            ("/dev/fd", None),
13926            ("self", None),
13927        ] {
13928            assert_eq!(
13929                procfs_selector_reached(Path::new(spelling), own).as_deref(),
13930                reached.map(Path::new),
13931                "{spelling}"
13932            );
13933        }
13934        // In a nested PID namespace Detcore does not know the caller's numbers.
13935        assert_eq!(procfs_selector_reached(Path::new("/proc/self"), None), None);
13936        assert_eq!(procfs_selector_reached(Path::new("/proc/3"), None), None);
13937        // The selector links themselves, which an `O_PATH | O_NOFOLLOW` open
13938        // opens rather than the directory they lead to.
13939        for (spelling, link) in [
13940            ("/proc/self", true),
13941            ("/proc/thread-self", true),
13942            // A trailing slash follows the link (`opens_the_link_itself`).
13943            ("/proc/self/", true),
13944            ("/proc/self/task", false),
13945            ("/proc/3", false),
13946            ("/proc/selfish", false),
13947        ] {
13948            assert_eq!(
13949                super::names_a_selector_link(Path::new(spelling)),
13950                link,
13951                "{spelling}"
13952            );
13953        }
13954        // The task each reached directory is, or is below.
13955        let task = |process, thread| crate::procfs::BoundTask { process, thread };
13956        for (reached, expected) in [
13957            ("/proc/3", Some(task(3, None))),
13958            ("/proc/3/task", Some(task(3, None))),
13959            ("/proc/3/task/5", Some(task(3, Some(5)))),
13960            ("/proc/3/task/5/ns", Some(task(3, Some(5)))),
13961            ("/proc/3/ns", Some(task(3, None))),
13962            ("/proc", None),
13963            ("/proc/sys", None),
13964            ("/proc/0", None),
13965        ] {
13966            assert_eq!(
13967                super::procfs_reached_task(Path::new(reached)),
13968                expected,
13969                "{reached}"
13970            );
13971        }
13972    }
13973
13974    /// A descriptor opened through one of the caller's descriptor links
13975    /// records the path of the descriptor the link names, so a name relative
13976    /// to it is the file Linux finds below that file: `/proc/stat` through a
13977    /// reopened `/proc`, and through a reopened reopening. It keeps its
13978    /// spelling wherever the recorded path could name another file: a link
13979    /// opened itself (`O_NOFOLLOW` without a trailing slash), the process's
13980    /// table where the caller holds a table of its own, a target without an
13981    /// absolute recorded path, and a target that names a per-caller
13982    /// selector. Every other open records its spelling.
13983    #[test]
13984    fn an_open_through_a_descriptor_link_records_the_targets_path() {
13985        use std::path::Path;
13986        use std::path::PathBuf;
13987
13988        use super::DescriptorLinkOpener;
13989        use super::path_to_record_for_open;
13990
13991        let leader = DescriptorLinkOpener {
13992            own: Some((3, 3)),
13993            holds_process_table: true,
13994        };
13995        let read = OFlag::O_RDONLY | OFlag::O_DIRECTORY;
13996        let table = |fd: i32| match fd {
13997            4 => Some(PathBuf::from("/proc")),
13998            6 => Some(PathBuf::from("relative/dir")),
13999            8 => Some(PathBuf::from("/proc/self")),
14000            9 => Some(PathBuf::from("/proc/thread-self")),
14001            10 => Some(PathBuf::from("/dev/fd")),
14002            11 => Some(PathBuf::from("/proc/12")),
14003            _ => None,
14004        };
14005        for spelling in [
14006            "/proc/self/fd/4",
14007            "/dev/fd/4",
14008            "/proc/thread-self/fd/4",
14009            "/proc/3/fd/4",
14010            "/proc/3/task/3/fd/4",
14011        ] {
14012            let recorded = path_to_record_for_open(Path::new(spelling), read, leader, table, None);
14013            assert_eq!(recorded, Path::new("/proc"), "{spelling}");
14014            // A dirfd-relative name below the new descriptor is then the
14015            // rendered file's own path (`Detcore::observed_path`).
14016            assert_eq!(recorded.join("stat"), Path::new("/proc/stat"));
14017            assert_eq!(
14018                recorded.join("sys/kernel/random/uuid"),
14019                Path::new("/proc/sys/kernel/random/uuid")
14020            );
14021        }
14022        // An alias of an alias: the second open finds the first's recorded
14023        // path, already the target's.
14024        let first =
14025            path_to_record_for_open(Path::new("/proc/self/fd/4"), read, leader, table, None);
14026        let second = path_to_record_for_open(
14027            Path::new("/dev/fd/9"),
14028            read,
14029            leader,
14030            |fd| (fd == 9).then(|| first.clone()),
14031            None,
14032        );
14033        assert_eq!(second, Path::new("/proc"));
14034        // O_NOFOLLOW opens the link itself (O_PATH) unless a trailing slash
14035        // or `/.` follows it.
14036        let nofollow = OFlag::O_PATH | OFlag::O_NOFOLLOW;
14037        assert_eq!(
14038            path_to_record_for_open(Path::new("/proc/self/fd/4"), nofollow, leader, table, None),
14039            Path::new("/proc/self/fd/4")
14040        );
14041        for spelling in ["/proc/self/fd/4/", "/proc/self/fd/4/.", "/dev/fd/4/"] {
14042            assert_eq!(
14043                path_to_record_for_open(Path::new(spelling), nofollow, leader, table, None),
14044                Path::new("/proc"),
14045                "{spelling}"
14046            );
14047        }
14048        // A thread with a table of its own: the process's links name the
14049        // leader's table, not the caller's, so they keep the spelling; its
14050        // own thread links still name its table.
14051        let split = DescriptorLinkOpener {
14052            own: Some((3, 5)),
14053            holds_process_table: false,
14054        };
14055        for spelling in ["/proc/self/fd/4", "/dev/fd/4", "/proc/3/fd/4"] {
14056            assert_eq!(
14057                path_to_record_for_open(
14058                    Path::new(spelling),
14059                    read,
14060                    split,
14061                    |_| { panic!("{spelling} names the leader's table, not the caller's") },
14062                    None
14063                ),
14064                Path::new(spelling)
14065            );
14066        }
14067        for spelling in ["/proc/thread-self/fd/4", "/proc/3/task/5/fd/4"] {
14068            assert_eq!(
14069                path_to_record_for_open(Path::new(spelling), read, split, table, None),
14070                Path::new("/proc"),
14071                "{spelling}"
14072            );
14073        }
14074        // A target without a recorded path, with a relative one, or with one
14075        // procfs resolves per caller, and another process's link, keep the
14076        // spelling. A numeric /proc/<pid> target is not per caller.
14077        for spelling in [
14078            "/proc/self/fd/5",
14079            "/proc/self/fd/6",
14080            "/proc/self/fd/8",
14081            "/proc/self/fd/9",
14082            "/dev/fd/10",
14083            "/proc/7/fd/4",
14084        ] {
14085            assert_eq!(
14086                path_to_record_for_open(Path::new(spelling), read, leader, table, None),
14087                Path::new(spelling)
14088            );
14089        }
14090        assert_eq!(
14091            path_to_record_for_open(Path::new("/dev/fd/11"), read, leader, table, None),
14092            Path::new("/proc/12")
14093        );
14094        // So does every open that names no descriptor link.
14095        for spelling in ["/proc/stat", "/proc/self/fd/4/stat", "/tmp/x"] {
14096            assert_eq!(
14097                path_to_record_for_open(
14098                    Path::new(spelling),
14099                    read,
14100                    leader,
14101                    |_| { panic!("{spelling} names no descriptor") },
14102                    None
14103                ),
14104                Path::new(spelling)
14105            );
14106        }
14107        // The path is N's as the open's lookup found it, and only while N
14108        // holds the same open file description: an open of N's link that
14109        // waited (a FIFO) while a thread sharing the table replaced N with a
14110        // /proc descriptor opened the FIFO, so it is not recorded as /proc.
14111        use super::LinkSource;
14112        let creator = crate::types::DetTid::from_raw(3);
14113        let fifo = LinkSource {
14114            fd: 5,
14115            path: Some(PathBuf::from("/tmp/dir/fifo")),
14116            open_file: crate::types::OpenFileId::new(creator, 7),
14117            reached: None,
14118        };
14119        let replaced = Some(crate::types::OpenFileId::new(creator, 8));
14120        let unchanged = Some(fifo.open_file);
14121        let spelling = Path::new("/proc/self/fd/5");
14122        assert_eq!(
14123            path_to_record_for_open(
14124                spelling,
14125                read,
14126                leader,
14127                |fd| fifo.path_if_unchanged(fd, unchanged),
14128                None
14129            ),
14130            Path::new("/tmp/dir/fifo")
14131        );
14132        assert_eq!(
14133            path_to_record_for_open(
14134                spelling,
14135                read,
14136                leader,
14137                |fd| fifo.path_if_unchanged(fd, replaced),
14138                None
14139            ),
14140            spelling
14141        );
14142        assert_eq!(
14143            path_to_record_for_open(
14144                spelling,
14145                read,
14146                leader,
14147                |fd| fifo.path_if_unchanged(fd, None),
14148                None
14149            ),
14150            spelling
14151        );
14152        assert_eq!(fifo.path_if_unchanged(4, unchanged), None);
14153    }
14154
14155    /// Where the descriptor a link names has no recorded path (one received
14156    /// through `SCM_RIGHTS`, which Detcore does not track), an open through
14157    /// the link records the procfs directory the kernel names for the opened
14158    /// descriptor (`Detcore::procfs_directory_named_for`): `/proc`, below
14159    /// which `stat` is `/proc/stat`. Without that name it keeps the
14160    /// spelling, as before. A recorded path of `N` still comes first, and the
14161    /// name is never taken for a link opened itself, a spelling that names no
14162    /// descriptor link, or a link to a table the caller does not hold. Only
14163    /// `/proc` and the pid-free paths below it are names the kernel's link
14164    /// may give (`procfs_directory_link`).
14165    #[test]
14166    fn an_open_through_an_unrecorded_descriptors_link_records_its_identity() {
14167        use std::path::Path;
14168        use std::path::PathBuf;
14169
14170        use super::DescriptorLinkOpener;
14171        use super::path_to_record_for_open;
14172
14173        let leader = DescriptorLinkOpener {
14174            own: Some((3, 3)),
14175            holds_process_table: true,
14176        };
14177        let read = OFlag::O_RDONLY | OFlag::O_DIRECTORY;
14178        let proc = || Some(PathBuf::from("/proc"));
14179        for spelling in [
14180            "/proc/self/fd/10",
14181            "/dev/fd/10",
14182            "/proc/thread-self/fd/10",
14183            "/proc/3/fd/10",
14184            "/proc/3/task/3/fd/10",
14185        ] {
14186            let recorded =
14187                path_to_record_for_open(Path::new(spelling), read, leader, |_| None, proc());
14188            assert_eq!(recorded, Path::new("/proc"), "{spelling}");
14189            assert_eq!(recorded.join("stat"), Path::new("/proc/stat"));
14190            assert_eq!(
14191                path_to_record_for_open(Path::new(spelling), read, leader, |_| None, None),
14192                Path::new(spelling)
14193            );
14194        }
14195        assert_eq!(
14196            path_to_record_for_open(
14197                Path::new("/proc/self/fd/4"),
14198                read,
14199                leader,
14200                |fd| (fd == 4).then(|| PathBuf::from("/proc/12")),
14201                proc(),
14202            ),
14203            Path::new("/proc/12")
14204        );
14205        let nofollow = OFlag::O_PATH | OFlag::O_NOFOLLOW;
14206        assert_eq!(
14207            path_to_record_for_open(
14208                Path::new("/proc/self/fd/10"),
14209                nofollow,
14210                leader,
14211                |_| None,
14212                proc()
14213            ),
14214            Path::new("/proc/self/fd/10")
14215        );
14216        for spelling in ["/proc/self/fd/10/stat", "/tmp/x"] {
14217            assert_eq!(
14218                path_to_record_for_open(Path::new(spelling), read, leader, |_| None, proc()),
14219                Path::new(spelling)
14220            );
14221        }
14222        // A recorded path refused as per caller is not replaced by the name.
14223        assert_eq!(
14224            path_to_record_for_open(
14225                Path::new("/proc/self/fd/8"),
14226                read,
14227                leader,
14228                |_| Some(PathBuf::from("/proc/self")),
14229                proc(),
14230            ),
14231            Path::new("/proc/self/fd/8")
14232        );
14233        // A thread with a table of its own: the process's links name the
14234        // leader's table, whose N the caller's table does not describe, so
14235        // they keep the spelling; its own thread links take the name.
14236        let split = DescriptorLinkOpener {
14237            own: Some((3, 5)),
14238            holds_process_table: false,
14239        };
14240        for spelling in ["/proc/self/fd/10", "/dev/fd/10", "/proc/3/fd/10"] {
14241            assert_eq!(
14242                path_to_record_for_open(Path::new(spelling), read, split, |_| None, proc()),
14243                Path::new(spelling)
14244            );
14245        }
14246        for spelling in ["/proc/thread-self/fd/10", "/proc/3/task/5/fd/10"] {
14247            assert_eq!(
14248                path_to_record_for_open(Path::new(spelling), read, split, |_| None, proc()),
14249                Path::new("/proc"),
14250                "{spelling}"
14251            );
14252        }
14253        use super::procfs_directory_link;
14254        for accepted in ["/proc", "/proc/sys", "/proc/sys/kernel", "/proc/sys/net"] {
14255            assert!(procfs_directory_link(Path::new(accepted)), "{accepted}");
14256        }
14257        for refused in [
14258            "/tmp/dir",
14259            "/procfs",
14260            "/proc (deleted)",
14261            "/proc/sys (deleted)",
14262            "/proc/12",
14263            "/proc/12/task/12",
14264            "/proc/self",
14265            "/proc/thread-self",
14266            // A symbolic link to the caller's own /proc/self/net.
14267            "/proc/net",
14268            "/proc/sys/../12",
14269            "proc",
14270            "anon_inode:[eventfd]",
14271            "/memfd:x (deleted)",
14272        ] {
14273            assert!(!procfs_directory_link(Path::new(refused)), "{refused}");
14274        }
14275    }
14276
14277    /// The kernel's name for a received procfs directory gives its components
14278    /// below `/proc` and the positions of the task numbers among them, which
14279    /// DBT translates to the guest's: a process's directory and a thread's
14280    /// below its `task`, nothing for the system directories, and no name
14281    /// procfs would not give.
14282    #[test]
14283    fn a_received_procfs_directory_names_its_task_positions() {
14284        use super::procfs_directory_task_positions;
14285        let parsed = |link: &str| procfs_directory_task_positions(link);
14286        let owned = |names: &[&str]| names.iter().map(|name| (*name).to_owned()).collect();
14287        assert_eq!(parsed("/proc"), Some((Vec::new(), Vec::new())));
14288        assert_eq!(
14289            parsed("/proc/sys/kernel"),
14290            Some((owned(&["sys", "kernel"]), Vec::new()))
14291        );
14292        assert_eq!(parsed("/proc/12"), Some((owned(&["12"]), vec![0])));
14293        assert_eq!(parsed("/proc/12/ns"), Some((owned(&["12", "ns"]), vec![0])));
14294        assert_eq!(parsed("/proc/12/fd"), Some((owned(&["12", "fd"]), vec![0])));
14295        assert_eq!(
14296            parsed("/proc/12/task/14"),
14297            Some((owned(&["12", "task", "14"]), vec![0, 2]))
14298        );
14299        assert_eq!(
14300            parsed("/proc/12/task/14/ns"),
14301            Some((owned(&["12", "task", "14", "ns"]), vec![0, 2]))
14302        );
14303        assert_eq!(
14304            parsed("/proc/irq/5"),
14305            Some((owned(&["irq", "5"]), Vec::new()))
14306        );
14307        for refused in [
14308            "/proc/012",
14309            "/proc/12/task/014",
14310            "/procfs",
14311            "/tmp/12",
14312            "proc/12",
14313            "/proc/12 (deleted)",
14314            "socket:[1]",
14315            "/proc/12/../13",
14316        ] {
14317            assert_eq!(parsed(refused), None, "{refused}");
14318        }
14319    }
14320
14321    #[test]
14322    fn inherited_input_status_flags_remain_kernel_owned() {
14323        for recordreplay_modes in [false, true] {
14324            let tool = crate::Detcore {
14325                detpid: crate::types::DetPid::from_raw(3),
14326                cfg: crate::Config {
14327                    sequentialize_threads: true,
14328                    recordreplay_modes,
14329                    ..Default::default()
14330                },
14331                record_or_replay: crate::record_or_replay::NoopTool,
14332            };
14333            for physically_nonblocking in [false, true] {
14334                assert!(!tool.keeps_physically_nonblocking(
14335                    crate::fd::FdType::Pipe,
14336                    false,
14337                    physically_nonblocking,
14338                    true
14339                ));
14340                assert_eq!(
14341                    tool.keeps_physically_nonblocking(
14342                        crate::fd::FdType::Pipe,
14343                        false,
14344                        physically_nonblocking,
14345                        false
14346                    ),
14347                    !recordreplay_modes || physically_nonblocking
14348                );
14349                assert_eq!(
14350                    tool.keeps_physically_nonblocking(
14351                        crate::fd::FdType::Socket,
14352                        true,
14353                        physically_nonblocking,
14354                        false
14355                    ),
14356                    !recordreplay_modes || physically_nonblocking
14357                );
14358            }
14359        }
14360    }
14361
14362    /// Every `fcntl` and `ioctl` that can make Linux signal a descriptor's
14363    /// owner at a moment set by host timing names SIGIO and SIGURG, plus the
14364    /// signal `F_SETSIG` chooses; every other command names nothing
14365    /// (https://github.com/rrnewton/hermit/issues/3146).
14366    #[test]
14367    fn async_io_arming_calls_name_their_host_timed_signals() {
14368        use reverie::syscalls::FcntlCmd;
14369        use reverie::syscalls::ioctl::Request;
14370        let bit = |signal: i32| 1_u64 << (signal - 1);
14371        let async_io = bit(libc::SIGIO) | bit(libc::SIGURG);
14372        for (cmd, expected) in [
14373            (
14374                FcntlCmd::F_SETFL(libc::O_ASYNC | libc::O_NONBLOCK),
14375                async_io,
14376            ),
14377            (FcntlCmd::F_SETFL(libc::O_NONBLOCK), 0),
14378            (FcntlCmd::F_SETOWN, async_io),
14379            (FcntlCmd::F_SETOWN_EX(None), async_io),
14380            (FcntlCmd::F_SETLEASE(libc::F_RDLCK), async_io),
14381            // DN_MODIFY, which the libc crate does not export.
14382            (FcntlCmd::F_NOTIFY(0x2), async_io),
14383            (
14384                FcntlCmd::F_SETSIG(libc::SIGUSR1),
14385                async_io | bit(libc::SIGUSR1),
14386            ),
14387            (FcntlCmd::F_SETSIG(0), async_io),
14388            (FcntlCmd::F_GETFL, 0),
14389            (FcntlCmd::F_SETFD(libc::FD_CLOEXEC), 0),
14390        ] {
14391            assert_eq!(fcntl_host_timed_signals(cmd), expected, "{cmd:?}");
14392        }
14393        for (request, expected) in [
14394            (Request::FIOASYNC(None), async_io),
14395            (Request::FIOSETOWN(None), async_io),
14396            (Request::SIOCSPGRP(None), async_io),
14397            (Request::FIOCLEX, 0),
14398        ] {
14399            assert_eq!(ioctl_host_timed_signals(request), expected, "{request:?}");
14400        }
14401    }
14402
14403    /// The calls that give a session its controlling terminal (TIOCSCTTY, and
14404    /// TIOCGPTPEER without O_NOCTTY, which opens a pseudoterminal's other end
14405    /// as `open` does) or choose the terminal's foreground process group
14406    /// (TIOCSPGRP) name every signal Linux sends because of that terminal, at
14407    /// a moment set by host timing: SIGHUP and SIGCONT when it hangs up or the
14408    /// leader exits, SIGINT, SIGQUIT and SIGTSTP for its interrupt, quit and
14409    /// suspend characters, SIGWINCH when its size changes, and SIGTTIN and
14410    /// SIGTTOU when a background process group reads or writes it. Reading the
14411    /// foreground group (TIOCGPGRP), giving up the controlling terminal
14412    /// (TIOCNOTTY), opening the other end with O_NOCTTY, and setting the size
14413    /// (TIOCSWINSZ, whose SIGWINCH is sent inside the caller's call) name
14414    /// nothing (round-9 High 2 and the round-11 finding "Terminal resize
14415    /// remains an admitted host-timed interruption" of
14416    /// https://github.com/rrnewton/hermit/pull/3361).
14417    #[test]
14418    fn terminal_control_calls_name_the_terminal_signals() {
14419        use reverie::syscalls::ioctl::Request;
14420        let bit = |signal: i32| 1_u64 << (signal - 1);
14421        let terminal = [
14422            libc::SIGHUP,
14423            libc::SIGCONT,
14424            libc::SIGINT,
14425            libc::SIGQUIT,
14426            libc::SIGTSTP,
14427            libc::SIGWINCH,
14428            libc::SIGTTIN,
14429            libc::SIGTTOU,
14430        ]
14431        .into_iter()
14432        .fold(0, |set, signal| set | bit(signal));
14433        for (request, expected) in [
14434            (Request::TIOCSCTTY(0), terminal),
14435            (Request::TIOCSCTTY(1), terminal),
14436            (Request::TIOCSPGRP(None), terminal),
14437            (Request::TIOCGPTPEER(libc::O_RDWR), terminal),
14438            (
14439                Request::TIOCGPTPEER(libc::O_RDWR | libc::O_CLOEXEC),
14440                terminal,
14441            ),
14442            (Request::TIOCGPTPEER(libc::O_RDWR | libc::O_NOCTTY), 0),
14443            (Request::TIOCGPGRP(None), 0),
14444            (Request::TIOCNOTTY, 0),
14445            (Request::TIOCSWINSZ(None), 0),
14446        ] {
14447            assert_eq!(ioctl_host_timed_signals(request), expected, "{request:?}");
14448        }
14449    }
14450
14451    /// An `open` can give its caller a controlling terminal only without
14452    /// O_NOCTTY and O_PATH, only in a session leader, and only of a terminal
14453    /// Linux can make controlling. None of the inputs is the controlling
14454    /// terminal procfs lists, which a hangup clears
14455    /// (https://github.com/rrnewton/hermit/issues/3146,
14456    /// https://github.com/rrnewton/hermit/pull/3361).
14457    #[test]
14458    fn an_open_acquires_a_controlling_terminal_only_as_a_session_leader() {
14459        assert!(open_can_acquire_controlling_terminal(OFlag::O_RDWR));
14460        assert!(!open_can_acquire_controlling_terminal(
14461            OFlag::O_RDWR | OFlag::O_NOCTTY
14462        ));
14463        assert!(!open_can_acquire_controlling_terminal(OFlag::O_PATH));
14464        // A host's /proc/tty/drivers, plus a driver whose name has a space.
14465        let table = Some(
14466            "/dev/tty             /dev/tty        5       0 system:/dev/tty\n\
14467             /dev/console         /dev/console    5       1 system:console\n\
14468             /dev/ptmx            /dev/ptmx       5       2 system\n\
14469             /dev/vc/0            /dev/vc/0       4       0 system:vtmaster\n\
14470             serial_8250          /dev/ttyS       4 64-95 serial\n\
14471             acm serial           /dev/ttyACM   166 0-255 serial\n\
14472             pty_slave            /dev/pts      136 0-1048575 pty:slave\n\
14473             pty_master           /dev/ptm      128 0-1048575 pty:master\n\
14474             unknown              /dev/tty        4 1-63 console\n",
14475        );
14476        // /dev/pts/3 is character device 136:3; minor 300 sets bits above 0xff.
14477        let pts3 = libc::makedev(136, 3);
14478        let pts300 = libc::makedev(136, 300);
14479        assert!(may_have_acquired_controlling_terminal(42, 42, pts3, table));
14480        assert!(may_have_acquired_controlling_terminal(
14481            42, 42, pts300, table
14482        ));
14483        assert!(!may_have_acquired_controlling_terminal(43, 42, pts3, table));
14484        // Serial lines, virtual consoles and /dev/tty can become controlling;
14485        // /dev/console, /dev/ptmx, /dev/vc/0, pseudoterminal masters, minors
14486        // outside every range and devices that are not terminals cannot.
14487        for (major, minor) in [(4, 64), (4, 95), (166, 7), (4, 1), (4, 63), (5, 0)] {
14488            let rdev = libc::makedev(major, minor);
14489            assert!(
14490                terminal_can_become_controlling(rdev, table),
14491                "{major}:{minor}"
14492            );
14493        }
14494        for (major, minor) in [(5, 1), (5, 2), (4, 0), (128, 3), (4, 96), (188, 0), (1, 3)] {
14495            let rdev = libc::makedev(major, minor);
14496            assert!(
14497                !terminal_can_become_controlling(rdev, table),
14498                "{major}:{minor}"
14499            );
14500        }
14501        // A table that cannot be read answers true, except for the devices
14502        // Linux never makes controlling. A line that does not parse answers
14503        // true, unless another line names the device.
14504        let null = libc::makedev(1, 3);
14505        assert!(terminal_can_become_controlling(pts3, None));
14506        assert!(terminal_can_become_controlling(null, None));
14507        assert!(!terminal_can_become_controlling(libc::makedev(5, 1), None));
14508        let garbled = Some("pty_slave /dev/pts 136 0-1048575 pty:slave\nnot a driver line\n");
14509        assert!(terminal_can_become_controlling(null, garbled));
14510        assert!(terminal_can_become_controlling(pts3, garbled));
14511        let master = Some("pty_master /dev/ptm 128 0-1048575 pty:master\nnot a driver line\n");
14512        assert!(!terminal_can_become_controlling(
14513            libc::makedev(128, 3),
14514            master
14515        ));
14516    }
14517
14518    /// A session leader that opens a pseudoterminal's slave without O_NOCTTY
14519    /// gains it as its controlling terminal. Closing the master then hangs the
14520    /// slave up, which clears the controlling terminal procfs lists but changes
14521    /// neither the session nor the descriptor's device. A hangup that lands
14522    /// after the `open`, whether before or after the descriptor's stat, must
14523    /// not hide that the `open` may have acquired the terminal
14524    /// (https://github.com/rrnewton/hermit/pull/3361).
14525    #[test]
14526    fn a_hangup_after_the_open_does_not_hide_the_acquired_terminal() {
14527        use std::time::Duration;
14528        use std::time::Instant;
14529
14530        struct Child(libc::pid_t);
14531        impl Drop for Child {
14532            fn drop(&mut self) {
14533                // SAFETY: the pid is this test's own child, not yet reaped.
14534                unsafe {
14535                    libc::kill(self.0, libc::SIGKILL);
14536                    libc::waitpid(self.0, std::ptr::null_mut(), 0);
14537                }
14538            }
14539        }
14540
14541        // SAFETY (every block below): libc calls on descriptors, buffers and
14542        // a child process this test owns.
14543        let flags = libc::O_RDWR | libc::O_NOCTTY | libc::O_CLOEXEC;
14544        let master = unsafe { libc::posix_openpt(flags) };
14545        assert!(
14546            master >= 0,
14547            "posix_openpt: {}",
14548            std::io::Error::last_os_error()
14549        );
14550        assert_eq!(unsafe { libc::grantpt(master) }, 0);
14551        assert_eq!(unsafe { libc::unlockpt(master) }, 0);
14552        let mut slave_path = [0 as libc::c_char; 64];
14553        let path_len = slave_path.len();
14554        assert_eq!(
14555            unsafe { libc::ptsname_r(master, slave_path.as_mut_ptr(), path_len) },
14556            0
14557        );
14558        // `ready` carries the slave's descriptor number to this process;
14559        // nothing writes `release`, so this process's exit ends the child.
14560        let (mut ready, mut release) = ([0; 2], [0; 2]);
14561        assert_eq!(
14562            unsafe { libc::pipe2(ready.as_mut_ptr(), libc::O_CLOEXEC) },
14563            0
14564        );
14565        assert_eq!(
14566            unsafe { libc::pipe2(release.as_mut_ptr(), libc::O_CLOEXEC) },
14567            0
14568        );
14569        let pid = unsafe { libc::fork() };
14570        assert!(pid >= 0, "fork: {}", std::io::Error::last_os_error());
14571        if pid == 0 {
14572            // The child makes only async-signal-safe calls and allocates
14573            // nothing, so forking from a test harness thread is safe.
14574            unsafe {
14575                libc::alarm(60);
14576                libc::signal(libc::SIGHUP, libc::SIG_IGN);
14577                libc::close(master);
14578                libc::close(ready[0]);
14579                libc::close(release[1]);
14580                if libc::setsid() < 0 {
14581                    libc::_exit(2);
14582                }
14583                let slave = libc::open(slave_path.as_ptr(), libc::O_RDWR);
14584                if slave < 0 {
14585                    libc::_exit(3);
14586                }
14587                let bytes = slave.to_ne_bytes();
14588                if libc::write(ready[1], bytes.as_ptr().cast(), bytes.len()) != 4 {
14589                    libc::_exit(4);
14590                }
14591                let mut byte = [0_u8; 1];
14592                libc::read(release[0], byte.as_mut_ptr().cast(), 1);
14593                libc::_exit(0);
14594            }
14595        }
14596        let child = Child(pid);
14597        unsafe {
14598            libc::close(ready[1]);
14599            libc::close(release[0]);
14600        }
14601        let mut bytes = [0_u8; 4];
14602        let got = unsafe { libc::read(ready[0], bytes.as_mut_ptr().cast(), bytes.len()) };
14603        assert_eq!(got, 4, "the child did not open the slave");
14604        let slave = i32::from_ne_bytes(bytes);
14605        // The descriptor's stat, read before the hangup, as `handle_openat`
14606        // reads it before it classifies the open.
14607        let link = std::ffi::CString::new(format!("/proc/{pid}/fd/{slave}")).unwrap();
14608        let mut host_stat: libc::stat = unsafe { std::mem::zeroed() };
14609        assert_eq!(unsafe { libc::stat(link.as_ptr(), &mut host_stat) }, 0);
14610        let terminal = (
14611            libc::major(host_stat.st_rdev) as i32,
14612            libc::minor(host_stat.st_rdev) as i32,
14613        );
14614        let process = procfs::process::Process::new(pid).unwrap();
14615        let before = process.stat().unwrap();
14616        assert_eq!(
14617            (before.session, before.tty_nr()),
14618            (pid, terminal),
14619            "the child's open did not acquire the terminal"
14620        );
14621        assert!(opened_controlling_terminal(pid, slave, Some(&host_stat)));
14622        // Hang the slave up: Linux clears the session's controlling terminal.
14623        assert_eq!(unsafe { libc::close(master) }, 0);
14624        let deadline = Instant::now() + Duration::from_secs(10);
14625        while process.stat().unwrap().tty_nr() != (0, 0) {
14626            assert!(
14627                Instant::now() < deadline,
14628                "the hangup did not clear the controlling terminal"
14629            );
14630            std::thread::sleep(Duration::from_millis(10));
14631        }
14632        assert_eq!(process.stat().unwrap().session, pid);
14633        assert!(
14634            opened_controlling_terminal(pid, slave, Some(&host_stat)),
14635            "a hangup after the descriptor's stat hid the acquisition"
14636        );
14637        assert!(
14638            opened_controlling_terminal(pid, slave, None),
14639            "a hangup before the descriptor's stat hid the acquisition"
14640        );
14641        drop(child);
14642    }
14643
14644    /// The ceiling is inclusive. A guest that reads the advertised
14645    /// `pipe-max-size` and asks for exactly that must be allowed to have it;
14646    /// refusing at the boundary would advertise a size that cannot be set.
14647    #[test]
14648    fn the_pipe_ceiling_admits_exactly_the_pinned_capacity() {
14649        assert!(!pipe_capacity_request_exceeds_ceiling(
14650            DETERMINISTIC_PIPE_CAPACITY_BYTES
14651        ));
14652        assert!(!pipe_capacity_request_exceeds_ceiling(
14653            DETERMINISTIC_PIPE_CAPACITY_BYTES - 1
14654        ));
14655        assert!(pipe_capacity_request_exceeds_ceiling(
14656            DETERMINISTIC_PIPE_CAPACITY_BYTES + 1
14657        ));
14658    }
14659
14660    /// A host pipe's capacity above the ceiling reads as the ceiling, so a
14661    /// default 64-KiB pipe and one the host shrank to two pages under
14662    /// `pipe-user-pages-soft` read the same. A capacity at or below the ceiling
14663    /// (Hermit's pin, or a guest's own shrink) reads as it is.
14664    #[test]
14665    fn a_host_pipe_capacity_reads_no_larger_than_the_ceiling() {
14666        let ceiling = i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES);
14667        assert_eq!(super::reported_pipe_capacity(65536), ceiling);
14668        assert_eq!(super::reported_pipe_capacity(1 << 20), ceiling);
14669        assert_eq!(super::reported_pipe_capacity(ceiling), ceiling);
14670        assert_eq!(super::reported_pipe_capacity(4096), 4096);
14671    }
14672
14673    /// Shrinking stays legal. `tests/c/pipe_capacity.c`
14674    /// shrinks to one page and requires the value to round-trip, so a blanket
14675    /// clamp to the pinned capacity would break a guest-visible contract this
14676    /// repository already locked.
14677    #[test]
14678    fn shrinking_is_never_refused_by_the_ceiling() {
14679        for requested in [1, 4096, DETERMINISTIC_PIPE_CAPACITY_BYTES / 2] {
14680            assert!(
14681                !pipe_capacity_request_exceeds_ceiling(requested),
14682                "shrink to {requested} must remain permitted"
14683            );
14684        }
14685    }
14686
14687    /// The host's own ceiling is the value this change exists to stop
14688    /// consulting: 1048576 on a default host, 65536 on a hardened one. Both are
14689    /// refused now, so the guest-visible answer no longer depends on which host
14690    /// it is.
14691    #[test]
14692    fn host_ceilings_are_refused_identically_on_any_host() {
14693        for host_ceiling in [65536, 1048576] {
14694            assert!(
14695                pipe_capacity_request_exceeds_ceiling(host_ceiling),
14696                "{host_ceiling} must be refused regardless of the host sysctl"
14697            );
14698        }
14699    }
14700
14701    use super::Errno;
14702    use super::TimerSlackBinding;
14703    use super::UNIX_AUTOBIND_NAME_LEN;
14704    use super::canonicalize_tcp_info;
14705    use super::classify_timer_slack_binding;
14706    use super::is_inherited_container_output;
14707    use super::parse_timer_slack_write;
14708    use super::pipe_capacity_failure;
14709    use super::random_device_lseek_result;
14710    use super::should_tag_host_timed_internal_pipe_io;
14711    use super::unix_autobind_address;
14712    use super::unix_autobind_addrlen;
14713    use super::vectored_offset;
14714    use crate::fd::FdType;
14715    use crate::resources::Device;
14716    use crate::resources::ResourceID;
14717
14718    /// This is an assumption we're making about flags.  Probably these flags can never be
14719    /// changed, but let's check just in case.
14720    #[test]
14721    fn linux_flags_assumptions() {
14722        assert_eq!(libc::SOCK_NONBLOCK, OFlag::O_NONBLOCK.bits());
14723        assert_eq!(libc::SOCK_CLOEXEC, OFlag::O_CLOEXEC.bits());
14724    }
14725
14726    #[test]
14727    fn pipe_capacity_failure_classifies_the_errno() {
14728        let created = [17, 18];
14729
14730        // The only success shape: Linux applied EXACTLY the capacity we asked for.
14731        assert_eq!(
14732            pipe_capacity_failure(created, Ok(i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES))),
14733            None
14734        );
14735
14736        // Successful-but-wrong capacity is a pipe whose size we did not choose. That is not a
14737        // kernel errno, so it is reported as EIO rather than dressed up as one.
14738        let mismatch = pipe_capacity_failure(
14739            created,
14740            Ok(i64::from(DETERMINISTIC_PIPE_CAPACITY_BYTES) * 2),
14741        )
14742        .expect("a capacity Linux rounded away from the pin must not read as success");
14743        assert_eq!(mismatch.created_fds, created);
14744        assert_eq!(mismatch.error, Errno::EIO);
14745
14746        // A real kernel errno is preserved rather than rewritten.
14747        let denied = pipe_capacity_failure(created, Err(Errno::EPERM))
14748            .expect("a kernel refusal must not read as success");
14749        assert_eq!(denied.created_fds, created);
14750        assert_eq!(denied.error, Errno::EPERM);
14751
14752        // The descriptors are carried through every failure shape, because they are what the
14753        // caller has to close; losing them here is how they would leak.
14754        assert_eq!(denied.created_fds, created);
14755    }
14756
14757    #[test]
14758    fn pipe_capacity_failure_closes_both_created_descriptors() {
14759        let mut created = [-1; 2];
14760        assert_eq!(
14761            unsafe { libc::pipe2(created.as_mut_ptr(), libc::O_CLOEXEC) },
14762            0
14763        );
14764
14765        let pin_result = unsafe { libc::fcntl(created[0], libc::F_SETPIPE_SZ, -1) };
14766        assert_eq!(pin_result, -1);
14767        let pin_error = Errno::last();
14768        // Pin the errno, not just the failure. Without this the test asserts only that
14769        // `fcntl` returned -1, so it would still pass if the call failed for a reason we
14770        // did not engineer -- an invalid `created[0]` fails EBADF, every assertion below
14771        // still holds, and the capacity-pin path is never exercised at all.
14772        //
14773        // EINVAL is structural here, not a property of this host. `fcntl`'s argument is an
14774        // `unsigned long`, so -1 arrives as ULONG_MAX; `round_pipe_size` returns 0 for any
14775        // size above 2^31, and `pipe_set_size` maps that 0 to -EINVAL BEFORE it consults
14776        // `CAP_SYS_RESOURCE`. So the result does not depend on privilege or on
14777        // `/proc/sys/fs/pipe-max-size`.
14778        assert_eq!(pin_error, Errno::EINVAL);
14779
14780        let failure = pipe_capacity_failure(created, Err(pin_error))
14781            .expect("the forced capacity-pin failure must enter the cleanup path");
14782        for close in failure.close_syscalls() {
14783            assert_eq!(unsafe { libc::close(close.fd()) }, 0);
14784        }
14785
14786        for fd in created {
14787            assert_eq!(unsafe { libc::fcntl(fd, libc::F_GETFD) }, -1);
14788            assert_eq!(Errno::last(), Errno::EBADF);
14789        }
14790    }
14791
14792    #[test]
14793    fn sabre_pipe_marker_requires_nonblockize_retry_semantics() {
14794        assert!(should_tag_host_timed_internal_pipe_io(
14795            true,
14796            FdType::Pipe,
14797            true,
14798            false
14799        ));
14800        assert!(!should_tag_host_timed_internal_pipe_io(
14801            true,
14802            FdType::Pipe,
14803            true,
14804            true
14805        ));
14806        assert!(!should_tag_host_timed_internal_pipe_io(
14807            true,
14808            FdType::Pipe,
14809            false,
14810            false
14811        ));
14812        assert!(!should_tag_host_timed_internal_pipe_io(
14813            false,
14814            FdType::Pipe,
14815            true,
14816            false
14817        ));
14818        assert!(!should_tag_host_timed_internal_pipe_io(
14819            true,
14820            FdType::Regular,
14821            true,
14822            false
14823        ));
14824    }
14825
14826    #[test]
14827    fn random_device_lseek_matches_linux_noop_llseek() {
14828        for whence in [
14829            Whence::SEEK_SET,
14830            Whence::SEEK_CUR,
14831            Whence::SEEK_END,
14832            Whence::SEEK_DATA,
14833            Whence::SEEK_HOLE,
14834        ] {
14835            for status_flags in [
14836                OFlag::empty().bits(),
14837                OFlag::O_WRONLY.bits(),
14838                OFlag::O_RDWR.bits(),
14839            ] {
14840                assert_eq!(random_device_lseek_result(status_flags, whence), Ok(0));
14841            }
14842            assert_eq!(
14843                random_device_lseek_result(OFlag::O_PATH.bits(), whence),
14844                Err(Errno::EBADF)
14845            );
14846        }
14847        assert_eq!(
14848            random_device_lseek_result(OFlag::empty().bits(), Whence::from_raw(99)),
14849            Err(Errno::EINVAL)
14850        );
14851        assert_eq!(
14852            random_device_lseek_result(OFlag::O_PATH.bits(), Whence::from_raw(99)),
14853            Err(Errno::EBADF)
14854        );
14855    }
14856
14857    #[test]
14858    fn timer_slack_write_parser_matches_decimal_procfs_contract() {
14859        assert_eq!(parse_timer_slack_write(b"0"), Ok(0));
14860        assert_eq!(parse_timer_slack_write(b"+123\n"), Ok(123));
14861        assert_eq!(parse_timer_slack_write(b"456\0ignored"), Ok(456));
14862        assert_eq!(
14863            parse_timer_slack_write(u64::MAX.to_string().as_bytes()),
14864            Ok(u64::MAX)
14865        );
14866
14867        for invalid in [b"".as_slice(), b"+", b"-1", b" 1", b"1 ", b"1\n2", b"0x10"] {
14868            assert_eq!(parse_timer_slack_write(invalid), Err(Errno::EINVAL));
14869        }
14870        assert_eq!(
14871            parse_timer_slack_write(b"18446744073709551616"),
14872            Err(Errno::ERANGE)
14873        );
14874    }
14875
14876    #[test]
14877    fn timer_slack_vectored_offset_preserves_minus_one_sentinel() {
14878        assert_eq!(vectored_offset(u64::MAX, u64::MAX), -1);
14879        assert_eq!(vectored_offset(0, 0), 0);
14880        assert_eq!(vectored_offset(7, 0), 7);
14881    }
14882
14883    #[test]
14884    fn timer_slack_binding_rejects_exit_reuse_and_other_tasks() {
14885        let binding = TimerSlackBinding {
14886            target: 202,
14887            device: 11,
14888            inode: 22,
14889        };
14890        assert_eq!(
14891            classify_timer_slack_binding(binding, Some((11, 22)), 202),
14892            Ok(())
14893        );
14894        assert_eq!(
14895            classify_timer_slack_binding(binding, Some((11, 22)), 303),
14896            Err(Errno::EPERM)
14897        );
14898        assert_eq!(
14899            classify_timer_slack_binding(binding, None, 202),
14900            Err(Errno::ESRCH)
14901        );
14902        assert_eq!(
14903            classify_timer_slack_binding(binding, Some((11, 23)), 202),
14904            Err(Errno::ESRCH),
14905            "a recycled numeric TID must not revive an old proc inode"
14906        );
14907    }
14908
14909    #[test]
14910    fn only_inherited_container_output_is_nonseekable() {
14911        assert!(is_inherited_container_output(Some(ResourceID::Device(
14912            Device::ContainerStdout
14913        ))));
14914        assert!(is_inherited_container_output(Some(ResourceID::Device(
14915            Device::ContainerStderr
14916        ))));
14917        assert!(!is_inherited_container_output(Some(ResourceID::Device(
14918            Device::ContainerStdin
14919        ))));
14920        assert!(!is_inherited_container_output(None));
14921    }
14922
14923    #[test]
14924    fn unix_autobind_address_matches_linux_shape() {
14925        let address = unix_autobind_address(0x2af);
14926        assert_eq!(address.sun_family, libc::AF_UNIX as libc::sa_family_t);
14927        assert_eq!(address.sun_path[0], 0);
14928        let name = address.sun_path[1..UNIX_AUTOBIND_NAME_LEN]
14929            .iter()
14930            .map(|byte| *byte as u8)
14931            .collect::<Vec<_>>();
14932        assert_eq!(name, b"002af");
14933        assert_eq!(
14934            unix_autobind_addrlen() as usize,
14935            std::mem::offset_of!(libc::sockaddr_un, sun_path) + UNIX_AUTOBIND_NAME_LEN
14936        );
14937    }
14938
14939    #[test]
14940    fn tcp_info_retains_only_logical_connection_header() {
14941        let mut info = [0xff; 16];
14942        canonicalize_tcp_info(&mut info);
14943
14944        for (offset, byte) in info.into_iter().enumerate() {
14945            let expected = if matches!(offset, 0 | 1 | 5 | 6) {
14946                0xff
14947            } else {
14948                0
14949            };
14950            assert_eq!(byte, expected, "unexpected byte at offset {offset}");
14951        }
14952
14953        for len in 0..8 {
14954            canonicalize_tcp_info(&mut [0xff; 8][..len]);
14955        }
14956    }
14957
14958    /// Records with the names `names`, as `serve_next_batch` encodes them
14959    /// from position 0, and the length of each name.
14960    fn directory_records(format: super::DirentFormat, names: &[&[u8]]) -> (Vec<u8>, Vec<usize>) {
14961        let mut records = Vec::new();
14962        for (index, name) in names.iter().enumerate() {
14963            let entry = super::DirEntry {
14964                name: name.to_vec(),
14965                ino: 0x1111_1111_1111_1111,
14966                off: 0,
14967                ty: 4,
14968            };
14969            format.encode(&entry, entry.ino, index as i64 + 1, &mut records);
14970        }
14971        (records, names.iter().map(|name| name.len()).collect())
14972    }
14973
14974    /// `records` as Linux leaves them in a buffer that held `Pages::FILL`:
14975    /// the padding after each name is not written.
14976    fn as_linux_writes(format: super::DirentFormat, records: &[u8], names: &[usize]) -> Vec<u8> {
14977        let mut bytes = records.to_vec();
14978        let mut at = 0;
14979        for &name_len in names {
14980            let reclen = format.record_len(name_len);
14981            let padding = at + format.name_offset() + name_len + 1;
14982            let end = match format {
14983                super::DirentFormat::Dirent64 => at + reclen,
14984                super::DirentFormat::Legacy => at + reclen - 1,
14985            };
14986            bytes[padding..end].fill(Pages::FILL);
14987            at += reclen;
14988        }
14989        bytes
14990    }
14991
14992    const FORMATS: [super::DirentFormat; 2] =
14993        [super::DirentFormat::Dirent64, super::DirentFormat::Legacy];
14994
14995    const TEN: [&[u8]; 10] = [b"a", b"b", b"c", b"d", b"e", b"f", b"g", b"h", b"i", b"j"];
14996
14997    /// A buffer starting 16 bytes before a writable page, in a page the guest
14998    /// cannot write: Linux's first store, to the first record's `d_off`,
14999    /// fails, so the call fails and the writable page is left as it was.
15000    #[test]
15001    fn a_first_record_that_cannot_be_written_leaves_the_next_page_untouched() {
15002        for protection in [libc::PROT_NONE, libc::PROT_READ] {
15003            for format in FORMATS {
15004                let pages = Pages::new(&[protection, libc::PROT_READ | libc::PROT_WRITE]);
15005                let (records, names) = directory_records(format, &TEN);
15006                let copied = super::copy_records(
15007                    &mut LocalMemory::new(),
15008                    pages.address(PAGE - 16),
15009                    format,
15010                    &records,
15011                    &names,
15012                    0,
15013                );
15014                assert_eq!(copied, (0, Err(Errno::EFAULT)), "{format:?} {protection}");
15015                assert!(
15016                    pages.contents().iter().all(|&byte| byte == Pages::FILL),
15017                    "{format:?} after a page with protection {protection}: bytes changed"
15018                );
15019            }
15020        }
15021    }
15022
15023    /// Guest memory whose every vectored copy fails with one error that is
15024    /// not a fault, as when the guest's thread is gone or the backend fails.
15025    struct FailingMemory(Errno);
15026
15027    impl reverie::syscalls::MemoryAccess for FailingMemory {
15028        fn read_vectored(
15029            &self,
15030            _: &[std::io::IoSlice],
15031            _: &mut [std::io::IoSliceMut],
15032        ) -> Result<usize, Errno> {
15033            Err(self.0)
15034        }
15035
15036        fn write_vectored(
15037            &mut self,
15038            _: &[std::io::IoSlice],
15039            _: &mut [std::io::IoSliceMut],
15040        ) -> Result<usize, Errno> {
15041            Err(self.0)
15042        }
15043    }
15044
15045    /// Only a fault ends a copy of directory records short. Any other error
15046    /// of the copy is the call's error, as it was before directory streams,
15047    /// and not `EFAULT`: reading the records back, copying them out (through
15048    /// a buffer whose first store crosses a page, and through one where none
15049    /// does), and reading the prefix the `getdents64` observer hashes.
15050    #[test]
15051    fn a_copy_error_other_than_a_fault_is_returned() {
15052        let buf = |offset| reverie::syscalls::AddrMut::<u8>::from_raw(16 * PAGE + offset).unwrap();
15053        for errno in [Errno::ESRCH, Errno::EIO] {
15054            let mut bytes = [0; 32];
15055            assert_eq!(
15056                super::read_guest_prefix(&FailingMemory(errno), buf(0), &mut bytes),
15057                Err(errno)
15058            );
15059            for format in FORMATS {
15060                let (records, names) = directory_records(format, &TEN);
15061                for offset in [0, PAGE - 4] {
15062                    let copied = super::copy_records(
15063                        &mut FailingMemory(errno),
15064                        buf(offset),
15065                        format,
15066                        &records,
15067                        &names,
15068                        0,
15069                    );
15070                    assert_eq!(copied, (0, Err(errno)), "{format:?} at {offset}");
15071                }
15072                let read =
15073                    super::read_records(&FailingMemory(errno), buf(0), records.len(), format);
15074                assert_eq!(read.err(), Some(errno), "{format:?}");
15075            }
15076        }
15077    }
15078
15079    /// A vectored copy that fails with `EFAULT`, which `process_vm_readv` and
15080    /// the KVM backend both return when the first byte is out of the guest's
15081    /// reach, copied nothing rather than failing: the caller decides what an
15082    /// empty copy means, as it does for a short one.
15083    #[test]
15084    fn a_fault_of_the_whole_copy_copies_nothing() {
15085        let buf = reverie::syscalls::AddrMut::<u8>::from_raw(16 * PAGE).unwrap();
15086        let mut bytes = [0; 32];
15087        assert_eq!(
15088            super::read_guest_prefix(&FailingMemory(Errno::EFAULT), buf, &mut bytes),
15089            Ok(0)
15090        );
15091        assert_eq!(
15092            super::write_guest_pieces(&mut FailingMemory(Errno::EFAULT), buf, &[(0, &bytes)]),
15093            Ok(0)
15094        );
15095    }
15096
15097    /// A buffer starting 8 bytes before a writable page, in a page the guest
15098    /// cannot write. Linux's first store, the first record's position into
15099    /// its own `d_off`, lands in the writable page; its next, `d_ino`, fails.
15100    /// The call fails and leaves the position there.
15101    #[test]
15102    fn a_first_record_leaves_its_position_in_its_d_off() {
15103        for format in FORMATS {
15104            let pages = Pages::new(&[libc::PROT_READ, libc::PROT_READ | libc::PROT_WRITE]);
15105            let (records, names) = directory_records(format, &TEN);
15106            let copied = super::copy_records(
15107                &mut LocalMemory::new(),
15108                pages.address(PAGE - 8),
15109                format,
15110                &records,
15111                &names,
15112                7,
15113            );
15114            assert_eq!(copied, (0, Err(Errno::EFAULT)), "{format:?}");
15115            let contents = pages.contents();
15116            assert_eq!(&contents[PAGE..PAGE + 8], &7i64.to_ne_bytes(), "{format:?}");
15117            assert!(
15118                contents[..PAGE]
15119                    .iter()
15120                    .chain(&contents[PAGE + 8..])
15121                    .all(|&byte| byte == Pages::FILL),
15122                "{format:?}: bytes other than the first d_off changed"
15123            );
15124        }
15125    }
15126
15127    /// A buffer starting 12 bytes before a writable page, in a page the guest
15128    /// can read but not write. The first record's `d_off` crosses into the
15129    /// writable page, and the CPU stores it at once, so Linux writes none of
15130    /// it: the part written in the writable page is put back.
15131    #[test]
15132    fn a_store_crossing_out_of_an_unwritable_page_writes_nothing() {
15133        for format in FORMATS {
15134            let pages = Pages::new(&[libc::PROT_READ, libc::PROT_READ | libc::PROT_WRITE]);
15135            let (records, names) = directory_records(format, &TEN);
15136            let copied = super::copy_records(
15137                &mut LocalMemory::new(),
15138                pages.address(PAGE - 12),
15139                format,
15140                &records,
15141                &names,
15142                0,
15143            );
15144            assert_eq!(copied, (0, Err(Errno::EFAULT)), "{format:?}");
15145            assert!(
15146                pages.contents().iter().all(|&byte| byte == Pages::FILL),
15147                "{format:?}: bytes changed"
15148            );
15149        }
15150    }
15151
15152    /// The same store between two pages one of which the guest cannot write,
15153    /// for each other pair Detcore can leave as Linux does: one page it can
15154    /// read, or a write-only page before one it cannot touch. Whichever part
15155    /// is written first must be one Detcore can put back.
15156    #[test]
15157    fn a_store_crossing_pages_is_put_back_from_the_page_that_can_be_read() {
15158        let (none, read, write) = (libc::PROT_NONE, libc::PROT_READ, libc::PROT_WRITE);
15159        let both = read | write;
15160        for protections in [
15161            [read, write],
15162            [write, read],
15163            [write, none],
15164            [both, none],
15165            [both, read],
15166            [none, both],
15167        ] {
15168            for format in FORMATS {
15169                let pages = Pages::new(&protections);
15170                let (records, names) = directory_records(format, &TEN);
15171                let copied = super::copy_records(
15172                    &mut LocalMemory::new(),
15173                    pages.address(PAGE - 12),
15174                    format,
15175                    &records,
15176                    &names,
15177                    0,
15178                );
15179                assert_eq!(
15180                    copied,
15181                    (0, Err(Errno::EFAULT)),
15182                    "{protections:?} {format:?}"
15183                );
15184                assert!(
15185                    pages.contents().iter().all(|&byte| byte == Pages::FILL),
15186                    "{protections:?} {format:?}: bytes changed"
15187                );
15188            }
15189        }
15190    }
15191
15192    /// Records of 24 bytes starting 100 bytes before a page the guest cannot
15193    /// write. Four fit. The fifth's `d_ino` crosses into that page, so Linux
15194    /// writes none of it: four records are returned, the fifth's position
15195    /// (the fourth's `d_off`) is written, and the four bytes before the page
15196    /// are left as they were.
15197    #[test]
15198    fn a_record_crossing_into_an_inaccessible_page_leaves_nothing_before_it() {
15199        for format in FORMATS {
15200            let pages = Pages::new(&[libc::PROT_READ | libc::PROT_WRITE, libc::PROT_NONE]);
15201            let (records, names) = directory_records(format, &TEN);
15202            let copied = super::copy_records(
15203                &mut LocalMemory::new(),
15204                pages.address(PAGE - 100),
15205                format,
15206                &records,
15207                &names,
15208                0,
15209            );
15210            assert_eq!(copied, (4, Ok(96)), "{format:?}");
15211            let contents = pages.contents();
15212            assert_eq!(
15213                &contents[PAGE - 100..PAGE - 4],
15214                &as_linux_writes(format, &records[..96], &names[..4])[..],
15215                "{format:?}"
15216            );
15217            assert!(
15218                contents[..PAGE - 100]
15219                    .iter()
15220                    .chain(&contents[PAGE - 4..])
15221                    .all(|&byte| byte == Pages::FILL),
15222                "{format:?}: bytes outside the records copied changed"
15223            );
15224        }
15225    }
15226
15227    /// A read of a procfs file whose buffer faults two bytes in: a
15228    /// `seq_file` returns the two bytes, a sysctl fails with `EFAULT`, as
15229    /// measured on Linux 7.1; a file that fits copies whole either way.
15230    #[test]
15231    fn a_torn_procfs_read_is_partial_for_a_seq_file_and_a_fault_for_a_sysctl() {
15232        let pages = Pages::new(&[libc::PROT_READ | libc::PROT_WRITE, libc::PROT_NONE]);
15233        let edge = || Some(pages.address(PAGE - 2));
15234        let read = |bytes: &[u8], sysctl| {
15235            super::copy_procfs_read(&mut LocalMemory::new(), edge(), bytes, sysctl)
15236                .map_err(|error| error.into_errno().unwrap())
15237        };
15238        assert_eq!(read(b"Linux version\n", false), Ok(2));
15239        assert_eq!(
15240            read(b"65530\n", true),
15241            Err(reverie::syscalls::Errno::EFAULT)
15242        );
15243        assert_eq!(read(b"0\n", true), Ok(2));
15244        assert_eq!(read(b"", true), Ok(0));
15245    }
15246
15247    /// A procfs read is EBADF unless the descriptor was opened for reading.
15248    #[test]
15249    fn only_a_descriptor_opened_for_reading_reads_procfs() {
15250        assert!(super::can_read(libc::O_RDONLY));
15251        assert!(super::can_read(libc::O_RDWR | libc::O_CLOEXEC));
15252        assert!(!super::can_read(libc::O_WRONLY));
15253        assert!(!super::can_read(libc::O_ACCMODE));
15254        assert!(!super::can_read(libc::O_PATH));
15255    }
15256
15257    /// `kiocb_set_rw_flags` for a procfs file, in Linux 7.1's order.
15258    #[test]
15259    fn procfs_vector_flags_are_refused_in_linux_order() {
15260        use reverie::syscalls::Errno;
15261        const NOSIGNAL: i32 = 0x100;
15262        const UNKNOWN: i32 = 0x200;
15263        for accepted in [
15264            0,
15265            libc::RWF_HIPRI,
15266            libc::RWF_DSYNC,
15267            libc::RWF_SYNC,
15268            libc::RWF_APPEND,
15269            libc::RWF_NOAPPEND,
15270            NOSIGNAL,
15271        ] {
15272            assert_eq!(super::validate_procfs_vector_flags(accepted, true), Ok(()));
15273        }
15274        for (flags, errno) in [
15275            (libc::RWF_NOWAIT, Errno::EOPNOTSUPP),
15276            (libc::RWF_ATOMIC, Errno::EOPNOTSUPP),
15277            (libc::RWF_DONTCACHE, Errno::EOPNOTSUPP),
15278            (UNKNOWN, Errno::EOPNOTSUPP),
15279            (libc::RWF_APPEND | libc::RWF_NOAPPEND, Errno::EINVAL),
15280            (libc::RWF_NOWAIT | UNKNOWN, Errno::EOPNOTSUPP),
15281            (
15282                libc::RWF_APPEND | libc::RWF_NOAPPEND | UNKNOWN,
15283                Errno::EOPNOTSUPP,
15284            ),
15285            (
15286                libc::RWF_ATOMIC | libc::RWF_APPEND | libc::RWF_NOAPPEND,
15287                Errno::EINVAL,
15288            ),
15289            (
15290                libc::RWF_NOWAIT | libc::RWF_APPEND | libc::RWF_NOAPPEND,
15291                Errno::EINVAL,
15292            ),
15293        ] {
15294            assert_eq!(
15295                super::validate_procfs_vector_flags(flags, true),
15296                Err(errno),
15297                "{flags:#x}"
15298            );
15299        }
15300        // A file without `read_iter` (`/proc/modules`, `/proc/swaps`) takes
15301        // `RWF_HIPRI` alone, and refuses even the conflicting pair with
15302        // EOPNOTSUPP.
15303        assert_eq!(
15304            super::validate_procfs_vector_flags(libc::RWF_HIPRI, false),
15305            Ok(())
15306        );
15307        for flags in [
15308            libc::RWF_DSYNC,
15309            libc::RWF_APPEND,
15310            NOSIGNAL,
15311            libc::RWF_APPEND | libc::RWF_NOAPPEND,
15312        ] {
15313            assert_eq!(
15314                super::validate_procfs_vector_flags(flags, false),
15315                Err(Errno::EOPNOTSUPP),
15316                "{flags:#x}"
15317            );
15318        }
15319    }
15320
15321    /// A buffer starting 4 bytes before a page the guest cannot write, in a
15322    /// page it can write but not read. Linux first writes the first record's
15323    /// `d_off`, 8 bytes in, which fails; it never writes the 4 bytes before
15324    /// the page.
15325    #[test]
15326    fn a_first_record_is_written_from_its_d_off() {
15327        for format in FORMATS {
15328            let pages = Pages::new(&[libc::PROT_WRITE, libc::PROT_NONE]);
15329            let (records, names) = directory_records(format, &TEN);
15330            let copied = super::copy_records(
15331                &mut LocalMemory::new(),
15332                pages.address(PAGE - 4),
15333                format,
15334                &records,
15335                &names,
15336                0,
15337            );
15338            assert_eq!(copied, (0, Err(Errno::EFAULT)), "{format:?}");
15339            assert!(
15340                pages.contents().iter().all(|&byte| byte == Pages::FILL),
15341                "{format:?}: bytes before the inaccessible page changed"
15342            );
15343        }
15344    }
15345
15346    /// Records across two writable pages and into a third the guest cannot
15347    /// write, starting 40 bytes before the second page, so the third starts
15348    /// 4136 bytes in. Record 172 starts at 4128: Linux stores its position
15349    /// into record 171's `d_off` and its `d_ino`, which ends at the third
15350    /// page, and then fails at its `d_reclen`. The call returns 172 records
15351    /// and leaves that `d_ino` written.
15352    #[test]
15353    fn a_record_not_copied_is_left_as_linux_leaves_it() {
15354        let names: Vec<[u8; 1]> = (0..200u8).map(|i| [b'a' + i % 26]).collect();
15355        let names: Vec<&[u8]> = names.iter().map(|name| &name[..]).collect();
15356        for format in FORMATS {
15357            let rw = libc::PROT_READ | libc::PROT_WRITE;
15358            let pages = Pages::new(&[rw, rw, libc::PROT_NONE]);
15359            let start = PAGE - 40;
15360            let (records, lens) = directory_records(format, &names);
15361            let copied = super::copy_records(
15362                &mut LocalMemory::new(),
15363                pages.address(start),
15364                format,
15365                &records,
15366                &lens,
15367                0,
15368            );
15369            assert_eq!(copied, (172, Ok(172 * 24)), "{format:?}");
15370            let contents = pages.contents();
15371            let mut expected = as_linux_writes(format, &records[..4128], &lens[..172]);
15372            expected.extend_from_slice(&records[4128..4136]);
15373            assert_eq!(&contents[start..start + 4136], &expected[..], "{format:?}");
15374            assert!(
15375                contents[..start]
15376                    .iter()
15377                    .chain(&contents[start + 4136..])
15378                    .all(|&byte| byte == Pages::FILL),
15379                "{format:?}: bytes outside what Linux writes changed"
15380            );
15381        }
15382    }
15383
15384    /// A second record with a 20-byte name, whose record ends past the end of
15385    /// what the guest can write. For `getdents64`, the NUL after the name is
15386    /// stored before the name and fails, so none of the name is written; for
15387    /// `getdents`, `d_type`, at the record's end, is stored before the name
15388    /// and fails. Either way the record's own `d_off` is not written: Linux
15389    /// stores it only with the next record or at the end of the call.
15390    #[test]
15391    fn a_name_is_stored_after_the_bytes_that_follow_it() {
15392        for format in FORMATS {
15393            let pages = Pages::new(&[libc::PROT_READ | libc::PROT_WRITE, libc::PROT_NONE]);
15394            let (records, names) = directory_records(format, &[b"a", b"abcdefghijklmnopqrst"]);
15395            let copied = super::copy_records(
15396                &mut LocalMemory::new(),
15397                pages.address(PAGE - 50),
15398                format,
15399                &records,
15400                &names,
15401                0,
15402            );
15403            assert_eq!(copied, (1, Ok(24)), "{format:?}");
15404            let contents = &pages.contents()[PAGE - 50..PAGE];
15405            let mut expected = as_linux_writes(format, &records[..24], &names[..1]);
15406            expected.extend_from_slice(&records[24..32]);
15407            expected.extend_from_slice(&[Pages::FILL; 8]);
15408            expected.extend_from_slice(&records[40..42]);
15409            match format {
15410                super::DirentFormat::Dirent64 => expected.push(records[42]),
15411                super::DirentFormat::Legacy => expected.push(Pages::FILL),
15412            }
15413            expected.resize(50, Pages::FILL);
15414            assert_eq!(contents, &expected[..], "{format:?}");
15415        }
15416    }
15417
15418    /// Records that all fit are all copied, apart from the padding after each
15419    /// name, which Linux does not write, and the bytes after them are left as
15420    /// they were.
15421    #[test]
15422    fn records_that_fit_are_copied_whole() {
15423        for format in FORMATS {
15424            let rw = libc::PROT_READ | libc::PROT_WRITE;
15425            let pages = Pages::new(&[rw, rw]);
15426            let (records, names) = directory_records(format, &TEN);
15427            let copied = super::copy_records(
15428                &mut LocalMemory::new(),
15429                pages.address(PAGE - 50),
15430                format,
15431                &records,
15432                &names,
15433                0,
15434            );
15435            assert_eq!(copied, (10, Ok(240)), "{format:?}");
15436            let contents = pages.contents();
15437            assert_eq!(
15438                &contents[PAGE - 50..PAGE - 50 + records.len()],
15439                &as_linux_writes(format, &records, &names)[..],
15440                "{format:?}"
15441            );
15442            assert!(
15443                contents[..PAGE - 50]
15444                    .iter()
15445                    .chain(&contents[PAGE - 50 + records.len()..])
15446                    .all(|&byte| byte == Pages::FILL),
15447                "{format:?}: bytes outside the records changed"
15448            );
15449        }
15450    }
15451}
15452
15453/// `inject_fstat` and `add_fd` against a scripted guest whose "address space"
15454/// is this test process, so every injected syscall runs for real on host
15455/// memory and a real descriptor. Regression coverage for
15456/// <https://github.com/rrnewton/hermit/issues/3328>; the traced end-to-end case
15457/// is `tests_misc::tight_stack_openat`.
15458#[cfg(test)]
15459mod inject_fstat_scratch {
15460    use std::os::fd::IntoRawFd;
15461    use std::os::fd::RawFd;
15462    use std::os::unix::fs::MetadataExt;
15463    use std::sync::Arc;
15464    use std::sync::atomic::AtomicBool;
15465    use std::sync::atomic::Ordering;
15466
15467    use reverie::GlobalRPC;
15468    use reverie::GlobalTool;
15469    use reverie::Pid;
15470    use reverie::Tool;
15471    use reverie::syscalls::LocalMemory;
15472    use reverie::syscalls::ProtFlags;
15473
15474    use super::*;
15475    use crate::Config;
15476    use crate::GlobalState;
15477    use crate::ThreadState;
15478    use crate::types::DetPid;
15479
15480    /// Room for one `libc::stat`, 8-byte aligned like a real stack slot.
15481    const ARENA_WORDS: usize = 32;
15482
15483    /// A guest stack scratch that is either writable or faults on commit,
15484    /// like the ptrace scratch below an `rsp` with no writable memory under
15485    /// it. The writable arena belongs to the guest and outlives every guard,
15486    /// so an early guard drop is reported by `guard_live` rather than by a
15487    /// write into freed memory.
15488    struct ScriptedStack {
15489        writable: bool,
15490        arena: usize,
15491        capacity: usize,
15492        guard_live: Arc<AtomicBool>,
15493        /// A failing commit first overwrites the scratch's first word, as a
15494        /// commit that faults part way does.
15495        partial: bool,
15496        /// A page that a failing commit makes read-only after its partial
15497        /// write, so the borrower cannot put the bytes back.
15498        protect_on_failure: Option<usize>,
15499    }
15500
15501    struct ScriptedStackGuard {
15502        guard_live: Arc<AtomicBool>,
15503    }
15504
15505    impl Drop for ScriptedStackGuard {
15506        fn drop(&mut self) {
15507            self.guard_live.store(false, Ordering::SeqCst);
15508        }
15509    }
15510
15511    impl reverie::Stack for ScriptedStack {
15512        type StackGuard = ScriptedStackGuard;
15513
15514        fn size(&self) -> usize {
15515            panic!("inject_fstat must not query the scratch size")
15516        }
15517        fn capacity(&self) -> usize {
15518            panic!("inject_fstat must not query the scratch capacity")
15519        }
15520        fn push<'stack, T>(&mut self, _: T) -> Addr<'stack, T> {
15521            panic!("inject_fstat reserves its buffer rather than pushing one")
15522        }
15523        fn reserve<'stack, T>(&mut self) -> AddrMut<'stack, T> {
15524            assert!(std::mem::size_of::<T>() <= self.capacity);
15525            AddrMut::from_raw(self.arena).unwrap()
15526        }
15527        fn commit(self) -> Result<Self::StackGuard, Errno> {
15528            if !self.writable {
15529                if self.partial {
15530                    // SAFETY: the arena (or scratch page) is this guest's,
15531                    // writable until protected below.
15532                    unsafe { (self.arena as *mut u64).write(0) };
15533                }
15534                if let Some(page) = self.protect_on_failure {
15535                    // SAFETY: the page is the test's own mapping.
15536                    assert_eq!(
15537                        unsafe { libc::mprotect(page as *mut _, 4096, libc::PROT_READ) },
15538                        0
15539                    );
15540                }
15541                return Err(Errno::EFAULT);
15542            }
15543            self.guard_live.store(true, Ordering::SeqCst);
15544            Ok(ScriptedStackGuard {
15545                guard_live: self.guard_live,
15546            })
15547        }
15548    }
15549
15550    struct ScriptedGuest {
15551        config: Config,
15552        thread: ThreadState<()>,
15553        stack_writable: bool,
15554        mmap_fails: bool,
15555        arena: Box<[u64; ARENA_WORDS]>,
15556        guard_live: Arc<AtomicBool>,
15557        injected: Vec<Sysno>,
15558        /// Whether a stack guard was live when each fstat was injected.
15559        fstat_guard_live: Vec<bool>,
15560        /// Buffer address of each injected fstat.
15561        fstat_buffers: Vec<usize>,
15562        /// (address, length) of each page the guest mapped.
15563        mapped: Vec<(usize, usize)>,
15564        /// (address, length) of each successful munmap.
15565        unmapped: Vec<(usize, usize)>,
15566        /// Descriptors closed through injection.
15567        closed: Vec<RawFd>,
15568        runtime_fd: Option<RawFd>,
15569        directory_batches: std::collections::VecDeque<Result<Vec<u8>, Errno>>,
15570        /// Scripted refusals of injected opens, in order; an open with none
15571        /// left opens a real file.
15572        open_errors: std::collections::VecDeque<Errno>,
15573        /// The paths of injected opens, as the guest's memory held them.
15574        opened_paths: Vec<Vec<u8>>,
15575        /// The real descriptors injected opens returned.
15576        opened_fds: Vec<RawFd>,
15577        /// Scripted errors of injected closes, in order, before any real
15578        /// close.
15579        close_errors: std::collections::VecDeque<Errno>,
15580        /// Every injected close's descriptor, a scripted failure included.
15581        close_attempts: Vec<RawFd>,
15582        /// The effective set an injected capget reports (the permitted set is
15583        /// every capability).
15584        capget_effective: u64,
15585        /// A page of its own for the stack scratch, in place of the arena.
15586        scratch_page: Option<usize>,
15587        /// A failing commit's partial write, and whether it then makes the
15588        /// scratch page read-only.
15589        commit_partial: bool,
15590        protect_page_on_commit_failure: bool,
15591        /// The injected syscall at which the scratch page becomes read-only,
15592        /// so that putting its bytes back fails.
15593        protect_page_on: Option<Sysno>,
15594        private_memory: Option<reverie::RuntimePrivateMemorySnapshot>,
15595        private_retired: bool,
15596        private_validations: std::sync::atomic::AtomicUsize,
15597        maps_reads: std::collections::VecDeque<Vec<u8>>,
15598    }
15599
15600    impl ScriptedGuest {
15601        fn new(stack_writable: bool, mmap_fails: bool) -> (Detcore, Self) {
15602            let config = Config {
15603                virtualize_metadata: true,
15604                ..Config::default()
15605            };
15606            let pid = DetPid::from_raw(1);
15607            let mut thread = ThreadState::new(pid, &config, ());
15608            thread.detpid = Some(pid);
15609            let tool = <Detcore as Tool>::new(Pid::from_raw(1), &config);
15610            let guest = Self {
15611                config,
15612                thread,
15613                stack_writable,
15614                mmap_fails,
15615                arena: Box::new([u64::MAX; ARENA_WORDS]),
15616                guard_live: Arc::new(AtomicBool::new(false)),
15617                injected: Vec::new(),
15618                fstat_guard_live: Vec::new(),
15619                fstat_buffers: Vec::new(),
15620                mapped: Vec::new(),
15621                unmapped: Vec::new(),
15622                closed: Vec::new(),
15623                runtime_fd: None,
15624                directory_batches: Default::default(),
15625                open_errors: Default::default(),
15626                opened_paths: Vec::new(),
15627                opened_fds: Vec::new(),
15628                close_errors: Default::default(),
15629                close_attempts: Vec::new(),
15630                capget_effective: (1 << 41) - 1,
15631                scratch_page: None,
15632                commit_partial: false,
15633                protect_page_on_commit_failure: false,
15634                protect_page_on: None,
15635                private_memory: None,
15636                private_retired: false,
15637                private_validations: std::sync::atomic::AtomicUsize::new(0),
15638                maps_reads: Default::default(),
15639            };
15640            (tool, guest)
15641        }
15642
15643        /// A guest whose stack scratch is a page of its own, holding a
15644        /// pattern, and whose failure policy returns EOPNOTSUPP rather than
15645        /// stopping (as with --allow-unsupported-syscalls).
15646        fn with_scratch_page(stack_writable: bool) -> (Detcore, Self) {
15647            let (tool, mut guest) = Self::new(stack_writable, false);
15648            guest.config.panic_on_unsupported_syscalls = false;
15649            // SAFETY: a fresh private anonymous page, unmapped by the test.
15650            let page = unsafe {
15651                libc::mmap(
15652                    std::ptr::null_mut(),
15653                    4096,
15654                    libc::PROT_READ | libc::PROT_WRITE,
15655                    libc::MAP_PRIVATE | libc::MAP_ANONYMOUS,
15656                    -1,
15657                    0,
15658                )
15659            };
15660            assert_ne!(page, libc::MAP_FAILED);
15661            // SAFETY: the page is 4096 writable bytes.
15662            unsafe { std::ptr::write_bytes(page as *mut u8, 0xa5, 4096) };
15663            guest.scratch_page = Some(page as usize);
15664            (tool, guest)
15665        }
15666
15667        /// The scratch page's bytes, and the page unmapped.
15668        fn take_scratch_page(&mut self) -> Vec<u8> {
15669            let page = self.scratch_page.take().unwrap();
15670            // SAFETY: the page is the test's mapping, readable throughout.
15671            let bytes = unsafe { std::slice::from_raw_parts(page as *const u8, 4096) }.to_vec();
15672            assert_eq!(unsafe { libc::munmap(page as *mut _, 4096) }, 0);
15673            bytes
15674        }
15675    }
15676
15677    #[reverie::tool]
15678    impl GlobalRPC<GlobalState> for ScriptedGuest {
15679        async fn send_rpc(
15680            &self,
15681            message: <GlobalState as GlobalTool>::Request,
15682        ) -> <GlobalState as GlobalTool>::Response {
15683            panic!("fd registration must not send an RPC: {:?}", message.2)
15684        }
15685        fn config(&self) -> &Config {
15686            &self.config
15687        }
15688    }
15689
15690    #[reverie::tool]
15691    impl Guest<Detcore> for ScriptedGuest {
15692        type Memory = LocalMemory;
15693        type Stack = ScriptedStack;
15694
15695        fn tid(&self) -> Pid {
15696            Pid::from_raw(1)
15697        }
15698        fn pid(&self) -> Pid {
15699            Pid::from_raw(1)
15700        }
15701        fn ppid(&self) -> Option<Pid> {
15702            None
15703        }
15704        fn is_runtime_owned_fd(&self, fd: RawFd) -> bool {
15705            self.runtime_fd == Some(fd)
15706        }
15707        fn runtime_private_memory_regions(&self) -> Option<reverie::RuntimePrivateMemory> {
15708            self.private_memory.clone().map(|facts| {
15709                if self.private_retired {
15710                    reverie::RuntimePrivateMemory::Unavailable
15711                } else {
15712                    reverie::RuntimePrivateMemory::Ready(facts)
15713                }
15714            })
15715        }
15716        fn runtime_private_memory_is_current(
15717            &self,
15718            snapshot: &reverie::RuntimePrivateMemorySnapshot,
15719        ) -> bool {
15720            self.private_validations.fetch_add(1, Ordering::SeqCst);
15721            !self.private_retired && self.private_memory.as_ref() == Some(snapshot)
15722        }
15723        fn memory(&self) -> Self::Memory {
15724            LocalMemory::new()
15725        }
15726        fn thread_state_mut(&mut self) -> &mut ThreadState<()> {
15727            &mut self.thread
15728        }
15729        fn thread_state(&self) -> &ThreadState<()> {
15730            &self.thread
15731        }
15732        async fn regs(&mut self) -> libc::user_regs_struct {
15733            panic!("fd registration must not read registers")
15734        }
15735        async fn stack(&mut self) -> Self::Stack {
15736            ScriptedStack {
15737                writable: self.stack_writable,
15738                arena: self
15739                    .scratch_page
15740                    .unwrap_or(self.arena.as_mut_ptr() as usize),
15741                capacity: if self.scratch_page.is_some() {
15742                    4096
15743                } else {
15744                    ARENA_WORDS * std::mem::size_of::<u64>()
15745                },
15746                guard_live: self.guard_live.clone(),
15747                partial: self.commit_partial,
15748                protect_on_failure: self
15749                    .scratch_page
15750                    .filter(|_| self.protect_page_on_commit_failure),
15751            }
15752        }
15753        async fn daemonize(&mut self) {
15754            panic!("fd registration must not daemonize")
15755        }
15756        async fn inject<S: SyscallInfo>(&mut self, syscall: S) -> Result<i64, Errno> {
15757            let (number, args) = syscall.into_parts();
15758            self.injected.push(number);
15759            if let Some(page) = self
15760                .scratch_page
15761                .filter(|_| self.protect_page_on == Some(number))
15762            {
15763                // SAFETY: the page is the test's own mapping.
15764                assert_eq!(
15765                    unsafe { libc::mprotect(page as *mut _, 4096, libc::PROT_READ) },
15766                    0
15767                );
15768            }
15769            if matches!(number, Sysno::getdents | Sysno::getdents64) {
15770                let bytes = self
15771                    .directory_batches
15772                    .pop_front()
15773                    .expect("scripted getdents")?;
15774                assert!(bytes.len() <= args.arg2);
15775                if !bytes.is_empty() {
15776                    let buffer = AddrMut::from_raw(args.arg1).unwrap();
15777                    self.memory().write_exact(buffer, &bytes)?;
15778                }
15779                return Ok(bytes.len() as i64);
15780            }
15781            // SAFETY: each arm runs the syscall Detcore asked for against this
15782            // process, on addresses Detcore obtained from this guest.
15783            let raw = match Syscall::from_raw(number, args) {
15784                Syscall::Lseek(call) if self.private_memory.is_some() => {
15785                    assert_eq!(call.offset(), 0);
15786                    assert_eq!(call.whence(), Whence::SEEK_SET);
15787                    0
15788                }
15789                Syscall::Read(call) if self.private_memory.is_some() => {
15790                    let bytes = self.maps_reads.pop_front().expect("scripted maps drain");
15791                    assert!(bytes.len() <= call.len());
15792                    self.memory().write_exact(call.buf().unwrap(), &bytes)?;
15793                    if bytes.is_empty() {
15794                        // The owner changes generation while the complete
15795                        // drain is in flight, before snapshot publication.
15796                        self.private_retired = true;
15797                    }
15798                    bytes.len() as i64
15799                }
15800                Syscall::Mmap(call) => {
15801                    assert!(call.addr().is_none(), "the kernel must choose the address");
15802                    assert_eq!(call.prot(), ProtFlags::PROT_READ | ProtFlags::PROT_WRITE);
15803                    assert_eq!(
15804                        call.flags(),
15805                        MapFlags::MAP_PRIVATE | MapFlags::MAP_ANONYMOUS
15806                    );
15807                    if self.mmap_fails {
15808                        return Err(Errno::ENOMEM);
15809                    }
15810                    let address = unsafe {
15811                        libc::mmap(
15812                            std::ptr::null_mut(),
15813                            call.len(),
15814                            libc::PROT_READ | libc::PROT_WRITE,
15815                            libc::MAP_PRIVATE | libc::MAP_ANONYMOUS,
15816                            -1,
15817                            0,
15818                        )
15819                    };
15820                    if address == libc::MAP_FAILED {
15821                        -1
15822                    } else {
15823                        self.mapped.push((address as usize, call.len()));
15824                        address as i64
15825                    }
15826                }
15827                Syscall::Fstat(call) => {
15828                    let buffer = call.stat().expect("fstat without a buffer").0.as_raw();
15829                    self.fstat_buffers.push(buffer);
15830                    self.fstat_guard_live
15831                        .push(self.guard_live.load(Ordering::SeqCst));
15832                    i64::from(unsafe { libc::fstat(call.fd(), buffer as *mut libc::stat) })
15833                }
15834                Syscall::Munmap(call) => {
15835                    let address = call.addr().expect("munmap without an address").as_raw();
15836                    let raw = i64::from(unsafe { libc::munmap(address as *mut _, call.len()) });
15837                    if raw == 0 {
15838                        self.unmapped.push((address, call.len()));
15839                    }
15840                    raw
15841                }
15842                Syscall::Close(call) => {
15843                    self.close_attempts.push(call.fd());
15844                    if let Some(errno) = self.close_errors.pop_front() {
15845                        return Err(errno);
15846                    }
15847                    self.closed.push(call.fd());
15848                    i64::from(unsafe { libc::close(call.fd()) })
15849                }
15850                Syscall::Openat(call) => {
15851                    let path = call.path().expect("openat without a path");
15852                    let path = path.read(&self.memory()).unwrap();
15853                    self.opened_paths
15854                        .push(path.as_os_str().as_encoded_bytes().to_vec());
15855                    if let Some(errno) = self.open_errors.pop_front() {
15856                        return Err(errno);
15857                    }
15858                    let (fd, _) = open_file();
15859                    self.opened_fds.push(fd);
15860                    i64::from(fd)
15861                }
15862                Syscall::Capget(call) => {
15863                    // Every capability, in the effective and permitted sets.
15864                    let data = call.data().expect("capget without data").as_raw();
15865                    let effective = self.capget_effective;
15866                    let words: [u32; 6] = [
15867                        effective as u32,
15868                        u32::MAX,
15869                        0,
15870                        (effective >> 32) as u32,
15871                        0x1ff,
15872                        0,
15873                    ];
15874                    let bytes: Vec<u8> = words.iter().flat_map(|word| word.to_ne_bytes()).collect();
15875                    self.memory()
15876                        .write_exact(AddrMut::<u8>::from_raw(data).unwrap(), &bytes)?;
15877                    0
15878                }
15879                other => panic!("unexpected injected syscall {other:?}"),
15880            };
15881            Errno::result(raw)
15882        }
15883        async fn tail_inject<S: SyscallInfo>(&mut self, _: S) -> reverie::Never {
15884            panic!("fd registration must not retire the guest")
15885        }
15886        fn set_timer(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
15887            panic!("fd registration must not set a timer")
15888        }
15889        fn set_timer_precise(&mut self, _: reverie::TimerSchedule) -> Result<(), Error> {
15890            panic!("fd registration must not set a timer")
15891        }
15892        fn read_clock(&mut self) -> Result<u64, Error> {
15893            panic!("fd registration must not read a clock")
15894        }
15895    }
15896
15897    pub(super) async fn raw_directory_projection() {
15898        use std::os::fd::AsRawFd;
15899        let directory = std::fs::File::open("/proc/self/fd").unwrap();
15900        for format in [DirentFormat::Legacy, DirentFormat::Dirent64] {
15901            let entries = [
15902                DirEntry {
15903                    ino: 91,
15904                    off: 29,
15905                    name: b"40960".to_vec(),
15906                    ty: 8,
15907                },
15908                DirEntry {
15909                    ino: 92,
15910                    off: 17,
15911                    name: b"1024".to_vec(),
15912                    ty: 10,
15913                },
15914                DirEntry {
15915                    ino: 93,
15916                    off: 31,
15917                    name: b"1023".to_vec(),
15918                    ty: 8,
15919                },
15920            ];
15921            let encode = |rows: &[DirEntry]| {
15922                let mut bytes = Vec::new();
15923                for entry in rows {
15924                    format.encode(entry, entry.ino, entry.off, &mut bytes);
15925                }
15926                bytes
15927            };
15928            let mut unmodified = encode(&entries[..1]);
15929            for at in format.name_offset() + entries[0].name.len() + 1..unmodified.len() {
15930                if at != format.type_offset(unmodified.len()) {
15931                    unmodified[at] = 0x7c;
15932                }
15933            }
15934            for (batches, expected, calls) in [
15935                (
15936                    vec![Ok(encode(&entries))],
15937                    Ok(encode(&[entries[0].clone(), entries[2].clone()])),
15938                    1,
15939                ),
15940                (
15941                    vec![Ok(encode(&entries[1..2])), Ok(encode(&entries[..1]))],
15942                    Ok(encode(&entries[..1])),
15943                    2,
15944                ),
15945                (
15946                    vec![Ok(encode(&entries[1..2])), Ok(Vec::new())],
15947                    Ok(Vec::new()),
15948                    2,
15949                ),
15950                (
15951                    vec![Ok(encode(&entries[1..2])), Err(Errno::EIO)],
15952                    Err(Errno::EIO),
15953                    2,
15954                ),
15955                (vec![Ok(unmodified.clone())], Ok(unmodified.clone()), 1),
15956            ] {
15957                let (_, mut guest) = ScriptedGuest::new(true, false);
15958                guest.config.virtualize_metadata = false;
15959                guest.config.backend = reverie::BackendCapabilities::DBT;
15960                guest.runtime_fd = Some(1024);
15961                let written = batches
15962                    .iter()
15963                    .filter_map(|batch| batch.as_ref().ok().map(Vec::len))
15964                    .max()
15965                    .unwrap();
15966                let untouched = expected.as_ref().is_ok_and(|bytes| bytes == &unmodified);
15967                guest.directory_batches = batches.into();
15968                let tool = <Detcore as Tool>::new(Pid::from_raw(1), &guest.config);
15969                let mut bytes = vec![0xa5; 512];
15970                let buffer: AddrMut<u8> = AddrMut::from_raw(bytes.as_mut_ptr() as usize).unwrap();
15971                let result = match format {
15972                    DirentFormat::Legacy => {
15973                        tool.handle_getdents(
15974                            &mut guest,
15975                            syscalls::Getdents::new()
15976                                .with_fd(directory.as_raw_fd() as u32)
15977                                .with_dirent(Some(buffer.cast()))
15978                                .with_count(bytes.len() as u32),
15979                        )
15980                        .await
15981                    }
15982                    DirentFormat::Dirent64 => {
15983                        tool.handle_getdents64(
15984                            &mut guest,
15985                            syscalls::Getdents64::new()
15986                                .with_fd(directory.as_raw_fd() as u32)
15987                                .with_dirent(Some(buffer.cast()))
15988                                .with_count(bytes.len() as u32),
15989                        )
15990                        .await
15991                    }
15992                };
15993                assert_eq!(guest.injected.len(), calls, "{format:?}");
15994                assert!(bytes[written..].iter().all(|byte| *byte == 0xa5));
15995                match expected {
15996                    Ok(expected) => {
15997                        assert_eq!(result.unwrap(), expected.len() as i64, "{format:?}");
15998                        assert_eq!(&bytes[..expected.len()], expected, "{format:?}");
15999                        if !untouched {
16000                            assert!(bytes[expected.len()..written].iter().all(|byte| *byte == 0));
16001                        }
16002                    }
16003                    Err(expected) => {
16004                        assert!(
16005                            matches!(result, Err(Error::Errno(actual)) if actual == expected),
16006                            "{format:?}: {result:?}"
16007                        );
16008                        assert!(bytes[..format.record_len(4)].iter().all(|byte| *byte == 0));
16009                    }
16010                }
16011            }
16012        }
16013    }
16014
16015    #[test]
16016    fn private_maps_targets_require_complete_identity_or_translated_numbers() {
16017        use crate::procfs::BoundTask;
16018        let actual = Path::new("/proc/21/task/23/maps");
16019        for (numbers, expected) in [
16020            (
16021                BTreeMap::from([(21, 21), (23, 23)]),
16022                Some(BoundTask {
16023                    process: 21,
16024                    thread: Some(23),
16025                }),
16026            ),
16027            (
16028                BTreeMap::from([(21, 3), (23, 5)]),
16029                Some(BoundTask {
16030                    process: 3,
16031                    thread: Some(5),
16032                }),
16033            ),
16034            (BTreeMap::from([(21, 3)]), None),
16035        ] {
16036            assert_eq!(
16037                Detcore::<crate::record_or_replay::NoopTool>::maps_target_with_numbers(
16038                    actual,
16039                    Some(&numbers),
16040                    1,
16041                    1,
16042                ),
16043                expected
16044            );
16045        }
16046    }
16047
16048    #[tokio::test]
16049    async fn private_maps_authenticates_the_opened_descriptor_in_its_task_view() {
16050        use std::os::fd::AsRawFd;
16051        let (_, mut guest) = ScriptedGuest::new(true, false);
16052        guest.config.backend = reverie::BackendCapabilities::DBT;
16053        guest.config.sequentialize_threads = true;
16054        guest.thread.physical_tid = Some(123456);
16055        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &guest.config);
16056        assert!(!procfs_inode::guest_tids_name_host_tasks(
16057            &guest.config.backend,
16058            guest.thread.physical_tid,
16059        ));
16060        let file = std::fs::File::open("/proc/thread-self/maps").unwrap();
16061        let fd = file.as_raw_fd();
16062        let mut stat: libc::stat = unsafe { std::mem::zeroed() };
16063        assert_eq!(unsafe { libc::fstat(fd, &mut stat) }, 0);
16064        let stat = DetStat::from(stat);
16065        let authenticated = tool.maps_descriptor_entry(&guest, &stat, fd).await;
16066        assert!(
16067            matches!(&authenticated, ProcfsEntry::At(path) if path.ends_with("maps")),
16068            "{authenticated:?}"
16069        );
16070
16071        // The same spelling cannot authorize a different descriptor/object.
16072        let ordinary = tempfile::tempfile().unwrap();
16073        let mut ordinary_stat: libc::stat = unsafe { std::mem::zeroed() };
16074        assert_eq!(
16075            unsafe { libc::fstat(ordinary.as_raw_fd(), &mut ordinary_stat) },
16076            0
16077        );
16078        assert!(matches!(
16079            tool.maps_descriptor_entry(&guest, &DetStat::from(ordinary_stat), ordinary.as_raw_fd())
16080                .await,
16081            ProcfsEntry::NotProcfs
16082        ));
16083        assert!(matches!(
16084            tool.maps_descriptor_entry(&guest, &stat, ordinary.as_raw_fd())
16085                .await,
16086            ProcfsEntry::Unknown
16087        ));
16088        guest.thread.changed_root.store(true, Ordering::SeqCst);
16089        assert!(matches!(
16090            tool.maps_descriptor_entry(&guest, &stat, fd).await,
16091            ProcfsEntry::Unknown
16092        ));
16093    }
16094
16095    #[tokio::test]
16096    async fn private_maps_retired_during_drain_never_publish_a_snapshot() {
16097        let (_, mut guest) = ScriptedGuest::with_scratch_page(true);
16098        guest.config.sequentialize_threads = true;
16099        let tool = <Detcore as Tool>::new(Pid::from_raw(1), &guest.config);
16100        let target = crate::procfs::MapsTarget {
16101            task: crate::procfs::BoundTask {
16102                process: 2,
16103                thread: None,
16104            },
16105            incarnation: crate::procfs::TaskIncarnation {
16106                process: 1,
16107                thread: None,
16108            },
16109            mm: detcore_model::futex::MmId::initial(DetTid::from_raw(2)),
16110            private: reverie::RuntimePrivateMemorySnapshot {
16111                owner: [1, 2, 3, 4],
16112                version: 1,
16113                regions: vec![reverie::RuntimePrivateMemoryRegion {
16114                    start: 0x1000,
16115                    end: 0x2000,
16116                }],
16117            },
16118        };
16119        guest.private_memory = Some(target.private.clone());
16120        guest.maps_reads = [b"1000-2000 rw-p 00000000 00:00 0 \n".to_vec(), Vec::new()].into();
16121        let fd = 9;
16122        guest
16123            .thread
16124            .add_fd(fd, OFlag::O_RDONLY, FdType::Regular, None)
16125            .unwrap();
16126        let mut file = ProcfsFile::from_path(Path::new("/proc/2/maps")).unwrap();
16127        file.bind_maps_target(target.clone());
16128        guest
16129            .thread
16130            .with_detfd(fd, |detfd| detfd.set_procfs(file.clone()))
16131            .unwrap();
16132        let mut output = [0xa5_u8; 512];
16133        let call = syscalls::Read::new()
16134            .with_fd(fd)
16135            .with_buf(AddrMut::from_raw(output.as_mut_ptr() as usize))
16136            .with_len(output.len());
16137
16138        let error = tool
16139            .initialize_procfs_snapshot(&mut guest, call)
16140            .await
16141            .unwrap_err();
16142        assert!(
16143            matches!(error, Error::Tool(ref error) if error.to_string() ==
16144            "runtime-private maps view unavailable: target ownership changed during capture"),
16145            "{error:?}"
16146        );
16147        assert_eq!(guest.private_validations.load(Ordering::SeqCst), 2);
16148        assert!(guest.maps_reads.is_empty());
16149        assert_eq!(guest.injected, [Sysno::lseek, Sysno::read, Sysno::read]);
16150        assert_eq!(output, [0xa5; 512]);
16151        guest
16152            .thread
16153            .with_detfd(fd, |detfd| {
16154                assert!(detfd.procfs_needs_snapshot());
16155                assert_eq!(detfd.procfs_position(), Some((0, None)));
16156                assert_eq!(detfd.preview_procfs(512), None);
16157                assert_eq!(detfd.procfs_maps_target(), Some(target.clone()));
16158            })
16159            .unwrap();
16160        assert_eq!(guest.take_scratch_page(), vec![0xa5; 4096]);
16161    }
16162
16163    /// A real descriptor the test owns by number, and its inode. Ownership is
16164    /// raw so a descriptor that Detcore closes is never closed a second time.
16165    fn open_file() -> (RawFd, u64) {
16166        let file = tempfile::tempfile().unwrap();
16167        let inode = file.metadata().unwrap().ino();
16168        (file.into_raw_fd(), inode)
16169    }
16170
16171    fn close_unless_detcore_did(guest: &ScriptedGuest, fd: RawFd) {
16172        if !guest.closed.contains(&fd) {
16173            assert_eq!(unsafe { libc::close(fd) }, 0);
16174        }
16175    }
16176
16177    fn recorded_inode(guest: &ScriptedGuest, fd: RawFd) -> Option<u64> {
16178        guest
16179            .thread
16180            .with_detfd(fd, |detfd| detfd.stat().map(|stat| stat.inode))
16181            .unwrap()
16182    }
16183
16184    /// The errno of a call the failure policy answered, which a guest run
16185    /// with --allow-unsupported-syscalls sees.
16186    fn policy_errno(error: Error) -> Errno {
16187        error.into_errno().unwrap()
16188    }
16189
16190    /// The task whose `/proc/3/auxv` the access tests open.
16191    const TARGET: crate::procfs::BoundTask = crate::procfs::BoundTask {
16192        process: 3,
16193        thread: None,
16194    };
16195
16196    /// Another process's open of a rendered `/proc/<pid>/auxv`, decided
16197    /// through `ptrace_read_allowed` by the caller's probe opens, as the
16198    /// kernel beneath answers them:
16199    /// - the target's probe opens: allowed, one probe;
16200    /// - it is refused while the caller's `/proc/thread-self/stat` opens: the
16201    ///   refusal's errno;
16202    /// - both are refused with EACCES (the provider's backstop): the caller's
16203    ///   CAP_SYS_PTRACE decides, with and without it;
16204    /// - both fail with EMFILE (a full descriptor table): EMFILE, never the
16205    ///   fallback's EACCES;
16206    /// - an open Reverie reports did not run (ERESTARTSYS) is retried.
16207    #[tokio::test]
16208    async fn the_auxv_access_check_follows_the_kernel_beneaths_answers() {
16209        let paths = |guest: &ScriptedGuest| guest.opened_paths.clone();
16210        let target = b"/proc/3/auxv".to_vec();
16211        let serves = b"/proc/thread-self/stat".to_vec();
16212        let all = (1_u64 << 41) - 1;
16213        let without_ptrace = all & !(1 << 19);
16214        for (errors, effective, answer, probes, capget) in [
16215            (vec![], all, Ok(()), vec![target.clone()], false),
16216            (
16217                vec![Errno::EACCES],
16218                all,
16219                Err(Errno::EACCES),
16220                vec![target.clone(), serves.clone()],
16221                false,
16222            ),
16223            (
16224                vec![Errno::EACCES, Errno::EACCES],
16225                all,
16226                Ok(()),
16227                vec![target.clone(), serves.clone()],
16228                true,
16229            ),
16230            (
16231                vec![Errno::EACCES, Errno::EACCES],
16232                without_ptrace,
16233                Err(Errno::EACCES),
16234                vec![target.clone(), serves.clone()],
16235                true,
16236            ),
16237            (
16238                vec![Errno::EMFILE, Errno::EMFILE],
16239                without_ptrace,
16240                Err(Errno::EMFILE),
16241                vec![target.clone(), serves.clone()],
16242                false,
16243            ),
16244            (
16245                vec![Errno::ERESTARTSYS],
16246                without_ptrace,
16247                Ok(()),
16248                vec![target.clone(), target.clone()],
16249                false,
16250            ),
16251        ] {
16252            let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16253            guest.open_errors.extend(errors.clone());
16254            guest.capget_effective = effective;
16255            let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16256            assert_eq!(result.unwrap(), answer, "{errors:?}");
16257            assert_eq!(paths(&guest), probes, "{errors:?}");
16258            assert_eq!(
16259                guest.injected.contains(&Sysno::capget),
16260                capget,
16261                "{errors:?}"
16262            );
16263            assert_eq!(guest.closed, guest.opened_fds, "every probe is closed");
16264            assert!(
16265                guest.take_scratch_page().iter().all(|byte| *byte == 0xa5),
16266                "{errors:?}: the scratch is left modified"
16267            );
16268        }
16269    }
16270
16271    /// Guest stack scratch that cannot be used, or cannot be put back, is
16272    /// the failure policy's (EOPNOTSUPP under --allow-unsupported-syscalls,
16273    /// a named stop otherwise), never an access answer:
16274    /// - a commit that fails, its partial write put back: no probe runs,
16275    ///   and the scratch is as it was;
16276    /// - a commit that fails part way and whose partial write cannot be put
16277    ///   back;
16278    /// - a probe, and a capget (K1's), whose scratch becomes read-only
16279    ///   before it is put back.
16280    /// And a capget that succeeds puts its scratch back.
16281    #[tokio::test]
16282    async fn guest_stack_scratch_failures_go_to_the_failure_policy() {
16283        // A commit that fails, put back.
16284        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(false);
16285        guest.commit_partial = true;
16286        let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16287        assert_eq!(policy_errno(result.unwrap_err()), Errno::EOPNOTSUPP);
16288        assert!(guest.injected.is_empty());
16289        assert!(guest.take_scratch_page().iter().all(|byte| *byte == 0xa5));
16290        // A partial write that cannot be put back.
16291        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(false);
16292        guest.commit_partial = true;
16293        guest.protect_page_on_commit_failure = true;
16294        let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16295        assert_eq!(policy_errno(result.unwrap_err()), Errno::EOPNOTSUPP);
16296        assert!(guest.injected.is_empty());
16297        guest.take_scratch_page();
16298        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(false);
16299        guest.commit_partial = true;
16300        guest.protect_page_on_commit_failure = true;
16301        let result =
16302            Detcore::inject_capget(&mut guest, rendered_procfs::CapabilitySet::Effective).await;
16303        assert_eq!(policy_errno(result.unwrap_err()), Errno::EOPNOTSUPP);
16304        guest.take_scratch_page();
16305        // A probe whose scratch cannot be put back: its descriptor is still
16306        // closed.
16307        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16308        guest.protect_page_on = Some(Sysno::openat);
16309        let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16310        assert_eq!(policy_errno(result.unwrap_err()), Errno::EOPNOTSUPP);
16311        assert_eq!(guest.closed, guest.opened_fds);
16312        guest.take_scratch_page();
16313        // A capget whose scratch cannot be put back.
16314        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16315        guest.protect_page_on = Some(Sysno::capget);
16316        let result =
16317            Detcore::inject_capget(&mut guest, rendered_procfs::CapabilitySet::Effective).await;
16318        assert_eq!(policy_errno(result.unwrap_err()), Errno::EOPNOTSUPP);
16319        guest.take_scratch_page();
16320        // A capget that succeeds.
16321        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16322        let result =
16323            Detcore::inject_capget(&mut guest, rendered_procfs::CapabilitySet::Effective).await;
16324        assert_eq!(result.unwrap(), Some((1 << 41) - 1));
16325        assert!(guest.take_scratch_page().iter().all(|byte| *byte == 0xa5));
16326    }
16327
16328    /// The probe's close, as Linux's close allows: a close Reverie reports
16329    /// did not run (ERESTARTSYS) is retried; EINTR is not (Linux released
16330    /// the descriptor before returning it); any other error is the failure
16331    /// policy's, never a silent leak.
16332    #[tokio::test]
16333    async fn the_auxv_access_probe_closes_its_descriptor_as_linux_close_allows() {
16334        let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16335        guest.close_errors.push_back(Errno::ERESTARTSYS);
16336        let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16337        assert_eq!(result.unwrap(), Ok(()));
16338        let [fd] = guest.opened_fds[..] else { panic!() };
16339        assert_eq!(
16340            guest.close_attempts,
16341            [fd, fd],
16342            "a close that did not run is retried"
16343        );
16344        assert_eq!(guest.closed, [fd]);
16345        guest.take_scratch_page();
16346        for (errno, failed) in [(Errno::EINTR, false), (Errno::EBADF, true)] {
16347            let (_tool, mut guest) = ScriptedGuest::with_scratch_page(true);
16348            guest.close_errors.push_back(errno);
16349            let result = Detcore::ptrace_read_allowed(&mut guest, TARGET).await;
16350            let [fd] = guest.opened_fds[..] else { panic!() };
16351            assert_eq!(guest.close_attempts, [fd], "{errno} is not retried");
16352            match result {
16353                Ok(answer) => {
16354                    assert!(!failed, "{errno}");
16355                    assert_eq!(answer, Ok(()));
16356                }
16357                Err(error) => {
16358                    assert!(failed, "{errno}");
16359                    assert_eq!(policy_errno(error), Errno::EOPNOTSUPP);
16360                }
16361            }
16362            // The scripted error left the real descriptor open.
16363            assert_eq!(unsafe { libc::close(fd) }, 0);
16364            assert!(guest.take_scratch_page().iter().all(|byte| *byte == 0xa5));
16365        }
16366    }
16367
16368    #[tokio::test]
16369    async fn writable_stack_scratch_is_used_while_its_guard_is_live() {
16370        let (fd, inode) = open_file();
16371        let (tool, mut guest) = ScriptedGuest::new(true, false);
16372
16373        let result = tool
16374            .add_fd(&mut guest, fd, OFlag::O_RDONLY, FdType::Regular)
16375            .await;
16376        close_unless_detcore_did(&guest, fd);
16377
16378        assert_eq!(result, Ok(()));
16379        assert_eq!(guest.injected, [Sysno::fstat]);
16380        assert_eq!(
16381            guest.fstat_guard_live,
16382            [true],
16383            "the stack guard must outlive the injected fstat: backends whose \
16384             scratch is an arena free it when the guard drops"
16385        );
16386        assert_eq!(
16387            guest.fstat_buffers,
16388            [guest.arena.as_ptr() as usize],
16389            "fstat must write into the stack scratch"
16390        );
16391        let used_words = std::mem::size_of::<libc::stat>().div_ceil(8);
16392        assert!(
16393            guest.arena[..used_words].iter().all(|word| *word == 0),
16394            "the stat must not be left in the guest's stack scratch"
16395        );
16396        assert_eq!(recorded_inode(&guest, fd), Some(inode));
16397    }
16398
16399    #[tokio::test]
16400    async fn faulting_stack_scratch_falls_back_to_a_transient_page() {
16401        let (fd, inode) = open_file();
16402        let (tool, mut guest) = ScriptedGuest::new(false, false);
16403
16404        let result = tool
16405            .add_fd(&mut guest, fd, OFlag::O_RDONLY, FdType::Regular)
16406            .await;
16407        close_unless_detcore_did(&guest, fd);
16408
16409        assert_eq!(
16410            result,
16411            Ok(()),
16412            "a stack that cannot hold the fstat buffer must not fail the open"
16413        );
16414        assert_eq!(guest.injected, [Sysno::mmap, Sysno::fstat, Sysno::munmap]);
16415        let [(page, len)] = guest.mapped[..] else {
16416            panic!(
16417                "expected exactly one transient page, got {:?}",
16418                guest.mapped
16419            );
16420        };
16421        assert_eq!(
16422            guest.fstat_buffers,
16423            [page],
16424            "fstat must write into the transient page"
16425        );
16426        assert_eq!(
16427            guest.unmapped,
16428            [(page, len)],
16429            "the transient page must be unmapped, whole"
16430        );
16431        assert_eq!(recorded_inode(&guest, fd), Some(inode));
16432    }
16433
16434    #[tokio::test]
16435    async fn descriptor_is_closed_when_no_scratch_can_be_found() {
16436        let (fd, _) = open_file();
16437        let (tool, mut guest) = ScriptedGuest::new(false, true);
16438
16439        let result = tool
16440            .add_fd(&mut guest, fd, OFlag::O_RDONLY, FdType::Regular)
16441            .await;
16442        close_unless_detcore_did(&guest, fd);
16443
16444        assert_eq!(result, Err(Errno::ENOMEM));
16445        assert_eq!(guest.injected, [Sysno::mmap, Sysno::close]);
16446        assert_eq!(
16447            guest.closed,
16448            [fd],
16449            "the descriptor must not stay open behind the error"
16450        );
16451        assert_eq!(
16452            guest.thread.with_detfd(fd, |_| ()),
16453            Err(Errno::EBADF),
16454            "a descriptor that failed registration must not be modeled"
16455        );
16456    }
16457}
16458
16459#[cfg(test)]
16460mod rebound_path_tests {
16461    use std::path::PathBuf;
16462
16463    use super::rebound_path;
16464
16465    /// A namespace change's operand is reported as the path it names, made
16466    /// absolute. One that could not be read (a tracer may not read a
16467    /// non-dumpable guest's memory) or made absolute is reported as `/`, the
16468    /// ancestor of every path, so that no host input change is named in that
16469    /// run instead of one the guest may have made.
16470    #[test]
16471    fn an_operand_that_cannot_be_established_is_reported_as_the_root() {
16472        assert_eq!(rebound_path(Some(PathBuf::from("/data/F"))), "/data/F");
16473        assert_eq!(rebound_path(None), "/");
16474        assert_eq!(rebound_path(Some(PathBuf::from("F"))), "/");
16475    }
16476}
16477
16478#[cfg(test)]
16479mod untraced_code_tests {
16480    use std::path::Path;
16481    use std::path::PathBuf;
16482
16483    use nix::fcntl::OFlag;
16484    use reverie::syscalls::Errno;
16485    use reverie::syscalls::SyscallArgs;
16486    use reverie::syscalls::Sysno;
16487
16488    use super::DescriptorFacts;
16489    use super::DetPid;
16490    use super::PROC_ROOT_INO;
16491    use super::PidfdSignalScope;
16492    use super::ProcessDirectoryDescriptor;
16493    use super::classify_process_directory;
16494    use super::descriptor_identity;
16495    use super::may_change_untraced_code;
16496    use super::may_write_process_memory;
16497    use super::pidfd_signal_scope;
16498
16499    const PAGE: (u64, u64) = (0x7100_0000, 0x7100_1000);
16500
16501    fn args(arg0: u64, arg1: u64, arg2: u64, arg3: u64, arg4: u64) -> SyscallArgs {
16502        SyscallArgs::new(
16503            arg0 as usize,
16504            arg1 as usize,
16505            arg2 as usize,
16506            arg3 as usize,
16507            arg4 as usize,
16508            0,
16509        )
16510    }
16511
16512    /// A thread cloned without CLONE_FILES has its own descriptor table, so
16513    /// a descriptor is read through the thread that opened it. Through its
16514    /// leader the same number names nothing here, which would make an
16515    /// ordinary write-mode open count as unreadable (a false `/` that
16516    /// withholds a real host input change) and would miss the thread's own
16517    /// process-memory file.
16518    #[test]
16519    fn a_descriptor_is_read_through_the_thread_that_opened_it() {
16520        use std::os::fd::AsRawFd;
16521
16522        let directory = tempfile::tempdir().unwrap();
16523        let ordinary = directory.path().join("out");
16524        let named_mem = directory.path().join("mem");
16525        std::thread::spawn(move || {
16526            // SAFETY: gives only this thread a private copy of the table.
16527            assert_eq!(unsafe { libc::unshare(libc::CLONE_FILES) }, 0);
16528            // SAFETY: plain syscalls on this thread's own descriptors.
16529            let tid = unsafe { libc::gettid() };
16530            let leader = std::process::id() as i32;
16531            let files = [
16532                (std::fs::File::create(&ordinary).unwrap(), false),
16533                (std::fs::File::create(&named_mem).unwrap(), false),
16534                (
16535                    std::fs::OpenOptions::new()
16536                        .read(true)
16537                        .write(true)
16538                        .open("/proc/thread-self/mem")
16539                        .unwrap(),
16540                    true,
16541                ),
16542            ];
16543            for (number, (file, is_process_memory)) in (900..).zip(files) {
16544                assert_eq!(unsafe { libc::dup2(file.as_raw_fd(), number) }, number);
16545                drop(file);
16546                let identity = descriptor_identity(tid, number);
16547                assert!(identity.is_some(), "{number}");
16548                assert_eq!(descriptor_identity(leader, number), None, "{number}");
16549                assert_eq!(
16550                    may_write_process_memory(
16551                        OFlag::O_WRONLY,
16552                        identity
16553                            .as_ref()
16554                            .map(|(link, procfs)| (link.as_path(), *procfs)),
16555                    ),
16556                    is_process_memory,
16557                    "{identity:?}"
16558                );
16559                assert_eq!(unsafe { libc::close(number) }, 0);
16560            }
16561        })
16562        .join()
16563        .unwrap();
16564    }
16565
16566    /// Every call that can replace, unprotect, discard or unmap the range
16567    /// counts when its interval reaches any byte of it, and not when it stops
16568    /// short of it or starts after it.
16569    #[test]
16570    fn a_call_counts_exactly_when_it_may_change_the_range() {
16571        let fixed = libc::MAP_FIXED as u64 | libc::MAP_PRIVATE as u64;
16572        let huge = fixed | libc::MAP_HUGETLB as u64;
16573        let huge_1gb = (30 << libc::MAP_HUGE_SHIFT) as u64;
16574        let remap_fixed = (libc::MREMAP_MAYMOVE | libc::MREMAP_FIXED) as u64;
16575        let remap = libc::SHM_REMAP as u64;
16576        let cases = [
16577            (
16578                "mmap fixed over it",
16579                Sysno::mmap,
16580                args(0x7100_0000, 0x1000, 7, fixed, 0),
16581                true,
16582            ),
16583            (
16584                "mmap fixed reaching it",
16585                Sysno::mmap,
16586                args(0x70ff_f000, 0x1001, 7, fixed, 0),
16587                true,
16588            ),
16589            (
16590                "mmap fixed below it",
16591                Sysno::mmap,
16592                args(0x70ff_f000, 0x1000, 7, fixed, 0),
16593                false,
16594            ),
16595            (
16596                "mmap fixed above it",
16597                Sysno::mmap,
16598                args(0x7100_1000, 0x1000, 7, fixed, 0),
16599                false,
16600            ),
16601            (
16602                "mmap hinted at it",
16603                Sysno::mmap,
16604                args(0x7100_0000, 0x1000, 7, 0x22, 0),
16605                false,
16606            ),
16607            // The host default here is 2 MiB; 0x7100_0000 is 2 MiB aligned.
16608            (
16609                "mmap fixed default huge page holding it",
16610                Sysno::mmap,
16611                args(0x7110_0000, 1, 7, huge, 0),
16612                true,
16613            ),
16614            (
16615                "mmap fixed small page there",
16616                Sysno::mmap,
16617                args(0x7110_0000, 1, 7, fixed, 0),
16618                false,
16619            ),
16620            (
16621                "mmap fixed default huge page below it",
16622                Sysno::mmap,
16623                args(0x70ff_f000, 1, 7, huge, 0),
16624                false,
16625            ),
16626            (
16627                "mmap fixed 1 GiB page holding it",
16628                Sysno::mmap,
16629                args(0x4000_0000, 1, 7, huge | huge_1gb, 0),
16630                true,
16631            ),
16632            (
16633                "mmap fixed 1 GiB page elsewhere",
16634                Sysno::mmap,
16635                args(0x8000_0000, 1, 7, huge | huge_1gb, 0),
16636                false,
16637            ),
16638            (
16639                "mprotect of it",
16640                Sysno::mprotect,
16641                args(0x7100_0000, 0x1000, 7, 0, 0),
16642                true,
16643            ),
16644            (
16645                "mprotect covering it",
16646                Sysno::mprotect,
16647                args(0x7000_0000, 0x200_0000, 7, 0, 0),
16648                true,
16649            ),
16650            (
16651                "mprotect of a zero length",
16652                Sysno::mprotect,
16653                args(0x7100_0000, 0, 7, 0, 0),
16654                true,
16655            ),
16656            (
16657                "pkey_mprotect of it",
16658                Sysno::pkey_mprotect,
16659                args(0x7100_0000, 1, 7, 0, 0),
16660                true,
16661            ),
16662            (
16663                "madvise of it",
16664                Sysno::madvise,
16665                args(0x7100_0000, 0x1000, 4, 0, 0),
16666                true,
16667            ),
16668            (
16669                "munmap of it",
16670                Sysno::munmap,
16671                args(0x7100_0000, 0x1000, 0, 0, 0),
16672                true,
16673            ),
16674            (
16675                "munmap past it",
16676                Sysno::munmap,
16677                args(0x7100_1000, 0x1000, 0, 0, 0),
16678                false,
16679            ),
16680            (
16681                "mremap from it",
16682                Sysno::mremap,
16683                args(0x7100_0000, 0x1000, 0x2000, 1, 0),
16684                true,
16685            ),
16686            (
16687                "mremap fixed onto it",
16688                Sysno::mremap,
16689                args(0x6000_0000, 0x1000, 0x1000, remap_fixed, 0x7100_0000),
16690                true,
16691            ),
16692            (
16693                "mremap fixed of a small page into its gigabyte",
16694                Sysno::mremap,
16695                args(0x6000_0000, 0x1000, 0x1000, remap_fixed, 0x4000_0000),
16696                false,
16697            ),
16698            (
16699                "mremap moving elsewhere",
16700                Sysno::mremap,
16701                args(0x6000_0000, 0x1000, 0x2000, 1, 0x7100_0000),
16702                false,
16703            ),
16704            (
16705                "shmat remapping at it",
16706                Sysno::shmat,
16707                args(3, 0x7100_0000, remap, 0, 0),
16708                true,
16709            ),
16710            (
16711                "shmat remapping below it",
16712                Sysno::shmat,
16713                args(3, 0x6000_0000, remap, 0, 0),
16714                true,
16715            ),
16716            (
16717                "shmat without remap",
16718                Sysno::shmat,
16719                args(3, 0x7100_0000, 0, 0, 0),
16720                false,
16721            ),
16722            (
16723                "shmat anywhere",
16724                Sysno::shmat,
16725                args(3, 0, remap, 0, 0),
16726                false,
16727            ),
16728            ("brk", Sysno::brk, args(0x7100_0000, 0, 0, 0, 0), false),
16729            // A scalar argument that equals an address in the range is not one.
16730            (
16731                "lseek to that offset",
16732                Sysno::lseek,
16733                args(3, 0x7100_0000, 0, 0, 0),
16734                false,
16735            ),
16736            (
16737                "an address near the end",
16738                Sysno::munmap,
16739                args(u64::MAX - 0xfff, 0x1000, 0, 0, 0),
16740                false,
16741            ),
16742        ];
16743        for (label, number, args, expected) in cases {
16744            assert_eq!(
16745                may_change_untraced_code(number, &args, PAGE, 2 << 20),
16746                expected,
16747                "{label}"
16748            );
16749        }
16750    }
16751
16752    /// `pidfd_send_signal`'s flags select one scope, as Linux's do; an unknown
16753    /// bit or two scopes are EINVAL (https://github.com/rrnewton/hermit/issues/4108).
16754    #[test]
16755    fn pidfd_signal_flags_select_one_scope() {
16756        assert_eq!(pidfd_signal_scope(0), Ok(PidfdSignalScope::Process));
16757        assert_eq!(pidfd_signal_scope(1), Ok(PidfdSignalScope::Thread));
16758        assert_eq!(pidfd_signal_scope(2), Ok(PidfdSignalScope::Process));
16759        assert_eq!(pidfd_signal_scope(4), Ok(PidfdSignalScope::ProcessGroup));
16760        for flags in [3, 5, 6, 7, 8, 9, 1 << 31, u32::MAX] {
16761            assert_eq!(pidfd_signal_scope(flags), Err(Errno::EINVAL), "{flags:#x}");
16762        }
16763    }
16764
16765    /// A descriptor names a process for `pidfd_send_signal` only when it is a
16766    /// directory whose parent is the root of the guest's procfs and whose name
16767    /// is a pid; another file is EBADF, and a pidfd Detcore did not open, an
16768    /// unreadable descriptor or another procfs instance cannot be classified.
16769    #[test]
16770    fn a_proc_process_directory_names_its_process() {
16771        use ProcessDirectoryDescriptor as D;
16772        let procfs = |link: &str, parent: Option<(u64, u64)>| DescriptorFacts {
16773            link: PathBuf::from(link),
16774            on_procfs: true,
16775            is_dir: parent.is_some(),
16776            dev: 22,
16777            parent,
16778            guest_proc_dev: Some(22),
16779        };
16780        let reaped = |link: &str| DescriptorFacts {
16781            is_dir: true,
16782            ..procfs(link, None)
16783        };
16784        let root = Some((22, PROC_ROOT_INO));
16785        let cases = [
16786            (
16787                "process",
16788                procfs("/proc/3", root),
16789                D::Process(DetPid::from_raw(3)),
16790            ),
16791            (
16792                "reaped process",
16793                reaped("/proc/7 (deleted)"),
16794                D::Process(DetPid::from_raw(7)),
16795            ),
16796            (
16797                "reaped task directory",
16798                reaped("/proc/7/task/8 (deleted)"),
16799                D::NotAProcess,
16800            ),
16801            (
16802                "reaped elsewhere",
16803                reaped("/mnt/p/7 (deleted)"),
16804                D::Unknown("it names a reaped task outside the guest's /proc"),
16805            ),
16806            (
16807                "procfs mounted elsewhere",
16808                procfs("/mnt/p/3", root),
16809                D::Process(DetPid::from_raw(3)),
16810            ),
16811            (
16812                "task directory",
16813                procfs("/proc/3/task/3", Some((22, 4000))),
16814                D::NotAProcess,
16815            ),
16816            (
16817                "procfs file",
16818                procfs("/proc/3/status", None),
16819                D::NotAProcess,
16820            ),
16821            (
16822                "named root entry",
16823                procfs("/proc/sys", root),
16824                D::NotAProcess,
16825            ),
16826            ("pid zero", procfs("/proc/0", root), D::NotAProcess),
16827            ("leading zero", procfs("/proc/03", root), D::NotAProcess),
16828            ("signed", procfs("/proc/+3", root), D::NotAProcess),
16829            (
16830                "another procfs root",
16831                procfs("/proc/3", Some((23, PROC_ROOT_INO))),
16832                D::NotAProcess,
16833            ),
16834            (
16835                "not the guest's procfs",
16836                DescriptorFacts {
16837                    guest_proc_dev: Some(99),
16838                    ..procfs("/proc/3", root)
16839                },
16840                D::Unknown("it is a procfs that is not the guest's /proc"),
16841            ),
16842            (
16843                "ordinary directory",
16844                DescriptorFacts {
16845                    on_procfs: false,
16846                    ..procfs("/tmp/3", root)
16847                },
16848                D::NotAProcess,
16849            ),
16850            (
16851                "pidfd",
16852                DescriptorFacts {
16853                    on_procfs: false,
16854                    ..procfs("anon_inode:[pidfd]", None)
16855                },
16856                D::Unknown("it is a pidfd that Detcore did not open with pidfd_open"),
16857            ),
16858            (
16859                "pidfs pidfd",
16860                DescriptorFacts {
16861                    on_procfs: false,
16862                    ..procfs("pidfd:[1234]", None)
16863                },
16864                D::Unknown("it is a pidfd that Detcore did not open with pidfd_open"),
16865            ),
16866        ];
16867        for (label, facts, expected) in cases {
16868            assert_eq!(
16869                classify_process_directory(Some(&facts)),
16870                expected,
16871                "{label}"
16872            );
16873        }
16874        assert_eq!(
16875            classify_process_directory(None),
16876            D::Unknown("Hermit cannot read what the descriptor names")
16877        );
16878    }
16879
16880    /// A write-mode open counts when its descriptor is a procfs file named
16881    /// `mem`, or cannot be read at all; a read-only or `O_PATH` open, an
16882    /// ordinary file named `mem`, a pipe, and another procfs file do not.
16883    #[test]
16884    fn an_open_counts_when_it_may_write_process_memory() {
16885        let proc_mem = Some((Path::new("/proc/12/mem"), true));
16886        let cases = [
16887            ("process mem read-write", OFlag::O_RDWR, proc_mem, true),
16888            (
16889                "task mem write-only",
16890                OFlag::O_WRONLY,
16891                Some((Path::new("/proc/12/task/13/mem"), true)),
16892                true,
16893            ),
16894            ("an unreadable descriptor", OFlag::O_WRONLY, None, true),
16895            ("process mem read-only", OFlag::O_RDONLY, proc_mem, false),
16896            (
16897                "process mem as a path",
16898                OFlag::O_PATH | OFlag::O_RDWR,
16899                proc_mem,
16900                false,
16901            ),
16902            (
16903                "an ordinary file named mem",
16904                OFlag::O_WRONLY | OFlag::O_CREAT,
16905                Some((Path::new("/tmp/mem"), false)),
16906                false,
16907            ),
16908            (
16909                "a name that leads to a pipe",
16910                OFlag::O_WRONLY,
16911                Some((Path::new("pipe:[4026]"), false)),
16912                false,
16913            ),
16914            (
16915                "another procfs file",
16916                OFlag::O_WRONLY,
16917                Some((Path::new("/proc/12/attr/current"), true)),
16918                false,
16919            ),
16920            (
16921                "an unreadable read-only descriptor",
16922                OFlag::O_RDONLY,
16923                None,
16924                false,
16925            ),
16926        ];
16927        for (label, flags, descriptor, expected) in cases {
16928            assert_eq!(
16929                may_write_process_memory(flags, descriptor),
16930                expected,
16931                "{label}"
16932            );
16933        }
16934    }
16935}
16936
16937/// Closing advice of every flock refusal. It names no backend: LOCK_NB is the
16938/// form Detcore can serve wherever the backend supports flock, and ENOLCK
16939/// reaches the guest only when the run opted in to unsupported syscalls.
16940const FLOCK_REFUSAL_ADVICE: &str = "LOCK_NB is the supported form where the backend \
16941     supports flock at all; ENOLCK is returned instead only under \
16942     --allow-unsupported-syscalls.";
16943
16944/// Report a flock refusal in every disposition, fail-closed (the run ends)
16945/// and opted in (the guest gets ENOLCK): through tracing, and directly on
16946/// stderr so that neither --log=off nor --log-file hides the reason.
16947fn report_flock_refusal(message: &str) {
16948    error!("{message}");
16949    let _ = std::io::Write::write_fmt(
16950        &mut crate::util::RetryingStderr,
16951        format_args!("hermit: {message}\n"),
16952    );
16953}