directory(3) Library Functions Manual directory(3)
Name
opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations
Syntax
#include <sys/types.h>
#include <sys/dir.h>
DIR *opendir(dirname)
char *dirname;
struct direct *readdir(dirp)
DIR *dirp;
long telldir(dirp)
DIR *dirp;
void seekdir(dirp, loc)
DIR *dirp;
long loc;
void rewinddir(dirp)
DIR *dirp;
int closedir(dirp)
DIR *dirp;
Description
The library routine opens the directory named by filename and associates a directory stream with it. A pointer is returned to identify the
directory stream in subsequent operations. The pointer NULL is returned if the specified filename can not be accessed, or if insufficient
memory is available to open the directory file.
The routine returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or on detecting an
invalid operation. The routine uses the system call to read directories. Since the routine returns NULL upon reaching the end of the
directory or on detecting an error, an application which wishes to detect the difference must set errno to 0 prior to calling
The routine returns the current location associated with the named directory stream. Values returned by are good only for the lifetime of
the DIR pointer from which they are derived. If the directory is closed and then reopened, the value may be invalidated due to undetected
directory compaction.
The routine sets the position of the next operation on the directory stream. Only values returned by should be used with
The routine resets the position of the named directory stream to the beginning of the directory.
The routine closes the named directory stream and returns a value of 0 if successful. Otherwise, a value of -1 is returned and errno is set
to indicate the error. All resources associated with this directory stream are released.
Examples
The following sample code searches a directory for the entry name.
len = strlen(name);
dirp = opendir(".");
for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
closedir(dirp);
return FOUND;
}
closedir(dirp);
return NOT_FOUND;
Environment
In the POSIX environment, the file descriptor returned in the DIR structure after an call will have the FD_CLOEXEC flag set. See <fcntl.h>
for more detail.
Return Values
Upon successful completion, returns a pointer to an object of type DIR. Otherwise, a value of NULL is returned and errno is set to indi-
cate the error.
The routine returns a pointer to an object of type struct dirent upon successful completion. Otherwise, a value of NULL is returned and
errno is set to indicate the error. When the end of the directory is encountered, a value of NULL is returned and errno is not changed.
The routine returns the current location. No errors are defined for and
The routine returns zero upon successful completion. Otherwise, a value of -1 is returned and errno is set to indicate the error.
Diagnostics
The routine will fail if:
[EBADF] The dirp argument does not refer to an open directory stream.
[EINTR] The routine was interrupted by a signal.
The routine will fail if:
[EACCES] Search permission is denied for any component of dirname or read permission is denied for dirname.
[ENAMETOOLONG] The length of the dirname string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.
[ENOENT] The dirname argument points to the name of a file which does not exist, or to an empty string and the environment defined is
POSIX or SYSTEM_FIVE.
[ENOTDIR] A component of dirname is not a directory.
[EMFILE] Too many file descriptors are currently open for the process.
[ENFILE] Too many files are currently open in the system.
The routine will fail if:
[EBADF] The dirp argument does not refer to an open directory stream.
See Also
close(2), getdirentries(2), lseek(2), open(2), read(2), dir(5)
directory(3)