core/epoll: implement epoll_pwait2(2)

Add epoll_pwait2(2) (Linux syscall 441), the epoll_pwait variant that takes a
struct timespec* timeout instead of an int millisecond timeout, plus an
optional signal mask.

The timespec is validated up front: NULL means block indefinitely; a malformed
timespec (negative tv_sec/tv_nsec, or tv_nsec >= 1e9) returns EINVAL like Linux;
{0,0} returns immediately; otherwise the value is converted to milliseconds
(rounding up) and saturated to INT_MAX before any multiply, avoiding signed
overflow UB. The result is forwarded to the existing epoll_pwait(), so the
sigmask handling and event delivery are shared.

Wired into the syscall table (x86-64 and aarch64 __NR_epoll_pwait2 = 441),
exported from libc and the musl loader, and covered by a new runnable test
(tst-epoll-pwait2) that also builds and passes on Linux.

Closes #1427

Author: gburd

core/epoll.cc

@@ -12,6 +12,8 @@
 #include <memory>
 #include <stdio.h>
 #include <errno.h>
+#include <limits.h>
+#include <time.h>
 #include <signal.h>
 
 #include <osv/file.h>
@@ -355,6 +357,43 @@ int epoll_pwait(int epfd, struct epoll_event *events, int maxevents, int timeout
     return ret;
 }
 
+// epoll_pwait2(2): like epoll_pwait but the timeout is a struct timespec (ns
+// resolution) instead of an int millisecond count.  A NULL timeout means block
+// indefinitely.  OSv's epoll_wait takes a millisecond timeout, so we round the
+// timespec up to whole milliseconds (a sub-ms nonzero timeout becomes 1 ms so
+// we do not busy-spin as if it were 0).
+//
+// Declared extern "C" here (musl's <sys/epoll.h> does not declare it) so the
+// syscall dispatch and callers get an unmangled symbol.
+extern "C" OSV_LIBC_API
+int epoll_pwait2(int epfd, struct epoll_event *events, int maxevents,
+            const struct timespec *timeout, const sigset_t *sigmask);
+
+int epoll_pwait2(int epfd, struct epoll_event *events, int maxevents,
+            const struct timespec *timeout, const sigset_t *sigmask)
+{
+    int timeout_ms;
+    if (!timeout) {
+        timeout_ms = -1;   // block indefinitely
+    } else if (timeout->tv_sec < 0 || timeout->tv_nsec < 0 ||
+               timeout->tv_nsec >= 1000000000) {
+        // Malformed timespec -> EINVAL, matching Linux, before any arithmetic.
+        errno = EINVAL;
+        return -1;
+    } else if (timeout->tv_sec == 0 && timeout->tv_nsec == 0) {
+        timeout_ms = 0;    // return immediately
+    } else if (timeout->tv_sec >= (long long)INT_MAX / 1000) {
+        // Would overflow the millisecond count; saturate to the max wait rather
+        // than risk signed-overflow UB in the multiply below.
+        timeout_ms = INT_MAX;
+    } else {
+        long long ms = (long long)timeout->tv_sec * 1000 +
+                       (timeout->tv_nsec + 999999) / 1000000;   // round up
+        timeout_ms = ms > INT_MAX ? INT_MAX : (int)ms;
+    }
+    return epoll_pwait(epfd, events, maxevents, timeout_ms, sigmask);
+}
+
 void epoll_file_closed(epoll_ptr ptr)
 {
     ptr.epoll->del(ptr.key);

exported_symbols/osv_ld-musl.so.1.symbols

@@ -146,6 +146,7 @@ epoll_create
 epoll_create1
 epoll_ctl
 epoll_pwait
+epoll_pwait2
 epoll_wait
 erand48
 erf

exported_symbols/osv_libc.so.6.symbols

@@ -110,6 +110,7 @@ epoll_create
 epoll_create1
 epoll_ctl
 epoll_pwait
+epoll_pwait2
 epoll_wait
 erand48
 __errno_location

include/api/aarch64/bits/syscall.h

@@ -281,6 +281,7 @@
 #define __NR_io_uring_setup 425
 #define __NR_io_uring_enter 426
 #define __NR_io_uring_register 427
+#define __NR_epoll_pwait2 441
 #define __NR_sys_io_uring_setup __NR_io_uring_setup
 #define __NR_sys_io_uring_enter __NR_io_uring_enter
 #define __NR_sys_io_uring_register __NR_io_uring_register
@@ -584,6 +585,7 @@
 #define SYS_io_uring_setup 425
 #define SYS_io_uring_enter 426
 #define SYS_io_uring_register 427
+#define SYS_epoll_pwait2 441
 #define SYS_open_tree		428
 #define SYS_move_mount		429
 #define SYS_fsopen		430

include/api/x64/bits/syscall.h

@@ -647,6 +647,7 @@
 #define SYS_io_uring_setup			425
 #define SYS_io_uring_enter			426
 #define SYS_io_uring_register			427
+#define SYS_epoll_pwait2			441
 
 #undef SYS_fstatat
 #undef SYS_pread
@@ -661,6 +662,7 @@
 #define __NR_io_uring_setup 425
 #define __NR_io_uring_enter 426
 #define __NR_io_uring_register 427
+#define __NR_epoll_pwait2 441
 #define __NR_sys_io_uring_setup __NR_io_uring_setup
 #define __NR_sys_io_uring_enter __NR_io_uring_enter
 #define __NR_sys_io_uring_register __NR_io_uring_register

linux.cc

@@ -68,6 +68,8 @@
 
 extern "C" int eventfd2(unsigned int, int);
 extern "C" int osv_sigtimedwait(const sigset_t *, siginfo_t *, const struct timespec *);
+extern "C" int epoll_pwait2(int epfd, struct epoll_event *events, int maxevents,
+            const struct timespec *timeout, const sigset_t *sigmask);
 
 extern "C" OSV_LIBC_API long gettid()
 {

modules/tests/Makefile

@@ -122,6 +122,7 @@ tests := tst-pthread.so misc-ramdisk.so tst-vblk.so tst-bsd-evh.so \
 	tst-mmap-file.so misc-mmap-big-file.so tst-mmap.so tst-huge.so \
 	tst-pthread-timedlock.so \
 	tst-signal-fills.so \
+	tst-epoll-pwait2.so \
 	tst-prctl.so \
 	tst-mmap-file-cow.so \
 	tst-elf-permissions.so misc-mutex.so misc-sockets.so tst-condvar.so \

syscalls/syscall_tracepoints.cc.in

@@ -69,6 +69,7 @@ TRACEPOINT(trace_syscall_ftruncate, "%d <= %d %ld", int, int, off_t);
 TRACEPOINT(trace_syscall_fsync, "%d <= %d", int, int);
 #if CONF_core_epoll
 TRACEPOINT(trace_syscall_epoll_pwait, "%d <= %d %p %d %d %p", int, int, struct epoll_event *, int, int, const sigset_t*);
+TRACEPOINT(trace_syscall_epoll_pwait2, "%d <= %d %p %d %p %p", int, int, struct epoll_event *, int, const struct timespec *, const sigset_t*);
 #endif
 TRACEPOINT(trace_syscall_getrandom, "%lu <= 0x%x %lu %u", ssize_t, char *, size_t, unsigned int);
 TRACEPOINT(trace_syscall_nanosleep, "%d <= %p %p", int, const struct timespec*, struct timespec *);

syscalls/syscalls.cc.in

@@ -69,6 +69,7 @@
     SYSCALL1(fsync, int);
 #if CONF_core_epoll
     SYSCALL5(epoll_pwait, int, struct epoll_event *, int, int, const sigset_t*);
+    SYSCALL5(epoll_pwait2, int, struct epoll_event *, int, const struct timespec *, const sigset_t*);
 #endif
     SYSCALL3(getrandom, char *, size_t, unsigned int);
     SYSCALL2(nanosleep, const struct timespec*, struct timespec *);

tests/tst-epoll-pwait2.cc

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2026 Greg Burd
+ *
+ * This work is open source software, licensed under the terms of the
+ * BSD license as described in the LICENSE file in the top-level directory.
+ */
+
+// Exercises epoll_pwait2(2) via the raw syscall.  Built and run on the OSv
+// test image.
+
+#include <sys/epoll.h>
+#include <sys/eventfd.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <time.h>
+#include <errno.h>
+#include <stdint.h>
+
+#include <cassert>
+#include <iostream>
+
+static int epoll_pwait2_(int epfd, struct epoll_event *ev, int maxev,
+                         const struct timespec *to, const sigset_t *sig)
+{
+    return syscall(SYS_epoll_pwait2, epfd, ev, maxev, to, sig);
+}
+
+int main()
+{
+    std::cerr << "Running epoll_pwait2 tests\n";
+
+    int ep = epoll_create1(0);
+    assert(ep >= 0);
+    int efd = eventfd(0, EFD_NONBLOCK);
+    assert(efd >= 0);
+
+    struct epoll_event ev {};
+    ev.events = EPOLLIN;
+    ev.data.fd = efd;
+    assert(epoll_ctl(ep, EPOLL_CTL_ADD, efd, &ev) == 0);
+
+    struct epoll_event out[4];
+
+    // Nothing ready: a zero timespec returns immediately with 0 events.
+    struct timespec zero { 0, 0 };
+    assert(epoll_pwait2_(ep, out, 4, &zero, nullptr) == 0);
+
+    // Nothing ready: a short timeout returns 0 after roughly that long.
+    struct timespec ts { 0, 100 * 1000 * 1000 };  // 100 ms
+    struct timespec before, after;
+    clock_gettime(CLOCK_MONOTONIC, &before);
+    assert(epoll_pwait2_(ep, out, 4, &ts, nullptr) == 0);
+    clock_gettime(CLOCK_MONOTONIC, &after);
+    long long elapsed_ms = (after.tv_sec - before.tv_sec) * 1000 +
+                           (after.tv_nsec - before.tv_nsec) / 1000000;
+    assert(elapsed_ms >= 90);   // waited about 100 ms, not returned instantly
+
+    // Make the eventfd readable: pwait2 reports it.
+    uint64_t one = 1;
+    assert(write(efd, &one, sizeof(one)) == sizeof(one));
+    int n = epoll_pwait2_(ep, out, 4, &ts, nullptr);
+    assert(n == 1);
+    assert(out[0].data.fd == efd);
+    assert(out[0].events & EPOLLIN);
+
+    // NULL timeout with a ready fd returns immediately (does not block forever).
+    n = epoll_pwait2_(ep, out, 4, nullptr, nullptr);
+    assert(n == 1);
+
+    close(efd);
+    close(ep);
+    std::cerr << "epoll_pwait2 tests PASSED\n";
+    return 0;
+}