Next: Simple Directory Lister, Previous: Opening a Directory, Up: Accessing Directories
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.
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
readdirmay not return entries for . and .., even though these are always valid file names in any directory. See File Name Resolution.If there are no more entries in the directory or an error is detected,
readdirreturns a null pointer. The followingerrnoerror conditions are defined for this function:
EBADF- The dirstream argument is not valid.
readdiris not thread safe. Multiple threads usingreaddiron the same dirstream may overwrite the return value. Usereaddir_rwhen this is critical.
This function is the reentrant version of
readdir. Likereaddirit returns the next entry from the directory. But to prevent conflicts between simultaneously running threads the result is not stored in statically allocated memory. Instead the argument entry points to a place to store the result.Normally
readdir_rreturns zero and sets*result to entry. If there are no more entries in the directory or an error is detected,readdir_rsets*result to a null pointer and returns a nonzero error code, also stored inerrno, as described forreaddir.Portability Note: On some systems
readdir_rmay not return a NUL terminated string for the file name, even when there is nod_reclenfield instruct direntand the file name is the maximum allowed size. Modern systems all have thed_reclenfield, and on old systems multi-threading is not critical. In any case there is no such problem with thereaddirfunction, so that even on systems without thed_reclenmember one could use multiple threads by using external locking.It is also important to look at the definition of the
struct direnttype. Simply passing a pointer to an object of this type for the second parameter ofreaddir_rmight not be enough. Some systems don't define thed_nameelement sufficiently long. In this case the user has to provide additional space. There must be room for at leastNAME_MAX + 1characters in thed_namearray. Code to callreaddir_rcould look like this:union { struct dirent d; char b[offsetof (struct dirent, d_name) + NAME_MAX + 1]; } u; if (readdir_r (dir, &u.d, &res) == 0) ...
To support large filesystems on 32-bit machines there are LFS variants of the last two functions.
The
readdir64function is just like thereaddirfunction except that it returns a pointer to a record of typestruct dirent64. Some of the members of this data type (notablyd_ino) might have a different size to allow large filesystems.In all other aspects this function is equivalent to
readdir.
The
readdir64_rfunction is equivalent to thereaddir_rfunction except that it takes parameters of base typestruct dirent64instead ofstruct direntin the second and third position. The same precautions mentioned in the documentation ofreaddir_ralso apply here.