readdir

Readdir is a function from the POSIX C library used to read directory entries from a directory stream. It is declared in dirent.h and works in conjunction with opendir, which opens a directory and returns a DIR pointer that represents the directory stream.

The function prototype is struct dirent *readdir(DIR *dirp). On each successful call, readdir returns a pointer to a dirent structure describing the next entry in the directory. When the end of the directory is reached, or an error occurs, it returns NULL. If NULL is returned due to end-of-directory, errno is not changed; if an error occurs, errno is set to indicate the error.

The dirent structure provides information about each entry. The most commonly used field is d_name, the null-terminated filename. Additional fields such as d_ino (inode number) and, on systems that support it, d_type (the entry’s type) may be present. The availability of d_type is filesystem-dependent; some filesystems do not provide it. Directory entries may include the special entries “.” and “..”.

Usage typically follows a loop pattern: open the directory with opendir, repeatedly call readdir to obtain each dirent, and finally close the stream with closedir. A common caveat is that the dirent data is stored in a buffer that may be overwritten by subsequent calls, so any needed information should be copied before the next readdir call.

Variants and portability notes: many systems offer readdir64 for large-file support, and some older code used readdir_r (a reentrant variant), though readdir_r is deprecated in favor of using separate DIR streams. For filtering or sorting entries, higher-level functions like scandir may be used.