NAME
readdir, readdirr - read a directory SYNOPSIS
#include
struct dirent *readdir(DIR *dirp); int readdirr(DIR *dirp, struct dirent *entry, struct dirent **result); Feature Test Macro Requirements for glibc (see featuretestmacros(7)): readdirr(): POSIXCSOURCE >= 1 || XOPENSOURCE || BSDSOURCE || SVIDSOURCE || POSIXSOURCE DESCRIPTION The readdir() function returns a pointer to a dirent structure repre‐ senting the next directory entry in the directory stream pointed to by dirp. It returns NULL on reaching the end of the directory stream or if an error occurred. On Linux, the dirent structure is defined as follows: struct dirent { inot dino; /* inode number */ offt doff; /* not an offset; see NOTES */ unsigned short dreclen; /* length of this record */ unsigned char dtype; /* type of file; not supported by all file system types */ char dname[256]; /* filename */ }; The only fields in the dirent structure that are mandated by POSIX.1 are: dname[], of unspecified size, with at most NAMEMAX characters preceding the terminating null byte ('\0'); and (as an XSI extension) dino. The other fields are unstandardized, and not present on all systems; see NOTES below for some further details. The data returned by readdir() may be overwritten by subsequent calls to readdir() for the same directory stream. The readdirr() function is a reentrant version of readdir(). It reads the next directory entry from the directory stream dirp, and returns it in the caller-allocated buffer pointed to by entry. (See NOTES for information on allocating this buffer.) A pointer to the returned item is placed in *result; if the end of the directory stream was encoun‐ tered, then NULL is instead returned in *result. RETURN VALUE On success, readdir() returns a pointer to a dirent structure. (This structure may be statically allocated; do not attempt to free(3) it.) If the end of the directory stream is reached, NULL is returned and errno is not changed. If an error occurs, NULL is returned and errno is set appropriately. The readdirr() function returns 0 on success. On error, it returns a positive error number (listed under ERRORS). If the end of the direc‐ tory stream is reached, readdirr() returns 0, and returns NULL in *result. ERRORS EBADF Invalid directory stream descriptor dirp. ATTRIBUTES For an explanation of the terms used in this section, see attributes(7). ┌────────────┬───────────────┬──────────────────────────┐ │Interface │ Attribute │ Value │ ├────────────┼───────────────┼──────────────────────────┤
│readdir() │ Thread safety │ MT-Unsafe race:dirstream │ ├────────────┼───────────────┼──────────────────────────┤
│readdirr() │ Thread safety │ MT-Safe │ └────────────┴───────────────┴──────────────────────────┘ CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001. NOTES
Only the fields dname and dino are specified in POSIX.1-2001. The remaining fields are available on many, but not all systems. Under glibc, programs can check for the availability of the fields not defined in POSIX.1 by testing whether the macros DIRENTHAVEDNAMLEN, DIRENTHAVEDRECLEN, DIRENTHAVEDOFF, or DIRENTHAVEDTYPE are defined. The value returned in doff is the same as would be returned by calling telldir(3) at the current position in the directory stream. Be aware that despite its type and name, the doff field is seldom any kind of directory offset on modern file systems. Applications should treat this field as an opaque value, making no assumptions about its con‐ tents; see also telldir(3). Other than Linux, the dtype field is available mainly only on BSD sys‐ tems. This field makes it possible to avoid the expense of calling lstat(2) if further actions depend on the type of the file. If the BSDSOURCE feature test macro is defined, then glibc defines the fol‐ lowing macro constants for the value returned in dtype: DTBLK This is a block device. DTCHR This is a character device. DTDIR This is a directory. DTFIFO This is a named pipe (FIFO). DTLNK This is a symbolic link. DTREG This is a regular file. DTSOCK This is a UNIX domain socket. DTUNKNOWN The file type is unknown. If the file type could not be determined, the value DTUNKNOWN is returned in dtype. Currently, only some file systems (among them: Btrfs, ext2, ext3, and ext4) have full support for returning the file type in dtype. All applications must properly handle a return of DTUNKNOWN. Since POSIX.1 does not specify the size of the dname field, and other nonstandard fields may precede that field within the dirent structure, portable applications that use readdirr() should allocate the buffer whose address is passed in entry as follows: namemax = pathconf(dirpath, PCNAMEMAX);
if (namemax == -1) /* Limit not defined, or error */ namemax = 255; /* Take a guess */ len = offsetof(struct dirent, dname) + namemax + 1; entryp = malloc(len); (POSIX.1 requires that dname is the last field in a struct dirent.) SEE ALSO getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), rewinddir(3), scandir(3), seekdir(3), telldir(3) COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
2013-06-21 READDIR(3)