home   contributing   bugs   download   online pages  

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | NOTES | SEE ALSO | COLOPHON


READDIR(3)                    Linux Programmer's Manual                    READDIR(3)

NAME         top

       readdir, readdir_r - read a directory

SYNOPSIS         top

       #include <dirent.h>

       struct dirent *readdir(DIR *dir);

       int readdir_r(DIR *dir, struct dirent *entry, struct dirent **result);

DESCRIPTION         top

       The readdir() function returns a pointer to a dirent structure representing
       the next directory entry in the directory stream pointed to by dir.  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 {
               ino_t          d_ino;       /* inode number */
               off_t          d_off;       /* offset to the next dirent */
               unsigned short d_reclen;    /* length of this record */
               unsigned char  d_type;      /* type of file */
               char           d_name[256]; /* filename */
           };

       According to POSIX, the dirent structure contains a field char d_name[] of
       unspecified size, with at most NAME_MAX characters preceding the terminating
       null byte.  POSIX.1-2001 also documents the field ino_t d_ino as an XSI
       extension.  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 readdir_r() function is a reentrant version of readdir().  It reads the
       next directory entry from the directory stream dir, 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 encountered, then NULL is instead
       returned in *result.

RETURN VALUE         top

       The readdir() function returns a pointer to a dirent structure, or NULL if an
       error occurs or end of the directory stream is reached.  On error, errno is
       set appropriately.

       The readdir_r() function returns 0 on success.  On error, it returns a
       positive error number.  If the end of the directory stream is reached,
       readdir_r() returns 0, and returns NULL in *result.

ERRORS         top

       EBADF  Invalid directory stream descriptor dir.

CONFORMING TO         top

       SVr4, 4.3BSD, POSIX.1-2001.

NOTES         top

       Only the fields d_name and d_ino 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 _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN,
       _DIRENT_HAVE_D_OFF, or _DIRENT_HAVE_D_TYPE are defined.

       Other than Linux, the d_type field is available mainly only on BSD systems.
       This field makes it possible to avoid the expense of calling stat(2) if
       further actions depend on the type of the file.  If the _BSD_SOURCE feature
       test macro is defined, then glibc defines the following macro constants for
       the value returned in d_type:

       DT_BLK      This is a block device.

       DT_CHR      This is a character device.

       DT_DIR      This is a directory.

       DT_FIFO     This is a named pipe (FIFO).

       DT_LNK      This is a symbolic link.

       DT_REG      This is a regular file.

       DT_SOCK     This is a Unix domain socket.

       DT_UNKNOWN  The file type is unknown.

       If the file type could not be determined, the value DT_UNKNOWN is returned in
       d_type.

       Since POSIX.1 does not specify the size of the d_name field, and other non-
       standard fields may precede that field within the dirent structure, portable
       applications that use readdir_r() should allocate the buffer whose address is
       passed in entry as follows:

           len = offsetof(struct dirent, d_name) +
                     pathconf(dirpath, _PC_NAME_MAX) + 1
           entryp = malloc(len);

       (POSIX.1 requires that d_name is the last field in a struct dirent.)

SEE ALSO         top

       read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), rewinddir(3),
       scandir(3), seekdir(3), telldir(3), feature_test_macros(7)

COLOPHON         top

       This page is part of release 3.08 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/.

                                      2008-07-04                           READDIR(3)