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

FreeBSD Manual Pages


home | help
DIRECTORY(3)		 BSD Library Functions Manual		  DIRECTORY(3)

     fdopendir,	opendir, readdir, readdir_r, telldir, seekdir, rewinddir,
     closedir, dirfd --	directory operations

     Standard C	Library	(libc, -lc)

     #include <dirent.h>

     DIR *
     opendir(const char	*filename);

     DIR *
     fdopendir(int fd);

     struct dirent *
     readdir(DIR *dirp);

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

     telldir(DIR *dirp);

     seekdir(DIR *dirp,	long loc);

     rewinddir(DIR *dirp);

     closedir(DIR *dirp);

     dirfd(DIR *dirp);

     The type DIR represents a directory stream; an ordered sequence of	all
     directory entries in a particular directory.  The purpose of the DIR
     structure is similar to that of the FILE structure	maintained by the
     stdio(3) library functions.

     The following standard directory operations are defined.

	  The opendir()	function opens the directory named by filename and as-
	  sociates a directory stream with it.	The directory stream is	posi-
	  tioned at the	first entry.  Upon successful completion, a pointer to
	  DIR type is returned.	 Otherwise, opendir() returns NULL.

	  The fdopendir() function associates a	directory stream with the di-
	  rectory file descriptor fd.  The file	offset associated with fd at
	  the time of the call determines which	entries	are returned.

	  Upon failure,	fdopendir() returns NULL.  Otherwise the file descrip-
	  tor is under the control of the system, and if any attempt is	made
	  to close the file descriptor,	or to modify the state of the associ-
	  ated description, other than by means	of closedir(), readdir(),
	  readdir_r(), rewinddir(), the	behavior is undefined.	The file de-
	  scriptor can be closed by calling closedir().

	  The readdir()	function returns a pointer to the directory entry at
	  the current position in the directory	stream specified by dirp, and
	  positions the	directory stream at the	next entry.  It	returns	NULL
	  upon reaching	the end	of the directory or detecting an invalid
	  seekdir() operation.	The returned structure is described in

	  The returned pointer to the dirent structure points to data which
	  may be overwritten by	another	call to	readdir() on the same direc-
	  tory stream.	This data is not however overwritten by	another	call
	  to readdir() on a different directory	stream.

     readdir_r(dirp, entry, result)
	  The readdir_r() function provides the	same functionality as
	  readdir(), but the caller must provide a directory entry buffer to
	  store	the results in.	 If the	read succeeds, result is pointed at
	  the entry; upon reaching the end of the directory result is set to
	  NULL.	 The readdir_r() function returns 0 on success or an error
	  number to indicate failure.

	  Like readdir(), the readdir_r() function may buffer several direc-
	  tory entries per actual read operation.  Both	functions mark for up-
	  date the st_atime field (see stat(2))	of the directory each time the
	  directory is actually	read.

	  The telldir()	function returns the current location associated with
	  the directory	stream specified by dirp.

	  If the most recent operation on the particular directory stream was
	  a seekdir(), the directory position returned from telldir() is the
	  same as loc supplied as an argument to the seekdir() call.

     seekdir(dirp, loc)
	  The seekdir()	function sets the position of the next readdir() oper-
	  ation	on the directory stream	specified by dirp.  The	value of loc
	  should come from a previous call to telldir()	using the same direc-
	  tory stream.

	  The new position reverts to the one associated with the directory
	  stream when the telldir() operation was performed.  Values returned
	  by telldir() are good	only for the lifetime of the DIR pointer,
	  dirp,	from which they	are derived.  If the directory is closed and
	  then reopened, the telldir() value cannot be re-used.

	  The rewinddir() function resets the position of the named directory
	  stream to the	beginning of the directory.  It	also causes the	direc-
	  tory stream to refer to the current state of the corresponding di-
	  rectory, as if a call	to opendir() would have	been made.

	  If dirp does not refer to a valid directory stream, the behavior is

	  The closedir() function closes the directory stream and frees	the
	  structure associated with the	dirp pointer, returning	0 on success
	  and -1 on failure.

	  The dirfd() function returns the integer file	descriptor associated
	  with the directory stream specified by dirp.	Upon failure, dirfd()
	  returns -1.  The returned file descriptor should be closed by
	  closedir() instead of	close(2).

	  The rationale	of dirfd() is to provide a mechanism by	which a	file
	  descriptor can be obtained for the use of the	fchdir(2) function.

     Sample code which searches	a directory for	entry "name" is:

	   len = strlen(name);
	   dirp	= opendir(".");
	   if (dirp != NULL) {
		   while ((dp =	readdir(dirp)) != NULL)
			   if (dp->d_namlen == len &&
			       !strcmp(dp->d_name, name)) {
				   return (FOUND);
	   return (NOT_FOUND);

     The described directory operations	have traditionally been	problematic in
     terms of portability.  A good example is the semantics around `.' (dot)
     and `..' (dot-dot).  Based	on historical implementations, the rules about
     file descriptors apply to directory streams as well.  The IEEE Std
     1003.1-2008 ("POSIX.1") standard does not however any more	mandate	that
     directory streams are necessarily implemented by using file descriptors.

     The following additional remarks can be noted from	the IEEE Std
     1003.1-2008 ("POSIX.1") standard.

       +o   If the type DIR is implemented using	a file descriptor, like	in
	   NetBSD, applications	should be able to open only OPEN_MAX files and
	   directories.	 Otherwise the limit is	left as	unspecified.

       +o   When	a file descriptor is used to implement the directory stream,
	   the closedir() function behaves as if the FD_CLOEXEC	had been set
	   for the file	descriptor.  In	another	words, it is mandatory that
	   closedir() deallocates the file descriptor.

       +o   If directory	streams	are not	implemented by using file descriptors,
	   functions such as dirfd() may fail with ENOTSUP.

       +o   If a	file is	removed	from or	added to the directory after the most
	   recent call to opendir() or rewinddir(), it is unspecified whether
	   a subsequent	call to	readdir() returns an entry for that file.

       +o   When	using the function seekdir(), note that	if the value of	loc
	   was not obtained from an earlier call to telldir(), or if a call to
	   rewinddir() occurred	between	the calls to telldir() and seekdir(),
	   any subsequent call to readdir() is unspecified, possibly resulting
	   undefined behavior.

       +o   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().  However,	if both	the parent and child
	   processes use these functions, the result is	undefined.

     All described functions may set errno to indicate the error.

     close(2), lseek(2), open(2), read(2), dirent(3)

     The opendir(), readdir(), rewinddir() and closedir() functions conform to
     ISO/IEC 9945-1:1990 ("POSIX.1").  The other functions conform to IEEE Std
     1003.1-2008 ("POSIX.1").

     The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(),
     and dirfd() functions appeared in 4.2BSD.	The fdopendir()	function ap-
     peared in NetBSD 6.0.

BSD			       October 15, 2011				   BSD


Want to link to this manual page? Use this URL:

home | help