./_Man_NeXT_html/html3/directory.3.html

Manual page for DIRECTORY(3)

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.