Reading and Closing a Directory Stream

This section describes how to read directory entries from a directory stream, and how to close the stream when you are done with it. All the symbols are declared in the header file `dirent.h'.

Function: struct dirent * readdir (DIR *dirstream)

This function reads the next entry from the directory. It normally returns a pointer to a structure containing information about the file. This structure is statically allocated and can be rewritten by a subsequent call.

Portability Note: On some systems, readdir may not return entries for `.' and `..', even though these are always valid file names in any directory. See section File Name Resolution.

If there are no more entries in the directory or an error is detected, readdir returns a null pointer. The following errno error conditions are defined for this function:

EBADF

The dirstream argument is not valid.

readdir is not thread safe. Multiple threads using readdir on the same dirstream may overwrite the return value. Use readdir_r when this is critical.

Function: int readdir_r (DIR *dirstream, struct dirent *entry, struct dirent **result)

This function is the reentrant version of readdir. Like readdir it returns the next entry from the directory. But to prevent conflicts for simultaneously running threads the result is not stored in some internal memory. Instead the argument entry has to point to a place where the result is stored.

The return value is 0 in case the next entry was read successfully. In this case a pointer to the result is returned in *result. It is not required that *result is the same as entry. If something goes wrong while executing readdir_r the function returns -1. The errno variable is set like described for readdir.

Portability Note: On some systems, readdir_r may not return a terminated string as the file name even if no d_reclen element is available in struct dirent and the file name as the maximal allowed size. Modern systems all have the d_reclen field and on old systems multi threading is not critical. In any case, there is no such problem with the readdir function so that even on systems without d_reclen field one could use multiple threads by using external locking.

Function: int closedir (DIR *dirstream)

This function closes the directory stream dirstream. It returns 0 on success and -1 on failure.

The following errno error conditions are defined for this function:

EBADF

The dirstream argument is not valid.

Go to the first, previous, next, last section, table of contents.