signal: implement signalfd(2)

Replace the ENOSYS signalfd() stub with a real implementation: create (or
update) a file descriptor that a program reads to receive signals as
signalfd_siginfo records instead of via a handler.

- signal_fd is a special_file holding the watched sigset and a queue of
  siginfos; read() copies out as many queued records as fit (blocking or
  EAGAIN under SFD_NONBLOCK), poll() reports POLLIN when the queue is
  non-empty.  read() peeks-copies-then-dequeues so a failed copy-out cannot
  drop a queued signal.
- kill()/the signal-raise path (libc/signal.cc) calls osv_signalfd_deliver():
  if any signalfd watches the signal it is queued to those fds (pollers woken)
  and the signal is consumed (no default action / handler).  The old
  WARN_STUBBED signalfd() in libc/signal.cc is removed.
- signalfd() updating an existing fd's mask takes registry_lock, the same lock
  the dispatch path holds while reading the mask, so a mask update cannot race
  a delivery.

Note on Linux fidelity: on Linux a signal is consumed by a signalfd only when
it is blocked in the caller's mask; OSv's signal model is already a
simplification and does not track a precise per-thread blocked mask here, so a
watched signal is consumed unconditionally.  Sufficient for the common use
(block the signals, read them through the fd); documented in the source.

Covered by tst-signalfd (which blocks the signals first, as a real signalfd
user does, so it is meaningful on Linux too).

Author: gburd

Makefile

@@ -2024,6 +2024,8 @@ libc += resource.o
 libc += mount.o
 libc += eventfd.o
 libc_to_hide += eventfd.o
+libc += signalfd.o
+libc_to_hide += signalfd.o
 libc += timerfd.o
 libc_to_hide += timerfd.o
 libc += shm.o

include/osv/signal.hh

@@ -34,4 +34,9 @@ public:
 
 }
 
+// signalfd delivery hook (libc/signalfd.cc).  Called by kill() when a signal is
+// raised: returns true if a signalfd consumed the signal, in which case the
+// caller must not run the default action or a handler.
+extern "C" bool osv_signalfd_deliver(int signo);
+
 #endif /* OSV_SIGNAL_HH_ */

libc/signal.cc

@@ -15,6 +15,7 @@
 #include <osv/mutex.h>
 #include <osv/condvar.h>
 #include <osv/power.hh>
+#include <osv/signal.hh>
 #include <osv/clock.hh>
 #include <api/setjmp.h>
 #include <osv/stubbing.hh>
@@ -412,6 +413,11 @@ int kill(pid_t pid, int sig)
         return -1;
     }
     unsigned sigidx = sig - 1;
+    // If a signalfd is watching this signal, deliver it to the fd and consume
+    // the signal (do not run the default action or a handler).
+    if (osv_signalfd_deliver(sig)) {
+        return 0;
+    }
     if (is_sig_dfl(signal_actions[sigidx])) {
         // Our default is to power off.
         debugf("Uncaught signal %d (\"%s\"). Powering off.\n",
@@ -745,14 +751,6 @@ int sigaltstack(const stack_t *ss, stack_t *oss)
     return 0;
 }
 
-extern "C" OSV_LIBC_API
-int signalfd(int fd, const sigset_t *mask, int flags)
-{
-    WARN_STUBBED();
-    errno = ENOSYS;
-    return -1;
-}
-
 extern "C" OSV_LIBC_API
 int sigwaitinfo(const sigset_t *__restrict mask,
                            siginfo_t *__restrict si)

libc/signalfd.cc

@@ -0,0 +1,199 @@
+/*
+ * 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.
+ */
+
+// signalfd(2): deliver signals to a file descriptor instead of via a handler.
+//
+// OSv is a single process, so a signalfd watches a set of signals for the whole
+// image.  When kill() raises a signal that some signalfd is watching, the
+// signal is queued to those fds (and their pollers woken) instead of running
+// the default action or a handler.
+//
+// Note on Linux fidelity: on Linux a signal is consumed by a signalfd only
+// when it is blocked in the caller's signal mask; an unblocked signal still
+// runs its handler/default action.  OSv's signal model is already a
+// simplification (see libc/signal.cc - kill() runs the handler on a fresh
+// thread rather than a designated one), and it does not track a precise
+// per-thread blocked mask here, so a watched signal is consumed by the
+// signalfd unconditionally.  This is sufficient for the common use (an app
+// blocks the signals it hands to a signalfd and reads them through the fd) but
+// is not bit-for-bit Linux semantics.
+
+#include <sys/signalfd.h>
+#include <fs/fs.hh>
+#include <libc/libc.hh>
+#include <osv/fcntl.h>
+#include <osv/mutex.h>
+#include <osv/condvar.h>
+#include <osv/poll.h>
+#include <osv/signal.hh>
+
+#include <unistd.h>
+#include <string.h>
+
+#include <deque>
+#include <set>
+#include <signal.h>
+#include <errno.h>
+
+namespace {
+
+class signal_fd;
+
+// Registry of all live signalfd objects, so kill() can find the ones watching a
+// given signal.  Guarded by its own lock.
+mutex registry_lock;
+std::set<signal_fd*> registry;
+
+class signal_fd final : public special_file {
+public:
+    signal_fd(const sigset_t& mask, int flags)
+        : special_file(FREAD | flags, DTYPE_UNSPEC), _mask(mask)
+    {
+        WITH_LOCK(registry_lock) { registry.insert(this); }
+    }
+
+    int close() override {
+        WITH_LOCK(registry_lock) { registry.erase(this); }
+        return 0;
+    }
+
+    int read(struct uio* uio, int flags) override;
+    int poll(int events) override;
+
+    // Is this fd watching signal `signo` (1-based)?
+    bool watches(int signo) const {
+        return sigismember(&_mask, signo) == 1;
+    }
+
+    // Called from the signal path to enqueue a delivered signal.
+    void deliver(const signalfd_siginfo& si) {
+        WITH_LOCK(_mutex) {
+            _queue.push_back(si);
+            _blocked_reader.wake_all();
+        }
+        poll_wake(this, POLLIN);
+    }
+
+    // Update the watched-signal set.  Taken under registry_lock (the same lock
+    // held while the signal-dispatch path calls watches()), so a concurrent
+    // signalfd() mask update cannot race a delivery's read of _mask.
+    void set_mask(const sigset_t& mask) {
+        WITH_LOCK(registry_lock) { _mask = mask; }
+    }
+
+private:
+    mutable mutex _mutex;
+    sigset_t      _mask;
+    condvar       _blocked_reader;
+    std::deque<signalfd_siginfo> _queue;
+};
+
+int signal_fd::read(struct uio* uio, int flags)
+{
+    if (uio->uio_resid < (ssize_t)sizeof(signalfd_siginfo)) {
+        return EINVAL;
+    }
+
+    WITH_LOCK(_mutex) {
+        while (_queue.empty()) {
+            if (f_flags & FNONBLOCK) {
+                return EAGAIN;
+            }
+            _blocked_reader.wait(_mutex);
+        }
+        // Copy out as many queued siginfos as fit in the caller's buffer.
+        // Peek, copy, and only dequeue after a successful copy so a failed
+        // copy-out never silently drops a queued signal.  (OSv's uiomove uses
+        // memcpy and does not currently fail, but keep the ordering correct.)
+        while (!_queue.empty() &&
+               uio->uio_resid >= (ssize_t)sizeof(signalfd_siginfo)) {
+            signalfd_siginfo si = _queue.front();
+            int err = uiomove(&si, sizeof(si), uio);
+            if (err) {
+                // If nothing was copied yet, report the error; otherwise the
+                // bytes already copied are a valid short read.
+                return err;
+            }
+            _queue.pop_front();
+        }
+    }
+    return 0;
+}
+
+int signal_fd::poll(int events)
+{
+    int rc = 0;
+    WITH_LOCK(_mutex) {
+        if (!_queue.empty() && (events & POLLIN)) {
+            rc |= POLLIN;
+        }
+    }
+    return rc;
+}
+
+} // anonymous namespace
+
+// Called by kill() (libc/signal.cc) when a signal is raised.  Returns true if at
+// least one signalfd consumed the signal, in which case the caller must not run
+// the default action or a handler.
+bool osv_signalfd_deliver(int signo)
+{
+    signalfd_siginfo si;
+    memset(&si, 0, sizeof(si));
+    si.ssi_signo = signo;
+    si.ssi_pid = getpid();
+
+    bool delivered = false;
+    WITH_LOCK(registry_lock) {
+        for (auto* sfd : registry) {
+            if (sfd->watches(signo)) {
+                sfd->deliver(si);
+                delivered = true;
+            }
+        }
+    }
+    return delivered;
+}
+
+extern "C" OSV_LIBC_API
+int signalfd(int fd, const sigset_t* mask, int flags)
+{
+    if (!mask || (flags & ~(SFD_CLOEXEC | SFD_NONBLOCK))) {
+        return libc_error(EINVAL);
+    }
+
+    int of = 0;
+    if (flags & SFD_NONBLOCK) {
+        of |= O_NONBLOCK;
+    }
+    if (flags & SFD_CLOEXEC) {
+        of |= O_CLOEXEC;
+    }
+
+    if (fd == -1) {
+        // Create a new signalfd.
+        try {
+            fileref f = make_file<signal_fd>(*mask, of);
+            fdesc newfd(f);
+            return newfd.release();
+        } catch (int error) {
+            return libc_error(error);
+        }
+    }
+
+    // Update the mask of an existing signalfd.
+    fileref f(fileref_from_fd(fd));
+    if (!f) {
+        return libc_error(EBADF);
+    }
+    auto* sfd = dynamic_cast<signal_fd*>(f.get());
+    if (!sfd) {
+        return libc_error(EINVAL);
+    }
+    sfd->set_mask(*mask);
+    return fd;
+}

modules/tests/Makefile

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

tests/tst-signalfd.cc

@@ -0,0 +1,82 @@
+/*
+ * 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 signalfd(2): a signal raised while a signalfd watches it is
+// delivered to the fd (and consumed) rather than running the default action.
+// Built and run as part of the OSv test image.
+
+#include <sys/signalfd.h>
+#include <sys/poll.h>
+#include <signal.h>
+#include <unistd.h>
+#include <errno.h>
+
+#include <cassert>
+#include <cstring>
+#include <iostream>
+
+int main()
+{
+    std::cerr << "Running signalfd tests\n";
+
+    // Create a signalfd watching SIGUSR1 and SIGUSR2.
+    sigset_t mask;
+    sigemptyset(&mask);
+    sigaddset(&mask, SIGUSR1);
+    sigaddset(&mask, SIGUSR2);
+    // Block these signals first, as an application using signalfd is expected
+    // to (on Linux the signal must be blocked to be consumed via the fd rather
+    // than run its handler/default action).  This keeps the test meaningful on
+    // Linux too.
+    assert(sigprocmask(SIG_BLOCK, &mask, nullptr) == 0);
+    int sfd = signalfd(-1, &mask, SFD_NONBLOCK);
+    assert(sfd >= 0);
+
+    // Nothing pending yet: a nonblocking read returns EAGAIN.
+    signalfd_siginfo si;
+    ssize_t n = read(sfd, &si, sizeof(si));
+    assert(n == -1 && errno == EAGAIN);
+
+    // Raise SIGUSR1: it must be delivered to the fd, not the default action
+    // (which would power the guest off).
+    assert(kill(getpid(), SIGUSR1) == 0);
+
+    n = read(sfd, &si, sizeof(si));
+    assert(n == (ssize_t)sizeof(si));
+    assert(si.ssi_signo == (uint32_t)SIGUSR1);
+
+    // Raise SIGUSR2, then verify poll() reports it readable, then read it.
+    assert(kill(getpid(), SIGUSR2) == 0);
+    struct pollfd pfd { sfd, POLLIN, 0 };
+    assert(poll(&pfd, 1, 1000) == 1);
+    assert(pfd.revents & POLLIN);
+    n = read(sfd, &si, sizeof(si));
+    assert(n == (ssize_t)sizeof(si));
+    assert(si.ssi_signo == (uint32_t)SIGUSR2);
+
+    // Two signals queued before a read: both should come out in order.
+    assert(kill(getpid(), SIGUSR1) == 0);
+    assert(kill(getpid(), SIGUSR2) == 0);
+    signalfd_siginfo two[2];
+    n = read(sfd, two, sizeof(two));
+    assert(n == (ssize_t)sizeof(two));
+    assert(two[0].ssi_signo == (uint32_t)SIGUSR1);
+    assert(two[1].ssi_signo == (uint32_t)SIGUSR2);
+
+    // A short buffer (< one siginfo) is rejected with EINVAL.
+    char tiny[8];
+    n = read(sfd, tiny, sizeof(tiny));
+    assert(n == -1 && errno == EINVAL);
+
+    // Bad flags rejected.
+    errno = 0;
+    assert(signalfd(-1, &mask, 0x40) == -1 && errno == EINVAL);
+
+    close(sfd);
+    std::cerr << "signalfd tests PASSED\n";
+    return 0;
+}