写过一阵子 Linux 下文件操作的人对#include sys/stat.h这行大概都不会陌生但真正能把它说明白的人并不多。有意思的是不少人在搜索引擎里输的是sys.stat.h——一个把斜杠打成点的写法这个小笔误本身就很说明问题大家知道有这么个头文件知道它跟文件有关却不太清楚它到底管什么、不管什么。stat在这里不是统计学的统计而是 status 的缩写。这个头文件是 POSIX 给文件系统元数据开的一扇正门文件多大、是普通文件还是目录、权限位怎么设、最后一次内容修改发生在什么时候、硬链接数是多少所有这些信息都通过它声明的struct stat和stat、fstat、lstat、mkdir、chmod、umask这一组接口拿到。不管你是刚接触系统编程的新手还是写了好几年业务代码、每次碰到权限问题都靠猜的老手把这一套东西理顺都能省下大量调试时间。下面我按它声明了什么、结构体怎么读、三个调用怎么选、建目录改权限怎么落地、哪些字段会咬人、跨平台怎么迁的顺序把我踩过的和见过的坑一次讲透。1. stat 不是统计这个头文件的职责边界在哪先把最容易混淆的一点摆正。stat这个词在这套接口里全程指代状态statussys/stat.h直译过来就是系统状态头文件只不过它管的状态特指文件系统对象的状态。你在 shell 里敲stat somefile、ls -l背后展示的那一堆信息包括 inode 号、权限串-rw-r--r--、大小、链接数、三个时间戳本质上都是这个头文件声明的接口吐出来的。理解这一点后面所有 API 的命名逻辑就顺了fstat是对文件描述符取状态lstat是取链接本身的状态chmod是改 modemkdir是造一个目录全都在文件状态这条主线上。很多人第一次被它绊住是因为搜到的资料要么只贴一个struct stat的字段表要么直接甩一段stat()调用示例中间那层为什么需要它、什么时候不需要它的说明是缺失的。我见过有同学为了判断一个路径存不存在专门去#include sys/stat.h然后写stat调用其实用access()或者直接open()看errno更贴合场景也见过有人拿stat的返回值当文件大小用结果对目录调用时拿到一个诡异的数字排查了半天。这一节先把边界划清楚后面几节再往里钻。1.1 头文件里实际躺着三类东西打开 glibc 的sys/stat.h不同 libc 的具体路径不同通常是/usr/include/x86_64-linux-gnu/sys/stat.h加一个bits/stat.h你会发现内容高度结构化就三类函数声明、结构体定义、宏常量。搞清楚这三类各自的用途比死记字段名有用得多。类别代表内容用在哪函数statfstatlstatchmodfchmodmkdirmkfifoumaskfutimens取状态、改权限、建目录/管道、改时间戳结构体struct stat承载一次取状态调用的全部结果类型mode_tdev_tino_tnlink_toff_tblkcnt_tblksize_t结构体字段和函数参数的类型宏S_IFMTS_IFREGS_IFDIR等文件类型S_IRUSRS_IWGRP等权限位S_ISREG()S_ISDIR()等判定宏位运算判断需要提醒的是mode_t、off_t这些类型严格来说是sys/types.h定义的sys/stat.h会把它包含进来所以你在代码里只写#include sys/stat.h也能用mode_t。但如果你要在别的地方单独声明一个mode_t变量而又不涉及 stat 系列函数规范做法是显式包含sys/types.h。这个细节在移植到某些精简 libc 时会突然变成编译错误属于平时不出事、换环境就炸的典型。还有几个不那么常用的成员值得知道mkfifo用来创建命名管道做进程间通信时会用到futimens和utimensat可以在不改变文件内容的前提下精确设置访问时间和修改时间做构建系统或者增量同步工具时特别有用它们支持两个特殊值UTIME_NOW和UTIME_OMIT后者表示这个时间戳别动省去了先读再写的麻烦。1.2 为什么有很多代码不写这行也能编过这是新手最容易产生的错觉明明自己没写#include sys/stat.h代码里却能用struct stat编译还没报错。原因通常是别的头文件把它间接带进来了。比如某些项目的公共头文件里包含了sys/types.h和sys/stat.h或者某个第三方库的头文件顺手包含了它于是你的源文件白嫖到了声明。这种依赖是非常脆弱的。glibc 能过不代表 musl 能过Linux 能过不代表 macOS 能过。我遇到过不止一次本地开发机编译一切正常CI 跑在 Alpine 上直接报storage size of st isnt known——因为struct stat是不完整类型编译器根本不知道要分配多大空间。修起来很简单加一行 include 就行但排查过程如果没有隐式包含这个意识很容易怀疑到别的地方去。提示判断某个类型是不是靠隐式包含拿到的最直接的办法是把可疑的 include 全部注释掉只留标准库的最小集合重新编译一次报错位置会立刻告诉你真相。养成习惯只要你的代码里出现了struct stat、mode_t、S_ISDIR这些符号就在该源文件顶部显式写上#include sys/stat.h哪怕它已经被别的头文件包含过。多余的一行 include 有头文件保护不会带来任何运行时开销但能省下未来某次跨平台构建的一小时。1.3 和 fcntl.h、unistd.h 的分工要理清文件操作相关的头文件容易混这里给一个我自己的记忆方式打开与属性在 fcntl.h 和 sys/stat.h读写与关闭在 unistd.h。open()的O_RDONLY、O_CREAT、O_NOFOLLOW这些标志位在fcntl.h里read()、write()、close()、unlink()、rmdir()、access()在unistd.h里而stat系列、chmod系列、mkdir、umask在sys/stat.h里。这个分工不是随意划的它反映的是元数据操作和数据流操作的分离。stat不碰文件内容只读 inode 里的信息chmod也不碰内容只改 inode 里的权限位。而read/write走的是文件描述符的数据通道。理解了这层你就明白为什么fstat需要一个已经打开的 fd而stat只需要一个路径——前者是在数据通道建立之后再问元数据后者是直接按路径去查。2. struct stat 的字段不是摆设st_mode 才是主战场struct stat的字段数量在不同平台上略有差异Linux 上大概十来个字段顺序由 ABI 固定绝对不要自己照着网上的文章复制一份结构体定义——这是我在代码评审里见过的最危险的操作之一。你自己定义的struct stat和系统头文件里的布局一旦对不上stat()调用不会报错它会老老实实往你给的那块内存里按系统布局写数据然后你按自己的布局去读读出来的就是一堆垃圾值。这种 bug 极难排查因为没有任何错误码提示。正确做法永远是#include sys/stat.h然后用系统给的定义。如果你确实需要跨编译单元传递这些信息也应该传自己定义的一个精简结构体在边界处做一次显式拷贝转换。2.1 按用途把字段分成四组字段多硬背没意义按用途分组记就轻松了。下面这张表我按标识、类型、尺寸、时间四组整理分组字段说明标识st_devst_ino设备号 inode 号二者组合唯一标识一个文件类型与权限st_modest_uidst_gidst_nlinkst_rdev文件类型 权限位、属主、属组、硬链接数、设备文件的主次设备号尺寸st_sizest_blksizest_blocks字节大小、推荐的 I/O 块大小、占用的 512 字节块数时间st_atimst_mtimst_ctim访问、修改、状态变更时间都是struct timespec两个容易混的点提前说清楚。第一st_blksize是推荐 I/O 块大小通常是 4096它是给read/write缓冲区大小做参考的不是文件占用的块大小真正表示磁盘占用的是st_blocks单位固定为 512 字节跟st_blksize没关系。第二st_size对普通文件是字节数对符号链接是链接目标字符串的长度对目录是实现相关的——也就是说你在 Linux 上看到目录的st_size是 4096 或者更大别拿它当目录里文件总大小用那完全是两回事。时间字段的命名在不同平台上还有差异。Linux/glibc 用st_atim、st_mtim、st_ctim带tv_sec和tv_nsec同时保留了st_atime、st_mtime、st_ctime这几个宏作为兼容别名只取秒部分。macOS 上则叫st_atimespec、st_mtimespec、st_ctimespec。写跨平台代码时取秒级时间用st_mtime最稳需要纳秒精度就得加平台判断。2.2 st_mode 的位布局高四位定类型低十二位定权限st_mode是mode_t类型通常是 32 位无符号整型它把文件类型和权限位塞进了同一个整数里。这个设计非常紧凑但也意味着你必须用位掩码来读不能直接比较。高位的文件类型占了 4 个比特掩码是S_IFMT八进制0170000。具体取值宏八进制值含义S_IFREG0100000普通文件S_IFDIR0040000目录S_IFLNK0120000符号链接S_IFCHR0020000字符设备S_IFBLK0060000块设备S_IFIFO0010000命名管道S_IFSOCK0140000套接字文件低十二位是权限八进制07777。其中最高的三位是特殊位S_ISUID04000、S_ISGID02000、S_ISVTX01000剩下九位是属主/属组/其他的 rwx。S_IRWXU是0700S_IRUSR是0400S_IWUSR是0200S_IXUSR是0100G和O两组同理右移。为什么必须用S_IFMT掩码因为st_mode里同时有类型位和权限位你写if (st.st_mode S_IFDIR)永远为假除非这个目录权限恰好是 0。正确的写法是(st.st_mode S_IFMT) S_IFDIR或者直接用宏S_ISDIR(st.st_mode)。2.3 别再手写 (mode 0170000) 0100000 了S_ISREG、S_ISDIR、S_ISLNK、S_ISCHR、S_ISBLK、S_ISFIFO、S_ISSOCK这一组宏就是上面位运算的封装。它们的实现在 glibc 里大致是这样#define S_ISREG(m) (((m) S_IFMT) S_IFREG) #define S_ISDIR(m) (((m) S_IFMT) S_IFDIR) #define S_ISLNK(m) (((m) S_IFMT) S_IFLNK)我见过不少老代码直接写st.st_mode S_IFDIR来判断目录这在多数情况下碰巧能用因为目录的类型位0040000里有非零位与运算结果非零就为真。但它是错的任何类型为S_IFREG的文件st_mode里0040000这一位也可能是 10100000和0040000的位并不互斥于是普通文件会被误判成目录。这类 bug 在测试环境里可能因为样本文件权限简单而侥幸躲过一到生产就爆。一个完整的类型判断写法#include sys/stat.h #include stdio.h static const char *type_name(mode_t m) { if (S_ISREG(m)) return regular; if (S_ISDIR(m)) return directory; if (S_ISLNK(m)) return symlink; if (S_ISCHR(m)) return char-device; if (S_ISBLK(m)) return block-device; if (S_ISFIFO(m)) return fifo; if (S_ISSOCK(m)) return socket; return unknown; }注意S_ISLNK只在lstat的结果里才可能为真。stat()会跟随符号链接返回的是目标文件的状态所以对软链接调用stat得到的类型是目标文件的类型。这个差异是下一节的重点。3. stat、fstat、lstat 的选择逻辑与 TOCTOU 竞态三个函数签名几乎一样参数都是路径或 fd struct stat *理解它们的差异是写好文件操作代码的分水岭。用错不会编译报错但行为会差出十万八千里。3.1 三者的差异点浓缩成一句话stat跟随符号链接lstat不跟随fstat用已打开的文件描述符。这句总结好记但真正重要的是知道什么时候该用哪个。函数首个参数是否跟随软链接典型场景statconst char *path是想知道我打开这个路径最终会拿到什么lstatconst char *path否遍历目录、备份工具、判断是否为链接fstatint fd不涉及路径已打开文件后取状态天然免疫竞态遍历目录树时99% 的情况应该用lstat。因为你要的是这个目录项本身是什么遇到符号链接就记录下来、不去跟随否则一个指向父目录的软链接会让你的递归无限循环直接把栈打爆。这个坑我在写第一个文件清理脚本时踩过脚本跑了三秒就把内存吃满了。反过来你要判断这个路径能不能读、多大、是不是普通文件用stat更符合直觉——因为你接下来要open的就是目标文件问链接本身的状态没有意义。3.2 软链接场景下的实测差异拿一个软链接做对照差别一目了然。假设link.txt - real.txtreal.txt内容是 5 个字节#include sys/stat.h #include stdio.h #include time.h void dump(const char *tag, const struct stat *st) { printf(%-6s type%s size%lld ino%llu\n, tag, S_ISLNK(st-st_mode) ? LNK : S_ISREG(st-st_mode) ? REG : OTHER, (long long)st-st_size, (unsigned long long)st-st_ino); } int main(void) { struct stat a, b; if (stat(link.txt, a) 0) dump(stat, a); if (lstat(link.txt, b) 0) dump(lstat, b); return 0; }实测输出大致是stat那行显示REG、size5lstat那行显示LNK、size8也就是real.txt这个目标字符串的长度。同一个路径两个调用给出完全不同的答案st_ino也可能不同软链接有自己的 inode。这就是为什么备份工具、rsync这类软件必须用lstat——它们要原样保留链接结构而不是把链接解开变成实体文件。3.3 先 stat 再 open 的经典竞态这是安全领域的老问题但日常业务代码里天天有人这么写/* 反例TOCTOU检查时与使用时不一致 */ struct stat st; if (stat(path, st) 0 S_ISREG(st.st_mode)) { int fd open(path, O_RDONLY); /* 这一行之间path 可能被换掉 */ /* ... */ }问题在于stat和open之间存在一个时间窗口。如果这个路径在共享目录、临时目录或者被其他进程可控攻击者可以在这两步之间把普通文件替换成指向敏感位置的符号链接你的open就会打开意料之外的文件。这类漏洞有个统一的名字叫 TOCTOU。还有一种变体更隐蔽先用stat检查文件大小再按这个大小分配缓冲区去读。中间文件被追加内容读的时候缓冲区就不够了。或者反过来文件被截断你读到一堆空洞。3.4 正确的姿势是 open 完再 fstat把检查挪到打开之后用fstat对已经拿到的 fd 做判断路径就不再参与后续决策竞态窗口彻底消失#include fcntl.h #include sys/stat.h #include unistd.h #include errno.h int open_regular(const char *path, int *out_fd, struct stat *out_st) { int fd open(path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); if (fd -1) return -1; /* ELOOP 表示最后一段是软链接 */ struct stat st; if (fstat(fd, st) -1) { int saved errno; close(fd); errno saved; return -1; } if (!S_ISREG(st.st_mode)) { close(fd); errno EINVAL; return -1; } *out_fd fd; *out_st st; return 0; }这里有三个细节值得展开。O_NOFOLLOW保证如果路径最后一段是符号链接就直接失败errno为ELOOP这是比lstat更彻底的防护因为它把检查和打开合并成一个原子操作。O_CLOEXEC让 fd 在exec家族调用后自动关闭避免子进程意外继承——这个标志在写守护进程或者调用外部命令时几乎是必须的不加的话很容易出现文件句柄泄漏到子进程、父进程关了子进程还占着的怪现象。最后错误处理里要先把errno存下来再close因为close本身失败时会覆盖errno这个坑我调过不止一次。注意open成功后立刻fstat然后基于st做所有后续判断中间不要再碰路径字符串。这条规则能消灭你代码里 90% 的文件相关竞态。4. 建目录与改权限mkdir、chmod、umask 的联动实操sys/stat.h里被用得最多的函数其实是mkdir其次才是stat。而mkdir又是最容易让人产生我的参数怎么不生效疑问的一个。4.1 mkdir 的 mode 参数为什么经常不生效mkdir(/tmp/mydir, 0777); /* 你以为会得到 drwxrwxrwx */跑完ls -ld /tmp/mydir看到的多半是drwxr-xr-x也就是0755。这不是 bug是umask在起作用。mkdir的第二个参数叫期望权限实际创建出来的权限等于mode ~umask。umask是进程级属性含义是从新建文件的默认权限里屏蔽掉哪些位。绝大多数 shell 的默认umask是022也就是屏蔽掉组和其他用户的写权限。所以0777 ~022 07550775 ~022 07550700 ~022 0700。计算过程拆开看更清楚。~022在 32 位下是...1111111111011101跟0777按位与把0022对应位置的两个 1 清零得到0755。如果umask是077那0777 ~077 0700只有属主有权限。做安全敏感的服务时很多团队会把服务进程的umask显式设成077确保新建文件天然对其他用户不可见。想读到当前umask而不改变它标准做法是先设后恢复#include sys/stat.h mode_t current_umask(void) { mode_t old umask(0); umask(old); return old; }这个写法有个小瑕疵中间那一瞬间umask是 0如果是多线程程序恰好有别的线程在这个窗口里创建文件就会得到过于宽松的权限。对权限敏感的场景正确做法是在程序启动、还没起线程的时候就记录一次umask后面直接用缓存值。4.2 递归建目录mkdir -p 的手写实现标准 C 库没有mkdir -p的等价函数需要自己逐级创建。这个函数看起来简单但错误处理有不少讲究#include sys/stat.h #include string.h #include errno.h #include limits.h int mkdir_p(const char *path, mode_t mode) { char tmp[PATH_MAX]; size_t len strlen(path); if (len 0 || len sizeof(tmp)) { errno ENAMETOOLONG; return -1; } memcpy(tmp, path, len 1); for (char *p tmp 1; *p ! \0; p) { if (*p ! /) continue; *p \0; if (mkdir(tmp, mode) -1 errno ! EEXIST) return -1; *p /; } if (mkdir(tmp, mode) -1) { if (errno ! EEXIST) return -1; struct stat st; if (stat(tmp, st) -1) return -1; if (!S_ISDIR(st.st_mode)) { errno ENOTDIR; return -1; } } return 0; }几个关键点。第一从tmp 1开始扫描跳过第一个字符这样处理绝对路径/a/b/c时不会尝试创建空字符串路径。第二EEXIST不能无条件当成成功——如果这个位置上已经存在一个同名普通文件mkdir同样返回-1且errno是EEXIST但它不是目录后续往里写文件会失败。所以最终一步必须补一次stat确认是目录不是就返回ENOTDIR。第三中间层级遇到EEXIST不做检查是常见取舍因为逐级stat会显著增加系统调用次数如果你对健壮性要求高可以把每个层级都检查一遍代价是路径深度翻倍的 syscall。第四PATH_MAX在有些系统上是不确定的比如 GNU Hurd严格可移植的写法要用动态分配日常 Linux 环境用PATH_MAX够用。还有一个细节容易被忽略中间层级的mkdir用的也是同样的mode但最终权限会被umask削减。如果你需要指定精确权限比如0750应该在全部创建完成后对最终目录调一次chmod因为chmod不受umask影响。4.3 chmod 与 fchmod 的差别以及什么情况下必须用后者chmod(path, mode)按路径改权限fchmod(fd, mode)按已打开的 fd 改。两者语义一样区别只在竞态安全性如果你已经打开了文件再按路径去chmod中间路径可能被替换你改的就是另一个文件的权限。稳妥的顺序永远是open→fchmod→close。int fd open(path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); if (fd -1) return -1; if (fchmod(fd, 0640) -1) { int e errno; close(fd); errno e; return -1; } close(fd);另外提一句chmod对符号链接的行为是改目标文件不是改链接本身——因为链接自身没有有意义的权限位在 Linux 上永远是0777且chmod跟随链接。想改链接的权限是做不到的这不是 API 限制而是文件系统层面就没这个概念。5. 时间戳、inode 和 st_size几个一定会咬人的字段字段表背下来只是起点真正让你加班的往往是这些字段的语义边界。5.1 三个时间戳ctime 不是创建时间st_atime是访问时间读文件内容会更新它现代内核用 relatime 策略只有在特定条件下才真正写盘所以别指望它精确到每次 readst_mtime是内容修改时间写入文件内容会更新st_ctime是状态变更时间改权限、改属主、改名、加硬链接都会更新它。最常被误解的是st_ctime很多人以为它是 create time。不是。Linux 的struct stat里根本没有创建时间字段要拿创建时间得用statx系统调用stx_btime而且还得看文件系统支不支持。这个误会在排查文件明明没改内容mtime 怎么变了这类问题时特别误导人——实际上变的常常是 ctime因为有人改了权限或者重命名了目录。打印时间戳要注意ctime()返回的字符串自带换行而且不是线程安全的。多线程环境用ctime_r或者strftime#include time.h #include stdio.h char buf[32]; struct tm tm_buf; localtime_r(st.st_mtime, tm_buf); strftime(buf, sizeof(buf), %Y-%m-%d %H:%M:%S, tm_buf); printf(mtime%s\n, buf);5.2 st_ino 加 st_dev 才是文件的唯一身份想判断两个路径是不是同一个文件比较路径字符串是肯定不行的软链接、硬链接、..都能绕过它。正确的是比较st_dev和st_ino的组合static int same_file(const struct stat *a, const struct stat *b) { return a-st_dev b-st_dev a-st_ino b-st_ino; }st_dev不能省因为 inode 号只在单个文件系统内唯一不同挂载点下完全可能出现相同 inode 号的两个文件。st_nlink则表示这个 inode 上有多少个硬链接普通文件通常是 1目录至少是 2自身的.加上父目录里的条目这也可以用来粗略判断某个路径是不是挂载点。5.3 st_size 在非普通文件上不可靠前面提过目录的st_size是实现相关的这里再补几个。对管道、字符设备、套接字文件调用statst_size通常是 0不代表没有数据。对块设备st_size可能也是 0要拿设备容量得用ioctl配合BLKGETSIZE64。对/proc下的文件st_size普遍是 0因为内容是动态生成的你读出来的字节数和st_size完全对不上。所以任何先stat拿大小、再按大小分配缓冲的代码都必须先确认S_ISREG为真。我见过一个日志读取工具遇到/proc/self/status时因为st_size是 0 直接判定文件为空跳过了排查了半天才发现是字段语义问题。5.4 32 位系统上的大文件与 EOVERFLOW在老一些的 32 位环境里off_t默认是 32 位超过 2GB 的文件调用stat会失败errno是EOVERFLOW。这个错误码不常见很容易被当成权限问题或者文件不存在忽略掉。解决办法是编译时加-D_FILE_OFFSET_BITS64让off_t在编译期变成 64 位gcc -D_FILE_OFFSET_BITS64 -O2 reader.c -o reader这个宏必须在包含任何系统头文件之前定义所以只能通过编译选项传写在源文件里往往太晚了。现在主流 64 位平台默认off_t就是 64 位不太会碰到这个问题但如果你维护的是嵌入式或者老系统上的代码这条是必查项。顺便说fopen时代对应的是fopen64、stat64、lseek64这一套现在用宏的方式更省心。6. 跨平台迁移与三条真实排查链路最后聊聊换平台时会发生什么以及几个我实际处理过的排查过程。6.1 Windows、C17 和脚本语言的对应物Windows 的 MSVC 其实也提供sys/stat.h但里面的东西是另一套函数叫_stat、_stat64、_fstat结构体叫struct _stat或struct _stat64字段名是st_mode、st_size、st_mtime这套没错但类型宽度和行为不同。文件类型宏也不一样用的是_S_IFREG、_S_IFDIR权限宏是_S_IREAD、_S_IWRITE没有执行位这个概念。st_ino在 Windows 上是 0 或没有意义st_nlink对普通文件基本恒为 1。写跨平台代码时通常的做法是抽一层薄封装平台相关的部分用条件编译隔开对外暴露统一的判定接口。C17 之后有个更省事的选择filesystem。std::filesystem::status(path)返回file_statusis_regular_file()、is_directory()、is_symlink()这些方法语义清晰std::filesystem::perms枚举把权限位也抽象好了。它底层在 POSIX 平台就是调stat/lstat但屏蔽了类型宽度和字段名差异。缺点是对错误处理的方式变了——它用error_code重载默认版本会抛异常在禁用异常的嵌入式环境里要用带error_code的那个版本。脚本语言里对应的是 Python 的os.stat()返回os.stat_result具名元组配合标准库stat模块的S_ISREG(mode)等函数使用思路和 C 完全一致。理解 C 的这套模型之后看其他语言的封装基本是降维。6.2 排查链路一errno 被 close 覆盖导致误判现象一个清理脚本偶尔把权限不足的文件当成不存在跳过日志里errno显示ENOENT但人工核对文件确实存在。排查过程是这样的。先看代码int fd open(path, O_RDONLY); if (fd -1) { if (errno ENOENT) { /* 当作不存在静默跳过 */ } else { perror(open); } return; } struct stat st; if (fstat(fd, st) -1) { close(fd); /* 问题在这一行 */ if (errno ENOENT) { /* 这里读到的是 close 留下的 errno */ } }问题很清楚了fstat失败后调closeclose执行成功不会重置errno但如果它内部有任何系统调用设置了errno就会把原值覆盖掉。虽然规范允许函数成功时保持errno不变但依赖这一点是非常脆弱的。修法就是前面示例里那个模式先存int saved errno;再close最后errno saved;。这条经验可以推广成一条硬规则在多步错误处理中每一个可能调用系统函数的清理动作之前都要先保存errno。6.3 排查链路二自己定义 struct stat 导致的幽灵 bug现象一个历史项目在新机器上编译通过但读出来的文件大小全是几十亿的离谱数字权限判断也完全错乱。顺着代码看在某个老旧的兼容头文件里发现了一段手写的结构体定义注释写着为了兼容某些平台。这段定义大概是十几年前照着一份文档抄的字段顺序和现在的 ABI 已经对不上还漏了st_blksize、st_blocks和时间戳字段。stat()把 144 字节或更多的数据写进只有 88 字节的结构体里直接踩爆了栈同时后续读取全按错误偏移解析。修复方式是删掉自定义定义改成#include sys/stat.h。这里给一个可复用的排查手法拿sizeof(struct stat)打印一下和系统文档对照再用offsetof(struct stat, st_size)看字段偏移如果和官方布局对不上基本就能锁定问题。这类 bug 的特点是只在某些平台上错因为老平台 ABI 可能碰巧兼容迁移之后就全乱了。6.4 排查链路三umask 在守护进程里意外变成 0现象一个后台服务启动后创建的文件全是0666其他用户可读可写安全审计直接报了问题。开发环境复现不出来。排查从mkdir、open的 mode 参数查起参数写的都是0640看起来没问题。继续追发现服务启动脚本里有一段初始化逻辑为了临时拿到真实 umask调了umask(0)然后因为某个异常分支提前 return恢复那行没执行到。进程的umask就永久变成了 0之后所有文件创建都按mode ~0来等于完全不做削减。这类问题的修法是读取umask的操作要么放在进程启动最早期、所有分支都保证恢复要么干脆用pthread_atfork或者启动时缓存的方式避免中途修改。更稳的思路是根本不去读它——如果你需要精确权限就在创建后显式chmod这样umask是什么值都无所谓。我个人在写这类文件操作代码时会坚持三条凡是涉及路径和打开的地方一律open后fstat不信任两次调用之间的世界凡是涉及权限创建时给宽一点的mode再用fchmod收紧避免被umask意外削减凡是涉及错误处理errno一律先存后恢复。这三条看着啰嗦但真能省掉大量本地复现不出来、线上偶尔出现的排查时间。如果你现在手上正好有一段用stat判断存在性的代码可以翻出来看看它后面跟着的open那中间的一行空隙就是最值得重写的地方。
写过一阵子 Linux 下文件操作的人对#include sys/stat.h这行大概都不会陌生但真正能把它说明白的人并不多。有意思的是不少人在搜索引擎里输的是sys.stat.h——一个把斜杠打成点的写法这个小笔误本身就很说明问题大家知道有这么个头文件知道它跟文件有关却不太清楚它到底管什么、不管什么。stat在这里不是统计学的统计而是 status 的缩写。这个头文件是 POSIX 给文件系统元数据开的一扇正门文件多大、是普通文件还是目录、权限位怎么设、最后一次内容修改发生在什么时候、硬链接数是多少所有这些信息都通过它声明的struct stat和stat、fstat、lstat、mkdir、chmod、umask这一组接口拿到。不管你是刚接触系统编程的新手还是写了好几年业务代码、每次碰到权限问题都靠猜的老手把这一套东西理顺都能省下大量调试时间。下面我按它声明了什么、结构体怎么读、三个调用怎么选、建目录改权限怎么落地、哪些字段会咬人、跨平台怎么迁的顺序把我踩过的和见过的坑一次讲透。1. stat 不是统计这个头文件的职责边界在哪先把最容易混淆的一点摆正。stat这个词在这套接口里全程指代状态statussys/stat.h直译过来就是系统状态头文件只不过它管的状态特指文件系统对象的状态。你在 shell 里敲stat somefile、ls -l背后展示的那一堆信息包括 inode 号、权限串-rw-r--r--、大小、链接数、三个时间戳本质上都是这个头文件声明的接口吐出来的。理解这一点后面所有 API 的命名逻辑就顺了fstat是对文件描述符取状态lstat是取链接本身的状态chmod是改 modemkdir是造一个目录全都在文件状态这条主线上。很多人第一次被它绊住是因为搜到的资料要么只贴一个struct stat的字段表要么直接甩一段stat()调用示例中间那层为什么需要它、什么时候不需要它的说明是缺失的。我见过有同学为了判断一个路径存不存在专门去#include sys/stat.h然后写stat调用其实用access()或者直接open()看errno更贴合场景也见过有人拿stat的返回值当文件大小用结果对目录调用时拿到一个诡异的数字排查了半天。这一节先把边界划清楚后面几节再往里钻。1.1 头文件里实际躺着三类东西打开 glibc 的sys/stat.h不同 libc 的具体路径不同通常是/usr/include/x86_64-linux-gnu/sys/stat.h加一个bits/stat.h你会发现内容高度结构化就三类函数声明、结构体定义、宏常量。搞清楚这三类各自的用途比死记字段名有用得多。类别代表内容用在哪函数statfstatlstatchmodfchmodmkdirmkfifoumaskfutimens取状态、改权限、建目录/管道、改时间戳结构体struct stat承载一次取状态调用的全部结果类型mode_tdev_tino_tnlink_toff_tblkcnt_tblksize_t结构体字段和函数参数的类型宏S_IFMTS_IFREGS_IFDIR等文件类型S_IRUSRS_IWGRP等权限位S_ISREG()S_ISDIR()等判定宏位运算判断需要提醒的是mode_t、off_t这些类型严格来说是sys/types.h定义的sys/stat.h会把它包含进来所以你在代码里只写#include sys/stat.h也能用mode_t。但如果你要在别的地方单独声明一个mode_t变量而又不涉及 stat 系列函数规范做法是显式包含sys/types.h。这个细节在移植到某些精简 libc 时会突然变成编译错误属于平时不出事、换环境就炸的典型。还有几个不那么常用的成员值得知道mkfifo用来创建命名管道做进程间通信时会用到futimens和utimensat可以在不改变文件内容的前提下精确设置访问时间和修改时间做构建系统或者增量同步工具时特别有用它们支持两个特殊值UTIME_NOW和UTIME_OMIT后者表示这个时间戳别动省去了先读再写的麻烦。1.2 为什么有很多代码不写这行也能编过这是新手最容易产生的错觉明明自己没写#include sys/stat.h代码里却能用struct stat编译还没报错。原因通常是别的头文件把它间接带进来了。比如某些项目的公共头文件里包含了sys/types.h和sys/stat.h或者某个第三方库的头文件顺手包含了它于是你的源文件白嫖到了声明。这种依赖是非常脆弱的。glibc 能过不代表 musl 能过Linux 能过不代表 macOS 能过。我遇到过不止一次本地开发机编译一切正常CI 跑在 Alpine 上直接报storage size of st isnt known——因为struct stat是不完整类型编译器根本不知道要分配多大空间。修起来很简单加一行 include 就行但排查过程如果没有隐式包含这个意识很容易怀疑到别的地方去。提示判断某个类型是不是靠隐式包含拿到的最直接的办法是把可疑的 include 全部注释掉只留标准库的最小集合重新编译一次报错位置会立刻告诉你真相。养成习惯只要你的代码里出现了struct stat、mode_t、S_ISDIR这些符号就在该源文件顶部显式写上#include sys/stat.h哪怕它已经被别的头文件包含过。多余的一行 include 有头文件保护不会带来任何运行时开销但能省下未来某次跨平台构建的一小时。1.3 和 fcntl.h、unistd.h 的分工要理清文件操作相关的头文件容易混这里给一个我自己的记忆方式打开与属性在 fcntl.h 和 sys/stat.h读写与关闭在 unistd.h。open()的O_RDONLY、O_CREAT、O_NOFOLLOW这些标志位在fcntl.h里read()、write()、close()、unlink()、rmdir()、access()在unistd.h里而stat系列、chmod系列、mkdir、umask在sys/stat.h里。这个分工不是随意划的它反映的是元数据操作和数据流操作的分离。stat不碰文件内容只读 inode 里的信息chmod也不碰内容只改 inode 里的权限位。而read/write走的是文件描述符的数据通道。理解了这层你就明白为什么fstat需要一个已经打开的 fd而stat只需要一个路径——前者是在数据通道建立之后再问元数据后者是直接按路径去查。2. struct stat 的字段不是摆设st_mode 才是主战场struct stat的字段数量在不同平台上略有差异Linux 上大概十来个字段顺序由 ABI 固定绝对不要自己照着网上的文章复制一份结构体定义——这是我在代码评审里见过的最危险的操作之一。你自己定义的struct stat和系统头文件里的布局一旦对不上stat()调用不会报错它会老老实实往你给的那块内存里按系统布局写数据然后你按自己的布局去读读出来的就是一堆垃圾值。这种 bug 极难排查因为没有任何错误码提示。正确做法永远是#include sys/stat.h然后用系统给的定义。如果你确实需要跨编译单元传递这些信息也应该传自己定义的一个精简结构体在边界处做一次显式拷贝转换。2.1 按用途把字段分成四组字段多硬背没意义按用途分组记就轻松了。下面这张表我按标识、类型、尺寸、时间四组整理分组字段说明标识st_devst_ino设备号 inode 号二者组合唯一标识一个文件类型与权限st_modest_uidst_gidst_nlinkst_rdev文件类型 权限位、属主、属组、硬链接数、设备文件的主次设备号尺寸st_sizest_blksizest_blocks字节大小、推荐的 I/O 块大小、占用的 512 字节块数时间st_atimst_mtimst_ctim访问、修改、状态变更时间都是struct timespec两个容易混的点提前说清楚。第一st_blksize是推荐 I/O 块大小通常是 4096它是给read/write缓冲区大小做参考的不是文件占用的块大小真正表示磁盘占用的是st_blocks单位固定为 512 字节跟st_blksize没关系。第二st_size对普通文件是字节数对符号链接是链接目标字符串的长度对目录是实现相关的——也就是说你在 Linux 上看到目录的st_size是 4096 或者更大别拿它当目录里文件总大小用那完全是两回事。时间字段的命名在不同平台上还有差异。Linux/glibc 用st_atim、st_mtim、st_ctim带tv_sec和tv_nsec同时保留了st_atime、st_mtime、st_ctime这几个宏作为兼容别名只取秒部分。macOS 上则叫st_atimespec、st_mtimespec、st_ctimespec。写跨平台代码时取秒级时间用st_mtime最稳需要纳秒精度就得加平台判断。2.2 st_mode 的位布局高四位定类型低十二位定权限st_mode是mode_t类型通常是 32 位无符号整型它把文件类型和权限位塞进了同一个整数里。这个设计非常紧凑但也意味着你必须用位掩码来读不能直接比较。高位的文件类型占了 4 个比特掩码是S_IFMT八进制0170000。具体取值宏八进制值含义S_IFREG0100000普通文件S_IFDIR0040000目录S_IFLNK0120000符号链接S_IFCHR0020000字符设备S_IFBLK0060000块设备S_IFIFO0010000命名管道S_IFSOCK0140000套接字文件低十二位是权限八进制07777。其中最高的三位是特殊位S_ISUID04000、S_ISGID02000、S_ISVTX01000剩下九位是属主/属组/其他的 rwx。S_IRWXU是0700S_IRUSR是0400S_IWUSR是0200S_IXUSR是0100G和O两组同理右移。为什么必须用S_IFMT掩码因为st_mode里同时有类型位和权限位你写if (st.st_mode S_IFDIR)永远为假除非这个目录权限恰好是 0。正确的写法是(st.st_mode S_IFMT) S_IFDIR或者直接用宏S_ISDIR(st.st_mode)。2.3 别再手写 (mode 0170000) 0100000 了S_ISREG、S_ISDIR、S_ISLNK、S_ISCHR、S_ISBLK、S_ISFIFO、S_ISSOCK这一组宏就是上面位运算的封装。它们的实现在 glibc 里大致是这样#define S_ISREG(m) (((m) S_IFMT) S_IFREG) #define S_ISDIR(m) (((m) S_IFMT) S_IFDIR) #define S_ISLNK(m) (((m) S_IFMT) S_IFLNK)我见过不少老代码直接写st.st_mode S_IFDIR来判断目录这在多数情况下碰巧能用因为目录的类型位0040000里有非零位与运算结果非零就为真。但它是错的任何类型为S_IFREG的文件st_mode里0040000这一位也可能是 10100000和0040000的位并不互斥于是普通文件会被误判成目录。这类 bug 在测试环境里可能因为样本文件权限简单而侥幸躲过一到生产就爆。一个完整的类型判断写法#include sys/stat.h #include stdio.h static const char *type_name(mode_t m) { if (S_ISREG(m)) return regular; if (S_ISDIR(m)) return directory; if (S_ISLNK(m)) return symlink; if (S_ISCHR(m)) return char-device; if (S_ISBLK(m)) return block-device; if (S_ISFIFO(m)) return fifo; if (S_ISSOCK(m)) return socket; return unknown; }注意S_ISLNK只在lstat的结果里才可能为真。stat()会跟随符号链接返回的是目标文件的状态所以对软链接调用stat得到的类型是目标文件的类型。这个差异是下一节的重点。3. stat、fstat、lstat 的选择逻辑与 TOCTOU 竞态三个函数签名几乎一样参数都是路径或 fd struct stat *理解它们的差异是写好文件操作代码的分水岭。用错不会编译报错但行为会差出十万八千里。3.1 三者的差异点浓缩成一句话stat跟随符号链接lstat不跟随fstat用已打开的文件描述符。这句总结好记但真正重要的是知道什么时候该用哪个。函数首个参数是否跟随软链接典型场景statconst char *path是想知道我打开这个路径最终会拿到什么lstatconst char *path否遍历目录、备份工具、判断是否为链接fstatint fd不涉及路径已打开文件后取状态天然免疫竞态遍历目录树时99% 的情况应该用lstat。因为你要的是这个目录项本身是什么遇到符号链接就记录下来、不去跟随否则一个指向父目录的软链接会让你的递归无限循环直接把栈打爆。这个坑我在写第一个文件清理脚本时踩过脚本跑了三秒就把内存吃满了。反过来你要判断这个路径能不能读、多大、是不是普通文件用stat更符合直觉——因为你接下来要open的就是目标文件问链接本身的状态没有意义。3.2 软链接场景下的实测差异拿一个软链接做对照差别一目了然。假设link.txt - real.txtreal.txt内容是 5 个字节#include sys/stat.h #include stdio.h #include time.h void dump(const char *tag, const struct stat *st) { printf(%-6s type%s size%lld ino%llu\n, tag, S_ISLNK(st-st_mode) ? LNK : S_ISREG(st-st_mode) ? REG : OTHER, (long long)st-st_size, (unsigned long long)st-st_ino); } int main(void) { struct stat a, b; if (stat(link.txt, a) 0) dump(stat, a); if (lstat(link.txt, b) 0) dump(lstat, b); return 0; }实测输出大致是stat那行显示REG、size5lstat那行显示LNK、size8也就是real.txt这个目标字符串的长度。同一个路径两个调用给出完全不同的答案st_ino也可能不同软链接有自己的 inode。这就是为什么备份工具、rsync这类软件必须用lstat——它们要原样保留链接结构而不是把链接解开变成实体文件。3.3 先 stat 再 open 的经典竞态这是安全领域的老问题但日常业务代码里天天有人这么写/* 反例TOCTOU检查时与使用时不一致 */ struct stat st; if (stat(path, st) 0 S_ISREG(st.st_mode)) { int fd open(path, O_RDONLY); /* 这一行之间path 可能被换掉 */ /* ... */ }问题在于stat和open之间存在一个时间窗口。如果这个路径在共享目录、临时目录或者被其他进程可控攻击者可以在这两步之间把普通文件替换成指向敏感位置的符号链接你的open就会打开意料之外的文件。这类漏洞有个统一的名字叫 TOCTOU。还有一种变体更隐蔽先用stat检查文件大小再按这个大小分配缓冲区去读。中间文件被追加内容读的时候缓冲区就不够了。或者反过来文件被截断你读到一堆空洞。3.4 正确的姿势是 open 完再 fstat把检查挪到打开之后用fstat对已经拿到的 fd 做判断路径就不再参与后续决策竞态窗口彻底消失#include fcntl.h #include sys/stat.h #include unistd.h #include errno.h int open_regular(const char *path, int *out_fd, struct stat *out_st) { int fd open(path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); if (fd -1) return -1; /* ELOOP 表示最后一段是软链接 */ struct stat st; if (fstat(fd, st) -1) { int saved errno; close(fd); errno saved; return -1; } if (!S_ISREG(st.st_mode)) { close(fd); errno EINVAL; return -1; } *out_fd fd; *out_st st; return 0; }这里有三个细节值得展开。O_NOFOLLOW保证如果路径最后一段是符号链接就直接失败errno为ELOOP这是比lstat更彻底的防护因为它把检查和打开合并成一个原子操作。O_CLOEXEC让 fd 在exec家族调用后自动关闭避免子进程意外继承——这个标志在写守护进程或者调用外部命令时几乎是必须的不加的话很容易出现文件句柄泄漏到子进程、父进程关了子进程还占着的怪现象。最后错误处理里要先把errno存下来再close因为close本身失败时会覆盖errno这个坑我调过不止一次。注意open成功后立刻fstat然后基于st做所有后续判断中间不要再碰路径字符串。这条规则能消灭你代码里 90% 的文件相关竞态。4. 建目录与改权限mkdir、chmod、umask 的联动实操sys/stat.h里被用得最多的函数其实是mkdir其次才是stat。而mkdir又是最容易让人产生我的参数怎么不生效疑问的一个。4.1 mkdir 的 mode 参数为什么经常不生效mkdir(/tmp/mydir, 0777); /* 你以为会得到 drwxrwxrwx */跑完ls -ld /tmp/mydir看到的多半是drwxr-xr-x也就是0755。这不是 bug是umask在起作用。mkdir的第二个参数叫期望权限实际创建出来的权限等于mode ~umask。umask是进程级属性含义是从新建文件的默认权限里屏蔽掉哪些位。绝大多数 shell 的默认umask是022也就是屏蔽掉组和其他用户的写权限。所以0777 ~022 07550775 ~022 07550700 ~022 0700。计算过程拆开看更清楚。~022在 32 位下是...1111111111011101跟0777按位与把0022对应位置的两个 1 清零得到0755。如果umask是077那0777 ~077 0700只有属主有权限。做安全敏感的服务时很多团队会把服务进程的umask显式设成077确保新建文件天然对其他用户不可见。想读到当前umask而不改变它标准做法是先设后恢复#include sys/stat.h mode_t current_umask(void) { mode_t old umask(0); umask(old); return old; }这个写法有个小瑕疵中间那一瞬间umask是 0如果是多线程程序恰好有别的线程在这个窗口里创建文件就会得到过于宽松的权限。对权限敏感的场景正确做法是在程序启动、还没起线程的时候就记录一次umask后面直接用缓存值。4.2 递归建目录mkdir -p 的手写实现标准 C 库没有mkdir -p的等价函数需要自己逐级创建。这个函数看起来简单但错误处理有不少讲究#include sys/stat.h #include string.h #include errno.h #include limits.h int mkdir_p(const char *path, mode_t mode) { char tmp[PATH_MAX]; size_t len strlen(path); if (len 0 || len sizeof(tmp)) { errno ENAMETOOLONG; return -1; } memcpy(tmp, path, len 1); for (char *p tmp 1; *p ! \0; p) { if (*p ! /) continue; *p \0; if (mkdir(tmp, mode) -1 errno ! EEXIST) return -1; *p /; } if (mkdir(tmp, mode) -1) { if (errno ! EEXIST) return -1; struct stat st; if (stat(tmp, st) -1) return -1; if (!S_ISDIR(st.st_mode)) { errno ENOTDIR; return -1; } } return 0; }几个关键点。第一从tmp 1开始扫描跳过第一个字符这样处理绝对路径/a/b/c时不会尝试创建空字符串路径。第二EEXIST不能无条件当成成功——如果这个位置上已经存在一个同名普通文件mkdir同样返回-1且errno是EEXIST但它不是目录后续往里写文件会失败。所以最终一步必须补一次stat确认是目录不是就返回ENOTDIR。第三中间层级遇到EEXIST不做检查是常见取舍因为逐级stat会显著增加系统调用次数如果你对健壮性要求高可以把每个层级都检查一遍代价是路径深度翻倍的 syscall。第四PATH_MAX在有些系统上是不确定的比如 GNU Hurd严格可移植的写法要用动态分配日常 Linux 环境用PATH_MAX够用。还有一个细节容易被忽略中间层级的mkdir用的也是同样的mode但最终权限会被umask削减。如果你需要指定精确权限比如0750应该在全部创建完成后对最终目录调一次chmod因为chmod不受umask影响。4.3 chmod 与 fchmod 的差别以及什么情况下必须用后者chmod(path, mode)按路径改权限fchmod(fd, mode)按已打开的 fd 改。两者语义一样区别只在竞态安全性如果你已经打开了文件再按路径去chmod中间路径可能被替换你改的就是另一个文件的权限。稳妥的顺序永远是open→fchmod→close。int fd open(path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); if (fd -1) return -1; if (fchmod(fd, 0640) -1) { int e errno; close(fd); errno e; return -1; } close(fd);另外提一句chmod对符号链接的行为是改目标文件不是改链接本身——因为链接自身没有有意义的权限位在 Linux 上永远是0777且chmod跟随链接。想改链接的权限是做不到的这不是 API 限制而是文件系统层面就没这个概念。5. 时间戳、inode 和 st_size几个一定会咬人的字段字段表背下来只是起点真正让你加班的往往是这些字段的语义边界。5.1 三个时间戳ctime 不是创建时间st_atime是访问时间读文件内容会更新它现代内核用 relatime 策略只有在特定条件下才真正写盘所以别指望它精确到每次 readst_mtime是内容修改时间写入文件内容会更新st_ctime是状态变更时间改权限、改属主、改名、加硬链接都会更新它。最常被误解的是st_ctime很多人以为它是 create time。不是。Linux 的struct stat里根本没有创建时间字段要拿创建时间得用statx系统调用stx_btime而且还得看文件系统支不支持。这个误会在排查文件明明没改内容mtime 怎么变了这类问题时特别误导人——实际上变的常常是 ctime因为有人改了权限或者重命名了目录。打印时间戳要注意ctime()返回的字符串自带换行而且不是线程安全的。多线程环境用ctime_r或者strftime#include time.h #include stdio.h char buf[32]; struct tm tm_buf; localtime_r(st.st_mtime, tm_buf); strftime(buf, sizeof(buf), %Y-%m-%d %H:%M:%S, tm_buf); printf(mtime%s\n, buf);5.2 st_ino 加 st_dev 才是文件的唯一身份想判断两个路径是不是同一个文件比较路径字符串是肯定不行的软链接、硬链接、..都能绕过它。正确的是比较st_dev和st_ino的组合static int same_file(const struct stat *a, const struct stat *b) { return a-st_dev b-st_dev a-st_ino b-st_ino; }st_dev不能省因为 inode 号只在单个文件系统内唯一不同挂载点下完全可能出现相同 inode 号的两个文件。st_nlink则表示这个 inode 上有多少个硬链接普通文件通常是 1目录至少是 2自身的.加上父目录里的条目这也可以用来粗略判断某个路径是不是挂载点。5.3 st_size 在非普通文件上不可靠前面提过目录的st_size是实现相关的这里再补几个。对管道、字符设备、套接字文件调用statst_size通常是 0不代表没有数据。对块设备st_size可能也是 0要拿设备容量得用ioctl配合BLKGETSIZE64。对/proc下的文件st_size普遍是 0因为内容是动态生成的你读出来的字节数和st_size完全对不上。所以任何先stat拿大小、再按大小分配缓冲的代码都必须先确认S_ISREG为真。我见过一个日志读取工具遇到/proc/self/status时因为st_size是 0 直接判定文件为空跳过了排查了半天才发现是字段语义问题。5.4 32 位系统上的大文件与 EOVERFLOW在老一些的 32 位环境里off_t默认是 32 位超过 2GB 的文件调用stat会失败errno是EOVERFLOW。这个错误码不常见很容易被当成权限问题或者文件不存在忽略掉。解决办法是编译时加-D_FILE_OFFSET_BITS64让off_t在编译期变成 64 位gcc -D_FILE_OFFSET_BITS64 -O2 reader.c -o reader这个宏必须在包含任何系统头文件之前定义所以只能通过编译选项传写在源文件里往往太晚了。现在主流 64 位平台默认off_t就是 64 位不太会碰到这个问题但如果你维护的是嵌入式或者老系统上的代码这条是必查项。顺便说fopen时代对应的是fopen64、stat64、lseek64这一套现在用宏的方式更省心。6. 跨平台迁移与三条真实排查链路最后聊聊换平台时会发生什么以及几个我实际处理过的排查过程。6.1 Windows、C17 和脚本语言的对应物Windows 的 MSVC 其实也提供sys/stat.h但里面的东西是另一套函数叫_stat、_stat64、_fstat结构体叫struct _stat或struct _stat64字段名是st_mode、st_size、st_mtime这套没错但类型宽度和行为不同。文件类型宏也不一样用的是_S_IFREG、_S_IFDIR权限宏是_S_IREAD、_S_IWRITE没有执行位这个概念。st_ino在 Windows 上是 0 或没有意义st_nlink对普通文件基本恒为 1。写跨平台代码时通常的做法是抽一层薄封装平台相关的部分用条件编译隔开对外暴露统一的判定接口。C17 之后有个更省事的选择filesystem。std::filesystem::status(path)返回file_statusis_regular_file()、is_directory()、is_symlink()这些方法语义清晰std::filesystem::perms枚举把权限位也抽象好了。它底层在 POSIX 平台就是调stat/lstat但屏蔽了类型宽度和字段名差异。缺点是对错误处理的方式变了——它用error_code重载默认版本会抛异常在禁用异常的嵌入式环境里要用带error_code的那个版本。脚本语言里对应的是 Python 的os.stat()返回os.stat_result具名元组配合标准库stat模块的S_ISREG(mode)等函数使用思路和 C 完全一致。理解 C 的这套模型之后看其他语言的封装基本是降维。6.2 排查链路一errno 被 close 覆盖导致误判现象一个清理脚本偶尔把权限不足的文件当成不存在跳过日志里errno显示ENOENT但人工核对文件确实存在。排查过程是这样的。先看代码int fd open(path, O_RDONLY); if (fd -1) { if (errno ENOENT) { /* 当作不存在静默跳过 */ } else { perror(open); } return; } struct stat st; if (fstat(fd, st) -1) { close(fd); /* 问题在这一行 */ if (errno ENOENT) { /* 这里读到的是 close 留下的 errno */ } }问题很清楚了fstat失败后调closeclose执行成功不会重置errno但如果它内部有任何系统调用设置了errno就会把原值覆盖掉。虽然规范允许函数成功时保持errno不变但依赖这一点是非常脆弱的。修法就是前面示例里那个模式先存int saved errno;再close最后errno saved;。这条经验可以推广成一条硬规则在多步错误处理中每一个可能调用系统函数的清理动作之前都要先保存errno。6.3 排查链路二自己定义 struct stat 导致的幽灵 bug现象一个历史项目在新机器上编译通过但读出来的文件大小全是几十亿的离谱数字权限判断也完全错乱。顺着代码看在某个老旧的兼容头文件里发现了一段手写的结构体定义注释写着为了兼容某些平台。这段定义大概是十几年前照着一份文档抄的字段顺序和现在的 ABI 已经对不上还漏了st_blksize、st_blocks和时间戳字段。stat()把 144 字节或更多的数据写进只有 88 字节的结构体里直接踩爆了栈同时后续读取全按错误偏移解析。修复方式是删掉自定义定义改成#include sys/stat.h。这里给一个可复用的排查手法拿sizeof(struct stat)打印一下和系统文档对照再用offsetof(struct stat, st_size)看字段偏移如果和官方布局对不上基本就能锁定问题。这类 bug 的特点是只在某些平台上错因为老平台 ABI 可能碰巧兼容迁移之后就全乱了。6.4 排查链路三umask 在守护进程里意外变成 0现象一个后台服务启动后创建的文件全是0666其他用户可读可写安全审计直接报了问题。开发环境复现不出来。排查从mkdir、open的 mode 参数查起参数写的都是0640看起来没问题。继续追发现服务启动脚本里有一段初始化逻辑为了临时拿到真实 umask调了umask(0)然后因为某个异常分支提前 return恢复那行没执行到。进程的umask就永久变成了 0之后所有文件创建都按mode ~0来等于完全不做削减。这类问题的修法是读取umask的操作要么放在进程启动最早期、所有分支都保证恢复要么干脆用pthread_atfork或者启动时缓存的方式避免中途修改。更稳的思路是根本不去读它——如果你需要精确权限就在创建后显式chmod这样umask是什么值都无所谓。我个人在写这类文件操作代码时会坚持三条凡是涉及路径和打开的地方一律open后fstat不信任两次调用之间的世界凡是涉及权限创建时给宽一点的mode再用fchmod收紧避免被umask意外削减凡是涉及错误处理errno一律先存后恢复。这三条看着啰嗦但真能省掉大量本地复现不出来、线上偶尔出现的排查时间。如果你现在手上正好有一段用stat判断存在性的代码可以翻出来看看它后面跟着的open那中间的一行空隙就是最值得重写的地方。
