hermit-detcore 0.5.0

Detcore: the deterministic scheduler and syscall determinization core of the Hermit execution engine.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

//! Widely useful small utilities.

use std::sync::OnceLock;
use std::sync::atomic::AtomicU64;
use std::sync::atomic::Ordering;
use std::time::Duration;

use crate::types::NANOS_PER_RCB;

/// Issues syscall `number` with `args` through the syscall instruction itself
/// on x86-64, returning the kernel's result (a negative errno on failure).
/// Under in-guest LiteInst Detcore runs inside the guest, where libc's
/// wrappers (`open`, `fstat`, `syscall`, ...) are dynamic symbols the program
/// or a preloaded library may define, and allocate in.
///
/// # Safety
///
/// As for the syscall itself: pointer arguments must be valid for it.
pub unsafe fn raw_syscall(number: libc::c_long, args: [u64; 6]) -> i64 {
    #[cfg(target_arch = "x86_64")]
    {
        let result: i64;
        // SAFETY: the caller vouches for the arguments.
        unsafe {
            core::arch::asm!(
                "syscall",
                inlateout("rax") number => result,
                in("rdi") args[0],
                in("rsi") args[1],
                in("rdx") args[2],
                in("r10") args[3],
                in("r8") args[4],
                in("r9") args[5],
                lateout("rcx") _,
                lateout("r11") _,
                options(nostack),
            );
        }
        result
    }
    #[cfg(not(target_arch = "x86_64"))]
    {
        // SAFETY: the caller vouches for the arguments.
        let result =
            unsafe { libc::syscall(number, args[0], args[1], args[2], args[3], args[4], args[5]) };
        if result < 0 {
            -i64::from(
                std::io::Error::last_os_error()
                    .raw_os_error()
                    .unwrap_or(libc::EIO),
            )
        } else {
            result
        }
    }
}

/// [`raw_syscall`]'s result as an `io::Result`.
pub fn raw_result(result: i64) -> std::io::Result<u64> {
    if (-4095..0).contains(&result) {
        Err(std::io::Error::from_raw_os_error(-result as i32))
    } else {
        Ok(result as u64)
    }
}

/// [`raw_syscall`]'s result for a syscall whose only success value is 0
/// (`fstat`, `pipe2`, `socketpair`, ...): any other value is refused, a
/// negative one as the error it names. [`raw_result`] would take a positive
/// return as success, which for such a call the kernel never gives.
pub fn raw_zero_result(result: i64) -> std::io::Result<()> {
    match raw_result(result)? {
        0 => Ok(()),
        other => Err(std::io::Error::other(format!(
            "a syscall that returns 0 on success returned {other}"
        ))),
    }
}

/// Describes `error` without asking the C library for an errno message.
///
/// `std::io::Error`'s `Display` and `Debug` render an operating-system error
/// through `strerror_r`, which can call `gettext` and allocate through the C
/// library's malloc: under in-guest LiteInst, where Detcore runs inside the
/// guest, the guest's own heap. An operating-system error is described by its
/// kind and number instead; any other error, or an I/O error wrapping one, as
/// before.
pub fn describe_io_error(error: &std::io::Error) -> String {
    if let Some(code) = error.raw_os_error() {
        return format!("{:?} (errno {code})", error.kind());
    }
    match error
        .get_ref()
        .and_then(|inner| inner.downcast_ref::<std::io::Error>())
    {
        Some(inner) => describe_io_error(inner),
        None => error.to_string(),
    }
}

#[allow(dead_code)]
/// A simple debugging helper function that makes it easy to printf-debug through
/// layers of stdout/stderr caputure, such as when running under buck test/tpx.
pub fn punch_out_print(msg: &str) {
    use std::io::Write;
    // TODO: if we want this to be more performant, we can have a lazy static
    // global file handle for this. This, however, keeps it simple for occasional usage.œ
    if let Ok(mut tty) = std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .open("/dev/tty")
    {
        writeln!(tty, "{}", msg).unwrap();
    } else {
        // If devtty doesn't exist, we just use stderr.
        eprintln!("{}", msg);
    }
}
/// A helper function to convert a number of Retired Conditional Branches (RCBS) into
/// a `std::time::Duration` via the `NANOS_PER_RCB` defined in ` types.rs`.
pub fn rcbs_to_duration(rcbs: u64) -> Duration {
    Duration::from_nanos((rcbs as f64 * NANOS_PER_RCB) as u64)
}

/// A little better than the builtin string truncation in format strings, because it includes ellipses.
// TODO: There should be some advanced solution for printing potentially huge things that
// doesn't actually render them all...
pub fn truncated(width: usize, mut s: String) -> String {
    if s.len() > width {
        if width >= 3 {
            s.truncate(width - 3);
            s.push_str("...");
            s
        } else {
            s.truncate(width);
            s
        }
    } else {
        s
    }
}

/// A `Write` for the supervisor's own diagnostics on fd 2 that survives a
/// NONBLOCKING description.
///
/// ⚠️ THE GUEST CAN SET `O_NONBLOCK` ON HERMIT'S STDERR AND SILENTLY CUT THE
/// SUPERVISOR'S ERROR CHANNEL. fd 2 is an INHERITED open file description shared
/// with the guest, so `fcntl(2, F_SETFL, O_NONBLOCK)` in the guest changes the
/// behaviour of hermit's OWN later writes. Measured 2026-08-26 on a 4096-byte
/// pipe under back-pressure, `hermit --log info run -- <guest>`:
///
/// ```text
///   control guest (touches nothing)   rc=0    138 lines, ends on the run summary
///   guest sets O_NONBLOCK on fd 2     rc=101  134 lines, ends mid-log
/// ```
///
/// The summary was emitted by `eprint!`, which calls `write_all`; `write_all`
/// does NOT retry `EAGAIN`, so it returns an error and the print macro PANICS.
/// The panic message then went to the same full pipe and was lost as well, so
/// the delivered output contained no panic text, no error, and no marker of any
/// kind -- it simply stopped on a plausible-looking line. Exit 101 was the only
/// surviving evidence, and a caller that reads output rather than status sees a
/// short report, not a truncated one.
///
/// ⚠️ WAIT, DO NOT SPIN, AND DO NOT CLEAR THE FLAG. Clearing `O_NONBLOCK` would
/// change what the guest observes on a descriptor it legitimately shares; this
/// leaves the flag exactly as the guest set it and simply waits for the pipe to
/// drain, which is what a blocking write would have done. A bare retry loop
/// would busy-spin against a full pipe, so it blocks in `poll(POLLOUT)`.
pub struct RetryingStderr;

/// Total wall-clock ALL diagnostic writes in ONE PROCESS may spend waiting for a
/// reader that is not draining. Hermit forks, so read the fork note below before
/// treating this as the whole exit path's budget.
///
/// ⚠️ WITHOUT A CEILING THIS LOOP NEVER ENDS, AND IT RUNS WHILE HERMIT IS ALREADY
/// FAILING. `EAGAIN` -> `poll(POLLOUT, 1s)` -> retry is correct for a reader that
/// is SLOW and unbounded for a reader that is STOPPED. Measured 2026-08-26 on a
/// 4096-byte pipe filled to 3900 with `O_NONBLOCK` set, where nothing ever reads:
///
/// ```text
///   before RetryingStderr (eprintln!)   EXITED rc=101 immediately
///   RetryingStderr, no ceiling          STILL RUNNING after 25s, no exit
/// ```
///
/// The first is wrong loudly; the second does not return at all, on the path that
/// reports why hermit is stopping. A supervisor that hangs while reporting an
/// error is harder to diagnose than one that dies reporting it badly.
///
/// ⚠️ THIS IS A TOTAL FOR THE WHOLE PROCESS, NOT A BUDGET PER `write()` CALL, AND
/// THE DIFFERENCE IS THE ENTIRE GUARANTEE. An earlier version started the clock
/// inside `fn write`, so every call got the full allowance. Nothing writes to
/// stderr exactly once on the exit path:
///
/// ```text
///   hermit-cli/src/bin/hermit/main.rs      the failure class, the head of the
///                                          error chain, then ONE PER CAUSE in
///                                          `for cause in chain` -- 2 + chain length
///   hermit-cli/src/bin/hermit/tracing.rs   .with_writer(|| RetryingStderr) is the
///                                          writer for the WHOLE subscriber: one
///                                          write per log event
///   detcore/src/tool_global.rs             a multi-part `write!`, which `write_fmt`
///                                          splits into several `write` calls
/// ```
///
/// With a per-call budget the process-level cost was N times this number, N is
/// bounded by the error chain rather than by anything here, and every caller's
/// `let _ =` swallowed the overrun silently. A `--log info` run measured at 138
/// lines would have been minutes, not seconds.
///
/// ⚠️ THE VALUE IS DERIVED FROM THE BOUND THAT ENCLOSES IT, NOT CHOSEN. Diagnostics
/// on the exit path run inside `RUN_TIMEOUT_UNWIND_GRACE` (10s,
/// `hermit-cli/src/lib.rs`): the window between a `--timeout` expiring and the
/// SIGALRM fallback calling `_exit`. Overrun there does not merely delay the
/// report, it loses it -- the fallback fires mid-sentence and additionally emits
/// `HERMIT_RUN_TIMEOUT_FALLBACK`, which is supposed to mean the teardown wedged.
/// So the arithmetic is:
///
/// ⚠️ IT USED TO APPLY ONCE PER PROCESS, BECAUSE HERMIT FORKS. `Container::run`
/// forks the container init, which got its own COPY of the process-wide clock and
/// spent its own full deadline; both write diagnostics to the same fd 2 on the way
/// out. Measured 2026-08-26 against a stopped reader on a real guest, which is the
/// case where both processes report:
///
/// ```text
///   deadline 5000ms   ->  10.03s observed   two processes, one deadline each
///   deadline 2500ms   ->   5.02s observed   the same two, halved
///   deadline 2500ms   ->   2.52s observed   missing guest: only ONE process reports
/// ```
///
/// ⚠️ AND THE MULTIPLIER WAS NOT ALWAYS TWO, WHICH IS WHY IT IS NO LONGER A
/// CONSTANT. `hermit run --verify` runs the guest twice and forks once per run, so
/// it is the outer hermit plus TWO container inits -- three writers, and siblings
/// rather than a chain. From the call structure, so it needs no sampling:
///
/// ```text
///   run.rs  fn verify()      Run1 -> self.run_verify(..)   Run2 -> self.run_verify(..)
///           fn run_verify()  -> with_container(..) forks a container init
/// ```
///
/// At three, `3 x 2500ms x 2 = 15s` against a 10s grace: the stated split does not
/// hold. Correcting the constant to three would force the deadline to ~1666ms and
/// leave a hardcoded count for the next differently-forking path to falsify.
///
/// So the ORIGIN is shared across the invocation instead (see
/// `STDERR_ORIGIN_ADDR`): every hermit process measures from the same start, the
/// invocation spends ONE deadline however many processes write, and the count
/// stops being an input. The arithmetic no longer contains it:
///
/// ```text
///   RUN_TIMEOUT_UNWIND_GRACE                    10s     the enclosing bound
///   diagnostics may have half of it              5s     leaving 5s for the unwind
///   this deadline, per INVOCATION             2500ms    comfortably inside the 5s
/// ```
///
/// Half is a split, not a measurement, and is stated as one. What is ALSO measured is
/// that the previous arrangement could not fit: at 5s per CALL, the same real-guest
/// fixture took 15.04s -- three blocked writes -- against a 10s grace, so the inner
/// bound exceeded its outer bound before any unwind work happened at all.
/// `hermit-cli` asserts this relationship in a test, so raising either side without
/// the other fails by name.
///
/// On expiry the write returns `WouldBlock`, `writeln!` gives up, the caller's
/// `let _ =` drops that line, and hermit exits — the pre-existing contract for a
/// diagnostic that cannot be delivered.
pub const STDERR_DIAGNOSTIC_DEADLINE: std::time::Duration = std::time::Duration::from_millis(2500);

/// When this process first found stderr unwritable, shared by every
/// `RetryingStderr`, which is what makes the deadline above a process total.
/// Set on the first `EAGAIN` and never reset: a run that recovers and later
/// blocks again has still spent that earlier time on its exit path.
///
/// Fallback only: used when the invocation-wide origin below is unavailable.
static STDERR_BLOCKED_SINCE: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();

/// The same instant, shared by every hermit process of ONE INVOCATION.
///
/// ⚠️ WITHOUT THIS THE DEADLINE IS MULTIPLIED BY THE NUMBER OF PROCESSES, AND
/// THAT NUMBER IS NOT 2. A `static` lives per process, so each hermit sets its
/// own origin and spends its own full deadline. The comment above states the
/// multiplier as "2 -- hermit + the forked init", which is right for `hermit
/// run` and wrong for `hermit run --verify`. From the call structure, not from
/// sampling a process table:
///
/// ```text
///   hermit-cli/src/bin/hermit/run.rs
///     fn verify()                      -> Run1: self.run_verify(log1_file, global)
///                                      -> Run2: self.run_verify(log2_file, global)
///     fn run_verify()                  -> with_container(..) forks a container init
/// ```
///
/// So `--verify` is the outer hermit plus TWO container inits, which share the
/// outer as their parent. Three writing processes, and siblings rather than a
/// chain. `record --verify` forks twice for the same reason, at
/// `record_verify.record` and `record_verify.replay` in record_start.rs.
///
/// At three the stated derivation does not hold: 3 x 2500ms x 2 = 15s against a
/// 10s grace. Correcting the constant to 3 would force the deadline to ~1666ms
/// and would leave a hardcoded count that the next differently-forking path
/// falsifies again. Sharing the ORIGIN makes the multiplier 1 by construction --
/// every process measures from the same start, so the invocation spends one
/// deadline however many processes write -- and the count stops being an input.
///
/// ⚠️ THE CARRIER IS AN INHERITED SHARED MAPPING, DELIBERATELY NOT AN ENVIRONMENT
/// VARIABLE AND NOT A FILE. A variable set on hermit reaches the GUEST by default
/// (`BaseEnv::Host` does not clear it), and a per-run-varying value visible to the
/// guest, in a determinism tool, on a surface the argv/env hashing covers, would
/// be a worse defect than the one being fixed. A file would put I/O on the path
/// that runs while hermit is already failing. `exec` drops the mapping, so the
/// guest never shares it.
///
/// `CLOCK_MONOTONIC` rather than `Instant`: an `Instant` is not meaningful in
/// another process, while `CLOCK_MONOTONIC` is system-wide on Linux, so the same
/// nanosecond count is directly comparable between parent and child. 0 means
/// unset; the first blocked write in ANY process installs the origin.
static STDERR_ORIGIN_ADDR: OnceLock<usize> = OnceLock::new();

/// Create the origin cell every hermit process of this invocation shares.
///
/// ⚠️ MUST BE CALLED BEFORE THE FIRST FORK, and is called from the top of `main`.
/// A mapping made after a fork is not shared with the child that already exists,
/// so a late call would silently give each process its own origin -- the exact
/// failure this removes. `main` dominates every `with_container` and
/// `run_guarded_at` site in run.rs, replay.rs and record_start.rs.
pub fn init_shared_stderr_deadline_origin() {
    STDERR_ORIGIN_ADDR.get_or_init(|| {
        // SAFETY: an anonymous shared mapping of one page, no fd, no fixed
        // address. Never unmapped: it must outlive every child, and one page per
        // invocation does not justify a teardown path on an exit route.
        let addr = unsafe {
            libc::mmap(
                std::ptr::null_mut(),
                std::mem::size_of::<AtomicU64>(),
                libc::PROT_READ | libc::PROT_WRITE,
                libc::MAP_SHARED | libc::MAP_ANONYMOUS,
                -1,
                0,
            )
        };
        if addr == libc::MAP_FAILED {
            // Not fatal and NOT silent: `stderr_deadline_is_shared` reports false
            // and the per-process fallback still bounds each process.
            return 0;
        }
        // SAFETY: freshly mapped, aligned for u64, sole owner at this point.
        unsafe { (addr as *mut AtomicU64).write(AtomicU64::new(0)) };
        addr as usize
    });
}

fn shared_origin_cell() -> Option<&'static AtomicU64> {
    match STDERR_ORIGIN_ADDR.get() {
        None | Some(0) => None,
        // SAFETY: the address came from `mmap` above, was initialised there, is
        // never unmapped, and `AtomicU64` is safe to share across processes in a
        // `MAP_SHARED` page.
        Some(&addr) => Some(unsafe { &*(addr as *const AtomicU64) }),
    }
}

fn monotonic_nanos() -> u64 {
    let mut ts = libc::timespec {
        tv_sec: 0,
        tv_nsec: 0,
    };
    // SAFETY: one initialised `timespec`, a clock id the kernel always supports.
    unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) };
    (ts.tv_sec as u64) * 1_000_000_000 + (ts.tv_nsec as u64)
}

/// Whether the deadline is bounded per INVOCATION or only per process.
///
/// ⚠️ EXISTS SO THE WEAKER STATE CANNOT BE SILENT. If the mapping failed, or
/// something forks before `init_shared_stderr_deadline_origin`, the bound
/// degrades to per-process and is multiplied by however many processes write.
#[doc(hidden)]
pub fn stderr_deadline_is_shared() -> bool {
    shared_origin_cell().is_some()
}

/// How long this invocation has been blocked on stderr, from the shared origin
/// when there is one and from this process's own first block otherwise.
fn stderr_blocked_for() -> std::time::Duration {
    match shared_origin_cell() {
        Some(cell) => {
            let now = monotonic_nanos();
            // The first blocked write in ANY process installs the origin; every
            // later one, in any process, reads the value that won.
            let origin = match cell.compare_exchange(0, now, Ordering::AcqRel, Ordering::Acquire) {
                Ok(_) => now,
                Err(existing) => existing,
            };
            std::time::Duration::from_nanos(now.saturating_sub(origin))
        }
        None => STDERR_BLOCKED_SINCE
            .get_or_init(std::time::Instant::now)
            .elapsed(),
    }
}

/// Reset the shared origin. Test-only: brackets that measure the deadline need
/// each case to start from zero, and nothing in a real run wants this.
#[doc(hidden)]
pub fn reset_stderr_deadline_origin_for_test() {
    if let Some(cell) = shared_origin_cell() {
        cell.store(0, Ordering::Release);
    }
}

impl std::io::Write for RetryingStderr {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        if buf.is_empty() {
            return Ok(0);
        }
        loop {
            // ⚠️ UNDER --max-log-bytes A BLOCKING DESCRIPTOR MUST NOT WAIT INSIDE
            // write(2). The bounded wait below starts only at `EAGAIN`, which a
            // blocking pipe never returns: its write simply waits for a reader,
            // forever when the reader has stopped, and the run never reaches the
            // cap. While `--max-log-bytes` is in force (review of
            // https://github.com/rrnewton/hermit/pull/3686) each attempt is one
            // that cannot wait for a reader, so a full pipe answers `EAGAIN` and
            // takes the same bounded path as a guest-set `O_NONBLOCK`. Without the
            // cap this is the plain `write(2)` it always was.
            let must_not_wait = crate::nonwaiting_write::diagnostics_must_not_wait();
            let attempt = if must_not_wait {
                crate::nonwaiting_write::write_without_waiting_for_a_reader(
                    libc::STDERR_FILENO,
                    buf,
                )
            } else {
                // SAFETY: `write(2)` on fd 2 reads `buf.len()` bytes from `buf`,
                // which is valid for that length, and writes no memory.
                let n = unsafe { libc::write(libc::STDERR_FILENO, buf.as_ptr().cast(), buf.len()) };
                if n >= 0 {
                    Ok(n as usize)
                } else {
                    Err(std::io::Error::last_os_error())
                }
            };
            let err = match attempt {
                Ok(n) => return Ok(n),
                Err(err) => err,
            };
            match err.kind() {
                // ⚠️ UNDER --max-log-bytes AN INTERRUPTED ATTEMPT IS RETRIED ONLY
                // WITHIN THE SAME DEADLINE, AND GIVEN UP AS `TimedOut`. A seccomp
                // policy can answer any call in the attempt with `EINTR` every
                // time: answering `statx` and the file-type probes on fd 2 that
                // way leaves the writer no type, and it returns `statx`'s
                // `EINTR`. An unbounded retry then never returned to
                // `DroppingStderr`, so the log was never charged and the cap
                // never crossed. `Interrupted` itself must not escape either:
                // `write_all`, behind `writeln!`, retries it forever. Without the
                // cap an interrupted write is retried as it always was.
                std::io::ErrorKind::Interrupted if must_not_wait => {
                    if STDERR_DIAGNOSTIC_DEADLINE
                        .checked_sub(stderr_blocked_for())
                        .is_none()
                    {
                        return Err(std::io::ErrorKind::TimedOut.into());
                    }
                    continue;
                }
                std::io::ErrorKind::Interrupted => continue,
                std::io::ErrorKind::WouldBlock => {
                    // ⚠️ BOUNDED, AND THE CLOCK IS PROCESS-WIDE. Waiting for a slow
                    // reader is the point; waiting for a stopped one is a hang on
                    // hermit's exit path. Starting the clock here rather than at the
                    // top of `write` is what makes the deadline a total: the first
                    // blocked write sets it and every later one inherits it, so N
                    // writes cost the deadline once instead of N times.
                    // Measured from the origin shared by every hermit process
                    // of this invocation when there is one, so N processes spend
                    // ONE deadline rather than N. See STDERR_ORIGIN_ADDR.
                    let spent = stderr_blocked_for();
                    let Some(remaining) = STDERR_DIAGNOSTIC_DEADLINE.checked_sub(spent) else {
                        return Err(err);
                    };
                    // Block until the reader makes room. A failed or timed-out
                    // poll falls through to another write attempt rather than
                    // dropping the bytes.
                    let mut pfd = libc::pollfd {
                        fd: libc::STDERR_FILENO,
                        events: libc::POLLOUT,
                        revents: 0,
                    };
                    // ⚠️ CLAMPED TO WHAT IS LEFT, NOT A FLAT SECOND. The check above
                    // happens BEFORE the poll, so a flat 1000ms let a call that
                    // started at 4.9s sleep a further second and overshoot to ~6s --
                    // the deadline documented one number and delivered another.
                    // Clamping makes the elapsed total the stated total.
                    let timeout_ms = i32::try_from(remaining.as_millis())
                        .unwrap_or(i32::MAX)
                        .min(1000);
                    // SAFETY: one initialised `pollfd`, count 1, timeout in ms.
                    unsafe {
                        libc::poll(&mut pfd, 1, timeout_ms);
                    }
                    continue;
                }
                _ => return Err(err),
            }
        }
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

/// [`RetryingStderr`] for output whose loss must not change how a capped run
/// ends: hermit's own log when it goes to stderr, and the stack traces that
/// `--stacktrace-event` and `--preemption-stacktrace` print there.
///
/// While `--max-log-bytes` is in force
/// ([`crate::nonwaiting_write::diagnostics_must_not_wait`]), bytes that
/// [`RetryingStderr`] gives up on -- its bounded deadline for a reader that is
/// not draining is spent, or the reader is gone -- are reported as written.
/// So a log line that stderr could not take still counts against the cap,
/// as `BoundedWriter` counts the bytes it truncates, and a run whose stderr
/// reader stopped still reaches the cap and exits 123 instead of running on
/// uncounted; and a caller that unwraps the write does not panic.
/// Without the cap this is exactly [`RetryingStderr`], errors included.
pub struct DroppingStderr;

impl std::io::Write for DroppingStderr {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        match RetryingStderr.write(buf) {
            Err(_) if crate::nonwaiting_write::diagnostics_must_not_wait() => Ok(buf.len()),
            result => result,
        }
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

/// `eprintln!` for detcore output that a capped run can print before the cap
/// crosses: under `--max-log-bytes` the line goes through [`DroppingStderr`]
/// and never waits beyond [`RetryingStderr`]'s deadline; otherwise this is the
/// `eprintln!` it replaces, with the same arguments, so uncapped output is
/// unchanged.
macro_rules! capped_eprintln {
    ($($arg:tt)*) => {
        if crate::nonwaiting_write::diagnostics_must_not_wait() {
            // One buffer, so the line is not split across several writes.
            let mut line = format!($($arg)*);
            line.push('\n');
            let _ = std::io::Write::write_all(&mut crate::util::DroppingStderr, line.as_bytes());
        } else {
            eprintln!($($arg)*);
        }
    };
}
pub(crate) use capped_eprintln;

#[cfg(test)]
mod shared_stderr_origin_tests {
    use super::*;

    /// ⚠️ THESE TESTS SHARE ONE PROCESS-GLOBAL CELL, SO THEY MUST NOT RUN AT THE
    /// SAME TIME. That is the point of the cell -- it is shared -- but it makes the
    /// tests interfere: one resets the origin while another is timing from it.
    /// Found the honest way: they passed under `--test-threads 1` and failed in the
    /// real suite, so the single-threaded run was not evidence about the suite.
    static SERIALISE: std::sync::Mutex<()> = std::sync::Mutex::new(());

    fn exclusive() -> std::sync::MutexGuard<'static, ()> {
        SERIALISE.lock().unwrap_or_else(|e| e.into_inner())
    }

    /// The origin must actually be SHARED across a fork, or nothing else holds.
    ///
    /// ⚠️ THIS IS THE ONE THING THAT CANNOT BE CHECKED BY READING THE CODE.
    /// `MAP_SHARED` versus `MAP_PRIVATE` is a single token; get it wrong and every
    /// single-process test still passes while each container init silently gets its
    /// own deadline again -- the exact defect this removes. So this forks for real
    /// and checks that a value written by the child is visible in the parent.
    #[test]
    fn the_origin_is_shared_across_a_fork() {
        let _exclusive = exclusive();
        init_shared_stderr_deadline_origin();
        let cell = shared_origin_cell().expect("mapping must exist after init");
        cell.store(0, Ordering::Release);

        // SAFETY: the child does no allocation and no locking -- one atomic store
        // and `_exit` -- so forking from a test harness thread is safe here.
        let pid = unsafe { libc::fork() };
        assert!(pid >= 0, "fork failed");
        if pid == 0 {
            shared_origin_cell()
                .expect("child inherited no mapping")
                .store(4242, Ordering::Release);
            unsafe { libc::_exit(0) };
        }
        let mut status = 0;
        assert_eq!(
            unsafe { libc::waitpid(pid, &mut status, 0) },
            pid,
            "waitpid"
        );
        assert_eq!(status, 0, "child exited nonzero");

        assert_eq!(
            cell.load(Ordering::Acquire),
            4242,
            "the parent cannot see the child's write, so each container init would \
             start its OWN deadline and the invocation would spend one per process -- \
             check MAP_SHARED in init_shared_stderr_deadline_origin"
        );
        cell.store(0, Ordering::Release);
    }

    /// The first blocked write installs the origin; later ones inherit it.
    ///
    /// This is what makes the deadline a TOTAL rather than a fresh allowance per
    /// caller, and it must hold across processes, not just across calls.
    #[test]
    fn the_first_writer_installs_the_origin_and_others_inherit_it() {
        let _exclusive = exclusive();
        init_shared_stderr_deadline_origin();
        reset_stderr_deadline_origin_for_test();
        let cell = shared_origin_cell().expect("mapping must exist after init");

        let first = stderr_blocked_for();
        let installed = cell.load(Ordering::Acquire);
        assert_ne!(installed, 0, "the first call must install a nonzero origin");
        // A fresh origin means almost no time has been spent yet.
        assert!(
            first < Duration::from_millis(50),
            "first call saw {first:?}"
        );

        std::thread::sleep(Duration::from_millis(20));
        let second = stderr_blocked_for();
        assert_eq!(
            cell.load(Ordering::Acquire),
            installed,
            "a later call moved the origin, so each caller would get a fresh \
             allowance and the deadline would stop being a total"
        );
        assert!(
            second >= Duration::from_millis(15),
            "the second call reported {second:?}, so it is not measuring from the \
             origin the first call installed"
        );
        reset_stderr_deadline_origin_for_test();
    }

    /// Which bound is in force must be answerable, not assumed.
    #[test]
    fn whether_the_deadline_is_invocation_wide_is_observable() {
        let _exclusive = exclusive();
        init_shared_stderr_deadline_origin();
        // ⚠️ THE WEAKER STATE MUST NOT BE SILENT. If the mapping failed, or something
        // forks before the init call, the deadline degrades to per-process and is
        // multiplied by however many processes write.
        assert!(
            stderr_deadline_is_shared(),
            "the origin is not shared after init, so the deadline is per-process and \
             is multiplied by the number of writing processes"
        );
    }
}

/// A descriptor opened with a raw syscall, closed with one when dropped.
pub struct RawFd(u64);

impl RawFd {
    /// `path` opened with `flags` (`O_CLOEXEC` added) by a raw `openat`, never
    /// through libc's `open` wrapper (see `raw_syscall`).
    pub fn open(path: &std::path::Path, flags: libc::c_int) -> std::io::Result<Self> {
        let path = raw_path(path)?;
        // SAFETY: a NUL-terminated path.
        let fd = raw_result(unsafe {
            raw_syscall(
                libc::SYS_openat,
                [
                    libc::AT_FDCWD as u64,
                    path.as_ptr() as u64,
                    (flags | libc::O_CLOEXEC) as u64,
                    0,
                    0,
                    0,
                ],
            )
        })?;
        Ok(Self(fd))
    }

    /// `name`, relative to this directory, opened with `flags` (`O_CLOEXEC`
    /// added) by a raw `openat`.
    pub fn open_at(&self, name: &std::ffi::OsStr, flags: libc::c_int) -> std::io::Result<Self> {
        let name = raw_path(std::path::Path::new(name))?;
        // SAFETY: a NUL-terminated name.
        let fd = raw_result(unsafe {
            raw_syscall(
                libc::SYS_openat,
                [
                    self.0,
                    name.as_ptr() as u64,
                    (flags | libc::O_CLOEXEC) as u64,
                    0,
                    0,
                    0,
                ],
            )
        })?;
        Ok(Self(fd))
    }

    /// The status of `name` in this directory, without following a final
    /// link, by a raw `newfstatat`.
    pub fn stat_at(&self, name: &std::ffi::OsStr) -> std::io::Result<libc::stat> {
        let name = raw_path(std::path::Path::new(name))?;
        // SAFETY: a NUL-terminated name; an all-zero `stat` is a valid value.
        let mut stat: libc::stat = unsafe { std::mem::zeroed() };
        raw_zero_result(unsafe {
            raw_syscall(
                libc::SYS_newfstatat,
                [
                    self.0,
                    name.as_ptr() as u64,
                    &mut stat as *mut libc::stat as u64,
                    libc::AT_SYMLINK_NOFOLLOW as u64,
                    0,
                    0,
                ],
            )
        })?;
        Ok(stat)
    }

    /// The descriptor's number.
    pub fn raw(&self) -> u64 {
        self.0
    }

    /// The open file's status, by a raw `fstat`.
    pub fn stat(&self) -> std::io::Result<libc::stat> {
        // SAFETY: an all-zero `stat` is a valid value, and the kernel writes
        // at most its size.
        let mut stat: libc::stat = unsafe { std::mem::zeroed() };
        raw_zero_result(unsafe {
            raw_syscall(
                libc::SYS_fstat,
                [self.0, &mut stat as *mut libc::stat as u64, 0, 0, 0, 0],
            )
        })?;
        Ok(stat)
    }

    /// Up to `buffer.len()` bytes at `offset`, by a raw `pread64`.
    pub fn read_at(&self, buffer: &mut [u8], offset: u64) -> std::io::Result<usize> {
        // SAFETY: the buffer is writable for its length.
        raw_result(unsafe {
            raw_syscall(
                libc::SYS_pread64,
                [
                    self.0,
                    buffer.as_mut_ptr() as u64,
                    buffer.len() as u64,
                    offset,
                    0,
                    0,
                ],
            )
        })
        .map(|read| read as usize)
    }
}

impl Drop for RawFd {
    fn drop(&mut self) {
        // SAFETY: a descriptor this value opened and owns.
        unsafe { raw_syscall(libc::SYS_close, [self.0, 0, 0, 0, 0, 0]) };
    }
}

fn raw_path(path: &std::path::Path) -> std::io::Result<std::ffi::CString> {
    use std::os::unix::ffi::OsStrExt;
    std::ffi::CString::new(path.as_os_str().as_bytes())
        .map_err(|_| std::io::Error::from(std::io::ErrorKind::InvalidInput))
}

/// The status of the file at `path`, following links, by a raw `newfstatat`.
pub fn raw_stat(path: &std::path::Path) -> std::io::Result<libc::stat> {
    let path = raw_path(path)?;
    // SAFETY: a NUL-terminated path; an all-zero `stat` is a valid value.
    let mut stat: libc::stat = unsafe { std::mem::zeroed() };
    raw_zero_result(unsafe {
        raw_syscall(
            libc::SYS_newfstatat,
            [
                libc::AT_FDCWD as u64,
                path.as_ptr() as u64,
                &mut stat as *mut libc::stat as u64,
                0,
                0,
                0,
            ],
        )
    })?;
    Ok(stat)
}

/// The target of the link at `path`, by a raw `readlinkat`.
pub fn raw_read_link(path: &std::path::Path) -> std::io::Result<std::path::PathBuf> {
    use std::os::unix::ffi::OsStrExt;
    let path = raw_path(path)?;
    let mut target = vec![0_u8; libc::PATH_MAX as usize];
    // SAFETY: a NUL-terminated path and a buffer writable for its length.
    let read = raw_result(unsafe {
        raw_syscall(
            libc::SYS_readlinkat,
            [
                libc::AT_FDCWD as u64,
                path.as_ptr() as u64,
                target.as_mut_ptr() as u64,
                target.len() as u64,
                0,
                0,
            ],
        )
    })? as usize;
    target.truncate(read);
    Ok(std::path::PathBuf::from(std::ffi::OsStr::from_bytes(
        &target,
    )))
}

/// The whole contents of the file at `path`, read with raw syscalls. Meant
/// for small files such as procfs entries.
pub fn raw_read_file(path: &std::path::Path) -> std::io::Result<Vec<u8>> {
    let file = RawFd::open(path, libc::O_RDONLY)?;
    let mut contents = Vec::new();
    let mut chunk = vec![0_u8; 4096];
    loop {
        // SAFETY: the buffer is writable for its length.
        let read = raw_result(unsafe {
            raw_syscall(
                libc::SYS_read,
                [
                    file.raw(),
                    chunk.as_mut_ptr() as u64,
                    chunk.len() as u64,
                    0,
                    0,
                    0,
                ],
            )
        })? as usize;
        if read == 0 {
            return Ok(contents);
        }
        contents.extend_from_slice(&chunk[..read]);
    }
}

/// The whole contents of the procfs listing at `path`, read with raw
/// syscalls and without allocating between reads, so that where the tool
/// shares the guest's process its own allocator maps nothing while the
/// kernel walks the address space: the buffer is allocated before the first
/// read, and a listing that fills it is read again, from the start, into one
/// twice the size.
pub fn raw_read_listing(path: &std::path::Path) -> std::io::Result<Vec<u8>> {
    let mut capacity = 64 * 1024;
    loop {
        let file = RawFd::open(path, libc::O_RDONLY)?;
        let mut contents = vec![0_u8; capacity];
        let mut filled = 0;
        while filled < capacity {
            // SAFETY: the buffer is writable from `filled` to its length.
            let read = raw_result(unsafe {
                raw_syscall(
                    libc::SYS_read,
                    [
                        file.raw(),
                        contents[filled..].as_mut_ptr() as u64,
                        (capacity - filled) as u64,
                        0,
                        0,
                        0,
                    ],
                )
            })? as usize;
            if read == 0 {
                contents.truncate(filled);
                return Ok(contents);
            }
            filled += read;
        }
        capacity *= 2;
    }
}

/// `path` with every symbolic link followed and every `.` and `..` resolved,
/// as glibc's `realpath` (`std::fs::canonicalize`) gives it: relative paths
/// from the working directory, and the same errors for an empty path
/// (`ENOENT`), a missing component (`ENOENT`), a component that is not a
/// directory but is followed by more, by `.`, `..` or a trailing `/`
/// (`ENOTDIR`), and links nested too deep (`ELOOP` after 40, Linux's
/// `MAXSYMLINKS`).
///
/// Walked with raw `getcwd`, `readlinkat` and `newfstatat` into buffers from
/// Rust's allocator, never with `std::fs::canonicalize`: that calls glibc's
/// `realpath`, whose result comes from the C library's `malloc`. Where
/// Detcore runs in the guest's process (SaBRe, in-guest LiteInst), that heap
/// is the guest's, and the allocation moves the guest's own `malloc` results
/// and can grow its program break (see `find_in_directory`).
pub fn canonicalize(path: &std::path::Path) -> std::io::Result<std::path::PathBuf> {
    use std::os::unix::ffi::OsStrExt;
    use std::path::PathBuf;
    let error = std::io::Error::from_raw_os_error;
    let bytes = path.as_os_str().as_bytes();
    if bytes.is_empty() {
        return Err(error(libc::ENOENT));
    }
    // What is left to walk, as `/`-separated pieces in reverse, so the next
    // is at the end. A trailing `/` is kept as a final `.` piece: Linux then
    // requires a directory, as it does before `.` and `..`.
    let mut pending: Vec<Vec<u8>> = Vec::new();
    let push = |pending: &mut Vec<Vec<u8>>, bytes: &[u8]| {
        let mut pieces: Vec<Vec<u8>> = bytes
            .split(|&byte| byte == b'/')
            .filter(|piece| !piece.is_empty())
            .map(<[u8]>::to_vec)
            .collect();
        if bytes.len() > 1 && bytes.ends_with(b"/") {
            pieces.push(b".".to_vec());
        }
        pieces.reverse();
        pending.extend(pieces);
    };
    let mut resolved = if bytes.starts_with(b"/") {
        PathBuf::from("/")
    } else {
        // The kernel answers within one PATH_MAX page and fails
        // ENAMETOOLONG past it, where glibc's getcwd walks `..` itself; so
        // does this (path_of_directory).
        let mut cwd = vec![0_u8; libc::PATH_MAX as usize];
        // SAFETY: the buffer is writable for its length. The kernel's length
        // counts the terminating NUL.
        let length = unsafe {
            raw_syscall(
                libc::SYS_getcwd,
                [cwd.as_mut_ptr() as u64, cwd.len() as u64, 0, 0, 0, 0],
            )
        };
        let length = if length == -(libc::ENAMETOOLONG as i64) {
            let here = RawFd::open(
                std::path::Path::new("."),
                libc::O_RDONLY | libc::O_DIRECTORY,
            )?;
            cwd = path_of_directory(here)?;
            cwd.push(0);
            cwd.len()
        } else {
            raw_result(length)? as usize
        };
        cwd.truncate(length.saturating_sub(1));
        // A working directory outside the process's root reads as
        // "(unreachable)..."; glibc's getcwd fails ENOENT there.
        if !cwd.starts_with(b"/") {
            return Err(error(libc::ENOENT));
        }
        PathBuf::from(std::ffi::OsStr::from_bytes(&cwd))
    };
    push(&mut pending, bytes);
    let is_directory = |path: &std::path::Path| {
        raw_stat(path).map(|stat| stat.st_mode & libc::S_IFMT == libc::S_IFDIR)
    };
    let mut links = 0;
    while let Some(piece) = pending.pop() {
        if piece == b"." || piece == b".." {
            if !is_directory(&resolved)? {
                return Err(error(libc::ENOTDIR));
            }
            if piece == b".." {
                resolved.pop();
            }
            continue;
        }
        let candidate = resolved.join(std::ffi::OsStr::from_bytes(&piece));
        let spelled = std::ffi::CString::new(candidate.as_os_str().as_bytes())
            .map_err(|_| std::io::Error::from(std::io::ErrorKind::InvalidInput))?;
        // A target that fills the buffer may have been cut short: read again
        // into a larger one.
        let mut target = vec![0_u8; libc::PATH_MAX as usize];
        let read = loop {
            // SAFETY: a NUL-terminated path and a buffer writable for its
            // length.
            let read = unsafe {
                raw_syscall(
                    libc::SYS_readlinkat,
                    [
                        libc::AT_FDCWD as u64,
                        spelled.as_ptr() as u64,
                        target.as_mut_ptr() as u64,
                        target.len() as u64,
                        0,
                        0,
                    ],
                )
            };
            if read != target.len() as i64 {
                break read;
            }
            target.resize(target.len() * 2, 0);
        };
        if read == -(libc::EINVAL as i64) {
            // There, and not a link.
            resolved = candidate;
            continue;
        }
        let read = raw_result(read)? as usize;
        links += 1;
        if links > 40 {
            return Err(error(libc::ELOOP));
        }
        if target[..read].starts_with(b"/") {
            resolved = PathBuf::from("/");
        }
        push(&mut pending, &target[..read]);
    }
    Ok(resolved)
}

/// The absolute path of the directory open at `start`: each directory's
/// name is found among its parent's entries by device and inode, walking `..`
/// up to the process's root, as glibc's getcwd does where the kernel's
/// `getcwd` cannot answer (a path longer than a page). Raw syscalls
/// throughout. `ENOENT` where a directory is missing from its parent (it was
/// removed, or lies outside the root).
fn path_of_directory(start: RawFd) -> std::io::Result<Vec<u8>> {
    use std::os::unix::ffi::OsStrExt;
    let mut names: Vec<Vec<u8>> = Vec::new();
    let mut current = start;
    loop {
        let here = current.stat()?;
        let parent = current.open_at(
            std::ffi::OsStr::new(".."),
            libc::O_RDONLY | libc::O_DIRECTORY,
        )?;
        let above = parent.stat()?;
        if (above.st_dev, above.st_ino) == (here.st_dev, here.st_ino) {
            break;
        }
        let name = find_in_open_directory(&parent, |name| {
            parent
                .stat_at(name)
                .is_ok_and(|stat| (stat.st_dev, stat.st_ino) == (here.st_dev, here.st_ino))
                .then(|| name.as_bytes().to_vec())
        })?
        .ok_or_else(|| std::io::Error::from_raw_os_error(libc::ENOENT))?;
        names.push(name);
        current = parent;
    }
    let mut path = Vec::new();
    for name in names.iter().rev() {
        path.push(b'/');
        path.extend_from_slice(name);
    }
    if path.is_empty() {
        path.push(b'/');
    }
    Ok(path)
}

/// Calls `visit` with each name in directory `path`, without `.` and `..`,
/// in the kernel's order, until it returns `Some`, and returns that value
/// (`None` when every name was visited).
///
/// Read with raw `getdents64` into one fixed buffer from Rust's allocator,
/// never with `std::fs::read_dir`: that calls glibc's `opendir`, whose
/// directory buffer comes from the C library's `malloc`. Under in-guest
/// LiteInst, Detcore runs inside the guest and that heap is the guest's: the
/// freed buffer would keep the kernel's bytes (raw `/proc` inode numbers, say)
/// where the guest's next allocation finds them, so the guest could observe
/// host-chosen data, for example in the padding of its own `getdents64`
/// records. Rust's allocator is private to the runtime there (inside a Tool
/// callback or an allocation scope). The names are streamed, not collected,
/// so a directory of any size costs the one buffer.
pub fn find_in_directory<T>(
    path: &std::path::Path,
    visit: impl FnMut(&std::ffi::OsStr) -> Option<T>,
) -> std::io::Result<Option<T>> {
    // Raw syscalls throughout (see raw_syscall); the descriptor closes when
    // dropped, a panicking visitor included.
    let directory = RawFd::open(path, libc::O_RDONLY | libc::O_DIRECTORY)?;
    find_in_open_directory(&directory, visit)
}

/// [`find_in_directory`] of a directory already open at `directory`, from
/// its current offset.
pub fn find_in_open_directory<T>(
    directory: &RawFd,
    mut visit: impl FnMut(&std::ffi::OsStr) -> Option<T>,
) -> std::io::Result<Option<T>> {
    use std::os::unix::ffi::OsStrExt;
    let fd = directory.raw();
    let mut buffer = vec![0_u8; 32 * 1024];
    'listing: loop {
        // SAFETY: the buffer is writable for its length.
        let read = unsafe {
            raw_syscall(
                libc::SYS_getdents64,
                [fd, buffer.as_mut_ptr() as u64, buffer.len() as u64, 0, 0, 0],
            )
        };
        if read < 0 {
            break Err(std::io::Error::from_raw_os_error(-read as i32));
        }
        if read == 0 {
            break Ok(None);
        }
        let mut offset = 0_usize;
        let read = read as usize;
        // A record: d_ino (8), d_off (8), d_reclen (2), d_type (1), d_name.
        while offset + 19 <= read {
            let reclen = u16::from_ne_bytes([buffer[offset + 16], buffer[offset + 17]]) as usize;
            if reclen < 19 || offset + reclen > read {
                break;
            }
            let name = &buffer[offset + 19..offset + reclen];
            let name = &name[..name
                .iter()
                .position(|byte| *byte == 0)
                .unwrap_or(name.len())];
            if name != b"."
                && name != b".."
                && let Some(found) = visit(std::ffi::OsStr::from_bytes(name))
            {
                break 'listing Ok(Some(found));
            }
            offset += reclen;
        }
    }
}

#[cfg(test)]
mod find_in_directory_tests {
    use super::*;

    /// Every name `std::fs::read_dir` finds is visited once, the visit stops
    /// at the first `Some`, and a path that is not a directory is an error.
    #[test]
    #[allow(clippy::disallowed_methods)] // std::fs::read_dir is the reference
    fn find_in_directory_visits_every_name_and_stops_at_the_first_find() {
        let directory = tempfile::tempdir().unwrap();
        for index in 0..300 {
            std::fs::write(
                directory
                    .path()
                    .join(format!("entry-with-a-long-name-{index}")),
                b"",
            )
            .unwrap();
        }
        let mut visited = Vec::new();
        let none: Option<()> = find_in_directory(directory.path(), |name| {
            visited.push(name.to_owned());
            None
        })
        .unwrap();
        assert!(none.is_none());
        visited.sort();
        let mut expected: Vec<_> = std::fs::read_dir(directory.path())
            .unwrap()
            .map(|entry| entry.unwrap().file_name())
            .collect();
        expected.sort();
        assert_eq!(visited.len(), 300);
        assert_eq!(visited, expected);
        let mut calls = 0;
        let found = find_in_directory(directory.path(), |name| {
            calls += 1;
            (calls == 7).then(|| name.to_owned())
        })
        .unwrap();
        assert!(found.is_some());
        assert_eq!(calls, 7);
        let file = directory.path().join("entry-with-a-long-name-0");
        assert!(find_in_directory(&file, |_| Some(())).is_err());
    }
}

#[cfg(test)]
mod canonicalize_tests {
    use std::os::unix::fs::symlink;
    use std::path::Path;

    use super::*;

    /// A directory's path is found by walking `..` where it is longer than
    /// the kernel's getcwd answers (a page), as glibc's getcwd does.
    #[test]
    fn a_long_directory_path_is_found_by_walking_up() {
        use std::os::unix::ffi::OsStrExt;
        let directory = tempfile::tempdir().unwrap();
        #[allow(clippy::disallowed_methods)] // std::fs::canonicalize is the independent oracle
        let root = std::fs::canonicalize(directory.path()).unwrap();
        let name = "d".repeat(200);
        let spelled = std::ffi::CString::new(name.as_str()).unwrap();
        let mut levels = vec![RawFd::open(&root, libc::O_RDONLY | libc::O_DIRECTORY).unwrap()];
        let mut expected = root.clone();
        // 25 levels of 201 bytes: past the 4096-byte page.
        for _ in 0..25 {
            let parent = levels.last().unwrap();
            // SAFETY: a NUL-terminated name relative to an open directory.
            assert_eq!(
                unsafe { libc::mkdirat(parent.raw() as i32, spelled.as_ptr(), 0o700) },
                0
            );
            let child = parent
                .open_at(
                    std::ffi::OsStr::new(&name),
                    libc::O_RDONLY | libc::O_DIRECTORY,
                )
                .unwrap();
            levels.push(child);
            expected.push(&name);
        }
        assert!(expected.as_os_str().len() > 4096);
        let deepest = levels
            .last()
            .unwrap()
            .open_at(
                std::ffi::OsStr::new("."),
                libc::O_RDONLY | libc::O_DIRECTORY,
            )
            .unwrap();
        let found = path_of_directory(deepest).unwrap();
        // A path short enough for the kernel is found the same way.
        let short = RawFd::open(&root, libc::O_RDONLY | libc::O_DIRECTORY).unwrap();
        let short = path_of_directory(short).unwrap();
        // The tree is too deep for a path-based removal: remove it level by
        // level before asserting.
        for parent in levels[..25].iter().rev() {
            // SAFETY: a NUL-terminated name relative to an open directory.
            unsafe { libc::unlinkat(parent.raw() as i32, spelled.as_ptr(), libc::AT_REMOVEDIR) };
        }
        assert_eq!(std::ffi::OsStr::from_bytes(&found), expected.as_os_str());
        assert_eq!(std::ffi::OsStr::from_bytes(&short), root.as_os_str());
    }

    /// The walk gives what glibc's `realpath` gives (`std::fs::canonicalize`,
    /// allowed here as the reference) through absolute, relative and chained
    /// links, `..` across a link, and procfs's own links; and the same errors
    /// for a missing component, a file used as a directory, and a link loop.
    #[test]
    #[allow(clippy::disallowed_methods)] // std::fs::canonicalize is the reference
    fn canonicalize_matches_realpath() {
        let directory = tempfile::tempdir().unwrap();
        let root = directory.path();
        std::fs::create_dir_all(root.join("a/b/c")).unwrap();
        std::fs::write(root.join("a/b/c/file"), b"").unwrap();
        symlink(root.join("a/b"), root.join("absolute")).unwrap();
        symlink("a/b/c", root.join("relative")).unwrap();
        symlink("relative", root.join("chained")).unwrap();
        symlink("../../b", root.join("a/b/c/up")).unwrap();
        symlink("loop2", root.join("loop1")).unwrap();
        symlink("loop1", root.join("loop2")).unwrap();
        for spelled in [
            root.join("a/b/c/file"),
            root.join("absolute/c/file"),
            root.join("relative/file"),
            root.join("chained/./file"),
            root.join("chained/../c/file"),
            root.join("a/b/c/up/c/file"),
            root.join("absolute/c/up/../.."),
            Path::new("/proc/self").to_path_buf(),
            Path::new("/proc/self/exe").to_path_buf(),
            Path::new("/").to_path_buf(),
        ] {
            assert_eq!(
                canonicalize(&spelled).unwrap(),
                std::fs::canonicalize(&spelled).unwrap(),
                "{spelled:?}"
            );
        }
        // Trailing separators and `.` on directories, and a link to one.
        for spelled in [
            root.join("a/b/"),
            root.join("a/b/."),
            root.join("absolute/"),
            root.join("relative/."),
        ] {
            assert_eq!(
                canonicalize(&spelled).unwrap(),
                std::fs::canonicalize(&spelled).unwrap(),
                "{spelled:?}"
            );
        }
        // The same errors as realpath, including after a regular file.
        let error = |spelled: &Path| canonicalize(spelled).unwrap_err().raw_os_error();
        let reference = |spelled: &Path| std::fs::canonicalize(spelled).unwrap_err().raw_os_error();
        let file = root.join("a/b/c/file");
        let violating = [
            Path::new("").to_path_buf(),
            root.join("missing/file"),
            root.join("a/b/c/file/x"),
            root.join("loop1"),
            file.join(""),
            Path::new(&format!("{}/.", file.display())).to_path_buf(),
            Path::new(&format!("{}/..", file.display())).to_path_buf(),
            Path::new(&format!("{}/../file", file.display())).to_path_buf(),
        ];
        for spelled in &violating {
            assert_eq!(error(spelled), reference(spelled), "{spelled:?}");
        }
        assert_eq!(error(&violating[0]), Some(libc::ENOENT));
        assert_eq!(error(&violating[3]), Some(libc::ELOOP));
        assert_eq!(error(&violating[5]), Some(libc::ENOTDIR));
        // A relative path starts from the working directory.
        let here = std::env::current_dir().unwrap();
        assert_eq!(
            canonicalize(Path::new(".")).unwrap(),
            std::fs::canonicalize(&here).unwrap()
        );
    }
}