BSD 4_3_Net_2 development

[unix-history] / usr / src / contrib / isode / dirent / directory.3c

.TH DIRECTORY 3C "Standard Extension"
.SH NAME
opendir, readdir, telldir, seekdir, rewinddir, closedir \- directory operations
.SH SYNOPSIS
.B "#include <sys/types.h>"
.br
.B "#include <isode/usr.dirent.h>"
.P
.B "DIR \(**opendir (dirname)"
.br
.B "char \(**dirname;"
.P
.B "struct dirent \(**readdir (dirp)"
.br
.B "DIR \(**dirp;"
.P
.B "off_t telldir (dirp)"
.br
.B "DIR \(**dirp;"
.P
.B "void seekdir (dirp, loc)"
.br
.B "DIR \(**dirp;"
.br
.B "off_t loc;"
.P
.B "void rewinddir (dirp)"
.br
.B "DIR \(**dirp;"
.P
.B "int closedir (dirp)"
.br
.B "DIR \(**dirp;"
.SH DESCRIPTION
.I Opendir
establishes a connection between
the directory named by
.I dirname
and a unique object of type
.SM DIR
known as a
.I "directory stream"
that it creates.
.I Opendir
returns a pointer to be used to identify the
directory stream
in subsequent operations.
A
.SM NULL
pointer is returned if
.I dirname
cannot be accessed or is not a directory,
or if
.I opendir
is unable to create the
.SM DIR
object
(perhaps due to insufficient memory).
.P
.I Readdir
returns a pointer to an internal structure
containing information about the next active directory entry.
No inactive entries are reported.
The internal structure may be overwritten by
another operation on the same
directory stream;
the amount of storage needed to hold a copy
of the internal structure is given by the value of a macro,
.IR DIRENTSIZ(strlen(direntp\->d_name)) ,
not by
.I "sizeof(struct\ dirent)"
as one might expect.
A
.SM NULL
pointer is returned
upon reaching the end of the directory,
upon detecting an invalid location in the directory,
or upon occurrence of an error while reading the directory.
.P
.I Telldir
returns the current position associated with the named
directory stream
for later use as an argument to
.IR seekdir .
.P
.I Seekdir
sets the position of the next
.I readdir
operation on the named
directory stream.
The new position reverts to the one associated with the
directory stream
when the
.I telldir
operation from which
.I loc
was obtained was performed.
.P
.I Rewinddir
resets the position of the named
directory stream
to the beginning of the directory.
All buffered data for the directory stream is discarded,
thereby guaranteeing that the actual
file system directory will be referred to for the next
.I readdir
on the
directory stream.
.P
.I Closedir
closes the named
directory stream;
internal resources used for the
directory stream are liberated,
and subsequent use of the associated
.SM DIR
object is no longer valid.
.I Closedir
returns a value of zero if no error occurs,
\-1 otherwise.
.P
There are several possible errors that can occur
as a result of these operations;
the external integer variable
.I errno
is set to indicate the specific error.
.RI ( Readdir 's
detection of the normal end of a directory
is not considered to be an error.)
.SH EXAMPLE
Sample code which searches the current working directory for entry
.IR name :
.sp
.P
.ft B
       dirp = opendir( "." );
.br
       while ( (dp = readdir( dirp )) != NULL )
.br
               if ( strcmp( dp\->d_name, name ) == 0 )
.br
                       {
.br
                       (void) closedir( dirp );
.br
                       return FOUND;
.br
                       }
.br
       (void) closedir( dirp );
.br
       return NOT_FOUND;
.ft P
.sp
.SH "SEE ALSO"
getdents(2), dirent(4).
.SH WARNINGS
Entries for "." and ".."
may not be reported for some file system types.
.P
The value returned by
.I telldir
need not have any simple interpretation
and should only be used as an argument to
.IR seekdir .
Similarly,
the
.I loc
argument to
.I seekdir
must be obtained from a previous
.I telldir
operation on the same
directory stream.
.P
.I Telldir
and
.I seekdir
are unreliable when used in conjunction with
file systems that perform directory compaction or expansion
or when the directory stream has been closed and reopened.
It is best to avoid using
.I telldir
and
.I seekdir
altogether.
.P
The exact set of
.I errno
values and meanings may vary among implementations.
.P
Because directory entries can dynamically
appear and disappear,
and because directory contents are buffered
by these routines,
an application may need to continually rescan
a directory to maintain an accurate picture
of its active entries.