readdir(3p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

READDIR(3P)             POSIX Programmer's Manual            READDIR(3P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The
       Linux implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior),
       or the interface may not be implemented on Linux.

NAME         top

       readdir, readdir_r — read a directory

SYNOPSIS         top

       #include <dirent.h>

       struct dirent *readdir(DIR *dirp);
       int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
           struct dirent **restrict result);

DESCRIPTION         top

       The type DIR, which is defined in the <dirent.h> header,
       represents a directory stream, which is an ordered sequence of
       all the directory entries in a particular directory. Directory
       entries represent files; files may be removed from a directory or
       added to a directory asynchronously to the operation of
       readdir().

       The readdir() function shall return a pointer to a structure
       representing the directory entry at the current position in the
       directory stream specified by the argument dirp, and position the
       directory stream at the next entry. It shall return a null
       pointer upon reaching the end of the directory stream. The
       structure dirent defined in the <dirent.h> header describes a
       directory entry. The value of the structure's d_ino member shall
       be set to the file serial number of the file named by the d_name
       member. If the d_name member names a symbolic link, the value of
       the d_ino member shall be set to the file serial number of the
       symbolic link itself.

       The readdir() function shall not return directory entries
       containing empty names. If entries for dot or dot-dot exist, one
       entry shall be returned for dot and one entry shall be returned
       for dot-dot; otherwise, they shall not be returned.

       The application shall not modify the structure to which the
       return value of readdir() points, nor any storage areas pointed
       to by pointers within the structure. The returned pointer, and
       pointers within the structure, might be invalidated or the
       structure or the storage areas might be overwritten by a
       subsequent call to readdir() on the same directory stream. They
       shall not be affected by a call to readdir() on a different
       directory stream. The returned pointer, and pointers within the
       structure, might also be invalidated if the calling thread is
       terminated.

       If a file is removed from or added to the directory after the
       most recent call to opendir() or rewinddir(), whether a
       subsequent call to readdir() returns an entry for that file is
       unspecified.

       The readdir() function may buffer several directory entries per
       actual read operation; readdir() shall mark for update the last
       data access timestamp of the directory each time the directory is
       actually read.

       After a call to fork(), either the parent or child (but not both)
       may continue processing the directory stream using readdir(),
       rewinddir(), or seekdir().  If both the parent and child
       processes use these functions, the result is undefined.

       The readdir() function need not be thread-safe.

       Applications wishing to check for error situations should set
       errno to 0 before calling readdir().  If errno is set to non-zero
       on return, an error occurred.

       The readdir_r() function shall initialize the dirent structure
       referenced by entry to represent the directory entry at the
       current position in the directory stream referred to by dirp,
       store a pointer to this structure at the location referenced by
       result, and position the directory stream at the next entry.

       The storage pointed to by entry shall be large enough for a
       dirent with an array of char d_name members containing at least
       {NAME_MAX}+1 elements.

       Upon successful return, the pointer returned at *result shall
       have the same value as the argument entry.  Upon reaching the end
       of the directory stream, this pointer shall have the value NULL.

       The readdir_r() function shall not return directory entries
       containing empty names.

       If a file is removed from or added to the directory after the
       most recent call to opendir() or rewinddir(), whether a
       subsequent call to readdir_r() returns an entry for that file is
       unspecified.

       The readdir_r() function may buffer several directory entries per
       actual read operation; readdir_r() shall mark for update the last
       data access timestamp of the directory each time the directory is
       actually read.

RETURN VALUE         top

       Upon successful completion, readdir() shall return a pointer to
       an object of type struct dirent.  When an error is encountered, a
       null pointer shall be returned and errno shall be set to indicate
       the error. When the end of the directory is encountered, a null
       pointer shall be returned and errno is not changed.

       If successful, the readdir_r() function shall return zero;
       otherwise, an error number shall be returned to indicate the
       error.

ERRORS         top

       These functions shall fail if:

       EOVERFLOW
              One of the values in the structure to be returned cannot
              be represented correctly.

       These functions may fail if:

       EBADF  The dirp argument does not refer to an open directory
              stream.

       ENOENT The current position of the directory stream is invalid.

       The following sections are informative.

EXAMPLES         top

       The following sample program searches the current directory for
       each of the arguments supplied on the command line.

           #include <dirent.h>
           #include <errno.h>
           #include <stdio.h>
           #include <string.h>

           static void lookup(const char *arg)
           {
               DIR *dirp;
               struct dirent *dp;

               if ((dirp = opendir(".")) == NULL) {
                   perror("couldn't open '.'");
                   return;
               }

               do {
                   errno = 0;
                   if ((dp = readdir(dirp)) != NULL) {
                       if (strcmp(dp->d_name, arg) != 0)
                           continue;

                       (void) printf("found %s\n", arg);
                       (void) closedir(dirp);
                           return;

                   }
               } while (dp != NULL);

               if (errno != 0)
                   perror("error reading directory");
               else
                   (void) printf("failed to find %s\n", arg);
               (void) closedir(dirp);
               return;
           }

           int main(int argc, char *argv[])
           {
               int i;
               for (i = 1; i < argc; i++)
                   lookup(argv[i]);
               return (0);
           }

APPLICATION USAGE         top

       The readdir() function should be used in conjunction with
       opendir(), closedir(), and rewinddir() to examine the contents of
       the directory.

       The readdir_r() function is thread-safe and shall return values
       in a user-supplied buffer instead of possibly using a static data
       area that may be overwritten by each call.

RATIONALE         top

       The returned value of readdir() merely represents a directory
       entry. No equivalence should be inferred.

       Historical implementations of readdir() obtain multiple directory
       entries on a single read operation, which permits subsequent
       readdir() operations to operate from the buffered information.
       Any wording that required each successful readdir() operation to
       mark the directory last data access timestamp for update would
       disallow such historical performance-oriented implementations.

       When returning a directory entry for the root of a mounted file
       system, some historical implementations of readdir() returned the
       file serial number of the underlying mount point, rather than of
       the root of the mounted file system. This behavior is considered
       to be a bug, since the underlying file serial number has no
       significance to applications.

       Since readdir() returns NULL when it detects an error and when
       the end of the directory is encountered, an application that
       needs to tell the difference must set errno to zero before the
       call and check it if NULL is returned.  Since the function must
       not change errno in the second case and must set it to a non-zero
       value in the first case, a zero errno after a call returning NULL
       indicates end-of-directory; otherwise, an error.

       Routines to deal with this problem more directly were proposed:

           int derror (dirp)
           DIR *dirp;

           void clearderr (dirp)
           DIR *dirp;

       The first would indicate whether an error had occurred, and the
       second would clear the error indication. The simpler method
       involving errno was adopted instead by requiring that readdir()
       not change errno when end-of-directory is encountered.

       An error or signal indicating that a directory has changed while
       open was considered but rejected.

       The thread-safe version of the directory reading function returns
       values in a user-supplied buffer instead of possibly using a
       static data area that may be overwritten by each call. Either the
       {NAME_MAX} compile-time constant or the corresponding pathconf()
       option can be used to determine the maximum sizes of returned
       pathnames.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       closedir(3p), dirfd(3p), exec(1p), fdopendir(3p), fstatat(3p),
       rewinddir(3p), symlink(3p)

       The Base Definitions volume of POSIX.1‐2017, dirent.h(0p),
       sys_types.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic
       form from IEEE Std 1003.1-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  In the event of any
       discrepancy between this version and the original IEEE and The
       Open Group Standard, the original IEEE and The Open Group
       Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page
       are most likely to have been introduced during the conversion of
       the source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group               2017                       READDIR(3P)

Pages that refer to this page: dirent.h(0p)dirfd(3p)exec(3p)fdopendir(3p)glob(3p)nftw(3p)rewinddir(3p)seekdir(3p)telldir(3p)