Description

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

   The type DIR defined in the <dirent.h> header file represents a
   directory stream. A directory stream is an ordered sequence of
   all the directory entries in a particular directory. Directory
   entries represent files. You can remove files from or add files
   to a directory asynchronously to the operation of the readdir
   function.

   The pointer returned by the readdir function points to data
   that you can overwrite 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 the opendir or rewinddir function, a
   subsequent call to the readdir function might not return an entry
   for that file.

   When it reaches the end of the directory, or when it detects an
   invalid seekdir operation, the readdir function returns the null
   value.

   An attempt to seek to an invalid location causes the readdir
   function to return the null value the next time it is called. A
   previous telldir function call returns the position.

   The readdir_r function is a reentrant version of readdir. In
   addition to dir_pointer, you must specify a pointer to a dirent
   structure in which the current directory entry of the specified
   stream is returned.

   If the operation is successful, readdir_r returns 0 and stores
   one of the following two pointers in result:

   o  Pointer to entry if the entry was found

   o  NULL pointer if the end of the directory stream was reached

   The storage pointed to by entry must be large enough for a dirent
   with an array of char d_name member containing at least NAME_MAX
   + 1 elements.

   If an error occurred, an error value is returned that indicates
   the cause of the error.

   Applications wishing to check for error situations should set
   errno to 0 before calling readdir. If errno is set to nonzero on
   return, then an error occurred.