directory(3C)directory(3C)NAME
directory: opendir, readdir, readdir64, telldir, telldir64, seekdir,
seekdir64, rewinddir, closedir, readdir_r, readdir64_r - directory
operations
SYNOPSIS
#include <dirent.h>
DIR *opendir (const char *filename);
struct dirent *readdir (DIR *dirp);
struct dirent64 *readdir64 (DIR *dirp);
off_t telldir (DIR *dirp);
off64_t telldir64 (DIR *dirp);
void seekdir (DIR *dirp, off_t loc);
void seekdir64 (DIR *dirp, off64_t loc);
void rewinddir (DIR *dirp);
int closedir (DIR *dirp);
int readdir_r (DIR *dirp, struct dirent *entry, struct dirent **res);
int readdir64_r (DIR *dirp, struct dirent64 *entry, struct dirent64
**res);
DESCRIPTION
The inclusion of <dirent.h> selects the System V versions of these
routines. For the 4.3BSD versions, include <sys/dir.h>. The 64-bit
interfaces are not present in the 4.3BSD versions.
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.
readdir returns a pointer to the next active directory entry and
positions the directory stream at the next 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 buffers
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.
Page 1
directory(3C)directory(3C)
readdir_r is a reentrant version of readdir. The directory entry at the
current position in dirp is copied into entry. The storage pointed to by
entry shall be large enough for a dirent with an array of char d_name
member containing at least {NAME_MAX} plus one 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.
telldir returns the current location associated with the named directory
stream.
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. Values returned by 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.
readdir64, readdir64_r, seekdir64, and telldir64 are parallel interfaces
provided for cases where the information returned will not fit in the
fields in the dirent structure. The fields in question are the inode
number (d_ino) and the current offset (d_off). If it is necessary to
call the 64-bit interfaces, and they are not called, an EOVERFLOW error
will result. The 64-bit readdir and telldir interfaces should not be
mixed with the non-64-bit interfaces in a sequence of calls.
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.
Page 2
directory(3C)directory(3C)
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.
readdir returns NULL on failure and sets 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.
EDIRCORRUPTED The directory is corrupted on disk.
EOVERFLOW One of the inode number values or offset values did
not fit in 32 bits, and the 64-bit interfaces were
not used.
EINVAL 64-bit and non-64-bit calls were mixed in a sequence
of calls.
readdir_r returns 0 on success and an error value (see above values for
readdir) on error.
telldir, seekdir, and closedir return -1 on failure and set 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.
EINVAL 64-bit and non-64-bit calls were mixed in a sequence
of calls.
EXAMPLE
Here is a sample program that prints the names of all the files in the
current directory:
#include <stdio.h>
#include <dirent.h>
Page 3
directory(3C)directory(3C)main()
{
DIR *dirp;
struct dirent *direntp;
dirp = opendir( "." );
while ( (direntp = readdir( dirp )) != NULL )
(void)printf( "%s\n", direntp->d_name );
closedir( dirp );
return (0);
}
SEE ALSOgetdents(2), mkdir(2), rmdir(2), malloc(3C), scandir(3C), dirent(4),
directory_bsd(3B).
NOTES
These functions overwrite the buffer as needed, so applications should
copy data to preserve it.
The telldir() and seekdir() functions used long in place of off_t prior
to IRIX 6.2. This change makes no difference in the o32 and 64 bit
compilation environments, but in the n32 compilation environment source
that used to use a long may need to be changed to use an off_t instead.
BUGS
The prototypes for telldir() and seekdir() in dirent.h use long rather
than off_t in the o32 and 64 bit compilation environments. This is
harmless, however, because long and off_t are identical in these
environments.
Page 4
