readdir, wreaddir

Go Up to dirent.h Index

Header File

dirent.h

Category

Directory Control Routines

Prototype

struct dirent *readdir(DIR *dirp);
struct wdirent *wreaddir(wDIR *dirp)

Description

Reads the current entry from a directory stream.

readdir is available on POSIX-compliant UNIX systems.

The readdir function reads the current directory entry in the directory stream pointed to by dirp. The directory stream is advanced to the next entry.

The readdir function returns a pointer to a dirent structure that is overwritten by each call to the function on the same directory stream. The structure is not overwritten by a readdir call on a different directory stream.

The dirent structure corresponds to a single directory entry. It is defined in dirent.h and contains (in addition to other non-accessible members) the following member:

char d_name[];

where d_name is an array of characters containing the null-terminated file name for the current directory entry. The size of the array is indeterminate; use strlen to determine the length of the file name.

All valid directory entries are returned, including subdirectories, "." and ".." entries, system files, hidden files, and volume labels. Unused or deleted directory entries are skipped.

A directory entry can be created or deleted while a directory stream is being read, but readdir might or might not return the affected directory entry. Rewinding the directory with rewinddir or reopening it with opendir ensures that readdir will reflect the current state of the directory.

The wreaddir function is the Unicode version of readdir. It uses the wdirent structure but otherwise is similar to readdir.

Return Value

On success, readdir returns a pointer to the current directory entry for the directory stream.

If the end of the directory has been reached, or dirp does not refer to an open directory stream, readdir returns NULL.

Example

#include <dirent.h>
void print_dir(wchar_t* dir_name)
{
  /* Open the directory and check for success */
  wDIR* dir = wopendir(dir_name);
  wdirent* ent;

  if (!dir)
    return;

  /* Navigate in the directory stream */
  while (ent = wreaddir(dir))
  {
    /* print the name of the entry */
    printf("%ls\n", ent->d_name);
  }
}

Portability

	POSIX	Win32	ANSI C	ANSI C++
readdir	+	+
wreaddir		+