'\"macro stdmacro
.if n .pH g3c.directory @(#)directory	40.22 of 10/26/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} directory 3C "" "" "\&"
.if \nX=1 .ds x} directory 3C "" ""
.if \nX=2 .ds x} directory 3C "" "" "\&"
.if \nX=3 .ds x} directory 3C "" "" "\&"
.TH \*(x}
.SH NAME
\f4directory\fP: \f4opendir\f1, \f4readdir\f1, \f4telldir\f1, \f4seekdir\f1, \f4rewinddir\f1, \f4closedir\f1 \- directory operations
.SH SYNOPSIS
\f4#include <dirent.h>\f1
.PP
\f4DIR \(**opendir (const char \(**filename);\f1
.PP
\f4struct dirent \(**readdir (DIR \(**dirp);\f1
.PP
\f4long telldir (DIR \(**dirp);\f1
.PP
\f4void seekdir (DIR \(**dirp, long loc);\f1
.PP
\f4void rewinddir (DIR \(**dirp);\f1
.PP
\f4int closedir (DIR \(**dirp);\f1
.SH DESCRIPTION
\f4opendir\fP
opens the directory named by
.I filename\^
and associates a
directory stream
with it.
\f4opendir\fP
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
.I filename\^
cannot be accessed or is not a directory,
or if it cannot
\f4malloc\fP(3C)
enough memory to hold a
\f4DIR\fP
structure or a buffer for the directory entries.
.PP
\f4readdir\fP
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
\f4NULL\fP
upon reaching the end of the directory or
upon detecting an invalid
location in the directory.
\f4readdir\fP buffers several directory entries per actual read operation;
\f4readdir\fP marks for update the \f4st_atime\fP field of the directory
each time the directory is actually read.
.PP
\f4telldir\fP
returns the current location associated with the named
directory stream.
.PP
\f4seekdir\fP
sets the position of the next
\f4readdir\fP
operation on the
directory stream.
The new position reverts to the position associated with
the directory stream
at the time the
\f4telldir\fP
operation that provides
.I loc\^
was performed.
Values returned by
\f4telldir\fP
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.
.PP
\f4rewinddir\fP
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
\f4opendir\fP would.
.PP
\f4closedir\fP
closes the named
directory stream
and frees the
\f4DIR\fP
structure.
.P
The following errors can occur as a result
of these operations.
.PP
\f4opendir\fP
returns \f4NULL\fP on failure and sets
\f4errno\fP to one of the following values:
.TP 20
\f4ENOTDIR\fP
A component of
.I filename\^
is not a directory.
.TP 20
\f4EACCES\fP
A component of 
.I filename\^
denies search permission.
.TP 20
\f4EACCES\fP
Read permission is denied on the specified directory.
.TP 20
\f4EMFILE\fP
The maximum number of file descriptors are currently open.
.TP 20
\f4ENFILE\fP
The system file table is full.
.TP 20
\f4EFAULT\fP
.I filename\^
points outside the allocated address space.
.TP 20
\f4ELOOP\fP
Too many symbolic links were encountered in translating \f2filename\fP.
.TP 20
\f4ENAMETOOLONG\fP
The length of the \f2filename\f1 argument exceeds \f4{PATH_MAX}\f1, or the
length of a \f2filename\f1 component exceeds \f4{NAME_MAX}\f1 while
\f4{_POSIX_NO_TRUNC}\f1 is in effect.
.TP 20
\f4ENOENT\fP
A component of
.I filename
does not exist or is a null pathname.
.P
\f4readdir\fP
returns \f4NULL\fP on failure and sets \f4errno\fP to one of the following values:
.TP 20
\f4ENOENT\fP
The current file pointer for the directory
is not located at a valid entry.
.TP 20
\f4EBADF\fP
The file descriptor determined by the
\f4DIR\fP
stream is no longer valid.  This result occurs
if the 
\f4DIR\fP
stream has been closed.
.P
\f4telldir\fP, \f4seekdir\fP, and  \f4closedir\fP
return \-1 on failure and set \f4errno\fP to the following value:
.TP 20
\f4EBADF\fP
The file descriptor determined by the
\f4DIR\fP
stream is no longer valid.
This results if the
\f4DIR\fP
stream has been closed.
.SH EXAMPLE
Here is a sample program that prints the names of all
the files in the current directory:
.PP
.RS
.ft 4
.nf
#include <stdio.h>
#include <dirent.h>

main()
{
	DIR \(**dirp;
	struct dirent \(**direntp;

	dirp = opendir( "." );
	while ( (direntp = readdir( dirp )) != NULL )
		(void)printf( "%s\en", direntp\->d_name );
	closedir( dirp );
	return (0);
}
.fi
.ft 1
.RE
.bp
.SH SEE ALSO
\f4getdents\fP(2), \f4dirent\fP(4).
.SH NOTES
\f4rewinddir\fP
is implemented as a macro,
so its function address cannot be taken.
