www.delorie.com/gnu/docs/dirent/directory.3.html

search

	Buy GNU books!

directory

NAME

opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations

SYNOPSIS

#include <sys/types.h>
#include <dirent.h>

DIR **opendir (dirname)
char **dirname;

struct dirent **readdir (dirp)
DIR **dirp;

off_t telldir (dirp)
DIR **dirp;

void seekdir (dirp, loc)
DIR **dirp;
off_t loc;

void rewinddir (dirp)
DIR **dirp;

int closedir (dirp)
DIR **dirp;

DESCRIPTION

Opendir establishes a connection between the directory named by dirname and a unique object of type DIR known as a directory stream that it creates. Opendir returns a pointer to be used to identify the directory stream in subsequent operations. A NULL pointer is returned if dirname cannot be accessed or is not a directory, or if opendir is unable to create the DIR object (perhaps due to insufficient memory).

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, DIRENTSIZ(strlen(direntp->d_name)), not by sizeof(struct dirent) as one might expect. A 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.

Telldir returns the current position associated with the named directory stream for later use as an argument to seekdir.

Seekdir sets the position of the next readdir operation on the named directory stream. The new position reverts to the one associated with the directory stream when the telldir operation from which loc was obtained was performed.

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 readdir on the directory stream.

Closedir closes the named directory stream; internal resources used for the directory stream are liberated, and subsequent use of the associated DIR object is no longer valid. Closedir returns a value of zero if no error occurs, -1 otherwise.

There are several possible errors that can occur as a result of these operations; the external integer variable errno is set to indicate the specific error. (Readdir's detection of the normal end of a directory is not considered to be an error.)

EXAMPLE

Sample code which searches the current working directory for entry name:

dirp = opendir( "." );
while ( (dp = readdir( dirp )) != NULL )
if ( strcmp( dp->d_name, name ) == 0 )
{
(void) closedir( dirp );
return FOUND;
}
(void) closedir( dirp );
return NOT_FOUND;

SEE ALSO

getdents(2), dirent(5).

WARNINGS

Entries for "." and ".." may not be reported for some file system types.

The value returned by telldir need not have any simple interpretation and should only be used as an argument to seekdir. Similarly, the loc argument to seekdir must be obtained from a previous telldir operation on the same directory stream.

Telldir and 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 telldir and seekdir altogether.

The exact set of errno values and meanings may vary among implementations.

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.