PAYATHON 2026

如何在 macOS APFS 卷上预分配文件空间并创建 extents?

技术老齐

结论

在 APFS 上,可以用 fcntl(fd, F_PREALLOCATE, ...) 为文件预留空间,通常不需要 root 权限。不过,macOS 的公开接口并不保证预分配后就能通过 F_LOG2PHYS_EXT 查到尚未写入区域的设备地址。

具体做法取决于需求:

  • 要提前预留容量,可以使用 F_PREALLOCATE,再用 ftruncate 设置文件长度。
  • 要提前取得可用的设备位置,不能依赖预分配接口。实际写入后可以再次查询,但查到的地址也不保证永久不变。

F_ALLOCATEALL 和 F_ALLOCATEPERSIST 都不保证立即创建可查询的物理映射。这是公开 API 的保证范围,不能据此认定所有 APFS 版本的内部实现都相同。Apple 的接口定义

为什么 ftruncate 得到的是 sparse file

ftruncate(fd, size) 设置文件的逻辑长度。扩展部分读取时必须返回零,但文件系统不必把这些零逐字节写入磁盘,也不保证分配同等大小的存储空间。Apple 的 truncate(2) 手册

APFS 支持 sparse file,可以用空洞表示尚未存储的数据。因此,文件显示为 10 GiB,实际占用却很小,符合这类文件系统的行为。Apple 文件系统说明

文件的逻辑长度、预留容量和能查到设备映射的数据范围是三个不同的量,不必同步增长。

如何预留空间

对于新建的空文件,可以先预分配,再设置长度:

#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
#include <errno.h>

/*
 * 在调用者控制的目录中创建新文件。
 * 成功时返回仍然打开的文件描述符,供稍后写入。
 * 失败时返回 -1,并保留 errno。
 */
int create_reserved_file(const char *path, off_t size)
{
    if (size <= 0) {
        errno = EINVAL;
        return -1;
    }

    int fd = open(path, O_RDWR | O_CREAT | O_EXCL, 0600);
    if (fd == -1)
        return -1;

    fstore_t store = {0};
    store.fst_flags = F_ALLOCATEALL | F_ALLOCATEPERSIST;
    store.fst_posmode = F_PEOFPOSMODE;
    store.fst_offset = 0;
    store.fst_length = size;

    if (fcntl(fd, F_PREALLOCATE, &store) == -1)
        goto fail;

    if (store.fst_bytesalloc < size) {
        errno = ENOSPC;
        goto fail;
    }

    if (ftruncate(fd, size) == -1)
        goto fail;

    return fd;

fail:
    {
        int saved_errno = errno;
        close(fd);
        unlink(path);
        errno = saved_errno;
        return -1;
    }
}

这段代码用于预留空间,不保证随后能取得所有 extents 的设备地址。各参数的含义如下:

  • F_ALLOCATEALL 要求分配全部请求空间,否则不分配。
  • F_ALLOCATEPERSIST 请求在关闭文件描述符后保留预分配空间,但手册明确允许文件系统忽略这一请求。
  • 在 F_PEOFPOSMODE 下,fst_length 表示希望新增分配的字节数。因此,示例仅适用于新建的空文件,不能直接用于已有数据或已有预分配空间的文件。

这些语义见 Apple 的 fcntl(2) 手册。如果稍后仍在同一进程内写入,可以保留文件描述符,直到写入结束,以免依赖关闭后的预留行为。如果必须关闭后重新打开,则需要在目标系统上单独验证。

F_ALLOCATECONTIG 可以请求连续空间,但不保证生成可查询的 extents。

如何理解 l2p_devoffset == -1

需要区分调用失败和调用成功却未返回设备地址的情况:

fcntl(fd, F_LOG2PHYS_EXT, &l2p) == -1

表示调用失败,应检查 errno。

fcntl(fd, F_LOG2PHYS_EXT, &l2p) == 0
l2p.l2p_devoffset == -1

表示调用成功,但没有返回该位置的有效设备地址。Apple 手册说明,文件区域没有物理块支撑时,设备地址可能返回 -1。仅凭这个字段,无法判断空间预留是否失败,也无法完整推断 APFS 内部有哪些元数据记录。Apple 的 F_LOG2PHYS 说明

查询循环必须检查调用结果和返回长度,否则在调用失败或长度为零时,循环可能无法前进:

#include <stdio.h>

int print_extents(int fd, off_t size)
{
    off_t offset = 0;

    while (offset < size) {
        off_t remaining = size - offset;

        struct log2phys map = {0};
        map.l2p_contigbytes = remaining;
        map.l2p_devoffset = offset;

        if (fcntl(fd, F_LOG2PHYS_EXT, &map) == -1) {
            perror("F_LOG2PHYS_EXT");
            return -1;
        }

        if (map.l2p_contigbytes <= 0 ||
            map.l2p_contigbytes > remaining) {
            fprintf(stderr, "Invalid mapping length\n");
            return -1;
        }

        if (map.l2p_devoffset < 0) {
            printf("File offset %lld, length %lld: "
                   "no device address returned\n",
                   (long long)offset,
                   (long long)map.l2p_contigbytes);
        } else {
            printf("File offset %lld, length %lld, "
                   "device offset %lld\n",
                   (long long)offset,
                   (long long)map.l2p_contigbytes,
                   (long long)map.l2p_devoffset);
        }

        offset += map.l2p_contigbytes;
    }

    return 0;
}

接口返回的是映射查询结果,不能直接视为 APFS 磁盘元数据中 extent 记录的逐条枚举。

必须取得设备位置时怎么办

如果业务依赖设备地址,可以先预留空间,再实际写入需要映射的范围,调用 fsync 并检查结果,最后查询映射。fsync 用于同步已有修改,不保证把未写入的空洞转换成具有设备地址的数据块。

查询成功后,结果也只代表查询时的映射。APFS 具有写时复制、克隆和快照机制,公开接口不保证文件映射永久固定。Apple 对 APFS 特性的说明

换用 CoreFoundation 或 Foundation,也没有公开文档保证能绕过这些限制。root 权限不会改变 F_PREALLOCATE 的接口语义。旧的 F_SETSIZE 已弃用,也不能作为免写入分配的替代方案。

原示例中还需要修正的细节

0x40000000LL * 10 实际是 10 GiB,即 10,737,418,240 字节。open 的标志应使用 O_WRONLY | O_CREAT 这样的按位或写法。

如果采用实际写入方案,必须先初始化缓冲区。直接写出 malloc 返回的未初始化内存,会把不确定的内容写入文件。write 的返回值应使用 ssize_t 接收,并处理短写和 EINTR;为此一次申请 1 GiB 缓冲区并无必要。

判断是否成功,不能只看 Finder 显示的文件大小或卷可用空间的变化。这些信息无法同时证明容量预留有效、设备映射已经建立,以及映射今后不会改变。

备注:内容仅供参考。