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



PPRROOLLOOGG
       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.

NNAAMMEE
       readdir, readdir_r -- read a directory

SSYYNNOOPPSSIISS
       #include <dirent.h>

       struct dirent *readdir(DIR *_d_i_r_p);
       int readdir_r(DIR *restrict _d_i_r_p, struct dirent *restrict _e_n_t_r_y,
           struct dirent **restrict _r_e_s_u_l_t);

DDEESSCCRRIIPPTTIIOONN
       The type DDIIRR, which is defined in the _<_d_i_r_e_n_t_._h_> header, represents a
       _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m, 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 _r_e_a_d_d_i_r().

       The _r_e_a_d_d_i_r() function shall return a pointer to a structure
       representing the directory entry at the current position in the
       directory stream specified by the argument _d_i_r_p, 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 ddiirreenntt defined
       in the _<_d_i_r_e_n_t_._h_> header describes a directory entry. The value of the
       structure's _d___i_n_o member shall be set to the file serial number of the
       file named by the _d___n_a_m_e member. If the _d___n_a_m_e member names a symbolic
       link, the value of the _d___i_n_o member shall be set to the file serial
       number of the symbolic link itself.

       The _r_e_a_d_d_i_r() 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 _r_e_a_d_d_i_r() 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 _r_e_a_d_d_i_r() on the same
       directory stream. They shall not be affected by a call to _r_e_a_d_d_i_r() 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 _o_p_e_n_d_i_r() or _r_e_w_i_n_d_d_i_r(), whether a subsequent call to
       _r_e_a_d_d_i_r() returns an entry for that file is unspecified.

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

       After a call to _f_o_r_k(), either the parent or child (but not both) may
       continue processing the directory stream using _r_e_a_d_d_i_r(), _r_e_w_i_n_d_d_i_r(),
       or _s_e_e_k_d_i_r().  If both the parent and child processes use these
       functions, the result is undefined.

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

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

       The _r_e_a_d_d_i_r___r() function shall initialize the ddiirreenntt structure
       referenced by _e_n_t_r_y to represent the directory entry at the current
       position in the directory stream referred to by _d_i_r_p, store a pointer
       to this structure at the location referenced by _r_e_s_u_l_t, and position
       the directory stream at the next entry.

       The storage pointed to by _e_n_t_r_y shall be large enough for a ddiirreenntt with
       an array of cchhaarr _d___n_a_m_e members containing at least {NAME_MAX}+1
       elements.

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

       The _r_e_a_d_d_i_r___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 _o_p_e_n_d_i_r() or _r_e_w_i_n_d_d_i_r(), whether a subsequent call to
       _r_e_a_d_d_i_r___r() returns an entry for that file is unspecified.

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

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _r_e_a_d_d_i_r() shall return a pointer to an
       object of type ssttrruucctt ddiirreenntt.  When an error is encountered, a null
       pointer shall be returned and _e_r_r_n_o shall be set to indicate the error.
       When the end of the directory is encountered, a null pointer shall be
       returned and _e_r_r_n_o is not changed.

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

EERRRROORRSS
       These functions shall fail if:

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

       These functions may fail if:

       EEBBAADDFF  The _d_i_r_p argument does not refer to an open directory stream.

       EENNOOEENNTT The current position of the directory stream is invalid.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       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);
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _r_e_a_d_d_i_r() function should be used in conjunction with _o_p_e_n_d_i_r(),
       _c_l_o_s_e_d_i_r(), and _r_e_w_i_n_d_d_i_r() to examine the contents of the directory.

       The _r_e_a_d_d_i_r___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.

RRAATTIIOONNAALLEE
       The returned value of _r_e_a_d_d_i_r() merely _r_e_p_r_e_s_e_n_t_s a directory entry. No
       equivalence should be inferred.

       Historical implementations of _r_e_a_d_d_i_r() obtain multiple directory
       entries on a single read operation, which permits subsequent _r_e_a_d_d_i_r()
       operations to operate from the buffered information. Any wording that
       required each successful _r_e_a_d_d_i_r() 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 _r_e_a_d_d_i_r() 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 _r_e_a_d_d_i_r() 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 _e_r_r_n_o to zero before the call and check it if NULL
       is returned.  Since the function must not change _e_r_r_n_o in the second
       case and must set it to a non-zero value in the first case, a zero
       _e_r_r_n_o after a call returning NULL indicates end-of-directory;
       otherwise, an error.

       Routines to deal with this problem more directly were proposed:


           int derror (_d_i_r_p)
           DIR *_d_i_r_p;

           void clearderr (_d_i_r_p)
           DIR *_d_i_r_p;

       The first would indicate whether an error had occurred, and the second
       would clear the error indication. The simpler method involving _e_r_r_n_o
       was adopted instead by requiring that _r_e_a_d_d_i_r() not change _e_r_r_n_o 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 _p_a_t_h_c_o_n_f() option can be
       used to determine the maximum sizes of returned pathnames.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_l_o_s_e_d_i_r(), _d_i_r_f_d(), _e_x_e_c, _f_d_o_p_e_n_d_i_r(), _f_s_t_a_t_a_t(), _r_e_w_i_n_d_d_i_r(),
       _s_y_m_l_i_n_k()

       The Base Definitions volume of POSIX.1-2017, <<ddiirreenntt..hh>>, <<ssyyss__ttyyppeess..hh>>

CCOOPPYYRRIIGGHHTT
       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)
