opendir, readdir, telldir, seekdir, rewinddir, closedir, opendir64, readdir64, telldir64, seekdir64, rewinddir64, closedir64, or fdopendir Subroutine

Purpose

Performs operations on directories.

Library

Standard C Library (libc.a)

Syntax

#include <dirent.h>

long int telldir(DirectoryPointer)
DIR *DirectoryPointer;

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

void rewinddir (DirectoryPointer)
DIR *DirectoryPointer;

int closedir (DirectoryPointer)
DIR *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;

Description

The opendir subroutine opens the directory designated by the DirectoryName parameter and associates a directory stream with it.

The opendir subroutine also returns a pointer to identify the directory stream in subsequent operations. The null pointer is returned when the directory named by the DirectoryName parameter cannot be accessed or when not enough memory is available to hold the entire stream. A successful call to any of the exec functions closes any directory streams opened in the calling process.

The fdopendir() function is equivalent to the opendir() function, except that the directory is specified by a file descriptor rather than by a name. The file offset associated with the file descriptor at the time of the call, determines the entries that are returned.

Upon the successful return from fdopendir(), the file descriptor is under the control of the system, and if any attempt is made to close the file descriptor, or to modify the state of the associated description, other than by means of closedir(), readdir(), readdir_r(), or rewinddir(), the behavior is undefined. Upon calling closedir() the file descriptor is closed.

The readdir subroutine returns a pointer to the next directory entry. The readdir subroutine returns entries for . (dot) and .. (dot dot), 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 subroutine returns the null value. The returned pointer designates data that may be overwritten by another call to the readdir subroutine on the same directory stream. A call to the readdir subroutine on a different directory stream does not overwrite this data. The readdir subroutine marks the st_atime field of the directory for update each time the directory is actually read.

The telldir subroutine returns the current location associated with the specified directory stream.

The seekdir subroutine sets the position of the next readdir subroutine operation on the directory stream. An attempt to seek an invalid location causes the readdir subroutine to return the null value the next time it is called. The position should be that returned by a previous telldir subroutine call.

The rewinddir subroutine resets the position of the specified directory stream to the beginning of the directory.

The closedir subroutine closes a directory stream and frees the structure associated with the DirectoryPointer parameter. If the closedir subroutine is called for a directory that is already closed, the behavior is undefined. To prevent this, always initialize the DirectoryPointer parameter to null after closure.

If you use the fork subroutine to create a new process from an existing one, either the parent or the child (but not both) may continue processing the directory stream using the readdir, rewinddir, or seekdir subroutine.

The readdir64 subroutine is similar to the readdir subroutine except that it returns a pointer to an object of type struct dirent64.

The telldir64 subroutine is similar to the telldir subroutine except that it returns the current directory location in an offset_t format.

The seekdir64 subroutine is similar to the seekdir subroutine except that the Location parameter is set in the format of offset_t.

The rewinddir64 subroutine resets the position of the specified directory stream (obtained by the opendir64 subroutine) to the beginning of the directory.

Parameters

Return Values

On successful completion, the opendir, and fdopendir subroutines returns a pointer to an object of type DIR, and the opendir64 subroutine returns a pointer to an object of type DIR64. Otherwise, a null value is returned and the errno global variable is set to indicate the error.

On successful completion, the readdir subroutine returns a pointer to an object of type struct dirent, and the readdir64 subroutine returns a pointer to an object of type struct dirent64. Otherwise, a null value is returned and the errno global variable is set to indicate the error. When the end of the directory is encountered, a null value is returned and the errno global variable is not changed by this function call.

On successful completion, the telldir or telldir64 subroutine returns the current location associated with the specified directory stream. Otherwise, a null value is returned.

On successful completion, the closedir or closedir64 subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

If the opendir subroutine is unsuccessful, it returns a null value and sets the errno global variable to one of the following values:

If the readdir or readdir64 subroutine is unsuccessful, it returns a null value and sets the errno global variable to the following value:

If the closedir or closedir64 subroutine is unsuccessful, it returns a value of -1 and sets the errno global variable to the following value:

If the fdopendir subroutine is unsuccessful, it returns a null value and sets the errno global variable to one of the following values:

Examples

To search a directory for the entry 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