刚接触Linux系统编程的人，通常都会经历这么一道坎：文件I/O已经用得很熟了，open、read、write、lseek各种调，但一碰到目录就有点懵。好像目录也能打开，但打开之后读出来的东西和普通文件完全不一样；想遍历一个目录树，网上搜到的代码五花八门，有的用递归，有的用nftw，有的直接调system("ls")，看得人眼花缭乱。其实Linux下目录操作的底层接口非常稳定，核心就是围绕“目录流”（directory stream）这一抽象概念展开的：opendir拿到一个DIR*，readdir循环取出目录项，closedir收尾。就这么简单？是，但也不完全是——真正写起来，踩坑的地方多着呢。
这篇文章我想从目录的本质讲起，把目录流相关API的来龙去脉、常见用法、以及我一路上趟过的坑都整理一遍。无论是你正在写文件同步工具、日志轮转脚本，还是想实现一个简化版find命令，都能从中找到可以直接拿去用的思路和代码。通篇我会用C语言示例，因为Linux系统编程的底层逻辑用C表达最直白，你看懂之后换成其他语言也只是一个封装深浅的问题。
1. 目录到底是个什么东西
1.1 目录是一种“特殊文件”
很多人误以为目录是“文件夹”，是用来装东西的容器。但在Linux文件系统的实现里，目录本质上是一种特殊文件，它不直接存储文件内容，而是保存了一张“文件名 -> inode编号”的映射表。通过这张表，内核才能把用户看到的路径名（比如 /var/log/syslog）一步步解析成真正的磁盘数据块。
你可以做一个简单实验：用vim直接打开一个目录，比如vim /tmp，会看到一堆乱码。这就是因为vim用read系统调用去读目录文件，而目录文件的原始二进制内容对普通应用来说毫无意义。它的内部结构是文件系统自己定义的，可能是hash表、B+树、或者线性数组，取决于具体文件系统格式。所以在系统编程层面，我们永远不应该去假设目录内部长什么样，而是要通过内核提供的目录流API去访问。
这里顺便解释一个重要概念：正因为目录是一种特殊文件，它的权限位里“读”和“执行”含义是有讲究的。对目录而言，r权限决定你能不能列出目录里的条目，x权限决定你能不能“穿过”这个目录去访问里面的文件。很多新手在写服务程序时，发现open一个文件明明有权限，但提示Permission denied，查了半天才发现是路径上某个中间目录少了x权限。这个问题在目录遍历场景下尤其常见，后面我会细说。
1.2 为什么不能像普通文件那样用read读目录
理论上你可以用open打开一个目录，得到文件描述符，但你不能用read去读它。如果强行read，内核会返回EISDIR错误。这是因为read期望的是连续的数据流，而目录内部结构对外界是黑盒，内核不希望应用直接把目录原始字节抓走。于是就有了专门的一套系统调用和库函数：opendir、readdir、closedir，它们共同构成了所谓的“目录流”接口。
目录流和普通文件流的共同点是：都有一个“当前位置”的概念，每次读取后位置自动后移，直到读完返回NULL。但目录流不能随便seek，虽然POSIX允许你使用telldir/seekdir，但仅在少量场景下靠谱，跨平台行为也不完全一致。我的个人建议是：不要把目录流当成一个可以前后跳转的数组，它就是一次性的迭代器，规规矩矩从头扫到尾，最稳。
2. 目录流API，使用入门
2.1 opendir / readdir / closedir 三件套
核心代码简单到让人怀疑人生：
#include <stdio.h> #include <dirent.h> int main(void) { DIR *dir = opendir("/tmp"); if (dir == NULL) { perror("opendir"); return 1; } struct dirent *entry; while ((entry = readdir(dir)) != NULL) { puts(entry->d_name); } closedir(dir); return 0; }这段代码做完了一件事：列出 /tmp 下的所有条目，包括隐藏文件。注意，readdir返回的每一个“目录项”，不止包含文件名，还包含其它元信息，比如类型、inode号、记录长度等。你平时在用户态看到的最常用字段是d_name和d_type，但真正落到内核里，目录项的数据远不止这两个字段。
还有几个细节值得记录：
- opendir失败返回NULL，常见错误码有ENOENT（目录不存在）、EACCES（无权限）。
- readdir返回NULL有两种可能：一是读完了，二是出错。要区分它们，需要检查errno是否为0。严格写法是：置errno为0，调用readdir，如果返回NULL且errno非0，才算读取失败。
- closedir失败会返回-1，但绝大多数场景下没人检查它，因为目录流关闭失败的概率极低，通常发生在NFS等文件系统上。如果程序要长时间运行，还是建议检查一下。
2.2 d_type 和 d_name：目录项里到底有什么
struct dirent的具体定义在不同glibc版本里略有差异，但至少包含以下关键字段：
| 字段 | 说明 |
|---|---|
| d_ino | inode编号 |
| d_name | 文件名，以\0结尾的字符数组 |
| d_type | 文件类型，见下面枚举值 |
| d_reclen | 这条目录记录的长度 |
d_type是很多人在做目录遍历时的“救命稻草”，因为如果文件系统支持它，你就不需要再调用stat/lstat去获取文件类型了。它的取值包括：
- DT_UNKNOWN：未知，需要再用stat获取
- DT_REG：普通文件
- DT_DIR：目录
- DT_LNK：符号链接
- DT_FIFO：命名管道
- DT_SOCK：Unix套接字
- DT_CHR：字符设备
- DT_BLK：块设备
但这里有个大坑：d_type是否真实有效完全取决于底层文件系统的支持情况。大多数本地文件系统（ext4、xfs、btrfs）会返回有效值，但某些网络文件系统，尤其是老旧的NFS实现，或者某些FUSE文件系统，会统一返回DT_UNKNOWN。见到DT_UNKNOWN，你只能乖乖调lstat去查类型。很多小白在递归遍历目录时，发现目录项没被识别为DT_DIR，于是漏递归了子目录，就是这个原因。
2.3 fdopendir 和 dirfd 的配套玩法
DIR* 这个句柄实际上内部持有一个文件描述符。你可以用dirfd(DIR*)把这个fd取出来，实现目录流和文件I/O的桥接。反过来，你也可以先把目录open成一个fd，再通过fdopendir把它包装成DIR*：
int fd = open(path, O_RDONLY | O_DIRECTORY); if (fd < 0) { perror("open"); return -1; } DIR *dir = fdopendir(fd); if (dir == NULL) { perror("fdopendir"); close(fd); return -1; }为什么要这么折腾？因为有些场景下你并不想只读目录列表，你还想对目录本身做另一些操作，比如fstat查看目录的修改时间，比如用openat来定位目录下的具体文件。此外，通过open拿到fd后，还能在调用fdopendir之前设置一些标志，比如O_NOFOLLOW，防止open一个符号链接。
这里有一个我在生产环境中踩过的坑：如果你成功调用了fdopendir，那么从这一刻起，目录流DIR*就“接管”了这个fd。关闭时必须用closedir，而不是close(fd)。如果你调用了close(fd)，然后又调用closedir，后者会尝试关闭一个已经无效的fd，轻则返回错误，重则在多线程程序里引发不可预知的后果，因为fd可能已经被另一个线程复用。所以记住一句话：fdopendir之后，闭源就交给closedir，绝对不要亲手去close那个fd。
2.4 scandir：一条龙读取+过滤+排序
如果你需要在目录里筛选特定类型的文件，并按某种规则排序，直接用readdir手写会有不少琐碎代码。Better approach是使用scandir，它把“读取所有目录项”“按过滤器筛选”“按比较器排序”三个动作合在了一起：
#include <stdio.h> #include <dirent.h> #include <string.h> #include <stdlib.h> static int is_c_file(const struct dirent *entry) { size_t len = strlen(entry->d_name); return len >= 2 && strcmp(entry->d_name + len - 2, ".c") == 0; } static int alpha_sort(const struct dirent **a, const struct dirent **b) { return strcoll((*a)->d_name, (*b)->d_name); } int main(void) { struct dirent **list = NULL; int n = scandir(".", &list, is_c_file, alpha_sort); if (n < 0) { perror("scandir"); return 1; } for (int i = 0; i < n; i++) { puts(list[i]->d_name); free(list[i]); } free(list); return 0; }scandir返回匹配项的数量，entries数组里每个元素都是动态分配的struct dirent*，用完记得逐一free。这个接口非常适合：找出目录下所有.log文件、按时间排序、或者只取目录项。不过要注意，scandir一次性把所有目录项都装进内存，如果你的目录有几十万个文件，内存占用就会很大，此时反而老老实实用readdir流式处理更合适。而且scandir在排序时无法利用目录在磁盘上的物理顺序，性能上也会稍微吃亏。我的经验是：小目录无脑scandir，大目录（超过几万条目）慎用。
3. 实操：手写一个目录遍历工具
3.1 递归遍历目录树的完整实现
目录遍历是文件同步、备份工具、构建系统里最常见的需求之一。核心思路是：
- opendir打开目录。
- readdir循环读取每个条目。
- 遇到子目录，按路径拼接后递归调用自身。
- 遇到文件，做你想做的处理。
一个最小但完整的实现如下：
#include <stdio.h> #include <string.h> #include <dirent.h> #include <sys/stat.h> #include <unistd.h> static int walk_dir(const char *path, int depth) { DIR *dir = opendir(path); if (dir == NULL) { perror(path); return -1; } struct dirent *entry; while ((entry = readdir(dir)) != NULL) { if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) { continue; } char full_path[4096]; int len = snprintf(full_path, sizeof(full_path), "%s/%s", path, entry->d_name); if (len < 0 || len >= (int)sizeof(full_path)) { fprintf(stderr, "path too long: %s/%s\n", path, entry->d_name); continue; } for (int i = 0; i < depth; i++) { printf(" "); } printf("%s", entry->d_name); if (entry->d_type == DT_DIR) { printf("/\n"); walk_dir(full_path, depth + 1); } else if (entry->d_type == DT_LNK) { printf(" -> symbolic link\n"); } else if (entry->d_type == DT_UNKNOWN) { printf(" (unknown type, use stat)\n"); } else { printf("\n"); } } closedir(dir); return 0; } int main(int argc, char **argv) { const char *root = argc > 1 ? argv[1] : "."; walk_dir(root, 0); return 0; }这段代码我在实际项目里改过很多版，有几个点值得特别说明。
路径拼接用snprintf而不是sprintf，且必须检查返回值。因为文件路径一旦超过缓冲区大小，sprintf就会产生缓冲区溢出，这是极其严重的内存安全问题。snprintf返回“本应写入的字符串长度”，如果它大于等于缓冲区大小，说明路径被截断了，必须跳过这条目录项，否则后续opendir/open是基于一个不完整的路径去操作，行为完全不可预知。
递归深度也不能忽略。如果你遍历的目录层级非常深（比如某些软件生成的多级cache目录），递归调用栈会持续增长，默认8MB栈空间一般够用，但在嵌入式环境里可能就不够了。更健壮的做法是改成显式栈实现非递归遍历，不过那是另一篇文章的篇幅，初版还是用递归最便于理解。
3.2 处理符号链接与死循环
上面代码里遇到DT_LNK我只打印了“symbolic link”，没有继续递归。这是有意为之。为什么不能递归？因为符号链接可以指回祖先目录，形成一个环路：比如 /tmp/a/link -> /tmp/a。如果不检查直接递归，程序会无限套娃，最终栈溢出崩溃。
更隐蔽的情况是：d_type不是DT_LNK，而是一个普通目录或文件，但目录内部存在符号链接指向该目录自身。判断环路的稳妥做法是维护一个“已访问目录”集合，用inode+设备的组合去重。但这样实现复杂度上升不少，一般应用场景下最实用的策略是：遇到符号链接直接用stat判断它指向的是不是目录，是目录则默认不跟随，除非你明确有业务需求要遍历链接指向的内容。如果你确实需要跟随符号链接（比如你想扫描一个含大量软链的部署目录），那就要设深度上限，或者记录路径集合。
另外一个常见的错误是：程序员看到DT_LNK后试图用chdir进入链接，然后getcwd得到“真实路径”，再用这个真实路径递归。这种做法在某些老代码里能见到，但它不仅有竞态窗口，还会让用户看到的路径和实际操作的路径不一致，非常容易引起困惑。正确的姿势是：用entry->d_name拼路径，然后opendir这个完整路径，内核会负责解析符号链接，你不需要手动处理。
3.3 输出格式设计与权限错误处理
目录遍历工具跑不起来，十有八九是因为权限。最常见的现场是：以普通用户运行，opendir一个没有r权限的目录，返回NULL，perror打出一句“Permission denied”。这时候你要想清楚：是继续还是终止？
在实际工具里，我一般倾向“记录错误继续跑”，而不是立刻退出。比如上面代码里opendir失败时，我打印错误信息并return -1，但外层函数收到-1后没有中断整个遍历。也就是说，一个子目录没权限访问，不影响兄弟目录的处理。这一点对构建工具、备份脚本特别重要，因为总有用户目录的权限是700，你扫到它就该华丽地跳过，而不是让整个任务失败。
还有一层权限需要注意：即使opendir成功了，后续在拼接路径访问某个文件时，也可能在文件的父目录上缺少x权限，导致open失败。所以编写目录遍历代码时，对每一次open/stat/readdir调用都要有完整的errno处理，并且要熟练掌握perror或者strerror的输出格式。调试时看着报错信息，比盲改代码高效得多。
4. 实操：像ls -la一样展示文件类型与元信息
4.1 stat 与 d_type 的关系
readdir目录项里的d_type能告诉我们文件类型，但它给不了文件大小、修改时间、权限位这些关键元数据。要拿到这些，必须用stat系列函数。但这里有个性能陷阱：如果你对目录下的每一个文件都调用stat，就多了一次系统调用；百万级文件时，性能差距非常明显。
所以一个成熟的做法是：先看d_type，只有以下情况才去调stat：
- d_type为DT_UNKNOWN，必须用stat确定类型。
- 你需要文件大小、mtime、权限等元信息，自然要调用stat。
如果你只是做一次“是否存在/类型是什么”的判断，优先信任d_type，不做stat。很多编程语言标准库里的目录遍历函数之所以慢，就是因为它对每个目录项都无条件执行了stat/lstat，这在文件量大时很致命。
4.2 用 lstat 判断文件类型
lstat和stat的区别在于：当目标是一个符号链接时，stat返回的是“链接指向的目标文件”的信息，而lstat返回的是“链接本身”的信息。目录遍历时，绝大多数场景你更关心链接本身是什么，所以应该用lstat，否则你遍历到一个指向目录的符号链接，S_ISDIR会判断它为目录，然后你可能就傻傻地递归进去了，造成前面说的死循环。
下面是判断文件类型的标准套路：
struct stat st; if (lstat(full_path, &st) != 0) { perror(full_path); continue; } if (S_ISDIR(st.st_mode)) { // 目录 } else if (S_ISREG(st.st_mode)) { // 普通文件 } else if (S_ISLNK(st.st_mode)) { // 符号链接 } else if (S_ISFIFO(st.st_mode)) { // 管道 } else if (S_ISSOCK(st.st_mode)) { // socket }S_ISDIR这类宏的本质是检查st_mode里的文件类型位段。这个位段位于权限位之上，两者打包在一个unsigned int里，所以不要试图用“st_mode == 0644”之类的写法去判断类型，那永远不成立。
4.3 组合代码：目录列表+类型展示
把上面内容组合起来，写一个简化版“ls -la”：
#include <stdio.h> #include <string.h> #include <dirent.h> #include <sys/stat.h> #include <time.h> #include <unistd.h> static void print_type(mode_t mode) { if (S_ISDIR(mode)) printf("d"); else if (S_ISLNK(mode)) printf("l"); else if (S_ISREG(mode)) printf("-"); else if (S_ISFIFO(mode)) printf("p"); else if (S_ISSOCK(mode)) printf("s"); else if (S_ISBLK(mode)) printf("b"); else if (S_ISCHR(mode)) printf("c"); else printf("?"); } static void print_perms(mode_t mode) { char perms[10] = "---------"; if (mode & S_IRUSR) perms[0] = 'r'; if (mode & S_IWUSR) perms[1] = 'w'; if (mode & S_IXUSR) perms[2] = 'x'; if (mode & S_IRGRP) perms[3] = 'r'; if (mode & S_IWGRP) perms[4] = 'w'; if (mode & S_IXGRP) perms[5] = 'x'; if (mode & S_IROTH) perms[6] = 'r'; if (mode & S_IWOTH) perms[7] = 'w'; if (mode & S_IXOTH) perms[8] = 'x'; printf("%s", perms); } int main(int argc, char **argv) { const char *dir_path = argc > 1 ? argv[1] : "."; DIR *dir = opendir(dir_path); if (!dir) { perror("opendir"); return 1; } struct dirent *entry; while ((entry = readdir(dir)) != NULL) { if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) { continue; } char full_path[4096]; snprintf(full_path, sizeof(full_path), "%s/%s", dir_path, entry->d_name); struct stat st; if (lstat(full_path, &st) != 0) { perror(full_path); continue; } print_type(st.st_mode); print_perms(st.st_mode); printf(" %5ld", (long)st.st_size); printf(" %s", ctime(&st.st_mtime) + 4); printf(" %s\n", entry->d_name); } closedir(dir); return 0; }这里我只是把关键部分拼了出来，正式工具还需要处理ctime返回的字符串尾部换行符，以及时间格式的本地化。你把这段代码跑一遍，基本就能看到一个陌生目录的完整面貌，再往后怎么扩展都方便。
5. 常见问题与排查技巧实录
5.1 d_type 返回 DT_UNKNOWN，怎么办
当你遍历NFS、某些FUSE、甚至某些虚拟文件系统（比如 /proc 下的子目录）时，readdir返回的d_type很可能是DT_UNKNOWN。如果代码里不做任何兜底，你精心设计的“快捷路径”就会失效，最直观的表现就是：目录没有被识别成目录，递归遍历直接断裂。
兜底方案很明确：遇到DT_UNKNOWN就调用lstat。但更优雅的做法是，在结构体内保存一个“是否需要stat”的标志位，不要每次循环都在if-else里写一遍。
struct stat st; if (entry->d_type == DT_UNKNOWN) { if (lstat(full_path, &st) != 0) { perror(full_path); continue; } } else { lstat(full_path, &st); // 这里也可以根据需求决定是否调用 }我自己的经验是：只要目标是写一个通用工具，就直接无条件lstat，因为在不同平台、不同文件系统上，d_type的行为你摸不透。你少调一次stat省下的那点性能，很可能在别的机器上以bug的形式偿还。只有当你明确只跑在ext4/xfs上时，才可以信赖d_type。
5.2 目录遍历时路径太长，或文件名包含特殊字符
Unix路径名理论上限是4096字节（PATH_MAX），但具体到每个文件名，允许的长度可达255字节（NAME_MAX）。这意味着一个深层目录树里，某个文件的完整路径很可能超过4096。比如你用snprintf拼路径，结果发现超过缓冲区长度，这时如果直接使用截断后的路径，后续访问的就是一个不存在的文件。
解法不只是增大缓冲区，而是改用openat这类“基于目录fd”的接口。openat允许你基于一个打开的目录fd，加上一个相对路径去访问子项，避免每次拼接完整路径，这就绕开了路径长度限制。不过openat属于进阶内容，如果只是做小工具，检查snprintf返回值判断是否截断，然后跳过或报错即可。
文件名的特殊字符更是一个大坑。Linux文件名可以是任意字节序列，除了“/”和“\0”。也就是说，一个文件名里可以包含换行符、制表符、甚至非法UTF-8字节。如果你直接把文件名打到终端上，换行符就会错乱输出。所以专业的目录遍历工具在打印文件名时一般会对特殊字符做转义，或者用引号包裹。解析时更要注意：绝对不能按UTF-8文本处理文件名，而应该把它当作“以\0结尾的字节串”，任何字符串函数（strlen、strcmp）都只以字节为单位操作，不带编码假设。
5.3 安全陷阱：拼接路径后的TOCTOU问题
TOCTOU（Time Of Check to Time Of Use）是目录操作里经常被忽略的安全风险。典型场景是：你先用lstat判断一个路径是符号链接，确认安全之后，再去open这个路径；但在这两次调用之间，攻击者把该路径替换成了指向敏感文件的符号链接。你的程序于是毫无防备地打开了不该打开的文件。
解决思路是：不要基于“路径”做判断，而是基于“目录fd + 文件名”做操作。先用open打开目录拿到fd，然后调用openat，并且传入O_NOFOLLOW标志，让内核拒绝打开符号链接。这样判断和打开之间不存在路径解析的窗口期。这套组合在编写安全敏感的工具时几乎必用。
5.4 大量文件目录的性能对比
我做过一个压力测试：目录里有大约50万个文件。
- 用readdir直接遍历，只取文件名和d_type，耗时约0.2秒。
- 如果对每个文件都调用stat，耗时约2秒。
- 如果用scandir加排序，内存占用飙到几百MB，耗时还要再加0.5秒。
所以结论很清楚：如果你只需要文件名列表，别碰stat；如果你需要展示元信息，尽量批量处理而不是逐个交互；如果目录特别大，排序尽量放到最后或者用外部工具（like sort命令）去做，不要把全部数据堆在内存里。系统编程的每一项选择最终都是在时间、空间和可读性之间做权衡，目录操作也不例外。
6. 我的几点实操体会
写目录遍历这类代码写多了，我最大的感受是：基础API本身并不难，难的是边界情况的处理。你以为你只是在递归一个目录树，实际上你同时要跟权限、符号链接、路径长度、字符编码、安全攻击面打交道。真正成熟的工程师写的目录遍历代码，一定不是最简洁的那一版，而是错误处理最完整的那一版。
如果你现在正要开始写这类工具，我的建议是：先把readdir + lstat的组合吃透，不要一上来就依赖find命令或者高层的库函数。等你理解了目录项是什么、d_type从哪里来、符号链接为什么不能随便递归，再去看那些高级接口，就会发现它们不过是帮你省事的外壳，而你，已经具备随时掀开外壳的能力了。
