May 18, 2006 DIRECTORY 3

### NAME

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

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```DIR``*` opendir(```const char *filename`)
```struct` `dirent``*` readdir(```DIR *dirp`)
```int` readdir_r(```DIR * restrict dirp``, struct dirent * restrict entry``, struct dirent ** restrict 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 directory entry. It returns ```NULL` upon reaching the end of the directory or detecting 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 associated with the named directory stream.

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. 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, the telldir(``) value cannot be re-used.

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 associated with the named directory stream, see open(2).

### EXAMPLES

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

  `

      len = strlen(name);
      dirp = opendir(".");
      if (dirp != NULL) {
              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)

### STANDARDS

The opendir(``), readdir(``), rewinddir(``) and closedir(``) functions conform to ISO/IEC 9945-1:1990 (``POSIX.1'') .

### HISTORY

The opendir(``), readdir(``), telldir(``), seekdir(``), rewinddir(``), closedir(``), and dirfd(``) functions appeared in 4.2BSD.