Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
readdir(3C)		 Standard C Library Functions		   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);

   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 <dirent.h>,	 represents  a
       directory stream, which is an ordered sequence of all the directory en-
       tries in	a particular directory.	 Directory  entries  represent	files;
       files  may  be  removed	from a directory or added to a directory asyn-
       chronously 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.

       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	which may be overwrit-
       ten  by	another	 call  to readdir() on the same	directory stream. This
       data is not overwritten by another call to readdir() on a different di-
       rectory stream.

       If  a file is removed from or added to the directory after the most re-
       cent 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 func-
       tions, the result is undefined.

       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 oc-
       curred, the readdir_r() function	initializes the	dirent structure  ref-
       erenced	by entry to represent the directory entry at the current posi-
       tion 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  <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  re-
       cent  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  ac-
       tual  read  operation;  the  readdir_r()	 function marks	for update the
       st_atime	field of the directory each time  the  directory  is  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 directory	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() re-
       turn a pointer to an object of type struct dirent. When an error	is en-
       countered,  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	direc-
       tory 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  can-
		       not be represented correctly.

       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  in-
		       valid.

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 applica-
       tion wanting to check for error situations should set errno to 0	before
       calling either of these functions. If errno is set to non-zero  on  re-
       turn, an	error occurred.

       The  standard-conforming	readdir_r() returns the	error number if	an er-
       ror 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 directory for each
       of the arguments	supplied on the	command	line:

       #include	<sys/types.h>
       #include	<dirent.h>
       #include	<errno.h>
       #include	<stdio.h>
       #include	<strings.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);
       }

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |readdir()	 is Unsafe; read-  |
       |			     |dir_r() is Safe.		   |
       +-----------------------------+-----------------------------+

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

NOTES
       When  compiling	multithreaded  programs, see Intro(3), Notes On	Multi-
       threaded	Applications.

       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 pro-
       vided  for  compatibility  only	and may	not be supported in future re-
       leases.	New applications and libraries should  use  the	 standard-con-
       forming interface.

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

SunOS 5.10			  21 Jul 2004			   readdir(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=readdir&sektion=3c&manpath=SunOS+5.10>

home | help