opendir ， readdir ， telldir ， seekdir ， rewinddir ， closedir ， opendir64， readdir64， telldir64， seekdir64， rewinddir64， closedir64或 fdopendir 子例程

用途

对目录执行操作。

库

标准 C 库 (libc.a)

语法

#include <dirent.h>

DIR *opendir ( DirectoryName )
const char *DirectoryName;

struct dirent *readdir ( DirectoryPointer )
DIR *DirectoryPointer;

long int telldir(DirectoryPointer)
DIR *DirectoryPointer;

void seekdir(DirectoryPointer,Location)
DIR *DirectoryPointer;
long Location;

void rewinddir (DirectoryPointer)
DIR *DirectoryPointer;

int closedir (DirectoryPointer)
DIR *DirectoryPointer;

DIR *opendir64 ( DirectoryName)
const char *DirectoryName;

struct dirent64 *readdir64 ( DirectoryPointer)
DIR64 *DirectoryPointer;

offset_t telldir64(DirectoryPointer)
DIR64 *DirectoryPointer;

void seekdir64(DirectoryPointer,Location)
DIR64 *DirectoryPointer;
offset_t Location;

void rewinddir64 (DirectoryPointer)
DIR64 *DirectoryPointer;

int closedir64 (DirectoryPointer)
DIR64 *DirectoryPointer;

DIR *fdopendir(fd);
int fd;

描述

注意: 请勿在多线程环境中使用 readdir 子例程。请参阅 readdir_r 子例程文章中的多线程替代方法。

opendir 子例程打开由 DirectoryName 参数指定的目录，并将目录流与其关联。

注: 必须始终使用 closedir 子例程关闭打开的目录，以确保下次尝试打开该目录成功。

opendir 子例程还返回一个指针以在后续操作中标识目录流。如果无法访问由 DirectoryName 参数指定的目录，或者没有足够的内存可用于保存整个流，那么将返回空指针。成功调用任何 exec 函数都会关闭在调用过程中打开的任何目录流。

fdopendir() 函数等同于 opendir() 函数，只是目录由文件描述符而不是名称指定。在调用时与文件描述符关联的文件偏移量确定返回的条目。

从 fdopendir()成功返回时，文件描述符受系统控制，如果尝试关闭文件描述符或修改关联描述的状态 (通过 closedir()， readdir()， readdir_r()或 rewinddir()除外) ，那么行为未定义。调用 closedir() 时，文件描述符已关闭。

readdir 子例程返回指向下一个目录条目的指针。 readdir 子例程返回 . (点) 和 .. (点点) 的条目 (如果存在) ，但从不返回无效的条目 (将 d_ino 设置为 0)。当它到达目录的末尾时，或者当它检测到无效的 seekdir 操作时， readdir 子例程将返回空值。返回的指针指定可能被同一目录流上的 readdir 子例程的另一个调用覆盖的数据。对另一个目录流上的 readdir 子例程的调用不会覆盖此数据。 readdir 子例程会在每次实际读取目录时标记要更新的目录的 st_atime 字段。

telldir 子例程返回与指定目录流关联的当前位置。

seekdir 子例程设置下一个 readdir 子例程操作在目录流上的位置。尝试查找无效位置会导致 readdir 子例程在下次调用时返回空值。位置应该是先前 telldir 子例程调用返回的位置。

rewinddir 子例程将指定目录流的位置重置为目录的开头。

closedir 子例程关闭目录流并释放与 DirectoryPointer 参数关联的结构。如果对已关闭的目录调用 closedir 子例程，那么行为未定义。要防止发生此情况，请始终在关闭后将 DirectoryPointer 参数初始化为 null。

如果使用 fork 子例程从现有子例程创建新进程，那么父或子 (但不能同时使用这两个子例程) 可以使用 readdir， rewinddir或 seekdir 子例程继续处理目录流。

opendir64 子例程类似于 opendir 子例程，只是它返回一个指向类型为 DIR64的对象的指针。

注: opendir64 子例程的打开目录必须始终与 closedir64 子例程一起关闭，以确保下次尝试打开该目录成功。此外，必须使用 64 位接口 (readdir64， telldir64， seekdir64， rewinddir64和 closedir64) 进行操作以获取正确的目录信息。

readdir64 子例程类似于 readdir 子例程，只是它返回一个指向类型为 struct dirent64的对象的指针。

telldir64 子例程类似于 telldir 子例程，只是它以 offset_t 格式返回当前目录位置。

seekdir64 子例程与 seekdir 子例程相似，只是 Location 参数以 offset_t格式设置。

rewinddir64 子例程将指定目录流 (由 opendir64 子例程获取) 的位置重置为目录的开头。

参数

项	描述
`DirectoryName`	命名目录。
`DirectoryPointer`	指向开放式目录的 DIR 或 DIR64 结构。
`位置`	指定相对于目录开头的项的偏移量。

返回值

成功完成时， opendir和 fdopendir 子例程将返回指向类型为 DIR的对象的指针，而 opendir64 子例程将返回指向类型为 DIR64的对象的指针。否则，将返回空值，并设置 errno 全局变量以指示错误。

成功完成时， readdir 子例程将返回指向类型为 struct dirent的对象的指针，而 readdir64 子例程将返回指向类型为 struct dirent64的对象的指针。否则，将返回空值，并设置 errno 全局变量以指示错误。迂到目录结束时，将返回空值，并且此函数调用不会更改 errno 全局变量。

成功完成时， telldir 或 telldir64 子例程返回与指定目录流相关联的当前位置。否则，将返回空值。

成功完成时， closedir 或 closedir64 子例程将返回值 0。否则，将返回值-1并设置全局变量 "errno以指示错误。

错误代码

如果 opendir 子例程不成功，那么它将返回空值并将 errno 全局变量设置为下列其中一个值:

项	描述
EACCES	指示拒绝对 `DirectoryName` 参数的任何组件的搜索许可权，或拒绝对 `DirectoryName` 参数的读许可权。
ENAMETOOLONG	指示 `DirectoryName` 参数自变量的长度超过 PATH_MAX 值，或者当 POSIX_NO_TRUNC 值生效时，路径名组件的长度超过 NAME_MAX 值。
ENOENT	表示指定的目录不存在。
ENOTDIR	指示 `DirectoryName` 参数的组件不是目录。
电子文件	指示当前为该进程打开的文件描述符过多。
ENFILE	指示当前在系统中打开了太多文件描述符。

如果 readdir 或 readdir64 子例程不成功，那么它将返回空值并将 errno 全局变量设置为以下值:

项	描述
EBADF	指示 `DirectoryPointer` 参数自变量未引用开放式目录流。

如果 "closedir或 "closedir64子程序不成功，则返回值为-1，并将 "errno全局变量设置为以下值：

项	描述
EBADF	指示 `DirectoryPointer` 参数自变量未引用开放式目录流。

如果 fdopendir 子例程不成功，那么它将返回空值并将 errno 全局变量设置为下列其中一个值:

项	描述
EBADF	指示 `fd` 参数不是打开用于读取的有效文件描述符。
ENOTDIR	指示描述符 `fd` 未与目录相关联。

示例

要在目录中搜索条目 name，请执行以下操作:

len = strlen(name);
DirectoryPointer = opendir(".");
for (dp = readdir(DirectoryPointer); dp != NULL; dp =
 readdir(DirectoryPointer))
        if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
                closedir(DirectoryPointer);
                DirectoryPointer=NULL     //To prevent multiple closure
                return FOUND;
        }
closedir(DirectoryPointer);
                DirectoryPointer=NULL     //To prevent multiple closure