DIRECTORY(3X-POSIX) RISC/os Reference Manual DIRECTORY(3X-POSIX)
NAME
directory: opendir, readdir, rewinddir, closedir - directory
operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *opendir (dirname)
char *dirname;
struct dirent *readdir (dirp)
DIR *dirp;
void rewinddir (dirp)
DIR *dirp;
int closedir(dirp)
DIR *dirp;
DESCRIPTION
The type DIR, which is defined in 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 direc-
tory or added to a directory asynchronously to the opera-
tions described in this manual page. The type DIR is imple-
mented using a file descriptor; applications may only open
up to a total of {OPEN_MAX} files and directories (see
open(2)). A successful call to any of the exec functions
will close any directory streams that are open in the cal-
ling process.
opendir opens the directory named by dirname and associates
a directory stream with it. opendir returns a pointer to be
used to identify the directory stream in subsequent opera-
tions. The NULL pointer is returned if dirname cannot be
accessed or is not a directory, or if it cannot malloc(3X)
enough memory to hold a DIR structure or a buffer for the
directory entries.
readdir returns a pointer to the next active directory
entry. No inactive entries are returned. It returns NULL
upon reaching the end of the directory or upon detecting an
invalid location in the directory.
readdir does not return directory entries containing empty
names. One entry is returned for dot and one entry for
dot-dot.
The pointer returned by readdir points to data which may be
overwritten by another call to readdir on the same directory
Printed 1/15/91 Page 1
DIRECTORY(3X-POSIX) RISC/os Reference Manual DIRECTORY(3X-POSIX)
stream. This data is not overwritten by another call to
readdir on a different directory stream.
readdir may buffer several directory entries per actual read
operation; readdir marks for update the st_atime field of
the directory each time the directory is actually read.
rewinddir resets the position of the named directory stream
to the beginning of the directory and also causes the direc-
tory stream to refer to the current state of the directory,
as a call to opendir would have done.
closedir closes the named directory stream and frees the DIR
structure. The file descriptor associated with DIR is
closed.
The result of using a directory stream after a call to one
of the exec functions is undefined. After a call to fork,
either the parent or the child, but not both, may continue
processing the directory stream using readdir or rewinddir
or both. If both the parent and child processes use these
functions, the result is undefined. Either or both
processes may use closedir.
RETURN VALUES
Upon successful completion, opendir returns a pointer to an
object of type DIR. Otherwise, a value of NULL 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 value of NULL is returned and errno is set to indicate the
error. When the end of the directory is encountered, a
value of NULL is returned and errno is not changed by this
call.
Upon successful completion, closedir returns a value of
zero. Otherwise, a value of -1 is returned and errno is set
to indicate the error.
ERRORS
The following errors can occur as a result of these opera-
tions.
opendir:
[ENOTDIR] A component of dirname is not a direc-
tory.
[EACCES] A component of dirname denies search
permission, or read permission is denied
for the directory itself.
Page 2 Printed 1/15/91
DIRECTORY(3X-POSIX) RISC/os Reference Manual DIRECTORY(3X-POSIX)
[EFAULT] dirname points outside the allocated
address space.
[ENAMETOOLONG] The length of dirname exceeds
{PATH_MAX}, or a pathname component is
longer than {NAME_MAX} while
{_POSIX_NO_TRUNC} is in effect.
[ENOENT] The named directory does not exist, or
dirname point to an empty string.
[EMFILE] Too many file descriptors are currently
open for the process.
[ENFILE] Too many file descriptors are currently
open in the system.
readdir:
[ENOENT] The current file pointer for the direc-
tory is not located at a valid entry.
[EBADF] The file descriptor determined by the
DIR stream is no longer valid. This
results if the DIR stream has been
closed.
closedir:
[EBADF] The file descriptor determined by the
DIR stream is no longer valid. This
results if the DIR stream has been
closed.
EXAMPLE
Sample code which searches a directory for entry name:
dirp = opendir( "." );
while ( (dp = readdir( dirp )) != NULL )
if ( strcmp( dp->d_name, name ) == 0 )
{
closedir( dirp );
return FOUND;
}
closedir( dirp );
return NOT_FOUND;
SEE ALSO
fcntl(2), getdents(2), dirent(4).
Printed 1/15/91 Page 3