Originální popis anglicky:
readdir, readdir_r - read a directory
Návod, kniha: POSIX Programmer's Manual
#include <dirent.h>
struct dirent *readdir(DIR *
dirp);
int readdir_r(DIR *restrict dirp, struct dirent *restrict
entry,
struct dirent **restrict
result);
The type
DIR, which is defined in the
<dirent.h> header,
represents a
directory stream, which is an ordered sequence of all the
directory entries in a particular directory. Directory entries represent
files; files may be removed from a directory or added to a directory
asynchronously to the operation of
readdir().
The
readdir() function shall return a pointer to a structure representing
the directory entry at the current position in the directory stream specified
by the argument
dirp, and position the directory stream at the next
entry. It shall return a null pointer upon reaching the end of the directory
stream. The structure
dirent defined in the
<dirent.h>
header describes a directory entry.
The
readdir() function shall not return directory entries containing
empty names. If entries for dot or dot-dot exist, one entry shall be returned
for dot and one entry shall be returned for dot-dot; otherwise, they shall not
be returned.
The pointer returned by
readdir() points to data which may be overwritten
by another call to
readdir() on the same directory stream. This data is
not overwritten by another call to
readdir() on a different directory
stream.
If a file is removed from or added to the directory after the most recent call
to
opendir() or
rewinddir(), whether a subsequent call to
readdir() returns an entry for that file is unspecified.
The
readdir() function may buffer several directory entries per actual
read operation;
readdir() shall mark for update the
st_atime
field of the directory each time the directory is actually read.
After a call to
fork(), either the parent or child (but not both) may
continue processing the directory stream using
readdir(),
rewinddir(), or
seekdir(). If both the parent and child
processes use these functions, the result is undefined.
If the entry names a symbolic link, the value of the
d_ino member is
unspecified.
The
readdir() function need not be reentrant. A function that is not
required to be reentrant is not required to be thread-safe.
The
readdir_r() function shall initialize the
dirent structure
referenced by
entry to represent the directory entry at the current
position in the directory stream referred to by
dirp, store a pointer
to this structure at the location referenced by
result, and position
the directory stream at the next entry.
The storage pointed to by
entry shall be large enough for a
dirent
with an array of
char d_name members containing at least
{NAME_MAX}+1 elements.
Upon successful return, the pointer returned at *
result shall have the
same value as the argument
entry. Upon reaching the end of the
directory stream, this pointer shall have the value NULL.
The
readdir_r() function shall not return directory entries containing
empty names.
If a file is removed from or added to the directory after the most recent call
to
opendir() or
rewinddir(), whether a subsequent call to
readdir_r() returns an entry for that file is unspecified.
The
readdir_r() function may buffer several directory entries per actual
read operation; the
readdir_r() function shall mark for update the
st_atime field of the directory each time the directory is actually
read.
Applications wishing to check for error situations should set
errno to 0
before calling
readdir(). If
errno is set to non-zero on return,
an error occurred.
Upon successful completion,
readdir() shall return a pointer to an object
of type
struct dirent. When an error is encountered, a null pointer
shall be returned and
errno shall be set to indicate the error. When
the end of the directory is encountered, a null pointer shall be returned and
errno is not changed.
If successful, the
readdir_r() function shall return zero; otherwise, an
error number shall be returned to indicate the error.
The
readdir() function shall fail if:
- EOVERFLOW
- One of the values in the structure to be returned cannot be
represented correctly.
The
readdir() function may fail if:
- EBADF
- The dirp argument does not refer to an open
directory stream.
- ENOENT
- The current position of the directory stream is invalid.
The
readdir_r() function may fail if:
- EBADF
- The dirp argument does not refer to an open
directory stream.
The following sections are informative.
The following sample program searches the current directory for each of the
arguments supplied on the command line.
#include <dirent.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
static void lookup(const char *arg)
{
DIR *dirp;
struct dirent *dp;
if ((dirp = opendir(".")) == NULL) {
perror("couldn't open '.'");
return;
}
do {
errno = 0;
if ((dp = readdir(dirp)) != NULL) {
if (strcmp(dp->d_name, arg) != 0)
continue;
(void) printf("found %s\n", arg);
(void) closedir(dirp);
return;
}
} while (dp != NULL);
if (errno != 0)
perror("error reading directory");
else
(void) printf("failed to find %s\n", arg);
(void) closedir(dirp);
return;
}
int main(int argc, char *argv[])
{
int i;
for (i = 1; i < argc; i++)
lookup(arvg[i]);
return (0);
}
The
readdir() function should be used in conjunction with
opendir(),
closedir(), and
rewinddir() to examine the
contents of the directory.
The
readdir_r() function is thread-safe and shall return values in a
user-supplied buffer instead of possibly using a static data area that may be
overwritten by each call.
The returned value of
readdir() merely
represents a directory
entry. No equivalence should be inferred.
Historical implementations of
readdir() obtain multiple directory entries
on a single read operation, which permits subsequent
readdir()
operations to operate from the buffered information. Any wording that required
each successful
readdir() operation to mark the directory
st_atime field for update would disallow such historical
performance-oriented implementations.
Since
readdir() returns NULL when it detects an error and when the end of
the directory is encountered, an application that needs to tell the difference
must set
errno to zero before the call and check it if NULL is
returned. Since the function must not change
errno in the second case
and must set it to a non-zero value in the first case, a zero
errno
after a call returning NULL indicates end-of-directory; otherwise, an error.
Routines to deal with this problem more directly were proposed:
int derror (dirp)
DIR *dirp;
void clearderr ( dirp)
DIR *dirp;
The first would indicate whether an error had occurred, and the second would
clear the error indication. The simpler method involving
errno was
adopted instead by requiring that
readdir() not change
errno
when end-of-directory is encountered.
An error or signal indicating that a directory has changed while open was
considered but rejected.
The thread-safe version of the directory reading function returns values in a
user-supplied buffer instead of possibly using a static data area that may be
overwritten by each call. Either the {NAME_MAX} compile-time constant or the
corresponding
pathconf() option can be used to determine the maximum
sizes of returned pathnames.
None.
closedir() ,
lstat() ,
opendir() ,
rewinddir() ,
symlink() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<dirent.h>,
<sys/types.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
