mmap(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

mmap - 将文件或设备映射到进程虚拟内存空间（以及 munmap 解除内存映射）

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#include <sys/mman.h>

void *mmap(void *addr, size_t length, int prot, int flags,
           int fd, off_t offset);
int munmap(void *addr, size_t length);

描述 (DESCRIPTION)

mmap() 在调用进程的虚拟地址空间中创建一段新的内存映射区域。

参数详解

1. 起始地址 addr

• 若 addr 为 NULL：内核将自动选择一个对齐到页边界（page-aligned）的未占用地址来创建映射。这是创建新映射最通用、最具可移植性的方法。
• 若 addr 不为 NULL：内核会将其视为放置映射的建议地址（hint）。在 Linux 上，内核会选取邻近的页边界（且该地址必须大于或等于 /proc/sys/vm/mmap_min_addr 所配置的安全阈值），并尝试在该处创建映射。若该地址已被其他映射占用，内核会自动分配另一个新地址（该地址可能与提示地址无关）。调用返回最终实际分配的映射起始地址。

2. 映射长度 length

• 指定要映射的内存区域长度（单位为字节）。
• 必须大于 0；若传入 0，调用将失败并设置 errno 为 EINVAL。

3. 内存保护标志 prot

prot 参数描述映射内存页的访问保护权限，不能与底层文件的打开模式（open 模式）冲突。其值可以为 PROT_NONE，或是以下标志的按位或（OR）组合：

4. 映射标志 flags

flags 决定对映射区域的修改是否对其他映射相同区域的进程可见，以及修改是否会同步更新到底层支持文件。

• MAP_SHARED：
  • 共享映射。对映射区域的任何修改对共享同一区域的其他进程均立即可见。
  • 对于文件映射（file-backed mapping），修改内容会同步写回底层文件。（若需精确控制写回底层磁盘的时间，须显式调用 msync(2)）。
• MAP_SHARED_VALIDATE (自 Linux 4.15 引入)：
  • 行为与 MAP_SHARED 基本一致，唯一的关键区别在于：MAP_SHARED 会静默忽略 flags 中无法识别的未知标志；而 MAP_SHARED_VALIDATE 会严格校验传入的所有标志，一旦包含未知标志，调用立即失败并返回错误 EOPNOTSUPP。
  • 某些高阶标志（如持久化内存的 MAP_SYNC）强制要求搭配该类型使用。
• MAP_PRIVATE：
  • 私有写时复制（COW, Copy-on-Write）映射。
  • 对映射区域的写入修改对其他进程完全不可见，且绝不会写回到底层文件。
  • 在 mmap() 调用之后对底层文件所做的修改是否会反映到已映射区域是未定义（unspecified）的行为。

除上述三者之一外，还可按需按位或（OR）组合以下可选标志位：

5. 文件描述符 fd 与偏移量 offset

• 文件映射：数据内容从文件 fd 中自 offset 偏移处读取 length 字节进行初始化。
• 对齐要求：offset 必须是系统页面大小（通过 sysconf(_SC_PAGE_SIZE) 获取，通常为 4096 字节）的整数倍。
• 文件描述符生命周期：mmap() 成功返回后，可以立即调用 close(fd)，这绝不会损坏或解除已建立的内存映射。

解除内存映射：munmap()

int munmap(void *addr, size_t length);

• munmap() 系统调用用于删除调用进程在指定虚拟地址范围 [addr, addr + length) 内的映射关系。
• 地址对齐：参数 addr 必须是系统页面大小的整数倍（而 length 不需要是页大小的整数倍）。内核会自动将覆盖该区间的整页全部解除映射。
• 自动释放：当进程终止退出时，所有内存映射都会被操作系统自动解除。但是，关闭对应的文件描述符（close(fd)）不会解除映射。
• 悬空访问：解除映射后，后续对该地址范围的任何内存访问均会触发 SIGSEGV（段错误）。若指定的地址范围内根本不存在任何有效映射，munmap() 也不会报错，依然返回 0。

返回值 (RETURN VALUE)

• mmap()：
  • 成功：返回指向已映射内存区域起始位置的指针（void *）。
  • 失败：返回宏 MAP_FAILED（定义为 ((void *) -1)），并设置 errno 指示具体的错误类型。

• munmap()：
  • 成功：返回 0。
  • 失败：返回 -1，并设置 errno（通常为 EINVAL）。

错误代码 (ERRORS)

访问映射区可能触发的异常信号

• SIGSEGV（段错误）：
  • 尝试向以只读方式映射（缺少 PROT_WRITE）的区域执行写操作。
  • 访问未经映射的虚拟内存空间，或触碰了向下生长的栈（MAP_GROWSDOWN）之外的受限保护页。
• SIGBUS（总线错误）：
  • 访问映射缓冲区中超出底层文件实际物理大小的内存页（例如其他进程调用 ftruncate(2) 截断缩短了文件，导致映射范围越过了文件尾端）。

接口属性 (ATTRIBUTES)

版本与特性宏 (VERSIONS)

• 硬件架构与权限推导：
  • 在部分硬件架构（如 x86/i386）上，硬件页表粒度决定了 PROT_WRITE 隐式包含了 PROT_READ。
  • PROT_READ 是否隐式包含 PROT_EXEC 因 CPU 架构和内核 NX 位保护而异。为了编写健壮的可移植程序，只要需要执行代码，就必须显式设置 PROT_EXEC。
• 可移植映射规范：
  • 最规范的可移植创建方式是将 addr 设为 NULL，并在 flags 中省去 MAP_FIXED。系统会自动选择互不冲突的安全地址。
• 特性测试宏定义：
  • 诸如 MAP_ANONYMOUS、MAP_POPULATE、MAP_HUGETLB 等大多数扩展标志均为 Linux 专属定义。使用时推荐在包含头文件前定义：

    #define _GNU_SOURCE
    #include <sys/mman.h>

• C 库与内核底层差异：
  • 本手册描述的是 glibc 提供的 mmap() 封装函数。最初该封装函数直接调用同名系统调用；
  • 自 Linux 2.4 起，内核引入了 mmap2(2) 系统调用（其 offset 参数以 4096 字节为基本单位，从而允许 32 位系统访问超过 4GB 的超大文件）；现代 glibc 的 mmap() 封装函数在底层透明调用 mmap2(2) 并自动转换偏移量。

标准 (STANDARDS)

• POSIX.1-2024。
• 历史标准：SVr4, 4.4BSD, SUSv1, POSIX.1-1996。
• 在支持 mmap()、msync() 与 munmap() 的 POSIX 兼容系统上，<unistd.h> 中会定义 _POSIX_MAPPED_FILES 宏且值大于 0。

注意事项 (NOTES)

1. 跨进程继承 (fork)

由 mmap() 创建的内存映射在进程执行 fork(2) 时会被子进程完整继承，且保留完全相同的保护属性；然而在调用 execve(2) 加载新程序镜像时，所有映射都会被自动销毁解除。

2. 页面对齐与超出文件末尾的部分页（Partial Page）

内存映射总是以系统页面大小（通常为 4KB）为最小粒度分配管理的：

• 若底层文件大小不是页面大小的整数倍，则映射末尾最后一页中超出文件末尾的剩余部分字节会被内核自动填充为 0。
• 对这部分超出文件末尾的零填充字节进行写入修改，绝不会被回写到磁盘文件中。
• 若文件在后续被外部缩减，访问超出文件物理结尾的页将直接引发 SIGBUS 信号。

3. 安全使用 MAP_FIXED 的准则与多线程竞态漏洞

• 典型竞态场景：线程 A 查询 /proc/self/maps 发现了一段空闲地址，准备使用 MAP_FIXED 映射到该地址；而在同一瞬间，线程 B 调用了 malloc()、dlopen() 或 pthread_create()，其内部在同一地址空间动态创建了内存映射。此时线程 A 的 mmap(MAP_FIXED) 会无声无息地彻底踩踏并销毁线程 B 的映射，导致整个进程随机崩溃。
• 正确实践：
  1. 自 Linux 4.17 起，在需要尝试固定地址时务必改用 MAP_FIXED_NOREPLACE。遇到地址占用时会安全报错 EEXIST，保障原子性与线程安全。
  2. 若必须使用 MAP_FIXED，唯一安全的前提是该目标地址区间已经在之前由当前模块通过一次占位映射（如匿名不可访问映射）预先保留。

4. 映射页的文件修改时间戳（Timestamps）

• st_atime（最后访问时间）：在 mmap() 与对应的 munmap() 期间的任意时刻可能更新；首次读取引用映射页时必然触发更新。
• st_ctime / st_mtime（状态改变与修改时间）：对带有 PROT_WRITE 和 MAP_SHARED 的文件映射区域写入后，会在随后的 msync(2)（带有 MS_SYNC 或 MS_ASYNC）之前由内核更新。

5. 大页映射（Huge Pages / HugeTLB）的特殊约束

使用 MAP_HUGETLB 时：

• 对于 mmap()：offset 必须是底层大页大小（例如 2MB 或 1GB）的整数倍；内核会自动将 length 向上取整对齐到大页尺寸。
• 对于 munmap()：addr 和 length 都必须是底层大页尺寸的整数倍。

使用限制与陷阱 (CAVEATS)

与常见的 malloc(3) 实现不同，mmap() 并不阻止创建体积超过 PTRDIFF_MAX（指针差值最大值）的对象：

• 在 C 语言规范中，如果两个指针相减的结果超出了 PTRDIFF_MAX，属于未定义行为（Undefined Behavior）。
• 此外，GCC 等编译器在优化时会假定任何单一对象的大小均不超过 PTRDIFF_MAX。
• 在 32 位架构上，PTRDIFF_MAX 通常约为 0x7fffffff（约 2GB）。开发时应避免映射跨度超过此限制的单一巨型内存块。

已知缺陷 (BUGS)

1. MAP_NORESERVE 无法抵御 OOM-killer：在 Linux 上，MAP_NORESERVE 并不能真正保证进程免于崩溃。默认情况下，一旦系统全局物理内存耗尽，任何进程都可能在任意时刻被内核 OOM-killer 强制终止。
2. length == 0 的历史兼容性：SUSv3 规定长度为 0 时必须报错。但在 Linux 2.6.12 之前，mmap() 传入 length == 0 竟会成功返回 addr 而不创建任何映射；自 Linux 2.6.12 起已严格修复并返回 EINVAL。
3. 文件尾部部分页脏数据缓存：向文件尾部未满一页的剩余部分写入数据时，该数据将滞留在内核 Page Cache 中。即使文件被 close 且映射被 munmap，后续建立的新映射依然可能读取到此脏数据。在 tmpfs(5)（如 POSIX 共享内存 shm_open(3)）上，即使在 unmap 前调用 msync(2) 也无法彻底避免该现象。

代码示例 (EXAMPLES)

示例 1：利用 mmap 高性能读取并打印文件指定字节区间

该程序演示如何通过页对齐处理安全映射文件区间，并利用 write(2) 直接输出映射内存。

#include <err.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>

int main(int argc, char *argv[])
{
    int         fd;
    char        *addr;
    off_t       offset, pa_offset;
    size_t      length;
    ssize_t     s;
    struct stat sb;
    long        page_size;

    if (argc < 3 || argc > 4) {
        fprintf(stderr, "用法: %s <文件路径> <偏移量offset> [长度length]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    fd = open(argv[1], O_RDONLY);
    if (fd == -1)
        err(EXIT_FAILURE, "打开文件失败 (open)");

    if (fstat(fd, &sb) == -1)
        err(EXIT_FAILURE, "获取文件状态失败 (fstat)");

    offset = atoll(argv[2]);
    page_size = sysconf(_SC_PAGE_SIZE);
    if (page_size == -1)
        err(EXIT_FAILURE, "获取系统页大小失败");

    /* mmap 要求 offset 必须按页大小对齐，因此向下取整计算页起始偏移 */
    pa_offset = offset & ~(page_size - 1);

    if (offset >= sb.st_size) {
        fprintf(stderr, "错误: 目标偏移量已超出文件物理末尾\n");
        exit(EXIT_FAILURE);
    }

    if (argc == 4) {
        length = atoll(argv[3]);
        if (offset + length > (size_t)sb.st_size)
            length = sb.st_size - offset; /* 避免越界读取 */
    } else {
        length = sb.st_size - offset;     /* 默认读取至文件末尾 */
    }

    /* 映射长度需包含对齐偏移造成的额外页头部字节 */
    size_t map_length = length + (offset - pa_offset);

    addr = mmap(NULL, map_length, PROT_READ, MAP_PRIVATE, fd, pa_offset);
    if (addr == MAP_FAILED)
        err(EXIT_FAILURE, "内存映射失败 (mmap)");

    /* 实际数据指针从 addr + (offset - pa_offset) 开始 */
    s = write(STDOUT_FILENO, addr + (offset - pa_offset), length);
    if (s != (ssize_t)length) {
        if (s == -1)
            err(EXIT_FAILURE, "写入标准输出失败 (write)");
        fprintf(stderr, "警告: 部分写入\n");
        exit(EXIT_FAILURE);
    }

    /* 释放映射并关闭文件 */
    if (munmap(addr, map_length) == -1)
        err(EXIT_FAILURE, "解除映射失败 (munmap)");

    close(fd);
    return EXIT_SUCCESS;
}

示例 2：使用匿名共享映射（MAP_ANONYMOUS | MAP_SHARED）实现跨进程共享内存通信

#include <err.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/wait.h>
#include <unistd.h>

struct shared_data {
    int counter;
    char message[64];
};

int main(void)
{
    /* 创建父子进程共享的匿名内存映射，无需任何磁盘文件支持 */
    struct shared_data *data = mmap(NULL, sizeof(*data),
                                    PROT_READ | PROT_WRITE,
                                    MAP_SHARED | MAP_ANONYMOUS,
                                    -1, 0);
    if (data == MAP_FAILED)
        err(EXIT_FAILURE, "匿名共享映射创建失败");

    data->counter = 100;
    snprintf(data->message, sizeof(data->message), "Hello from Parent!");

    pid_t pid = fork();
    if (pid == -1)
        err(EXIT_FAILURE, "fork 失败");

    if (pid == 0) {
        /* 子进程：读取并直接修改共享内存中的数据 */
        printf("[子进程 PID %d] 读取初始数据: counter=%d, msg='%s'\n",
               getpid(), data->counter, data->message);

        data->counter += 50;
        snprintf(data->message, sizeof(data->message), "Modified by Child!");

        munmap(data, sizeof(*data));
        exit(EXIT_SUCCESS);
    }

    /* 父进程：等待子进程退出后读取最新更新 */
    wait(NULL);
    printf("[父进程 PID %d] 检测到更新: counter=%d, msg='%s'\n",
           getpid(), data->counter, data->message);

    if (munmap(data, sizeof(*data)) == -1)
        err(EXIT_FAILURE, "解除映射失败");

    return EXIT_SUCCESS;
}

参见 (SEE ALSO)

• 相关系统调用：
  • ftruncate(2) - 调整文件大小
  • mprotect(2) - 动态修改内存保护属性
  • msync(2) - 将映射数据强制同步刷写至底层存储介质
  • mremap(2) - 重新调整已有虚拟内存映射区域的大小与位置
  • mincore(2) - 检测映射页当前是否常驻物理 RAM
  • mlock(2) - 显式锁定进程虚拟内存页
  • mmap2(2) - 以 4KB 页为单位偏移的基础内核映射调用
  • sendfile(2) - 内核级零拷贝数据传输
  • splice(2) - 在管道与文件描述符之间直接移动数据
  • tee(2) - 管道数据非破坏性分流
  • userfaultfd(2) - 用户态缺页中断处理机制
• 库函数与机制规范：
  • shm_open(3) - POSIX 共享内存对象打开接口
  • shm_overview(7) - POSIX 共享内存概述与开发指南
  • proc(5) - /proc/[pid]/maps、/proc/[pid]/smaps 虚拟内存映射分布调试文件

open(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

open, openat, creat - 打开并可能创建文件或设备，返回关联的文件描述符

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#include <fcntl.h>

int open(const char *path, int flags, ...
           /* mode_t mode */ );

int creat(const char *path, mode_t mode);

int openat(int dirfd, const char *path, int flags, ...
           /* mode_t mode */ );

/* 单独在 openat2(2) 中记录： */
int openat2(int dirfd, const char *path,
           const struct open_how *how, size_t size);

glibc 特性测试宏要求 (参见 feature_test_macros(7))

openat():
    自 glibc 2.10 起:
        _POSIX_C_SOURCE >= 200809L
    glibc 2.10 之前:
        _ATFILE_SOURCE

描述 (DESCRIPTION)

open() 系统调用打开由 path 指定的文件。若目标文件不存在，且在 flags 中指定了 O_CREAT，则 open() 可以选择创建该文件。

文件描述符与打开文件描述 (File Descriptor vs. Open File Description)

open() 成功时返回一个文件描述符 (file descriptor, fd)，这是一个非负整数，代表当前进程打开文件描述符表的索引。

• 返回的描述符总是当前进程中数值最小且未被占用的可用文件描述符。
• 默认情况下，新文件描述符跨 execve(2) 保持打开状态（即 fcntl(2) 的 FD_CLOEXEC 标志默认处于禁用状态）；通过指定 O_CLOEXEC 标志可以改变该默认行为。
• 文件读写偏移量（offset）初始被置为文件开头（参见 lseek(2)）。

访问模式 (Access Modes)

参数 flags 必须且只能包含以下访问模式之一：

标志位分类 (Creation Flags vs. Status Flags)

除了基础访问模式外，flags 参数还可以按位或（|）组合零个或多个可选标志。标志位可分为两大类：

1. 文件创建标志 (File Creation Flags)：影响 open() 调用本身的创建或打开语义。这些标志不能通过 fcntl(2) 查询或修改：
   • O_CLOEXEC
   • O_CREAT
   • O_DIRECTORY
   • O_EXCL
   • O_NOCTTY
   • O_NOFOLLOW
   • O_TMPFILE
   • O_TRUNC
2. 文件状态标志 (File Status Flags)：影响后续针对该描述符的 I/O 操作语义。可以通过 fcntl(2) 的 F_GETFL 获取，部分标志可通过 F_SETFL 动态修改：
   • 其余所有标志（如 O_APPEND, O_ASYNC, O_DIRECT, O_NONBLOCK, O_SYNC 等）。

标志位详解 (Flags Details)

• O_APPEND：
  以追加模式打开文件。在执行每次 write(2) 之前，内核原子地将文件偏移量移动至文件末尾（等效于先执行 lseek(2)）。

  警告

  在 NFS 网络文件系统上，多进程同时以 O_APPEND 写入可能会损坏文件，因为 NFS 协议本身不支持文件追加语义，需由客户端内核模拟，容易引发竞态条件。

• O_ASYNC：
  启用信号驱动 I/O（Signal-driven I/O）。当文件描述符就绪时向进程发送信号（默认为 SIGIO，可用 fcntl(2) 修改）。仅适用于终端、伪终端、套接字、管道以及 FIFO。注：建议通过 fcntl(2) 启用该标志，避免在 open() 中直接使用。

• O_CLOEXEC（自 Linux 2.6.23 起）：
  为返回的新文件描述符自动设置 FD_CLOEXEC（close-on-exec）标志。这避免了多线程程序在 fork(2) 与 execve(2) 之间并发调用 open() 时可能导致的文件描述符泄露竞态条件。

• O_CREAT：
  若指定路径的文件不存在，则创建该文件为普通文件。

  • 必须提供第 3 个参数 mode，用于指定新文件的访问权限掩码（受进程的 umask 影响，实际权限为 mode & ~umask）。
  • 新文件的属主（UID）设置为进程的有效用户 ID。属组（GID）取决于目录的 set-group-ID 状态或挂载选项。

• O_DIRECT（自 Linux 2.4.10 起）：
  尝试绕过内核页缓存（Page Cache）进行直接 I/O。用户空间缓冲区与文件系统传输直接交互，适用于数据库等拥有自研缓存系统的中间件。用户空间缓冲区的内存地址、文件偏移量以及传输字节长度通常必须按底层设备或文件系统的块大小（通常为 512 字节或 4096 字节）对齐。

• O_DIRECTORY：
  要求被打开的文件必须是目录。若 path 不是目录，则 open() 失败并设置 errno 为 ENOTDIR。

• O_DSYNC：
  按照 POSIX 同步 I/O 数据完整性完成（Synchronized I/O data integrity completion）方式执行写入。写操作必须等待数据及允许后续读取所需的元数据（如文件大小变化）刷入底层硬件才返回。

• O_EXCL：
  与 O_CREAT 组合使用：若文件已存在，则 open() 失败并返回 EEXIST 错误。这保证了文件创建的原子性，避免多进程检查文件是否存在时产生竞态。

• O_LARGEFILE：
  允许在 32 位系统上打开文件大小无法用 31 位表示（大于 2GB）的大文件。64 位系统上该标志默认隐式开启。

• O_NOATIME（自 Linux 2.6.8 起）：
  在读取文件时不更新其最后访问时间戳（st_atime）。调用进程的有效 UID 必须与文件属主匹配，或者拥有特权（CAP_FOWNER）。常见于备份工具与搜索索引程序。

• O_NOCTTY：
  若 path 指向一个终端设备，该设备不会成为调用进程的控制终端（即使该进程此前没有控制终端）。

• O_NOFOLLOW：
  若 path 的最后一部分是一个符号链接，则打开失败并返回 ELOOP 错误。与 O_PATH 标志联用时，则允许直接打开符号链接本身获取其描述符。

• O_NONBLOCK 或 O_NDELAY：
  以非阻塞模式打开文件。对普通文件通常没有影响，主要用于 FIFO、管道、套接字与设备驱动。在设备未就绪时立即返回而不会阻塞进程。

• O_PATH（自 Linux 2.6.39 起）：
  仅用于获取文件在文件系统层级中的句柄（文件描述符），而不实际打开文件内容。返回的描述符不能用于 read(2)、write(2) 等 I/O 调用，但可以作为 openat(2) 的 dirfd 参数、配合 fstat(2) 查询元数据、传递给 dup(2) 或通过 UNIX 域套接字传递。

• O_SYNC：
  按照 POSIX 同步 I/O 文件完整性完成（Synchronized I/O file integrity completion）方式执行写入。不仅刷入数据，还会刷入包括最后修改时间（st_mtime）在内的全部元数据。

• O_TMPFILE（自 Linux 3.11 起）：
  在指定目录下创建一个无名的隐式临时文件。必须与 O_RDWR 或 O_WRONLY 一同指定，path 必须为目录路径。该临时文件关闭后自动从文件系统中彻底销毁，亦可在后续通过 linkat(2) 将其原子原子地链接为常规目录项。

• O_TRUNC：
  若文件已存在且为普通文件，并且打开模式包含写权限（O_RDWR 或 O_WRONLY），则将文件长度截断为 0 字节。

creat()

int creat(const char *path, mode_t mode);

creat() 是早期 UNIX 遗留的历史接口，完全等效于：

open(path, O_WRONLY | O_CREAT | O_TRUNC, mode);

openat()

int openat(int dirfd, const char *path, int flags, ...
           /* mode_t mode */ );

openat() 的运行机制与 open() 类似，但扩展支持了基于基准目录文件描述符 dirfd 进行路径解析：

1. 绝对路径：若 path 是绝对路径（以 / 开头），则忽略 dirfd，行为与 open() 完全一致。
2. 相对路径与 AT_FDCWD：若 path 为相对路径，且 dirfd 的取值为特殊常量 AT_FDCWD，则相对于调用进程的当前工作目录（CWD）解析路径，行为等同于 open()。
3. 相对路径与特定 dirfd：若 path 为相对路径，且 dirfd 是此前通过 open()（通常带有 O_DIRECTORY 或 O_PATH）打开的目录的文件描述符，则相对于 dirfd 所指向的目录进行相对路径解析。

mode 参数详解

当指定了 O_CREAT 或 O_TMPFILE 时，必须提供 mode 参数。它由以下权限位宏进行按位或构成：

返回值 (RETURN VALUE)

• 成功：返回新打开或创建的文件描述符（非负整数）。
• 失败：返回 -1，并设置全局变量 errno 以指示具体的错误原因。

错误代码 (ERRORS)

open(), openat(), creat() 可能发生以下错误：

版本与标准 (VERSIONS & STANDARDS)

• POSIX 标准：
  • open(), creat(): POSIX.1-2001, POSIX.1-2008, POSIX.1-2024。
  • openat(): POSIX.1-2008, POSIX.1-2024。
  • openat2(2): Linux 专有（从 Linux 5.6 引入）。
• Linux 扩展标志：
  • O_DIRECT, O_NOATIME, O_PATH, O_TMPFILE 均为 Linux 特有特性。
• C 库与内核层演进：
  • 从 glibc 2.26 起，glibc 内部的 open() 包装函数在所有支持的架构上统一改为使用 openat() 系统调用实现。

历史演进 (HISTORY)

• open() 与 creat() 存在于早期的 Version 6 AT&T UNIX 与 Version 7 AT&T UNIX。在早期 UNIX 中，open() 无法创建不存在的文件，因此必须使用 creat()；随后 O_CREAT 标志被加入 open()，使 creat() 退化为历史兼容函数。
• openat() 由 Solaris 率先引入，后随 Linux 2.6.16（glibc 2.4）被加入 Linux 内核，并最终被 POSIX.1-2008 采纳为标准。
• O_CLOEXEC 自 Linux 2.6.23 和 POSIX.1-2008 引入，彻底解决了多线程并发下的文件描述符泄漏安全漏洞。
• O_TMPFILE 自 Linux 3.11 引入，显著增强了临时文件创建的安全性。

注意事项 (NOTES)

同步 I/O (O_SYNC 与 O_DSYNC) 的性能权衡

POSIX 规范定义了同步 I/O 的不同层级：

• O_DSYNC（数据完整性完成）：只将数据本身以及后续成功读取该数据所必需的元数据（如文件长度）刷入磁盘。如果只是覆盖写而不改变文件大小，不会强刷最后修改时间（st_mtime）。
• O_SYNC（文件完整性完成）：无论写操作是否影响文件大小，都会将数据以及所有更新后的文件元数据（包括时间戳）全部刷入硬件。

在对 I/O 延迟敏感的场景下，使用 O_DSYNC 往往比 O_SYNC 节省一次针对 inode 元数据块的随机写操作。

直接 I/O (O_DIRECT) 与 fork 并发安全

通过 /proc 观察描述符状态

在 Linux 中，可以通过以下 proc 文件系统路径直观查看进程的打开文件情况：

• /proc/[pid]/fd/：该目录下包含了进程所有打开文件描述符的符号链接。
• /proc/[pid]/fdinfo/[fd]：记录了该描述符的当前偏移量（pos）、打开标志（flags）及挂载 ID（mnt_id）。

参见 (SEE ALSO)

• creat(2)
• openat2(2)
• close(2)
• read(2)
• write(2)
• lseek(2)
• fcntl(2)
• stat(2)
• mmap(2)
• pipe(2)
• dup(2)
• unlink(2)
• path_resolution(7)

代码示例 (EXAMPLE)

以下是使用 open() 与 openat() 的完整、可编译 C 语言示例程序：

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>

int main(void)
{
    const char *test_dir = "/tmp";
    const char *filename = "antigravity_open_demo.txt";
    const char *content = "Hello, Linux System Calls with open() and openat()!\n";

    /* 1. 使用 open() 打开目录，获取目录的文件描述符 */
    int dir_fd = open(test_dir, O_RDONLY | O_DIRECTORY | O_CLOEXEC);
    if (dir_fd == -1) {
        perror("open(directory) 失败");
        exit(EXIT_FAILURE);
    }

    /* 2. 使用 openat() 在指定目录下创建并截断新文件（权限 0644） */
    int file_fd = openat(dir_fd, filename,
                         O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC,
                         0644);
    if (file_fd == -1) {
        perror("openat(file) 失败");
        close(dir_fd);
        exit(EXIT_FAILURE);
    }

    /* 3. 写入内容 */
    ssize_t written = write(file_fd, content, strlen(content));
    if (written == -1) {
        perror("write 失败");
    } else {
        printf("成功写入 %zd 字节数据到 %s/%s\n", written, test_dir, filename);
    }

    /* 4. 关闭文件描述符并清理测试文件 */
    close(file_fd);
    unlinkat(dir_fd, filename, 0);
    close(dir_fd);

    return 0;
}

read(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

read - 从文件描述符读取数据

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#include <unistd.h>

ssize_t read(int fd, void buf[count], size_t count);

描述 (DESCRIPTION)

read() 系统调用尝试从文件描述符 fd 引用的打开文件中读取最多 count 字节的数据，并将其存入起始地址为 buf 的内存缓冲区中。

寻址定位与文件偏移量 (Seeking & File Offset)

• 支持寻址的文件：
  • 对于支持寻址定位（seekable）的文件（如普通磁盘文件），读取操作将从当前文件读写偏移量（file offset）处开始。
  • 读取成功后，文件偏移量会自动向前递增实际读取到的字节数。
  • 如果当前文件偏移量已经位于或超过了文件末尾（EOF），则不读取任何数据，并且 read() 立即返回 0。
• 不支持寻址的文件：
  • 对于不支持随机寻址的文件（如管道 pipe、FIFO、套接字 socket 或终端终端设备），数据将从流的当前头部开始连续读取，且这些对象没有文件偏移量的概念。

边界情况与限制

• count 为 0 的情形：
  • 若指定的 count 为 0，read() 可能会对传入的参数执行错误检查（如检测 fd 是否有效），若检测到错误则返回相应错误码。
  • 若无任何错误发生，或者内核实现不对此做错误检测，则传入 count = 0 的 read() 调用将直接返回 0，且不产生任何其他副作用。
• 超出 SSIZE_MAX 上限：
  • 根据 POSIX.1 规范，如果请求读取的字节数 count 大于 SSIZE_MAX，其结果属于实现定义行为（implementation-defined）。关于 Linux 系统的具体传输上限，请参见「注意事项 (NOTES)」章节。

局部读取 / 短读 (Short Reads)

成功调用 read() 时，其实际读取并返回的字节数小于请求的 count 字节数属于完全正常的情况，并不代表发生错误。产生短读的常见原因包括：

1. 接近文件末尾：文件中剩余可读的字节数少于 count；
2. 流式管道/套接字：从管道（pipe）或网络套接字（socket）读取时，当前内核接收缓冲区中可用的数据量少于请求量；
3. 终端行缓冲：从终端（terminal）读取时，终端默认处于规范模式（canonical mode），只要接收到一行输入（遇到换行符）即立刻返回；
4. 被信号中断：在读取到部分数据后被捕获的信号（signal）中断，系统调用选择返回已读取的字节数，而不是返回错误。

返回值 (RETURN VALUE)

• 成功：
  • 返回实际读取并写入缓冲区的字节数（类型为 ssize_t，非负整数）。
  • 返回值为 0 明确表示已到达文件末尾 (EOF)。
  • 成功读取后，关联文件的当前读取位置将相应向前推进该字节数。
• 失败：
  • 返回 -1，并设置全局变量 errno 以指示具体的错误原因。
  • 当发生错误时，内核规范规定：当前文件偏移量是否发生改变是未定义的（unspecified）。

错误代码 (ERRORS)

版本与标准 (VERSIONS & STANDARDS)

• POSIX.1-2008
• POSIX.1-2001
• SVr4, 4.3BSD

历史演进 (HISTORY)

read() 系统调用自早期的 Version 7 AT&T UNIX 便已存在，是 UNIX 操作系统与 POSIX 体系中最为核心的基础 I/O 原语之一。

注意事项 (NOTES)

Linux 单次最大传输上限

在 Linux 系统上，read()（以及类似的读写系统调用如 pread(2)、write(2)）单次传输的最大字节数限制为：

无论是在 32 位系统还是 64 位系统上，这一上限均严格成立。如果用户请求的 count 超出此范围，内核会将其截断至该最大值并执行读取，返回实际传输的字节数。

NFS 客户端属性缓存对访问时间的影响

在 NFS 网络文件系统上，连续读取少量数据可能仅在第一次调用时更新文件的访问时间戳（st_atime），随后的调用可能不会继续更新。

• 这是由于客户端属性缓存（client-side attribute caching）机制引起的：绝大多数 NFS 客户端将 st_atime 的更新委托给服务端，而命中客户端缓存的本地读取不会向服务端发送 RPC 请求。
• 虽可通过禁用客户端属性缓存来获得严格的传统 UNIX 语义，但在大部分实际生产环境下，这会显著增加网络开销并严重降低吞吐性能。

内核原子性与历史缺陷

参见 (SEE ALSO)

• close(2) — 关闭文件描述符
• fcntl(2) — 操控文件描述符属性与文件锁
• ioctl(2) — 控制设备 I/O
• lseek(2) — 重新定位读写文件偏移量
• open(2) — 打开或创建文件
• pread(2) — 在指定偏移量处读取文件（不更新文件偏移量）
• readv(2) — 分散读取数据到多个缓冲区（Scatter-Gather I/O）
• select(2) — 同步 I/O 多路复用
• write(2) — 向文件描述符写入数据
• sendfile(2) — 内核级文件到文件零拷贝传输
• splice(2) — 管道零拷贝数据移动
• epoll(7) — I/O 事件通知机制

代码示例 (EXAMPLE)

以下完整 C 示例展示了如何安全地使用 read() 读取文件内容，妥善处理局部读取（短读）以及被信号中断（EINTR）的边界情况：

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#define BUFFER_SIZE 4096

/**
 * 安全完整读取指定字节数的辅助函数
 * 自动处理 EINTR 信号中断与短读情况
 */
ssize_t read_all(int fd, void *buf, size_t count)
{
    size_t bytes_read = 0;
    char *ptr = (char *)buf;

    while (bytes_read < count) {
        ssize_t res = read(fd, ptr + bytes_read, count - bytes_read);
        if (res < 0) {
            if (errno == EINTR) {
                /* 被信号中断，重试读取 */
                continue;
            }
            /* 遇到其他严重错误 */
            return -1;
        }
        if (res == 0) {
            /* 提前到达文件末尾 EOF */
            break;
        }
        bytes_read += (size_t)res;
    }

    return (ssize_t)bytes_read;
}

int main(int argc, char *argv[])
{
    const char *filepath = "/etc/issue";
    if (argc > 1) {
        filepath = argv[1];
    }

    int fd = open(filepath, O_RDONLY);
    if (fd < 0) {
        perror("open failed");
        return EXIT_FAILURE;
    }

    char buffer[BUFFER_SIZE + 1];
    ssize_t n = read_all(fd, buffer, BUFFER_SIZE);
    if (n < 0) {
        perror("read failed");
        close(fd);
        return EXIT_FAILURE;
    }

    buffer[n] = '\0';
    printf("成功从 '%s' 读取了 %zd 字节数据：\n---\n%s\n---\n", filepath, n, buffer);

    if (close(fd) < 0) {
        perror("close failed");
        return EXIT_FAILURE;
    }

    return EXIT_SUCCESS;
}

sendfile(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

sendfile - 在文件描述符之间直接传输数据（内核级数据拷贝 / 零拷贝）

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#include <sys/sendfile.h>

ssize_t sendfile(int out_fd, int in_fd, off_t *_Nullable offset, size_t count);

描述 (DESCRIPTION)

sendfile() 在一个文件描述符与另一个文件描述符之间直接复制数据。由于该复制过程完全在内核空间中完成，因此 sendfile() 比 read(2) 与 write(2) 的组合更加高效——后者需要将数据在内核空间与用户空间之间来回拷贝（造成额外的上下文切换与内存复制开销）。

参数详解

• in_fd：

  • 用于读取数据的输入文件描述符。
  • 必须对应一个支持类似 mmap(2) 操作的文件（即不能是套接字 socket）。
  • 例外情况：自 Linux 5.12 起，如果 out_fd 是管道（pipe），则 sendfile() 会在内核中解糖（desugar）转换为 splice(2)，并适用 splice(2) 的相应限制规则。

• out_fd：

  • 用于写入数据的输出文件描述符。
  • 在 Linux 2.6.33 之前，out_fd 必须是一个套接字（socket）。
  • 自 Linux 2.6.33 起，out_fd 可以是任意文件。如果输出目标支持寻址定位（seekable），sendfile() 会相应地推进其文件偏移量。

• offset：

  • 指向保存输入文件读取起始偏移量的变量（类型为 off_t *）。
  • 非 NULL 时：sendfile() 从该指针所指的偏移量位置开始读取 in_fd 的数据。当调用返回时，该变量会被更新为紧跟最后读取字节之后的下一个偏移量。在此模式下，sendfile() 不会改变 in_fd 自身的文件偏移量。
  • 为 NULL 时：数据将从 in_fd 当前的文件偏移量处开始读取，并且调用完成后会直接推进并更新 in_fd 的当前文件偏移量。

• count：

  • 请求在两个文件描述符之间拷贝的字节数。

返回值 (RETURN VALUE)

• 成功：返回实际写入到 out_fd 的字节数。
  • 注意：一次成功的 sendfile() 调用写入的字节数可能少于请求的字节数（例如受到底层网络缓冲区大小或文件末尾限制）。若仍有未发送完的字节，调用者应当准备好循环重试。详见【注意事项】。
• 失败：返回 -1，并设置全局变量 errno 以指示具体错误原因。

错误代码 (ERRORS)

版本与兼容性 (VERSIONS)

其他 UNIX 系统（如 FreeBSD, Solaris）中也实现了名为 sendfile() 的接口，但它们具有不同的参数签名和语义。因此，在编写需要高度跨平台移植的程序时不应直接依赖该 Linux 调用。

标准 (STANDARDS)

无（None）。本系统调用为 Linux 特有实现，不属于 POSIX.1 标准规范。

历史演进 (HISTORY)

• Linux 2.2 / glibc 2.1：首次引入 sendfile()。
• Linux 2.4：最初在 2.4 及更早版本中 out_fd 支持常规文件，但在 2.6.x 早期被收窄仅支持 socket；直到 Linux 2.6.33 才彻底恢复并支持输出到任意文件。
• 大文件支持 (LFS)：早期 Linux sendfile() 未考虑 64 位大文件偏移量。Linux 2.4 引入了 sendfile64() 系统调用（提供 64 位宽的 offset 参数）。在现代 Linux 和 glibc 环境下，开启 _FILE_OFFSET_BITS=64 后，glibc 会透明映射到 64 位实现。

注意事项 (NOTES)

1. 单次传输上限： sendfile() 单次调用最多传输 0x7ffff000（即 2,147,479,552 字节，约 2GB - 4KB）的数据，返回实际传输的字节数。这在 32 位和 64 位系统上均成立。传输大文件时必须使用循环处理。

2. 配合 TCP_CORK 优化： 如果使用 sendfile() 向 TCP 套接字发送文件，但需要在文件内容前先发送协议头（如 HTTP Response Header），建议使用 setsockopt(2) 开启 TCP_CORK 选项。这可以将头部数据与文件内容合并在同一个 TCP 报文中发出，最小化数据包数量，显著提升吞吐量。

3. 优雅降级 (Fallback)： 若应用程序在某些老旧内核或特殊文件系统上遇到 sendfile() 返回 EINVAL 或 ENOSYS，建议在代码中编写回退逻辑，降级为常规的 read(2) + write(2) 循环。

4. 零拷贝内存一致性保护： 当 out_fd 是支持零拷贝的网络套接字或管道时，调用方必须确保源文件 in_fd 被传输的数据块在接收端彻底消费完成之前不被修改，否则可能导致对端接收到脏数据。

5. 与 splice(2) 的关系： Linux 特有的 splice(2) 支持在任意两个文件描述符之间传输数据（前提是其中至少一个是管道）。自 Linux 5.12 起，若 out_fd 为管道，sendfile() 内核底层直接复用 splice 机制。

参见 (SEE ALSO)

• copy_file_range(2)
• mmap(2)
• open(2)
• socket(2)
• splice(2)
• tcp(7)

经典用例：零拷贝发送文件至网络 Socket

#define _GNU_SOURCE
#include <sys/sendfile.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <errno.h>

/**
 * @brief 将指定文件全量零拷贝发送至客户端 socket
 * @param client_socket 目标网络连接描述符
 * @param filepath 本地文件路径
 * @return 成功返回发送的总字节数，失败返回 -1
 */
ssize_t send_file_zero_copy(int client_socket, const char *filepath) {
    int file_fd = open(filepath, O_RDONLY);
    if (file_fd < 0) {
        perror("open failed");
        return -1;
    }

    struct stat stat_buf;
    if (fstat(file_fd, &stat_buf) < 0) {
        perror("fstat failed");
        close(file_fd);
        return -1;
    }

    off_t offset = 0;
    size_t remain_bytes = stat_buf.st_size;
    ssize_t total_sent = 0;

    // 循环发送，应对单次传输未完全发送或上限为 2GB 的场景
    while (remain_bytes > 0) {
        ssize_t sent = sendfile(client_socket, file_fd, &offset, remain_bytes);
        if (sent <= 0) {
            if (sent < 0 && (errno == EAGAIN || errno == EWOULDBLOCK)) {
                // 非阻塞 socket 缓冲区满，可在 epoll/select 等可写事件后继续
                continue;
            }
            if (sent < 0 && errno == EINTR) {
                // 被信号中断，重试
                continue;
            }
            perror("sendfile error");
            close(file_fd);
            return -1;
        }

        total_sent += sent;
        remain_bytes -= (size_t)sent;
    }

    close(file_fd);
    return total_sent;
}

splice(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

splice - 在管道与文件描述符之间直接移动数据（内核级数据移动 / 零拷贝）

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#define _GNU_SOURCE         /* 参见 feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>

ssize_t splice(int fd_in, off_t *_Nullable off_in,
               int fd_out, off_t *_Nullable off_out,
               size_t size, unsigned int flags);

描述 (DESCRIPTION)

splice() 在两个文件描述符之间移动数据，无需在内核地址空间与用户空间之间来回拷贝数据。它最多将 size 字节的数据从文件描述符 fd_in 传输到文件描述符 fd_out。

偏移量与管道语义规则

针对输入描述符 fd_in 和偏移量指针 off_in：

• 若 fd_in 引用管道：
  • off_in 必须为 NULL。因为管道是不可寻址（nonseekable）的流式设备，无法指定偏移量。
• 若 fd_in 不引用管道且 off_in 为 NULL：
  • 数据从 fd_in 当前的文件偏移量处开始读取，并在调用完成后自动推进并更新 fd_in 的文件偏移量。
• 若 fd_in 不引用管道且 off_in 不为 NULL：
  • off_in 必须指向一个指定读取起始偏移量的 off_t 变量。
  • splice() 会从该偏移量读取数据，并在返回时将 off_in 指向的值更新为紧跟最后读取字节之后的偏移量。
  • 在此模式下，fd_in 自身的文件偏移量保持不变。

针对输出描述符 fd_out 和偏移量指针 off_out，适用完全对等的语义规则：

• 若 fd_out 引用管道，则 off_out 必须为 NULL。
• 若 fd_out 不引用管道且 off_out 为 NULL，则从当前文件偏移量写入并更新该偏移量。
• 若 fd_out 不引用管道且 off_out 不为 NULL，则写入到指定偏移量并仅更新指针指向的值，不改变 fd_out 本身的文件偏移量。

标志位参数 (flags)

flags 参数是一个位掩码，由以下零个或多个常量按位或（OR）组合而成：

返回值 (RETURN VALUE)

• 成功：返回实际在两个描述符之间拼接/传输的字节数。
  • 返回值 0 表示到达输入流末尾（EOF）。若 fd_in 是管道，意味着管道中已无数据，且由于写端已全部关闭，继续阻塞等待也无意义。
• 失败：返回 -1，并设置全局变量 errno 以指示具体的错误原因。

错误代码 (ERRORS)

标准 (STANDARDS)

无（None）。本系统调用为 Linux 特有（Linux-specific），不属于 POSIX.1 标准规范。

历史演进 (HISTORY)

• Linux 2.6.17 / glibc 2.5：首次引入 splice()。
• Linux 2.6.30 及更早版本：严格要求 fd_in 和 fd_out 中恰好只能有一个是管道。
• Linux 2.6.31：放宽了上述约束，支持两者均为管道（但仍然禁止两者都不是管道，且两者不能引用同一个管道）。

注意事项 (NOTES)

1. 零拷贝管道三剑客与内核缓冲区模型

系统调用 splice()、vmsplice(2) 与 tee(2) 为用户空间程序提供了对内核缓冲区的精细控制能力。内核使用与管道完全相同的缓冲区结构（pipe_buffer）来实现这一体系：

• splice()：在任意文件描述符与管道缓冲区之间双向搬运数据，或在两个管道缓冲区之间搬运。
• tee(2)：在两个管道缓冲区之间“复制”数据（仅复制页面引用，不发生物理数据拷贝）。
• vmsplice(2)：将用户空间内存页直接挂载/“复制”到管道缓冲区中。

2. 页面引用计数机制（零拷贝本质）

虽然接口逻辑概念被称为“移动”或“复制”，但内核实际上完全避免了真实的物理内存拷贝。 内核将管道缓冲区实现为指向内核物理内存页（struct page）的引用计数指针数组。当内核在管道之间传递数据时，仅在目标管道的缓冲区中创建指向该物理页的新指针，并递增该物理页的引用计数（page_ref_inc）。因此，拷贝的只是指针元数据，物理内存中的数据本身从未移动。

3. 大文件支持（_FILE_OFFSET_BITS 64）

在传统的 32 位 x86 和 ARM 平台上，off_t 的默认宽度是 32 位（仅支持最大 2GB 偏移）。为了确保代码在处理大文件时的可移植性，若代码中使用了非空的 off_in / off_out，必须在引入头文件之前显式定义：

#define _FILE_OFFSET_BITS 64

4. 任意文件间传输的“双 splice”经典范式

由于 splice() 要求必须有至少一端为管道，若要在两个非管道描述符之间传输数据（例如从 file_fd 到 socket_fd，或者从 socket_fd 到另一个 socket_fd），常见的工程范式是利用一对管道作为中转站：

[文件描述符 A] ---- splice ----> [管道 Pipe] ---- splice ----> [文件描述符 B]

这种方法使得数据始终在内核页缓存与管道页之间流转，全程不需要进出用户空间内存缓冲区，比传统的 read() + write() 节省多次上下文切换与 CPU 内存拷贝开销。

参见 (SEE ALSO)

• copy_file_range(2)
• pipe(2)
• pipe(7)
• sendfile(2)
• tee(2)
• vmsplice(2)

经典用例与代码示例

示例 1：双 splice 实现零拷贝文件复制（两个普通描述符间传输）

#define _GNU_SOURCE
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>

/**
 * @brief 使用中间管道通过两次 splice 在任意描述符之间零拷贝传输数据
 * @param fd_in 源文件描述符
 * @param fd_out 目标文件描述符
 * @param len 传输字节数
 * @return 成功传输的字节数，遇到错误返回 -1
 */
ssize_t transfer_splice(int fd_in, int fd_out, size_t len) {
    int pipefd[2];
    if (pipe(pipefd) < 0) {
        perror("pipe creation failed");
        return -1;
    }

    size_t total_transferred = 0;

    while (total_transferred < len) {
        size_t chunk = len - total_transferred;

        // 步骤 1：从源文件 splice 到管道写端
        ssize_t bytes_in = splice(fd_in, NULL, pipefd[1], NULL, chunk, SPLICE_F_MOVE | SPLICE_F_MORE);
        if (bytes_in < 0) {
            if (errno == EINTR) continue;
            perror("splice in failed");
            close(pipefd[0]);
            close(pipefd[1]);
            return -1;
        }
        if (bytes_in == 0) {
            // 源文件已到达 EOF
            break;
        }

        // 步骤 2：从管道读端 splice 到目标文件
        size_t bytes_to_write = (size_t)bytes_in;
        while (bytes_to_write > 0) {
            ssize_t bytes_out = splice(pipefd[0], NULL, fd_out, NULL, bytes_to_write, SPLICE_F_MOVE | SPLICE_F_MORE);
            if (bytes_out < 0) {
                if (errno == EINTR) continue;
                perror("splice out failed");
                close(pipefd[0]);
                close(pipefd[1]);
                return -1;
            }
            bytes_to_write -= (size_t)bytes_out;
            total_transferred += (size_t)bytes_out;
        }
    }

    close(pipefd[0]);
    close(pipefd[1]);
    return (ssize_t)total_transferred;
}

示例 2：标准手册示例（管道数据传输与精确偏移量控制）

#define _GNU_SOURCE
#define _FILE_OFFSET_BITS 64
#include <err.h>
#include <fcntl.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

int main(void) {
    int fd;
    int pfd[2];
    off_t off;
    const char s[12] = "Hello, world";

    // 创建或打开目标文件
    fd = open("out.txt", O_WRONLY | O_CREAT | O_TRUNC, 0644);
    if (fd == -1)
        err(EXIT_FAILURE, "open");

    // 创建管道
    if (pipe(pfd) == -1)
        err(EXIT_FAILURE, "pipe");

    // 将测试数据写入管道
    if (write(pfd[1], s, sizeof(s)) != sizeof(s))
        err(EXIT_FAILURE, "write");
    close(pfd[1]); // 关闭写端以产生 EOF 条件

    // 从管道 splice 到常规文件，并通过 &off 指定写入偏移量
    off = 10;
    if (splice(pfd[0], NULL, fd, &off, sizeof(s), 0) != sizeof(s))
        err(EXIT_FAILURE, "splice");
    close(pfd[0]);

    printf("写入完成，更新后的文件偏移量为: %jd\n", (intmax_t)off);

    close(fd);
    unlink("out.txt"); // 清理测试文件
    return EXIT_SUCCESS;
}

tee(2) — Linux 系统调用手册

对应手册: Linux man-pages 6.20 (2026)
分类章节: 第 2 节 —— 系统调用（System Calls）
目录代号: man2

名称 (NAME)

tee - 复制管道内容（内核级零拷贝流分支复制）

库 (LIBRARY)

标准 C 库 (libc, -lc)

概述 (SYNOPSIS)

#define _GNU_SOURCE         /* 参见 feature_test_macros(7) */
#include <fcntl.h>

ssize_t tee(int fd_in, int fd_out, size_t size, unsigned int flags);

描述 (DESCRIPTION)

tee() 系统调用最多将 size 字节的数据从文件描述符 fd_in 所引用的管道，复制到文件描述符 fd_out 所引用的管道中。

参数详解

• fd_in：源管道的文件描述符（必须引用管道）。
• fd_out：目标管道的文件描述符（必须引用管道，且不能与 fd_in 引用同一个管道）。
• size：希望复制的最大字节数。
• flags：控制复制行为的位掩码参数，由以下零个或多个常量按位或（OR）组合而成：

返回值 (RETURN VALUE)

• 成功：返回实际在输入和输出管道之间成功复制的字节数。
  • 返回值 0 表示当前无数据可传输（即源管道为空），并且此时阻塞已无意义，因为引用 fd_in 管道写端的所有写进程均已关闭（即写端已遇 EOF）。
• 失败：返回 -1，并设置全局变量 errno 以指示具体的错误原因。

错误代码 (ERRORS)

标准 (STANDARDS)

Linux 特有。本系统调用为 Linux 专属接口（Linux-specific），非 POSIX.1 标准定义。

历史演进 (HISTORY)

• Linux 2.6.17 / glibc 2.5：首次引入 tee() 系统调用。

注意事项 (NOTES)

1. 概念模型与零拷贝本质

从概念上讲，tee() 负责在两个管道之间“复制”数据。然而在 Linux 内核实现深处，根本不发生任何实际的物理内存数据拷贝。

内核底层的管道缓冲区使用 struct pipe_buffer 管理物理内存页（struct page）。当 tee() 执行时，内核仅在目标管道的缓冲区环形队列中追加指向源物理页的引用指针，并递增对应内存页的引用计数（get_page() / 引用递增）。
因此：

• 数据完全停留在内核物理页中，不经过 CPU 拷贝，也不经过用户空间内存。
• 消耗的仅是极其微小的内核结构元数据开销。

2. 零拷贝三剑客的分工协同

Linux 提供了三个紧密协作的管道零拷贝系统调用：

1. splice(2)：数据移动（消费型）。在管道与任意文件/套接字之间传输数据，或者在两个管道间搬运数据（会消耗源端数据）。
2. tee(2)：数据分流（非消费型）。在两个管道之间复制数据，保留源管道数据供后续消费。
3. vmsplice(2)：用户空间与内核管道嫁接。将用户内存页直接映射插入到管道中。

3. 典型流式分支架构（Tee + Splice 范式）

在网络代理、视频多路推流、实时日志归档等场景中，常用 tee() 与 splice() 组合构建高效的流分发系统：

               +------------------> [管道 B] ---- splice ----> [网络 Socket / 实时处理]
               | (tee 复制指针引用)
[数据源] ---> [管道 A]
               |
               +------------------> (splice 消费数据) -------> [本地文件 / 日志落盘]

4. 管道容量与死锁防范

• 管道具有固定的容量缓冲区（在现代 Linux 内核中默认为 64KB，可通过 fcntl(fd, F_SETPIPE_SZ, size) 进行动态调整）。
• 当使用 tee() 将数据复制到目标管道时，如果目标管道的缓冲区已满且未被消费端读取，tee() 可能会阻塞（若未设置 SPLICE_F_NONBLOCK）。
• 工程建议：若要实现高吞吐的多路分发，务必保证下游消费端并发消费，或为下游分支管道设置非阻塞并在缓冲区满时采取合理的背压/丢弃策略。

参见 (SEE ALSO)

• splice(2)
• vmsplice(2)
• pipe(2)
• pipe(7)
• tee(1)

经典用例与代码示例

示例 1：Linux 手册标准示例（使用系统调用实现简易 tee(1) 工具）

以下程序使用 tee(2) 与 splice(2) 实现了类似 shell 命令 tee 的核心功能：从标准输入读取数据，在输出到标准输出的同时，将数据写入到指定的文件中。全程无需经过用户空间内存缓冲区。

#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

int main(int argc, char *argv[])
{
    int      fd;
    ssize_t  size, ssize;

    if (argc != 2) {
        fprintf(stderr, "用法: %s <目标文件>\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);
    if (fd == -1) {
        perror("open 失败");
        exit(EXIT_FAILURE);
    }

    for (;;) {
        /*
         * 步骤 1: 使用 tee() 将 stdin (管道) 数据复制到 stdout (管道)。
         * 注意：tee() 仅复制页引用，不会消耗 stdin 中的数据！
         */
        size = tee(STDIN_FILENO, STDOUT_FILENO,
                   INT_MAX, SPLICE_F_NONBLOCK);
        if (size < 0) {
            if (errno == EAGAIN)
                continue;
            perror("tee 错误");
            exit(EXIT_FAILURE);
        }
        if (size == 0)
            break; // stdin 管道写端已关闭，传输完成

        /*
         * 步骤 2: 使用 splice() 将 stdin 中刚才被 tee 复制过的数据消费掉，
         * 并直接写入到目标磁盘文件中。
         */
        while (size > 0) {
            ssize = splice(STDIN_FILENO, NULL, fd, NULL,
                           size, SPLICE_F_MOVE);
            if (ssize < 0) {
                perror("splice 写入文件错误");
                exit(EXIT_FAILURE);
            }
            size -= ssize;
        }
    }

    close(fd);
    exit(EXIT_SUCCESS);
}

运行与验证

# 编译程序
gcc -O2 tee_demo.c -o tee_demo

# 测试：通过管道输入，并同时在终端显示和写入日志
date | ./tee_demo out.log | cat
cat out.log

示例 2：工程实战：流数据单写双读（广播分发至两个处理管道）

在某些高性能微服务或旁路监控系统中，需要将一份数据流无损分发给两个独立的消费线程或进程：

#define _GNU_SOURCE
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>

/**
 * @brief 将源管道中的数据同时广播分发至目标管道 A 和目标管道 B
 * @param p_in   源管道读端描述符
 * @param p_outA 旁路管道写端描述符（保留副本）
 * @param p_outB 主路管道写端描述符（消费数据）
 * @param len    请求传输的最大字节数
 * @return 实际分发的字节数
 */
ssize_t tee_broadcast(int p_in, int p_outA, int p_outB, size_t len) {
    // 1. 将数据从 p_in 零拷贝复制给旁路管道 p_outA（不消耗 p_in 数据）
    ssize_t teed = tee(p_in, p_outA, len, SPLICE_F_NONBLOCK);
    if (teed < 0) {
        if (errno != EAGAIN) {
            perror("tee 到旁路管道失败");
            return -1;
        }
        teed = 0; // 旁路满时可根据业务选择跳过或重试
    }

    // 2. 将数据从 p_in splice 移动消费至主路管道 p_outB
    size_t to_splice = (teed > 0) ? (size_t)teed : len;
    ssize_t spliced = splice(p_in, NULL, p_outB, NULL, to_splice, SPLICE_F_MOVE);
    if (spliced < 0) {
        perror("splice 到主路管道失败");
        return -1;
    }

    return spliced;
}