2025-08-07

userfaultfd系统调用及示例

好的，我们继续按照您的要求学习 Linux 系统编程中的重要函数。这次我们介绍 userfaultfd。

1. 函数介绍

userfaultfd (User Fault File Descriptor) 是一个 Linux 系统调用（内核版本 >= 4.3），它提供了一种机制，允许用户态程序处理发生在其他进程（或同一进程的其他线程）中的页面错误（Page Fault）。

data-ad-format="fluid" data-ad-layout-key="-7k+ex-4a-9w+4a">

简单来说，它让你可以：

监控一块内存区域。

当这块内存被访问（读/写）但尚未分配物理页或被换出时，内核会暂停访问该内存的进程/线程。

内核通过一个特殊的文件描述符（userfaultfd）通知你的用户态程序。

你的程序可以读取这个通知，了解到哪个进程、哪个地址发生了缺页。

然后，你的程序可以自行决定如何处理这个缺页：

从磁盘加载数据。
从网络获取数据。
生成所需的数据。
映射另一块已存在的内存。
返回错误。

最后，你的程序通过 ioctl 调用告诉内核：“我已经处理好了，让那个进程继续运行吧”。

你可以把它想象成一个智能的内存管家：

你告诉管家（userfaultfd）：“监控客厅（某块内存）”。
当孩子（另一个进程）跑进客厅玩耍（访问内存），但客厅还没收拾好（页面未分配/换出），孩子会被卡住。
管家会立刻通知你：“孩子卡在客厅了！”。
你收到通知后，赶紧去把客厅收拾好（准备数据）。
然后你告诉管家：“客厅搞定了，让孩子进去玩吧”。
孩子就能继续开心地玩耍了。

这使得实现惰性加载（Lazy Loading）、内存快照、用户态垃圾回收、分布式共享内存等高级功能成为可能。

2. 函数原型

#include <sys/syscall.h> // 因为 glibc 可能未包装，常需 syscall
#include <unistd.h>
#include <fcntl.h>       // O_CLOEXEC, O_NONBLOCK
#include <linux/userfaultfd.h> // 核心定义

// 注意：glibc 可能没有直接包装，需要 syscall 或使用 liburing 等库
// 系统调用号在 x86_64 上通常是 323 (SYS_userfaultfd)
int userfaultfd(int flags);

3. 功能

创建 UFFD: 创建一个新的 userfaultfd 对象，并返回一个与之关联的文件描述符。
设置监听: 后续需要使用 ioctl (UFFDIO_API, UFFDIO_REGISTER) 来配置这个 userfaultfd，告诉它要监听哪些内存区域以及监听哪些类型的页面错误。
接收通知: 其他进程访问被监听的内存区域时发生页面错误，内核会将错误信息通过这个文件描述符发送给用户态程序。
处理错误: 用户态程序读取错误信息，进行处理，并通过 ioctl (UFFDIO_COPY, UFFDIO_ZEROPAGE, UFFDIO_WAKE) 等操作来解决页面错误，使被阻塞的进程恢复运行。

4. 参数

int flags: 控制 userfaultfd 行为的标志。可以是以下值的按位或组合：

0: 默认行为。
O_CLOEXEC: 在调用 exec() 时自动关闭该文件描述符。这是个好习惯，防止意外传递给新程序。
O_NONBLOCK: 使 userfaultfd 文件描述符变为非阻塞模式。对 userfaultfd 本身的读写操作（读取事件）会受到影响。

5. 返回值

成功时: 返回一个新的 userfaultfd 文件描述符（一个非负整数）。
失败时: 返回 -1，并设置全局变量 errno 来指示具体的错误原因（例如 EINVAL flags 无效，EMFILE 进程打开的文件描述符已达上限，ENOSYS 内核不支持 userfaultfd 等）。

6. 相似函数，或关联函数

mmap: 用于分配和映射内存区域，这些区域后续可以用 userfaultfd 来监控。
ioctl: 用于配置 userfaultfd（注册内存区域、处理页面错误）和与其交互的主要方式。
poll / select / epoll: 用于等待 userfaultfd 文件描述符变为可读（有事件到来）。
read: 用于从 userfaultfd 文件描述符读取页面错误事件。
fork / pthread: userfaultfd 通常与多进程或多线程结合使用，一个线程/进程负责监控和处理错误，其他线程/进程进行内存访问。

7. 示例代码

重要提示: userfaultfd 的使用非常复杂，涉及多线程/多进程、ioctl 操作、内存管理等。下面的示例是一个极度简化的概念演示，展示了核心流程。

示例 1：基本的 userfaultfd 设置和事件读取（概念性）

// userfaultfd_concept.c
#define _GNU_SOURCE
#include <sys/syscall.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>
#include <poll.h>
#include <linux/userfaultfd.h>
#include <sys/ioctl.h>

// 简化系统调用包装
static inline int sys_userfaultfd(int flags) {
    return syscall(__NR_userfaultfd, flags);
}

int main() {
    int uffd;
    struct uffdio_api api;
    struct uffdio_register reg;
    char *page;
    long page_size = sysconf(_SC_PAGESIZE);
    struct pollfd pollfd;
    struct uffd_msg msg;
    ssize_t nread;

    printf("Page size: %ld bytes\n", page_size);

    // 1. 检查内核支持
    printf("Checking for userfaultfd support...\n");
    uffd = sys_userfaultfd(O_CLOEXEC | O_NONBLOCK);
    if (uffd == -1) {
        if (errno == ENOSYS) {
            printf("userfaultfd is NOT supported on this kernel (need >= 4.3).\n");
        } else {
            perror("userfaultfd");
        }
        exit(EXIT_FAILURE);
    }
    printf("userfaultfd supported. File descriptor: %d\n", uffd);

    // 2. 启用 API (必须步骤)
    printf("\nEnabling UFFD API...\n");
    api.api = UFFD_API;
    api.features = 0; // 不请求任何额外特性
    if (ioctl(uffd, UFFDIO_API, &api) == -1) {
        perror("ioctl UFFDIO_API");
        close(uffd);
        exit(EXIT_FAILURE);
    }
    if (api.api != UFFD_API) {
        fprintf(stderr, "UFFD API version mismatch.\n");
        close(uffd);
        exit(EXIT_FAILURE);
    }
    printf("UFFD API enabled successfully.\n");

    // 3. 分配并映射内存
    printf("\nAllocating memory using mmap...\n");
    page = mmap(NULL, page_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
    if (page == MAP_FAILED) {
        perror("mmap");
        close(uffd);
        exit(EXIT_FAILURE);
    }
    printf("Memory mapped at %p (size: %ld bytes)\n", (void*)page, page_size);

    // 4. 注册内存区域到 userfaultfd
    printf("\nRegistering memory region with userfaultfd...\n");
    reg.range.start = (unsigned long) page;
    reg.range.len = page_size;
    reg.mode = UFFDIO_REGISTER_MODE_MISSING; // 监听缺页错误
    if (ioctl(uffd, UFFDIO_REGISTER, &reg) == -1) {
        perror("ioctl UFFDIO_REGISTER");
        munmap(page, page_size);
        close(uffd);
        exit(EXIT_FAILURE);
    }
    printf("Memory region registered successfully.\n");

    // 5. 触发缺页错误 (在另一个线程/进程中通常发生)
    printf("\nTriggering a page fault by accessing the memory...\n");
    printf("  Accessing address %p...\n", (void*)page);
    *page = 'X'; // 这会触发缺页错误，并被 uffd 捕获
    printf("  Successfully wrote 'X' to %p.\n", (void*)page);

    // 6. 等待并读取事件 (通常在专用线程中)
    printf("\nPolling userfaultfd for events...\n");
    pollfd.fd = uffd;
    pollfd.events = POLLIN;
    int poll_res = poll(&pollfd, 1, 1000); // 1秒超时
    if (poll_res > 0 && (pollfd.revents & POLLIN)) {
        printf("Event detected on uffd.\n");
        nread = read(uffd, &msg, sizeof(msg));
        if (nread > 0) {
            if (msg.event == UFFD_EVENT_PAGEFAULT) {
                printf("  Received PAGEFAULT event:\n");
                printf("    Address: %p\n", (void*)msg.arg.pagefault.address);
                printf("    Flags: 0x%llx\n", (unsigned long long)msg.arg.pagefault.flags);
                if (msg.arg.pagefault.flags & UFFD_PAGEFAULT_FLAG_WRITE) {
                    printf("    (Fault was caused by a WRITE access)\n");
                } else {
                    printf("    (Fault was caused by a READ access)\n");
                }

                // --- 关键: 处理缺页错误 ---
                printf("\n--- Resolving page fault ---\n");
                struct uffdio_zeropage zeropage;
                zeropage.range.start = msg.arg.pagefault.address & ~(page_size - 1); // 对齐到页
                zeropage.range.len = page_size;
                zeropage.mode = 0;
                if (ioctl(uffd, UFFDIO_ZEROPAGE, &zeropage) == -1) {
                    perror("ioctl UFFDIO_ZEROPAGE");
                } else {
                    printf("  Page zeroed and resolved successfully.\n");
                    printf("  The faulting process/thread should now resume.\n");
                }
            } else {
                printf("  Received unexpected event type: %d\n", msg.event);
            }
        } else if (nread == 0) {
            printf("  Read 0 bytes from uffd (unexpected).\n");
        } else {
            perror("read from uffd");
        }
    } else if (poll_res == 0) {
        printf("  Timeout: No event received on uffd within 1 second.\n");
        printf("  (This might be because the page was already handled by the kernel\n");
        printf("   or the access didn't trigger a monitored fault.)\n");
    } else {
        perror("poll uffd");
    }

    // 7. 清理
    printf("\nCleaning up...\n");
    if (munmap(page, page_size) == -1) {
        perror("munmap");
    }
    if (close(uffd) == -1) {
        perror("close uffd");
    }
    printf("Cleanup completed.\n");

    return 0;
}

**代码解释 **(概念性):

定义 sys_userfaultfd 包装 syscall，因为 glibc 可能未直接提供。

调用 sys_userfaultfd(O_CLOEXEC | O_NONBLOCK) 创建 userfaultfd。

关键: 调用 ioctl(uffd, UFFDIO_API, &api) 启用 userfaultfd API。这是必需的初始化步骤。

使用 mmap 分配一个匿名私有内存页。

关键: 调用 ioctl(uffd, UFFDIO_REGISTER, &reg) 将 mmap 分配的内存区域注册到 userfaultfd 进行监控。UFFDIO_REGISTER_MODE_MISSING 表示监听缺页错误。

触发缺页: 程序直接访问 page 指向的内存。对于匿名私有映射，首次访问会触发内核分配一个“零页”并映射，这通常不会被 userfaultfd 捕获，因为内核自己处理了。为了让 userfaultfd 生效，通常需要更复杂的设置（如 mmap 一个未实际分配物理页的区域，或在另一个进程中访问）。

等待事件: 使用 poll 等待 userfaultfd 文件描述符变为可读。

读取事件: 如果 poll 检测到事件，调用 read(uffd, &msg, sizeof(msg)) 读取 struct uffd_msg。

检查事件类型: 检查 msg.event 是否为 UFFD_EVENT_PAGEFAULT。

处理事件: 打印缺页的地址和访问类型（读/写）。

关键: 调用 ioctl(uffd, UFFDIO_ZEROPAGE, &zeropage) 来解决缺页错误。这里使用 UFFDIO_ZEROPAGE 将缺页的地址范围映射为一个全零页。

清理资源。

注意: 这个例子为了简化，直接在主线程中触发并处理缺页，这在实际中可能不会按预期工作，因为内核通常会自己处理匿名页的首次分配。userfaultfd 的威力在于跨进程或更复杂的惰性加载场景。

重要提示与注意事项:

内核版本: 需要 Linux 内核 4.3 或更高版本。

glibc 支持: 标准 glibc 可能没有包装 userfaultfd，需要使用 syscall。

权限: 通常需要特殊权限（如 CAP_SYS_PTRACE）才能对其他进程使用 userfaultfd。同一进程内使用通常不需要。

复杂性: userfaultfd 的完整使用非常复杂，涉及多线程、事件循环、复杂的 ioctl 操作（如 UFFDIO_COPY 从用户态缓冲区复制数据到缺页地址）。

性能: 虽然功能强大，但处理页面错误涉及用户态和内核态的多次交互，可能带来开销。

应用场景: 主要用于实现高级内存管理功能，如用户态分页、惰性加载文件、内存快照、分布式内存等。

总结:

userfaultfd 是一个强大而独特的 Linux 系统调用，它将传统的、由内核全权处理的页面错误处理机制，部分地移交给了用户态程序。这为实现创新的内存管理和虚拟化技术提供了前所未有的灵活性和控制力。虽然使用起来相当复杂，但它是现代 Linux 系统编程中一个极具价值的工具。

data-ad-format="auto" data-full-width-responsive="true">

CalcGuide 技术博客

AI Coding · 技术分享 · 工具实践

userfaultfd系统调用及示例

1. 函数介绍

2. 函数原型

3. 功能

4. 参数

5. 返回值

6. 相似函数，或关联函数

7. 示例代码

示例 1：基本的 userfaultfd 设置和事件读取（概念性）

重要提示与注意事项:

1. 函数介绍

2. 函数原型

3. 功能

4. 参数

5. 返回值

6. 相似函数，或关联函数

7. 示例代码

示例 1：基本的 userfaultfd 设置和事件读取（概念性）

重要提示与注意事项:

📚 相关文章