readdir_r Subroutine

Base Operating System and Extensions Technical Reference, Volume 2

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, or 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.

Parameters

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

0	Indicates that the subroutines was successful.
9	Indicates that the subroutines was not successful.

Error Codes

If the readdir_r subroutine is unsuccessful, the errno global variable is set to one of the following values:

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;

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Programs using this subroutine must link to the libpthreads.a library.

Related Information

The close subroutine, exec subroutines, fork subroutine, lseek subroutine, openx, open, or creat subroutine, read, readv, readx, or readvx subroutine, scandir or alphasort subroutine.

The opendir, readdir, telldir, seekdir, rewinddir, or closedir subroutine.

Subroutines Overview, List of File and Directory Manipulation Services, and List of Multithread Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.