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

Technical Reference: Base Operating System and Extensions, Volume 1


opendir, readdir, telldir, seekdir, rewinddir, or closedir Subroutine

Purpose

Performs operations on directories.

Library

Standard C Library (libc.a)

Syntax

#include <dirent.h>


DIR *opendir ( DirectoryName)
const char *DirectoryName;


struct dirent *readdir ( DirectoryPointer)
DIR *DirectoryPointer;

long int telldir(DirectoryPointer)
DIR *DirectoryPointer;

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

void rewinddir (DirectoryPointer)
DIR *DirectoryPointer;

int closedir (DirectoryPointer)
DIR *DirectoryPointer;

Description

Attention: Do not use the readdir subroutine in a multithreaded environment. See the multithread alternative in the readdir_r subroutine article.

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

Note: An open directory must always be closed with the closedir subroutine to ensure that the next attempt to open that directory is successful.

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 (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) functions closes any directory streams opened in the calling process.

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 you use the fork (fork, f_fork, or vfork Subroutine) 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.

Parameters


DirectoryName Names the directory.
DirectoryPointer Points to the DIR structure of an open directory.
Location Specifies the offset of an entry relative to the start of the directory.

Return Values

On successful completion, the opendir subroutine returns a pointer to an object of type DIR. 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. 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 closedir 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:

EACCES Indicates that search permission is denied for any component of the DirectoryName parameter, or read permission is denied for the DirectoryName parameter.
ENAMETOOLONG Indicates that the length of the DirectoryName parameter argument exceeds the PATH_MAX value, or a path-name component is longer than the NAME_MAX value while the POSIX_NO_TRUNC value is in effect.
ENOENT Indicates that the named directory does not exist.
ENOTDIR Indicates that a component of the DirectoryName parameter is not a directory.
EMFILE Indicates that too many file descriptors are currently open for the process.
ENFILE Indicates that too many file descriptors are currently open in the system.

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

EBADF Indicates that the DirectoryPointer parameter argument does not refer to an open directory stream.

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

EBADF Indicates that the DirectoryPointer parameter argument does not refer to an open directory stream.

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);
                return FOUND;
        }
closedir(DirectoryPointer);
return NOT_FOUND;

Implementation Specifics

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

Related Information

The close (close Subroutine) subroutine, exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutines, fork (fork, f_fork, or vfork Subroutine) subroutine, lseek (lseek, llseek or lseek64 Subroutine) subroutine, openx, open, or creat (open, openx, open64, creat, or creat64 Subroutine) subroutine, read, readv, readx, or readvx subroutine, scandir or alphasort subroutine.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


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