Performs operations on directories.
Standard C Library (libc.a)
#include <dirent.h>DIR *opendir ( DirectoryName)
const char *DirectoryName;
struct dirent *readdir ( DirectoryPointer)
DIR *DirectoryPointer;
long int telldir(DirectoryPointer)
DIR *DirectoryPointer;void seekdir(DirectoryPointer,Location)
DIR *DirectoryPointer;
long Location;void rewinddir (DirectoryPointer)
DIR *DirectoryPointer;int closedir (DirectoryPointer)
DIR *DirectoryPointer;DIR *opendir64 ( DirectoryName)
const char *DirectoryName;
struct dirent64 *readdir64 ( DirectoryPointer)
DIR64 *DirectoryPointer;
offset_t telldir64(DirectoryPointer)
DIR64 *DirectoryPointer;void seekdir64(DirectoryPointer,Location)
DIR64 *DirectoryPointer;
offset_t Location;void rewinddir64 (DirectoryPointer)
DIR64 *DirectoryPointer;int closedir64 (DirectoryPointer)
DIR64 *DirectoryPointer;DIR *fdopendir(fd);
int fd;The opendir subroutine opens the directory designated by the DirectoryName parameter and associates a directory stream with it.
The opendir subroutine also returns a pointer to identify the directory stream in subsequent operations. The null pointer is returned when the directory named by the DirectoryName parameter cannot be accessed or when not enough memory is available to hold the entire stream. A successful call to any of the exec (exec, execl, execle, execlp, execv, execve, execvp, exect, or fexecve Subroutine) functions closes any directory streams opened in the calling process.
The fdopendir() function is equivalent to the opendir() function, except that the directory is specified by a file descriptor rather than by a name. The file offset associated with the file descriptor at the time of the call, determines the entries that are returned.
Upon the successful return from fdopendir(), 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(), or rewinddir(), the behavior is undefined. Upon calling closedir() the file descriptor is closed.
The readdir subroutine returns a pointer to the next directory entry. The readdir subroutine returns entries for . (dot) and .. (dot dot), if present, but never returns an invalid entry (with d_ino set to 0). When it reaches the end of the directory, or when it detects an invalid seekdir operation, the readdir subroutine returns the null value. The returned pointer designates data that may be overwritten by another call to the readdir subroutine on the same directory stream. A call to the readdir subroutine on a different directory stream does not overwrite this data. The readdir subroutine marks the st_atime field of the directory for update each time the directory is actually read.
The telldir subroutine returns the current location associated with the specified directory stream.
The seekdir subroutine sets the position of the next readdir subroutine operation on the directory stream. An attempt to seek an invalid location causes the readdir subroutine to return the null value the next time it is called. The position should be that returned by a previous telldir subroutine call.
The rewinddir subroutine resets the position of the specified directory stream to the beginning of the directory.
The closedir subroutine closes a directory stream and frees the structure associated with the DirectoryPointer parameter. If the closedir subroutine is called for a directory that is already closed, the behavior is undefined. To prevent this, always initialize the DirectoryPointer parameter to null after closure.
If you use the fork (fork, f_fork, or vfork Subroutine) subroutine to create a new process from an existing one, either the parent or the child (but not both) may continue processing the directory stream using the readdir, rewinddir, or seekdir subroutine.
The readdir64 subroutine is similar to the readdir subroutine except that it returns a pointer to an object of type struct dirent64.
The telldir64 subroutine is similar to the telldir subroutine except that it returns the current directory location in an offset_t format.
The seekdir64 subroutine is similar to the seekdir subroutine except that the Location parameter is set in the format of offset_t.
The rewinddir64 subroutine resets the position of the specified directory stream (obtained by the opendir64 subroutine) to the beginning of the directory.
| Item | Description |
|---|---|
| DirectoryName | Names the directory. |
| DirectoryPointer | Points to the DIR or DIR64 structure of an open directory. |
| Location | Specifies the offset of an entry relative to the start of the directory. |
On successful completion, the opendir, and fdopendir subroutines returns a pointer to an object of type DIR, and the opendir64 subroutine returns a pointer to an object of type DIR64. Otherwise, a null value is returned and the errno global variable is set to indicate the error.
On successful completion, the readdir subroutine returns a pointer to an object of type struct dirent, and the readdir64 subroutine returns a pointer to an object of type struct dirent64. Otherwise, a null value is returned and the errno global variable is set to indicate the error. When the end of the directory is encountered, a null value is returned and the errno global variable is not changed by this function call.
On successful completion, the telldir or telldir64 subroutine returns the current location associated with the specified directory stream. Otherwise, a null value is returned.
On successful completion, the closedir or closedir64 subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.
If the opendir subroutine is unsuccessful, it returns a null value and sets the errno global variable to one of the following values:
| Item | Description |
|---|---|
| EACCES | Indicates that search permission is denied for any component of the DirectoryName parameter, or read permission is denied for the DirectoryName parameter. |
| ENAMETOOLONG | Indicates that the length of the DirectoryName parameter argument exceeds the PATH_MAX value, or a path-name component is longer than the NAME_MAX value while the POSIX_NO_TRUNC value is in effect. |
| ENOENT | Indicates that the named directory does not exist. |
| ENOTDIR | Indicates that a component of the DirectoryName parameter is not a directory. |
| EMFILE | Indicates that too many file descriptors are currently open for the process. |
| ENFILE | Indicates that too many file descriptors are currently open in the system. |
If the readdir or readdir64 subroutine is unsuccessful, it returns a null value and sets the errno global variable to the following value:
| Item | Description |
|---|---|
| EBADF | Indicates that the DirectoryPointer parameter argument does not refer to an open directory stream. |
If the closedir or closedir64 subroutine is unsuccessful, it returns a value of -1 and sets the errno global variable to the following value:
| Item | Description |
|---|---|
| EBADF | Indicates that the DirectoryPointer parameter argument does not refer to an open directory stream. |
If the fdopendir subroutine is unsuccessful, it returns a null value and sets the errno global variable to one of the following values:
| Item | Description |
|---|---|
| EBADF | Indicates that the fd argument is not a valid file descriptor open for reading. |
| ENOTDIR | Indicates that the descriptor fd is not associated with a directory. |
To search a directory for the entry name:
len = strlen(name);
DirectoryPointer = opendir(".");
for (dp = readdir(DirectoryPointer); dp != NULL; dp =
readdir(DirectoryPointer))
if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
closedir(DirectoryPointer);
DirectoryPointer=NULL //To prevent multiple closure
return FOUND;
}
closedir(DirectoryPointer);
DirectoryPointer=NULL //To prevent multiple closure