Manual Pages for UNIX Operating System command usage for man readdir_r

Standard C Library Functions                          readdir(3C)



NAME
     readdir, readdir_r - read directory

SYNOPSIS
     #include 
     #include 

     struct dirent *readdir(DIR *dirp);


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


  Standard conforming
     cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

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


DESCRIPTION
     The type DIR, which is defined  in  the  header  ,
     represents  a directory stream, which is an ordered sequence
     of all the directory  entries  in  a  particular  directory.
     Directory entries represent files. Files can 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 
     header describes a directory entry.


     The readdir() function will  not  return  directory  entries
     containing  empty  names. 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 that can be
     overwritten  by another call to readdir() on the same direc-
     tory stream. These data are not overwritten by another  call
     to readdir() on a different directory stream.






SunOS 5.11          Last change: 26 Jun 2007                    1






Standard C Library Functions                          readdir(3C)



     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 can buffer several directory  entries
     per  actual read operation. It 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)  can  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()
     Unless the end of the directory stream has been  reached  or
     an  error occurred, the readdir_r() function initializes the
     dirent structure referenced by entry to represent the direc-
     tory  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(directory,   _PC_NAME_MAX))   plus   one  elements.
     (_PC_NAME_MAX is defined in  .)


     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  can  buffer  several   directory
     entries  per  actual read operation. It marks for update the
     st_atime field of the directory each time the  directory  is



SunOS 5.11          Last change: 26 Jun 2007                    2






Standard C Library Functions                          readdir(3C)



     actually read.


     The standard-conforming version (see  standards(5))  of  the
     readdir_r()  function  performs all of the actions described
     above and sets the pointer pointed to by result. If a direc-
     tory  entry is returned, the pointer will be set to the same
     value as the entry argument; otherwise, it will  be  set  to
     NULL.

RETURN VALUES
     Upon  successful  completion,  readdir()  and  the   default
     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 standard-conforming readdir_r() returns  0 if the end of
     the  directory is encountered or a directory entry is stored
     in the structure referenced by entry.  Otherwise,  an  error
     number is returned to indicate the failure.

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

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



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

     EBADF     The dirp argument does not refer to an open direc-
               tory stream.


     ENOENT    The current position of the  directory  stream  is
               invalid.


USAGE
     The readdir()  and readdir_r() functions should be  used  in
     conjunction  with  opendir(), closedir(), and rewinddir() to
     examine the contents of the directory.  Since readdir()  and
     the  default  readdir_r()  return a null pointer both at the
     end of the directory and on error, an application wanting to
     check for error situations should set errno to 0 before cal-
     ling either of these functions. If errno is set to  non-zero
     on return, an error occurred.




SunOS 5.11          Last change: 26 Jun 2007                    3






Standard C Library Functions                          readdir(3C)



     It is safe to use readdir() in a  threaded  application,  so
     long  as  only one thread reads from the directory stream at
     any given time. The readdir()  function  is  generally  pre-
     ferred over the readdir_r() function.


     The standard-conforming readdir_r() returns the error number
     if  an  error  occurred.  It returns 0 on success (including
     reaching the end of the directory stream).


     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 program will search the current  direc-
     tory for each of the arguments supplied on the command line:


       #include 
       #include 
       #include 
       #include 
       #include 

       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");



SunOS 5.11          Last change: 26 Jun 2007                    4






Standard C Library Functions                          readdir(3C)



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


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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See below.                  |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|



     The readdir() function is Unsafe. The  readdir_r()  function
     is Safe.

SEE ALSO
     fork(2),  lstat(2),  symlink(2),   Intro(3),   closedir(3C),
     opendir(3C), rewinddir(3C), scandir(3C), seekdir(3C), attri-
     butes(5), lf64(5), standards(5)

NOTES
     When compiling multithreaded programs, see the MULTITHREADED
     APPLICATIONS section of Intro(3).


     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 might not be supported in  future  releases.
     New  applications  and  libraries  should  use the standard-



SunOS 5.11          Last change: 26 Jun 2007                    5






Standard C Library Functions                          readdir(3C)



     conforming interface.


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
















































SunOS 5.11          Last change: 26 Jun 2007                    6