directory(3)

NAME

opendir, readdir, readdir_r, telldir, seekdir, rewinddir,

closedir, dirfd
- directory operations

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <sys/types.h>
#include <dirent.h>
DIR *
opendir(const char *filename);
struct dirent *
readdir(DIR *dirp);
int
readdir_r(DIR  *dirp,  struct  dirent  *entry, struct dirent
**result);
long
telldir(DIR *dirp);
void
seekdir(DIR *dirp, long loc);
void
rewinddir(DIR *dirp);
int
closedir(DIR *dirp);
int
dirfd(DIR *dirp);

DESCRIPTION

The opendir() function opens the directory named by

filename, associates
a directory stream with it and returns a pointer to be used

to identify
the directory stream in subsequent operations. The pointer

NULL is
returned if filename cannot be accessed, or if it cannot

malloc(3) enough
memory to hold the whole thing.

The readdir() function returns a pointer to the next direc

tory entry. It
returns NULL upon reaching the end of the directory or de

tecting an
invalid seekdir() operation.

The readdir_r() function provides the same functionality as

readdir(),
but the caller must provide a directory entry buffer to

store the results
in. If the read succeeds, result is pointed at the entry;

upon reaching
the end of the directory result is set to NULL. The

readdir_r() function
returns 0 on success or an error number to indicate failure.

The telldir() function returns the current location associ

ated with the
named directory stream. Values returned by telldir() are

good only for
the lifetime of the DIR pointer, dirp, from which they are

derived. If
the directory is closed and then reopened, prior values re

turned by
telldir() will no longer be valid.

The seekdir() function sets the position of the next

readdir() operation
on the directory stream. The new position reverts to the

one associated
with the directory stream when the telldir() operation was

performed.

The rewinddir() function resets the position of the named

directory
stream to the beginning of the directory.

The closedir() function closes the named directory stream

and frees the
structure associated with the dirp pointer, returning 0 on

success. On
failure, -1 is returned and the global variable errno is set

to indicate
the error.

The dirfd() function returns the integer file descriptor as

sociated with
the named directory stream, see open(2).

Sample code which searches a directory for entry ``name''

is:

len = strlen(name);
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL)

if (dp->d_namlen == len && !strcmp(dp->d_name,

name)) {

(void)closedir(dirp);
return FOUND;

}

(void)closedir(dirp);
return NOT_FOUND;

SEE ALSO

close(2), lseek(2), open(2), read(2), dir(5)

HISTORY

The opendir(), readdir(), telldir(), seekdir(), rewinddir(),

closedir(),
and dirfd() functions appeared in 4.2BSD.

BSD June 4, 1993

BSD