NAME
fdopendir,
opendir,
readdir,
readdir_r,
telldir,
seekdir,
rewinddir,
closedir,
dirfd —
directory operations
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <dirent.h>
DIR *
opendir(
const
char *filename);
DIR *
fdopendir(
int
fd);
struct dirent *
readdir(
DIR
*dirp);
int
readdir_r(
DIR *
restrict dirp,
struct
dirent * restrict entry,
struct dirent ** restrict
result);
long
telldir(
DIR
*dirp);
void
seekdir(
DIR
*dirp,
long loc);
void
rewinddir(
DIR
*dirp);
int
closedir(
DIR
*dirp);
int
dirfd(
DIR
*dirp);
DESCRIPTION
The type
DIR represents a directory stream; an ordered
sequence of all directory entries in a particular directory. The purpose of
the
DIR structure is similar to that of the
FILE structure maintained by the
stdio(3) library functions.
FUNCTIONS
The following standard directory operations are defined.
-
-
- opendir(filename)
- The opendir() function opens the
directory named by filename and associates a
directory stream with it. The directory stream is positioned at the first
entry. Upon successful completion, a pointer to DIR
type is returned. Otherwise, opendir() returns
NULL
.
-
-
- fdopendir(fd)
- The fdopendir() function associates a
directory stream with the directory file descriptor
fd. The file offset associated with
fd at the time of the call determines which entries
are returned.
Upon failure, fdopendir() returns
NULL
. Otherwise the file descriptor is under the
control of the system, and if any attempt is made to close the file
descriptor, or to modify the state of the associated description, other
than by means of closedir(),
readdir(), readdir_r(),
rewinddir(), the behavior is undefined. The file
descriptor can be closed by calling closedir().
-
-
- readdir(dirp)
- The readdir() function returns a pointer
to the directory entry at the current position in the directory stream
specified by dirp, and positions the directory
stream at the next entry. It returns
NULL
upon
reaching the end of the directory or detecting an invalid
seekdir() operation. The returned structure is described
in dirent(3).
The returned pointer to the dirent structure points to
data which may be overwritten by another call to
readdir() on the same directory stream. This data is not
however overwritten by another call to readdir() on a
different directory stream.
-
-
- readdir_r(dirp,
entry, result)
- The readdir_r() function provides the
same functionality as readdir(), but the caller must
provide a directory entry buffer to store the
results in. If the read succeeds, result is pointed
at the entry; upon reaching the end of the directory
result is set to
NULL
. The
readdir_r() function returns 0 on success or an error
number to indicate failure.
Like readdir(), the readdir_r() function
may buffer several directory entries per actual read operation. Both
functions mark for update the st_atime field (see
stat(2)) of the directory each
time the directory is actually read.
-
-
- telldir(dirp)
- The telldir() function returns the
current location associated with the directory stream specified by
dirp.
If the most recent operation on the particular directory stream was a
seekdir(), the directory position returned from
telldir() is the same as loc
supplied as an argument to the seekdir() call.
-
-
- seekdir(dirp,
loc)
- The seekdir() function sets the position
of the next readdir() operation on the directory stream
specified by dirp. The value of
loc should come from a previous call to
telldir() using the same 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, dirp, from
which they are derived. If the directory is closed and then reopened, the
telldir() value cannot be re-used.
-
-
- rewinddir(dirp)
- The rewinddir() function resets the
position of the named directory stream to the beginning of the directory.
It also causes the directory stream to refer to the current state of the
corresponding directory, as if a call to opendir() would
have been made.
If dirp does not refer to a valid directory stream,
the behavior is undefined.
-
-
- closedir(dirp)
- The closedir() function closes the
directory stream and frees the structure associated with the
dirp pointer, returning 0 on success and -1 on
failure.
-
-
- dirfd(dirp)
- The dirfd() function returns the integer
file descriptor associated with the directory stream specified by
dirp. Upon failure, dirfd()
returns -1. The returned file descriptor should not be closed by
close(2), it will be released
when dirp is closed with
closedir().
The rationale of dirfd() is to provide a mechanism by
which a file descriptor can be obtained for the use of the
fchdir(2) function.
EXAMPLES
Sample code which searches a directory for entry “name” is:
len = strlen(name);
dirp = opendir(".");
if (dirp != NULL) {
while ((dp = readdir(dirp)) != NULL)
if (dp->d_namlen == len &&
!strcmp(dp->d_name, name)) {
(void)closedir(dirp);
return (FOUND);
}
(void)closedir(dirp);
}
return (NOT_FOUND);
COMPATIBILITY
The described directory operations have traditionally been problematic in terms
of portability. A good example is the semantics around ‘.’ (dot)
and ‘..’ (dot-dot). Based on historical implementations, the rules
about file descriptors apply to directory streams as well. The
IEEE Std 1003.1-2008 (“POSIX.1”) standard
no longer mandates that directory streams be implemented by using file
descriptors.
The following additional remarks can be noted from the
IEEE Std
1003.1-2008 (“POSIX.1”) standard.
- If the type DIR is implemented
using a file descriptor, like in NetBSD,
applications should be able to open only
OPEN_MAX
files and directories. Otherwise the limit is left as unspecified.
- When a file descriptor is used to implement the
directory stream, the closedir() function behaves as if
the
FD_CLOEXEC
had been set for the file
descriptor. In another words, it is mandatory that
closedir() deallocates the file descriptor.
- If directory streams are not implemented by using file
descriptors, functions such as dirfd() may fail with
ENOTSUP
.
- If a file is removed from or added to the directory
after the most recent call to opendir() or
rewinddir(), it is unspecified whether a subsequent call
to readdir() returns an entry for that file.
- When using the function seekdir(),
note that if the value of loc was not obtained from
an earlier call to telldir(), or if a call to
rewinddir() occurred between the calls to
telldir() and seekdir(), any
subsequent call to readdir() is unspecified, possibly
resulting in undefined behavior.
- After a call to
fork(2), either the parent or
child (but not both) can continue processing the directory stream using
readdir(), rewinddir(), or
seekdir(). However, if both the parent and child
processes use these functions, the result is undefined.
ERRORS
All described functions may set
errno to indicate the
error.
SEE ALSO
close(2),
lseek(2),
open(2),
read(2),
dirent(3)
STANDARDS
The
opendir(),
readdir(),
rewinddir() and
closedir() functions
conform to
IEEE Std 1003.1-1990
(“POSIX.1”). The other functions conform to
IEEE Std 1003.1-2008 (“POSIX.1”).
HISTORY
The
opendir(),
readdir(),
telldir(),
seekdir(),
rewinddir(),
closedir(), and
dirfd() functions appeared in
4.2BSD. The
fdopendir() function
appeared in
NetBSD 6.0.