Movatterモバイル変換

NAME

opendir - open a directory

SYNOPSIS

#include <dirent.h>

DIR *opendir(const char *dirname);


DESCRIPTION

Theopendir() function shall open a directory stream corresponding to the directory named by thedirname argument.The directory stream is positioned at the first entry. If the typeDIR is implemented using a file descriptor, applicationsshall only be able to open up to a total of {OPEN_MAX} files and directories.

RETURN VALUE

Upon successful completion,opendir() shall return a pointer to an object of typeDIR. Otherwise, a null pointershall be returned anderrno set to indicate the error.

ERRORS

Theopendir() function shall fail if:

[EACCES]

Search permission is denied for the component of the path prefix ofdirname or read permission is denied fordirname.

[ELOOP]

A loop exists in symbolic links encountered during resolution of thedirname argument.

[ENAMETOOLONG]

The length of thedirname argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENOENT]

A component ofdirname does not name an existing directory ordirname is an empty string.

[ENOTDIR]

A component ofdirname is not a directory.

Theopendir() function may fail if:

[ELOOP]

More than {SYMLOOP_MAX} symbolic links were encountered during resolution of thedirname argument.

[EMFILE]

{OPEN_MAX} file descriptors are currently open in the calling process.

[ENAMETOOLONG]

As a result of encountering a symbolic link in resolution of thedirname argument, the length of the substituted pathnamestring exceeded {PATH_MAX}.

[ENFILE]

Too many files are currently open in the system.

EXAMPLES

Open a Directory Stream

The following program fragment demonstrates how theopendir() function is used.

#include <sys/types.h>#include <dirent.h>#include <libgen.h>...    DIR *dir;    struct dirent *dp;...    if ((dir = opendir (".")) == NULL) {        perror ("Cannot open .");        exit (1);    }
    while ((dp = readdir (dir)) != NULL) {...

APPLICATION USAGE

Theopendir() function should be used in conjunction withreaddir(),closedir(), andrewinddir() toexamine the contents of the directory (see the EXAMPLES section inreaddir() ). This method isrecommended for portability.

RATIONALE

Based on historical implementations, the rules about file descriptors apply to directory streams as well. However, this volumeof IEEE Std 1003.1-2001 does not mandate that the directory stream be implemented using file descriptors. The descriptionofclosedir() clarifies that if a file descriptor is used for the directory stream,it is mandatory thatclosedir() deallocate the file descriptor. When a filedescriptor is used to implement the directory stream, it behaves as if the FD_CLOEXEC had been set for the file descriptor.

The directory entries for dot and dot-dot are optional. This volume of IEEE Std 1003.1-2001 does not provide a way totesta priori for their existence because an application that is portable must be written to look for (and usually ignore)those entries. Writing code that presumes that they are the first two entries does not always work, as many implementations permitthem to be other than the first two entries, with a "normal" entry preceding them. There is negligible value in providing a wayto determine what the implementation does because the code to deal with dot and dot-dot must be written in any case and becausesuch a flag would add to the list of those flags (which has proven in itself to be objectionable) and might be abused.

Since the structure and buffer allocation, if any, for directory operations are defined by the implementation, this volume ofIEEE Std 1003.1-2001 imposes no portability requirements for erroneous program constructs, erroneous data, or the use ofunspecified values such as the use or referencing of adirp value or adirent structure value after a directorystream has been closed or after afork() or one of theexec function calls.

FUTURE DIRECTIONS

None.

SEE ALSO

closedir(),lstat(),readdir(),rewinddir(),symlink(), the Base Definitions volume of IEEE Std 1003.1-2001,<dirent.h>,<limits.h>,<sys/types.h>

CHANGE HISTORY

First released in Issue 2.

Issue 6

In the SYNOPSIS, the optional include of the<sys/types.h> header isremoved.

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

• The requirement to include<sys/types.h> has been removed. Although<sys/types.h> was required for conforming implementations of previous POSIXspecifications, it was not required for UNIX applications.

• The [ELOOP] mandatory error condition is added.

• A second [ENAMETOOLONG] is added as an optional error condition.

The following changes were made to align with the IEEE P1003.1a draft standard:

• The [ELOOP] optional error condition is added.