readdir_r Subroutine

Purpose

Reads a directory.

Library

Thread-Safe C Library (libc_r.a)

Syntax

#include <sys/types.h>
#include <dirent.h>

int readdir_r (DirectoryPointer, Entry, Result) 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.

Note: The readdir subroutine is reentrant when an application program uses different DirectoryPointer parameter values (returned from the opendir subroutine). Use the readdir_r subroutine when multiple threads use the same directory pointer.

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;