directory(3C) directory(3C)
NAME
directory: opendir, readdir, readdir_r, telldir, seekdir,
rewinddir, closedir - directory operations
SYNOPSIS
#include <dirent.h>
DIR *opendir(const char *filename);
struct dirent *readdir(DIR *dirp);
struct dirent *readdir_r(DIR *dirp, struct dirent *result);
long telldir(DIR *dirp);
void seekdir(DIR *dirp, long loc);
void rewinddir(DIR *dirp);
int closedir(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 enough
memory to hold a DIR structure or a buffer for the directory
entries.
readdir and readdir_r return pointers to the next active
directory entry and position the directory stream (dirp) at
the next entry. Both functions will not return inactive
directory entries. NULL is returned upon reaching the end of
the directory. result is a pointer to a dirent structure
which readdir_r uses to return the directory entry
information. Since the size of the result structure may vary
depending on the length of d_name, one should provide a struct
dirent with at least {NAME_MAX} bytes for d_name. On
successful completion, readdir_r returns the pointer result.
readdir and readdir_r typically buffer several directory
entries per actual read operation; both functions mark for
update the st_atime field of the directory each time the
directory is actually read.
telldir returns the current location associated with the named
directory stream.
seekdir sets the position of the next read 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. Values returned by
Copyright 1994 Novell, Inc. Page 1
directory(3C) directory(3C)
telldir are valid only if the directory has not changed
because of compaction or expansion. This situation is not a
problem with System V, but it may be a problem with some file
system types.
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.
closedir closes the named directory stream and frees the DIR
structure.
Errors
The following errors can occur as a result of these
operations.
opendir returns NULL on failure and sets errno to one of the
following values:
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
{PATH_MAX}, or the length of a filename component
exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in
effect.
ENOENT A component of filename does not exist or is a null
pathname.
Copyright 1994 Novell, Inc. Page 2
directory(3C) directory(3C)
readdir and readdir_r return NULL on failure and set errno to
one of the following values:
ENOENT The current file pointer for the directory is not
located at a valid entry.
EBADF The file descriptor determined by the DIR stream is
no longer valid. This result occurs if the DIR
stream has been closed.
closedir returns -1 on failure and sets errno to the following
value:
EBADF The file descriptor determined by the DIR stream is
no longer valid. This results if the DIR stream has
been closed.
USAGE
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->d_name);
closedir(dirp);
return (0);
}
REFERENCES
dirent(4), getdents(2), mkdir(2), rmdir(2)
NOTICES
rewinddir is implemented as a macro, so its function address
cannot be taken.
These functions overwrite a buffer per DIR as needed, so
applications should copy data or use readdir_r to preserve it.
Copyright 1994 Novell, Inc. Page 3