DIRECTORY(3)            NetBSD 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 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.

     fdopendir(fd)
          The fdopendir() function associates a directory stream with the
          directory 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
          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 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
          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() 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.

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

          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.

          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.

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

          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.

          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.

          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.

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() functions appeared in 4.2BSD.  The fdopendir() function
     appeared in NetBSD 6.0.

NetBSD 7.0                     October 15, 2011                     NetBSD 7.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen