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

名称

readdir-读取目录

语法

#include <dirent.h>

struct dirent *readdir(DIR *dirp);

说明

readdir()函数返回一个指向dirent结构的指针，该结构表示dirp指向的目录流中的下一个目录条目。在到达目录流的末尾或发生错误时，它返回NULL。

在glibc实现中，Dirent结构定义如下：

struct dirent {
    ino_t          d_ino;       /* Inode number */
    off_t          d_off;       /* Not an offset; see below */
    unsigned short d_reclen;    /* Length of this record */
    unsigned char  d_type;      /* Type of file; 不支持
                                   by all filesystem types */
    char           d_name[256]; /* Null-terminated filename */
};

POSIX.1强制Dirent结构中的唯一字段是d_name和d_ino。其他字段是非标准化的，并非在所有系统上都存在；有关更多详细信息，请参见下面的注释。

差异结构的字段如下：

d_ino

这是文件的索引节点号。

d_off

d_off中返回的值与通过在目录流中当前位置调用telldir(3)返回的值相同。请注意，尽管有类型和名称，但d_off字段在现代文件系统上几乎没有任何类型的目录偏移。应用程序应将此字段视为一个不透明的值，不对其内容进行任何假设；另请参见telldir(3)。

d_reclen

这是返回记录的大小(以字节为单位)。这可能与上面显示的结构定义的大小不匹配；请参阅注释。

d_type

该字段包含一个指示文件类型的值，如果进一步的操作取决于文件的类型，则可以避免调用lstat(2)的开销。

When a suitable feature test macro is defined (_DEFAULT_SOURCE

on glibc versions since 2.19, or
_BSD_SOURCE

on glibc versions 2.19 and earlier),
glibc defines the following macro constants for the value returned in
d_type:

DT_BLK

这是一个块设备。

DT_CHR

这是字符设备。

DT_DIR

这是一个目录。

DT_FIFO

这是一个命名管道(FIFO)。

DT_LNK

这是一个符号链接。

DT_REG

这是一个常规文件。

DT_SOCK

这是UNIX域套接字。

DT_UNKNOWN

无法确定文件类型。

当前，只有某些文件系统(其中包括Btrfs，ext2，ext3和ext4)完全支持返回d_type中的文件类型。所有应用程序都必须正确处理DT_UNKNOWN的返回。

d_name

此字段包含以空值终止的文件名。请参阅注释。

readdir()返回的数据可能被后续对同一目录流的readdir()调用所覆盖。

返回值

成功后，readdir()返回一个指向dirent结构的指针。 (此结构可能是静态分配的；请勿尝试对其进行free(3)。)

如果到达目录流的末尾，则返回NULL且errno不变。如果发生错误，则返回NULL并正确设置errno。为了将流的结尾与错误区分开，在调用readdir()之前将errno设置为零，然后如果返回NULL，则检查errno的值。

错误说明

EBADF

无效的目录流描述符dirp。

属性

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

在当前的POSIX.1规范(POSIX.1-2008)中，readdir()不需要是线程安全的。但是，在现代的实现中(包括glibc实现)，对同时指定不同目录流的readdir()的调用是线程安全的。在必须从同一目录流读取多个线程的情况下，使用带有外部同步的readdir()仍然比使用不推荐使用的readdir_r(3)函数更好。预计将来的POSIX.1版本将要求readdir()在不同目录流上同时使用时必须是线程安全的。

遵循规范

POSIX.1-2001，POSIX.1-2008，SVr4、4.3BSD。

备注

使用opendir(3)打开目录流。

连续调用readdir()读取文件名的顺序取决于文件系统的实现。名称不太可能以任何方式排序。

在POSIX.1中仅指定字段d_name和(作为XSI扩展名)d_ino。除Linux外，d_type字段主要仅在BSD系统上可用。其余字段在许多但不是所有系统上都可用。在glibc下，程序可以通过测试是否定义了_DIRENT_HAVE_D_NAMLEN，_DIRENT_HAVE_D_RECLEN，_DIRENT_HAVE_D_OFF或_DIRENT_HAVE_D_TYPE宏来检查POSIX.1中未定义的字段的可用性。

The d_name field

上面显示的dirent结构定义取自glibc标头，并显示了具有固定大小的d_name字段。

警告：应用程序应避免依赖于d_name字段的大小。 POSIX将其定义为char d_name []，这是一个未指定大小的字符数组，在终止空字节(aq \ 0aq)之前最多有NAME_MAX个字符。

POSIX.1明确指出该字段不应用作左值。该标准还指出，使用sizeof(d_name)是不正确的。请改用strlen(d_name)。 (在某些系统上，此字段被定义为char d_name [1]！)隐含地，使用sizeof(struct dirent)捕获记录的大小(包括d_name的大小)也是不正确的。

注意当通话

fpathconf(fd，_PC_NAME_MAX)

对于大多数文件系统(在某些文件系统(例如CIFS，Windows SMB服务器)上)返回值255，(正确)在d_name中返回的以空终止的文件名实际上可以超过此大小。在这种情况下，d_reclen字段将包含一个值，该值超过上面显示的glibc dirent结构的大小。

另外参见

getdents(2)，read(2)，closedir(3)，dirfd(3)，ftw(3)，offsetof(3)，opendir(3)，readdir_r(3)，rewinddir(3)，scandir(3)， seekdir(3)，telldir(3)

出版信息

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