opendir(3)						     Library Functions Manual							opendir(3)

NAME

       opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir -  Performs operations on directories

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <sys/types.h> #include <dirent.h>

       DIR *opendir (	   const char *dir_name );

       struct dirent *readdir (      DIR *dir_pointer );

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

       long telldir (	   DIR *dir_pointer );

       void seekdir (	   DIR *dir_pointer,	  long location );

       void rewinddir (      DIR *dir_pointer );

       int closedir (
	       DIR *dir_pointer );

       The following function does not conform to current industry standards and is supported only for backward compatibility:

       int readdir_r (	    DIR *dir_pointer,	   struct dirent *result );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       closedir():  POSIX.1, XPG4, XPG4-UNIX

       opendir():  POSIX.1, XPG4, XPG4-UNIX

       readdir():  POSIX.1c, XPG4, XPG4-UNIX

       readdir_r():  POSIX.1c

       rewinddir():  POSIX.1, XPG4, XPG4-UNIX

       seekdir():  POSIX.1, XPG4, XPG4-UNIX

       telldir():  POSIX.1, XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Names  the  directory.	If  the final component of dir_name names a symbolic link, the link will be traversed and pathname resolution will
       continue.  Points to the dir structure of an open directory.  Points to the storage location that will hold the entry.  Specifies the  num-
       ber  of	an  entry  relative to the start of the directory.  Contains the next directory entry on return from the readdir_r() function. Set
       equal to entry upon successful completion or to NULL on error or end-of-directory.

DESCRIPTION

       The opendir() function opens the directory designated by the dir_name parameter and associates a directory stream with it.   The  directory
       stream  is positioned at the first entry.  The type DIR, which is defined in the dirent.h header file, represents a directory stream, which
       is an ordered sequence of all the directory entries in a particular directory.  If a file descriptor is used, the FD_CLOEXEC flag  will	be
       set on that file descriptor.

       The  opendir() function also returns a pointer to identify the directory stream in subsequent operations. The null pointer is returned when
       the directory named by the dir_name parameter cannot be accessed or when not enough memory is available to hold the entire stream.

       The type DIR, which is defined in the dirent.h header file, represents a directory stream, which is an ordered sequence of all  the  direc-
       tory  entries  in a particular directory.  Directory entries represent files; files may be removed from a directory or added to a directory
       asynchronously to the operation of the readdir() function.

       The readdir() function returns a pointer to a structure representing the directory entry at the current position in  the  directory  stream
       specified  by  the dir_pointer parameter, and positions the directory stream at the next entry. It returns a null pointer upon reaching the
       end of the directory stream. The dirent structure defined in the dirent.h header file 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 the readdir() function points to data which may be overwritten by another call to readdir() on the same directory
       stream.	This data will not be overwritten by another call to readdir() on a different directory stream.

       If a file is removed from or added to the directory after the most recent call to the opendir() or rewinddir() function, whether  a  subse-
       quent call to the readdir() function returns an entry for that file is unspecified.

       The readdir() function may buffer several directory entries per actual read operation; the readdir() function marks for update the st_atime
       field of the directory each time the directory is actually read.

       When it reaches the end of the directory, or when it detects an invalid seekdir() operation, the readdir() function returns the null value.

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

       The seekdir() function sets the position of the next readdir() operation on the directory stream specified by the dir_pointer parameter	to
       the position specified by the location parameter.

       If  the	value  of  the location parameter was not returned by a call to the telldir() function, or if there was an intervening call to the
       rewinddir() function on this directory stream, the effect is undefined.	The new position reverts to the one associated with the  directory
       stream when the telldir() operation was performed.

       An  attempt  to seek to an invalid location causes the readdir() function to return the null value the next time it is called. The position
       should be that returned by a previous telldir() function call.

       The rewinddir() function resets the position of the specified directory stream to the beginning of  the	directory.   It  also  causes  the
       directory stream to refer to the current state of the corresponding directory, as a call to the opendir() function would have done.  If the
       dir_pointer parameter does not refer to a directory stream, the effect is undefined.

       The closedir() function closes a directory stream and frees the structure associated with the  dir_pointer  parameter.	Upon  return,  the
       value of dir_pointer may no longer point to an accessible object of the type DIR.  If a file descriptor is used to implement type DIR, that
       file descriptor will be closed.

       [POSIX]	The readdir_r() function is the reentrant version of the readdir() function.  The readdir_r() function stores the  next  directory
       entry at entry, and returns entry in result.  On end-of-directory, NULL is stored in result and 0 (zero) is returned.

NOTES

       An open directory must always be closed with the closedir() function to ensure that the next attempt to open that directory is successful.

       The  use  of  the  seekdir()  and  telldir()  functions is not recommended in the Tru64 UNIX operating system, as the results can be unpre-
       dictable.

       [POSIX] The readdir function is not supported for multithreaded applications.  Instead, its reentrant equivalent, readdir_r, should be used
       with multiple threads.

EXAMPLES

       To  search a directory for the entry name: len = strlen(name); dir_pointer = opendir("."); for (dp = readdir(dir_pointer); dp != NULL; dp =
	    readdir(dir_pointer))
	       if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
		       closedir(dir_pointer);
		       return FOUND;
	       } closedir(dir_pointer); return NOT_FOUND;

RETURN VALUES

       Upon successful completion, the opendir() function returns a pointer to an object of type DIR.  Otherwise, null is returned and	errno  set
       to indicate the error.

       Upon  successful  completion, the readdir() function returns a pointer to an object of type struct dirent.  When an error is encountered, 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.

       Upon successful completion, the telldir() function returns the current location.  Otherwise, -1 is returned.

       Upon successful completion, the closedir() function returns 0 (zero). Otherwise, -1 is returned.

       [POSIX]	Upon successful completion or end-of-directory, the readd_r() function returns 0 (zero).  Otherwise, an error number is returned.

       [Tru64 UNIX]  Upon successful completion, the obsolete version of the readdir_r() function returns 0 (zero).  Otherwise, -1 is returned.

ERRORS

       If the opendir() function fails, errno may be set to one of the following values: Search permission is denied for any component of dir_name
       or read permission is denied for dir_name.  Too many links were encountered in translating dir_name.  The length  of  the  dir_name  string
       exceeds	PATH_MAX,  or  a  pathname  component  is longer than NAME_MAX.  The dir_name parameter points to the name of a file that does not
       exist, or the parameter points to an empty string.  A component of dir_name is not a directory.

RELATED INFORMATION

       Functions: close(2), lseek(2), open(2), read(2), scandir(3)

       Standards: standards(5) delim off

																	opendir(3)