opendir()

open a directory file

Synopsis:

#include <dirent.h>
DIR *opendir( const char *dirname );

The opendir() function is used in conjunction with the functions readdir() and closedir() to obtain the list of file names contained in the directory specified by dirname. The path indicated by dirname can be either relative to the current working directory, or it can be an absolute path name.

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.

More than one directory can be read at the same time using the opendir(), readdir(), rewinddir() and closedir() functions.

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:

A pointer to a DIR structure if successful. This pointer is required for subsequent calls to readdir() to retrieve the file names specified by dirname.

The opendir() function returns NULL if dirname is not a valid pathname.

Errors:

EACCES: Search permission is denied for a component of dirname, or read permission is denied for dirname.
EBADFSYS: While attempting to open the named directory, a component of the path prefix was found to be corrupted. You'll need to invoke appropriate systems-administration procedures to correct this situation before proceeding.
EINTR: The opendir() operation was interrupted by a signal.
EMFILE: Too many file descriptors are currently in use by this process.
ELOOP: Too many levels of symbolic loops (or prefix aliases): an infinite loop is assumed after SYMLOOP_MAX symbolic links or prefixes are encountered.
ENAMETOOLONG: The length of the argument dirname exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENFILE: Too many files are currently open in the system.
ENOENT: The named directory doesn't exist.
ENOMEM: Not enough memory
ENOTDIR: A component of dirname is not a directory.

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 ) {
      perror( "" );
    } else {
      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