Linux程序员手册 第3部分
更新日期： 2016-03-01

名称

readdir_r-读取目录

语法

#include <dirent.h>

int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

glibc的功能测试宏要求(请参阅feature_test_macros(7))：

readdir_r()：

_POSIX_C_SOURCE || / * Glibc版本

说明

不推荐使用此功能；使用readdir(3)代替。

readdir_r()函数被发明为readdir(3)的可重入版本。它从目录流dirp中读取下一个目录条目，并将其返回到由该条目指向的调用者分配的缓冲区中。有关dirent结构的详细信息，请参见readdir(3)。

指向返回缓冲区的指针放在* result;中。如果遇到目录流的末尾，则在* result中返回NULL。

建议应用程序使用readdir(3)而不是readdir_r()。此外，从2.24版开始，glibc弃用了readdir_r()。原因如下：

*

在未定义NAME_MAX的系统上，调用readdir_r()可能是不安全的，因为接口不允许调用者指定用于返回目录条目的缓冲区的长度。

*

在某些系统上，readdir_r()无法读取名称很长的目录条目。当glibc实现遇到这样的名称时，在读取最终目录条目之后，readdir_r()失败，并显示错误ENAMETOOLONG。在其他一些系统上，readdir_r()可能会返回成功状态，但是返回的d_name字段不能为null终止或可以被截断。

*

在当前的POSIX.1规范(POSIX.1-2008)中，不需要readdir(3)是线程安全的。但是，在现代实现中(包括glibc实现)，对同时指定不同目录流的readdir(3)的调用是线程安全的。因此，在多线程程序中通常不需要使用readdir_r()。在必须从同一目录流读取多个线程的情况下，出于上述几点的原因，与外部使用readdir_r()相比，将readdir(3)与外部同步仍然是更可取的。

*

预计将来的POSIX.1版本将使readdir_r()过时，并要求同时在不同目录流上使用readdir(3)是线程安全的。

返回值

readdir_r()函数成功返回0。出现错误时，它将返回一个正的错误号(在"错误"下列出)。如果到达目录流的末尾，则readdir_r()返回0，并在* result中返回NULL。

错误说明

EBADF

无效的目录流描述符dirp。

ENAMETOOLONG

遇到名称太长而无法读取的目录条目。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

POSIX.1-2001，POSIX.1-2008。

另外参见

readdir(3)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。