directory(3c) manual page
NAME
directory, opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir - directory operations
SYNOPSIS
#include
<dirent.h>
DIR *opendir(const char *filename);
struct dirent *readdir(DIR *dirp);
struct dirent *readdir_r(DIR *dirp,struct dirent *res);
long telldir(DIR *dirp);
void seekdir(DIR *dirp, long loc);
void rewinddir(DIR *dirp);
int closedir(DIR *dirp);
MT-LEVEL
See the NOTES section.
DESCRIPTION
RETURN VALUES
-
opendir(), readdir(), and readdir_r() return NULL on failure and set
errno
to indicate the error.
- telldir(), seekdir(), and closedir() return -1 on failure and set
errno
to indicate the error.
ERRORS
-
opendir() will fail if one or more of the following are true:
- EACCES
- Read permission is denied on the specified directory.
- EFAULT
- filename points outside the allocated address space.
- ELOOP
- Too many symbolic links were encountered in translating filename.
- ENOTDIR
- A component of filename is not a directory.
- EMFILE
- The maximum number of file descriptors are currently open.
- ENFILE
- The system file table is full.
- ENAMETOOLONG
- The length of the filename argument exceeds {PATH_MAX}, or the length of a filename component exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
- ENOENT
- A component of filename does not exist or is a null pathname.
- EACCES
- A component of filename denies search permission.
-
readdir() and readdir_r() will fail if one or more of the following are true:
- EAGAIN
- Mandatory file/record locking was set,
O_NDELAY
or O_NONBLOCK
was set, and there was a blocking record lock.
- EAGAIN
- Total amount of system memory available when reading using raw I/O is temporarily insufficient.
- EAGAIN
- No data is waiting to be read on a file associated with a tty device and
O_NONBLOCK
was set.
- EAGAIN
- No message is waiting to be read on a stream and
O_NDELAY
or O_NONBLOCK
was set.
- EBADF
- The file descriptor determined by the DIR stream is no longer valid. This results if the DIR stream has been closed.
- EBADMSG
- Message waiting to be read on a stream is not a data message.
- EDEADLK
- The read() was going to go to sleep and cause a deadlock to occur.
- EFAULT
- buf points to an illegal address.
- EINTR
- A signal was caught during the read() or readv() function.
- EINVAL
- Attempted to read from a stream linked to a multiplexor.
- EIO
- A physical I/O error has occurred, or
the process is in a background process group and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the
SIGTTIN
signal or the process group of the process is orphaned.
- ENOENT
- The current file pointer for the directory is not located at a valid entry.
- ENOLCK
- The system record lock table was full, so the read() or readv() could not go to sleep until the blocking record lock was removed.
- ENOLINK
- fildes is on a remote machine and the link to that machine is no longer active.
- ENXIO
- The device associated with fildes is a block special or character special file and the value of the file pointer is out of range.
-
telldir(), seekdir(), and closedir() return 0 on success and will fail if one or more of the following are true:
- EBADF
- The file descriptor determined by the DIR stream is no longer valid. This results if the DIR stream has been closed.
EXAMPLES
Here is a sample program that prints the names of all the files in the current directory:
#include <stdio.h>
#include <dirent.h>
main() {
DIR *dirp;
struct dirent *direntp;
dirp = opendir( "." );
while ( (direntp = readdir( dirp )) != NULL )
(void)printf( "%s\n", direntp->d_name );
(void)closedir( dirp );
return (0);
}
SEE ALSO
getdents(2), dirent(4)
The readdir_r() interface is as proposed in the POSIX.4a Draft #6 document, and is subject to change to be compliant to the standard when it is accepted.
When compiling multi-thread applications, the _REENTRANT flag must be defined on the compile line. This flag should only be used in multi-thread applications.
readdir() is unsafe in multi-thread applications. readdir_r() is safe, and should be used instead. closedir(), directory(), opendir(), rewinddir(), seekdir(), and telldir() are safe in multi-thread applications.