DIRECTORY(3)DIRECTORY(3)NAME
opendir, readdir, rewinddir, closedir - directory operations
SYNOPSIS
#include <sys/types.h>
#include <sys/dir.h> /* POSIX applications #include <dirent.h> */
DIR *opendir(const char *dirname);
struct direct *readdir(DIR *dirp);
/* Returns struct dirent * for POSIX applications. */
void rewinddir(DIR *dirp);
int closedir(DIR *dirp);
(ALSO AVAILABLE IN BSD)
long telldir(DIR *dirp);
int seekdir(DIR *dirp, long loc);
DESCRIPTION
The opendir function opens the directory named by dirname and
associates a directory stream with it. The function returns a pointer
to be used to identify the directory stream in subsequent operations.
The directory stream is positioned at the first entry of dirname. A
NULL pointer is returned if dirname can not be accessed, or if it can
not malloc enough memory to hold the whole thing.
The readdir function returns a pointer to a direct structure ( dirent
for POSIX applications) representing the directory entry at the current
position in the directory stream referred to by dirp, and positions the
directory stream at the next entry. It returns a NULL pointer upon
reaching the end of the directory stream.
The direct/dirent structure includes the following member:
Member Type Member Name Description
char[] d_name Null-terminated filename.
The rewinddir function resets the position of the directory stream
referred to by dirp to the beginning of the directory. It does not
return a value.
The closedir function closes the directory stream referred to by dirp
and frees the structure.
The following sample code searches the current working directory for
directory 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;
Telldir returns the current location associated with the named
directory stream.
Seekdir sets the position of the next readdir operation on the
directory stream. The new position reverts to the one associated with
the directory stream when the telldir operation was performed. Values
returned by telldir are good only for the lifetime of the DIR pointer
from which they are derived. If the directory is closed and then
reopened, the telldir value may be invalidated due to undetected
directory compaction. It is safe to use a previous telldir value
immediately after a call to opendir and before any calls to readdir.
RETURN VALUE
Upon successful completion, opendir returns a pointer to a DIR
structure. Otherwise, a NULL pointer is returned and errno is set to
indicate the error.
Upon successful completion, readdir returns a pointer to a
direct/dirent structure. When an error occurs, a NULL pointer is
returned and errno is set to indicate the error. When the end of the
directory stream is reached, a NULL pointer is returned and errno is
left unchanged.
Upon successful completion, closedir returns zero. Otherwise, -1 is
returned and errno is set to indicate the error.
ERRORS
If any of the following conditions occurs, the opendir function returns
a NULL pointer and sets errno to the corresponding value:
[EACCES] Search permission is denied for a component of the path
prefix of dirname, or read permission is denied for the
directory itself.
[ENAMETOOLONG] A component of direname exceeds 255 characters, or the
entire dirname exceeds 1023 characters. For POSIX
applications these values are given by the constants
{NAME_MAX} and {PATH_MAX}, respectively.
[ENOENT] The directory named by dirname does not exist, or the
argument points to an empty string.
[ENOTDIR] A pathname component of dirname is not a directory.
If any of the following conditions occurs, the readdir function returns
a NULL pointer and sets errno to the corresponding value:
[EBADF] The dirp argument is a NULL pointer.
If any of the following conditions occurs, the closedir function
returns -1 and sets errno to the corresponding value:
[EBADF] The dirp argument is a NULL pointer.
NOTES
The telldir and seekdir functions are not POSIX-compliant. POSIX
applications should avoid using them.
SEE ALSOopen(2), close(2), read(2), lseek(2)4.2 Berkeley Distribution August 1, 1992 DIRECTORY(3)
