readdir_r Subroutine
Purpose
Reads a directory.
Library
Thread-Safe C Library (libc_r.a)
Syntax
#include <sys/types.h>
#include <dirent.h>DIR * DirectoryPointer;
struct dirent * Entry;
struct dirent ** Result;
Description
The readdir_r subroutine returns the directory
entry in the structure pointed to by the Result parameter.
The readdir_r subroutine returns entries for the . (dot) and
.. (dot-dot) directories, if present, but never returns an invalid
entry (with d_ino set to 0). When it reaches
the end of the directory, the readdir_r subroutine
returns 9 and sets the Result parameter
to NULL. When it detects an invalid seekdir operation, the readdir_r subroutine
returns a 9.
Using the readdir_r subroutine after the closedir subroutine, for the structure pointed to by the DirectoryPointer parameter, has an undefined result. The structure pointed to by the DirectoryPointer parameter becomes invalid for all threads, including the caller.
Programs using this subroutine must link to the libpthreads.a library.
Parameters
| Item | Description |
|---|---|
| DirectoryPointer | Points to the DIR structure of an open directory. |
| Entry | Points to a structure that contains the next directory entry. |
| Result | Points to the directory entry specified by the Entry parameter. |
Return Values
| Item | Description |
|---|---|
| 0 | Indicates that the subroutine was successful. |
| 9 | Indicates that the subroutine was not successful or that the end of the directory was reached. If the user has set the environment variable XPG_SUS_ENV=ON prior to execution of the process, then the SIGXFSZ signal is posted to the process when exceeding the process' file size limit, and the subroutine will always be successful. |
Error Codes
If the readdir_r subroutine is unsuccessful, the errno global variable is set to one of the following values:
| Item | Description |
|---|---|
| EACCES | Search permission is denied for any component of the structure pointed to by the DirectoryPointer parameter, or read permission is denied for the structure pointed to by the DirectoryPointer parameter. |
| ENAMETOOLONG | The length of the DirectoryPointer parameter exceeds the value of the PATH_MAX variable, or a path-name component is longer than the value of NAME_MAX variable while the _POSIX_NO_TRUNC variable is in effect. |
| ENOENT | The named directory does not exist. |
| ENOTDIR | A component of the structure pointed to by the DirectoryPointer parameter is not a directory. |
| EMFILE | Too many file descriptors are currently open for the process. |
| ENFILE | Too many file descriptors are currently open in the system. |
| EBADF | The structure pointed to by the DirectoryPointer parameter does not refer to an open directory stream. |
Examples
To search a directory for the entry name,enter:
len = strlen(name);
DirectoryPointer = opendir(".");
for (readdir_r(DirectoryPointer, &Entry, &Result); Result != NULL;
readdir_r(DirectoryPointer, &Entry, &Result))
if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
closedir(DirectoryPointer);
return FOUND;
}
closedir(DirectoryPointer);
return NOT_FOUND;