signal: implement signalfd(2)

gburd · gburd · commit 3d56ce6ac210 · 2026-07-13T06:49:32.000-04:00
signalfd() was stubbed to return ENOSYS, so event loops that consume signals
through a file descriptor (a common pattern with epoll) could not run.

Implement it as a pollable special_file (modeled on eventfd) backed by a global
registry of live signalfd objects.  OSv is a single process, so a signalfd
watches a set of signals for the whole image.  kill() now checks the registry
first: if any signalfd is watching the raised signal, the signal is queued to
those fds (as a signalfd_siginfo) and their pollers are woken, and the signal is
consumed -- the default action and any handler are skipped.  This matches Linux,
where a signalfd-consumed signal must be blocked and is dequeued through the fd.

- signalfd(-1, mask, flags) creates a new fd; signalfd(fd, mask, flags) updates
  an existing one's mask.  SFD_CLOEXEC and SFD_NONBLOCK are honored.
- read() returns as many queued signalfd_siginfo structures as fit in the
  buffer, blocking (or EAGAIN when non-blocking) when the queue is empty, and
  rejecting a buffer smaller than one siginfo with EINVAL.
- poll() reports POLLIN when signals are queued.

The delivery hook (osv_signalfd_deliver) is declared in &lt;osv/signal.hh&gt; and
called from kill() in libc/signal.cc; the stub there is removed.

Add tests/tst-signalfd.cc covering delivery of a watched signal to the fd
(instead of the default poweroff action), the EAGAIN/poll/queue-order paths,
and the EINVAL cases.  Passes on OSv under KVM (1 and 2 vCPUs); tst-sigwait and
tst-sigaction continue to pass (normal signal delivery is unaffected for signals
no signalfd is watching).
diff --git a/Makefile b/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
diff --git a/include/osv/signal.hh b/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_ */
diff --git a/libc/signal.cc b/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>
@@ -364,6 +365,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",
@@ -697,14 +703,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)
diff --git a/libc/signalfd.cc b/libc/signalfd.cc
@@ -0,0 +1,177 @@
+/*
+ * Copyright (C) 2026 Waldemar Kozaczuk
+ *
+ * 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 -- matching Linux, where a signalfd-consumed
+// signal must be blocked and is dequeued through the fd.
+
+#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 <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);
+    }
+
+    void set_mask(const sigset_t& mask) { _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.
+        while (!_queue.empty() &&
+               uio->uio_resid >= (ssize_t)sizeof(signalfd_siginfo)) {
+            signalfd_siginfo si = _queue.front();
+            _queue.pop_front();
+            int err = uiomove(&si, sizeof(si), uio);
+            if (err) {
+                return err;
+            }
+        }
+    }
+    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;
+}
diff --git a/modules/tests/Makefile b/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-prctl.so \
 	tst-mmap-file-cow.so \
+	tst-signalfd.so \
 	tst-elf-permissions.so misc-mutex.so misc-sockets.so tst-condvar.so \
 	tst-queue-mpsc.so tst-af-local.so tst-pipe.so tst-yield.so \
 	misc-ctxsw.so tst-read.so tst-symlink.so tst-openat.so \
diff --git a/tests/tst-signalfd.cc b/tests/tst-signalfd.cc
@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2026 Waldemar Kozaczuk
+ *
+ * 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);
+    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;
+}

Original file line number	Diff line number	Diff line change
`@@ -34,4 +34,9 @@ public:`
`34`	`34`
`35`	`35`	`}`
`36`	`36`
	`37`	`+// signalfd delivery hook (libc/signalfd.cc). Called by kill() when a signal is`
	`38`	`+// raised: returns true if a signalfd consumed the signal, in which case the`
	`39`	`+// caller must not run the default action or a handler.`
	`40`	`+extern "C" bool osv_signalfd_deliver(int signo);`
	`41`	`+`
`37`	`42`	`#endif /* OSV_SIGNAL_HH_ */`