opendir()

NAME

opendir(), readdir(), rewinddir(), closedir(), telldir(), seekdir(), dirfd() - directory operations

SYNOPSIS

#include <sys/types.h>
#include <dirent.h>


DIR * opendir (const char *filename)
struct dirent * readdir (DIR *dirp)
void rewinddir (DIR *dirp)
int closedir (DIR *dirp)
long telldir (DIR *dirp)
void seekdir (DIR *dirp, long loc)
int dirfd (DIR *dirp)

These calls create, remove, read, and search directories. They make use of the DIR type, defined in the header <dirent.h>, which represents a directory stream A directory stream is an ordered sequence of all the directory entries in a particular directory. Each directory entry represents a file.

The opendir(3) function opens the directory named by filename, associates a directory stream with it and returns a pointer to be used to identify the directory stream in subsequent operations. readdir(2) returns nULL if filename cannot be accessed, or if it cannot malloc(3) enough memory to hold the whole thing.

The readdir(2) function returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory. If entries for dot or dot-dot exist, one entry will be returned for dot and one entry will be returned for dot-dot; otherwise they will not be returned.

The rewinddir(3) function resets the position of the named directory stream to the beginning of the directory.

The closedir(3) function closes the named directory stream and frees the structure associated with the dirp pointer, returning 0 on success.

The telldir(3) call returns the current location associated with the directory stream indicated by dirp.

The seekdir(3) function sets the position of the next readdir(2) operation on the directory stream. The new position reverts to the one associated with the directory stream when the telldir(3) operation was performed. Values returned by telldir(3) are good only for the lifetime of the DIR pointer, dirp, from which they are derived. If the directory is closed and then reopened, the telldir(3) value may be invalidated due to undetected directory compaction. It is safe to use a previous telldir(3) value immediately after a call to opendir(3) and before any calls to readdir(2).

The dirfd(3) function returns the integer file descriptor associated with the named directory stream, see open(2).

RETURN VALUES

Opendir(3) returns a pointer to a DIR on success. On failure, it returns NULL and sets errno

readdir(2) returns a pointer to a struct dirent on success; when it reaches the end of the directory, it returns NULL and doesn't set errno. On failure, it returns NULL and does set errno.

Closedir(3) returns 0 on success; on error, it returns -1 and sets errno.

Rewinddir(3) and seekdir(3) don't return a value.

On success, telldir(3) returns the current location of the directory stream.

EXAMPLE

To search the current directory for the entry name:

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

ERRORS

Opendir(3) can set errno to the following values:

[EACCES]: The process doesn't have search permission for a component of the path filename, or it doesn't have read permission for the directory itself.
[EMFILE]: The process has too many file descriptors open.
[ENFILE]: The system has too many file descriptors open.
[ENAMETOOLONG]: A component of filename exceeded {NAME_MAX} characters, or the entire pathname exceeded {PATH_MAX} characters.
[ENOENT]: The directory named by filename doesn't exist, or filename is an empty string.
[ENOTDIR]: Some component of filename isn't a directory.

The closedir(3) and readdir(2) functions can set errno to the following values:

[EBADF]: Dirp doesn't refer to an open directory stream.