directory(3C)

NAME

directory: closedir(), opendir(), readdir(), readdir_r(), rewinddir(), seekdir(), telldir() — directory operations

SYNOPSIS

#include <dirent.h>

DIR *opendir(const char *dirname);

struct dirent *readdir(DIR *dirp);

int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

long int telldir(DIR *dirp);

void seekdir(DIR *dirp, long int loc);

void rewinddir(DIR *dirp);

int closedir(DIR *dirp);

DESCRIPTION

This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries.

opendir(): opens the directory dirname and associates a directory stream with it. opendir() returns a pointer used to identify the directory stream in subsequent operations. opendir() uses malloc() to allocate memory.
readdir(): returns a pointer to the next directory entry. It returns a NULL pointer upon reaching the end of the directory or detecting an invalid seekdir() operation. See dirent(5) for a description of the fields available in a directory entry.
readdir_r(): initializes the dirent structure referenced by entry to represent the current position in the directory stream referenced by dirp, and stores a pointer to this structure at the location referenced by result.
telldir(): returns the current location (encoded) associated with the directory stream to which dirp refers.
seekdir(): sets the position of the next readdir() operation on the directory stream to which dirp refers. The loc argument is a location within the directory stream obtained from telldir(). The position of the directory stream is restored to where it was when telldir() returned that loc value. Values returned by telldir() are valid only while the DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the telldir() value might be invalid.
rewinddir(): resets the position of the directory stream to which dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to opendir() would have done.
closedir(): closes the named directory stream, then frees the structure associated with the DIR pointer.

APPLICATION USAGE

Users of readdir_r() should note that readdir_r() now conforms with the POSIX.1c Threads standard. The old prototype of readdir_r() is supported for compatibility with existing DCE applications only.

RETURN VALUE

opendir(): upon successful completion, returns a pointer to an object of type DIR referring to an open directory stream. Otherwise, it returns a NULL pointer and sets the global variable errno to indicate the error.
readdir(): upon successful completion, returns a pointer to an object of type struct dirent describing a directory entry. Upon reaching the end of the directory, readdir() returns a NULL pointer and does not change the value of errno. Otherwise, it returns a NULL pointer and sets errno to indicate the error.
readdir_r(): upon successful completion returns a 0. On successful return, the pointer returned at result has the same value as the argument entry. Upon reaching end of the directory stream, result has the value NULL. An error number is returned upon error.
telldir(): upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns -1 and sets errno to indicate the error.
seekdir(): does not return any value, but if an error is encountered, errno is set to indicate the error.
closedir(): upon successful completion, returns a value of 0. Otherwise, it returns a value of -1 and sets errno to indicate the error.

ERRORS

opendir() fails if any of the following conditions are encountered:

EACCES: Search permission is denied for a component of dirname, or read permission is denied for dirname.
EFAULT: dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent.
ELOOP: Too many symbolic links were encountered in translating the path name.
EMFILE: Too many open file descriptors are currently open for the calling process.
ENAMETOOLONG: A component of dirname exceeds PATH_MAX bytes, or the entire length of dirname exceeds PATH_MAX - 1 bytes while _POSIX_NO_TRUNC is in effect.
ENFILE: Too many open file descriptors are currently open on the system.
ENOENT: A component of dirname does not exist or dirname points to an empty string.
ENOMEM: malloc() failed to provide sufficient memory to process the directory.
ENOTDIR: A component of dirname is not a directory.

readdir() or readdir_r() might fail if any of the following conditions are encountered:

EBADF: dirp does not refer to an open directory stream.
EFAULT: dirp points outside the allocated address space of the process.
EIO: An I/O error occurred.
ENOENT: The directory stream to which dirp refers is not located at a valid directory entry.
ENXIO: Directory may be corrupted.

telldir() might fail if any of the following conditions are encountered:

EBADF: dirp does not refer to an open directory stream.
ENOENT: dirp specifies an improper file system block size.

seekdir() might fail if the following condition is encountered:

ENOENT: dirp specifies an improper file system block size.

closedir() might fail if any of the following conditions are encountered:

EBADF: dirp does not refer to an open directory stream.
EFAULT: dirp points outside the allocated address space of the process.

rewinddir() might fail if any of the following conditions are encountered:

EBADF: dirp does not refer to an open directory stream.
EFAULT: dirp points outside the allocated address space of the process.

EXAMPLES

The following code searches the current directory for an entry name:

DIR *dirp;
struct dirent *dp;
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL) {
        if (strcmp(dp->d_name, name) == 0) {
                (void) closedir(dirp);
                return FOUND;
        }
}
(void) closedir(dirp);
return NOT_FOUND;

WARNINGS

readdir() and getdirentries() (see getdirentries(2)) are the only ways to access remote NFS directories. Attempting to read a remote directory via NFS by using read() returns -1 and sets errno to EISDIR (see read(2)).

If a file is removed from or added to the directory after the most recent call to opendir() or rewinddir(), whether a subsequent call to readdir() or readdir_r() returns an entry for that file is unspecified.

For 32-bit applications, the d_ino field of the dirent struct may overflow for filesystems that use 64-bit values. In this case the most-significant bytes will be truncated without generating an error and d_ino values may not be unique.

AUTHOR

directory was developed by AT&T, HP, and the University of California, Berkeley.

STANDARDS CONFORMANCE

closedir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

opendir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

readdir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

readdir_r(): POSIX.1c

rewinddir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

seekdir(): AES, SVID3, XPG2, XPG3, XPG4

telldir(): AES, XPG2, XPG3, XPG4