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



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

NAME
       readdir, readdir_r -- read a directory

SYNOPSIS
       #include <dirent.h>

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

DESCRIPTION
       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
       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
       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
       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
       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
       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
       None.

SEE ALSO
       closedir(), dirfd(), exec, fdopendir(), fstatat(), rewinddir(),
       symlink()

       The Base Definitions volume of POSIX.1-2017, <dirent.h>, <sys_types.h>

COPYRIGHT
       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(3)
