Unix/Linux Go Back    


Linux 2.6 - man page for readdir (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


READDIR(P)			    POSIX Programmer's Manual			       READDIR(P)

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 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 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() 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 st_atime field of the directory each time the direc-
       tory 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.

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

       The readdir() function need not be reentrant. A function that is not required to be  reen-
       trant is not required to be thread-safe.

       The readdir_r() function shall initialize the dirent structure referenced by entry to rep-
       resent 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;
       the readdir_r() function shall mark for update the st_atime field of  the  directory  each
       time the directory is actually read.

       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.

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
       The readdir() function shall fail if:

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

       The readdir() function 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 readdir_r() function may fail if:

       EBADF  The dirp argument does not refer to an open directory stream.

       The following sections are informative.

EXAMPLES
       The following sample program searches the current directory for each of the arguments sup-
       plied 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(arvg[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  st_atime  field  for update would disallow such historical performance-oriented
       implementations.

       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-sup-
       plied 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() , lstat() , opendir() , rewinddir() , symlink() , the Base  Definitions  volume
       of IEEE Std 1003.1-2001, <dirent.h>, <sys/types.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       READDIR(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:51 AM.