Skip to main content

kh_runtime/
host.rs

1//! Host OS primitives: the **only** crate-level home for most libc I/O and
2//! memory syscalls used by the translator.
3//!
4//! Call sites should prefer these wrappers so `unsafe` does not scatter across
5//! BSD handlers. Each function documents the ownership / validity contract.
6#![allow(unsafe_code)]
7
8use std::fs::File;
9use std::io;
10use std::os::fd::{AsRawFd, RawFd};
11use std::path::Path;
12use std::ptr;
13
14/// Linux `MAP_FIXED_NOREPLACE` (do not clobber existing maps).
15#[cfg(target_os = "linux")]
16pub const MAP_FIXED_NOREPLACE: libc::c_int = 0x100_000;
17
18/// Preferred fixed-map flag for this host.
19#[must_use]
20pub fn fixed_map_flag() -> libc::c_int {
21    #[cfg(target_os = "linux")]
22    {
23        MAP_FIXED_NOREPLACE
24    }
25    #[cfg(not(target_os = "linux"))]
26    {
27        libc::MAP_FIXED
28    }
29}
30
31/// Host page size in bytes, or `None` if `sysconf` fails.
32#[must_use]
33pub fn page_size() -> Option<usize> {
34    // SAFETY: `sysconf(_SC_PAGESIZE)` returns a scalar; no memory is touched.
35    let raw = unsafe { libc::sysconf(libc::_SC_PAGESIZE) };
36    if raw <= 0 {
37        return None;
38    }
39    usize::try_from(raw).ok()
40}
41
42/// Physical page count from `sysconf(_SC_PHYS_PAGES)`, when available.
43#[must_use]
44pub fn phys_pages() -> Option<u64> {
45    // SAFETY: scalar sysconf; no memory is touched.
46    let raw = unsafe { libc::sysconf(libc::_SC_PHYS_PAGES) };
47    if raw <= 0 {
48        return None;
49    }
50    u64::try_from(raw).ok()
51}
52
53/// Best-effort host RAM size in bytes.
54#[must_use]
55pub fn phys_mem_bytes() -> u64 {
56    match (phys_pages(), page_size()) {
57        (Some(pages), Some(page)) => {
58            let s = u64::try_from(page).unwrap_or(0);
59            pages.saturating_mul(s).max(64 * 1024 * 1024)
60        }
61        _ => 8 * 1024 * 1024 * 1024, // 8 GiB fallback
62    }
63}
64
65/// Close a host file descriptor. Errors are ignored (best-effort cleanup).
66pub fn close_fd(fd: RawFd) {
67    // SAFETY: caller owned `fd` and will not use it after this call.
68    unsafe {
69        let _ = libc::close(fd);
70    }
71}
72
73/// Duplicate a host fd. Returns the new fd or `None` on failure.
74#[must_use]
75pub fn dup_fd(fd: RawFd) -> Option<RawFd> {
76    // SAFETY: `fd` is a live host descriptor.
77    let rc = unsafe { libc::dup(fd) };
78    if rc < 0 { None } else { Some(rc) }
79}
80
81/// `dup2(old, new)` on the host. Returns `new` or `None` on failure.
82#[must_use]
83pub fn dup2_fd(old: RawFd, new: RawFd) -> Option<RawFd> {
84    // SAFETY: both fds are valid host descriptors for the duration of the call.
85    let rc = unsafe { libc::dup2(old, new) };
86    if rc < 0 { None } else { Some(rc) }
87}
88
89/// Host `fork`. Returns `Ok(pid)` where pid is 0 in the child, or `Err(errno)`.
90pub fn fork_process() -> Result<i32, i32> {
91    // SAFETY: Linux fork; only the calling thread is duplicated.
92    let rc = unsafe { libc::fork() };
93    if rc < 0 {
94        Err(last_errno())
95    } else {
96        Ok(rc)
97    }
98}
99
100/// Host `waitpid`. Returns `(pid, status)` or `Err(errno)`. `pid == 0` with
101/// `WNOHANG` means no child ready.
102pub fn wait_pid(pid: i32, options: i32) -> Result<(i32, i32), i32> {
103    let mut status: libc::c_int = 0;
104    // SAFETY: status is stack-local; waitpid is well-defined.
105    let rc = unsafe { libc::waitpid(pid, &raw mut status, options) };
106    if rc < 0 {
107        Err(last_errno())
108    } else {
109        Ok((rc, status))
110    }
111}
112
113/// Host `execve` with owned C strings (never returns on success).
114///
115/// # Safety
116///
117/// `argv` and `envp` must be NULL-terminated arrays of valid C strings; this
118/// process image is replaced on success.
119pub unsafe fn execve_host(
120    path: &std::ffi::CStr,
121    argv: &[*const libc::c_char],
122    envp: &[*const libc::c_char],
123) -> i32 {
124    // SAFETY: caller guarantees NUL-terminated argv/envp; path is a CStr.
125    let rc = unsafe { libc::execve(path.as_ptr(), argv.as_ptr().cast(), envp.as_ptr().cast()) };
126    let _ = rc;
127    last_errno()
128}
129
130/// Host `posix_spawn` without forking this process's address space.
131///
132/// Prefer this over guest `fork`+`execve` when the parent has large mappings
133/// (CLT tools): CoW of a 100+ MiB guest image is pure tax before the child
134/// replaces itself with nested `kh`.
135///
136/// # Safety
137///
138/// `argv` / `envp` must be NULL-terminated C string pointer arrays (as for
139/// `execve`). On success returns the child pid; on failure returns `Err(errno)`.
140pub unsafe fn posix_spawn_host(
141    path: &std::ffi::CStr,
142    argv: &[*const libc::c_char],
143    envp: &[*const libc::c_char],
144) -> Result<i32, i32> {
145    let mut pid: libc::pid_t = 0;
146    // Linux libc wants `*const *mut c_char`; our slices are `*const *const`.
147    // SAFETY: argv/envp are live NUL-terminated arrays for the duration of the call.
148    let rc = unsafe {
149        libc::posix_spawn(
150            &raw mut pid,
151            path.as_ptr(),
152            core::ptr::null(),
153            core::ptr::null(),
154            argv.as_ptr().cast_mut().cast(),
155            envp.as_ptr().cast_mut().cast(),
156        )
157    };
158    if rc != 0 {
159        Err(rc)
160    } else {
161        Ok(pid)
162    }
163}
164
165fn last_errno() -> i32 {
166    io::Error::last_os_error()
167        .raw_os_error()
168        .unwrap_or(libc::EIO)
169}
170
171fn socklen_of(len: usize) -> Option<libc::socklen_t> {
172    libc::socklen_t::try_from(len).ok()
173}
174
175/// `pipe(2)` — returns `(read_fd, write_fd)` or `None` on failure.
176///
177/// Both ends are set `O_NONBLOCK|O_CLOEXEC`. Freestanding curl/c-ares often
178/// `poll` then `read` the wakeup pipe; a **blocking** host pipe deadlocks the
179/// single-threaded guest when nothing is readable yet (tier1 hang).
180///
181/// Darwin default is blocking; guest-visible semantics are tracked in
182/// [`crate::process::fd_guest_nonblock`]. I/O waits on `EAGAIN` until the guest
183/// sets `O_NONBLOCK` via `fcntl`. Nested helpers also call
184/// [`crate::process::normalize_stdio_pipes_blocking`] so inherited command
185/// pipes behave as Darwin blocking stdin/stdout.
186#[must_use]
187pub fn pipe_fds() -> Option<(RawFd, RawFd)> {
188    let mut fds = [0_i32; 2];
189    // Prefer pipe2 when available (Linux).
190    #[cfg(target_os = "linux")]
191    {
192        // SAFETY: stack buffer of two ints for the kernel to fill.
193        let rc = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_NONBLOCK | libc::O_CLOEXEC) };
194        if rc != 0 {
195            return None;
196        }
197    }
198    #[cfg(not(target_os = "linux"))]
199    {
200        // SAFETY: stack buffer of two ints for the kernel to fill.
201        let rc = unsafe { libc::pipe(fds.as_mut_ptr()) };
202        if rc != 0 {
203            return None;
204        }
205        for fd in fds {
206            set_nonblock(fd);
207            // SAFETY: freshly created pipe ends.
208            unsafe {
209                let _ = libc::fcntl(fd, libc::F_SETFD, libc::FD_CLOEXEC);
210            }
211        }
212    }
213    match (fds.first().copied(), fds.get(1).copied()) {
214        (Some(r), Some(w)) => Some((r, w)),
215        _ => None,
216    }
217}
218
219/// Block until `fd` is readable, hung-up, or errored. `timeout_ms` as in
220/// `poll(2)` (`-1` = forever). Returns `true` if any interesting revent.
221#[must_use]
222pub fn poll_fd_readable(fd: RawFd, timeout_ms: i32) -> bool {
223    poll_fd(fd, libc::POLLIN, timeout_ms)
224}
225
226/// Block until `fd` is writable, hung-up, or errored.
227#[must_use]
228pub fn poll_fd_writable(fd: RawFd, timeout_ms: i32) -> bool {
229    poll_fd(fd, libc::POLLOUT, timeout_ms)
230}
231
232/// Block until `fd` is readable **or** writable (TLS may need both).
233#[must_use]
234pub fn poll_fd_io(fd: RawFd, timeout_ms: i32) -> bool {
235    poll_fd(fd, libc::POLLIN | libc::POLLOUT, timeout_ms)
236}
237
238fn poll_fd(fd: RawFd, events: libc::c_short, timeout_ms: i32) -> bool {
239    let mut pfd = libc::pollfd {
240        fd,
241        events,
242        revents: 0,
243    };
244    loop {
245        // SAFETY: single pollfd on the stack; fd is a live host descriptor.
246        let rc = unsafe { libc::poll(&raw mut pfd, 1, timeout_ms) };
247        if rc < 0 {
248            let err = io::Error::last_os_error()
249                .raw_os_error()
250                .unwrap_or(0);
251            if err == libc::EINTR {
252                continue;
253            }
254            return false;
255        }
256        if rc == 0 {
257            return false;
258        }
259        let interest = events | libc::POLLHUP | libc::POLLERR | libc::POLLNVAL;
260        return pfd.revents & interest != 0;
261    }
262}
263
264/// Mark a host fd non-blocking (best-effort).
265fn set_nonblock(fd: RawFd) {
266    // SAFETY: live fd from socket/accept/pipe.
267    unsafe {
268        let fl = libc::fcntl(fd, libc::F_GETFL);
269        if fl >= 0 {
270            let _ = libc::fcntl(fd, libc::F_SETFL, fl | libc::O_NONBLOCK);
271        }
272    }
273}
274
275/// Clear host `O_NONBLOCK` (best-effort). Used for nested-helper stdio pipes.
276pub fn clear_nonblock(fd: RawFd) {
277    // SAFETY: live fd.
278    unsafe {
279        let fl = libc::fcntl(fd, libc::F_GETFL);
280        if fl >= 0 {
281            let _ = libc::fcntl(fd, libc::F_SETFL, fl & !libc::O_NONBLOCK);
282        }
283    }
284}
285
286/// `true` when `fd` is a FIFO/pipe (`S_IFIFO`).
287#[must_use]
288pub fn fd_is_fifo(fd: RawFd) -> bool {
289    // SAFETY: fstat on a live fd.
290    unsafe {
291        let mut st: libc::stat = core::mem::zeroed();
292        if libc::fstat(fd, &raw mut st) != 0 {
293            return false;
294        }
295        (st.st_mode & libc::S_IFMT) == libc::S_IFIFO
296    }
297}
298
299/// `socket(domain, type, protocol)` — host libc. Returns host fd or `None`.
300///
301/// Sockets are forced `O_NONBLOCK`. Curl/c-ares (and the multi interface)
302/// expect non-blocking I/O; a blocking `recv` on a keep-alive TCP socket after
303/// the response body is complete hangs the guest forever (clean-exit G3).
304#[must_use]
305pub fn socket(domain: libc::c_int, ty: libc::c_int, protocol: libc::c_int) -> Option<RawFd> {
306    // SAFETY: standard socket(2). Strip Darwin-only type flags if any sneak in;
307    // Linux SOCK_NONBLOCK/CLOEXEC bits differ and are applied via fcntl below.
308    let ty_plain = ty & 0xf;
309    let rc = unsafe { libc::socket(domain, ty_plain, protocol) };
310    if rc < 0 {
311        return None;
312    }
313    set_nonblock(rc);
314    // SAFETY: freshly created socket.
315    unsafe {
316        let _ = libc::fcntl(rc, libc::F_SETFD, libc::FD_CLOEXEC);
317    }
318    Some(rc)
319}
320
321/// `socketpair(domain, type, protocol, sv[2])`.
322pub fn socketpair(
323    domain: libc::c_int,
324    ty: libc::c_int,
325    protocol: libc::c_int,
326) -> Option<(RawFd, RawFd)> {
327    let mut sv = [0_i32; 2];
328    let ty_plain = ty & 0xf;
329    // SAFETY: stack pair for the kernel to fill.
330    let rc = unsafe { libc::socketpair(domain, ty_plain, protocol, sv.as_mut_ptr()) };
331    if rc != 0 {
332        return None;
333    }
334    set_nonblock(sv[0]);
335    set_nonblock(sv[1]);
336    // SAFETY: freshly created sockets.
337    unsafe {
338        let _ = libc::fcntl(sv[0], libc::F_SETFD, libc::FD_CLOEXEC);
339        let _ = libc::fcntl(sv[1], libc::F_SETFD, libc::FD_CLOEXEC);
340    }
341    Some((sv[0], sv[1]))
342}
343
344/// `connect(fd, sockaddr_bytes)`.
345pub fn connect(fd: RawFd, addr: &[u8]) -> Result<(), i32> {
346    let Some(len) = socklen_of(addr.len()) else {
347        return Err(libc::EINVAL);
348    };
349    // SAFETY: `addr` is a valid host buffer for `len` bytes.
350    let rc = unsafe { libc::connect(fd, addr.as_ptr().cast(), len) };
351    if rc == 0 { Ok(()) } else { Err(last_errno()) }
352}
353
354/// `bind(fd, sockaddr_bytes)`.
355pub fn bind(fd: RawFd, addr: &[u8]) -> Result<(), i32> {
356    let Some(len) = socklen_of(addr.len()) else {
357        return Err(libc::EINVAL);
358    };
359    // SAFETY: `addr` is a valid host buffer for `len` bytes.
360    let rc = unsafe { libc::bind(fd, addr.as_ptr().cast(), len) };
361    if rc == 0 { Ok(()) } else { Err(last_errno()) }
362}
363
364/// `listen(fd, backlog)`.
365pub fn listen(fd: RawFd, backlog: libc::c_int) -> Result<(), i32> {
366    // SAFETY: live socket fd.
367    let rc = unsafe { libc::listen(fd, backlog) };
368    if rc == 0 { Ok(()) } else { Err(last_errno()) }
369}
370
371/// `accept(fd)` — peer address discarded (curl client path rarely needs it).
372pub fn accept(fd: RawFd) -> Result<RawFd, i32> {
373    // SAFETY: live listening socket; null addr is allowed by accept(2).
374    let rc = unsafe { libc::accept(fd, ptr::null_mut(), ptr::null_mut()) };
375    if rc < 0 {
376        Err(last_errno())
377    } else {
378        set_nonblock(rc);
379        Ok(rc)
380    }
381}
382
383/// `accept` with peer sockaddr written into `addr_out` (truncated to buffer len).
384///
385/// Returns `(new_fd, bytes_written_into_addr_out)`.
386pub fn accept_addr(fd: RawFd, addr_out: &mut [u8]) -> Result<(RawFd, usize), i32> {
387    let mut alen = socklen_of(addr_out.len()).unwrap_or(0);
388    // SAFETY: live socket; `addr_out` is writable for `alen` bytes.
389    let rc = unsafe {
390        libc::accept(
391            fd,
392            addr_out.as_mut_ptr().cast(),
393            ptr::addr_of_mut!(alen),
394        )
395    };
396    if rc < 0 {
397        return Err(last_errno());
398    }
399    set_nonblock(rc);
400    let n = usize::try_from(alen).unwrap_or(0).min(addr_out.len());
401    Ok((rc, n))
402}
403
404/// `setsockopt(fd, level, optname, value_bytes)`.
405pub fn setsockopt(
406    fd: RawFd,
407    level: libc::c_int,
408    optname: libc::c_int,
409    value: &[u8],
410) -> Result<(), i32> {
411    let Some(len) = socklen_of(value.len()) else {
412        return Err(libc::EINVAL);
413    };
414    // SAFETY: live socket; value buffer valid for `len` bytes.
415    let rc = unsafe {
416        libc::setsockopt(
417            fd,
418            level,
419            optname,
420            value.as_ptr().cast(),
421            len,
422        )
423    };
424    if rc == 0 { Ok(()) } else { Err(last_errno()) }
425}
426
427/// `getsockopt` — writes into `value`, returns updated length.
428pub fn getsockopt(
429    fd: RawFd,
430    level: libc::c_int,
431    optname: libc::c_int,
432    value: &mut [u8],
433) -> Result<usize, i32> {
434    let mut len = socklen_of(value.len()).unwrap_or(0);
435    // SAFETY: live socket; value buffer writable.
436    let rc = unsafe {
437        libc::getsockopt(
438            fd,
439            level,
440            optname,
441            value.as_mut_ptr().cast(),
442            ptr::addr_of_mut!(len),
443        )
444    };
445    if rc == 0 {
446        Ok(usize::try_from(len).unwrap_or(0).min(value.len()))
447    } else {
448        Err(last_errno())
449    }
450}
451
452/// `shutdown(fd, how)`.
453pub fn shutdown(fd: RawFd, how: libc::c_int) -> Result<(), i32> {
454    // SAFETY: live socket fd.
455    let rc = unsafe { libc::shutdown(fd, how) };
456    if rc == 0 { Ok(()) } else { Err(last_errno()) }
457}
458
459/// `sendto` / `send` — optional peer address bytes.
460pub fn sendto(
461    fd: RawFd,
462    buf: &[u8],
463    flags: libc::c_int,
464    addr: Option<&[u8]>,
465) -> Result<usize, i32> {
466    let (ap, alen) = if let Some(a) = addr {
467        let Some(len) = socklen_of(a.len()) else {
468            return Err(libc::EINVAL);
469        };
470        (a.as_ptr().cast(), len)
471    } else {
472        (ptr::null(), 0)
473    };
474    // SAFETY: live fd; buffer valid; optional sockaddr.
475    let n = unsafe { libc::sendto(fd, buf.as_ptr().cast(), buf.len(), flags, ap, alen) };
476    if n < 0 {
477        Err(last_errno())
478    } else {
479        usize::try_from(n).map_err(|_| libc::EIO)
480    }
481}
482
483/// `recvfrom` / `recv` — optional peer address out-buffer.
484///
485/// Returns `(bytes_read, peer_addr_len)` when `addr_out` is `Some`.
486pub fn recvfrom(
487    fd: RawFd,
488    buf: &mut [u8],
489    flags: libc::c_int,
490    addr_out: Option<&mut [u8]>,
491) -> Result<(usize, usize), i32> {
492    let (n, peer_len) = if let Some(a) = addr_out {
493        let mut alen = socklen_of(a.len()).unwrap_or(0);
494        // SAFETY: live fd; buffers valid.
495        let n = unsafe {
496            libc::recvfrom(
497                fd,
498                buf.as_mut_ptr().cast(),
499                buf.len(),
500                flags,
501                a.as_mut_ptr().cast(),
502                ptr::addr_of_mut!(alen),
503            )
504        };
505        (n, usize::try_from(alen).unwrap_or(0).min(a.len()))
506    } else {
507        // SAFETY: live fd; buffer valid; null peer.
508        let n = unsafe {
509            libc::recvfrom(
510                fd,
511                buf.as_mut_ptr().cast(),
512                buf.len(),
513                flags,
514                ptr::null_mut(),
515                ptr::null_mut(),
516            )
517        };
518        (n, 0)
519    };
520    if n < 0 {
521        Err(last_errno())
522    } else {
523        let nr = usize::try_from(n).map_err(|_| libc::EIO)?;
524        Ok((nr, peer_len))
525    }
526}
527
528/// `getsockname(fd, addr_out)`.
529pub fn getsockname(fd: RawFd, addr_out: &mut [u8]) -> Result<usize, i32> {
530    let mut alen = socklen_of(addr_out.len()).unwrap_or(0);
531    // SAFETY: live socket; buffer writable for `alen` bytes.
532    let rc = unsafe {
533        libc::getsockname(fd, addr_out.as_mut_ptr().cast(), ptr::addr_of_mut!(alen))
534    };
535    if rc == 0 {
536        Ok(usize::try_from(alen).unwrap_or(0).min(addr_out.len()))
537    } else {
538        Err(last_errno())
539    }
540}
541
542/// `getpeername(fd, addr_out)`.
543pub fn getpeername(fd: RawFd, addr_out: &mut [u8]) -> Result<usize, i32> {
544    let mut alen = socklen_of(addr_out.len()).unwrap_or(0);
545    // SAFETY: live socket; buffer writable for `alen` bytes.
546    let rc = unsafe {
547        libc::getpeername(fd, addr_out.as_mut_ptr().cast(), ptr::addr_of_mut!(alen))
548    };
549    if rc == 0 {
550        Ok(usize::try_from(alen).unwrap_or(0).min(addr_out.len()))
551    } else {
552        Err(last_errno())
553    }
554}
555
556/// `poll(fds, timeout_ms)` — empty slice sleeps / checks timeout only.
557pub fn poll(fds: &mut [libc::pollfd], timeout: libc::c_int) -> Result<i32, i32> {
558    let nfds = libc::nfds_t::try_from(fds.len()).unwrap_or(0);
559    // SAFETY: `fds` is a valid pollfd array of `nfds` entries (or empty).
560    let rc = unsafe {
561        libc::poll(
562            if fds.is_empty() {
563                ptr::null_mut()
564            } else {
565                fds.as_mut_ptr()
566            },
567            nfds,
568            timeout,
569        )
570    };
571    if rc < 0 { Err(last_errno()) } else { Ok(rc) }
572}
573
574/// `lseek` on a host fd.
575pub fn lseek_fd(fd: RawFd, offset: i64, whence: libc::c_int) -> Option<i64> {
576    // SAFETY: live fd; whence is a SEEK_* constant.
577    let rc = unsafe { libc::lseek(fd, offset, whence) };
578    if rc < 0 { None } else { Some(rc) }
579}
580
581/// `fcntl` with no extra arg (`F_GETFD` / `F_GETFL`).
582pub fn fcntl_get(fd: RawFd, cmd: libc::c_int) -> Option<i32> {
583    // SAFETY: live fd; cmd is a valid fcntl command.
584    let rc = unsafe { libc::fcntl(fd, cmd) };
585    if rc < 0 { None } else { Some(rc) }
586}
587
588/// `fcntl` with one integer arg (`F_SETFD` / `F_SETFL` / `F_DUPFD`).
589pub fn fcntl_set(fd: RawFd, cmd: libc::c_int, arg: libc::c_int) -> Option<i32> {
590    // SAFETY: live fd; cmd/arg match the fcntl ABI.
591    let rc = unsafe { libc::fcntl(fd, cmd, arg) };
592    if rc < 0 { None } else { Some(rc) }
593}
594
595/// `open(path, flags, mode)` — prefers libc over `std::fs::OpenOptions` so
596/// directories open with `O_RDONLY` (archive walks) and we avoid extra syscalls.
597pub fn open_path(path: &std::ffi::CStr, flags: libc::c_int, mode: libc::c_uint) -> Option<RawFd> {
598    // SAFETY: path is a valid C string for the duration of the call.
599    let rc = unsafe { libc::open(path.as_ptr(), flags, mode) };
600    if rc < 0 { None } else { Some(rc) }
601}
602
603/// Open a directory as `O_RDONLY|O_DIRECTORY|O_CLOEXEC` (bottle root dirfd, B1).
604pub fn open_directory(path: &std::ffi::CStr) -> Option<RawFd> {
605    open_path(
606        path,
607        libc::O_RDONLY | libc::O_DIRECTORY | libc::O_CLOEXEC,
608        0,
609    )
610}
611
612/// `openat(dirfd, path, flags, mode)`.
613pub fn openat(
614    dirfd: RawFd,
615    path: &std::ffi::CStr,
616    flags: libc::c_int,
617    mode: libc::c_uint,
618) -> Option<RawFd> {
619    // SAFETY: dirfd live; path is a valid C string for the duration of the call.
620    let rc = unsafe { libc::openat(dirfd, path.as_ptr(), flags, mode) };
621    if rc < 0 { None } else { Some(rc) }
622}
623
624/// `mkdirat(dirfd, path, mode)` — returns `Ok(())` on success or `EEXIST`.
625pub fn mkdirat(dirfd: RawFd, path: &std::ffi::CStr, mode: libc::mode_t) -> io::Result<()> {
626    // SAFETY: dirfd live; path is a valid C string for the duration of the call.
627    let rc = unsafe { libc::mkdirat(dirfd, path.as_ptr(), mode) };
628    if rc == 0 {
629        return Ok(());
630    }
631    let err = io::Error::last_os_error();
632    if err.raw_os_error() == Some(libc::EEXIST) {
633        Ok(())
634    } else {
635        Err(err)
636    }
637}
638
639/// `fstatat(dirfd, path, …)` — used by B1 bottle-relative `stat`/`lstat`.
640pub fn fstatat(dirfd: RawFd, path: &std::ffi::CStr, no_follow: bool) -> Option<libc::stat> {
641    let mut st: libc::stat = unsafe { std::mem::zeroed() };
642    let flags = if no_follow {
643        libc::AT_SYMLINK_NOFOLLOW
644    } else {
645        0
646    };
647    // SAFETY: dirfd live; path valid C string; stack `stat` buffer.
648    let rc = unsafe { libc::fstatat(dirfd, path.as_ptr(), std::ptr::addr_of_mut!(st), flags) };
649    if rc == 0 { Some(st) } else { None }
650}
651
652/// `faccessat(dirfd, path, F_OK, 0)` — existence check without full path build.
653pub fn faccessat_ok(dirfd: RawFd, path: &std::ffi::CStr) -> bool {
654    // SAFETY: dirfd live; path valid C string.
655    let rc = unsafe { libc::faccessat(dirfd, path.as_ptr(), libc::F_OK, 0) };
656    rc == 0
657}
658
659/// Write bytes to a host fd (`write(2)`).
660pub fn write_fd(fd: RawFd, data: &[u8]) -> io::Result<usize> {
661    if data.is_empty() {
662        return Ok(0);
663    }
664    // SAFETY: fd live; buffer valid for `data.len()` bytes.
665    let n = unsafe { libc::write(fd, data.as_ptr().cast(), data.len()) };
666    if n < 0 {
667        return Err(io::Error::last_os_error());
668    }
669    usize::try_from(n).map_err(|_| io::Error::other("write returned out-of-range count"))
670}
671
672/// Read bytes from a host fd (`read(2)`).
673pub fn read_fd(fd: RawFd, buf: &mut [u8]) -> io::Result<usize> {
674    if buf.is_empty() {
675        return Ok(0);
676    }
677    // SAFETY: fd live; buffer valid for `buf.len()` bytes.
678    let n = unsafe { libc::read(fd, buf.as_mut_ptr().cast(), buf.len()) };
679    if n < 0 {
680        return Err(io::Error::last_os_error());
681    }
682    usize::try_from(n).map_err(|_| io::Error::other("read returned out-of-range count"))
683}
684
685/// `fstat` into a host `stat` buffer.
686pub fn fstat_fd(fd: RawFd) -> Option<libc::stat> {
687    // SAFETY: live fd; stack buffer is valid for the duration of the call.
688    let mut st: libc::stat = unsafe { std::mem::zeroed() };
689    let rc = unsafe { libc::fstat(fd, std::ptr::addr_of_mut!(st)) };
690    if rc == 0 { Some(st) } else { None }
691}
692
693/// `ftruncate(fd, length)`.
694pub fn ftruncate_fd(fd: RawFd, length: i64) -> Option<()> {
695    // SAFETY: live fd.
696    let rc = unsafe { libc::ftruncate(fd, length) };
697    if rc == 0 { Some(()) } else { None }
698}
699
700/// `fchmod(fd, mode)` — needed so guest `ld` can mark products executable.
701pub fn fchmod_fd(fd: RawFd, mode: u32) -> Option<()> {
702    let mode = libc::mode_t::try_from(mode).unwrap_or(0);
703    // SAFETY: live fd; mode is Darwin permission bits (subset of POSIX).
704    let rc = unsafe { libc::fchmod(fd, mode) };
705    if rc == 0 { Some(()) } else { None }
706}
707
708/// `fsync(fd)`.
709pub fn fsync_fd(fd: RawFd) -> Option<()> {
710    // SAFETY: live fd.
711    let rc = unsafe { libc::fsync(fd) };
712    if rc == 0 { Some(()) } else { None }
713}
714
715/// `readlink(path)` into `buf` (no trailing NUL). Returns bytes written or host errno.
716pub fn readlink_path(path: &std::ffi::CStr, buf: &mut [u8]) -> Result<usize, i32> {
717    if buf.is_empty() {
718        return Ok(0);
719    }
720    // SAFETY: path is a valid C string; buffer is writable for `buf.len()`.
721    let n = unsafe { libc::readlink(path.as_ptr(), buf.as_mut_ptr().cast(), buf.len()) };
722    if n < 0 {
723        return Err(io::Error::last_os_error()
724            .raw_os_error()
725            .unwrap_or(libc::EIO));
726    }
727    usize::try_from(n).map_err(|_| libc::EIO)
728}
729
730/// `symlink(target, linkpath)`.
731pub fn symlink_path(target: &std::ffi::CStr, linkpath: &std::ffi::CStr) -> Result<(), i32> {
732    // SAFETY: both are valid C strings for the duration of the call.
733    let rc = unsafe { libc::symlink(target.as_ptr(), linkpath.as_ptr()) };
734    if rc == 0 {
735        Ok(())
736    } else {
737        Err(io::Error::last_os_error()
738            .raw_os_error()
739            .unwrap_or(libc::EIO))
740    }
741}
742
743/// `link(existing, newpath)` hard link.
744pub fn link_path(existing: &std::ffi::CStr, newpath: &std::ffi::CStr) -> Result<(), i32> {
745    // SAFETY: both are valid C strings for the duration of the call.
746    let rc = unsafe { libc::link(existing.as_ptr(), newpath.as_ptr()) };
747    if rc == 0 {
748        Ok(())
749    } else {
750        Err(io::Error::last_os_error()
751            .raw_os_error()
752            .unwrap_or(libc::EIO))
753    }
754}
755
756/// Host `gettimeofday` (timezone ignored).
757pub fn gettimeofday() -> Option<libc::timeval> {
758    // SAFETY: stack timeval; null tz pointer is allowed.
759    let mut tv: libc::timeval = unsafe { std::mem::zeroed() };
760    let rc = unsafe { libc::gettimeofday(std::ptr::addr_of_mut!(tv), ptr::null_mut()) };
761    if rc == 0 { Some(tv) } else { None }
762}
763
764/// Host `clock_gettime`.
765pub fn clock_gettime(clock_id: libc::clockid_t) -> Option<libc::timespec> {
766    // SAFETY: stack timespec; clock_id is a host constant.
767    let mut ts: libc::timespec = unsafe { std::mem::zeroed() };
768    let rc = unsafe { libc::clock_gettime(clock_id, std::ptr::addr_of_mut!(ts)) };
769    if rc == 0 { Some(ts) } else { None }
770}
771
772/// Read-only file-backed mapping of an entire file (lazy page faults).
773///
774/// Used by the loader to parse and fill guest segments without
775/// `fs::read` of multi‑hundred‑MiB containers (demand-paged I/O).
776///
777/// Dropping unmaps the range. Safe for concurrent shared reads only while
778/// this owner is alive (not `Sync`; single-threaded load path).
779pub struct MappedFile {
780    ptr: *mut u8,
781    len: usize,
782}
783
784impl std::fmt::Debug for MappedFile {
785    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
786        f.debug_struct("MappedFile")
787            .field("len", &self.len)
788            .finish_non_exhaustive()
789    }
790}
791
792// SAFETY: unique owner of the mapping; no interior mutation after create.
793unsafe impl Send for MappedFile {}
794
795impl MappedFile {
796    /// `mmap` the whole file `PROT_READ` / `MAP_PRIVATE`. Empty files yield a
797    /// zero-length mapping (`as_slice` is empty).
798    pub fn open(path: &Path) -> io::Result<Self> {
799        let file = File::open(path)?;
800        let len_u64 = file.metadata()?.len();
801        let len = usize::try_from(len_u64).map_err(|_| {
802            io::Error::new(io::ErrorKind::InvalidData, "file too large to map")
803        })?;
804        if len == 0 {
805            return Ok(Self {
806                ptr: ptr::null_mut(),
807                len: 0,
808            });
809        }
810        let fd = file.as_raw_fd();
811        // Lazy faults: do **not** use MAP_POPULATE — parse only needs headers;
812        // segment fill touches only file-backed ranges.
813        let Some(base) = mmap(
814            None,
815            len,
816            libc::PROT_READ,
817            libc::MAP_PRIVATE,
818            fd,
819            0,
820        ) else {
821            return Err(io::Error::last_os_error());
822        };
823        // Mapping keeps its own reference; fd may close with `file` drop.
824        Ok(Self { ptr: base, len })
825    }
826
827    /// Byte view of the mapped file (or empty).
828    #[must_use]
829    pub fn as_slice(&self) -> &[u8] {
830        if self.ptr.is_null() || self.len == 0 {
831            return &[];
832        }
833        // SAFETY: mapping is live, PROT_READ, length is exact file size.
834        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
835    }
836
837    /// Mapped length in bytes.
838    #[must_use]
839    pub const fn len(&self) -> usize {
840        self.len
841    }
842
843    /// Whether the file was empty.
844    #[must_use]
845    pub const fn is_empty(&self) -> bool {
846        self.len == 0
847    }
848}
849
850impl Drop for MappedFile {
851    fn drop(&mut self) {
852        if !self.ptr.is_null() && self.len > 0 {
853            let _ = munmap(self.ptr, self.len);
854            self.ptr = ptr::null_mut();
855            self.len = 0;
856        }
857    }
858}
859
860/// Anonymous or file-backed `mmap`. Returns host base or `None` on failure.
861///
862/// When `fixed_addr` is `Some(va)`, the call uses that as the address hint
863/// (combine with [`fixed_map_flag`] / `MAP_FIXED` as appropriate).
864#[must_use]
865pub fn mmap(
866    fixed_addr: Option<u64>,
867    len: usize,
868    prot: libc::c_int,
869    flags: libc::c_int,
870    fd: RawFd,
871    offset: i64,
872) -> Option<*mut u8> {
873    if len == 0 {
874        return None;
875    }
876    let addr = fixed_addr.map_or(ptr::null_mut(), u64_as_void_ptr);
877    // SAFETY: length non-zero; flags/prot valid combinations; fd matches flags;
878    // `addr` is either null or a page-aligned VA for fixed placement.
879    let raw = unsafe { libc::mmap(addr, len, prot, flags, fd, offset) };
880    if raw == libc::MAP_FAILED {
881        None
882    } else {
883        Some(raw.cast())
884    }
885}
886
887/// `munmap` a mapping previously returned by [`mmap`].
888pub fn munmap(ptr: *mut u8, len: usize) -> bool {
889    if ptr.is_null() || len == 0 {
890        return true;
891    }
892    // SAFETY: ptr/len came from a successful mmap owned by the caller.
893    let rc = unsafe { libc::munmap(ptr.cast(), len) };
894    rc == 0
895}
896
897/// `mprotect` on a host mapping range.
898pub fn mprotect(ptr: *mut u8, len: usize, prot: libc::c_int) -> bool {
899    if ptr.is_null() || len == 0 {
900        return true;
901    }
902    // SAFETY: range is a live mapping owned by the caller.
903    let rc = unsafe { libc::mprotect(ptr.cast(), len, prot) };
904    rc == 0
905}
906
907/// `msync` on a host mapping range.
908pub fn msync(ptr: *mut u8, len: usize, flags: libc::c_int) -> bool {
909    if ptr.is_null() || len == 0 {
910        return true;
911    }
912    // SAFETY: range is a live mapping; flags are MS_* bits.
913    let rc = unsafe { libc::msync(ptr.cast(), len, flags) };
914    rc == 0
915}
916
917/// Pointer address as `u64` (identity guest/host model helpers).
918#[must_use]
919pub fn ptr_addr_u64(p: *mut u8) -> u64 {
920    u64::try_from(p.addr()).unwrap_or(0)
921}
922
923/// `u64` address → void pointer (fixed mmap hints).
924#[must_use]
925pub fn u64_as_void_ptr(addr: u64) -> *mut libc::c_void {
926    let u = usize::try_from(addr).unwrap_or(0);
927    ptr::with_exposed_provenance_mut::<u8>(u).cast()
928}
929
930// ── directory streams (for guest readdir) ───────────────────────────────────
931
932/// Opaque host directory stream (`DIR*`).
933#[derive(Debug)]
934pub struct HostDir {
935    ptr: *mut libc::DIR,
936}
937
938// SAFETY: process-wide guest model serializes dir mutation under ProcessState
939// write lock; readers never touch `HostDir`.
940unsafe impl Send for HostDir {}
941// SAFETY: same as `Send` — exclusive dir use under write lock only.
942unsafe impl Sync for HostDir {}
943
944impl HostDir {
945    /// Open a directory stream on a **duplicate** of `host_fd` (does not own `host_fd`).
946    pub fn open_dup(host_fd: RawFd) -> Result<Self, i32> {
947        // SAFETY: dup of a live host FD.
948        let dup = unsafe { libc::dup(host_fd) };
949        if dup < 0 {
950            return Err(last_errno_i32());
951        }
952        // SAFETY: fdopendir takes ownership of `dup`.
953        let dir = unsafe { libc::fdopendir(dup) };
954        if dir.is_null() {
955            let err = last_errno_i32();
956            // SAFETY: close the unused dup on failure.
957            unsafe {
958                libc::close(dup);
959            }
960            return Err(err);
961        }
962        Ok(Self { ptr: dir })
963    }
964
965    /// Next entry: `(name_bytes, d_type)`. `None` at end of stream.
966    pub fn read_next(&mut self) -> Option<(Vec<u8>, u8)> {
967        use std::ffi::CStr;
968        loop {
969            // SAFETY: `ptr` from fdopendir; readdir is the iterator.
970            let ent = unsafe { libc::readdir(self.ptr) };
971            if ent.is_null() {
972                return None;
973            }
974            // SAFETY: ent valid until next readdir/closedir.
975            let d_type = unsafe { (*ent).d_type };
976            let name_ptr = unsafe { (*ent).d_name.as_ptr() };
977            let name = unsafe { CStr::from_ptr(name_ptr) };
978            let bytes = name.to_bytes().to_vec();
979            if bytes.is_empty() {
980                continue;
981            }
982            return Some((bytes, d_type));
983        }
984    }
985}
986
987impl Drop for HostDir {
988    fn drop(&mut self) {
989        if !self.ptr.is_null() {
990            // SAFETY: owns DIR* from fdopendir.
991            unsafe {
992                let _ = libc::closedir(self.ptr);
993            }
994            self.ptr = ptr::null_mut();
995        }
996    }
997}
998
999fn last_errno_i32() -> i32 {
1000    let raw = io::Error::last_os_error()
1001        .raw_os_error()
1002        .unwrap_or(1)
1003        .unsigned_abs();
1004    i32::try_from(raw).unwrap_or(1)
1005}