DIRECTORY(3)

DIRECTORY(3) | Library Functions Manual | DIRECTORY(3)

# NAME

`fdopendir`, `opendir`, `readdir`, `readdir_r`, `telldir`, `seekdir`, `rewinddir`, `closedir`, `dirfd` —
directory operations

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <dirent.h>`

DIR *
`opendir`(const char *filename);

DIR *
`fdopendir`(int fd);

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 type DIR represents a directory stream; an ordered sequence of all directory entries in a particular directory. The purpose of the DIR structure is similar to that of the FILE structure maintained by the stdio(3) library functions.

# FUNCTIONS

The following standard directory operations are defined.

`opendir`(filename)
  The `opendir`() function opens the directory named by filename and associates a directory stream with it. The directory stream is positioned at the first entry. Upon successful completion, a pointer to DIR type is returned. Otherwise, `opendir`() returns `NULL`.
`fdopendir`(fd)
  The `fdopendir`() function associates a directory stream with the directory file descriptor fd. The file offset associated with fd at the time of the call determines which entries are returned.

  Upon failure, `fdopendir`() returns `NULL`. Otherwise the file descriptor is under the control of the system, and if any attempt is made to close the file descriptor, or to modify the state of the associated description, other than by means of `closedir`(), `readdir`(), `readdir_r`(), `rewinddir`(), the behavior is undefined. The file descriptor can be closed by calling `closedir`().

`readdir`(dirp)
  The `readdir`() function returns a pointer to the directory entry at the current position in the directory stream specified by dirp, and positions the directory stream at the next entry. It returns `NULL` upon reaching the end of the directory or detecting an invalid `seekdir`() operation. The returned structure is described in dirent(3).

  The returned pointer to the dirent structure points to data which may be overwritten by another call to `readdir`() on the same directory stream. This data is not however overwritten by another call to `readdir`() on a different directory stream.

`readdir_r`(dirp, entry, result)
  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.

  Like `readdir`(), the `readdir_r`() function may buffer several directory entries per actual read operation. Both functions mark for update the st_atime field (see stat(2)) of the directory each time the directory is actually read.

`telldir`(dirp)
  The `telldir`() function returns the current location associated with the directory stream specified by dirp.

  If the most recent operation on the particular directory stream was a `seekdir`(), the directory position returned from `telldir`() is the same as loc supplied as an argument to the `seekdir`() call.

`seekdir`(dirp, loc)
  The `seekdir`() function sets the position of the next `readdir`() operation on the directory stream specified by dirp. The value of loc should come from a previous call to `telldir`() using the same 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.

`rewinddir`(dirp)
  The `rewinddir`() function 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 if a call to `opendir`() would have been made.

  If dirp does not refer to a valid directory stream, the behavior is undefined.

`closedir`(dirp)
  The `closedir`() function closes the directory stream and frees the structure associated with the dirp pointer, returning 0 on success and -1 on failure.
`dirfd`(dirp)
  The `dirfd`() function returns the integer file descriptor associated with the directory stream specified by dirp. Upon failure, `dirfd`() returns -1. The returned file descriptor should not be closed by close(2), it will be released when dirp is closed with `closedir`().

  The rationale of `dirfd`() is to provide a mechanism by which a file descriptor can be obtained for the use of the fchdir(2) function.

# 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);

# COMPATIBILITY

The described directory operations have traditionally been problematic in terms of portability. A good example is the semantics around ‘.’ (dot) and ‘..’ (dot-dot). Based on historical implementations, the rules about file descriptors apply to directory streams as well. The IEEE Std 1003.1-2008 (“POSIX.1”) standard no longer mandates that directory streams be implemented by using file descriptors.

The following additional remarks can be noted from the IEEE Std 1003.1-2008 (“POSIX.1”) standard.

- If the type DIR is implemented using a file descriptor, like in NetBSD, applications should be able to open only `OPEN_MAX` files and directories. Otherwise the limit is left as unspecified.
- When a file descriptor is used to implement the directory stream, the `closedir`() function behaves as if the `FD_CLOEXEC` had been set for the file descriptor. In another words, it is mandatory that `closedir`() deallocates the file descriptor.
- If directory streams are not implemented by using file descriptors, functions such as `dirfd`() may fail with `ENOTSUP`.
- If a file is removed from or added to the directory after the most recent call to `opendir`() or `rewinddir`(), it is unspecified whether a subsequent call to `readdir`() returns an entry for that file.
- When using the function `seekdir`(), note that if the value of loc was not obtained from an earlier call to `telldir`(), or if a call to `rewinddir`() occurred between the calls to `telldir`() and `seekdir`(), any subsequent call to `readdir`() is unspecified, possibly resulting in undefined behavior.
- After a call to fork(2), either the parent or child (but not both) can continue processing the directory stream using `readdir`(), `rewinddir`(), or `seekdir`(). However, if both the parent and child processes use these functions, the result is undefined.

# ERRORS

All described functions may set errno to indicate the error.

# SEE ALSO

close(2), lseek(2), open(2), read(2), dirent(3)

# STANDARDS

The `opendir`(), `readdir`(), `rewinddir`() and `closedir`() functions conform to IEEE Std 1003.1-1990 (“POSIX.1”). The other functions conform to IEEE Std 1003.1-2008 (“POSIX.1”).

# HISTORY

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

January 22, 2016 | NetBSD 9.5