Tribblix: manual page: opendir.3c

OPENDIR(3C) Standard C Library Functions OPENDIR(3C)

NAME

opendir, fdopendir - open directory stream

SYNOPSIS

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

DIR *
opendir(dirname);

DIR *
fdopendir(int filedes);

DESCRIPTION

The opendir() and fdopendir() functions are used to create seekable
directory streams that can be used to iterate over the contents of a
directory, most commonly with readdir(3C). One can traverse and seek
the stream with functions such as seekdir(3C), telldir(3C), and
rewinddir(3C).

The opendir() function creates a directory stream from the path named
by dirname. The fdopendir() function creates a directory stream from
an already opened file descriptor, filedes, that refers to a directory.
After successfully calling fdopendir(), filedes belongs to the system
and the application must not modify or close it in any way.

The new directory stream is positioned at the first entry. When
finished with the directory stream, the caller is responsible for
releasing its resources by calling the closedir(3C) function. This
will close the directory stream's underlying file descriptor, including
filedes if fdopendir() was used to create it. In addition, memory
associated with the directory stream, such as the struct dirent
returned from readdir(3C) will be invalid once a call to closedir(3C)
is completed.

All directory streams are closed upon a successful call to any of the
exec(2) family of functions. The underlying file descriptors behave as
though the FD_CLOEXEC flag was set upon them.

Directory streams created by the opendir() function require an
underlying file descriptor. As a result, applications are only able to
open up to a total of {OPEN_MAX} files and directories.

RETURN VALUES

Upon successful completion, the opendir() and fdopendir() functions
return a pointer to an object of type DIR. Otherwise, a null pointer
is returned and errno is set to indicate the error.

ERRORS

The opendir() function will fail if:

EACCES Search permission is denied for any component of the
path prefix of dirname or read permission is denied
for Idirname.

ELOOP Too many symbolic links were encountered in
resolving path.

ENAMETOOLONG The length of the dirname argument exceeds
{PATH_MAX}, or a path name component is longer than
{NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.

ENOENT A component of dirname does not name an existing
directory or dirname is an empty string.

ENOTDIR A component of dirname is not a directory.

The fdopendir() function will fail if:

ENOTDIR The file descriptor filedes does not reference a
directory.

The opendir() function may fail if:

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

ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATH_MAX.

ENFILE Too many files are currently open on the system.

INTERFACE STABILITY