Unix/Linux Go Back    


NetBSD 6.1.5 - man page for readdir_r (netbsd section 3)

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


DIRECTORY(3)			   BSD Library Functions Manual 		     DIRECTORY(3)

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

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <dirent.h>

     DIR *
     opendir(const char *filename);

     DIR *
     fdopendir(int fd);

     struct dirent *
     readdir(DIR *dirp);

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

     long
     telldir(DIR *dirp);

     void
     seekdir(DIR *dirp, long loc);

     void
     rewinddir(DIR *dirp);

     int
     closedir(DIR *dirp);

     int
     dirfd(DIR *dirp);

DESCRIPTION
     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.

FUNCTIONS
     The following standard directory operations are defined.

     opendir(filename)
	  The opendir() function opens the directory named by filename and associates a directory
	  stream with it.  The directory stream is positioned at the first entry.  Upon success-
	  ful completion, a pointer to DIR type is returned.  Otherwise, opendir() returns NULL.

     fdopendir(fd)
	  The fdopendir() function associates a directory stream with the directory file descrip-
	  tor 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 descriptor 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 associated description, other than by means of closedir(),
	  readdir(), readdir_r(), rewinddir(), the behavior is undefined.  The file descriptor
	  can be closed by calling closedir().

     readdir(dirp)
	  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 dirent(3).

	  The returned pointer to the dirent structure points to data which may be overwritten by
	  another call to readdir() on the same directory stream.  This data is not however over-
	  written 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 directory entries per
	  actual read operation.  Both functions mark for update the st_atime field (see stat(2))
	  of the directory each time the directory is actually read.

     telldir(dirp)
	  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() operation on the direc-
	  tory stream specified by dirp.  The value of loc should come from a previous call to
	  telldir() using the same directory 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.

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

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

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

     dirfd(dirp)
	  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.

EXAMPLES
     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)) {
				   (void)closedir(dirp);
				   return (FOUND);
			   }
		   (void)closedir(dirp);
	   }
	   return (NOT_FOUND);

COMPATIBILITY
     The described directory operations have traditionally been problematic in terms of portabil-
     ity.  A good example is the semantics around '.' (dot) and '..' (dot-dot).  Based on histor-
     ical 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() func-
	   tion 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 pro-
	   cessing the directory stream using readdir(), rewinddir(), or seekdir().  However, if
	   both the parent and child processes use these functions, the result is undefined.

ERRORS
     All described functions may set errno to indicate the error.

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

STANDARDS
     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'').

HISTORY
     The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(), and dirfd() func-
     tions appeared in 4.2BSD.	The fdopendir() function appeared in NetBSD 6.0.

BSD					 October 15, 2011				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:00 PM.