userfaultfd(2)

Synopsis

#include <fcntl.h>
#include <sys/syscall.h>
#include <linux/userfaultfd.h>
#include <unistd.h>

int syscall(SYS_userfaultfd, int flags);

Rod's take

Normally a touch on a missing page gets you SIGSEGV and a funeral. userfaultfd says hold on, I'll supply that page myself: the faulting thread stalls, a handler reads the event off the fd, fills the page with UFFDIO_COPY, and the thread carries on none the wiser. That's the trick under post-copy migration and lazy restore. The rule that bites everyone once: the handler must never fault on the region it's serving, or you've built a very elegant deadlock. Unprivileged use hinges on vm.unprivileged_userfaultfd, so check before you promise anybody anything.

Flags and arguments that matter

Errors you will actually hit

Example

int uffd = syscall(SYS_userfaultfd, O_CLOEXEC | O_NONBLOCK);
if (uffd < 0)
    err(1, "userfaultfd");  /* EPERM: vm.unprivileged_userfaultfd */

struct uffdio_api api = { .api = UFFD_API, .features = 0 };
if (ioctl(uffd, UFFDIO_API, &api) < 0)
    err(1, "UFFDIO_API");

struct uffdio_register reg = {
    .range = { .start = (uintptr_t)region, .len = len },
    .mode  = UFFDIO_REGISTER_MODE_MISSING,
};
if (ioctl(uffd, UFFDIO_REGISTER, &reg) < 0)
    err(1, "UFFDIO_REGISTER");
/* handler thread: poll(), read struct uffd_msg, UFFDIO_COPY */

Trimmed from the full walkthrough in userfaultfd: handle your own page faults from userspace.

BSD equivalent

none