readdir()

get information about the next matching filename

Synopsis:

#include <dirent.h>
struct dirent *readdir( DIR *dirp );

The readdir() function obtains information about the next matching file name from the argument dirp. The argument dirp is the value returned from the opendir function. The readdir() function can be called repeatedly to obtain the list of file names contained in the directory specified by the pathname given to opendir(). The function closedir() must be called to close the directory and free the memory allocated by opendir().

The file <dirent.h> contains definitions for the structure dirent and the DIR type.

In QNX, the dirent structure contains a stat structure in the d_stat member. To speed up applications, which often want both the name and the stat data, a resource manager may return the stat information at the same time the readdir() function is called.

However, since the support of this feature is left to the discretion of various resource managers, every program must use the following test to determine if the d_stat member contains valid data:

d_stat.st_status & _FILE_USED

This test must be performed after every readdir() call.

If the d_stat member doesn't contain valid data, and the data is needed then the application should construct the file's pathname and call stat() or lstat(), as appropriate.

The result of using a directory stream after one of the exec... or spawn... family of functions is undefined. After a call to the fork() function, either the parent or the child (but not both) may continue processing the directory stream, using readdir() or rewinddir(), or both. If both the parent and child processes use these functions, the result is undefined. Either or both processes may use closedir().

Returns:

When successful, readdir() returns a pointer to an object of type struct dirent.
When an error occurs, readdir() returns the value NULL, and errno is set to indicate the error.
When the end of the directory is encountered, readdir() returns the value NULL, and errno is unchanged.

Errors:

EBADF: The argument dirp does not refer to an open directory stream.

Examples:

To get a list of files contained in the directory /home/fred of your node:

#include <stdio.h>
#include <dirent.h>

void main()
  {
    DIR *dirp;
    struct dirent *direntp;

    dirp = opendir( "/home/fred" );
    if( dirp != NULL ) {
      for(;;) {
        direntp = readdir( dirp );
        if( direntp == NULL ) break;
        printf( "%s\n", direntp->d_name );
      }
      closedir( dirp );
    }
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes