directory(3C) directory(3C)
NAME
directory: opendir, readdir, telldir, seekdir, rewinddir, closedir,
readdir64 - directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *opendir(const char *filename);
struct dirent *readdir(DIR *dirp);
long int telldir(DIR *dirp);
void seekdir(DIR *dirp, long int loc);
void rewinddir(DIR *dirp);
int closedir(DIR *dirp);
struct dirent64 *readdir64(DIR *dirp);
DESCRIPTION
opendir() opens the directory named by filename and associates a
directory stream with it. opendir() returns a pointer to be used to
identify the directory stream in subsequent operations. The directory
stream is positioned at the first entry. A null pointer is returned if
filename cannot be accessed or is not a directory, or if it cannot
malloc(3C) enough memory to hold a DIR structure or a buffer for the
directory entries. A successful call to any of the exec functions will
close any directory streams that are open in the calling process.
The type DIR, which is defined in the header <dirent.h>, 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 asyn-
chronously to the operation of 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 <dirent.h>
header describes a directory entry.
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.
Page 1 Reliant UNIX 5.44 Printed 11/98
directory(3C) directory(3C)
The pointer returned by readdir() points to data which may be over-
written by another call to readdir() on the same directory stream.
This data is not overwritten by another call to readdir() on a dif-
ferent 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() marks for update the statime 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 func-
tions, the result is undefined.
If the entry names a symbolic link, the value of the dino member is
unspecified.
The telldir() function obtains the current location associated with
the directory stream specified by dirp.
If the most recent operation on the directory stream was a seekdir(),
the directory position returned from the telldir() is the same as that
supplied as a loc argument for seekdir().
seekdir() sets the position of the next readdir() operation on the
directory stream. The new position reverts to the position associated
with the directory stream at the time the telldir() operation that
provides loc was performed. If the value of loc was not obtained from
an earlier call to telldir() or if a call to rewinddir() occurred
between the call to telldir() and the call to seekdir(), the results
of subsequent calls to readdir() are unspecified.
rewinddir() 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 a call
to opendir() would.
In the readdir() and rewinddir() functions, either the parent or child
process (but not both) can continue the directory stream using read-
dir(), rewinddir() or seekdir() after a fork() call. If both processes
use these functions, behavior is undefined.
closedir() closes the named directory stream and frees the DIR struc-
ture.
There is no functional difference between readdir() and readdir64(),
except for the interpretation of struct dirent64 [see dirent(4)].
Page 2 Reliant UNIX 5.44 Printed 11/98
directory(3C) directory(3C)
RETURN VALUE
Upon successful completion, opendir() returns a pointer to an object
of type DIR. Otherwise, a null pointer is returned and errno is set to
indicate the error.
Upon successful completion, readdir() returns 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.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
The following errors can occur as a result of these operations:
ENOTDIR A component of filename is not a directory.
EACCES A component of filename denies search permission.
EACCES Read permission is denied on the specified directory.
EMFILE The maximum number of file descriptors are currently
open.
ENFILE The system file table is full.
EFAULT filename points outside the allocated address space.
ELOOP Too many symbolic links were encountered in translating
filename
ENAMETOOLONG The length of the filename argument exceeds PATHMAX, or
the length of a filename component exceeds NAMEMAX.
ENAMETOOLONG Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATHMAX.
ENOENT filename points to the name of a file that does not
exist or to an empty string.
readdir() returns NULL on failure and sets errno to one of the follow-
ing values:
ENOENT The current file pointer for the directory is not
located at a valid entry.
EBADF The file descriptor determined by the directory stream
is no longer valid. This result occurs if the directory
stream has been closed.
Page 3 Reliant UNIX 5.44 Printed 11/98
directory(3C) directory(3C)
EOVERFLOW One of the values in the structure to be returned cannot
be represented correctly.
telldir(), seekdir(), and closedir() return -1 on failure and set
errno to the following value:
EBADF The file descriptor determined by the directory stream
is no longer valid. This results if the directory stream
has been closed.
EXAMPLES
Here is a sample program that prints the names of all the files in the
current directory:
#include <stdio.h>
#include <dirent.h>
main()
{
DIR *dirp;
struct dirent *direntp;
dirp = opendir( "." );
while ( (direntp = readdir( dirp )) != NULL )
(void)printf( "%s\n", direntp->dname );
closedir( dirp );
return (0);
}
NOTES
rewinddir() is implemented as a macro, so its function address cannot
be taken.
SEE ALSO
getdents(2), lstat(2), symlink(2), dirent(4), limits(4), lfs(5),
types(5).
Page 4 Reliant UNIX 5.44 Printed 11/98