# readdir

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


* * *