readdir(3C)




NAME

     readdir, readdir_r - read directory


SYNOPSIS

     #include <sys/types.h>
     #include <dirent.h>

     struct dirent *readdir(DIR *dirp);

     struct dirent *readdir_r(DIR *dirp, struct dirent *entry);

  POSIX
     cc [ flag ... ] file ... -D_POSIX_PTHREAD_SEMANTICS [ library ... ]

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


DESCRIPTION

     The type DIR, which is defined  in  the  header  <dirent.h>,
     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() and readdir_r().

  readdir()
     The readdir() function returns  a  pointer  to  a  structure
     representing  the directory entry at the current position in
     the directory stream specified by  the  argument  dirp,  and
     positions the directory stream at the next entry. It returns
     a null pointer  upon  reaching  the  end  of  the  directory
     stream.  The  structure  dirent  defined  by  the <dirent.h>
     header describes a directory entry.

     If entries for . (dot) or .. (dot-dot) exist, one entry will
     be  returned for dot and one entry will be returned for dot-
     dot; otherwise they will not be returned.

     The pointer returned by readdir() points to data  which  may
     be  overwritten  by  another  call  to readdir() on the same
     directory stream. This data is not  overwritten  by  another
     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(3C)  or  rewinddir(3C),
     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() marks for update the
     st_atime field of the directory each time the  directory  is
     actually read.
     After a call to fork(2), either the parent or child (but not
     both)  may  continue  processing  the directory stream using
     readdir(), rewinddir() or seekdir(3C). If  both  the  parent
     and child processes use these functions, the result is unde-
     fined.

     If the entry names a symbolic link, the value of  the  d_ino
     member is unspecified.

  readdir_r()
     The readdir_r() function initializes  the  dirent  structure
     referenced  by entry to represent the directory entry at the
     current position in the  directory  stream  referred  to  by
     dirp,  and positions the directory stream at the next entry.

     The caller must allocate storage pointed to by entry  to  be
     large  enough  for  a dirent structure with an array of char
     d_name  member  containing  at  least  NAME_MAX  (that   is,
     pathconf(_PC_NAME_MAX))  plus  one elements. _PC_NAME_MAX is
     defined in  <unistd.h>.

     The readdir_r() function will not return  directory  entries
     containing  empty  names.  It is unspecified whether entries
     are returned for . (dot) or .. (dot-dot).

     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; the readdir_r() function
     marks for update the st_atime field of  the  directory  each
     time the directory is actually read.

     The POSIX version  (see  standards(5))  of  the  readdir_r()
     function  initializes  the structure referenced by entry and
     stores a pointer to this structure in result. On  successful
     return,  the pointer returned at *result will the same value
     as the argument entry. Upon reaching the end of  the  direc-
     tory stream, this pointer will have the value NULL.


RETURN VALUES

     Upon successful completion, readdir() and readdir_r() return
     a  pointer to an object of type struct dirent. When an error
     is encountered, a null pointer is returned and errno is  set
     to  indicate  the  error.   When the end of the directory is
     encountered, a null pointer is returned  and  errno  is  not
     changed.  The  POSIX readdir_r() returns  0 if successful or
     an error number to indicate failure.


ERRORS

     The readdir() function will fail if:

     EOVERFLOW
           One of the values in the structure to be returned can-
           not be represented correctly.

     The readdir() and readdir_r() functions will fail if:

     EBADF The file descriptor determined by the DIR stream is no
           longer  valid. This results if the DIR stream has been
           closed.

     ENOENT
           The current file pointer  for  the  directory  is  not
           located at a valid entry.

     The readdir() and readdir_r() 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.


USAGE

     The readdir() function should be used  in  conjunction  with
     opendir(),  closedir(),  and rewinddir() to examine the con-
     tents of the directory.  As readdir() returns a null pointer
     both  at  the end of the directory and on error, an applica-
     tion wishing to check for error situations should set  errno
     to  0,  then  call  readdir(), then check errno and if it is
     non-zero, assume an error has occurred.

     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() and readdir_r()  functions  have  transitional
     interfaces for 64-bit file offsets.  See lf64(5).


EXAMPLES

     Example 1: Search the current directory for the entry name.

     The following sample code will search the current  directory
     for the entry name:

     dirp = opendir(".");

     while (dirp) {
         errno = 0;
         if ((dp = readdir(dirp)) != NULL) {
             if (strcmp(dp->d_name, name) == 0) {
                 closedir(dirp);
                 return FOUND;
             }
         } else {
             if (errno == 0) {
                 closedir(dirp);
                 return NOT_FOUND;
             }
             closedir(dirp);
             return READ_ERROR;
         }
     }

     return OPEN_ERROR;


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below.            |
    |_____________________________|_____________________________|


NOTES

     When compiling multithreaded programs, see  Intro(3),  Notes
     On Multithreaded Applications.

     The readdir() function is unsafe in  multithreaded  applica-
     tions.  The readdir_r() function is safe, and should be used
     instead.

     Solaris 2.4 and  earlier  releases  provided  a  readdir_r()
     interface  as  specified  in  POSIX.1c  Draft  6.  The final
     POSIX.1c standard changed the interface as described  above.
     Support  for  the Draft 6 interface is provided for compati-
     bility only and may not be  supported  in  future  releases.
     New applications and libraries should use the POSIX standard
     interface.

     For       POSIX.1c-compliant        applications,        the
     _POSIX_PTHREAD_SEMANTICS  and _REENTRANT flags are automati-
     cally turned on by defining the _POSIX_C_SOURCE flag with  a
     value >= 199506L.


SEE ALSO

     fork(2),  lstat(2),  symlink(2),   Intro(3),   closedir(3C),
     opendir(3C),   rewinddir(3C),   seekdir(3C),  attributes(5),
     lf64(5), standards(5)


Man(1) output converted with man2html