directory(3)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 asso‐
ciates 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 insuffi‐
cient 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 differ‐
ence 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 unde‐
tected 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 indicate 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 environ‐
ment 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 Alsoclose(2), getdirentries(2), lseek(2), open(2), read(2), dir(5)directory(3)