Provided by: manpages-posix-dev_2013a-2_all bug

PROLOG

       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

       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.

       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‐2008, <dirent.h>, <sys_types.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/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 .