Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

rewinddir(3) [ultrix man page]

directory(3)						     Library Functions Manual						      directory(3)

Name
       opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations

Syntax
       #include <sys/types.h>
       #include <sys/dir.h>

       DIR *opendir(dirname)
       char *dirname;

       struct direct *readdir(dirp)
       DIR *dirp;

       long telldir(dirp)
       DIR *dirp;

       void seekdir(dirp, loc)
       DIR *dirp;
       long loc;

       void rewinddir(dirp)
       DIR *dirp;

       int closedir(dirp)
       DIR *dirp;

Description
       The library routine opens the directory named by filename and associates a directory stream with it.  A pointer is returned to identify the
       directory stream in subsequent operations.  The pointer NULL is returned if the specified filename can not be accessed, or if  insufficient
       memory is available to open the directory file.

       The  routine  returns  a  pointer  to  the next directory entry.  It returns NULL upon reaching the end of the directory or on detecting an
       invalid operation.  The routine uses the system call to read directories. Since the routine returns NULL  upon  reaching  the  end  of  the
       directory or on detecting an error, an application which wishes to detect the difference must set errno to 0 prior to calling

       The  routine  returns the current location associated with the named directory stream. Values returned by are good only for the lifetime of
       the DIR pointer from which they are derived.  If the directory is closed and then reopened, the value may be invalidated due to	undetected
       directory compaction.

       The routine sets the position of the next operation on the directory stream.  Only values returned by should be used with

       The routine resets the position of the named directory stream to the beginning of the directory.

       The routine closes the named directory stream and returns a value of 0 if successful. Otherwise, a value of -1 is returned and errno is set
       to indicate the error.  All resources associated with this directory stream are released.

Examples
       The following sample code searches a directory for the entry name.
       len = strlen(name);

       dirp = opendir(".");

       for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))

       if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {

		 closedir(dirp);

		 return FOUND;

	    }

       closedir(dirp);

       return NOT_FOUND;

Environment
       In the POSIX environment, the file descriptor returned in the DIR structure after an call will have the FD_CLOEXEC flag set.  See <fcntl.h>
       for more detail.

Return Values
       Upon  successful  completion, returns a pointer to an object of type DIR.  Otherwise, a value of NULL is returned and errno is set to indi-
       cate the error.

       The routine returns a pointer to an object of type struct dirent upon successful completion.  Otherwise, a value of NULL  is  returned  and
       errno is set to indicate the error.  When the end of the directory is encountered, a value of NULL is returned and errno is not changed.

       The routine returns the current location.  No errors are defined for and

       The routine returns zero upon successful completion.  Otherwise, a value of -1 is returned and errno is set to indicate the error.

Diagnostics
       The routine will fail if:

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

       [EINTR]	      The routine was interrupted by a signal.

       The routine will fail if:

       [EACCES]       Search permission is denied for any component of dirname or read permission is denied for dirname.

       [ENAMETOOLONG] The length of the dirname string exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.

       [ENOENT]       The dirname argument points to the name of a file which does not exist, or to an empty string and the environment defined is
		      POSIX or SYSTEM_FIVE.

       [ENOTDIR]      A component of dirname is not a directory.

       [EMFILE]       Too many file descriptors are currently open for the process.

       [ENFILE]       Too many files are currently open in the system.

       The routine will fail if:

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

See Also
       close(2), getdirentries(2), lseek(2), open(2), read(2), dir(5)

																      directory(3)
Man Page