illumos: manual page: fdopendir.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 Ft 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