[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , 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, the readdir_r subroutine returns a 0. 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 (read, readx, readv, readvx, or pread Subroutine) subroutine, scandir or alphasort (scandir or alphasort Subroutine) 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 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]