如何在 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 显示的文件大小或卷可用空间的变化。这些信息无法同时证明容量预留有效、设备映射已经建立,以及映射今后不会改变。
备注:内容仅供参考。
