Standard C Library Functions readdir(3C)
NAME
readdir, readdirr - read directory
SYNOPSIS
#include
#include
struct dirent *readdir(DIR *dirp);
struct dirent *readdirr(DIR *dirp, struct dirent *entry);
Standard conforming
cc [ flag... ] file... -DPOSIXPTHREADSEMANTICS [ library... ]
int readdirr(DIR *restrict dirp, struct dirent *restrict entry,
struct dirent **restrict result);
DESCRIPTION
The type DIR, which is defined in the header ,
represents a directory stream, which is an ordered sequence
of all the directory entries in a particular directory.
Directory entries represent files. Files can be removed from
a directory or added to a directory asynchronously to the
operation of readdir() and readdirr().
readdir()
The readdir() function returns a pointer to a structure
representing the directory entry at the current position in
the directory stream specified by the argument dirp, and
positions the directory stream at the next entry. It returns
a null pointer upon reaching the end of the directory
stream. The structure dirent defined by the
header describes a directory entry.
The readdir() function will not return directory entries
containing empty names. If entries for . (dot) or .. (dot-
dot) exist, one entry will be returned for dot and one entry
will be returned for dot-dot; otherwise they will not be
returned.
The pointer returned by readdir() points to data that can be
overwritten by another call to readdir() on the same direc-
tory stream. These data are not overwritten by another call
to readdir() on a different directory stream.
SunOS 5.11 Last change: 26 Jun 2007 1
Standard C Library Functions readdir(3C)
If a file is removed from or added to the directory after
the most recent call to opendir(3C) or rewinddir(3C),
whether a subsequent call to readdir() returns an entry for
that file is unspecified.
The readdir() function can buffer several directory entries
per actual read operation. It marks for update the statime
field of the directory each time the directory is actually
read.
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(3C). If both the parent
and child processes use these functions, the result is unde-
fined.
If the entry names a symbolic link, the value of the dino
member is unspecified.
readdirr()
Unless the end of the directory stream has been reached or
an error occurred, the readdirr() function initializes the
dirent structure referenced by entry to represent the direc-
tory entry at the current position in the directory stream
referred to by dirp, and positions the directory stream at
the next entry.
The caller must allocate storage pointed to by entry to be
large enough for a dirent structure with an array of char
dname member containing at least NAMEMAX (that is,
pathconf(directory, PCNAMEMAX)) plus one elements.
(PCNAMEMAX is defined in .)
The readdirr() function will not return directory entries
containing empty names. It is unspecified whether entries
are returned for . (dot) or .. (dot-dot).
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 readdirr() returns an entry for that
file is unspecified.
The readdirr() function can buffer several directory
entries per actual read operation. It marks for update the
statime field of the directory each time the directory is
SunOS 5.11 Last change: 26 Jun 2007 2
Standard C Library Functions readdir(3C)
actually read.
The standard-conforming version (see standards(5)) of the
readdirr() function performs all of the actions described
above and sets the pointer pointed to by result. If a direc-
tory entry is returned, the pointer will be set to the same
value as the entry argument; otherwise, it will be set to
NUL.
RETURN VALUES
Upon successful completion, readdir() and the default
readdirr() return a pointer to an object of type struct
dirent. When an error is encountered, a null pointer is
returned and errno is set to indicate the error. When the
end of the directory is encountered, a null pointer is
returned and errno is not changed.
The standard-conforming readdirr() returns 0 if the end of
the directory is encountered or a directory entry is stored
in the structure referenced by entry. Otherwise, an error
number is returned to indicate the failure.
ERORS
The readdir() and readdirr() functions will fail if:
EOVERFLOW One of the values in the structure to be
returned cannot be represented correctly.
The readdir() and readdirr() functions may fail if:
EBADF The dirp argument does not refer to an open direc-
tory stream.
ENOENT The current position of the directory stream is
invalid.
USAGE
The readdir() and readdirr() functions should be used in
conjunction with opendir(), closedir(), and rewinddir() to
examine the contents of the directory. Since readdir() and
the default readdirr() return a null pointer both at the
end of the directory and on error, an application wanting to
check for error situations should set errno to 0 before cal-
ling either of these functions. If errno is set to non-zero
on return, an error occurred.
SunOS 5.11 Last change: 26 Jun 2007 3
Standard C Library Functions readdir(3C)
It is safe to use readdir() in a threaded application, so
long as only one thread reads from the directory stream at
any given time. The readdir() function is generally pre-
ferred over the readdirr() function.
The standard-conforming readdirr() returns the error number
if an error occurred. It returns 0 on success (including
reaching the end of the directory stream).
The readdir() and readdirr() functions have transitional
interfaces for 64-bit file offsets. See lf64(5).
EXAMPLES
Example 1 Search the current directory for the entry name.
The following sample program will search the current direc-
tory for each of the arguments supplied on the command line:
#include
#include
#include
#include
#include
static void lookup(const char *arg)
{
DIR *dirp;
struct dirent *dp;
if ((dirp = opendir(".")) == NUL) {
perror("couldn't open '.'");
return;
}
do {
errno = 0;
if ((dp = readdir(dirp)) != NUL) {
if (strcmp(dp->dname, arg) != 0)
continue;
(void) printf("found %s\n", arg);
(void) closedir(dirp);
return;
}
} while (dp != NUL);
if (errno != 0)
perror("error reading directory");
SunOS 5.11 Last change: 26 Jun 2007 4
Standard C Library Functions readdir(3C)
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(argv[i]);
return (0);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level See below.
The readdir() function is Unsafe. The readdirr() function
is Safe.
SEE ALSO
fork(2), lstat(2), symlink(2), Intro(3), closedir(3C),
opendir(3C), rewinddir(3C), scandir(3C), seekdir(3C), attri-
butes(5), lf64(5), standards(5)
NOTES
When compiling multithreaded programs, see the MULTITHREADED
APLICATIONS section of Intro(3).
Solaris 2.4 and earlier releases provided a readdirr()
interface as specified in POSIX.1c Draft 6. The final
POSIX.1c standard changed the interface as described above.
Support for the Draft 6 interface is provided for compati-
bility only and might not be supported in future releases.
New applications and libraries should use the standard-
conforming interface.
SunOS 5.11 Last change: 26 Jun 2007 5
Standard C Library Functions readdir(3C)
For POSIX.1c-conforming applications, the
POSIXPTHREADSEMANTICS and RENTRANT flags are automati-
cally turned on by defining the POSIXCSOURCE flag with a
value >= 199506L.
SunOS 5.11 Last change: 26 Jun 2007 6
|
